raptor-aios 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -3,11 +3,36 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.6.3] - 2026-06-06
+
+### Fixed
+
+- **`raptor new --jira=<KEY>` no longer creates an empty, mislabelled spec when the Jira card can't be read.** Previously, when a ticket was given but Jira was not connected (or the token had expired, or the issue was unreachable), `new` warned and then degraded to seeding a spec stamped with the Jira ID but **no card content** — and created the branch too. Now, when a fetch was expected (the default), an unreadable card is a **hard stop**: `new` aborts **before any side effect** (no spec, no directory, no branch) with an actionable message that states the reason and points to `raptor jira connect` (or configuring the Jira MCP server). The intentional offline path is unchanged — pass `--no-jira-fetch` to record the ticket ID only.
+
+### Internal
+
+- `New.fetchJiraContext` now returns a discriminated result (`{ ok, context }` | `{ ok: false, reason }`) so the caller can abort with the specific failure reason instead of silently degrading. Removed the now-unreachable `"id only (fetch unavailable)"` status tag.
+
+## [0.6.2] - 2026-06-06
+
+### Changed
+
+- **`raptor upgrade` is now a real, non-destructive project sync.** Previously it only bumped `raptor_version` as a side effect of a manifest schema-version change, so a same-schema release (e.g. 0.5.0 → 0.6.x) left the project stamped at the old version and brought none of the framework updates. Now `raptor upgrade`:
+  - **Re-stamps the version unconditionally** in `raptor.manifest.json` and, surgically (single `version:` line), in `.raptor/raptor.yml` — preserving the user's `mcp`/`git`/`jira` sections **and comments** byte-for-byte (no template re-render).
+  - **Refreshes every framework-owned file** to the installed version — shell scripts, command templates, the rich slash commands (`specify`/`plan`/`tasks`/… now carry the design-gate instructions), and bundled extensions — **backing each up to `.raptor/backup/<timestamp>/` before overwriting**, and skipping files that are already current (idempotent).
+  - **Upgrades the constitution CORE block in place** when outdated (reusing the `repair constitution` mechanism): preserves preset (M*) and project (P*) articles, logs `constitution.upgraded`, and keeps `gate.constitution.integrity` / `gate.amendment.core` green. Requires a human approver (C5, `git user.email`); skips with a warning when absent or when the CORE was hand-edited (run `raptor repair constitution` first).
+  - **Never touches user-owned content**: `init-options.json`, `.raptor/specs/`, `.raptor/memory/*`, `.raptor/templates/overrides/`, custom extensions, and an existing `agents.yml` are left as-is. `--dry-run` previews the full change list and writes nothing.
+
+### Internal
+
+- Extracted the framework-install routines (`installShellScripts`, `installTemplates`, `installBundledExtensions`, `collectFrameworkFiles`) into `packages/cli/src/shared/scaffold.ts`, shared by `init` and `upgrade` so an upgraded project matches a freshly-init'd one. Split the slash-command materializer into a pure `planSlashCommands` (used by upgrade's diff) plus the writing `materializeSlashCommands`.
+
 ## [0.6.1] - 2026-06-05
 
 ### Changed
 
