create-agent-rig 0.4.0 → 0.6.0

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

@@ -0,0 +1,166 @@
+# __PROJECT_NAME__
+
+> **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.
+
+## One operating system, two harnesses
+
+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`.
+
+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").

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

@@ -1,11 +1,22 @@
 # __PROJECT_NAME__
 
 > **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: Claude …`), `Generated with Claude Code`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+> 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.
 
+## One operating system, two harnesses
+
+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`.
+
 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.
@@ -42,10 +53,13 @@ them all; they are one rulebook.
 
 - **TDD, without exception.** The failing test comes first — use the
   `test-writer` agent for it. See `.claude/rules/workflow.md`.
-- **Check the task's premises before the test.** 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.
+- **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
@@ -53,17 +67,31 @@ them all; they are one rulebook.
   `.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.** `code-reviewer` before every PR; `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, this
-  file, the README. Blocking findings are resolved, not argued with, and the
+- **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; `block-no-verify` refuses pre-commit bypasses; `guard-bash` refuses
+  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
@@ -95,13 +123,20 @@ is a path the gate sweep cannot see.
 ```elevated-paths
 packages/db/src/
 .claude/
+.agents/
+.codex/
+AGENTS.md
+docs/decisions/
 .github/workflows/
 ```
 
-`.claude/` and `.github/workflows/` are there because they are what *disarms* the
-rest: a merge that rewrites the Never tier, unwires a hook or edits what CI runs
-should never pass unreviewed. `packages/db/src/` is the one the generated shape
-has.
+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

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

@@ -20,45 +20,12 @@ 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
 
-## Journal
+`journal/YYYY-MM.md` — one file per month, newest-on-top inside each. The
+convention and the field list are in `journal/README.md`.
 
-Newest first, date-free — order carries the sequence. Prune freely: this is
-operational memory, not an archive. An unattended run writes an entry at every
-stop **and** at checkpoints along the way, because a run that dies unexpectedly
-must not take its history with it.
-
-The fields exist so an entry can be visibly **incomplete**. A journal with no
-stated shape decays into a diary that reads fine and proves nothing.
-
-<!-- Template — copy the block, drop the fields that do not apply (`unblocked` is
-     the exception: it is stated even when the answer is "nothing"):
-
-### <one-line summary of the session>
-
-- **done** — what landed, one line each, with the PR reference
-- **escalated** — what stopped, and the diagnosis: what failed, what was tried,
-  the current hypothesis, and the one question whose answer unblocks it
-- **reviewed** — changes that went through a reviewer gate, and what it returned
-- **stopped at** — which stop condition ended the session (or "checkpoint,
-  still running")
-- **unblocked** — what the session's closes released. **The field that is never
-  dropped** — a missing line and an unpaid debt read identically from outside,
-  and this is the only record of whether anyone looked. It has **three**
-  answers and they do not substitute for each other: the items that were
-  waiting, by name; "nothing was waiting", where the queue carries dependency
-  links and none pointed here; and "this queue has no dependency links", where
-  it cannot answer at all — a flat-list queue is **absent**, not satisfied, and
-  writing "nothing was waiting" there claims a look that no query could perform
-- **queue hygiene** — queue state the session found unreliable and **reported**:
-  a stale marker, a dependency already satisfied, an item that describes work
-  already done. Reported, never corrected in passing — quietly fixing the
-  metadata destroys the evidence that the metadata is unreliable
-- **cost** — the counts the session actually observed: reviewer subagents run,
-  CI runs consumed (re-runs included — the cheapest signal that a task fought
-  its tests), deploys triggered
-
-     A field the session cannot observe stays **visibly empty — never estimated**.
-     A plausible number will be believed, by the next reader and by the next run
-     reasoning about its own budget. Leave the gap; it is information.
--->
+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.

package/templates/agent-os/universal/docs/decisions/closing-a-task.md

@@ -0,0 +1,98 @@
+# Why the close command looks the way it does
+
+The rule lives in the `loop` skill, section 9 ("State updates bracket the task").
+This file is the evidence behind each argument in the `recordCompletedTier`
+call, and it is not loaded into any session. Read it before "simplifying" that
+command.
+
+Four of the five were live defects; the fifth (`execFileSync` with an argument
+array) is prophylaxis. They do **not** fail the same way, and the difference is
+the whole reason each is pinned rather than left to judgement:
+
+| argument | how it fails when wrong |
+| --- | --- |
+| `-z` | silently, **permissively** — records `normal` for an elevated change |
+| `runDir` | silently, but toward a **stop** nobody can clear |
+| the diff form | **loudly** — the call refuses on an empty file list |
+| `env: withoutGitLocation()` | loudly, for the sha-to-sha form pinned here; it is prophylaxis for this call and load-bearing for every symbolic-ref spawn |
+| `execFileSync` array | it does not; nothing is interpolated into a shell today |
+
+Exactly one of the five fails silently in the permissive direction. Do not
+round that up.
+
+## `runDir`
+
+It is what resets the escalation streak: the close is the "something landed in
+between" that makes the run-level stop "two escalations **in a row**" mean two
+in a row. Omit it and the counter only ever rises — two escalations an hour
+apart end the run however many tasks closed between them.
+
+The parameter is optional in the signature. So leaving it out does not throw; it
+fails quietly, and in the direction of a stop nobody can clear.
+
+## `<merge-sha>^1 <merge-sha>`, never `origin/<default>...<merge-sha>`
+
+A three-dot diff is `merge-base..head`. Once the remote-tracking ref includes the
+merge — which is exactly its state at the moment this step runs — the merge base
+_is_ the merge, so the file list comes back **empty** and the call refuses.
+
+The three-dot form appeared to work for a while. It only ever worked while the
+local ref happened to be stale: an accident of ordering, not a property of the
+command.
+
+## `-z`, and splitting on `\0`
+
+With `core.quotePath` on (the default) a path containing a non-ASCII byte
+arrives quoted and octal-escaped — `".claude/caf\303\251.mjs"`. That string
+matches no declared elevated prefix, so an elevated change records as `normal`.
+Separately, a filename containing a newline splits into two junk paths. `-z`
+removes both failure modes at once.
+
+## `execFileSync` with an argument array, never a shell string
+
+Nothing in the current command is interpolated into a shell. The point of the
+argument array is that the next session cannot start doing so: the safe form has
+to be the one already written down, or it will not be the one copied.
+
+## `env: withoutGitLocation()`
+
+Run under a git hook, this command inherits `GIT_DIR` — absolute, when the hook
+fired in a worktree — and then resolves against **another repository**.
+
+Measured, from repository A with `GIT_DIR` pointing at an unrelated B:
+
+| form | result |
+| --- | --- |
+| `<sha>^1 <sha>` — the form pinned above | `fatal: ambiguous argument … unknown revision`, so `execFileSync` throws |
+| `HEAD^1 HEAD`, or any `origin/<default>…` form | B's file list, exit 0, nothing wrong-looking |
+
+So for this call, as written, the redirect fails loudly: a sha-to-sha diff is an
+object-database lookup, and B either lacks the object (fatal) or shares it and
+answers identically. The silent wrong answer needs a **ref that resolves
+differently in the other repo** — which is the diff form this record rejects
+two sections above.
+
+That is why the argument stays anyway. It costs nothing, it is the same line
+every other script here uses, and the moment someone "simplifies" the diff back
+to a symbolic ref it becomes the only thing standing between a git hook and a
+tier recorded from somebody else's repository.
+
+The sweep that checks `.mjs` sources for this line cannot read markdown, so the
+copy inside the rulebook's fenced code blocks is covered by a second sweep over
+those blocks. Both live in the generator that produced this project, not here —
+if you change the command above, that is the pair to re-check.
+
+## The shape the dangerous one has
+
+`-z` is the one that never announced itself: it returned a plausible answer — a
+tier of `normal` — and a plausible answer is what a run acts on, with nothing
+left behind to say it was never measured.
+
+The others are pinned because they are cheap to keep and expensive to
+rediscover, not because they all failed the same way. Reading the list as five
+silent bypasses is how the one that really is silent stops standing out.
+
+The empty-file-list case is the deliberate counter-example: `recordCompletedTier`
+**throws** rather than guessing `normal`, because an absence and a zero look
+identical in a count and mean opposite things. That refusal is the behaviour the
+loop skill relies on — do not soften it into a default.

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

@@ -0,0 +1,108 @@
+# Codex adapter: derived parity
+
+Status: accepted for AR-113.
+
+## 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.
+
+## Why
+
+Two hand-maintained rulebooks inevitably diverge. Derivation keeps the generated
+snapshots aligned while preserving native Codex formats. The adapter translates
+the fields for which Codex has native controls and does not invent policy.
+
+Claude agent `tools` allowlists have no equivalent custom-agent allowlist in the
+documented Codex TOML schema. The adapter therefore uses those fields only to
+choose `read-only` or `workspace-write` sandboxing; the exact Claude tool list is
+not carried over. This is a known parity limit, not an implicit restriction.
+
+## Risk and rollback
+
+The main risks are generated-file drift, downstream edits to only one snapshot,
+and unsupported Claude shapes. In the generator, the adapter fails loudly when
+it cannot derive a portable hook command and its drift check catches stale
+output. Generated projects rely on review for subsequent local parity. Rollback
+is deleting the derived Codex files from the generated project and reverting the
+generator change; Claude files remain usable.
+
+Hook launch also depends on `git rev-parse --show-toplevel`, and that lookup has
+two failure modes rather than one. Both are visible in `.codex/hooks.json`.
+
+The mild one: if Git is absent or the session is outside a worktree, the
+generated command exits before the hook runs and therefore cannot return the
+blocking exit code — a fail-open boundary.
+
+🔴 The sharp one, stated because a reader who only saw the first would infer
+cover that is not there: **the root is resolved from the session's working
+directory, which the agent controls, so the hook that runs is whichever file
+sits at that path.** An agent that creates a repository of its own and works
+from inside it supplies its own `.claude/hooks/*.mjs`. Measured on this branch:
+the emitted `guard-bash` command exits 2 on a force-push payload from the real
+repository root, and exits 0 from an agent-created repository holding a no-op
+hook of the same name. That is guard *substitution*, not merely fail-open.
+
+It is documented rather than fixed, deliberately, and the reasoning is worth
+keeping because the obvious alternatives are worse. Codex provides no
+project-root variable for repo-local hooks — the equivalent of Claude Code's
+`$CLAUDE_PROJECT_DIR` does not exist, and the [official hooks
+documentation](https://learn.chatgpt.com/docs/hooks) *recommends* resolving from
+the Git root for exactly this case, with commands run in the session `cwd`. So
+this adapter follows the documented pattern rather than inventing one. Pinning an
+absolute path at install time would diverge from that pattern and break a rig
+that is moved, copied or checked out as a worktree, and it would buy protection
+only against an agent that deliberately builds a decoy repository — the
+"determined evasion" `.claude/rules/invariants.md` puts outside every guard's
+threat model: *the guard targets drift, not an adversary.*
+
+What this costs is worth naming, and the first draft of this paragraph understated
+it. "Drift-resistant, not adversary-resistant" is wrong: **no adversary is
+required.** A session whose cwd sits inside any repository that is not this one —
+a vendored dependency with its own `.git`, a fixture repo, a scratch `git init` —
+resolves a root with no `.claude/hooks` in it, and the emitted command exits 1.
+Measured: exit 2 from the rig root, **exit 1 from a nested repository**, exit 1
+outside a worktree. Exit 1 is not the blocking code, so the hook layer is simply
+gone, silently, for ordinary reasons.
+
+So state it plainly: under Codex the hook layer holds when the session works from
+the rig's own root and is absent otherwise, which is one layer less than under
+Claude Code, where the harness sets the root. The layers behind it — review, the
+test suite, CI — are unchanged, and they are what this rig relies on for the
+Codex path.
+
+## Schema and executable contracts
+
+The emitted agent fields are `name`, `description`, `sandbox_mode`, and
+`developer_instructions`, matching the documented Codex custom-agent TOML.
+For hooks, the [official Codex hooks documentation](https://learn.chatgpt.com/docs/hooks)
+documents `tool_input.command` for both `Bash` and `apply_patch` and requires a
+string `command` when a hook replaces that input. The same document is what makes
+the `Bash`-only tool-name gate in `guard-bash` and `block-no-verify` correct
+rather than narrow: Codex's canonical matcher name for its shell/exec tool **is**
+`Bash`, and its editing tool is `apply_patch`, which also matches the `Edit` and
+`Write` aliases. Recorded here because it is an external fact no test in this
+repository can pin, and a reader who assumes otherwise will widen those gates to
+names the platform never sends. The guards therefore accept
+that documented string form. A command that is ABSENT still fails open — a
+payload the hook does not understand — while one that is present and is not a
+shape the normalizer reads is REFUSED, because that is a condition it detects
+and can report rather than an error it threw. See `codex.test.ts` › "refuses,
+rather than failing open, when apply_patch command is supplied as %s".
+Hook output is the JSON `description` plus event arrays accepted by
+`.codex/hooks.json`; command portability is carried by generated POSIX and
+Windows commands. In this generated project, `.claude/settings.json` and
+`.codex/hooks.json` are the two concrete hook-wiring snapshots to review.
+
+`apply_patch` inspection also has aggregate, per-patch work bounds. In
+particular, `MAX_PATCH_PATH_COMPONENTS` counts destination path components
+across the whole patch, so the file capacity of one patch decreases as path
+depth increases. When that bound is reached, split the edit into multiple
+smaller patches.

package/templates/agent-os/universal/docs/decisions/fail-open-guards.md

@@ -0,0 +1,43 @@
+# Why a fail-open guard must do provably bounded work
+
+The rule this record explains lives in `.claude/rules/invariants.md`, under
+"What the enforcement actually is — stated exactly". This file is the evidence
+behind it, and it is not loaded into any session — read it when the rule looks
+like an over-reaction.
+
+## The trap
+
+Fail-open is the right default: a guard that throws must not make the session
+unusable. But fail-open turns **every line of work the guard does into a
+potential total bypass**. An exception, a timeout, or a stack overflow anywhere
+inside the guard resolves to _allow_ — and not just for the rule that broke, for
+**all** of them. The guard does not fail loudly and get fixed; it goes quiet and
+keeps reporting success.
+
+## What actually happened
+
+Three review rounds on one hook produced three separate total bypasses. All
+three were the same shape: an input made the guard's own code throw, and the
+fail-open catch turned that into permission.
+
+| the code                                                   | the failure                | the result |
+| ---------------------------------------------------------- | -------------------------- | ---------- |
+| an unbounded `spread` over an input-derived array          | `RangeError`               | allow      |
+| a recursive expansion whose bound was per-group, not total | stack overflow             | allow      |
+| a quadratic loop                                           | killed by the hook timeout | allow      |
+
+One of them was worse than a plain bypass: when its bound was hit it silently
+dropped part of the input, so whole commands went unexamined while the guard
+reported that it had looked.
+
+That is why the test is not "is it fast enough on realistic input" but **"can
+any input make it do unbounded work at all"**. The first question has a
+comfortable answer for all three of the defects above.
+
+## Why the corollary is "prefer deleting a rule to adding one"
+
+Each of those three bypasses arrived in a commit whose stated purpose was to
+make the guard _stricter_. That is the uncomfortable part, and it is the reason
+the rule reads the way it does: subtraction cannot introduce this class of
+defect, and addition routinely does. A guard that checks less, reliably, beats a
+guard that checks more until the day an input makes it check nothing.