create-agent-rig 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -11,6 +11,118 @@ Numbering is ordinary semver — **additive is a minor, a fix is a patch** — s
 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.6.0
+
+**The loop now checks its premises against the tracker at three points, and
+the rulebook cannot be edited from an unattended run.** Everything below is what
+a newly scaffolded or `init`ed project receives.
+
+**The released-hash table no longer depends on tags** (AR-35). It is built
+from `templates/release-ledger.json` — the commit each version was published
+from — so it now carries 0.5.0's bytes, 0.4.0's real bytes (the stale `v0.4.0`
+tag is reported and ignored) and a 0.2.0 row; the consequence 0.5.0's notes
+state for a rig upgraded without a readable manifest is closed for every
+release the ledger records. This release itself is excluded, as every release
+being prepared is: commit `.claude/.rig-manifest.json`.
+
+### Added
+
+- **Revalidation at SELECT, BEFORE_PR and BEFORE_CLOSE** (AR-133, AR-134,
+  AR-135, AR-136). `.claude/scripts/revalidate.mjs` compares the item the run
+  took against the tracker's current state — at selection against this run's
+  take-up, before a PR against the item and the default branch, and before a
+  close against the item's fields and its dependants — and every point records
+  one evidence shape in the run directory; `revalidation-report.mjs` reads them
+  back. A close now proves it transitioned rather than reporting the write. The
+  points themselves have one spelling, `.claude/scripts/lib/revalidation-points.mjs`,
+  and the `loop` and `pr-ship` skills are checked against it in both directions
+  (AR-137).
+- **`guard-rulebook`** (AR-51): a `PreToolUse` hook that refuses an edit to the
+  hooks, their wiring, `.claude/queue.json`, the queue adapters, the router, the
+  gate sweep, the rules or `CLAUDE.md` while the unattended flag the `loop` skill
+  writes at claim time is on disk (`.claude/scripts/unattended-flag.mjs`), unless
+  the item's allow-list names the path. Attended sessions are untouched. Its
+  header states its limits, each one under test in the generator.
+- **`doctor`** (AR-5): `node .claude/scripts/doctor.mjs` reads
+  `.claude/.rig-manifest.json` and reports every hook the project owns — bytes
+  that differ from what the generator installed, or no manifest entry — that has
+  no `<hook>.test.mjs` beside it. Exemptions are an explicit list with reasons in
+  `.claude/doctor-exemptions.json`, a file the project writes (none ships); a
+  doctor that looked nowhere never says GO.
+- **Fan-out coverage is checked, not just recorded** (AR-79, AR-118): `pr-ship`
+  compares the reviewers that answered against the route the router gave the
+  head, bound to that head; `docs/decisions/gate-coverage.md` records the shape
+  and the unreadable states.
+- **Queue items carry more of the tracker's meaning into selection:**
+  - an item marked for another repository (`owner-<name>`; `[owner:<name>]` in
+    `PLAN.md`) is held, never taken — a checkout names itself in
+    `options.owner` (AR-132);
+  - the lifecycle vocabulary `keep-core` / `re-scope` / `obsolete` and the
+    `parked` pile are read above the adapter seam, and the loop infers none of
+    it (AR-144);
+  - a proposal the loop files records the commit it was measured against
+    (`asOf`), and `hygiene` reports the one git has overtaken (AR-116); it also
+    names what it measured and what it inferred, and an inference past the
+    measurement is refused at filing (AR-142);
+  - the take-up baseline reaches into earlier runs, so a marker the adapter's
+    own write produced is not read back as a catch (AR-138, AR-140);
+  - `gate-round` refuses to count a round on a checkout that cannot ship, and
+    states the cap as a spent count rather than a convergence verdict (AR-141,
+    AR-115).
+
+### Changed
+
+- **The Jira adapter is harder to knock over** (AR-54): a request timeout that
+  stays armed through the body read, transient retry honouring `Retry-After`
+  (capped at 60 s), cursor pagination with a stated page cap, a priority-id
+  fallback, and a JQL that is always project-qualified — an explicit
+  `options.jql` must begin with `project = <KEY>`.
+- **The adapter contract gained `find` and `listProposals`** (AR-135, AR-116)
+  and the ticket shape gained `updatedAt`, `owner`, `lifecycle` and `parked`.
+  On `jira`, `limit` is now the **page** size, not a result cap.
+- **A close is a close only when the tracker says so** (AR-135): all three
+  adapters read the item back and return `transitioned` from what they read,
+  instead of from the argument they were given or a `gh` exit code.
+- **`gate-stop-dod` measures the project the hook belongs to, not the cwd**, and
+  names the tree in its refusal (AR-119).
+- **`.claude/rules/node-ts.md` names the third state of a PR head** — one that
+  gets no workflow run at all — and says it is retriggered per required check,
+  never merged on an older head's green (AR-149).
+- **The autonomy and invariants rules state the enforcement they have exactly**:
+  `guard-secret-file`'s four blind spots, the unattended flag as what arms
+  `guard-rulebook`, and the unbacked-claim rule with its two exits (delete, or
+  point at the test).
+
+### Fixed
+
+- **`MultiEdit` and `NotebookEdit` reached every content guard and produced no
+  fragment**, so an impure edit to the core through either passed unchecked.
+  `hooks/lib/edit-input.mjs` now yields one fragment per edit for both (AR-51).
+- **`manifest.version` is held to the same value check its siblings get**, and
+  the comment no longer claims a prerelease the rig never wrote (AR-128).
+- **Hooks resolve the project root inside `main()`**, so a throw there announces
+  itself instead of failing open silently (AR-119).
+
+- **The upgrade plan's header told you your rig was old when it could not know
+  that.** It greeted every rig it could not read a manifest for with "no manifest
+  here (a pre-0.4.0 rig)". There are three ways to reach that branch and the
+  claim is false for two of them: a manifest you deleted, and one that is on disk
+  and voided by its own reader — the case 0.5.0's notes below single out. The
+  header now states the condition the code actually has, **no readable manifest
+  here**, and offers the three causes without asserting any of them.
+- **`--no-color` is accepted by `upgrade` and `init`**, not only by the
+  scaffolder. It was advertised under Options without being scoped to one
+  command, and the other two exited 1 with "Unknown option". **Nothing about
+  their output changes** — the CLI builds its palette on the `create` path alone,
+  so neither command had colour to switch off, and neither read `NO_COLOR`
+  either. What changes is that a flag the help offers is no longer a refusal.
+- **The plan's summary now accounts for every action, not four kinds out of
+  six.** It counted files to replace, new files, yours-kept and already-current,
+  while the plan above it also prints a line for a hook wiring hand-over and for
+  a file you removed — so the four buckets could not add up to what was printed.
+  Both are counted now, in the order the plan lists them, and they appear only
+  when they occurred: a plan without them reads exactly as it did.
+
 ## 0.5.0
 
 **Codex is a harness of this rig now, not a thing you adapt it to.** A generated
