create-agent-rig 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ the generator.
 Versions are published to npm as [`create-agent-rig`](https://www.npmjs.com/package/create-agent-rig);
 `npx github:serhii-baksheiev/create-agent-rig` keeps working for either path.
 
+Numbering is ordinary semver — **additive is a minor, a fix is a patch** — so
+that "I only take minors" remains a usable policy; 0.3.2 shipped additive
+content as a patch by the owner's call and stays recorded as one.
+
+## 0.4.0
+
+Upgrading is a command now: **`npx create-agent-rig@0.4.0 upgrade`** (`@latest`
+once you know what latest is — this section will not). That sentence replaces
+the six-file manual procedure 0.3.2 had to print, and it is the whole point of
+this release: a rig you cannot bring forward stops being maintained at whatever
+version you installed it at.
+
+Read the [Upgrading](README.md#upgrading-a-rig-you-already-have) section before
+the first run on an existing rig; `--dry-run` prints the plan and writes
+nothing.
+
+### Added
+
+- **`create-agent-rig upgrade [--dry-run] [--yes]`** — brings an installed rig
+  to this version: it replaces the files the rig wrote **and you have not
+  touched**, installs what the release adds, and **reports everything else**.
+  There is no three-way merge and no patching, by decision rather than
+  omission: silently folding your edits into the documents an agent loop obeys
+  is how a rig stops meaning what its owner thinks it means. Every conflict
+  names the file, why it was kept, and the path to the new version, so the diff
+  you may want is one command away.
+- **`.claude/.rig-manifest.json`** — written by `create` and by `init`: the rig
+  version and a hash per installed file. **Commit it.** It is what lets an
+  upgrade tell a file the rig wrote from a file you own, and without it in the
+  repository the command is blind on CI and on a colleague's machine. `init`
+  records only files it actually wrote — never one it kept, which would be
+  claiming somebody else's document.
+- **A released-hash table travels in the package**, generated from the git tags
+  at release time and never by hand. It is what makes a 0.3.x rig upgradable at
+  all, and it answers a second question too: a file that shipped in every
+  release it covers and is gone from disk was **deleted on purpose**, so it
+  stays deleted. The rules tell you to delete the invariants your project does
+  not have; an upgrade that quietly restored them would be undoing your work.
+- **The `loop` skill writes back what a close unblocked**, in a required
+  journal field with three distinct answers — the items that were waiting, by
+  name; "nothing was waiting"; or "this queue has no dependency links" where
+  the adapter cannot answer at all. It is a **report, not an edit** to those
+  items: correcting queue state by hand destroys the evidence that the state is
+  unreliable, which the rules forbid by name.
+
+### Two things `upgrade` deliberately will not do
+
+- **Replace `.claude/settings.json`.** It is where your own hooks live, so the
+  new wiring is printed for you to merge — in the dry run too. The cost is
+  real and stated: a release that adds a hook delivers the file and not its
+  wiring, and whether a manifest-proven-unmodified settings file should be
+  refreshed is an open decision for 0.5.
+- **Touch the skeleton.** After `create`, the code is your project. The manifest
+  covers the agent-os layer and nothing else.
+
+### Deferred, and on what condition
+
+- The clarify-gate (`C-0…C-2`) — unchanged from 0.3.2: it enters once that gate
+  has fired at least once anywhere. Until then there is nothing to copy but an
+  intention.
+- `init --force` now overlaps `upgrade`, and its future is an open question
+  rather than a deprecation: decided in 0.5, unchanged here.
+
 ## 0.3.2
 
 Numbered as a patch by the owner's call; the content below is additive, so
@@ -35,10 +98,14 @@ will not touch them:
 .claude/hooks/gate-stop-dod.mjs          # judges the tree it is in
 ```
 
-Delete those six and re-run `init`, or copy them across by hand. A proper
-upgrade command is queued, not shipped — and until it exists this note tells you
-the manual steps rather than an easy sentence that leaves half the release
-inert. That failure mode is the whole subject of 0.3.1, immediately below.
+Delete those six and re-run `init`, or copy them across by hand. This note tells
+you the manual steps rather than an easy sentence that leaves half the release
+inert — that failure mode is the whole subject of 0.3.1, immediately below.
+
+> **Superseded in 0.4.0.** `create-agent-rig upgrade` delivers exactly these
+> files, and the ones every release after it changes. The procedure above is
+> kept as the record of what 0.3.2 asked of its users; do not follow it if you
+> have 0.4.0 or later.
 
 ### Added
 
@@ -256,7 +323,8 @@ layers, and the `aws-serverless` and `node-service` targets.
 ## Releasing
 
 `npm publish` needs 2FA and cannot be undone, so an agent prepares a release and
-**stops at that command**. Everything before it is mechanical:
+**stops at the first step it is not allowed to take** — normally `npm publish`,
+sometimes earlier (step 6). Everything before that is mechanical:
 
 1. `pnpm test` — the full suite, including the e2e that generates both targets
    cold and runs their own checks through the git path **and** the pack path.
@@ -264,8 +332,25 @@ layers, and the `aws-serverless` and `node-service` targets.
    tree, are in the tarball. This is where scaffolders break, and the git path
    cannot catch it.
 3. Version in `package.json` (and the private inner package, kept in step).
-4. This file, and `PLAN.md` if the plan's claims changed.
-5. `git tag v<version> && git push --tags`.
-6. **Owner:** `npm publish`.
-7. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in
-   an empty directory, then `pnpm install && pnpm check` inside it.
+4. `node scripts/build-hash-history.mjs` — regenerate the released-hash table
+   from the tags **after** the version bump, so the version now shipping is the
+   first one it excludes. Forgetting it would leave `upgrade` unable to
+   recognise the previous release.
+5. This file, and `PLAN.md` if the plan's claims changed.
+6. **`pnpm test` again — this run, not step 1, is the one that can catch a
+   stale hash table.** The check compares the table against the versions this
+   file lists below the one in `package.json`, so before steps 3–5 it is
+   comparing the _old_ release to the _old_ table and passes either way. A
+   guard that can only fire after the thing it guards has changed has to be run
+   after it.
+7. `git tag v<version> && git push --tags` — **first check that the tag does not
+   already exist** (`git ls-remote --tags origin`). A leftover from an abandoned
+   attempt is a published ref: deleting or moving it is an **owner** action, and
+   the release stops here until it is gone. A tag pointing at the wrong commit
+   is not cosmetic — the next release builds its hash table from it, and every
+   file that changed in between then reads as user-modified and stops being
+   upgradable.
+8. **Owner:** `npm publish`.
+9. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in
+   an empty directory, then `pnpm install && pnpm check` inside it; and
+   `upgrade --dry-run` in a rig installed from the previous version.

package/README.md

@@ -32,6 +32,44 @@ Two things it deliberately leaves to you, and says so in the installed
 `CLAUDE.md`: the Definition-of-Done gate has no `dod-checks.json` (it cannot know
 your commands), and the elevated-path list names only what every repo has.
 
+## Upgrading a rig you already have
+
+A release changes files, and `init` only ever _adds_ — so bringing an existing
+rig forward is its own command:
+
+```sh
+npx create-agent-rig@latest upgrade --dry-run  # print the plan, write nothing
+npx create-agent-rig@latest upgrade            # print the plan, then ask before writing
+npx create-agent-rig@latest upgrade --yes      # the answer up front (required off a terminal)
+```
+
+It replaces the files the rig installed **and you have not touched**, installs
+what the release added, and **reports everything else** — no three-way merge, no
+patching. Silently merging your edits into the documents an agent loop obeys is
+how a rig quietly stops meaning what you think it means; a conflict report is how
+it does not. Each conflict names the file, why it was kept, and the path to the
+new version so you can diff it yourself.
+
+How it knows: `create` and `init` write `.claude/.rig-manifest.json` — the rig
+version plus a hash per installed file. **Commit it**; without it in the
+repository the command is blind on CI and on a colleague's machine. Rigs
+installed before 0.4.0 have no manifest, so the package also carries the hashes
+of every **tagged** release (0.3.0 onward — 0.1.0 and 0.2.0 shipped untagged,
+and a rig from those reports every file as yours) and recognises a file matching
+one of them.
+
+`.claude/settings.json` is never replaced — it is where your own hooks live, so
+the new wiring is printed for you to merge.
+
+**A file you deleted stays deleted.** The rules invite you to delete the ones
+whose invariant your project does not have, so an upgrade that quietly restored
+them would be undoing your work. With a manifest that is direct — it names the
+file, the disk does not have it, and the manifest is _evidence_, not a command.
+Without one, the shipped table answers instead: a file that was in every release
+it covers was there to be removed. The single case nothing can tell apart is a
+file a **later** release added, which your rig never had — that one is installed,
+and `--dry-run` lists it before anything is written.
+
 ## What you get
 
 **A system of boundaries, each held by tooling.** An agent (or a human using

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",

package/packages/cli/dist/commands/create.js

@@ -1,13 +1,16 @@
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, stat } from 'node:fs/promises';
+import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { copyTree, listTree } from '../lib/copy-tree.js';
 import { ALLOWED_OVERWRITES, detectCollisions } from '../lib/composition.js';
+import { agentOsLayerDirs } from '../lib/install-set.js';
+import { sha256, writeManifest } from '../lib/manifest.js';
 import { substituteContent, substituteFileName } from '../lib/substitute.js';
 import { gitEnv } from '../lib/git-env.js';
 import { DEFAULT_TARGET, TARGETS, TARGET_NAMES } from '../lib/targets.js';
-import { agentOsStackDir, agentOsUniversalDir, skeletonDir } from '../templates.js';
+import { skeletonDir } from '../templates.js';
+import { packageVersion } from '../lib/version.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class CreateError extends Error {
 }
@@ -36,13 +39,10 @@ export async function createProject(dirArg, options) {
         transformName: (name) => substituteFileName(name, ctx),
     };
     // Layer 2 (the skeleton) + layer 1 (agent-os: universal + stack overlays).
+    const agentOsLayers = agentOsLayerDirs(target.stacks);
     const layers = [
         { name: `skeleton/${target.skeletonDir}`, dir: skeletonDir(target.skeletonDir) },
-        { name: 'agent-os/universal', dir: agentOsUniversalDir() },
-        ...target.stacks.map((stack) => ({
-            name: `agent-os/stack/${stack}`,
-            dir: agentOsStackDir(stack),
-        })),
+        ...agentOsLayers,
     ];
     // Composition safety: layers must claim disjoint paths. Checked before any
     // copy — a collision is a template bug and must never be resolved by order.
@@ -61,11 +61,39 @@ export async function createProject(dirArg, options) {
     for (const layer of layers) {
         await copyTree(layer.dir, projectDir, transforms);
     }
+    await recordInstall(projectDir, agentOsLayers, transforms, ctx, targetName);
     if (options.git !== false) {
         await initGitBaseline(projectDir);
     }
     return { projectDir, projectName };
 }
+/**
+ * Record the agent-os layer in `.claude/.rig-manifest.json`, so a later
+ * `upgrade` can tell a file the rig wrote from a file the project's own people
+ * changed.
+ *
+ * The skeleton is **not** recorded, and that is the boundary of the whole
+ * upgrade story: once generated, the code belongs to the project. The hashes
+ * are read back off the disk rather than recomputed, so the manifest states
+ * what is actually there and cannot drift from what was copied. The manifest
+ * lands before the baseline commit — it is part of the pristine template, and
+ * it belongs in the project's git history.
+ */
+async function recordInstall(projectDir, agentOsLayers, transforms, ctx, target) {
+    const files = {};
+    for (const layer of agentOsLayers) {
+        for (const rel of await listTree(layer.dir, transforms)) {
+            files[rel] = sha256(await readFile(path.join(projectDir, ...rel.split('/')), 'utf8'));
+        }
+    }
+    await writeManifest(projectDir, {
+        version: await packageVersion(),
+        kind: 'create',
+        project: { name: ctx.projectName, scope: ctx.projectScope, region: ctx.region },
+        stacks: [...(TARGETS[target]?.stacks ?? [])],
+        files,
+    });
+}
 const run = promisify(execFile);
 async function initGitBaseline(projectDir) {
     // Disable git's background maintenance for these one-shot commands: a commit

package/packages/cli/dist/commands/init.js

@@ -1,8 +1,10 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { settingsForInstalledHooks } from '../lib/init-settings.js';
+import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
 import { substituteContent } from '../lib/substitute.js';
 import { agentOsInitDir, agentOsUniversalDir } from '../templates.js';
+import { packageVersion } from '../lib/version.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class InitError extends Error {
 }
@@ -71,9 +73,13 @@ export async function initManifest() {
  * `__PROJECT_NAME__` in `stop-flag.mjs` is a kill switch that silently never
  * fires.
  */
-export async function initFileContents(repoDir) {
-    const projectName = projectNameFor(repoDir);
-    const ctx = { projectName, projectScope: projectName, region: '' };
+export async function initFileContents(repoDir, project) {
+    const projectName = project?.name ?? projectNameFor(repoDir);
+    const ctx = {
+        projectName,
+        projectScope: project?.scope ?? projectName,
+        region: project?.region ?? '',
+    };
     const files = await initManifest();
     const contents = new Map();
     for (const { rel, source } of files) {
@@ -86,6 +92,12 @@ export async function initFileContents(repoDir) {
     contents.set(SETTINGS, `${JSON.stringify(settingsForInstalledHooks(shipped, installedHooks), null, 2)}\n`);
     return contents;
 }
+/** The process layer as a set of {@link InstalledFile}s — what `upgrade` reads. */
+export async function initInstallSet(repoDir, project) {
+    const files = await initManifest();
+    const contents = await initFileContents(repoDir, project);
+    return files.map(({ rel, source }) => ({ rel, source, content: contents.get(rel) ?? '' }));
+}
 export async function planInit(repoDir) {
     const files = (await initManifest()).map((f) => f.rel);
     const conflicts = [];
@@ -123,5 +135,31 @@ export async function initProject(repoDir, options) {
         await writeFile(dest, contents.get(rel) ?? '');
         written.push(rel);
     }
+    if (!options.dryRun)
+        await recordInstall(repoDir, written, contents);
     return { written, skipped, plannedCount };
 }
+/**
+ * Record what was installed, so a later `upgrade` can tell a file it wrote
+ * from a file the user owns.
+ *
+ * Only files actually **written** are recorded. A file `init` kept is
+ * somebody else's — claiming it here would let the next upgrade replace a
+ * user's own document with the rig's. Earlier entries are preserved: a re-run
+ * writes nothing and must not therefore un-remember everything.
+ */
+async function recordInstall(repoDir, written, contents) {
+    const previous = await readManifest(repoDir);
+    const name = projectNameFor(repoDir);
+    const files = { ...(previous?.files ?? {}) };
+    for (const rel of written)
+        files[rel] = sha256(contents.get(rel) ?? '');
+    const manifest = {
+        version: await packageVersion(),
+        kind: 'init',
+        project: { name, scope: name, region: '' },
+        stacks: [],
+        files,
+    };
+    await writeManifest(repoDir, manifest);
+}

package/packages/cli/dist/commands/upgrade.js

@@ -0,0 +1,300 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { initInstallSet, projectNameFor } from './init.js';
+import { loadHashHistory, presentInEveryRelease } from '../lib/history.js';
+import { agentOsInstallSet, agentOsLayerDirs } from '../lib/install-set.js';
+import { listTree } from '../lib/copy-tree.js';
+import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
+import { resolveInside } from '../lib/safe-path.js';
+import { detokenizeContent, substituteFileName } from '../lib/substitute.js';
+import { TARGETS } from '../lib/targets.js';
+import { packageVersion } from '../lib/version.js';
+/** A user-facing failure: message is printed as-is, no stack trace. */
+export class UpgradeError extends Error {
+}
+const SETTINGS = '.claude/settings.json';
+/** The universal layer's architecture group — installed by `create`, never by `init`. */
+const ARCHITECTURE_ONLY = [
+    '.claude/rules/architecture.md',
+    '.claude/hooks/guard-core-purity.mjs',
+    '.claude/hooks/guard-web-boundary.mjs',
+];
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `rel` lives inside the rig — refused outright if it lands anywhere
+ * else. Nothing should be able to produce such a path once the manifest is
+ * validated, which is exactly why this stays: the whole command is writes into
+ * somebody's repository, and a containment check is cheap next to the cost of
+ * being wrong about that.
+ */
+function onDisk(repoDir, rel) {
+    const dest = resolveInside(repoDir, rel);
+    if (dest === null) {
+        throw new UpgradeError(`Refusing to touch "${rel}" — it resolves outside ${repoDir}.`);
+    }
+    return dest;
+}
+/**
+ * The file's bytes, or `null` when it is genuinely **absent**.
+ *
+ * Only "not there" is absence. Any other failure — a permission, a directory
+ * where a file should be, a path this command refuses to touch — is rethrown,
+ * because "I could not read your file" must never become "so I wrote mine over
+ * it": every caller of this treats `null` as grounds to install.
+ */
+async function readIfPresent(repoDir, rel) {
+    try {
+        return await readFile(onDisk(repoDir, rel), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/** Every stack overlay any target composes — the candidates a rig can carry. */
+function knownStacks() {
+    return [...new Set(Object.values(TARGETS).flatMap((t) => t.stacks))];
+}
+/**
+ * What a rig with no manifest looks like it is, from the files it has.
+ *
+ * Two signals, because one file is too thin a thread to hang a project's map
+ * on: the architecture rules and hooks, which `create` installs and `init`
+ * deliberately does not, **and** any stack-overlay file at all — `init`
+ * composes no overlays, so one of those is proof on its own. The region comes
+ * from the target whose stack set matches; it is the only value substitution
+ * needs that the directory name cannot give.
+ *
+ * 🔴 Limit: a `create` rig that deleted every architecture file *and* every
+ * stack file reads as an `init` rig. It is then offered the `init` flavour of
+ * `CLAUDE.md` — a map of a different project shape. Nothing but a manifest
+ * distinguishes those two rigs, which is why 0.4.0 writes one.
+ */
+async function detectInstall(repoDir) {
+    const ctx = { projectName: '', projectScope: '', region: '' };
+    const stacks = [];
+    for (const stack of knownStacks()) {
+        const [layer] = agentOsLayerDirs([stack]).slice(1);
+        if (layer === undefined)
+            continue;
+        const rels = await listTree(layer.dir, {
+            transformName: (name) => substituteFileName(name, ctx),
+        });
+        for (const rel of rels) {
+            if (await exists(onDisk(repoDir, rel))) {
+                stacks.push(stack);
+                break;
+            }
+        }
+    }
+    let architectural = stacks.length > 0;
+    for (const rel of ARCHITECTURE_ONLY) {
+        if (architectural)
+            break;
+        architectural = await exists(onDisk(repoDir, rel));
+    }
+    if (!architectural)
+        return { kind: 'init', stacks: [], region: '' };
+    const target = Object.values(TARGETS).find((t) => t.stacks.length === stacks.length && t.stacks.every((s) => stacks.includes(s)));
+    return { kind: 'create', stacks, region: target?.defaultRegion ?? '' };
+}
+async function installSetFor(repoDir, kind, project, stacks) {
+    if (kind === 'init')
+        return initInstallSet(repoDir, project);
+    return agentOsInstallSet(stacks, {
+        projectName: project.name,
+        projectScope: project.scope,
+        region: project.region,
+    });
+}
+/**
+ * Whether these bytes are a released version of this file.
+ *
+ * Two candidates are offered to the table: the bytes as they sit, and the
+ * bytes with the project's own values turned back into tokens — released
+ * template bytes carry `__PROJECT_NAME__`, installed bytes never do.
+ */
+function isReleasedVersion(history, rel, content, ctx) {
+    const known = history.files[rel];
+    if (known === undefined || known.hashes.length === 0)
+        return false;
+    const candidates = new Set([sha256(content), sha256(detokenizeContent(content, ctx))]);
+    return known.hashes.some((hash) => candidates.has(hash));
+}
+/**
+ * What an upgrade would do, decided per file, writing nothing.
+ *
+ * The rule is the whole design: **replace what the rig installed and the user
+ * did not touch; report everything else.** There is no three-way merge and no
+ * patching — silently merging someone's edits into a file the agent loop obeys
+ * is how a rig stops meaning what its owner thinks it means.
+ */
+export async function planUpgrade(repoDir, options = {}) {
+    const manifest = await readManifest(repoDir);
+    // Detection is a whole-tree probe, and it answers a question the manifest
+    // has already answered when there is one.
+    const detected = manifest === null
+        ? await detectInstall(repoDir)
+        : { kind: manifest.kind, stacks: manifest.stacks, region: manifest.project.region };
+    const kind = manifest?.kind ?? detected.kind;
+    const name = path.basename(path.resolve(repoDir));
+    // `init` slugs the directory name into something an operator can type (it
+    // ends up in the kill-switch filename); `create` validated it as an npm name
+    // at generation time, so there the basename is already the project name.
+    const bootstrapName = kind === 'init' ? projectNameFor(repoDir) : name;
+    const project = manifest?.project ?? {
+        name: bootstrapName,
+        scope: bootstrapName,
+        region: detected.region,
+    };
+    // Only overlays this version actually ships. An unknown name is not input
+    // being dropped — there is no layer behind it to install from — and reading
+    // a directory a manifest names would be reading a directory a manifest names.
+    const shipped = new Set(knownStacks());
+    const stacks = (manifest?.stacks ?? detected.stacks).filter((stack) => shipped.has(stack));
+    const history = options.history ?? (await loadHashHistory());
+    const files = await installSetFor(repoDir, kind, project, stacks);
+    const ctx = {
+        projectName: project.name,
+        projectScope: project.scope,
+        region: project.region,
+    };
+    const actions = [];
+    const contents = new Map();
+    const nextFiles = {};
+    let wiring = null;
+    for (const file of files) {
+        const current = await readIfPresent(repoDir, file.rel);
+        const recorded = manifest?.files[file.rel];
+        contents.set(file.rel, file.content);
+        if (current === null) {
+            // Evidence, not a command. The manifest is the direct evidence; without
+            // one, a path that shipped in *every* release the table covers was there
+            // to be removed, so its absence is a decision. A path added later is
+            // simply missing from an older rig, and that one is delivered.
+            if (recorded !== undefined) {
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'deleted',
+                    reason: 'installed by the rig, removed since — not restored',
+                });
+                nextFiles[file.rel] = recorded;
+            }
+            else if (presentInEveryRelease(history, file.rel)) {
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'deleted',
+                    reason: `shipped in every release since ${history.versions[0]}, and is gone — not restored`,
+                });
+            }
+            else {
+                actions.push({ rel: file.rel, verdict: 'new', templatePath: file.source });
+                nextFiles[file.rel] = sha256(file.content);
+            }
+            continue;
+        }
+        if (file.rel === SETTINGS) {
+            if (current === file.content) {
+                actions.push({ rel: file.rel, verdict: 'unchanged' });
+                nextFiles[file.rel] = sha256(file.content);
+            }
+            else {
+                // Same special case `init` makes: this file is a merge target, not a
+                // payload — replacing it can unwire hooks the user added themselves.
+                wiring = file.content;
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'wiring',
+                    reason: 'never replaced — merge the entries below by hand',
+                });
+                if (recorded !== undefined)
+                    nextFiles[file.rel] = recorded;
+            }
+            continue;
+        }
+        if (current === file.content) {
+            actions.push({ rel: file.rel, verdict: 'unchanged' });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else if (recorded !== undefined && sha256(current) === recorded) {
+            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else if (isReleasedVersion(history, file.rel, current, ctx)) {
+            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else {
+            actions.push({
+                rel: file.rel,
+                verdict: 'conflict',
+                reason: recorded === undefined
+                    ? 'not a version this rig ever released — treated as yours'
+                    : 'edited since it was installed',
+                templatePath: file.source,
+            });
+            // deliberately NOT recorded: the rig does not own these bytes
+        }
+    }
+    // With no manifest, "there is a rig here" has to be *recognised*, not
+    // assumed from a file existing: `CLAUDE.md` and `.claude/settings.json` are
+    // in the install set and in nearly every repository ever opened by an agent.
+    // Recognition means bytes we know — a file already current, or one that
+    // matches a released version. Without that this command would silently
+    // perform an `init` nobody asked for.
+    if (manifest === null &&
+        !actions.some((a) => a.verdict === 'unchanged' || a.verdict === 'update'))
+        throw new UpgradeError(`No rig found in ${repoDir}. Nothing here is recognisable as a create-agent-rig ` +
+            'install — run `create-agent-rig init` to install the process layer, or upgrade ' +
+            'from the directory that holds the rig.');
+    return {
+        kind,
+        fromVersion: manifest?.version ?? null,
+        toVersion: await packageVersion(),
+        bootstrapped: manifest === null,
+        actions,
+        wiring,
+        contents,
+        manifest: {
+            version: await packageVersion(),
+            kind,
+            project,
+            stacks: [...stacks],
+            files: nextFiles,
+        },
+    };
+}
+/**
+ * Write the plan: the `update` and `new` files, then the manifest. Everything
+ * else in the plan is a sentence for a human, not an edit.
+ */
+export async function applyUpgrade(repoDir, plan, options = {}) {
+    const written = [];
+    if (options.dryRun === true)
+        return { written };
+    for (const action of plan.actions) {
+        if (action.verdict !== 'update' && action.verdict !== 'new')
+            continue;
+        const content = plan.contents.get(action.rel);
+        // Never a silent empty file: a missing entry is a defect in the plan, and
+        // truncating somebody's rule file is the worst way to report one.
+        if (content === undefined) {
+            throw new UpgradeError(`Internal: no content planned for "${action.rel}" — nothing written.`);
+        }
+        const dest = onDisk(repoDir, action.rel);
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, content);
+        written.push(action.rel);
+    }
+    await writeManifest(repoDir, plan.manifest);
+    return { written };
+}