create-agent-rig 0.9.1 → 0.10.0

package/templates/agent-os/universal/docs/decisions/agents-md-canonical.md

@@ -0,0 +1,313 @@
+# AGENTS.md is canonical; CLAUDE.md is a shim
+
+The rule lives in `AGENTS.md`, under "One operating system, two harnesses".
+This file explains the model behind it, what is and is not claimed about
+Claude Code's own `AGENTS.md` support, and what an existing rig's upgrade does
+with a `CLAUDE.md`/`AGENTS.md` pair it already has (RP-186).
+
+## The model
+
+Before this change, `templates/agent-os/universal/CLAUDE.md` was the authored
+source and `AGENTS.md` was a byte-identical Codex-facing projection of it,
+mechanically generated by `scripts/sync-codex-adapter.mjs`. That inverted the
+provider-neutral framing the rest of this rulebook states everywhere else:
+the rules are not Claude Code's, and authoring them under a Claude-Code-named
+file made `AGENTS.md` — a name several tools other than Claude Code already
+read — the copy.
+
+`AGENTS.md` is now the canonical, provider-neutral source: the full rulebook
+text lives there, once, and the generator authors it in that file directly.
+`CLAUDE.md` is a short compatibility shim: a Claude Code `@AGENTS.md` import
+(see "Claude Code's own import syntax" below) plus anything genuinely
+specific to Claude Code — nothing that duplicates the rulebook. Neither file
+is generated from the other any more; both are authored tree files under
+`templates/agent-os/universal/`, and `scripts/sync-agent-os.mjs` composes each
+one (elevated paths and this repository's addendum go into `AGENTS.md` only)
+independently.
+
+## What is claimed about Claude Code reading AGENTS.md — and what is not
+
+**Verified against Anthropic's Claude Code documentation** (`docs.claude.com`
+→ `code.claude.com/docs/en/memory`, "AGENTS.md" section, read 2026-09-20):
+
+- Claude Code can read a repository's `AGENTS.md` directly, without a
+  `CLAUDE.md`, starting with Claude Code v2.1.277.
+- That support is conditional, not universal. Paraphrased from the docs (this
+  rulebook names no cloud provider — `test/template/composition.test.ts`):
+  in some sessions, such as ones on certain third-party model-hosting
+  providers or with telemetry disabled, Claude Code cannot read `AGENTS.md`
+  at all — and separately, whenever a `CLAUDE.md`
+  (or a same-named file nested under a project's `.claude` directory, or
+  `CLAUDE.local.md`) exists anywhere in the working directory or above it,
+  Claude Code reads that file **instead of** `AGENTS.md` by default (the
+  `claude-md-or-agents-md` project-instructions setting, the default).
+- The documented remedy for exactly this situation is the pattern this
+  project ships: *"When Claude isn't reading your AGENTS.md directly, you can
+  still keep it as the one file every tool shares by putting an `@AGENTS.md`
+  import in a CLAUDE.md next to it… Add any Claude-specific instructions
+  below the import, and Claude reads the imported file first, then the
+  rest"* — with the worked example:
+
+  ```markdown
+  @AGENTS.md
+
+  ## Claude Code
+
+  Use plan mode for changes under `src/billing/`.
+  ```
+
+  This project's `CLAUDE.md` template follows that exact shape.
+
+**What this project does NOT claim**, stated because the shim's own text and
+this record both have to survive a reader who takes them literally:
+
+- It does **not** claim Claude Code always reads `AGENTS.md` on its own. It
+  might, depending on version and configuration — the shim exists precisely
+  for the sessions and configurations where it does not, and costs nothing
+  when it does (the docs state the import is never read twice).
+- It does **not** claim `AGENTS.md` appears in `/memory` or `/context` when
+  Claude reads it directly through the setting — the docs say it does not,
+  and point at the `AGENTS.md loaded` session-start line instead.
+- The `@AGENTS.md` import syntax itself: relative and absolute paths are both
+  allowed, imports are expanded at launch, and recursive imports are capped
+  at four hops — none of which this project's shim relies on beyond the one,
+  first-line import.
+
+## The migration (RP-186)
+
+A rig installed before this change has a `CLAUDE.md`/`AGENTS.md` pair that is
+byte-identical and recorded as such in its manifest (`.claude/.rig-manifest.json`
+— see `packages/cli/src/lib/manifest.ts`). Both files are ordinary
+manifest-tracked paths (`MAPS` in `packages/cli/src/commands/init.ts`), so
+`upgrade`/`uninstall` need no special-cased migration logic for the
+*ordinary* per-file cases — the same hash-based verdict machinery that
+decides `update` / `conflict` / `deleted` for every other tracked file
+governs both, independently. One coupling IS special-cased: CLAUDE.md's own
+verdict is never allowed to become `update` — writing the `@AGENTS.md`
+shim — while the on-disk AGENTS.md cannot actually SERVE as the rulebook.
+
+**Round 5 design ruling (replacing round 4's verdict-only rule, gate cycle 4
+blocker 1): the hold condition is CONTENT, not verdict.** CLAUDE.md is held
+back only when AGENTS.md is absent (`deleted`), or present but not a
+readable rulebook — no fenced ` ```elevated-paths ` block at all, or one
+that parses to nothing once comments and blank lines are stripped (see
+`packages/cli/src/lib/elevated-paths.ts`'s `isReadableRulebook`, mirroring
+the gate sweep's own `parseElevatedPaths` in
+`templates/agent-os/universal/.claude/scripts/detect-missed-gate.mjs` — a
+script that ships only with the opt-in workflow layer, so this Core rule is
+implemented independently of it rather than importing it — kept in step by a
+correspondence test). An AGENTS.md the user CUSTOMISED but that
+still carries a non-empty `elevated-paths` block lets the shim through — the
+shim then imports the user's own rulebook, which is the point of it — and
+AGENTS.md itself stays a perfectly ordinary, QUIET `conflict`: the same
+`edited since it was installed` line every other kept file gets, no rescue
+file, no special wording anywhere. This matters because a customised
+AGENTS.md is not a broken rulebook — it is this project's own SHIPPED,
+DESIGNED steady state: `AGENTS.md` itself tells every project to extend its
+`elevated-paths` block for its own paths. Round 4's rule kept AGENTS.md's
+own *verdict* (`conflict` or `deleted`) as the trigger, which made every
+customisation indistinguishable from a genuinely broken rulebook — measured
+directly against the real pre-RP-186 payload with one added path line: every
+`upgrade` said "the migration is NOT finished", wrote a rescue file that
+carried NONE of the user's own lines, and closed on `mv AGENTS.md.rig-new
+AGENTS.md` — following it would have deleted user-authored rulebook content,
+and merging into it and `mv`-ing looped forever.
+
+When genuinely held back, `upgrade` keeps CLAUDE.md as its current bytes,
+verdict `conflict`, with a reason naming AGENTS.md's own state and pointing
+at the rescue-file section below for the exact remedy (round 5, blocker 2:
+the reason text never hardcodes `mv` — the actual remedy depends on the
+rescue file's own status, decided separately, and a fixed `mv` promise here
+survived even the case where `mv` would be wrong).
+
+**Held back re-vouches, and that has an `uninstall` consequence (PR #241
+round 3, blocker 2; measured correct in round 4).** Holding CLAUDE.md back
+does not merely skip writing it — it also records `sha256` of its CURRENT
+bytes into the next manifest (`nextFiles['CLAUDE.md']`), the same way an
+ordinary `update` would record the new bytes. This is deliberate (see "The
+remedy" below: it is what lets a LATER `upgrade` resolve cleanly instead of
+falling through to "not a version this rig ever released" forever) — but it
+means `uninstall`, which reads `manifest.files` exactly like every other
+rig-owned path, now sees a held-back CLAUDE.md as rig-owned and unedited
+since, and **removes it**, precisely as it would any other untouched file.
+It does not "leave it in place" the way a genuine `conflict` (bytes the
+manifest never vouched for) does. Pinned by `packages/cli/test/upgrade.test.ts`'s
+test "uninstall removes a held-back CLAUDE.md — the re-vouch makes it
+rig-owned again" (absent in a generated rig — `packages/cli/test/` ships no
+test into the payload, so a mention of it is not a citation this rulebook's
+own checker, `evidence-pointers.test.ts`, examines: it reads `test/` and
+`templates/agent-os/`, never `packages/`).
+
+**Round 4, blocker 2 (CLI-UX): that removal is now disclosed, not silent.**
+Removing CLAUDE.md while AGENTS.md is not a clean removal (preserved as
+edited, or already gone) — or the other way around — is exactly the moment
+the rulebook could end up with no readable copy left at all, and a bare
+`- CLAUDE.md` line did not say so. `UninstallAction` now carries an optional
+`note` (distinct from `reason`, which stays `preserved`-only) for this one
+case, set at PLAN time so `--dry-run` and a real run print it identically,
+and carried in `--json` as a `notes` array alongside `preserved`. Pinned by
+`packages/cli/test/uninstall.test.ts`'s tests "discloses that removing
+CLAUDE.md leaves AGENTS.md, preserved as edited, as the only rulebook copy",
+"discloses the same thing in the opposite direction when AGENTS.md is the
+one being removed", "discloses when the sibling is already gone (absent),
+not only when it is preserved as edited", "adds no note when both are a
+clean removal", and "the disclosure is identical on --dry-run and a real
+run — set at plan time, never at apply time" (absent in a generated rig,
+same reason as above).
+
+| Case | Upgrade outcome | Uninstall outcome |
+| --- | --- | --- |
+| Both untouched since install | Both `update`: `CLAUDE.md` becomes the shim, `AGENTS.md` becomes canonical | Both removed (rig-owned, unedited); no `note` — a clean removal on both sides |
+| `CLAUDE.md` edited by the user, AGENTS.md untouched | `conflict`: kept exactly as the user left it, never force-shimmed; if the edited content is not already the `@AGENTS.md` shim, the reason also says it shadows AGENTS.md (Claude Code reads CLAUDE.md instead, by default) and names the fix; AGENTS.md upgrades independently | `CLAUDE.md` left in place — its own `conflict` verdict is never recorded in `manifest.files` (`upgrade.ts`, the per-file loop's `conflict` branch: "deliberately NOT recorded in `files`"), so `planUninstall` gives it no action at all; it is simply never touched. AGENTS.md removed WITH a `note`, measured verbatim: `this is the rig's own AGENTS.md — removing it leaves CLAUDE.md, which exists and is yours (untracked by this rig), as the only rulebook copy` — the untracked-but-present sibling wording, pinned by `packages/cli/test/uninstall.test.ts`'s test "when CLAUDE.md is the untracked sibling after a real upgrade dropped its conflict verdict from the manifest, the AGENTS.md removal note says it EXISTS — never "absent" (mirror direction)" (absent in a generated rig, same reason as above) |
+| `AGENTS.md` **customised WITH a readable `elevated-paths` block**, CLAUDE.md untouched (round 5's central case — the shipped rulebook's own designed steady state) | AGENTS.md `conflict`, perfectly QUIET — the ordinary `edited since it was installed` line, nothing else. CLAUDE.md is **NOT held back**: verdict `update`, the shim IS adopted, and it imports the user's own customised rulebook | CLAUDE.md removed WITH a `note` (never held back, so never re-vouched — same as any ordinary untouched shim), measured verbatim: `this is the rig's own CLAUDE.md — removing it leaves AGENTS.md, which exists and is yours (untracked by this rig), as the only rulebook copy` — pinned by `packages/cli/test/uninstall.test.ts`'s test "when the sibling is untracked by the manifest (present on disk, never recorded), says it EXISTS — never "absent"" (absent in a generated rig, same reason as above). AGENTS.md itself is left in place — an ordinary, untracked `conflict`, never an uninstall action at all |
+| `AGENTS.md` edited WITHOUT a readable `elevated-paths` block (no block at all, or one that parses to nothing), CLAUDE.md untouched | AGENTS.md `conflict`: kept exactly as the user left it, never overwritten with the canonical text. CLAUDE.md is **held back**: verdict `conflict` (not `update`), kept as its current (old, still-readable) bytes, never written as the shim | AGENTS.md left in place — untracked `conflict`, no uninstall action. **CLAUDE.md is REMOVED** — the hold re-vouches it, so it reads as rig-owned and unedited — WITH a `note`, measured verbatim: `this is the rig's own CLAUDE.md — removing it leaves AGENTS.md, which exists and is yours (untracked by this rig), as the only rulebook copy` — pinned by `packages/cli/test/uninstall.test.ts`'s test "when the sibling is untracked by the manifest (present on disk, never recorded), says it EXISTS — never "absent"" (absent in a generated rig, same reason as above) |
+| `AGENTS.md` deleted by the user, CLAUDE.md untouched | AGENTS.md `deleted`: stays deleted. CLAUDE.md is **held back** the same way, for the same reason (there is no rulebook file at all otherwise) | AGENTS.md stays absent — a genuinely absent path the manifest still records a hash for (`upgrade.ts`'s `deleted` branch keeps `nextFiles['AGENTS.md']` pointing at the recognised, pre-deletion hash, so it stays a manifest-tracked path rather than dropping out the way an ordinary `conflict` does); the `upgrade` REPORT — not the manifest — is what labels it `you removed (left removed)`, in its own summary line (`index.ts`). **CLAUDE.md is REMOVED**, for the same re-vouching reason as the row above — WITH a `note`, measured verbatim: `this is the rig's own CLAUDE.md — removing it leaves AGENTS.md, which is already gone, as the only rulebook copy` — the genuinely-absent sibling wording, pinned by `packages/cli/test/uninstall.test.ts`'s test "discloses when the sibling is already gone (absent), not only when it is preserved as edited" (absent in a generated rig, same reason as above) |
+| `CLAUDE.md` deleted by the user | `deleted`: stays deleted, never restored as the new shim; unaffected by AGENTS.md's own state | already absent |
+| `AGENTS.md` deleted by the user, CLAUDE.md deleted too | Both `deleted`: stays deleted on both sides — there is nothing left to hold back | already absent |
+| The migration already finished (CLAUDE.md is already the shim), THEN AGENTS.md is deleted on a later run | AGENTS.md `deleted`: stays deleted. CLAUDE.md's own verdict is `unchanged` — the held-back coupling above only overrides a verdict that would otherwise become `update`, and an already-adopted shim's verdict never is, so it is left exactly as it is rather than resurrected, rewritten, or held back a second time | CLAUDE.md (the shim) removed like any other untouched file — WITH a `note`, measured verbatim: `this is the rig's own CLAUDE.md — removing it leaves AGENTS.md, which is already gone, as the only rulebook copy` — pinned by `packages/cli/test/uninstall.test.ts`'s test "discloses when the sibling is already gone (absent), not only when it is preserved as edited" (absent in a generated rig, same reason as above); AGENTS.md already absent. Upgrade side pinned by `packages/cli/test/upgrade.test.ts`'s test "AGENTS.md deleted after the migration already finished: the already-adopted shim is left exactly alone" (absent in a generated rig, same reason as above) |
+| A repo that had its own `CLAUDE.md` (or `AGENTS.md`) before `init` | `init` **refuses outright** (`InitError`, non-zero exit) rather than installing over it or recording it as `kept` — `MAPS` files are the one install-time exception to the generic "kept" path every other pre-existing process file gets. Pinned by `packages/cli/test/init.test.ts`'s tests "refuses to clobber an existing CLAUDE.md unless forced" and "refuses to clobber an existing AGENTS.md" — named by full path deliberately: `test/e2e/init.test.ts` (a different suite) shares the bare basename `init.test.ts`, and either mention is absent in a generated rig for the same reason as above regardless | N/A — `init` never installed here, so there is nothing for `uninstall` to have owned |
+
+The round-5 rule was re-derived and pinned as a 4×3 grid — AGENTS.md's axis
+split into `pristine` / `edited-with-block` / `edited-without-block` /
+`deleted`, crossed with CLAUDE.md's `pristine` / `edited` / `deleted` — each
+cell's expected verdicts and hold-back flag hand-derived from the rule
+itself, never copied from `upgrade.ts`'s own branching, by
+`packages/cli/test/upgrade.test.ts`'s parametrised test "AGENTS.md %s ×
+CLAUDE.md %s" and its own central case "AGENTS.md customised WITH a readable
+elevated-paths block: the shim is adopted, not held back, and no rescue file
+appears" (absent in a generated rig, same reason as above). Verified AT THE
+CLI BOUNDARY against a customised, still-readable AGENTS.md by
+`packages/cli/test/cli-report.test.ts`'s test "fresh init, then a path line
+added to elevated-paths: upgrade --yes is silent about it, exit 0, AGENTS.md
+unchanged" (same absence), and against the real pre-RP-186 payload by
+`test/e2e/agents-md-migration.test.ts` (absent in a generated rig) › "a
+legacy rig whose AGENTS.md was customised (still a readable rulebook) before
+upgrading: the shim is adopted in one run, and a second run is a no-op".
+
+Round 4, blocker 1's rescue file (below) is invisible to the table above — it
+is never a manifest-tracked path — so `uninstall` treats it out of band: a
+byte-identical copy of what THIS release would render right now is
+`remove`d like any other untouched file; anything else is the user's,
+`preserved`. Pinned by `packages/cli/test/uninstall.test.ts`'s tests "treats
+a byte-identical rescue file as removable" and "leaves a differing rescue
+file alone, reported as preserved — not this release's own bytes" (absent
+in a generated rig, same reason as above).
+
+## The remedy that actually works — measured, not assumed (PR #241 rounds 3–5)
+
+AGENTS.md's own conflict names a fix, but three readings of it do not work,
+and this project measured each rather than asserting any of them:
+
+- **Copying the file the conflict's own `new version:` line points at.**
+  That path is the RAW template — still carrying the unsubstituted
+  per-project placeholder (`substituteContent` replaces it by exact match;
+  see `packages/cli/src/lib/substitute.ts` — spelled out here would itself
+  be substituted away by this repo's own dogfood sync, which is exactly why
+  it is not), because templates are substituted at install/upgrade time,
+  not at rest. Pasting it verbatim gives Claude Code the wrong project name.
+  (Round 5: the raw template DOES still carry a real, non-empty
+  `elevated-paths` block, so under the content-based hold rule it no longer
+  latches the hold the way it used to — but it is still the wrong remedy,
+  since it hands the project the wrong name throughout its own rulebook.)
+- **Restoring "the exact bytes the rig installed".** Once AGENTS.md is
+  already a conflict, the manifest no longer records what those bytes were
+  (the generic rule: "a conflict is not recorded" — deliberately unchanged
+  by this ticket, see the top of this section) — there is nothing left on
+  disk or in the manifest to restore TO, and this record makes no claim
+  about whether any specific past release's bytes would be recognised
+  another way (that would need its own test, not an assertion here).
+- **Round 3's own remedy: printing the rendered content to stdout for a
+  verbatim paste.** Gate cycle 3 measured this directly, with the built CLI,
+  and it does not work either: pasting the block verbatim, or de-indented,
+  left AGENTS.md at `conflict` and CLAUDE.md held back regardless — nothing
+  about a terminal's own line-wrapping and a human's own copy-paste survives
+  byte-for-byte reliably enough for `planUpgrade`'s exact-bytes comparison.
+  The dump was also ~270 lines sitting between the plan and the consent
+  prompt, scrolling the actionable lines off screen, and the run ended on
+  "Wrote N files." even while CLAUDE.md stayed held back — a bare success
+  line over an unfinished migration.
+- **Round 4's own remedy: a rescue file keyed on AGENTS.md's verdict alone.**
+  Gate cycle 4 measured this against the real pre-RP-186 payload and found
+  it did the wrong thing for the project's own designed steady state (a
+  customised, still-readable AGENTS.md) — see "Round 5 design ruling" above
+  — and, separately, that its `differs` case still closed on `mv`: pasting a
+  hostile or merely stale pre-existing rescue file over AGENTS.md as if this
+  run had written or verified it.
+
+**The fix that is always reachable, with no dependency on release history,
+a terminal, or a human's paste at all — and that only ever appears in the
+GENUINELY held-back state (round 5):** `create-agent-rig upgrade` WRITES the
+already-rendered (substituted) content for AGENTS.md — the same bytes
+`UpgradePlan.contents` carries — to a real sibling file, `AGENTS_MD_RESCUE`
+(`AGENTS.md.rig-new`, `packages/cli/src/commands/upgrade.ts`), through the
+same symlink-refusing write path (`resolveWritableInside`) every other file
+in the plan goes through. It is never recorded in the manifest. The rescue
+file's status is decided ENTIRELY AT PLAN TIME (round 5, blocker 3) —
+`would-write` | `identical` | `differs` | `unsafe` — so a dry run and a real
+run report the identical status, and `applyUpgrade` refuses `unsafe`
+(a symlink, a directory, or similar sitting at the path) BEFORE touching
+anything else at all, including the ordinary payload writes and the
+manifest — closing gate cycle 4's own finding that a symlinked rescue file
+used to leave other files rewritten and the manifest stale, and that a
+directory there crashed with an uncaught `EISDIR`.
+
+The closing instruction is printed as a short, delimited block, LAST, after
+the plan, after any wiring hand-over, after "Wrote N files." — the previous
+remedy's placement between the plan and the consent prompt is exactly why
+cycle 3 found "Wrote N files." reading as success while the migration was
+not finished. **`mv` is printed ONLY for `would-write` and `identical`** —
+bytes this run either just wrote or independently verified byte-identical to
+its own rendering. **For `differs`, the remedy is `rm` (or restoring
+AGENTS.md some other way), never `mv`** (round 5, blocker 2: printing `mv`
+there installs bytes this run never wrote or verified as the live rulebook
+the moment the instruction is followed literally). A leftover, byte-identical
+rescue file is cleaned up once AGENTS.md resolves and the rig is NOT held
+back; unrelated clutter at the path (a stray directory or symlink) on an
+otherwise healthy rig is never touched and never even mentioned (round 5,
+blocker 3's own "must not affect upgrade at all").
+
+Verified AT THE CLI BOUNDARY — the spawned, built binary, never
+`plan.contents` as the oracle for "the bytes are right" (that circularity was
+cycle 3's finding about round 3's own test) — by
+`packages/cli/test/cli-report.test.ts`'s describe block "AGENTS.md.rig-new —
+the CLI-boundary remedy for a GENUINELY held-back AGENTS.md", including "the
+rescue file is byte-identical to an independently-rendered AGENTS.md for the
+same project — not `plan.contents`" (the independent oracle is a SEPARATE
+`initProject` call, forced to the same project name), "never overwrites a
+pre-existing AGENTS.md.rig-new that differs from the rendered bytes, and
+NEVER prints `mv` for it", "a symlinked AGENTS.md.rig-new in the held-back
+state: exit 1, a clean message, zero files changed", and "a directory at
+AGENTS.md.rig-new in the held-back state: exit 1, a clean message, no
+EISDIR crash" (absent in a generated rig, same reason as above). The
+plan-time state machine itself is pinned at the `planUpgrade`/`applyUpgrade`
+level by `packages/cli/test/upgrade.test.ts`'s describe blocks "the
+AGENTS.md.rig-new rescue file — GENUINELY held back only (round 5)" and
+"AGENTS.md.rig-new clutter on a HEALTHY (never held back) rig must not
+affect upgrade at all" (same absence). And the whole remedy is followed end
+to end against the real pre-RP-186 payload — not a fixture — by
+`test/e2e/agents-md-migration.test.ts` (absent in a generated rig) › "a
+legacy rig whose AGENTS.md was edited before upgrading: CLAUDE.md is held
+back, never shimmed over an unreadable rulebook — and the rescue file
+resolves it end to end".
+
+Also see the byte-identity tests this ticket replaced, listed in the PR
+description as an old-test → new-test table.
+
+## What did not change
+
+- Provider-specific wiring stays provider-specific: `.claude/settings.json`,
+  `.claude/agents/`, `.codex/hooks.json`, `.codex/config.toml` are untouched
+  by this ticket and are never duplicated into either rulebook file.
+- The `elevated-paths` block moved with the canonical text: it is declared in
+  `AGENTS.md` now, not `CLAUDE.md`. Every mechanical reader of that block —
+  `readDeclaredPaths`, and through it the PR-lane router and the queue's own
+  tier bookkeeping, all of them part of the opt-in workflow layer and named
+  by the core rulebook only to describe what that layer adds — reads
+  `AGENTS.md` first and `CLAUDE.md` second, so a not-yet-migrated rig (or a
+  test fixture that still writes the block into a `CLAUDE.md`) is not
+  silently un-declared.
+- Zero new dependencies; the project-name token this generator substitutes
+  everywhere else is unaffected (it is not written literally here — this
+  file is itself substituted); no application skeleton, benchmark, agent-bus
+  or mandatory Memory
+  came back.