@@ -506,13 +618,27 @@ sometimes earlier (step 6). Everything before that is mechanical:
    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. `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. ⚠ With no tag cut (step 7), what excludes the
-   shipping version is the absent tag rather than that filter — and the same
-   absence keeps it out of every later table too, which is the cost step 7
-   states.
+4. **Record where the previous release was published from, then regenerate
+   the released-hash table.** `templates/release-ledger.json` maps each released
+   version to the commit it was published from; the entry for the release
+   _before_ this one is written now, because a commit cannot carry its own sha:
+
+   ```sh
+   npm view create-agent-rig@<previous> gitHead   # → the sha for the ledger
+   node scripts/build-hash-history.mjs             # rebuilds the table from it
+   ```
+
+   The builder reads every `## X.Y.Z` this file lists below the version in
+   `package.json` and **refuses, naming the version and that command**, when
+   the ledger has no entry for one — it never drops a release silently, since a
+   dropped release is one `upgrade` can no longer recognise. A value of `null`
+   is the one other answer: the published bytes are not recoverable from git
+   (0.1.0 was published from a commit whose `package.json` already read
+   0.2.0), so that version deliberately gets no row. Pinned in
+   `test/template/hash-history.test.ts` › "throws for a released version the
+   ledger does not mention, naming the version and the npm command" and ›
+   "points at a commit whose package.json carries that version".
+
 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
@@ -521,33 +647,13 @@ sometimes earlier (step 6). Everything before that is mechanical:
    guard that can only fire after the thing it guards has changed has to be run
    after it.
 7. **Tagging is not part of this project's release process** — standing owner