-- Package `author` set to **Lucas Pedro <lucaspedrolbg@gmail.com> (https://github.com/lucaspedronet)** on the publishable package and the workspace `package.json` files (previously the bare npm handle). Metadata-only; no code changes.
+- Package `author` set to **Lucas Pedro <lucaspedrolbg@gmail.com> (https://github.com/lucaspedronet)** on the publishable package and the workspace `package.json` files (previously the bare npm handle).
+- **Slimmer published package.** The tarball no longer ships `.d.ts` type declarations, `.d.ts.map`/`.js.map` source maps, or `sourceMappingURL` pragmas, and the emitted `.js` is built with `removeComments` — removing the most readable/structured slice of the code (the typed API surface and the JSDoc rationale) and roughly halving the tarball. Runtime behaviour is unchanged. (Note: a public npm package can never truly hide code; this only reduces casual exposure.)
 
 ## [0.6.0] - 2026-06-05
 

package/dist/_core/dist/agents/index.js

@@ -15,4 +15,4 @@ export { validateHandoff, nextPhase, isTerminalPhase } from "./handoff.js";
 export { waitForArtifact, snapshotMtime, snapshotDir, resolveArtifactPath, watchTargetOf, relPath, ArtifactWaitTimeoutError, ArtifactWaitAbortedError, } from "./artifact-watcher.js";
 export { backupIfExists, createBackupSession, backupTimestamp, DEFAULT_BACKUP_SUBDIR, } from "./backup.js";
 export { MARKERS, wrapSpec, wrapUntrusted, sanitizeUntrusted, assertNoMarkers, extractSpec, extractUntrusted, hasSpecMarkers, } from "./prompt-markers.js";
-export { materializeSlashCommands, renderRichCommand, locateRichCommandsDir, } from "./slash-materializer.js";
+export { materializeSlashCommands, planSlashCommands, renderRichCommand, locateRichCommandsDir, } from "./slash-materializer.js";

package/dist/_core/dist/agents/slash-materializer.js

@@ -37,10 +37,9 @@ export function renderRichCommand(raw, opts) {
     c = c.replace(/\brpt\.([a-z-]+)/g, "raptor-$1");
     return c;
 }
-export function materializeSlashCommands(opts) {
+export function planSlashCommands(opts) {
     const { projectRoot, adapter, constitutionArticles } = opts;
     const commandDir = join(projectRoot, adapter.commandDir);
-    mkdirSync(commandDir, { recursive: true });
     const richDir = locateRichCommandsDir(projectRoot);
     const commands = richDir
         ? readdirSync(richDir)
@@ -48,7 +47,7 @@ export function materializeSlashCommands(opts) {
             .map((f) => f.replace(/\.md$/, ""))
             .sort()
         : knownCommands();
-    const materialized = [];
+    const planned = [];
     for (const command of commands) {
         let content;
         const richPath = richDir ? join(richDir, `${command}.md`) : null;
@@ -68,16 +67,23 @@ export function materializeSlashCommands(opts) {
             content = adapter.packPrompt(canonical);
         }
         const fileName = adapter.commandFileName(command);
-        const filePath = join(commandDir, fileName);
-        writeFileSync(filePath, content);
-        materialized.push({
+        planned.push({
             command,
-            path: filePath,
+            path: join(commandDir, fileName),
+            content,
             hash: hashString(content),
         });
     }
-    return {
-        agentId: adapter.id,
-        commands: materialized,
-    };
+    return { agentId: adapter.id, commands: planned };
+}
+export function materializeSlashCommands(opts) {
+    const plan = planSlashCommands(opts);
+    const commandDir = join(opts.projectRoot, opts.adapter.commandDir);
+    mkdirSync(commandDir, { recursive: true });
+    const materialized = [];
+    for (const c of plan.commands) {
+        writeFileSync(c.path, c.content);
+        materialized.push({ command: c.command, path: c.path, hash: c.hash });
+    }
+    return { agentId: plan.agentId, commands: materialized };
 }

package/dist/_core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raptor/core",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "main": "dist/index.js"
 }

package/dist/commands/init.js

@@ -1,9 +1,10 @@
 import { Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, writeFileSync, } from "node:fs";
+import { basename, join } from "node:path";
 import { appendAuditEvent, buildContextBlock, coreBlock, CORE_VERSION, createManifest, detectInstalledAgents, generateAgentsYaml, getAgentByKind, getPreset, hashString, knownPresetIds, materializeSlashCommands, renderBundled, renderPresetArticles, SELECTABLE_AGENT_KEYS, upsertContextFile, VERSION, } from "../_core/dist/index.js";
 import { currentActor } from "../shared/project.js";
+import { installBundledExtensions, installShellScripts, installTemplates, } from "../shared/scaffold.js";
 export default class Init extends BaseCommand {
     static description = "Initialize a Raptor project in the current directory";
     static examples = [
@@ -126,9 +127,9 @@ export default class Init extends BaseCommand {
         writeFileSync(join(raptorDir, "memory", "decisions.md"), "# Architecture Decision Records\n\n");
         writeFileSync(join(raptorDir, "memory", "glossary.md"), "# Project Glossary\n\n");
         writeFileSync(join(raptorDir, ".gitignore"), "cache/\n*.log\n");
-        this.copyShellScripts(cwd, raptorDir, manifest);
-        this.copyTemplates(raptorDir);
-        this.installBundledExtensions(raptorDir, manifest);
+        installShellScripts(this, raptorDir, manifest);
+        installTemplates(raptorDir);
+        installBundledExtensions(this, raptorDir, manifest);
         const installedAgents = detectInstalledAgents();
         const primaryAgent = getAgentByKind(flags.ai);
         if (primaryAgent && !installedAgents.some((a) => a.id === primaryAgent.id)) {
@@ -273,101 +274,6 @@ export default class Init extends BaseCommand {
         }
         return { status: "ok", installed, skipped };
     }
-    copyShellScripts(_cwd, raptorDir, manifest) {
-        const pkgRoot = this.findRaptorPackageRoot();
-        if (!pkgRoot) {
-            this.warn("Could not locate Raptor package root — shell scripts not copied.");
-            return;
-        }
-        const copied = [];
-        const summary = [];
-        const shells = [
-            { dir: "bash", ext: ".sh" },
-            { dir: "powershell", ext: ".ps1" },
-        ];
-        for (const shell of shells) {
-            const sourceDir = join(pkgRoot, "scripts", shell.dir);
-            const targetDir = join(raptorDir, "scripts", shell.dir);
-            if (!existsSync(sourceDir))
-                continue;
-            mkdirSync(targetDir, { recursive: true });
-            const files = readdirSync(sourceDir).filter((f) => f.endsWith(shell.ext));
-            for (const file of files) {
-                const src = join(sourceDir, file);
-                const dest = join(targetDir, file);
-                copyFileSync(src, dest);
-                if (shell.ext === ".sh")
-                    chmodSync(dest, 0o755);
-                copied.push(`scripts/${shell.dir}/${file}`);
-            }
-            if (files.length > 0) {
-                summary.push(`${files.length} ${shell.dir}`);
-            }
-        }
-        manifest.scripts_installed = copied;
-        writeFileSync(join(raptorDir, "raptor.manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
-        if (summary.length > 0) {
-            this.log(`  Scripts:  ${summary.join(", ")}`);
-        }
-    }
-    copyTemplates(raptorDir) {
-        const pkgRoot = this.findRaptorPackageRoot();
-        if (!pkgRoot)
-            return;
-        const srcTemplates = join(pkgRoot, "templates");
-        if (!existsSync(srcTemplates))
-            return;
-        const srcCommands = join(srcTemplates, "commands");
-        if (existsSync(srcCommands)) {
-            const destCommands = join(raptorDir, "templates", "commands");
-            mkdirSync(destCommands, { recursive: true });
-            for (const f of readdirSync(srcCommands).filter((f) => f.endsWith(".md"))) {
-                copyFileSync(join(srcCommands, f), join(destCommands, f));
-            }
-        }
-        const destTemplates = join(raptorDir, "templates");
-        mkdirSync(destTemplates, { recursive: true });
-        for (const f of readdirSync(srcTemplates).filter((f) => f.endsWith("-template.md"))) {
-            copyFileSync(join(srcTemplates, f), join(destTemplates, f));
-        }
-    }
-    installBundledExtensions(raptorDir, manifest) {
-        const pkgRoot = this.findRaptorPackageRoot();
-        if (!pkgRoot)
-            return;
-        const sourceExtRoot = join(pkgRoot, "extensions");
-        if (!existsSync(sourceExtRoot))
-            return;
-        const registered = [];
-        for (const extId of readdirSync(sourceExtRoot)) {
-            const sourceExt = join(sourceExtRoot, extId);
-            const manifestFile = join(sourceExt, "extension.yml");
-            if (!existsSync(manifestFile))
-                continue;
-            const targetExt = join(raptorDir, "extensions", extId);
-            copyDirRecursive(sourceExt, targetExt);
-            registered.push(extId);
-        }
-        if (registered.length === 0)
-            return;
-        manifest.extensions_registered = registered;
-        writeFileSync(join(raptorDir, "raptor.manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
-        this.log(`  Ext:      ${registered.length} bundled (${registered.join(", ")})`);
-    }
-    findRaptorPackageRoot() {
-        let dir = dirname(new URL(import.meta.url).pathname);
-        for (let i = 0; i < 10; i++) {
-            if (existsSync(join(dir, "pnpm-workspace.yaml")) ||
-                existsSync(join(dir, "scripts", "bash"))) {
-                return dir;
-            }
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-        return null;
-    }
 }
 function describeCi(r) {
     if (r.status === "disabled")
@@ -388,16 +294,3 @@ function describeHooks(r) {
         parts.push(`skipped (already exist): ${r.skipped.join(", ")}`);
     return parts.length > 0 ? parts.join("; ") : "nothing to do";
 }
-function copyDirRecursive(source, target) {
-    mkdirSync(target, { recursive: true });
-    for (const entry of readdirSync(source)) {
-        const src = join(source, entry);
-        const dest = join(target, entry);
-        if (statSync(src).isDirectory()) {
-            copyDirRecursive(src, dest);
-        }
-        else {
-            copyFileSync(src, dest);
-        }
-    }
-}

package/dist/commands/new.js

@@ -113,7 +113,26 @@ export default class New extends BaseCommand {
         const specNeedsSeeding = !existsSync(specPath);
         let jiraContext = null;
         if (specNeedsSeeding && flags.jira && flags["jira-fetch"]) {
-            jiraContext = await this.fetchJiraContext(root, flags.jira);
+            const result = await this.fetchJiraContext(root, flags.jira);
+            if (result.ok) {
+                jiraContext = result.context;
+            }
+            else {
+                this.error([
+                    `${result.reason}`,
+                    ``,
+                    `Aborting: --jira=${flags.jira} was given but its Jira card could not be read,`,
+                    `so there is no card content to seed the spec from. No spec or branch was`,
+                    `created — a spec stamped with a Jira ID but no Jira content would be misleading.`,
+                    ``,
+                    `To fix, do one of:`,
+                    `  • Connect Jira, then retry:`,
+                    `      raptor jira connect`,
+                    `      (or configure the Jira MCP server under 'jira:' in .raptor/raptor.yml)`,
+                    `  • Record the ticket ID only, without fetching the card:`,
+                    `      raptor new ${args.slug} --jira=${flags.jira} --no-jira-fetch`,
+                ].join("\n"), { exit: 1 });
+            }
         }
         const designText = specNeedsSeeding
             ? [
@@ -271,9 +290,7 @@ export default class New extends BaseCommand {
                 ? "seeded spec"
                 : !specNeedsSeeding
                     ? "id recorded — spec already authored, not re-seeded"
-                    : flags["jira-fetch"]
-                        ? "id only (fetch unavailable)"
-                        : "id only";
+                    : "id only";
             this.log(`  Jira:      ${flags.jira} (${tag})`);
         }
         if (designContext.hasDesign) {
@@ -416,28 +433,27 @@ export default class New extends BaseCommand {
     async fetchJiraContext(root, key) {
         const conn = jiraConn(readConfig(root));
         if (!conn) {
-            this.warn(`--jira=${key} given but Jira is not connected — recording the ID only. Run 'raptor jira connect' to seed specs.`);
-            return null;
+            return { ok: false, reason: `Jira is not connected.` };
         }
         if (!jiraReadyNonInteractive(conn)) {
-            this.warn(`Jira tokens missing — run 'raptor jira connect'. Recording ID only.`);
-            return null;
+            return { ok: false, reason: `Jira credentials are missing.` };
         }
         let client;
         try {
             client = await openJiraClient(conn);
         }
         catch {
-            this.warn(`Jira session expired — run 'raptor jira connect'. Recording ID only.`);
-            return null;
+            return { ok: false, reason: `Jira session expired.` };
         }
         try {
             const issue = await client.getJiraIssue(conn.cloudId, key);
-            return mapIssueToSpecContext(issue);
+            return { ok: true, context: mapIssueToSpecContext(issue) };
         }
         catch (err) {
-            this.warn(`Could not fetch ${key} (${err instanceof Error ? err.message : String(err)}) — recording ID only.`);
-            return null;
+            return {
+                ok: false,
+                reason: `Could not fetch ${key} from Jira (${err instanceof Error ? err.message : String(err)}).`,
+            };
         }
         finally {
             await client.close();

package/dist/commands/upgrade.js

@@ -1,143 +1,292 @@
 import { Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { MANIFEST_SCHEMA_VERSION, validateManifest, VERSION, } from "../_core/dist/index.js";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { appendAuditEvent, buildContextBlock, coreHash, CORE_VERSION, createBackupSession, createManifest, detectInstalledAgents, extractCoreBlock, generateAgentsYaml, getAgentByKind, getPreset, hashString, loadAgentsConfig, MANIFEST_SCHEMA_VERSION, planSlashCommands, rewriteCoreBlock, upsertContextFile, validateManifest, VERSION, } from "../_core/dist/index.js";
+import { collectFrameworkFiles, installBundledExtensions, installShellScripts, installTemplates, } from "../shared/scaffold.js";
+import { currentActor, readInitOptions, restampYmlVersion, } from "../shared/project.js";
 export default class Upgrade extends BaseCommand {
-    static description = "Migrate Raptor configuration to the latest version";
+    static description = "Sync the project to the installed Raptor version (non-destructive)";
     static examples = [
         "<%= config.bin %> upgrade",
         "<%= config.bin %> upgrade --dry-run",
     ];
     static flags = {
         "dry-run": Flags.boolean({
-            description: "Show what would be changed without applying",
+            description: "Show what would change without writing anything",
             default: false,
         }),
     };
     async run() {
         const { flags } = await this.parse(Upgrade);
-        const cwd = process.cwd();
-        const raptorDir = join(cwd, ".raptor");
+        const dry = flags["dry-run"];
+        const root = process.cwd();
+        const raptorDir = join(root, ".raptor");
         if (!existsSync(raptorDir)) {
             this.error("No .raptor/ directory found. Run 'raptor init' first.");
         }
-        const manifestPath = join(raptorDir, "raptor.manifest.json");
-        const raptorYmlPath = join(raptorDir, "raptor.yml");
         const changes = [];
+        const skipped = [];
+        const session = dry ? null : createBackupSession(root);
+        const backup = (abs) => {
+            session?.backup(abs);
+        };
+        const hashOf = (p) => existsSync(p) ? hashString(readFileSync(p, "utf8")) : "";
+        const manifestPath = join(raptorDir, "raptor.manifest.json");
+        const ymlPath = join(raptorDir, "raptor.yml");
+        const initOpts = readInitOptions(root);
+        let manifest;
         if (!existsSync(manifestPath)) {
-            this.log("📦 raptor.manifest.json not found — creating from scratch.");
             let projectName = "unknown";
-            let preset = "mobile-opinionated";
-            if (existsSync(raptorYmlPath)) {
-                try {
-                    const yml = readFileSync(raptorYmlPath, "utf-8");
-                    const nameMatch = yml.match(/project_name:\s*["']?([^"'\n]+)/);
-                    const presetMatch = yml.match(/preset:\s*["']?([^"'\n]+)/);
-                    if (nameMatch)
-                        projectName = nameMatch[1].trim();
-                    if (presetMatch)
-                        preset = presetMatch[1].trim();
-                }
-                catch {
-                }
+            if (existsSync(ymlPath)) {
+                const m = readFileSync(ymlPath, "utf8").match(/name:\s*["']?([^"'\n]+)/);
+                if (m)
+                    projectName = m[1].trim();
             }
-            const manifest = {
-                schema_version: MANIFEST_SCHEMA_VERSION,
+            manifest = createManifest({
                 raptor_version: VERSION,
                 project_name: projectName,
-                integration: "claude-code",
+                integration: initOpts?.ai ?? "claude-code",
                 script_type: "sh",
-                branch_numbering: "sequential",
-                preset,
+                branch_numbering: initOpts?.branch_numbering ?? "sequential",
+                preset: initOpts?.preset ?? "mobile-opinionated",
                 scripts_installed: [],
                 templates_installed: [],
                 extensions_registered: [],
-                created_at: new Date().toISOString(),
-            };
+            });
             changes.push("CREATE raptor.manifest.json (migrated from raptor.yml)");
-            if (!flags["dry-run"]) {
-                writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
-            }
         }
         else {
-            try {
-                const raw = JSON.parse(readFileSync(manifestPath, "utf-8"));
-                const result = validateManifest(raw);
-                if (!result.valid) {
-                    this.warn("Manifest validation errors:");
-                    for (const err of result.errors) {
-                        this.warn(`  - ${err}`);
-                    }
-                    changes.push("FIX manifest validation errors");
+            manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            const result = validateManifest(manifest);
+            if (!result.valid) {
+                for (const err of result.errors)
+                    this.warn(`manifest: ${err}`);
+            }
+        }
+        if (manifest.raptor_version !== VERSION) {
+            changes.push(`STAMP raptor_version: ${manifest.raptor_version} → ${VERSION}`);
+        }
+        if (manifest.schema_version !== MANIFEST_SCHEMA_VERSION) {
+            changes.push(`BUMP schema_version: ${manifest.schema_version} → ${MANIFEST_SCHEMA_VERSION}`);
+        }
+        manifest.raptor_version = VERSION;
+        manifest.schema_version = MANIFEST_SCHEMA_VERSION;
+        const projectName = typeof manifest.project_name === "string"
+            ? manifest.project_name
+            : "project";
+        const presetId = typeof manifest.preset === "string" ? manifest.preset : undefined;
+        if (existsSync(ymlPath)) {
+            const raw = readFileSync(ymlPath, "utf8");
+            let next = restampYmlVersion(raw, VERSION);
+            next = next.replace(/\nagents:\s*\[\]\n(?:#[^\n]*\n)*/, "\n# Agent configuration lives in agents.yml — run 'raptor add-agent <key>'.\n");
+            if (next !== raw) {
+                changes.push("UPDATE raptor.yml (version + legacy cleanup)");
+                if (!dry) {
+                    backup(ymlPath);
+                    writeFileSync(ymlPath, next);
                 }
-                if (raw.schema_version !== MANIFEST_SCHEMA_VERSION) {
-                    changes.push(`BUMP schema_version: ${raw.schema_version} → ${MANIFEST_SCHEMA_VERSION}`);
-                    if (!flags["dry-run"]) {
-                        raw.schema_version = MANIFEST_SCHEMA_VERSION;
-                        raw.raptor_version = VERSION;
-                        raw.updated_at = new Date().toISOString();
-                        writeFileSync(manifestPath, JSON.stringify(raw, null, 2) + "\n");
-                    }
+            }
+        }
+        const fw = collectFrameworkFiles(raptorDir);
+        const changedFw = fw.filter((f) => !existsSync(f.dest) || hashOf(f.src) !== hashOf(f.dest));
+        if (changedFw.length > 0) {
+            changes.push(`REFRESH ${changedFw.length} framework file(s)`);
+            if (!dry) {
+                for (const f of changedFw)
+                    backup(f.dest);
+                installShellScripts(this, raptorDir, manifest);
+                installTemplates(raptorDir);
+                installBundledExtensions(this, raptorDir, manifest);
+            }
+        }
+        const agents = this.resolveAgents(root, initOpts?.ai);
+        const presetArticles = presetId
+            ? getPreset(presetId)?.articles.map((a) => a.id)
+            : undefined;
+        let slashChanged = 0;
+        let ctxChanged = 0;
+        for (const adapter of agents) {
+            if (adapter.id === "human")
+                continue;
+            const plan = planSlashCommands({
+                projectRoot: root,
+                projectName,
+                adapter,
+                ...(presetArticles ? { constitutionArticles: presetArticles } : {}),
+                ...(presetId ? { presetId } : {}),
+            });
+            for (const c of plan.commands) {
+                if (existsSync(c.path) && hashOf(c.path) === c.hash)
+                    continue;
+                slashChanged++;
+                if (!dry) {
+                    backup(c.path);
+                    mkdirSync(dirname(c.path), { recursive: true });
+                    writeFileSync(c.path, c.content);
                 }
             }
-            catch (err) {
-                this.error(`Failed to parse ${manifestPath}: ${err instanceof Error ? err.message : String(err)}`);
+            if (adapter.contextFile) {
+                const ctxPath = join(root, adapter.contextFile);
+                const before = existsSync(ctxPath) ? readFileSync(ctxPath, "utf8") : "";
+                const block = buildContextBlock({
+                    projectName,
+                    ...(presetId ? { preset: presetId } : {}),
+                    ...(presetArticles ? { constitutionArticles: presetArticles } : {}),
+                });
+                if (!before.includes(block)) {
+                    ctxChanged++;
+                    if (!dry)
+                        upsertContextFile(ctxPath, block);
+                }
             }
         }
-        const constitutionMemory = join(raptorDir, "memory", "constitution.md");
-        const constitutionRoot = join(raptorDir, "constitution.md");
-        if (!existsSync(constitutionMemory) && existsSync(constitutionRoot)) {
-            changes.push("COPY constitution.md → memory/constitution.md (E02 upgrade)");
-            if (!flags["dry-run"]) {
-                const content = readFileSync(constitutionRoot, "utf-8");
-                writeFileSync(constitutionMemory, content);
+        if (slashChanged > 0) {
+            changes.push(`REFRESH ${slashChanged} slash command file(s)`);
+        }
+        if (ctxChanged > 0) {
+            changes.push(`SYNC ${ctxChanged} agent context file(s)`);
+        }
+        const constPath = join(raptorDir, "constitution.md");
+        if (existsSync(constPath)) {
+            const src = readFileSync(constPath, "utf8");
+            const ex = extractCoreBlock(src);
+            if (ex?.isCanonical) {
+            }
+            else if (ex && !ex.isIntact) {
+                this.warn("Constitution CORE block was hand-edited (hash mismatch) — skipping. Run 'raptor repair constitution --confirm' first.");
+                skipped.push("constitution CORE (tampered)");
+            }
+            else {
+                const actor = currentActor("human");
+                if (!actor.email) {
+                    this.warn("Constitution CORE is outdated but no `git config user.email` is set (C5) — skipping. Set it and re-run to upgrade the CORE.");
+                    skipped.push("constitution CORE (no C5 approver)");
+                }
+                else {
+                    changes.push(`UPGRADE constitution CORE → v${CORE_VERSION}`);
+                    if (!dry) {
+                        const memPath = join(raptorDir, "memory", "constitution.md");
+                        backup(constPath);
+                        if (existsSync(memPath))
+                            backup(memPath);
+                        const prevHash = hashString(src);
+                        const next = rewriteCoreBlock(src);
+                        writeFileSync(constPath, next);
+                        mkdirSync(dirname(memPath), { recursive: true });
+                        writeFileSync(memPath, next);
+                        appendAuditEvent(join(raptorDir, "memory", "amendments.log"), {
+                            event: "constitution.upgraded",
+                            command: "raptor upgrade",
+                            actor: { user: actor.user, via: actor.via },
+                            article: "C4",
+                            inputs: [
+                                {
+                                    path: ".raptor/constitution.md",
+                                    hash: prevHash,
+                                    role: "constitution",
+                                },
+                            ],
+                            outputs: [
+                                {
+                                    path: ".raptor/constitution.md",
+                                    hash: hashString(next),
+                                    role: "constitution",
+                                },
+                            ],
+                            meta: {
+                                previous_version: ex?.version ?? null,
+                                new_version: CORE_VERSION,
+                                new_block_hash: coreHash(),
+                            },
+                        });
+                    }
+                }
             }
         }
         const initOptionsPath = join(raptorDir, "init-options.json");
         if (!existsSync(initOptionsPath)) {
-            changes.push("CREATE init-options.json (E06 upgrade)");
-            if (!flags["dry-run"]) {
+            changes.push("CREATE init-options.json");
+            if (!dry) {
                 writeFileSync(initOptionsPath, JSON.stringify({
-                    ai: "claude-code",
+                    ai: initOpts?.ai ?? "claude-code",
                     script_type: "sh",
                     branch_numbering: "sequential",
-                    preset: "mobile-opinionated",
+                    preset: presetId ?? "mobile-opinionated",
                     no_git: false,
                     created_at: new Date().toISOString(),
                 }, null, 2) + "\n");
             }
         }
-        if (existsSync(raptorYmlPath)) {
-            try {
-                const ymlContent = readFileSync(raptorYmlPath, "utf-8");
-                if (/^agents:\s*\[\]/m.test(ymlContent)) {
-                    changes.push("REMOVE legacy agents: block from raptor.yml (agents now in agents.yml)");
-                    if (!flags["dry-run"]) {
-                        const cleaned = ymlContent.replace(/\nagents:\s*\[\]\n(?:#[^\n]*\n)*/, "\n# Agent configuration lives in agents.yml — do not add agents here.\n# Run 'raptor add-agent <key>' to configure agents.\n");
-                        writeFileSync(raptorYmlPath, cleaned);
-                    }
-                }
+        const memC = join(raptorDir, "memory", "constitution.md");
+        if (!existsSync(memC) && existsSync(constPath)) {
+            changes.push("COPY constitution.md → memory/constitution.md");
+            if (!dry) {
+                mkdirSync(dirname(memC), { recursive: true });
+                copyFileSync(constPath, memC);
             }
-            catch {
+        }
+        const agentsYmlPath = join(raptorDir, "agents.yml");
+        if (!existsSync(agentsYmlPath)) {
+            changes.push("CREATE agents.yml");
+            if (!dry) {
+                writeFileSync(agentsYmlPath, generateAgentsYaml(agents.map((a) => ({
+                    id: a.id,
+                    kind: a.id,
+                    capabilities: [...a.capabilities],
+                }))));
             }
         }
+        if (!dry) {
+            manifest.updated_at = new Date().toISOString();
+            writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+            session?.discardIfEmpty();
+        }
         if (changes.length === 0) {
             this.log("✓ Project is up to date. No changes needed.");
+            for (const s of skipped)
+                this.log(`  ⊘ skipped: ${s}`);
             return;
         }
-        if (flags["dry-run"]) {
-            this.log("\nDRY RUN — would apply the following changes:\n");
-            for (const change of changes) {
-                this.log(`  • ${change}`);
-            }
+        if (dry) {
+            this.log("\nDRY RUN — would apply:\n");
+            for (const c of changes)
+                this.log(`  • ${c}`);
+            for (const s of skipped)
+                this.log(`  ⊘ skipped: ${s}`);
             this.log("\nRe-run without --dry-run to apply.");
         }
         else {
-            this.log("\n✓ Upgrade complete. Changes applied:\n");
-            for (const change of changes) {
-                this.log(`  ✓ ${change}`);
+            this.log("\n✓ Upgrade complete:\n");
+            for (const c of changes)
+                this.log(`  ✓ ${c}`);
+            for (const s of skipped)
+                this.log(`  ⊘ skipped: ${s}`);
+            if (session && existsSync(session.dir)) {
+                this.log(`\n  💾 Previous versions backed up to ${session.dir}`);
+            }
+        }
+    }
+    resolveAgents(root, primaryAi) {
+        const cfg = loadAgentsConfig(root);
+        if (cfg?.agents?.length) {
+            const seen = new Set();
+            const out = [];
+            for (const a of cfg.agents) {
+                const adapter = getAgentByKind(a.kind ?? a.id);
+                if (adapter && !seen.has(adapter.id)) {
+                    seen.add(adapter.id);
+                    out.push(adapter);
+                }
             }
+            if (out.length)
+                return out;
         }
+        const primary = primaryAi ? getAgentByKind(primaryAi) : undefined;
+        const detected = detectInstalledAgents();
+        const out = primary
+            ? [primary, ...detected.filter((a) => a.id !== primary.id)]
+            : detected;
+        return out;
     }
 }

package/dist/shared/project.js

@@ -31,6 +31,12 @@ export function writeConfig(root, config) {
     const path = join(root, '.raptor', 'raptor.yml');
     writeFileSync(path, stringifyYaml(config));
 }
+export function restampYmlVersion(raw, version) {
+    if (/^version:.*$/m.test(raw)) {
+        return raw.replace(/^version:.*$/m, `version: ${version}`);
+    }
+    return `version: ${version}\n${raw}`;
+}
 export function readInitOptions(root) {
     const path = join(root, '.raptor', 'init-options.json');
     if (!existsSync(path))

package/dist/shared/scaffold.js

@@ -0,0 +1,162 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+export function findRaptorPackageRoot() {
+    let dir = dirname(new URL(import.meta.url).pathname);
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")) ||
+            existsSync(join(dir, "scripts", "bash"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function walkFiles(dir, onFile) {
+    for (const entry of readdirSync(dir)) {
+        const abs = join(dir, entry);
+        if (statSync(abs).isDirectory())
+            walkFiles(abs, onFile);
+        else
+            onFile(abs);
+    }
+}
+export function collectFrameworkFiles(raptorDir) {
+    const pkgRoot = findRaptorPackageRoot();
+    const out = [];
+    if (!pkgRoot)
+        return out;
+    for (const { dir, ext } of [
+        { dir: "bash", ext: ".sh" },
+        { dir: "powershell", ext: ".ps1" },
+    ]) {
+        const s = join(pkgRoot, "scripts", dir);
+        if (!existsSync(s))
+            continue;
+        for (const f of readdirSync(s).filter((f) => f.endsWith(ext))) {
+            out.push({
+                src: join(s, f),
+                dest: join(raptorDir, "scripts", dir, f),
+                exec: ext === ".sh",
+            });
+        }
+    }
+    const sc = join(pkgRoot, "templates", "commands");
+    if (existsSync(sc)) {
+        for (const f of readdirSync(sc).filter((f) => f.endsWith(".md"))) {
+            out.push({ src: join(sc, f), dest: join(raptorDir, "templates", "commands", f) });
+        }
+    }
+    const st = join(pkgRoot, "templates");
+    if (existsSync(st)) {
+        for (const f of readdirSync(st).filter((f) => f.endsWith("-template.md"))) {
+            out.push({ src: join(st, f), dest: join(raptorDir, "templates", f) });
+        }
+    }
+    const se = join(pkgRoot, "extensions");
+    if (existsSync(se)) {
+        for (const extId of readdirSync(se)) {
+            const sed = join(se, extId);
+            if (!existsSync(join(sed, "extension.yml")))
+                continue;
+            walkFiles(sed, (abs) => out.push({
+                src: abs,
+                dest: join(raptorDir, "extensions", extId, relative(sed, abs)),
+            }));
+        }
+    }
+    return out;
+}
+export function copyDirRecursive(source, target) {
+    mkdirSync(target, { recursive: true });
+    for (const entry of readdirSync(source)) {
+        const src = join(source, entry);
+        const dest = join(target, entry);
+        if (statSync(src).isDirectory()) {
+            copyDirRecursive(src, dest);
+        }
+        else {
+            copyFileSync(src, dest);
+        }
+    }
+}
+export function installShellScripts(cmd, raptorDir, manifest) {
+    const pkgRoot = findRaptorPackageRoot();
+    if (!pkgRoot) {
+        cmd.warn("Could not locate Raptor package root — shell scripts not copied.");
+        return [];
+    }
+    const copied = [];
+    const summary = [];
+    const shells = [
+        { dir: "bash", ext: ".sh" },
+        { dir: "powershell", ext: ".ps1" },
+    ];
+    for (const shell of shells) {
+        const sourceDir = join(pkgRoot, "scripts", shell.dir);
+        const targetDir = join(raptorDir, "scripts", shell.dir);
+        if (!existsSync(sourceDir))
+            continue;
+        mkdirSync(targetDir, { recursive: true });
+        const files = readdirSync(sourceDir).filter((f) => f.endsWith(shell.ext));
+        for (const file of files) {
+            const dest = join(targetDir, file);
+            copyFileSync(join(sourceDir, file), dest);
+            if (shell.ext === ".sh")
+                chmodSync(dest, 0o755);
+            copied.push(`scripts/${shell.dir}/${file}`);
+        }
+        if (files.length > 0)
+            summary.push(`${files.length} ${shell.dir}`);
+    }
+    manifest.scripts_installed = copied;
+    writeFileSync(join(raptorDir, "raptor.manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    if (summary.length > 0)
+        cmd.log(`  Scripts:  ${summary.join(", ")}`);
+    return copied;
+}
+export function installTemplates(raptorDir) {
+    const pkgRoot = findRaptorPackageRoot();
+    if (!pkgRoot)
+        return;
+    const srcTemplates = join(pkgRoot, "templates");
+    if (!existsSync(srcTemplates))
+        return;
+    const srcCommands = join(srcTemplates, "commands");
+    if (existsSync(srcCommands)) {
+        const destCommands = join(raptorDir, "templates", "commands");
+        mkdirSync(destCommands, { recursive: true });
+        for (const f of readdirSync(srcCommands).filter((f) => f.endsWith(".md"))) {
+            copyFileSync(join(srcCommands, f), join(destCommands, f));
+        }
+    }
+    const destTemplates = join(raptorDir, "templates");
+    mkdirSync(destTemplates, { recursive: true });
+    for (const f of readdirSync(srcTemplates).filter((f) => f.endsWith("-template.md"))) {
+        copyFileSync(join(srcTemplates, f), join(destTemplates, f));
+    }
+}
+export function installBundledExtensions(cmd, raptorDir, manifest) {
+    const pkgRoot = findRaptorPackageRoot();
+    if (!pkgRoot)
+        return [];
+    const sourceExtRoot = join(pkgRoot, "extensions");
+    if (!existsSync(sourceExtRoot))
+        return [];
+    const registered = [];
+    for (const extId of readdirSync(sourceExtRoot)) {
+        const sourceExt = join(sourceExtRoot, extId);
+        if (!existsSync(join(sourceExt, "extension.yml")))
+            continue;
+        copyDirRecursive(sourceExt, join(raptorDir, "extensions", extId));
+        registered.push(extId);
+    }
+    if (registered.length === 0)
+        return [];
+    manifest.extensions_registered = registered;
+    writeFileSync(join(raptorDir, "raptor.manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    cmd.log(`  Ext:      ${registered.length} bundled (${registered.join(", ")})`);
+    return registered;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raptor-aios",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Raptor — Spec-Driven Development (SDD) CLI for modern mobile apps. Constitutional gates, audit trail, real verification (a11y/perf/stores/OS matrix), and AI-agent slash commands.",
   "type": "module",
   "bin": {

package/scripts/prepare-npm.mjs

@@ -29,7 +29,7 @@ const CLI = join(ROOT, "packages", "cli");
 const CORE = join(ROOT, "packages", "core");
 const OUT = join(ROOT, "build", "npm");
 
-const VERSION = "0.6.1";
+const VERSION = "0.6.3";
 
 function log(msg) {
   process.stdout.write(`  ${msg}\n`);