package/templates/agent-os/universal/docs/decisions/codex-adapter.md

@@ -4,15 +4,20 @@ Status: accepted for AR-113; subagent routing extended for RP-166.
 
 ## Decision
 
-Claude-shaped files remain the authoring surface. The generator derives the
-Codex rulebook (`AGENTS.md`), skills (`.agents/`), custom agents and hook
-wiring (`.codex/`); the generated files are checked for drift in the generator
-repository and are materialised into a
-generated project as its local, versioned operating system. A generated
-project does not ship the generator's projector. Its Claude and Codex files are
-versioned snapshots: a downstream project that deliberately changes one side
-must either make the equivalent local change on the other side or take a newer
-generated release. There is no downstream automatic drift check.
+Claude-shaped files remain the authoring surface for skills, custom agents and
+hook wiring. The generator derives the Codex skills (`.agents/`), custom
+agents and hook wiring (`.codex/`) from them; the generated files are checked
+for drift in the generator repository and are materialised into a generated
+project as its local, versioned operating system. The rulebook itself is the
+one exception, since RP-186: `AGENTS.md` is the canonical, authored,
+provider-neutral source — not derived from `CLAUDE.md` — and `CLAUDE.md` is a
+short, separately authored compatibility shim (`@AGENTS.md` import plus
+Claude-Code-specific notes; see `docs/decisions/agents-md-canonical.md`). A
+generated project does not ship the generator's projector for the derived
+files. Its Claude and Codex files are versioned snapshots: a downstream
+project that deliberately changes one side must either make the equivalent
+local change on the other side or take a newer generated release. There is no
+downstream automatic drift check.
 
 ## Why
 