-   decision, recorded at 0.5.0: the owner publishes by hand and does not tag. So
-   this step is deliberately _not_ performed, and the cost is stated here rather
-   than discovered later.
-
-   Step 4 builds the table from `v*` tags, so an untagged release never enters
-   it. That is free for the release being prepared and **not free for the one
-   after it**: step 6 fails as soon as the CHANGELOG lists an untagged release
-   _below_ the version being prepared, and its message says "stale table", which
-   running the builder cannot satisfy. Measured against this repository at
-   0.5.0 preparation: with `0.5.0` untagged, a `0.5.0` bump passes and an
-   `0.6.0` bump fails. The check is
-   `test/template/hash-history.test.ts` › "covers every released version below
-   the one being prepared". **AR-35 carries the fix**, and which shape it takes
-   is that item's to decide, not this note's.
-
-   **What a releaser may do when step 6 fails, stated so it is not inferred:**
-   stop, and land AR-35 first. Cutting the missing tag after the fact is _not_
-   the sanctioned way out — it would put the table's honesty back on a step this
-   process does not perform, which is the whole reason the decision is recorded
-   here.
-
-   If a tag is ever cut anyway, the older warning still applies: check first
-   that it does not exist (`git ls-remote --tags origin`), because a leftover
-   from an abandoned attempt is a published ref, deleting or moving one is an
-   **owner** action, and a tag on the wrong commit makes the next table **name a
-   version whose bytes it does not carry**. `v0.4.0` is in exactly that state —
-   it points at 0.3.2's content.
+   decision, recorded at 0.5.0: the owner publishes by hand and does not tag.
+   Since 0.6.0 (AR-35) that costs nothing: the table is built from the ledger in
+   step 4, not from tags, and a `v*` tag is neither required nor trusted. One
+   that exists and points elsewhere than the ledger — `v0.4.0` does, at 0.3.2's
+   content — is printed as a warning by the builder and changes nothing:
+   `test/template/hash-history.test.ts` › "builds the table from the ledger
+   alone — tags are a warning source, never an input".
 
 8. **Owner:** `npm publish`.
 9. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in

package/README.md

@@ -68,12 +68,13 @@ 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. Releases from 0.5.0 on ship untagged as well, so the table does not
-carry them either: on a rig with no manifest most of their files are reported as yours
-rather than refreshed. This is why committing the manifest is the sentence in
-bold above and not an aside.
+of every release whose published commit is on record (0.2.0 onward — 0.1.0's
+published bytes are not recoverable, and a rig from it reports every file as
+yours) and recognises a file matching one of them. The record is
+`templates/release-ledger.json`, written at the release _after_ the one it
+describes, so the newest release is never in the table a rig installed from it
+carries — one more reason committing the manifest is the sentence in bold above
+and not an aside.
 
 `.claude/settings.json` is replaced only when the manifest's recorded hash
 proves the rig wrote those exact bytes and you have not touched them — the case
@@ -105,6 +106,11 @@ wired by both `.claude/settings.json` and `.codex/hooks.json`:
   environment access, or a non-allowlisted import into the pure domain core;
 - **`guard-web-boundary`** — refuses `db`/service imports from the frontend;
   the web talks to the backend over HTTP only;
+- **`guard-rulebook`** — in an unattended run (a flag file the `loop` skill
+  writes at claim time), refuses an edit to the rulebook — hooks, wiring,
+  `queue.json`, the queue adapters, the router, the gate sweep, the rules,
+  `CLAUDE.md` — outside the current item's allow-list; does nothing in an
+  attended session.
 - **`guard-secret-file`** — refuses an edit that writes a credential: either the
   path names one (`jira.env`, `id_rsa`, anything under `secrets/`) or the text
   carries a credential VALUE. Both arms read one vocabulary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.5.0",
+  "version": "0.6.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/init.js

