create-agent-rig 0.9.0 → 0.10.0

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

@@ -1,166 +1,19 @@
-# __PROJECT_NAME__
+@AGENTS.md
 
-> **Top rule — commit/PR attribution: NEVER include co-authored or AI-attribution information.**
-> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: AI Assistant …`), `Generated with an AI coding agent`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
-> This project runs under an agent operating system: the rules below are not
-> suggestions — the important ones are enforced by hooks and gates at the tool
-> layer.
+## Claude Code
 
-## One operating system, two harnesses
+This file is a compatibility shim, not a second copy of the rulebook.
+`AGENTS.md` next to it is the single canonical source — see
+`docs/decisions/agents-md-canonical.md` — and the `@AGENTS.md` line above is
+Claude Code's own import syntax: it pulls the full rulebook into context
+exactly as if it were written here.
 
-This rulebook serves both Claude Code and Codex. The generator authors it as
-`CLAUDE.md` and publishes the same text as `AGENTS.md`, so neither harness gets
-a weaker policy. The `.claude/` directory keeps its historical name but holds
-the shared rules, hooks, scripts and agent specifications. Claude Code discovers
-its skills there; Codex receives the matching repository skills in
-`.agents/skills/` and its native agent and hook configuration in `.codex/`.
-The derivation and rollback contract is recorded in
-`docs/decisions/codex-adapter.md`.
+The shim exists because Claude Code's native `AGENTS.md` reading is not
+always active — it depends on the Claude Code version and configuration in
+use — so this file guarantees the rulebook loads either way. It is **not**
+a claim that Claude Code always reads `AGENTS.md` on its own.
 
-This project runs under an agent operating system: the rules below are not
-suggestions — the important ones are enforced by hooks and gates at the tool
-layer.
-
-## If you read only four sections, read these
-
-1. **Autonomy tiers** — what you may do alone vs. propose first:
-   `.claude/rules/autonomy.md` ("Tiers")
-2. **Stop rules** — when stopping with a diagnosis is the correct move:
-   `.claude/rules/autonomy.md` ("Stop rules")
-3. **The request path** — the mandatory usecase layer and the pure core:
-   `.claude/rules/architecture.md`
-4. **Definition of Done** — the checklist a change must pass:
-   `.claude/rules/workflow.md` ("Definition of Done")
-
-## The map
-
-```
-packages/core/    pure domain logic — schemas + functions; no I/O, no clock,
-                  no randomness, no environment (hook-enforced)
-packages/shared/  logger, env loading, typed errors — cross-cutting, no domain
-packages/db/      the ONLY module that touches the storage SDK/driver
-services/         entrypoints; every request: payload → handler → usecase → model
-apps/web/         the frontend; imports core + shared ONLY, talks to services
-                  over HTTP (hook-enforced)
-```
-
-The target-specific details (how to run, deploy, and verify runtime health)
-live in `README.md`. Alongside the universal rules, `.claude/rules/` carries
-the stack-specific conventions composed in for this project's target — read
-them all; they are one rulebook.
-
-## How work happens here
-
-- **TDD, without exception.** The failing test comes first — use the
-  `test-writer` agent for it. See `.claude/rules/workflow.md`.
-- **Check the premises at both ends.** A queue item is a claim about the code, and
-  nothing downstream re-reads the file it was wrong about — the `check-premises`
-  skill runs between taking the item and the failing test, and a false load-bearing
-  claim stops the task instead of quietly re-aiming it. It runs **again before the
-  gate**, on the prose the task itself wrote: a behaviour claim with nothing behind
-  it is `UNMEASURED`, and it is deleted or turned into a pointer to its test rather
-  than left for a reviewer to find.
-- **One task, one branch — and merge via PR.** Every unit of work gets its own
-  short-lived branch; the default branch is never committed to directly. Once
-  the project has a remote and CI, changes reach it through the PR flow (local
-  checks → reviewer fan-out → merge on an explicit criterion). See
-  `.claude/rules/workflow.md` ("Branches and commits", "PR flow"). When another
-  session may touch this repo at the same time, the branch lives in its own
-  worktree — the `worktree-task` skill has the lifecycle and the cleanup.
-- **Gates.** Every PR is routed before it is reviewed — the
-  `decision-router` picks the cheapest lane the change earns
-  (`deterministic` → `fast-path` → `model`), and risk flags escalate ahead of
-  all three. `code-reviewer` runs on the `model` lane, which is **everything the
-  two cheap lanes did not claim** — code, a rulebook document, an unclassifiable
-  path, a derived artifact git does not report as drift, or anything a risk flag
-  escalated;
-  `security-scanner` when a change touches auth, secrets, parsing, or outbound
-  calls; `prose-reviewer` when it touches the documents that instruct agents —
-  rules, skills, agent specs, decision records, this file, the README. Those last two are
-  **lane-independent and may only add** — the lane is a floor, never a ceiling.
-  `.claude/rules/workflow.md` carries the ladder and what the cheap lanes give
-  up. Blocking findings are resolved, not argued with, and the
-  `pr-ship` skill drives the fan-out. **No hook launches them** — a gate here is
-  a session following a written rule, so "the gate ran" is a claim, not a
-  guarantee. The mechanical enforcement below is a different thing, and the
-  difference is worth keeping straight.
-- **Enforcement is mechanical.** `guard-core-purity` catches an impure edit to
-  the core the moment it lands; `guard-web-boundary` keeps the frontend off the
-  backend; `guard-rulebook` refuses an edit to the rulebook itself from an
-  unattended run outside the item's allow-list (a flag file the `loop` skill
-  writes; attended sessions are untouched); `guard-secret-file` refuses an edit that writes a credential — by the
-  file's name or by a value in its text, from the one vocabulary in
-  `.claude/scripts/lib/secrets.mjs`; `block-no-verify` refuses pre-commit
-  bypasses; `guard-bash` refuses
-  the "Never" tier — force-pushing a shared branch, a production deploy, a
-  filesystem wipe — and carries the kill switch; `gate-stop-dod` refuses to end
-  the session while a Definition-of-Done check fails. If a hook blocks you, fix
-  the cause; never route around a hook.
-- **Enforcement is a pattern you can apply again.** Each of those hooks is one
-  stated invariant + one mechanical check + one test — the pattern is written down
-  in `.claude/rules/invariants.md`, and the `new-invariant` skill walks you
-  through adding one. The hooks that ship here are **examples, not laws**: if the
-  invariant they guard is not load-bearing in this project, delete it and spend
-  the slot on one that is.
-- **There is a brake, and it is a real file.** `touch
-  ~/.claude/__PROJECT_NAME__-loop-STOP` and `guard-bash` denies every merge
-  until it is removed. Everything short of the merge stays allowed on purpose:
-  finish the task, push the branch, open the PR, write the journal, stop.
-  Stopping cleanly never means losing the work.
-- **Work comes from the queue, through an adapter.** The `loop` skill selects via
-  `.claude/scripts/queue/index.mjs`, which reads whichever queue
-  `.claude/queue.json` names — the Agent queue in `PLAN.md` by default, issues in
-  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.
-
-## The elevated paths of this project
-
-Tier 2 in `.claude/rules/autonomy.md` names *kinds* of change. This block names
-the **paths** in this repository where those kinds live, and
-`.claude/scripts/detect-missed-gate.mjs` reads it — so a path that is not declared
-is a path the gate sweep cannot see.
-
-```elevated-paths
-packages/db/src/
-.claude/
-.agents/
-.codex/
-AGENTS.md
-docs/decisions/
-.github/workflows/
-```
-
-The entries that earn their place first are the ones that *disarm* the rest —
-wherever this project keeps its rulebook, its hooks and its CI definition. A
-merge that rewrites the Never tier, unwires a hook or edits what CI runs should
-never pass unreviewed. The rest of the block is whatever this particular shape
-has, so read the list above rather than this paragraph: the two are maintained
-separately, and a project that re-composes the block leaves prose describing
-somebody else's repository.
-
-**They are a seed, not a law — the list is yours to extend.** It is what every
-generated shape has; a real project accumulates more (auth handlers, billing, a
-credentials module, a migration directory). Add a path the same day you add the
-code, because the gap between the two is exactly the window in which a change
-slips through unreviewed.
-
-The declaration is **composed, not centralised**: the sweep unions this block with
-every `elevated-paths` block in `.claude/rules/`, so a stack layer declares the
-paths that only exist in its shape. A gate declared over a directory this project
-does not have would report "clean" while looking nowhere.
-
-Nothing about this list is retroactive. Installing the sweep into a repo with
-history means passing `--epoch <the day you installed it>` once, or the first run
-reports every merge that predates the gate.
-
-## Foot-guns
-
-- Don't "simplify" a handler by calling a model directly — the usecase layer is
-  mandatory even when it looks like ceremony.
-- Don't inline `Date.now()`/randomness into the core "just this once" — inject
-  them; the hook will refuse anyway.
-- Don't weaken a failing test to get green — a red check is information, and
-  test integrity is a blocking review finding.
-- After a deploy, CI-green ≠ runtime-healthy: verify per the README, and on
-  regression revert first (`.claude/rules/autonomy.md`, "Post-deploy
-  verification").
+Add Claude-Code-only instructions below this line — provider-specific
+wiring stays in `.claude/settings.json`, `.claude/agents/` and the other
+provider-specific files the rulebook already names. Do not restate
+rulebook content here, and do not remove the import above.

package/templates/agent-os/universal/PLAN.md

@@ -1,12 +1,17 @@
 # __PROJECT_NAME__ — plan and work queues
 
-Work in this project has a stated origin: one of the two queues below. An
-agent session picks from the **Agent queue** (see the `loop` skill); anything
-that needs a human decision waits in the **Operator queue**. An empty Agent
-queue means the session ends — it is never an invitation to improvise.
+This file itself ships with Core — every rig has it, `--layer workflow` or
+not. **What reads it automatically is workflow-layer only** (`init --layer
+workflow`): with that layer, an agent session picks from the **Agent queue**
+through the `loop` skill, and anything that needs a human decision waits in
+the **Operator queue** — an empty Agent queue means the session ends, never
+an invitation to improvise. **Without the workflow layer, this file is
+manual**: a place to note or look up planned work by hand, read by a session
+only when asked to, never selected from automatically.
 
 Keep entries one line each, most valuable first. Delete done items — the
-journal records history; the queues state only what is next.
+journal (workflow layer only, below) records history; the queues state only
+what is next.
 
 ## Agent queue
 
@@ -20,12 +25,14 @@ journal records history; the queues state only what is next.
 <!-- Decisions and Tier-2 work waiting on a human. State what is needed, e.g.:
 - decide: retention policy before real data (RemovalPolicy flip)
 -->
-## Where the journal is
+## Where the journal is (workflow layer only)
 
-`journal/YYYY-MM.md` — one file per month, newest-on-top inside each. The
-convention and the field list are in `journal/README.md`.
+`journal/README.md` and the `journal/YYYY-MM.md` files it describes ship with
+the opt-in workflow layer (`init --layer workflow`) — a Core-only rig has
+neither. Where they exist: one journal file per month, newest-on-top inside
+each; the convention and the field list are in `journal/README.md`.
 
 The heading here is deliberately **not** `## Journal`: a pointer under that name
 still sends a session into this file to look, and keeping this file small is the
-point. `plan-md.mjs` resolves the two queue headings above by name and is not
-affected either way.
+point. `plan-md.mjs` (workflow layer) resolves the two queue headings above by
+name and is not affected either way.

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