@@ -26,7 +31,7 @@ table, and the projector refuses a missing or orphaned agent profile. It also
 refuses duplicate source-agent names across layers, since one profile name
 cannot route two definitions.
 
-Frequent bounded work (`test-writer`, `prose-reviewer`) uses `gpt-5.6-terra`;
+Frequent bounded work (`test-writer`, `implementation-agent`, `prose-reviewer`) uses `gpt-5.6-terra`;
 correctness, security, and infrastructure gates use `gpt-5.6-sol`. Every named
 gate uses `high` reasoning effort. Unnamed subagents inherit repository defaults
 of `gpt-5.6-terra` and `medium` from `.codex/config.toml`. `xhigh` is not a

package/templates/agent-os/universal/docs/decisions/review-lanes.md

@@ -4,10 +4,13 @@ The rule lives in `.claude/rules/workflow.md`, under "PR flow". This file
 explains the one part of it that reads like an inconsistency and is not, so that
 nobody "tidies" the two sets into agreement. It is not loaded into any session.
 
-## The sets
+## The sets (opt-in workflow layer)
 
-Three different mechanisms each carry their own notion of "this file is only
-words":
+All three mechanisms below — the gate sweep, the router, and the queue's
+elevated ration — ship with the opt-in workflow layer (`init --layer
+workflow`); a Core-only rig applies the same rulebook exemptions by hand,
+since none of these scripts exist for it to run. Three different mechanisms
+each carry their own notion of "this file is only words":
 
 **The first two carve out the rulebook**, and only then differ; the third runs
 *after* the sweep has already answered, so it sees only what survived:
