create-agent-rig 0.3.2 → 0.5.0

package/packages/cli/dist/index.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
+import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
-import { promptTarget } from './lib/prompts.js';
+import { readManifest } from './lib/manifest.js';
+import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
+import { packageVersion } from './lib/version.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
-Scaffolds a new project into <dir>: agent operating system (.claude/, CLAUDE.md)
+Scaffolds a new project into <dir>: a Claude Code + Codex agent operating system
 plus a runnable code skeleton. Refuses to write into a non-empty directory.
 
 Options
@@ -23,16 +23,16 @@ Options
   --version         print the version
   -h, --help        this text
 
-Also: create-agent-rig init [--dry-run] [--force]
+Also: create-agent-rig init [--dry-run]
   Install the process layer (rules, gates, stop rules — no architecture
-  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.`;
-async function packageVersion() {
-    // dist/index.js lives three levels under the package root — same walk as
-    // the templates resolver, valid in the repo and in the published package.
-    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json');
-    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
-    return pkg.version;
-}
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md
+  or AGENTS.md.
+  --force is deprecated: it refuses and points at upgrade, which refreshes a
+  rig file by file. It is removed in 0.6.
+
+Also: create-agent-rig upgrade [--dry-run] [--yes]
+  Bring the rig in the CURRENT repo up to this version. Replaces the files it
+  installed and you did not touch; everything else is reported, never merged.`;
 async function runInit(rawArgs) {
     let values;
     try {
@@ -48,10 +48,23 @@ async function runInit(rawArgs) {
     }
     const cwd = process.cwd();
     const dryRun = values['dry-run'] === true;
+    // `init` adopts a repo the rig knows nothing about. Run inside a rig `create`
+    // generated — reachable when its CLAUDE.md was deleted — it is the wrong
+    // command: it installs the process layer alone and never refreshes the stack
+    // overlays. Say so before anything is written, so it is visible on --dry-run
+    // too.
+    //
+    // It is a manifest read, so a pre-0.4.0 rig with no manifest gets no advisory
+    // even when it came from `create` — the same limit `recordInstall` carries,
+    // and stated in both places because either one alone reads as wider.
+    const existing = await readManifest(cwd);
     const plan = await planInit(cwd);
     process.stdout.write(`agent-rig init — process layer into ${cwd}\n\n` +
         plan.files.map((f) => `  + ${f.path}`).join('\n') +
         '\n');
+    if (existing?.kind === 'create') {
+        process.stdout.write(`\n!  This rig was created by create-agent-rig — \`init\` only fills gaps here; use \`upgrade\` to refresh.\n`);
+    }
     if (plan.conflicts.length > 0) {
         process.stdout.write(`\nAlready present (kept, not overwritten):\n` +
             plan.conflicts.map((c) => `  · ${c}`).join('\n') +
@@ -65,22 +78,118 @@ async function runInit(rawArgs) {
     process.stdout.write(`\nInstalled ${result.written.length} files` +
         (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
         '.\n');
-    // The one kept file that silently disables everything else: without this
-    // wiring the hooks sit on disk and are never called, while the rules claim
-    // they are enforced. Say so loudly, and hand over the exact entries.
-    if (result.skipped.includes('.claude/settings.json')) {
-        const wiring = (await initFileContents(cwd)).get('.claude/settings.json') ?? '';
-        process.stdout.write(`\n!  .claude/settings.json already exists — it was kept, so the rig's hooks are NOT wired.\n` +
+    // A kept harness config silently disables that harness's enforcement: the
+    // hooks sit on disk and are never called, while the rules claim they are.
+    // Say so loudly, and hand over the exact entries for each affected harness.
+    const generated = await initFileContents(cwd);
+    for (const wiringPath of ['.claude/settings.json', '.codex/hooks.json']) {
+        if (!result.skipped.includes(wiringPath))
+            continue;
+        const wiring = generated.get(wiringPath) ?? '';
+        process.stdout.write(`\n!  ${wiringPath} already exists — it was kept, so the rig's hooks are NOT wired there.\n` +
             `   Until you merge these entries into it, nothing enforces the rules:\n\n` +
             wiring.replace(/^/gm, '   ') +
             '\n');
     }
     return 0;
 }
+const MARK = {
+    update: '~',
+    new: '+',
+    conflict: '!',
+    deleted: '-',
+    wiring: '!',
+    unchanged: '·',
+};
+function renderUpgradePlan(repoDir, plan) {
+    const of = (verdict) => plan.actions.filter((a) => a.verdict === verdict);
+    const lines = [
+        `agent-rig upgrade — ${plan.kind} rig in ${repoDir}`,
+        plan.bootstrapped
+            ? `  no manifest here (a pre-0.4.0 rig) — matching files against released versions`
+            : `  installed by ${plan.fromVersion}`,
+        `  upgrading to ${plan.toVersion}`,
+        '',
+    ];
+    for (const verdict of ['update', 'new', 'deleted', 'conflict', 'wiring']) {
+        for (const action of of(verdict)) {
+            lines.push(`  ${MARK[verdict]} ${action.rel}` + (action.reason ? `  — ${action.reason}` : ''));
+            // A conflict is only useful if the new version can be diffed by hand.
+            if (verdict === 'conflict' && action.templatePath) {
+                lines.push(`      new version: ${action.templatePath}`);
+            }
+        }
+    }
+    const unchanged = of('unchanged').length;
+    lines.push('', `  ${of('update').length} to replace, ${of('new').length} new, ` +
+        `${of('conflict').length} yours (kept), ${unchanged} already current`);
+    return `${lines.join('\n')}\n`;
+}
+async function runUpgrade(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: { 'dry-run': { type: 'boolean' }, yes: { type: 'boolean' } },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const cwd = process.cwd();
+    const plan = await planUpgrade(cwd);
+    process.stdout.write(renderUpgradePlan(cwd, plan));
+    // The one thing this command will not do for you — printed with the plan,
+    // because the dry run is where a reader decides whether there is work here,
+    // and a report that mentions entries it never shows is not a plan.
+    if (plan.wiringByPath.size > 0) {
+        for (const [wiringPath, wiring] of plan.wiringByPath) {
+            process.stdout.write(`\n!  ${wiringPath} was handed over rather than replaced — the reason is\n` +
+                `   on its line above. It is hook wiring, so it is never overwritten\n` +
+                `   without proof the rig wrote those exact bytes.\n` +
+                `   This version wires it like this; merge in what is missing:\n\n` +
+                wiring.replace(/^/gm, '   ') +
+                '\n');
+        }
+    }
+    if (values['dry-run'] === true) {
+        process.stdout.write('\nDry run — nothing written.\n');
+        return 0;
+    }
+    // The plan above is the review step, so it has to be answered before
+    // anything is written. On a terminal that is a question; off one it is the
+    // same refusal `create` makes without --target — never guess for a run that
+    // cannot be asked, least of all when the answer rewrites its repository.
+    const isInteractive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (values.yes !== true) {
+        if (!isInteractive) {
+            process.stderr.write('Refusing to rewrite files in a non-interactive run. ' +
+                'Re-run with --yes once the plan above is what you want (or --dry-run to keep looking).\n');
+            return 1;
+        }
+        const confirmed = await promptConfirm('\nApply this plan?', {
+            input: process.stdin,
+            output: process.stderr,
+            isInteractive,
+        });
+        if (!confirmed) {
+            process.stdout.write('Nothing written.\n');
+            return 0;
+        }
+    }
+    const result = await applyUpgrade(cwd, plan);
+    process.stdout.write(`\nWrote ${result.written.length} files.\n`);
+    return 0;
+}
 async function main() {
     if (process.argv[2] === 'init') {
         return runInit(process.argv.slice(3));
     }
+    if (process.argv[2] === 'upgrade') {
+        return runUpgrade(process.argv.slice(3));
+    }
     let positionals;
     let values;
     try {
@@ -144,7 +253,9 @@ main()
     process.exitCode = code;
 })
     .catch((error) => {
-    if (error instanceof CreateError || error instanceof InitError) {
+    if (error instanceof CreateError ||
+        error instanceof InitError ||
+        error instanceof UpgradeError) {
         process.stderr.write(`${error.message}\n`);
     }
     else {

package/packages/cli/dist/lib/copy-tree.js

@@ -25,8 +25,38 @@ function isBinary(buffer) {
 }
 export async function copyTree(srcDir, destDir, options = {}) {
     const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
+    const files = [];
     await mkdir(destDir, { recursive: true });
-    await copyDir(srcDir, destDir, '', { ...options, ignore });
+    await collectCopyTasks(srcDir, destDir, '', { ...options, ignore }, files);
+    await mapConcurrent(files, 16, ({ srcPath, destPath, relPath }) => copyFileEntry(srcPath, destPath, relPath, { ...options, ignore }));
+}
+/** Run independent async work through a bounded pool while preserving result order. */
+export async function mapConcurrent(items, limit, worker) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new RangeError('concurrency limit must be positive');
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    let firstError;
+    const run = async () => {
+        while (!failed && next < items.length) {
+            const index = next;
+            next += 1;
+            try {
+                results[index] = await worker(items[index]);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    firstError = error;
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => run()));
+    if (failed)
+        throw firstError;
+    return results;
 }
 /**
  * The destination-relative file paths {@link copyTree} would produce — same
@@ -34,6 +64,14 @@ export async function copyTree(srcDir, destDir, options = {}) {
  * composition for collisions before anything is copied.
  */
 export async function listTree(srcDir, options = {}) {
+    return (await listTreeEntries(srcDir, options)).map((entry) => entry.rel);
+}
+/**
+ * {@link listTree} with the source path kept alongside each destination — what
+ * an upgrade needs to read the new version of a file, and to name where it
+ * lives when it must not write it.
+ */
+export async function listTreeEntries(srcDir, options = {}) {
     const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
     const files = [];
     const walk = async (dir, relDir) => {
@@ -47,14 +85,14 @@ export async function listTree(srcDir, options = {}) {
                 await walk(path.join(dir, entry.name), relPath);
             }
             else if (entry.isFile()) {
-                files.push(relPath);
+                files.push({ rel: relPath, source: path.join(dir, entry.name) });
             }
         }
     };
     await walk(srcDir, '');
     return files;
 }
-async function copyDir(srcDir, destDir, relDir, options) {
+async function collectCopyTasks(srcDir, destDir, relDir, options, files) {
     const entries = await readdir(srcDir, { withFileTypes: true });
     for (const entry of entries) {
         if (options.ignore.has(entry.name))
@@ -65,10 +103,10 @@ async function copyDir(srcDir, destDir, relDir, options) {
         const relPath = path.join(relDir, entry.name);
         if (entry.isDirectory()) {
             await mkdir(destPath, { recursive: true });
-            await copyDir(srcPath, destPath, relPath, options);
+            await collectCopyTasks(srcPath, destPath, relPath, options, files);
         }
         else if (entry.isFile()) {
-            await copyFileEntry(srcPath, destPath, relPath, options);
+            files.push({ srcPath, destPath, relPath });
         }
         // Symlinks and other special entries are intentionally not copied:
         // templates are plain trees.
@@ -79,7 +117,7 @@ async function copyFileEntry(srcPath, destPath, relPath, options) {
         await copyFile(srcPath, destPath); // copyFile preserves the mode by itself
         return;
     }
-    const buffer = await readFile(srcPath);
+    const [buffer, { mode }] = await Promise.all([readFile(srcPath), stat(srcPath)]);
     if (isBinary(buffer)) {
         await writeFile(destPath, buffer);
     }
@@ -88,6 +126,5 @@ async function copyFileEntry(srcPath, destPath, relPath, options) {
     }
     // writeFile does NOT preserve permissions — restore them (chmod ignores umask),
     // otherwise executable template files (scripts, hooks) arrive non-executable.
-    const { mode } = await stat(srcPath);
     await chmod(destPath, mode & 0o777);
 }

package/packages/cli/dist/lib/history.js

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { templatesRoot } from '../templates.js';
+export const EMPTY_HISTORY = { versions: [], files: {} };
+/**
+ * Whether every release this table knows about carried this path.
+ *
+ * It is the one question that lets a manifest-less rig keep a **deletion**: if
+ * the file shipped in every version the rig could possibly be, then it is gone
+ * because somebody removed it — not because the rig predates it. A path added
+ * later is genuinely new to an older rig and must still be delivered.
+ */
+export function presentInEveryRelease(history, rel) {
+    const oldest = history.versions[0];
+    const entry = history.files[rel];
+    return oldest !== undefined && entry !== undefined && entry.since === oldest;
+}
+export function historyPath() {
+    return path.join(templatesRoot(), 'hash-history.json');
+}
+/**
+ * Fails open to an empty table: a missing or corrupt history means "nothing is
+ * recognised", which downgrades files to conflicts. That is the safe
+ * direction — the unsafe one is claiming a file is untouched when it is not.
+ */
+export async function loadHashHistory() {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(historyPath(), 'utf8'));
+    }
+    catch {
+        return EMPTY_HISTORY;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return EMPTY_HISTORY;
+    const { versions, files } = parsed;
+    if (!Array.isArray(versions) || typeof files !== 'object' || files === null)
+        return EMPTY_HISTORY;
+    const clean = {};
+    for (const [rel, entry] of Object.entries(files)) {
+        const { since, hashes } = (entry ?? {});
+        if (typeof since !== 'string')
+            continue;
+        if (!Array.isArray(hashes) || hashes.some((h) => typeof h !== 'string'))
+            continue;
+        clean[rel] = { since, hashes };
+    }
+    return { versions: versions.filter((v) => typeof v === 'string'), files: clean };
+}

package/packages/cli/dist/lib/init-settings.js

@@ -13,6 +13,18 @@
  */
 /** Matches the hook file a wired command runs, e.g. `.claude/hooks/guard-bash.mjs`. */
 const HOOK_REFERENCE = /\.claude\/hooks\/[A-Za-z0-9._-]+\.mjs/;
+/**
+ * Every hook file some command in this settings text would run.
+ *
+ * Deliberately a scan of the raw text rather than a walk of the parsed shape:
+ * the caller compares two settings files to ask whether one stops calling a
+ * hook the other called, and a shape this module does not understand must not
+ * make that question answer "nothing was wired". The same expression decides
+ * both, so the filter and the comparison cannot drift apart.
+ */
+export function hookFilesReferencedIn(settingsText) {
+    return new Set(settingsText.match(new RegExp(HOOK_REFERENCE, 'g')) ?? []);
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/packages/cli/dist/lib/install-set.js

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { listTreeEntries, mapConcurrent } from './copy-tree.js';
+import { substituteContent, substituteFileName } from './substitute.js';
+import { agentOsStackDir, agentOsUniversalDir } from '../templates.js';
+/**
+ * The agent-os layers of a target, in composition order. One definition, read
+ * by `create` when it copies them and by `upgrade` when it refreshes them —
+ * two lists would drift, and the one nobody looks at would be the wrong one.
+ */
+export function agentOsLayerDirs(stacks) {
+    return [
+        { name: 'agent-os/universal', dir: agentOsUniversalDir() },
+        ...stacks.map((stack) => ({ name: `agent-os/stack/${stack}`, dir: agentOsStackDir(stack) })),
+    ];
+}
+/**
+ * Exactly the agent-os bytes `create` writes, for a given target and project.
+ *
+ * The skeleton is deliberately absent: after generation the code is the user's
+ * project, not the rig's — `upgrade` refreshes the process layer and nothing
+ * else. Layers claim disjoint paths (`composition.ts` refuses otherwise), so
+ * this is a plain concatenation.
+ *
+ * 🔴 Two assumptions, both load-bearing and both true today: the layer is all
+ * **text** (this reads every file as UTF-8; a template test pins it for the
+ * process half) and none of it is **executable** (`upgrade` writes with a bare
+ * `writeFile` and does not carry the mode across the way `copyTree` does —
+ * nothing in `templates/agent-os` currently has a mode to carry). Adding the
+ * first binary asset or executable script here means teaching both.
+ */
+export async function agentOsInstallSet(stacks, ctx) {
+    const files = [];
+    for (const layer of agentOsLayerDirs(stacks)) {
+        const entries = await listTreeEntries(layer.dir, {
+            transformName: (name) => substituteFileName(name, ctx),
+        });
+        files.push(...(await mapConcurrent(entries, 16, async (entry) => ({
+            rel: entry.rel,
+            source: entry.source,
+            content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
+        }))));
+    }
+    return files;
+}

package/packages/cli/dist/lib/manifest.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isSafeSubstitutionValue } from './safe-path.js';
+/**
+ * The install manifest: what this rig installed, at which version, and the
+ * hash each file had when it was written.
+ *
+ * It exists to answer the one hard question an upgrade has — *did the user
+ * edit this file?* — with evidence instead of a guess. It is **evidence, not a
+ * command**: a file the manifest names but the disk no longer has is reported,
+ * never silently restored.
+ *
+ * It is meant to be committed. Without it in the repository, an upgrade run on
+ * CI or on a colleague's machine is blind and falls back to the hash history.
+ */
+export const MANIFEST_REL = '.claude/.rig-manifest.json';
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function isStringRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === 'string'));
+}
+/**
+ * A manifest, or `null` when there is nothing trustworthy to read.
+ *
+ * The distinction matters: `null` means "no evidence", which sends the upgrade
+ * to the hash history. A half-parsed manifest treated as an empty one would
+ * claim every file on disk belongs to the user, and upgrade nothing at all.
+ */
+export function parseManifest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const m = parsed;
+    if (typeof m.version !== 'string')
+        return null;
+    if (m.kind !== 'create' && m.kind !== 'init')
+        return null;
+    const project = m.project;
+    if (typeof project !== 'object' ||
+        project === null ||
+        typeof project.name !== 'string' ||
+        typeof project.scope !== 'string' ||
+        typeof project.region !== 'string') {
+        return null;
+    }
+    // Values, not just types. This file is committed, so it reaches a
+    // maintainer's disk through a pull request. A name of `../..` would send a
+    // write out of the repository — and `name` and `region` go further than
+    // paths: they are substituted into installed **files**, where a quote closes
+    // the string literal `stop-flag.mjs` embeds the name in, which `guard-bash`
+    // imports on every Bash call. (`scope` reaches no template today and a
+    // `stacks` entry names an overlay *directory*.) An unsafe value invalidates
+    // the whole manifest rather than being quietly corrected into something
+    // plausible.
+    //
+    // One check, not two: `isSafeSubstitutionValue` is strictly stronger than
+    // `isSafeSegment` here — its first character excludes `.`, and its class
+    // admits neither `/` nor `\` nor `\0` — so pairing them would leave a second
+    // predicate that can never fire, read as cover, and quietly stop being true
+    // if either one moves. `isSafeSegment` still guards every path segment at
+    // write time, in `resolveInside`.
+    if (!isSafeSubstitutionValue(project.name) || !isSafeSubstitutionValue(project.scope)) {
+        return null;
+    }
+    if (project.region !== '' && !isSafeSubstitutionValue(project.region))
+        return null;
+    if (!Array.isArray(m.stacks) || m.stacks.some((s) => typeof s !== 'string'))
+        return null;
+    if (m.stacks.some((s) => !isSafeSubstitutionValue(s)))
+        return null;
+    if (!isStringRecord(m.files))
+        return null;
+    return {
+        version: m.version,
+        kind: m.kind,
+        project: { name: project.name, scope: project.scope, region: project.region },
+        stacks: [...m.stacks],
+        files: { ...m.files },
+    };
+}
+/** Stable bytes: sorted paths, so a re-run produces no diff of its own. */
+export function serializeManifest(manifest) {
+    const files = {};
+    for (const rel of Object.keys(manifest.files).sort())
+        files[rel] = manifest.files[rel];
+    return `${JSON.stringify({ ...manifest, files }, null, 2)}\n`;
+}
+export async function readManifest(repoDir) {
+    try {
+        return parseManifest(await readFile(path.join(repoDir, ...MANIFEST_REL.split('/')), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeManifest(repoDir, manifest) {
+    const dest = path.join(repoDir, ...MANIFEST_REL.split('/'));
+    await mkdir(path.dirname(dest), { recursive: true });
+    await writeFile(dest, serializeManifest(manifest));
+}

package/packages/cli/dist/lib/prompts.js

@@ -1,4 +1,24 @@
 import { createInterface } from 'node:readline';
+/**
+ * A yes/no gate before something irreversible. **The default is no**, and a
+ * non-interactive caller gets `false` without being asked — the same rule the
+ * rest of this CLI follows: never guess for a run that cannot answer.
+ *
+ * Unlike the target prompt, an unrecognised answer is *not* forgiving: the
+ * question is asked before rewriting files in somebody's repository, and "I
+ * did not understand you" must not resolve to "go ahead".
+ */
+export function promptConfirm(question, streams) {
+    if (!streams.isInteractive)
+        return Promise.resolve(false);
+    const rl = createInterface({ input: streams.input, output: streams.output });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
 /**
  * Pick a target interactively: by number, by name, or Enter for the default.
  * Anything unrecognised falls back to the default — generation should never

package/packages/cli/dist/lib/safe-path.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+/**
+ * Path safety for values that came from **outside the CLI** — the install
+ * manifest is committed to a repository, so it arrives in pull requests like
+ * any other file, and its values are substituted into paths.
+ *
+ * One module owns both halves so they cannot disagree: what may become a path
+ * segment, and where a resolved path is allowed to land.
+ */
+/** A value that can be substituted into a path without steering it. */
+export function isSafeSegment(value) {
+    return (value !== '' &&
+        value !== '.' &&
+        value !== '..' &&
+        !value.includes('/') &&
+        !value.includes('\\') &&
+        !value.includes('\0'));
+}
+/**
+ * A value that can be substituted into an **installed file** without changing
+ * what that file means.
+ *
+ * 🔴 **Why this is not {@link isSafeSegment}, and why widening that one instead
+ * would be wrong.** `isSafeSegment` answers "can this steer a path", and it is
+ * what {@link resolveInside} holds every path segment to when an upgrade
+ * writes — `CLAUDE.md` and `.claude/rules/workflow.md` have to keep passing it,
+ * so it cannot become this whitelist. But `project.name` is substituted into
+ * `.claude/scripts/stop-flag.mjs` **inside a single-quoted JavaScript string
+ * literal**, and `guard-bash` imports that module on every Bash call. A value
+ * that steers no path at all still closes that quote: it reaches code
+ * execution in the hook process, and it silently disarms the kill switch,
+ * because the paths it computes stop pointing at `~/.claude/<name>-loop-STOP`.
+ * A brake that looks installed and is not is the worst of the two.
+ *
+ * So the rule is a whitelist, not a blacklist of the payloads anyone thought
+ * of. It costs nothing real: `create` already refuses anything outside this
+ * shape, and `projectNameFor` only ever emits `[a-z0-9._-]` — plus a leading
+ * `_`, which is why the first character allows it.
+ *
+ * One legitimate value it does reject on purpose: the **empty** region, which
+ * `init` writes to mean "no region". That carve-out belongs to the caller
+ * (`parseManifest`), not here — an empty string is exactly what a whitelist of
+ * substitutable characters should refuse, and folding "or empty" into this
+ * predicate would hand it to `name` and `scope` as well.
+ */
+export function isSafeSubstitutionValue(value) {
+    return /^[a-z0-9_][a-z0-9._-]*$/.test(value);
+}
+/**
+ * `rel` resolved under `root`, or `null` when it would land anywhere else —
+ * including an absolute path, an empty path, and the classic sibling
+ * (`/tmp/rig` must not contain `/tmp/rig-evil`).
+ *
+ * This is the containment behind every write an upgrade makes. It is deliberate
+ * belt-and-braces: the values that build `rel` are validated where they are
+ * parsed, and this refuses the write anyway.
+ */
+export function resolveInside(root, rel) {
+    if (rel === '' || path.isAbsolute(rel))
+        return null;
+    const segments = rel.split('/');
+    // Refused, not repaired: joining an absolute or `..`-bearing path onto the
+    // root would silently turn hostile input into a plausible-looking write.
+    if (segments.some((segment) => !isSafeSegment(segment)))
+        return null;
+    const base = path.resolve(root);
+    const dest = path.resolve(base, ...segments);
+    if (dest === base)
+        return null;
+    return dest.startsWith(base + path.sep) ? dest : null;
+}

package/packages/cli/dist/lib/substitute.js

@@ -5,6 +5,38 @@ export function substituteContent(content, ctx) {
         .replaceAll('__REGION__', ctx.region)
         .replaceAll('@app/', `@${ctx.projectScope}/`);
 }
+/**
+ * The inverse of {@link substituteContent}, used **only to recognise** an
+ * installed file as a released version of its template: the released bytes
+ * carry tokens, the installed bytes carry the project's own name, and without
+ * this every token-carrying file (the kill switch, the loop skill, `CLAUDE.md`)
+ * would be a permanent conflict on every rig.
+ *
+ * 🔴 Limits, and both of them fail in the safe direction — an unrecognised file
+ * is reported and left alone, never overwritten:
+ *
+ * - `__PROJECT_SCOPE__` is not reversed. It substitutes to the same string as
+ *   `__PROJECT_NAME__`, so the two are indistinguishable after the fact; the
+ *   agent-os layer (the only layer an upgrade touches) uses neither the scope
+ *   token nor `@app/` in prose, which a template test pins.
+ * - A template that contains the project's name as a *literal* reverses into a
+ *   token that was never there. That costs nothing on its own — recognition
+ *   offers the untouched bytes as a candidate too, and those still match. It
+ *   bites only on a file carrying **both** a token and the literal, which then
+ *   reads as a conflict for that one project.
+ */
+export function detokenizeContent(content, ctx) {
+    let out = content;
+    // scope first: reversing the name first would rewrite `@name/` into
+    // `@__PROJECT_NAME__/` and the scope form could never match afterwards
+    if (ctx.projectScope !== '')
+        out = out.replaceAll(`@${ctx.projectScope}/`, '@app/');
+    if (ctx.region !== '')
+        out = out.replaceAll(ctx.region, '__REGION__');
+    if (ctx.projectName !== '')
+        out = out.replaceAll(ctx.projectName, '__PROJECT_NAME__');
+    return out;
+}
 /**
  * Files that must exist in the generated project under a dotted name, but are
  * stored un-dotted in the template because `npm publish` strips the dotted