create-agent-rig 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,174 @@ 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
+nothing that shipped in 0.3.1 changed shape.
+
+A generated project gains two review gates it did not have — one before the work
+starts, one over the prose that instructs it — and three more queue-hygiene
+checks.
+
+**Upgrading an existing rig: `init` alone is not enough, and here is exactly
+why.** `create-agent-rig init` installs files that are not there and **keeps
+every file that is** — `--force` replaces `CLAUDE.md` and nothing else
+(`packages/cli/src/commands/init.ts`). Re-running it on a 0.3.1 rig therefore
+delivers the two new files, `.claude/agents/prose-reviewer.md` and
+`.claude/skills/check-premises/SKILL.md`, and **none of their wiring**: the
+skill arrives with nothing calling it, and the agent arrives with `pr-ship`
+never launching it. Six files below changed rather than appeared, and `init`
+will not touch them:
+
+```
+.claude/agents/code-reviewer.md          # the sixth blocking item
+.claude/skills/loop/SKILL.md             # calls check-premises, and §3/§6/§8
+.claude/skills/pr-ship/SKILL.md          # fans out prose-reviewer, passes the item
+.claude/scripts/queue/core.mjs           # the three hygiene checks + Ticket.body
+.claude/scripts/detect-missed-gate.mjs   # sees a rulebook outside the repo root
+.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. 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
+
+- **`check-premises` skill** — a queue item is a _claim about the code_, written
+  by someone who was not reading the code at the time, and nothing downstream
+  re-checks it: the failing test is written against the item, the implementation
+  against the test, and the reviewer compares the diff to the item. A false
+  premise therefore produces work that is correct, tested, reviewed and useless.
+  The skill runs between taking the item and the Red step, is read-only by
+  frontmatter so it cannot start implementing, and returns `PREMISES HOLD` /
+  `PREMISE FALSE` / `UNVERIFIABLE`. Its two boundaries are the point: a false
+  load-bearing premise is **stop and report**, never a silent re-aim of the task,
+  and only load-bearing claims are checked — an audit is what makes the step
+  expensive enough to skip. The `loop` skill calls it, and treats `PREMISE FALSE`
+  as a per-task escalation rather than a licence to rewrite the item.
+- **`prose-reviewer` agent** — a fourth gate, read-only. In this layer the prose
+  _is_ the implementation: a rule that overstates its own enforcement fails
+  exactly like broken code, silently and in the direction of false confidence. It
+  blocks on five things — enforcement claimed beyond the mechanism, a dead
+  reference, two rules that contradict each other, stated limits gone stale in
+  either direction, and domain that must not travel (a vendor name, a host path,
+  a tracker key or a credential in a layer meant to be neutral) — and its
+  boundary comes before its checklist: it is **not
+  a literary editor**, and prose that is merely clumsy is not a finding. Wired
+  into the `pr-ship` fan-out and named in both maps.
+- **A sixth blocking item for `code-reviewer`** — a change that contradicts the
+  queue item it claims to implement. The instruction is to report the mismatch,
+  never to decide which side "must have been meant": a reviewer who reconciles
+  the two silently turns a visible mismatch into an invisible one. Where no item
+  was supplied, it says so rather than reconstructing one from the PR body —
+  which is evidence `autonomy.md` refuses by name. `pr-ship` now passes the item.
+- **Three queue-hygiene checks** — a parent that says it was split up and is
+  still open; a dependency line naming a blocker no link carries (worse than a
+  stale label: selection reads the item as unblocked); and a document link that
+  is broken on its face. The neutral `Ticket` shape gains a **nullable `body`**
+  so these live in one pure function instead of once per adapter — and `null`
+  means "this adapter cannot answer", never "checked, found nothing".
+
+### Fixed
+
+- **The baseline commit of a generated project could land in the caller's
+  repository.** Git hands its hooks an absolute `GIT_DIR`, and the CLI spawned
+  git with the environment intact — so `git init` re-initialised the caller's
+  repo, `add -A` staged its tree, and the commit landed on whatever branch it had
+  checked out, while the generated project got no `.git` at all. A redirected
+  `git init` can also flip the caller's repository to `core.bare=true`. The path
+  that triggers it is a pre-commit hook running a suite that generates projects —
+  which is what made the `worktree-task` skill unusable. Every git call site now
+  strips the variables that locate a repository, including the shipped
+  `gate-stop-dod` hook (which asked git whether _which_ tree was clean) and
+  `preflight`.
+- **The Tier-2 gate sweep could not see a rulebook outside the repository root.**
+  `detect-missed-gate` exempts the rulebook from its inert-file rule so a merge
+  rewriting the autonomy tiers cannot pass as "just prose" — but the exemption
+  was anchored at `CLAUDE.md` / `.claude/`. Any project that vendors, templates
+  or nests a rig keeps its rulebook elsewhere, and every `.md` there was dropped
+  before the elevated-path test ran. It is now recognised wherever it sits, and
+  the sweep's verdict vocabulary knows the words `pr-ship` actually emits.
+
+### Deferred, and on what condition
+
+Two pieces of the source brief did **not** travel, because shipping an unproven
+gate into other people's projects is worse than not having one:
+
+- the queue-closing discipline for blocked dependents — enters when it has been
+  merged and used in the project it came from;
+- the clarify-gate (`C-0…C-2`) — enters once that gate has fired at least once
+  anywhere. Until then there is nothing to copy but an intention.
+
 ## 0.3.1
 
 `create-agent-rig init` shipped a rig that looked installed and enforced
@@ -155,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.
@@ -163,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
@@ -83,8 +121,8 @@ never labels**, and **the agent never files its own work items**.
 
 Around all of it: **autonomy tiers** (what an agent does alone / after review /
 never), **stop rules** (three strikes, flaky ≠ retry, session staleness),
-**subagent gates** (`test-writer`, `code-reviewer`, `security-scanner`, and
-`cdk-diff-reviewer` on the AWS target), **skills** (`pr-ship` pre-merge gate;
+**subagent gates** (`test-writer`, `code-reviewer`, `security-scanner`,
+`prose-reviewer`, and `cdk-diff-reviewer` on the AWS target), **skills** (`pr-ship` pre-merge gate;
 `loop` queue driver; `worktree-task` for concurrent sessions; `new-invariant`, a
 generator for the invariant→hook→test pattern; `post-deploy-verify` and
 `ro-debug` on the AWS target), and a one-page `CLAUDE.md` map a fresh session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.3.1",
+  "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,12 +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 {
 }
@@ -35,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.
@@ -60,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
@@ -72,9 +101,10 @@ async function initGitBaseline(projectDir) {
     // .git/objects/pack after we return — a non-deterministic tail that races any
     // caller cleaning up the directory, and pointless work on a one-commit repo.
     const quiet = ['-c', 'gc.auto=0', '-c', 'maintenance.auto=false'];
+    const where = { cwd: projectDir, env: gitEnv() };
     try {
-        await run('git', [...quiet, 'init', '--quiet'], { cwd: projectDir });
-        await run('git', [...quiet, 'add', '-A'], { cwd: projectDir });
+        await run('git', [...quiet, 'init', '--quiet'], where);
+        await run('git', [...quiet, 'add', '-A'], where);
         // Explicit identity: the baseline must commit even where git has no
         // global user configured (fresh machines, CI). --no-verify here shields
         // the baseline from the USER'S global hooks only — the generated
@@ -90,7 +120,7 @@ async function initGitBaseline(projectDir) {
             '--no-verify',
             '-m',
             'Pristine template (create-agent-rig)',
-        ], { cwd: projectDir });
+        ], where);
     }
     catch {
         // git missing or unusable — generation never fails on this.

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);
+}