@@ -29,7 +32,7 @@ test in the rig belongs there. The router's sets stay where they are, for the
 reason this whole record exists.
 
 **Neither row applies to a decision record, including this one.** Both
-predicates recognise `CLAUDE.md` anywhere, everything under `.claude/`, and —
+predicates recognise `CLAUDE.md` and `AGENTS.md` anywhere, everything under `.claude/`, and —
 since these records were extracted — everything under `docs/decisions/`, through
 the one shared `isDecisionRecord`. A change here escalates the sweep and takes
 the `model` lane, exactly as the rule it explains would. The router's call is
@@ -58,10 +61,11 @@ is one of the risk flags — and its extension happens to be `.txt`.
 
 Copying the sweep's `.mdx` into the router's prose set would put executable MDX
 back on the prose lane. MDX carries components and imports; it is a program that
-renders, not a document that is read. The ration reads it the same way and for
-the same reason (`spacing-rations-mechanisms.md`): calling it prose there would
-clear the spacing hold on a file this rig treats as a program, on the permissive
-side.
+renders, not a document that is read. The ration (workflow layer, like the
+mechanism it rations) reads it the same way and for the same reason
+(`spacing-rations-mechanisms.md`, also workflow layer): calling it prose there
+would clear the spacing hold on a file this rig treats as a program, on the
+permissive side.
 
 ## The shape of the mistake this prevents
 