@@ -179,9 +179,12 @@ export async function initProject(repoDir, options) {
  * it wrote; it does not get to re-describe how the rig was installed.
  *
  * ⚠ **The limit, stated because the fix reads as wider than it is:** this
- * preserves a manifest, so a rig that has none — anything from before 0.4.0 —
- * still gets `kind: 'init'`, no stacks and an empty region, and the advisory in
- * `runInit` stays silent for the same reason. `upgrade`'s `detectInstall`
+ * preserves a manifest, so a rig without a READABLE one still gets
+ * `kind: 'init'`, no stacks and an empty region, and the advisory in `runInit`
+ * stays silent for the same reason. That is three populations, not one: a rig
+ * from before 0.4.0 never had a manifest, a deleted manifest is a documented
+ * recovery step, and one on disk that `parseManifest` voids reads as absent to
+ * `readManifest` alike. `upgrade`'s `detectInstall`
  * recovers all three from the files on disk, so those values are not
  * unavailable, only unavailable *here*: reaching for it would point
  * `commands/init` at `commands/upgrade`, which already imports this module.

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

@@ -189,8 +189,8 @@ export async function planUpgrade(repoDir, options = {}) {
     // The one case where the raw name cannot be kept is a directory the manifest
     // reader would refuse — `My App` produced `{"name":"My App"}`, which
     // `parseManifest` voids, so the manifest this command exists to write was
-    // written and immediately unreadable and every later run reported "no
-    // manifest here (a pre-0.4.0 rig)". The condition is that reader's own
+    // written and immediately unreadable, and every later run fell back to
+    // matching against released versions. The condition is that reader's own
     // exported predicate, not a second copy of its rule.
     //
     // 🔴 All three branches were bought by a defect, and two of those defects

package/packages/cli/dist/index.js

@@ -38,7 +38,13 @@ async function runInit(rawArgs) {
     try {
         ({ values } = parseArgs({
             args: rawArgs,
-            options: { 'dry-run': { type: 'boolean' }, force: { type: 'boolean' } },
+            // `--no-color` for the same reason it is accepted on `upgrade`: USAGE
+            // offers it without scoping it to one command.
+            options: {
+                'dry-run': { type: 'boolean' },
+                force: { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
             allowPositionals: false,
         }));
     }
@@ -54,9 +60,11 @@ async function runInit(rawArgs) {
     // 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.
+    // It is a manifest read, so any rig without a READABLE manifest gets no
+    // advisory even when it came from `create` — one never written, one deleted,
+    // and one present but voided by `parseManifest` all reach here alike. The
+    // same limit `recordInstall` carries, 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` +
@@ -106,7 +114,7 @@ function renderUpgradePlan(repoDir, plan) {
     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`
+            ? `  no readable manifest here (deleted, never written, or unparseable) — matching files against released versions`
             : `  installed by ${plan.fromVersion}`,
         `  upgrading to ${plan.toVersion}`,
         '',
@@ -120,9 +128,29 @@ function renderUpgradePlan(repoDir, plan) {
             }
         }
     }
-    const unchanged = of('unchanged').length;
+    // Every one of `UpgradeVerdict`'s six members is accounted for here.
+    // `wiring` and `deleted` each print their own line and were in none of the
+    // buckets, so a reader counted lines and was told a smaller number.
+    // (`unchanged` is counted and prints nothing — the sum is over actions, not
+    // over printed lines.) The two appear only when they occurred, so a plan
+    // without them renders exactly as it always has. Pinned by, in cli-report.test.ts,
+    // "renders a plan with no wiring action exactly as it does today".
+    // `deleted` before `wiring`, the relative order the plan prints them in.
+    // ⚠ Only their order relative to EACH OTHER matches: the plan prints
+    // `deleted` before `conflict` and the summary prints it after, so this is not
+    // a plan-ordered line. Pinned by, in cli-report.test.ts,
+    // "lists the two occasional buckets in the order the plan prints them".
+    const occasional = [
+        ['deleted', (n) => `${n} you removed (left removed)`],
+        ['wiring', (n) => `${n} wiring handed over`],
+    ];
+    const extra = occasional
+        .map(([verdict, phrase]) => [of(verdict).length, phrase])
+        .filter(([count]) => count > 0)
+        .map(([count, phrase]) => phrase(count));
     lines.push('', `  ${of('update').length} to replace, ${of('new').length} new, ` +
-        `${of('conflict').length} yours (kept), ${unchanged} already current`);
+        `${of('conflict').length} yours (kept), ` +
+        [...extra, `${of('unchanged').length} already current`].join(', '));
     return `${lines.join('\n')}\n`;
 }
 async function runUpgrade(rawArgs) {
@@ -130,7 +158,17 @@ async function runUpgrade(rawArgs) {
     try {
         ({ values } = parseArgs({
             args: rawArgs,
-            options: { 'dry-run': { type: 'boolean' }, yes: { type: 'boolean' } },
+            // `--no-color` is advertised in USAGE without scoping it to one command, so
+            // every command accepts it. Refusing a flag the help offers costs the
+            // reader more than honouring it costs us — and honouring it is only a
+            // parse here, because the sole palette lives on the `create` path below.
+            // Pinned by, in cli-report.test.ts,
+            // "upgrade accepts --no-color and prints plain output".
+            options: {
+                'dry-run': { type: 'boolean' },
+                yes: { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
             allowPositionals: false,
         }));
     }

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

@@ -44,6 +44,16 @@ export function parseManifest(raw) {
     const m = parsed;
     if (typeof m.version !== 'string')
         return null;
+    // The same value check its siblings get (AR-128). `version` is printed raw
+    // in the upgrade plan header — `installed by ${plan.fromVersion}`, the screen
+    // read immediately before `--yes` — so a version carrying a newline or an
+    // ANSI escape could forge plan lines the CLI never composed. A version this
+    // rig writes is the package's own (`0.5.0` today; a prerelease such as
+    // `0.6.0-rc.1` would also pass), which the substitution whitelist admits;
+    // semver build metadata (`+`) is not, and a manifest carrying one is voided
+    // rather than printed — no released version has carried one.
+    if (!isSafeSubstitutionValue(m.version))
+        return null;
     if (m.kind !== 'create' && m.kind !== 'init')
         return null;
     const project = m.project;

package/scripts/prepare.mjs

@@ -36,7 +36,7 @@ export const gitConfigEnv = (env = process.env) => {
 
 function main() {
   // 1. Wire up the pre-commit hook when working inside the git checkout.
-  if (existsSync(path.join(root, '.git'))) {
+  if (!process.env.CI && existsSync(path.join(root, '.git'))) {
     spawnSync('git', ['config', 'core.hooksPath', '.husky'], {
       cwd: root,
       env: gitConfigEnv(),

package/templates/agent-os/init/AGENTS.md

@@ -105,9 +105,9 @@ it a hook via the `new-invariant` skill.
   this repository once it has a remote. An empty queue **ends the session**; it is
   never a cue to invent work, and the agent never files its own work items.
 
-## Three things this install left for you to finish
+## Four things this install left for you to finish
 
-All three are one-liners, and all three are inert until you do them.
+All four are one-liners, and all four are inert until you do them.
 
 1. **The Definition-of-Done gate has nothing to run.** `gate-stop-dod` executes
    the commands listed in `.claude/hooks/dod-checks.json`, and `init` ships no
@@ -130,7 +130,6 @@ All three are one-liners, and all three are inert until you do them.
    # the run journal's per-run trace
    .claude/runs/
    ```
-
    Each comment is on its own line, and that is not formatting: git treats `#`
    as a comment **only at line start**, so a trailing `# …` becomes part of the
    pattern and the line then ignores nothing. It fails silently — you find out
@@ -145,6 +144,15 @@ All three are one-liners, and all three are inert until you do them.
    edited on purpose. `.claude/queue.json` is the opposite: that one is
    configuration and belongs in the repository.
 
+4. **`doctor` reads two files this install does not ship.**
+   `node .claude/scripts/doctor.mjs` decides who owns each hook from
+   `.claude/.rig-manifest.json` — which `init` wrote next to the files it
+   installed, so commit it — and reads exemptions from
+   `.claude/doctor-exemptions.json`, a file you author (`{ "<path>": "<reason>" }`)
+   only when a hook you own is deliberately left without a test neighbour.
+   Without the manifest every hook that has no test neighbour reports `unknown`,
+   which is not a pass.
+
 ## The elevated paths of this project
 
 Tier 2 in `.claude/rules/autonomy.md` names *kinds* of change. This block names

package/templates/agent-os/init/CLAUDE.md

@@ -105,9 +105,9 @@ it a hook via the `new-invariant` skill.
   this repository once it has a remote. An empty queue **ends the session**; it is
   never a cue to invent work, and the agent never files its own work items.
 
-## Three things this install left for you to finish
+## Four things this install left for you to finish
 
-All three are one-liners, and all three are inert until you do them.
+All four are one-liners, and all four are inert until you do them.
 
 1. **The Definition-of-Done gate has nothing to run.** `gate-stop-dod` executes
    the commands listed in `.claude/hooks/dod-checks.json`, and `init` ships no
@@ -130,7 +130,6 @@ All three are one-liners, and all three are inert until you do them.
    # the run journal's per-run trace
    .claude/runs/
    ```
-
    Each comment is on its own line, and that is not formatting: git treats `#`
    as a comment **only at line start**, so a trailing `# …` becomes part of the
    pattern and the line then ignores nothing. It fails silently — you find out
@@ -145,6 +144,15 @@ All three are one-liners, and all three are inert until you do them.
    edited on purpose. `.claude/queue.json` is the opposite: that one is
    configuration and belongs in the repository.
 
+4. **`doctor` reads two files this install does not ship.**
+   `node .claude/scripts/doctor.mjs` decides who owns each hook from
+   `.claude/.rig-manifest.json` — which `init` wrote next to the files it
+   installed, so commit it — and reads exemptions from
+   `.claude/doctor-exemptions.json`, a file you author (`{ "<path>": "<reason>" }`)
+   only when a hook you own is deliberately left without a test neighbour.
+   Without the manifest every hook that has no test neighbour reports `unknown`,
+   which is not a pass.
+
 ## The elevated paths of this project
 
 Tier 2 in `.claude/rules/autonomy.md` names *kinds* of change. This block names

package/templates/agent-os/stack/aws-cdk/.agents/skills/post-deploy-verify/SKILL.md

@@ -74,7 +74,8 @@ the next selection reads the verdict.
     }
   ],
   "advisories": [],
-  "evidence": ["stack LastUpdatedTime is this deploy", "DLQ depth 0"]
+  "evidence": ["stack LastUpdatedTime is this deploy", "DLQ depth 0"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -88,6 +89,12 @@ the next selection reads the verdict.
   deploy runs `node .claude/scripts/verdict.mjs check <report>
   post-deploy-verify` before it retypes the word into `run-state.mjs`. This
   skill runs nothing — it is read-only by construction.
+- **`headSha` is the commit that was deployed** — `git rev-parse HEAD` in the
+  checkout the deploy went out from. ⚠ **Nothing reads it yet**: `run-state.mjs`
+  stores the word alone, so the commit lives in this block and nowhere else.
+  Write it anyway — the pairing is what a later reader needs to tell a stale
+  `HEALTHY` from a current one, and `HEALTHY` is the only thing that clears the
+  `REGRESSION` latch the next selection reads.
 
 ## Boundaries
 

package/templates/agent-os/stack/aws-cdk/.claude/agents/cdk-diff-reviewer.md

@@ -67,7 +67,8 @@ nothing after it. It is what the calling gate reads.
     }
   ],
   "advisories": [],
-  "evidence": ["cdk diff against the deployed stage"]
+  "evidence": ["cdk diff against the deployed stage"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -78,3 +79,9 @@ nothing after it. It is what the calling gate reads.
 - A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:
   `node .claude/scripts/verdict.mjs check <report> cdk-diff-reviewer` is what
   refuses them.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

package/templates/agent-os/stack/aws-cdk/.claude/skills/post-deploy-verify/SKILL.md

@@ -74,7 +74,8 @@ the next selection reads the verdict.
     }
   ],
   "advisories": [],
-  "evidence": ["stack LastUpdatedTime is this deploy", "DLQ depth 0"]
+  "evidence": ["stack LastUpdatedTime is this deploy", "DLQ depth 0"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -88,6 +89,12 @@ the next selection reads the verdict.
   deploy runs `node .claude/scripts/verdict.mjs check <report>
   post-deploy-verify` before it retypes the word into `run-state.mjs`. This
   skill runs nothing — it is read-only by construction.
+- **`headSha` is the commit that was deployed** — `git rev-parse HEAD` in the
+  checkout the deploy went out from. ⚠ **Nothing reads it yet**: `run-state.mjs`
+  stores the word alone, so the commit lives in this block and nowhere else.
+  Write it anyway — the pairing is what a later reader needs to tell a stale
+  `HEALTHY` from a current one, and `HEALTHY` is the only thing that clears the
+  `REGRESSION` latch the next selection reads.
 
 ## Boundaries
 

package/templates/agent-os/stack/aws-cdk/.codex/agents/cdk-diff-reviewer.toml

@@ -1,4 +1,4 @@
 name = "cdk-diff-reviewer"
 description = "Reviews an infrastructure change via `cdk diff` BEFORE any deploy. MUST run on every change under infra/ — a deploy without this review is a Never-tier action. Read-only; findings gate the deploy."
 sandbox_mode = "read-only"
-developer_instructions = "You review what a deploy would actually do to running infrastructure. Your\ninput is the change under `infra/` **and** the synthesized diff (`cdk diff`,\nrun it yourself); your output is a verdict. You never fix and never deploy.\n\n## How you work\n\n1. Run `cdk diff` (and read the changed `infra/` sources for intent). The diff\n   is the truth: review what CloudFormation will do, not what the TypeScript\n   looks like it does.\n2. Walk every resource change and flag it **by named rule** (below). Findings\n   come as **BLOCKERS first, then nits** — one list each, with the resource\n   and the rule it violates.\n3. Your message IS the review, not a summary of it: every finding carries the\n   resource, the change, the rule, and the smallest fix. End with the verdict\n   block below — `SHIP` where `DEPLOY: OK` used to be, `HOLD` where\n   `DEPLOY: BLOCKED` did.\n\n## Named rules — blockers\n\n- **IAM broadening.** Any policy gaining actions, resources widening to `*`,\n  or a grant that outruns what a usecase does today. Least privilege is added\n  in the same PR as the need, never \"for later\".\n- **Data loss paths.** A stateful resource (table, bucket, queue) being\n  replaced, deleted, or flipping its RemovalPolicy toward DESTROY.\n  Logical-id renames on stateful resources are replacements in disguise.\n- **Safety-net removal.** A DLQ detached, an alarm deleted or loosened, a\n  retry budget widened to infinity, a dead-letter retention shortened.\n- **Blast-radius growth.** New public surface (endpoints, permissions to\n  external principals), broadened network access, cross-stack exports that\n  make future changes harder to reverse.\n- **Cost-relevant flips.** On-demand → provisioned capacity, log retention to\n  \"forever\", memory/timeout jumps with no stated reason.\n\n## Nits (report, do not block)\n\nNaming drift, missing descriptions, constructs that could use the narrower\ngrant helper, duplication between stacks.\n\n## Boundaries\n\n- Read-only: you run `cdk diff` and read code; you never run `cdk deploy`,\n  never edit files, never mutate AWS state.\n- An empty diff is a real finding too — say \"no infrastructure change\" and\n  return `SHIP`, so the gate leaves a trace either way.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. It is what the calling gate reads.\n\n```json\n{\n  \"gate\": \"cdk-diff-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"infra/lib/api-stack.ts\",\n      \"line\": 88,\n      \"rule\": \"data loss\",\n      \"note\": \"the table's RemovalPolicy went to DESTROY — replacement drops it\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"cdk diff against the deployed stage\"]\n}\n```\n\n- `verdict` is `SHIP` (nothing blocking, including an empty diff), `HOLD`, or\n  `NOT_APPLICABLE` when the change touches no infrastructure at all.\n- Every blocker names the `rule` it violates, with `file` and `line` when it has\n  a location and neither when it does not.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> cdk-diff-reviewer` is what\n  refuses them."
+developer_instructions = "You review what a deploy would actually do to running infrastructure. Your\ninput is the change under `infra/` **and** the synthesized diff (`cdk diff`,\nrun it yourself); your output is a verdict. You never fix and never deploy.\n\n## How you work\n\n1. Run `cdk diff` (and read the changed `infra/` sources for intent). The diff\n   is the truth: review what CloudFormation will do, not what the TypeScript\n   looks like it does.\n2. Walk every resource change and flag it **by named rule** (below). Findings\n   come as **BLOCKERS first, then nits** — one list each, with the resource\n   and the rule it violates.\n3. Your message IS the review, not a summary of it: every finding carries the\n   resource, the change, the rule, and the smallest fix. End with the verdict\n   block below — `SHIP` where `DEPLOY: OK` used to be, `HOLD` where\n   `DEPLOY: BLOCKED` did.\n\n## Named rules — blockers\n\n- **IAM broadening.** Any policy gaining actions, resources widening to `*`,\n  or a grant that outruns what a usecase does today. Least privilege is added\n  in the same PR as the need, never \"for later\".\n- **Data loss paths.** A stateful resource (table, bucket, queue) being\n  replaced, deleted, or flipping its RemovalPolicy toward DESTROY.\n  Logical-id renames on stateful resources are replacements in disguise.\n- **Safety-net removal.** A DLQ detached, an alarm deleted or loosened, a\n  retry budget widened to infinity, a dead-letter retention shortened.\n- **Blast-radius growth.** New public surface (endpoints, permissions to\n  external principals), broadened network access, cross-stack exports that\n  make future changes harder to reverse.\n- **Cost-relevant flips.** On-demand → provisioned capacity, log retention to\n  \"forever\", memory/timeout jumps with no stated reason.\n\n## Nits (report, do not block)\n\nNaming drift, missing descriptions, constructs that could use the narrower\ngrant helper, duplication between stacks.\n\n## Boundaries\n\n- Read-only: you run `cdk diff` and read code; you never run `cdk deploy`,\n  never edit files, never mutate AWS state.\n- An empty diff is a real finding too — say \"no infrastructure change\" and\n  return `SHIP`, so the gate leaves a trace either way.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. It is what the calling gate reads.\n\n```json\n{\n  \"gate\": \"cdk-diff-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"infra/lib/api-stack.ts\",\n      \"line\": 88,\n      \"rule\": \"data loss\",\n      \"note\": \"the table's RemovalPolicy went to DESTROY — replacement drops it\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"cdk diff against the deployed stage\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP` (nothing blocking, including an empty diff), `HOLD`, or\n  `NOT_APPLICABLE` when the change touches no infrastructure at all.\n- Every blocker names the `rule` it violates, with `file` and `line` when it has\n  a location and neither when it does not.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> cdk-diff-reviewer` is what\n  refuses them.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."

package/templates/agent-os/stack/node-ts/.claude/rules/node-ts.md

@@ -55,3 +55,32 @@ gh api "repos/{owner}/{repo}/commits/$SHA/check-runs" \
 # must print: success   (a result set containing only a scanner is NOT done)
 ```
 
+**A head that gets no run at all is a third state, not a slow one.** A
+`pull_request` push can register no workflow run and emit no failure signal —
+the head sits with a scanner only, and the poll above waits forever while the
+previous head's green sits one line up in the same PR (AR-149: `69b5d65` on
+#130 got no `ci` run; `8ca26e7` on #134 got `ci` and no `e2e`). Tell "not
+registered" apart from "pending" by asking for runs by head, not by PR:
+
+```sh
+gh api "repos/{owner}/{repo}/actions/runs?head_sha=$SHA" \
+  -q '.workflow_runs[] | "\(.name) \(.event) \(.status) \(.conclusion)"'
+# one line per workflow that ran for THIS sha; a required workflow missing
+# here after a bounded wait (a few minutes) is not registered, not pending
+```
+
+⚠ The names differ in case between the two queries: `workflow_runs[].name`
+is the **workflow** name (`CI`, `E2E`), the check-runs filter above reads the
+**job** name (`ci`, `e2e`). Searching the runs list for `ci` finds nothing.
+
+Then the rule, **per required check by name**, never per head: a check with
+no run after the wait is **retriggered**, and the PR is **never merged on an
+older head's green**. The retrigger depends on the workflow — `ci.yml` has no
+`workflow_dispatch`, so an empty commit (`git commit --allow-empty`) is the
+simplest trigger it has; `e2e.yml` has one, so
+`gh workflow run e2e.yml --ref <branch>` re-runs it on the same head. Pinned
+in the generator's `test/template/pr-flow.test.ts` — absent in a generated
+rig — › "node-ts names the head that gets no run at all, and says it is
+retriggered rather than waited on" and › "the no-run branch is stated per
+required check, not per head".
+

package/templates/agent-os/universal/.agents/skills/check-premises/SKILL.md

@@ -173,7 +173,8 @@ inside the block; both forms are the contract.
     }
   ],
   "advisories": [],
-  "evidence": ["read the validator and both call sites"]
+  "evidence": ["read the validator and both call sites"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -187,6 +188,8 @@ inside the block; both forms are the contract.
   and the caller is what checks: the `loop` skill runs
   `node .claude/scripts/verdict.mjs check <report> check-premises` on what you
   return. Nothing in this skill runs it — this skill writes nothing at all.
+- **`headSha` is the commit you read** — `git rev-parse HEAD` in the checkout
+  you examined. A premise check answers about a tree, and the tree moves.
 
 ## Examples — the three shapes this actually catches