create-agent-rig 0.9.0 → 0.10.0

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.
 

package/templates/agent-os/universal/docs/decisions/workflow-layer-split.md

@@ -0,0 +1,235 @@
+# Why the workflow layer is opt-in, and where the line falls
+
+The rule lives in `CLAUDE.md`, under "The opt-in workflow layer (experimental)".
+This file explains why `layers.json` (RP-180) draws the line where it does,
+and why a few files that look like PR-lifecycle automation stayed in Lean Core
+instead of moving with the rest of it.
+
+## What moved, and why
+
+Before this split, `templates/agent-os/universal/layers.json` had one array,
+and `init`/`create` installed all of it unconditionally — including the queue
+adapter, the `loop` and `pr-ship` skills, run-state, the run journal,
+revalidation, claim-records and the PR-lifecycle helpers named below. None of
+that is required by Lean Core: a thin CRUD service or a solo-maintained
+library gets the same review gates and stop rules with none of the
+autonomous, cooperative machinery, and shipping it anyway made every fresh
+rig carry queue-selection semantics it never asked for.
+
+The workflow layer is what a project opts into with `init --layer workflow`:
+the queue adapter (`.claude/scripts/queue/`, `.claude/queue.json`), the
+`loop` and `pr-ship` skills, `run-state.mjs`, the run journal
+(`run-journal.mjs` — see the one exception below —, `journal/README.md`),
+revalidation and claim-records, and the PR-lifecycle helpers
+`decision-router.mjs`, `detect-missed-gate.mjs` and
+`reconcile-external-prs.mjs`.
+
+## The exception: why `verdict.mjs`, `lib/verdict.mjs`, `lib/gate-coverage.mjs`
+## and `run-journal.mjs` stayed in Lean Core
+
+These four read as PR-lifecycle automation — the ticket's own wording groups
+"PR-lifecycle helpers" with the workflow layer — and the first draft of this
+split moved them too. It does not survive contact with what Lean Core
+actually installs, for one mechanical reason: `check-premises` is a Lean Core
+skill (a session runs it standalone, with no queue and no loop, "before the
+Red step" and again "before the gate"), and its own second entry point tells
+the reader to run `node .claude/scripts/verdict.mjs check <report>
+check-premises` on its own output. `.claude/scripts/verdict.mjs` is a single
+module with **static, top-level imports** of `./lib/gate-coverage.mjs` and
+`./run-journal.mjs` — Node resolves the whole file before any subcommand
+runs, so a core-only install that shipped `verdict.mjs` without those two
+would break `check-premises`'s own documented command on the very first
+`check` subcommand, not only on `coverage`.
+
+The three reviewer agent specs (`code-reviewer.md`, `security-scanner.md`,
+`prose-reviewer.md`) are Lean Core for the same reason `check-premises` is —
+review applies to any PR, loop-driven or not — and all three cite
+`.claude/scripts/verdict.mjs` as the shape their own report is checked
+against.
+
+So the dependency runs from Lean Core outward: `check-premises` (core) needs
+`verdict.mjs` (core) to load at all, `verdict.mjs`'s own module graph needs
+`lib/gate-coverage.mjs` and `run-journal.mjs`, and neither of those two
+imports anything outside itself (`node:fs`, `node:path`, and in
+`gate-coverage.mjs`'s case nothing at all — the mention of
+`decision-router.mjs` in its header is a comment, not an import). Moving the
+leaves and leaving the root behind was the option that did not exist;
+`invariants.md`'s "a file a core guard imports must stay core" generalises
+past hooks to this case on the same reasoning.
+
+`decision-router.mjs` itself has no such pull: `lib/gate-coverage.mjs`
+mentions it only in a comment, and the one real static import of it
+(`.claude/hooks/lib/edit-input.mjs`) is also a comment, not code. It moved
+with the rest of the workflow layer, and `workflow.md`'s "PR flow" section
+states the Lean Core fallback when it is not installed: every change still
+reaches `code-reviewer`, and a human or the session decides which additional
+reviewers apply, by the same triggers `decision-router` would have read.
+
+`docs/decisions/gate-coverage.md` stayed with `pr-ship` (workflow) rather
+than `lib/gate-coverage.mjs` (core) for a different reason: nothing in Lean
+Core cites the record, only `pr-ship`'s own skill file does. The module and
+the rationale for *why it exists* travel separately on purpose — the module
+is a dependency of a core skill's documented command, the essay about why a
+hook version of the same check was rejected is not.
+
+## The freeze this split does not touch
+
+RP-53 holds revalidation and claim-records' *behavior* frozen through the
+RP-26 gate (2026-10-27): no feature expansion, no experiment restart, no bias
+introduced by this or any other 0.10 change. This split moves their
+*install-time layer* only — which `layers.json` array they sit in — and
+changes not one line of `revalidate.mjs`, `revalidation-report.mjs`,
+`lib/revalidation-evidence.mjs`, `lib/revalidation-points.mjs` or
+`lib/claim-records.mjs` beyond that relocation. After the gate: GO retains
+them in the optional workflow layer as they are today; NO-GO removes them in
+a bounded follow-up. Missing evidence is not a NO-GO.
+
+## What the manifest records, and the direction that matters
+
+`RigManifest.layers` records which layer(s) a rig installed, and `upgrade`
+refreshes only what it names. The one detail worth restating here because
+getting it backwards is silent and destructive: a manifest written **before**
+this field existed recorded nothing about layers because there was only one
+payload to record — so `parseManifest` reads that absence as `['process',
+'workflow']`, never as `['process']`. A fresh `init` with no
+`--layer workflow` flag writes `['process']` explicitly. The two defaults
+point in opposite directions on purpose, and swapping them would make the
+very next `upgrade` on an existing dogfood repository report every workflow
+file it already has as `retired` and stop managing it.
+
+## Interaction with `uninstall` (RP-181, merged after this split was written)
+
+`uninstall` needs no separate awareness of `layers` at all, and gains none:
+it walks `manifest.files` and `manifest.kept` directly (`commands/uninstall.ts`),
+and both of those already name exactly the paths a given install wrote or
+found, regardless of which `layers.json` array a path happens to live in. Three
+cases, all covered by the same unmodified byte-hash check:
+
+- **A Core-only rig** (no `--layer workflow`) never has a workflow-layer path in
+  `manifest.files` in the first place — `initManifest` only reads the layers
+  `effectiveLayers` resolved — so `uninstall` has nothing workflow-shaped to
+  remove and reports nothing about it.
+- **A rig that opted into the workflow layer** has those paths in
+  `manifest.files` exactly like any process-layer path, and `uninstall` removes
+  or preserves them by the same pristine-bytes check as everything else it
+  owns.
+- **An inherited pre-0.10 rig** (a manifest with no `layers` key at all) had its
+  workflow files recorded in `files` the only way any release before this one
+  ever wrote a manifest — there was no `kept`/`files` split by layer to begin
+  with — so `uninstall` already treats them as owned, the same as it always
+  has. Nothing here widens what `uninstall` is willing to remove, and nothing
+  narrows it: a manifest either names a path in `files`/`kept` with the right
+  hash, or `uninstall` leaves it alone, and that rule does not read `layers`.
+
+Pinned in `packages/cli/test/uninstall.test.ts` (absent in a generated rig —
+this is the generator's own test suite, not a payload path) › "removes an
+installed workflow-layer file exactly like any Core file, when the rig opted
+in", › "a workflow-layer file never installed here (Core-only rig) is simply
+absent from the manifest, never reported \"not a path this release installs\"",
+and › "an inherited pre-layers manifest (no `layers` key) still owns its
+workflow files, exactly like any other installed path".
+
+## There is no opt-out short of `uninstall`
+
+Once a rig has the workflow layer — `init --layer workflow`, or inherited
+from before RP-180 — nothing in `init` or `upgrade` ever drops a layer a
+READABLE manifest already recorded; `effectiveLayers` (`init.ts`) is
+additive by construction, full stop. `detectLayersOnDisk` (`upgrade.ts`) is
+a narrower claim: it only ever runs when there is NO readable manifest at
+all, and even then it does not treat "a layer's files exist" as license to
+keep them regardless of how many — it is additive in the same direction
+(never narrows what a READABLE manifest said), but on the bootstrapped path
+it decides per layer by quorum (`LAYER_ADOPTION_QUORUM`, more than half of
+the layer's own files present), and can legitimately decide a layer is NOT
+this rig's: a Core-only rig with one or a few stray files that happen to
+share a workflow-layer path is left at Core, its stray files untouched and
+unrecorded (round 4, blocker A — round 3's fix asked only "does at least one
+file exist", which re-adopted the whole layer from a single stray path).
+The only supported way back to Core-only for a rig the manifest genuinely
+still names as having the workflow layer is `uninstall` (removing the
+workflow files this rig owns) followed by a fresh `init` with no `--layer`
+flag — see "The exact opt-out procedure, measured" below for what that
+takes when `uninstall` had to preserve something.
+
+**Hand-editing `layers` in `.claude/.rig-manifest.json` down to `["process"]`
+is not that opt-out, and it does not do what it looks like it does.** The
+files themselves are untouched by the edit itself — nothing deletes them —
+but the next `upgrade` reads the manifest's `layers` as authoritative
+(`upgrade.ts`'s `initInstallSet(repoDir, project, layers)`), so every
+workflow path drops out of that plan's own install set and is reported
+`retired`, reason `"no longer shipped by this release — the rig no longer
+manages it; it is now yours"` — the same verdict RP-177 gave a deleted stack
+overlay, applied here to files that are simply no longer read as this rig's
+layer. `applyUpgrade` then writes a manifest whose `files` map has no entry
+for any of the roughly three dozen workflow paths at all — measured, on a
+clean `--layer workflow` install, at exactly 89 file entries down to 56
+(`packages/cli/test/upgrade.test.ts`, absent in a generated rig, pins "a
+clean workflow-layer install hand-edited down to a core-only layers array
+goes from 89 manifest entries to 56"; the figure moved by one from an
+earlier 86/53 when RP-186 added `docs/decisions/agents-md-canonical.md` to
+the process layer, and by two more when `implementation-agent` joined it).
+The files stay on disk, silently un-hashed and unowned —
+and a LATER `uninstall`, reading the same manifest, has nothing there to
+recognise them by: they read as an ordinary foreign/untracked path, not as
+something this release ever installed, and are left alone. The manifest
+itself does not warn about this because it has no opinion on why `layers`
+changed; the tool trusts its own evidence file. This is measured behaviour,
+not a guess: `packages/cli/test/upgrade.test.ts` (absent in a generated rig)
+pins the `retired` verdict and the orphaning it causes in "hand-editing
+`layers` down to `["process"]` on a rig that already has the workflow
+layer retires every workflow file — on disk, unowned, never deleted".
+
+**The mirror hand-edit — `layers: ["workflow"]` alone, dropping `process` —
+does the identical thing in the other direction, on a still-readable
+manifest.** `initInstallSet` reads exactly the array it is given; a `layers`
+that never names `process` un-owns every Core file the same way dropping
+`workflow` un-owns every workflow file: the next `upgrade` retires them from
+the plan and drops them from `files`, silently, files untouched on disk.
+(This is not the bootstrapped path's own normalisation — `detectLayersOnDisk`
+always forces `process` into a layer set it INFERS from disk; a READABLE
+manifest is trusted as written, `process` included, and nothing here
+prevents an operator from writing one that omits it.)
+
+## The exact opt-out procedure, measured (RP-180 round 4, blocker B)
+
+`uninstall --yes` followed by a fresh `init` (no `--layer` flag) reaches
+Core-only in exactly ONE of the two cases that matter, and round 3 stated it
+as though it always worked. Measured on the built CLI, both ways:
+
+- **Nothing on the rig was ever edited.** `uninstall --yes` removes every
+  file it owns — Core and workflow alike — and, because nothing was left to
+  preserve, deletes the manifest too. A fresh `init` then finds no manifest
+  and no workflow files: Core-only, as documented. A fresh `init` then
+  installs Core only.
+- **Anything was edited — one file is enough.** `uninstall --yes` preserves
+  that one file (and reports it) and, because something was preserved,
+  **keeps the manifest** — still recording `layers: ["process","
+  workflow"]`. The next plain `init` reads that surviving manifest
+  (`effectiveLayers` in `init.ts`: `previous?.layers.includes('workflow')`)
+  and reinstalls the entire workflow layer right back. `uninstall --yes` leaves
+  the one preserved file plus the manifest, and a plain `init` afterward
+  brings the whole workflow layer back, `layers` still both. The
+  "fresh `init`" instruction alone does NOT reach Core-only here — round 3
+  said it did.
+
+**The procedure that actually reaches Core-only when something was
+preserved: pass `--detach`.** `uninstall --yes --detach` performs the
+identical safe removal and then deletes the manifest regardless of what is
+left behind, handing the preserved file(s) over to the operator outright
+(they stay on disk, no longer named by anything). The next plain `init`
+then finds no manifest at all and installs Core only. A fresh `init` then installs
+Core, leaves the preserved file untouched, and records `layers: ["process"]`. No new flag
+was added for this — `--detach` already existed (RP-181) for the identical
+reason: a manifest kept alive only by something it has no business
+prescribing further action over.
+
+Equivalently, without `--detach`: remove the file(s) `uninstall --yes`
+reported as preserved, then remove `.claude/.rig-manifest.json` by hand,
+then run a plain `init`. Both procedures were measured to reach the same
+end state; `--detach` is the one to recommend because it is one command
+instead of a report a human has to read and act on by hand.
+
+Pinned end-to-end on the built CLI in `test/e2e/uninstall.test.ts` (absent in
+a generated rig) › `describe('the opt-out procedure to Core-only, measured
+(RP-180 round 4, blocker B)')`: both cases end in `layers: ["process"]` and
+no un-preserved workflow file left on disk.

package/templates/agent-os/universal/layers.json

@@ -7,6 +7,7 @@
     ".claude/skills/new-invariant/guard-invariant.example.mjs",
     ".claude/skills/new-invariant/guard-invariant.example.test.mjs",
     ".claude/agents/test-writer.md",
+    ".claude/agents/implementation-agent.md",
     ".claude/agents/code-reviewer.md",
     ".claude/agents/security-scanner.md",
     ".claude/agents/prose-reviewer.md",
@@ -20,41 +21,52 @@
     ".claude/hooks/warn-subagent-routing.mjs",
     ".claude/hooks/lib/edit-input.mjs",
     ".claude/hooks/lib/hook-input.mjs",
-    ".claude/skills/pr-ship/SKILL.md",
-    ".claude/skills/loop/SKILL.md",
     ".claude/skills/check-premises/SKILL.md",
     ".claude/skills/worktree-task/SKILL.md",
     ".agents/skills/new-invariant/SKILL.md",
     ".agents/skills/new-invariant/guard-invariant.example.mjs",
     ".agents/skills/new-invariant/guard-invariant.example.test.mjs",
-    ".agents/skills/pr-ship/SKILL.md",
-    ".agents/skills/loop/SKILL.md",
     ".agents/skills/check-premises/SKILL.md",
     ".agents/skills/worktree-task/SKILL.md",
     ".codex/agents/test-writer.toml",
+    ".codex/agents/implementation-agent.toml",
     ".codex/agents/code-reviewer.toml",
     ".codex/agents/security-scanner.toml",
     ".codex/agents/prose-reviewer.toml",
-    ".claude/scripts/detect-missed-gate.mjs",
-    ".claude/scripts/decision-router.mjs",
-    ".claude/scripts/reconcile-external-prs.mjs",
     ".claude/scripts/stop-flag.mjs",
     ".claude/scripts/unattended-flag.mjs",
     ".claude/scripts/git-env.mjs",
-    ".claude/scripts/preflight.mjs",
     ".claude/scripts/doctor.mjs",
     ".claude/scripts/run-journal.mjs",
-    ".claude/scripts/run-state.mjs",
     ".claude/scripts/verdict.mjs",
+    ".claude/scripts/lib/gate-coverage.mjs",
+    ".claude/scripts/lib/verdict.mjs",
+    ".claude/scripts/lib/secrets.mjs",
+    ".claude/scripts/lib/shell-tools.mjs",
+    "PLAN.md",
+    "docs/decisions/fail-open-guards.md",
+    "docs/decisions/codex-adapter.md",
+    "docs/decisions/subagent-routing.md",
+    "docs/decisions/review-lanes.md",
+    "docs/decisions/workflow-layer-split.md",
+    "docs/decisions/session-start-wire-format.md",
+    "docs/decisions/agents-md-canonical.md"
+  ],
+  "workflow": [
+    ".claude/skills/pr-ship/SKILL.md",
+    ".claude/skills/loop/SKILL.md",
+    ".agents/skills/pr-ship/SKILL.md",
+    ".agents/skills/loop/SKILL.md",
+    ".claude/scripts/detect-missed-gate.mjs",
+    ".claude/scripts/decision-router.mjs",
+    ".claude/scripts/reconcile-external-prs.mjs",
+    ".claude/scripts/preflight.mjs",
+    ".claude/scripts/run-state.mjs",
     ".claude/scripts/revalidate.mjs",
     ".claude/scripts/revalidation-report.mjs",
-    ".claude/scripts/lib/gate-coverage.mjs",
     ".claude/scripts/lib/claim-records.mjs",
     ".claude/scripts/lib/revalidation-evidence.mjs",
     ".claude/scripts/lib/revalidation-points.mjs",
-    ".claude/scripts/lib/verdict.mjs",
-    ".claude/scripts/lib/secrets.mjs",
-    ".claude/scripts/lib/shell-tools.mjs",
     ".claude/scripts/queue/core.mjs",
     ".claude/scripts/queue/plan-md.mjs",
     ".claude/scripts/queue/github-issues.mjs",
@@ -66,30 +78,13 @@
     ".claude/scripts/queue/gate-rounds.mjs",
     ".claude/queue.json",
     ".rig/revalidation.json",
-    "PLAN.md",
     "journal/README.md",
     "docs/decisions/gate-coverage.md",
-    "docs/decisions/fail-open-guards.md",
-    "docs/decisions/codex-adapter.md",
-    "docs/decisions/subagent-routing.md",
     "docs/decisions/closing-a-task.md",
     "docs/decisions/content-blind-revalidation.md",
-    "docs/decisions/review-lanes.md",
     "docs/decisions/run-directory.md",
     "docs/decisions/spacing-rations-mechanisms.md",
     "docs/decisions/stop-conditions-in-a-file.md",
     "docs/decisions/two-empty-endings.md"
-  ],
-  "architecture": [
-    ".claude/rules/architecture.md",
-    ".claude/hooks/guard-core-purity.mjs",
-    ".claude/hooks/guard-web-boundary.mjs"
-  ],
-  "meta": [
-    ".claude/settings.json",
-    ".codex/config.toml",
-    ".codex/hooks.json",
-    "CLAUDE.md",
-    "AGENTS.md"
   ]
 }