package/templates/agent-os/universal/docs/decisions/session-start-wire-format.md

@@ -0,0 +1,206 @@
+# SessionStart hook output: one JSON wire format, both harnesses
+
+Status: accepted for RP-185.
+
+## Decision
+
+`inject-rules.mjs` (the SessionStart hook that re-injects the autonomy rules on
+startup, resume and compaction) prints one JSON object to stdout, unconditionally,
+for both Claude Code and Codex:
+
+```json
+{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"…"}}
+```
+
+No trailing newline, no other top-level fields, no provider branching. The
+`additionalContext` value carries exactly the text the hook used to write
+directly to stdout (the `[agent-os] …` banner, the notice, the excerpted rules).
+
+## Why
+
+Measured, 2026-09-17, Codex 0.154.0 on Windows: with the previous plain-text
+output — stdout beginning with the literal characters `[agent-os] Autonomy
+rules refresh …` — Codex printed `Hook failed └ hook returned invalid session
+start JSON output`, and the autonomy refresh never reached the session's
+context. Claude Code was unaffected by that same plain-text form. A second
+SessionStart hook in the same measured session, one that already emitted
+`{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}`,
+did reach the session — which is what pointed at the wire format rather than at
+"Codex rejects plain text" as the fix.
+
+That framing matters because it is not what Codex's own documentation says.
+[Codex's hooks reference](https://learn.chatgpt.com/docs/hooks) states plainly
+that plain text on stdout is accepted for `session_start` and is added as
+developer context — so "Codex does not support plain-text SessionStart output"
+would be false, and this file does not claim it. What the page does not
+document is *how* Codex decides a given stdout is JSON rather than plain text,
+or what happens when that decision goes the wrong way. The measured symptom —
+an output whose first character is `[` reported as *invalid* JSON, rather than
+silently read as plain text — is consistent with a sniff that treats a leading
+`[` (or `{`) as a signal to attempt a JSON parse, and reports a failure rather
+than falling back when that parse does not succeed. That mechanism is inferred
+from the symptom, not read off the page, and is stated here as an inference,
+not a documented fact.
+
+## Why the JSON envelope, not a reworded plain-text banner
+
+The alternative fix — keep printing plain text, just not starting with `[` —
+would have worked too, but it leaves the same undocumented sniffing behaviour
+one character choice away from breaking again, for a reason nobody would think
+to look for. The JSON form sidesteps the ambiguity entirely rather than
+tip-toeing around it, and it turns out to need no provider branching, because
+both harnesses already document the identical shape:
+
+- **Codex** ([learn.chatgpt.com/docs/hooks](https://learn.chatgpt.com/docs/hooks)):
+  gives the worked example
+  `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"Load the workspace conventions before editing."}}`
+  as JSON output for a `session_start` hook.
+- **Claude Code** ([code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)):
+  documents the same nested shape for `SessionStart` — `hookSpecificOutput`
+  with `hookEventName` (must equal `"SessionStart"`) and `additionalContext` —
+  and states that JSON is detected when stdout starts with `{` and ends with
+  `}`; anything else is treated as plain text and added to context the same
+  way. `systemMessage` and `terminalSequence` are also accepted fields there,
+  unused here because nothing today needs them.
+
+One shape, honoured by both harnesses' own documentation, is what
+`invariants.md` ("One mechanism, one implementation") asks for whenever a
+single source can serve two consumers — the alternative, a provider check that
+picks plain text for one harness and JSON for the other, would be exactly the
+kind of guessed, undocumented branching this repository's rules warn against
+("never invent APIs or behavior").
+
+## What this does not claim
+
+- Not that Codex rejects plain text in general — its own docs say otherwise.
+- Not a documented account of Codex's JSON-vs-plain-text sniffing — that
+  mechanism is not published; only the fix (always emit the one documented
+  JSON shape) is asserted, not the internal reason it was needed.
+- Not that `source: "startup"`, `"resume"` and `"compact"` are guaranteed
+  identical by either harness's spec beyond what each page states; both are
+  silent on any per-source difference in output handling, and the hook applies
+  the same output uniformly across all three because nothing in either
+  contract says to do otherwise.
+
+## The exit path: exitCode vs exit(), and what it trades
+
+The envelope change alone re-armed the original defect at a different trigger.
+`inject-rules.mjs` ended with `process.exit(main())`, and `process.exit()` tears
+the process down without waiting for a queued `stdout.write()` to drain. Under
+the old plain-text wire format a write a pipe's buffer could not hold in one
+piece degraded to *partial rules text* — readable, if incomplete. Under the
+JSON envelope the same truncation is *invalid JSON* — precisely the state
+Codex was measured rejecting wholesale, just moved from "the output starts
+with `[`" to "the output was cut off mid-object". Exit code 0 either way, so
+nothing downstream reports it.
+
+Reproduced independently by two review passes at HEAD before the fix: a
+consumer that does not start reading until well after the child would have
+exited loses everything past the pipe's buffer — at one measurement, a 74 KB
+rules file delivered 0 bytes; at another, 65536 of 73893. Both parse as
+`Unterminated string`.
+
+The fix is `process.exitCode = main()` in place of `process.exit(main())`.
+Every path through `main()` returns `0`, so the exit STATUS does not change.
+What changes is whether the process terminates before the write finishes:
+`exitCode` lets Node's event loop drain naturally, which is what lets a large
+payload actually reach a reader. Verified against the same probe shape that
+found the defect, at four payload sizes (7 083 B through 1 002 552 B) and
+three consumer shapes (a non-draining reader, a slow reader at 4 KiB/50 ms,
+and a plain file redirect): every case delivered the complete envelope and
+parsed. Pinned in the generator's `hooks.test.ts` (absent in a generated rig)
+› "delivers the whole envelope even when the reader does not drain until
+process.exit(main()) would already have torn the process down", which goes
+red (`Unterminated string`, at a byte count that is host-dependent — kernel
+pipe buffer size and scheduler timing both vary) if the single line is
+reverted. The pinned payload is sized for a deterministic kill rather than a
+merely likely one: a smaller payload truncated on nearly every reversion run
+on every host checked, but not every one, and a pin the defect can slip
+through occasionally is a pin that will eventually be green on a real
+revert. That pin's coverage is Linux-shaped: Node documents pipe writes as
+synchronous on Windows and asynchronous on POSIX, so the same reversion is
+expected to have little or nothing to catch on a Windows lane — the test's
+own comment says so, so a future reader does not mistake a Linux-only kill
+for cross-platform cover.
+
+**What this trades away, stated plainly rather than left to be discovered:**
+`process.exit()` also GUARANTEED teardown, and `exitCode` does not. A consumer
+that never reads stdout at all no longer gets a fast, wrong exit 0 — it gets
+a hook that stays alive indefinitely, waiting on the write. Measured: still
+running 8 seconds in in one review's reproduction, at 74 KB and 1 MB payloads
+with nobody draining; completing the instant a reader appeared. A probe built
+to refuse reading until the child would already have exited measurably
+DEADLOCKS this version, where `process.exit()` would have terminated
+(truncated, but terminated). Nothing in this file bounds that wait — the
+calling harness's own hook timeout does. Not reachable at the size this hook
+ships today (a few KB, well under a second to write), but a real behaviour
+change on a project whose `autonomy.md` grows large, or whose harness stops
+reading a hook's stdout entirely. The trade is made on purpose: a loud hang
+bounded by the harness's own timeout is preferred over a silent, truncated
+"success" with no bound on how wrong it can be.
+
+A second, smaller consequence of the same change: a reader that vanishes
+MID-write (a closed pipe, a harness that kills this process before reading)
+now surfaces as an unhandled `error` event on `process.stdout` — exit 1 with
+a Node stack trace on stderr, where the old `process.exit()` path exited 0
+silently in the same situation. The handler is narrow rather than blanket,
+and the difference is measured, not theoretical: an earlier draft of this
+fix silenced every stdout error unconditionally, and security review found
+that with stdout redirected to `/dev/full` — a genuine write failure
+(ENOSPC), with the reader still fully attached — that blanket form exited 0
+with nothing delivered and no diagnostic, the exact silent-loss shape this
+whole file exists to avoid, moved one write call over. The handler now
+distinguishes the two: EPIPE (the reader is gone; there is nothing left to
+report to) stays silent, and anything else is written to stderr and marks
+the exit non-zero. Pinned in the generator's `hooks.test.ts` (absent in a
+generated rig) › "silently exits 0 when the reader is gone before the write
+starts (EPIPE)" and › "reports a genuine stdout write failure on stderr and
+marks the exit non-zero, rather than looking like a healthy session".
+
+**Left for a separate decision, not for this one:** seven sibling hooks in
+this same directory still end in `process.exit(…)` with no wait for a
+pending write — `block-no-verify.mjs`, `guard-rulebook.mjs`,
+`guard-subagent-model.mjs`, `guard-bash.mjs`, `guard-secret-file.mjs`
+(`process.exit(status)`), `gate-stop-dod.mjs` (`process.exit(code)`) and
+`warn-subagent-routing.mjs` (the first four and the last end
+`process.exit(main())`). Their payloads are short (a refusal message, not a
+whole rules file), so the exposure is far smaller, but the reasoning above
+now lives in one hook's comments only — `invariants.md`'s "one mechanism,
+one implementation" would ask for the same pattern everywhere it applies.
+This change deliberately does not touch the other seven: changing every
+`process.exit()` call in the hooks directory in a PR whose stated purpose is
+a SessionStart wire-format fix is exactly the scope creep `autonomy.md`'s
+Tier-2 discipline exists to catch. Recorded here so the inconsistency is a
+known, named backlog item rather than something the next reader has to
+rediscover.
+
+## Risk and rollback
+
+Tier 2 (`templates/agent-os/universal/.claude/hooks/` is a declared elevated
+path) for both decisions this record carries, each with its own risk and its
+own rollback:
+
+**The wire format.** The blast radius is narrow: this hook's own stdout
+contract, read only by the two harnesses' SessionStart machinery. If either
+harness's documented shape turns out to differ from what was fetched here, or
+a future harness version stops accepting it, rollback is reverting
+`inject-rules.mjs` to write plain text again — a one-line change, the same
+one this decision replaces. The old plain-text form is pinned by a regression
+test precisely so it is not reintroduced by accident while chasing an
+unrelated fix: the generator's `hooks.test.ts` (absent in a generated rig) ›
+"never regresses to the old bare [agent-os]-prefixed plain-text stdout".
+
+**The exit path** ("The exit path: exitCode vs exit(), and what it trades",
+above). The blast radius is this hook's shutdown behaviour, not its output
+shape: a consumer that never drains stdout at all now holds this process
+alive rather than letting it exit truncated, bounded only by the calling
+harness's own hook timeout. If that trade turns out to be wrong — a harness
+with no such timeout, or one where a hung hook process is worse than a
+truncated one — rollback is reverting the single `process.exitCode = main()`
+line to `process.exit(main())`, independently of the wire-format decision
+above; the two lines do not depend on each other. That reintroduces the
+flush defect this record measures, so a revert of this line alone should
+also remove or explicitly override the test that pins it: the generator's
+`hooks.test.ts` (absent in a generated rig) › "delivers the whole envelope
+even when the reader does not drain until process.exit(main()) would already
+have torn the process down".

package/templates/agent-os/universal/docs/decisions/subagent-routing.md

@@ -11,7 +11,7 @@ Each named subagent this rig ships pins the model and the effort it reads with:
 | Role | Claude Code | Codex |
 | --- | --- | --- |
 | `code-reviewer`, `security-scanner`, a stack's infrastructure reviewer | `claude-opus-5`, `high` | `gpt-5.6-sol`, `high` |
-| `test-writer`, `prose-reviewer` | `claude-sonnet-5`, `high` | `gpt-5.6-terra`, `high` |
+| `test-writer`, `implementation-agent`, `prose-reviewer` | `claude-sonnet-5`, `high` | `gpt-5.6-terra`, `high` |
 | a subagent with no definition | `claude-sonnet-5`; effort follows the session | `gpt-5.6-terra`, `medium` |
 
 In this project the pins are the files themselves: `model:` and `effort:` in
@@ -93,8 +93,11 @@ environment: `subagent-routing.test.ts` (absent in a generated rig) ›
   In a generated project the definitions are the policy (next section), so an agent
   a project adds with a pin is a role, and a role whose definition is changed to
   `model: inherit` has stopped being one — by that project's reviewed decision.
-- **The built-in agents get no definitions here.** A general-purpose subagent follows
-  the unnamed default like any subagent without a definition.
+- **The built-in agents get no definitions here.** Ordinary implementation has its
+  own role, `implementation-agent`, on the same tier as `test-writer`: frequent,
+  bounded work, not the reviewer tier. A general-purpose subagent remains for
+  ad-hoc work no role covers, and follows the unnamed default like any subagent
+  without a definition.
 - **The warning is a warning.** A session started with `CLAUDE_CODE_EFFORT_LEVEL` set
   still runs every gate — at that level.