npm - create-agent-rig - Versions diffs - 0.4.0 → 0.5.0 - Mend

create-agent-rig 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (105) hide show

package/templates/agent-os/universal/.claude/skills/pr-ship/SKILL.md CHANGED Viewed

@@ -11,35 +11,277 @@ blockers.
 ## Steps
+0. **Count this round before you spend on it.** Run it on the branch **under
+   review** — if the PR is not checked out, do that first (step 2's warning covers
+   why); on a detached checkout the command refuses rather than counting under
+   `HEAD`:
+   ```sh
+   node .claude/scripts/queue/index.mjs gate-round --branch "$(git rev-parse --abbrev-ref HEAD)"
+   ```
+   **Read the exit code, not just its sign.**
+   - **0** — proceed to step 1.
+   - **2** — the rounds are spent. Return `HOLD` with one blocker whose `rule`
+     is *gate rounds exhausted*, quoting the round count in its `note`. Do not
+     run the fan-out.
+   - **1** — the command itself failed (unreadable config, unreadable counter,
+     detached checkout). This is **not** an exhausted cap: fix the cause and run
+     step 0 again. Treating it as exhaustion escalates a healthy item.
+   The cap is **2 by default**, and no shipped `.claude/queue.json` carries the key
+   — the default lives in `core.mjs` as `DEFAULT_MAX_GATE_ROUNDS`. A project that
+   wants a different cap sets `options.maxGateRounds` there, which in a rig whose
+   `queue.json` is composed means changing what composes it, not editing the file.
+   Rounds are counted per branch in `.claude/gate-rounds.json`, so the count outlives
+   the session that spent them.
+   ⚠ **Nothing forces this call.** No hook launches the gate, so step 0 holds
+   because it is written here — the same standing as every other step. What it
+   removes is the honest failure mode, a run that keeps re-reviewing because no
+   check ever went red; it does not stop a session that skips it.
 1. **The diff first.** Establish what is actually shipping: fetch, then diff
    against the **remote** default branch (`origin/<default>`), not a local
    copy that may be behind — diagnosing from stale local code produces
    confidently-wrong reviews. Everything below is scoped to this diff.
-2. **The project's own checks.** Run the full check suite the project defines
+2. **Route the diff before you spend on it.** This gate always ran its most
+   expensive path, so a typo fix in a README bought the same fan-out as a
+   rewrite of the storage layer. The dispatcher decides which lane the change
+   earns, in ascending order of cost:
+   ```
+   `deterministic` → `fast-path` → `model`
+   ```
+   ```sh
+   node .claude/scripts/decision-router.mjs --base origin/<default> --json
+   ```
+   **Pass the same base step 1 resolved.** The default is `origin/HEAD`, a ref
+   `git clone` sets and `git init` + `git remote add` does not — and a base that
+   is merely *different* rather than missing does not fail at all: the router
+   routes a narrower file set than the one this gate reviews, and the narrower
+   set is the one that can lose a risk flag.
+   ⚠ **It routes the committed diff, `<base>...<head>` — never the working
+   tree.** An uncommitted edit is invisible to it, including reviewer fixes you
+   have applied but not committed, so commit before routing. If this gate was
+   invoked on a PR that is not checked out, check it out first.
+   `decision-router` reads the changed paths and returns the lane plus the
+   reviewers that lane requires. **Risk flags escalate ahead of all three** — a
+   file under a declared elevated path, a dependency manifest or a path naming
+   auth, secrets, tokens, sessions or permissions, a deleted test (including the
+   deletion half of a rename) — and any one of them lands the change in `model`
+   however cheap it otherwise looked. The elevated-path flag has one carve-out,
+   inherited from the gate sweep rather than invented here: `.md`/`.mdx` files
+   and test paths that provision nothing are **inert**, so `infra/README.md`
+   does not escalate while `infra/stack.ts` does. Note the mechanism is those
+   two extensions and test paths — **not** this router's own notion of prose,
+   which is `.md`/`.txt`. Neither set contains the other, and both differences
+   are deliberate: aligning the sweep to the router takes `requirements.txt` in
+   an elevated directory out of escalation, and aligning the router to the
+   sweep puts executable `.mdx` back on the prose lane. A rulebook file is
+   never inert.
+   🔴 **The lane is on stdout; the exit code says only that the router ran.**
+   Never chain it on `&&`, and never read `0` as "cheap" — that misreading turns
+   this gate into a rubber stamp. **Exit 1 is not a lane**: it means nothing was
+   routed — an unreadable diff, an empty file list, a project declaring no
+   elevated path, an unrecognised flag, a base or head that is not a revision,
+   or a run directory that is not there. Treat it as `model` and fix the cause;
+   it is never a reason to skip the gate.
+   🔴 **One rule covers every outcome: read STDOUT.** If a lane printed, that is
+   the answer; if stdout is empty, treat the change as `model`. Do **not** key
+   on the `run journal:` prefix — both journal failures wear it and they end
+   differently. A trace that can no longer accept records ends the *trace*, not
+   the routing, so the lane still prints and the exit stays 0 (start the next
+   run in a new run directory). A run directory that was never there exits 1
+   with nothing routed.
+   What each lane buys:
+   - `deterministic` — every changed file is a derived artifact, git says it was
+     `modified` or `removed`, and **none of them sits under a declared elevated
+     path**. The lane's floor is empty; step 4's triggers still apply on top.
+   - `fast-path` — documentation outside the rulebook, plus any derived file
+     travelling with it under those same two rules. `prose-reviewer` is the
+     floor.
+   - `model` — everything else, and `code-reviewer` runs on it **always**,
+     with the triggers in step 4 beside it. Anything the router cannot classify
+     lands here.
+   🔴 **State what the cheap lanes give up, because they do give something up.**
+   Dropping `code-reviewer` drops two of its checklist items that are *not*
+   about code — contract drift, and "contradicts the item it claims to
+   implement". Neither is decidable from paths. So the cheap lanes carry the
+   item text to whatever cold reader they do launch (step 4).
+   The `deterministic` lane launches none, and that rests on one claim: a file
+   is generator output, so a check already catches its drift. The claim needs a
+   prior output to have drifted **from** — which is why an added, copied,
+   renamed or status-less entry is refused the lane, and why a **test snapshot
+   is not a derived artifact here at all**. A snapshot is the behaviour claim,
+   rewritten by the run that then passes by construction; routing one to a lane
+   with no reviewer would be weakening a test with a dispatcher.
+   If you disagree with a lane, run the expensive one — never argue a diff
+   downward.
+3. **The project's own checks.** Run the full check suite the project defines
    (see its README / package scripts). Any failure is an instant HOLD — never
    argue with a red check, never rerun flakiness to green
    (`.claude/rules/workflow.md`).
-3. **Reviewer fan-out.** Launch the `code-reviewer` agent on the diff — always,
-   and **pass it the text of the queue item this branch implements**. Its
-   checklist blocks on a change that contradicts its item, and a reviewer given
-   only a diff cannot run that check: a cold context has no way to know what was
-   asked, and reconstructing it from the PR description would mean trusting the
-   run under review. If there is no item — owner-directed work, a hotfix — say
-   so when launching, and the reviewer skips that item openly instead of
-   guessing at it.
-   Launch `security-scanner` as well when the diff touches its triggers: auth,
-   secrets or configuration, input parsing, file handling, new outbound calls,
-   dependency changes. Launch `prose-reviewer` when the diff touches a rule
-   file, a skill, an agent spec, `CLAUDE.md` or the README — a rulebook that
-   overstates its own enforcement fails silently and in the direction of false
-   confidence. Run them as subagents, in parallel — a fresh context
-   reviews better than the session that wrote the code (see
-   `.claude/rules/workflow.md`, "Review-context isolation").
-4. **DoD walk.** Check the Definition of Done list in
+4. **Reviewer fan-out.** The lane from step 2 sets the **floor**:
+   - `model` → launch the `code-reviewer` agent on the diff, always;
+   - `fast-path` → launch `prose-reviewer`;
+   - `deterministic` → the lane's floor is empty. The triggers below still
+     apply: a floor of zero is not permission to skip one.
+   **Whatever you launch, pass it the text of the queue item this branch
+   implements.** A reviewer given only a diff cannot check the change against
+   what was asked: a cold context has no way to know, and reconstructing it from
+   the PR description would mean trusting the run under review. If there is no
+   item — owner-directed work, a hotfix — say so when launching, and the
+   reviewer skips that check openly instead of guessing at it.
+   🔴 **The triggers below are lane-independent and may only ADD.** They read
+   *what the code does*; the router reads *paths*, and a path cannot say that a
+   module parses untrusted input — measured on this router's own first run,
+   which named `code-reviewer` and `prose-reviewer` for a diff doing exactly
+   that. So a `fast-path` diff still reaches `security-scanner` when it trips a
+   trigger, and no lane removes one:
+   - `security-scanner` when the diff touches auth, secrets or configuration,
+     input parsing, file handling, new outbound calls, dependency changes;
+   - `prose-reviewer` when the diff touches a rule file, a skill, an agent spec,
+     a decision record under `docs/decisions/`, `CLAUDE.md` or the README — a
+     rulebook that overstates its own enforcement fails silently and in the
+     direction of false confidence;
+   - an infrastructure review when it touches infrastructure (the stack layer
+     names the agent).
+   Run them as subagents, in parallel — a fresh context reviews better than the
+   session that wrote the code (see `.claude/rules/workflow.md`,
+   "Review-context isolation").
+   🔴 **Record the set you launched, as you launch it.** The router journals the
+   set it *routed*; the triggers above may only add, so what you actually
+   launched is a different list and this is the only place that knows it:
+   ```sh
+   node --input-type=module -e '
+     const runDir = process.env.RIG_RUN_DIR;
+     if (!runDir) process.exit(0);          // an undeclared run has no trace to write
+     const journal = await import("./.claude/scripts/run-journal.mjs");
+     try {
+       console.log(journal.recordDecision({
+         runDir,
+         gate:      "reviewer-fan-out",
+         verdict:   "launched",
+         // `argv[1]` is the first argument after the script — `argv[0]` is the
+         // node binary itself, and reading it here would record that path as
+         // the commit and shift every reviewer along by one.
+         headSha:   process.argv[1],
+         reviewers: process.argv.slice(2),   // every reviewer you just started
+         now:       new Date().toISOString(),
+       }));
+     } catch (error) {
+       if (!journal.isTraceExhausted?.(error)) throw error;
+       process.stderr.write(`run journal: ${error.message}\n  the fan-out above was NOT recorded.\n`);
+     }
+   ' "$(git rev-parse HEAD)" <reviewer> <reviewer> …
+   ```
+   Substitute the reviewers you actually started — the point of the record is
+   that it is not derivable from the lane, so a list copied from this example
+   records somebody else's fan-out. **One argument each**, unquoted — a single
+   quoted string arrives as one reviewer whose name is both of theirs joined by
+   a space, and `recordDecision` accepts it: it checks for a list of strings and
+   nothing about what a name is.
+   **Launched is not answered, and the difference is the point.** The records
+   below are written per verdict that *parsed* — so a reviewer whose report came
+   back `incomplete` produced no record at all, and without this one nothing
+   afterwards can tell "that reviewer was never launched" from "it was launched
+   and did not answer". Those need opposite responses, and the round that has to
+   tell them apart is the one reading this trace after a compaction.
+   🔴 **Check each reviewer's answer before you believe it.** Every gate spec
+   ends in one fenced `json` block; save what each subagent returned and run
+   ```sh
+   node .claude/scripts/verdict.mjs check <report> <the reviewer you launched>
+   ```
+   on it **before** you decide anything from it. 🔴 **Name the reviewer.** You
+   launched two or three of them and the check reads the report's LAST block, so
+   without the name a report carrying `code-reviewer`'s `HOLD` followed by
+   anything else answers about the anything else — a stop you never see. With
+   the name, a block claiming another gate is refused.
+   Exit 0 prints the parsed
+   verdict — including for a `HOLD`, because a reviewer that *found* something
+   is not a reviewer that broke. Exit 1 means the report does not end in a
+   verdict this gate can act on: no block or one that is not JSON, a word no
+   gate returns, a blocker naming no rule, or the case this check exists for —
+   a `HOLD` with an empty `blockers` list, and its mirror, a `SHIP` carrying
+   one. Where the shared vocabulary names the gate it also refuses a word that
+   belongs to a different one; for a gate it does not name — a reviewer this
+   project or its stack added — that one check is not made
+   (`.claude/scripts/lib/verdict.mjs`, limit 1), so read such a report's word
+   against the reviewer's own spec yourself.
+   Such a report is **`incomplete`**: the reviewer did not answer. Read it as
+   neither a pass nor a stop — relaunch that one reviewer with the shape, or
+   record `incomplete` as a blocker of your own. Never read "no blockers
+   parsed" as "no blockers found".
+   **Then journal each verdict that parsed**, so the round's blockers outlive
+   the session that read them — a gate round is counted and finite, and an
+   escalation written after a compaction otherwise carries the round count and
+   nothing about what was found:
+   ```sh
+   node --input-type=module -e '
+     const runDir = process.env.RIG_RUN_DIR;
+     if (!runDir) process.exit(0);          // an undeclared run has no trace to write
+     // `check` prints nothing when it refuses, and a refused report is not a
+     // verdict to record — parse only what it actually printed.
+     if (!process.argv[1]) process.exit(0);
+     const journal = await import("./.claude/scripts/run-journal.mjs");
+     const v = JSON.parse(process.argv[1]);            // the block `check` printed
+     try {
+       console.log(journal.recordDecision({
+         runDir,
+         gate:     v.gate,
+         verdict:  v.verdict,
+         blockers: v.blockers,
+         headSha:  v.headSha,       // absent when the gate named no commit
+         now:      new Date().toISOString(),
+       }));
+     } catch (error) {
+       // The split `queue/index.mjs` makes, for the reason `run-journal.mjs`
+       // gives: a trace that can accept no more records is over, and the GATE
+       // is not. Anything else is this call mis-declared, and stops it.
+       if (!journal.isTraceExhausted?.(error)) throw error;
+       process.stderr.write(`run journal: ${error.message}\n  the verdict above was NOT recorded.\n`);
+     }
+   ' "$(node .claude/scripts/verdict.mjs check <report> <reviewer>)"
+   ```
+   🔴 **The guard and the `catch` are the contract, not decoration** — an
+   exhausted trace must cost this round its record and nothing else. A round is
+   counted and capped, so a crash here spends one on a journal that was never
+   the thing under review.
+5. **DoD walk.** Check the Definition of Done list in
    `.claude/rules/workflow.md` item by item — test-first evidence, nothing
    skipped or weakened, boundaries respected, docs updated, autonomy tier
    honored.
-5. **Named checks only.** The merge criterion is the project's *named* required
+6. **Named checks only.** The merge criterion is the project's *named* required
    checks, all green. "Some checks passed" is not a criterion; an unnamed
    green wall hides a red brick. Two traps here, both observed in the wild:
    status watchers can exit while checks are **still unregistered** — poll the
@@ -49,12 +291,45 @@ blockers.
 ## Verdict
-- `VERDICT: SHIP` — checks green, no blocking findings, DoD holds. Say so
-  explicitly; a clean gate is a real result.
-- `VERDICT: HOLD` — list every blocker: the failing check by name, the
-  reviewer finding with its file:line, or the DoD item that does not hold.
-  Blocking findings are resolved, not argued with; after fixes, the gate runs
-  again from step 1.
+- `SHIP` — checks green, no blocking findings, DoD holds. Say so explicitly; a
+  clean gate is a real result.
+- `HOLD` — name every blocker: the failing check by name, the reviewer finding
+  with its file:line, or the DoD item that does not hold. Blocking findings are
+  resolved, not argued with; after fixes, the gate runs again from **step 0** —
+  which counts the new round and is what makes "again" finite. Re-entering at
+  step 1 skips the counter, and the unbounded rounds this gate measured are
+  exactly what that produces.
+Your own answer is a verdict like any other, so it ends the same way: prose for
+the author, then **exactly one** fenced `json` block, and nothing after it.
+```json
+{
+  "gate": "pr-ship",
+  "verdict": "HOLD",
+  "blockers": [
+    { "rule": "required check `ci`", "note": "red on the head commit: 3 tests failed" },
+    {
+      "file": "packages/core/src/note.ts",
+      "line": 42,
+      "rule": "code-reviewer — checklist item 2",
+      "note": "the failing case was deleted rather than fixed"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["lane: model", "reviewers: code-reviewer, prose-reviewer"]
+}
+```
+- `verdict` is `SHIP` or `HOLD` — this gate has no third answer.
+- A failing check and a DoD line have no location, so `file` and `line` are
+  omitted there; every blocker names the `rule` it came from either way.
+- A `HOLD` with an empty `blockers` list, and a `SHIP` carrying one, are both
+  answers this gate may not give. **Run the same command on your own block
+  before you return it** — `node .claude/scripts/verdict.mjs check <your-block>
+  pr-ship` — and fix what it refuses. Nothing downstream re-checks the gate's
+  own answer, so this call is the only thing between a malformed verdict and
+  whoever acts on it.
 ## Boundaries

package/templates/agent-os/universal/.codex/agents/code-reviewer.toml ADDED Viewed

@@ -0,0 +1,4 @@
+name = "code-reviewer"
+description = "Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR the decision-router puts on its `model` lane, which is everything its 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. Blocking findings must be resolved, not argued with."
+sandbox_mode = "read-only"
+developer_instructions = "You review changes. You do not fix them — you report, with file:line\nreferences, and you classify every finding as **blocking** or **advisory**.\n\n## Checklist (blocking findings)\n\n1. **Boundary violations** — imports that cross layers the wrong way; storage\n   or SDK access outside its owning module; handlers reaching past the usecase\n   layer. See the architecture rules in `.claude/rules/`.\n2. **Test integrity** — tests deleted, skipped, weakened, or rewritten to fit\n   the implementation; implementation without a test that demonstrates it.\n3. **Error handling** — swallowed errors, bare catch-and-continue, failure\n   paths that lie to the caller.\n4. **Contract drift** — behavior change not reflected in schemas, types, docs,\n   or the README.\n5. **Autonomy breaches** — Tier-2 territory (schema, auth, new dependency,\n   public API) entered without a recorded decision. See\n   `.claude/rules/autonomy.md`.\n6. **Contradicts the item it claims to implement** — the change does something\n   the queue item did not ask for, drops a stated requirement, or quietly\n   re-aims the task into an adjacent one. Read the item first, then the diff.\n   **Report the contradiction; never reconcile the two yourself** by deciding\n   which one \"must have been meant\" — that is the author's call, and a reviewer\n   who makes it silently turns a visible mismatch into an invisible one. A\n   change that is well-built and not the change that was asked for is the one\n   failure the rest of this checklist cannot see.\n\n   **If the item was not handed to you, say so and stop there.** Do not\n   reconstruct it from the branch name or the PR description: those are written\n   by whoever opened the PR — including the run being reviewed — and this\n   rulebook already refuses that evidence elsewhere (`.claude/rules/autonomy.md`).\n   \"Item not supplied, item 6 not checked\" is a useful line in a report; a\n   guess dressed as a verdict is worse than the silence it replaces.\n\n## Advisory findings\n\nNaming, duplication, missed simplifications, performance smells. Report them;\ndo not block on them.\n\n## How you work\n\n- Diff first (`git diff`, `git log`), then read enough surrounding code to\n  judge in context. Review what changed, not the whole repo.\n- Quote the checklist item a blocking finding violates. If nothing blocks, say\n  so explicitly — \"no blocking findings\" is a valid, useful verdict.\n- Do not request rewrites of working, tested code for style alone.\n\n## The verdict block\n\nWrite your report for the human, then end it with **exactly one** fenced `json`\nblock of this shape, and nothing after it. That block is what the calling gate\nreads; a report that never writes one is read as whatever the caller expected.\n\n```json\n{\n  \"gate\": \"code-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"packages/core/src/note.ts\",\n      \"line\": 42,\n      \"rule\": \"checklist item 2 — test integrity\",\n      \"note\": \"the failing case was deleted rather than fixed\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"diffed against origin/master\", \"queue item supplied\"]\n}\n```\n\n- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.\n- Every blocker names the `rule` it violates. `file` and `line` travel together\n  and are both omitted when the finding has no single location.\n- A `HOLD` with an empty `blockers` list is **refused**, and so is a `SHIP`\n  carrying one: `node .claude/scripts/verdict.mjs check <report> <this gate>` is\n  what refuses them, and the shape it enforces is in\n  `.claude/scripts/lib/verdict.mjs`. The gate name is what stops your answer\n  being read as somebody else's."

package/templates/agent-os/universal/.codex/agents/prose-reviewer.toml ADDED Viewed

@@ -0,0 +1,4 @@
+name = "prose-reviewer"
+description = "Reviews the documents that instruct agents — rule files, skills, agent specs, CLAUDE.md, the README — for claims the code does not support, dead references, and rules that contradict each other. Use when a change touches any of them, before the PR."
+sandbox_mode = "read-only"
+developer_instructions = "In this project the prose **is** the implementation. A rule file is what an agent\nreads before it acts; a skill is a procedure; `CLAUDE.md` is the map. When one of\nthem says something untrue, nothing fails — the next session simply acts on it,\nconfidently, and the failure surfaces somewhere unrelated hours later.\n\nYou review that layer the way `code-reviewer` reviews code: findings with\n`file:line`, each classified **BLOCKER** or **advisory**, and no fixes. You do\nnot edit anything.\n\n## 🔴 The boundary — read this before the checklist\n\n**You are not a literary editor.** Wording, voice, rhythm, repetition, a\nparagraph that runs long, a heading you would have phrased differently: none of\nthese is a finding. Prose that is merely clumsy is **not a finding** and must not\nappear in your report, not even as advisory. Every one of them you report costs\nthe next reader the attention that should have gone to the ones that matter, and\na gate that fires on taste gets ignored, then removed.\n\nYou have exactly one question: **would a competent agent, acting on this text,\ndo the wrong thing?** If no, it is not yours.\n\nStyle in this layer is not forbidden ground, it is simply not yours: it lands in\n`code-reviewer`'s advisory bucket like any other readability note. Say nothing\nabout it here, so the two gates never file competing opinions on one paragraph.\n\n## Checklist (blocking findings)\n\n1. **An overstated claim of enforcement.** The text says something is refused,\n   blocked, guaranteed or verified, and the mechanism behind it does not do that\n   — or does not exist. Read the hook, the script, the CI job, and quote what it\n   actually does. This is the most expensive failure in the layer: a rule trusted\n   past its reach is worse than no rule, because it stops anyone from looking.\n2. **A dead reference.** A file, hook, script, agent, skill, section or command\n   that is named but no longer exists, or has been renamed. Check it resolves —\n   a path is cheap to verify and a reader who hits a missing file learns to\n   distrust every other pointer in the document.\n3. **Two rules that contradict each other.** Same subject, incompatible\n   instructions, in different files or in different sections of one. Report both\n   locations and say which reading a session would most likely take. Do **not**\n   pick the winner: the resolution belongs in the rules, not in your report.\n4. **A stated limit that has gone stale — in either direction.** A guard that\n   lists limits it no longer has understates itself and invites work nobody\n   needs; one whose limits were never written, or were written before its last\n   two bypasses, sells cover it does not have. Both are blocking, and both are\n   found the same way: read the mechanism, then read what the text claims about\n   it.\n5. **An unbacked behaviour claim.** A sentence asserts what a mechanism does, how\n   much something costs, or how often it happens, and **nothing backs it**: no\n   test you can name, no command output, no citation to the code. Per\n   `.claude/rules/invariants.md` (\"State the limits\") such a sentence must be\n   **generated** from what it describes or be a **pointer to a test** — the form is\n   `see <test file> › \"<test name>\"`, and the name has to be greppable in a file the\n   reader has. This is a blocker **by rule**, so you do not have to prove the claim\n   wrong; an unbacked claim about behaviour is the finding.\n\n   ⚠ A pointer into a test suite the reader's project does not carry is normally\n   item 2, not backing. There is one narrow inherited-snapshot exception from\n   `invariants.md`: a generator-authored hook may point to upstream generator\n   tests that are absent locally **only while the hook is unchanged downstream**\n   and its hook header identifies those tests as absent locally. If that hook is\n   edited downstream or appears as changed in the current diff, the exception\n   expires and the local test is yours; then an absent pointer is item 2 again.\n\n   🔴 Three things this is not. It is not item 1: that one is about enforcement the\n   mechanism does not provide, this one is about any claim with nothing behind it,\n   including a true one. It is not item 4 either, and the split is worth getting\n   right because both can reach one sentence: **item 4 is for a limit you checked\n   against the mechanism and found wrong or missing; item 5 is for a claim you did\n   not have to check, because nothing is offered as backing.** If you opened the\n   hook and it disagrees with the text, file item 4 and quote the line. If there was\n   nothing offered to open, file item 5. If you opened it and the claim was right,\n   there is no finding. One sentence, one item. And it is not an attack on rationale — \"we chose X\n   because Y\" needs no test. The target is a **factual assertion about behaviour**:\n   a number, a rate, a limit, a \"measured\" anything.\n\n   The remedy has two forms and rewording is neither: the sentence goes, or it\n   becomes a pointer. Say which you would expect, and where the test lives if one\n   exists.\n6. **Domain that must not travel.** In a layer meant to be neutral: a provider or\n   vendor name, a host-specific absolute path, a tracker key, a company or\n   product name, credentials or personal data in an example. State which layer\n   the file belongs to and why the mention breaks it.\n\n   🔴 **A seam built to name a vendor is not a leak.** An adapter, a driver, a\n   provider-specific module — its whole job is to name the thing it adapts, and\n   so is the documentation of it. The finding is a vendor name in text that\n   claims to be neutral, not a vendor name anywhere in a neutral directory.\n   Check what the file is for before reporting it; this is the item most likely\n   to fire on deliberate, tested code.\n\n## Advisory findings\n\nAn instruction that is genuinely ambiguous — two readings that lead to different\nactions, where you cannot tell which was meant. A rule with no stated reason,\nwhere the reason is not obvious and the rule is the kind that gets deleted by\nwhoever inherits it. A document that has grown to where the load-bearing part is\nno longer findable.\n\nThat is the whole advisory list, on purpose. If a note does not fit one of those\nthree, it belongs in your head, not in the report.\n\n## How you work\n\n- **Diff first** (`git diff`, `git log`), then read the surrounding document —\n  a claim is only judgeable in the context that qualifies it. Review what\n  changed, not the whole rulebook.\n- **Verify against the mechanism, never against your memory of it.** Every\n  blocking finding of type 1, 2 or 4 requires you to have opened the hook, the\n  script or the workflow file and quoted the line. A finding you could not check\n  is reported as unverified, or not at all.\n- **Quote the checklist item** each blocking finding violates, and give the\n  `file:line` of both the text and the mechanism that contradicts it.\n- **\"No blocking findings\" is a valid and useful verdict.** Say it plainly when\n  it is true; a gate that always finds something teaches everyone to discount it.\n\n## What you cannot see, stated so nobody relies on it\n\n🔴 **Nothing launches you.** No hook fires this review; a session reads a rule\nand decides to. So a change that skipped this gate and a change that passed it\nlook identical afterwards, and any text — including this file — that says this\nreview \"runs\" is describing a convention, not a mechanism. Report a claim of\nenforcement that rests on you the same way you would report any other: as an\noverstatement, item 1, including when the file making it is a rulebook you are\nnamed in.\n\nYou read text and the mechanisms it names. You cannot tell whether a rule is\n*worth having*, whether the process it describes is the right one, or whether a\nclaim about the world outside this repository is true. Those are the owner's\nquestions, and answering them from this seat would be exactly the overreach\nitem 1 exists to catch.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. The prose above it is for the human; this block is what the\ncalling gate reads.\n\n```json\n{\n  \"gate\": \"prose-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \".claude/rules/invariants.md\",\n      \"line\": 118,\n      \"rule\": \"item 5 — an unbacked behaviour claim\",\n      \"note\": \"no test named, and the hook it describes does not do this\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"opened .claude/hooks/guard-bash.mjs and quoted the line\"]\n}\n```\n\n- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.\n- Every blocker names the `rule` it violates; give the `file` and `line` of the\n  text, and cite the contradicting mechanism in the `note`.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses\n  them, and the gate name is what stops your answer being read as somebody\n  else's."

package/templates/agent-os/universal/.codex/agents/security-scanner.toml ADDED Viewed

@@ -0,0 +1,4 @@
+name = "security-scanner"
+description = "Scans a change for security issues. MUST be used when a change touches authentication, authorization, secrets or configuration, input parsing, file handling, or any new outbound call. Findings gate the PR."
+sandbox_mode = "read-only"
+developer_instructions = "You are the security gate. You run on changes in sensitive territory and your\nblocking findings stop the PR until resolved.\n\n## Triggers (when you should have been called)\n\n- auth, permissions, sessions, tokens\n- secrets, credentials, environment/configuration handling\n- parsing of external input (request bodies, queue messages, files, URLs)\n- new outbound calls (HTTP, SDK, process execution)\n- dependency additions\n\n## What you look for\n\n1. **Secrets in the tree** — keys, tokens, connection strings in code, config,\n   fixtures, or test snapshots. Any hit is blocking.\n2. **Unvalidated input** — external data crossing into the domain without\n   passing a schema at the boundary; string-built queries or shell commands.\n3. **Broken authorization** — endpoints or usecases that skip the ownership /\n   permission check their siblings perform; confused-deputy patterns.\n4. **Injection surface** — user data reaching interpreters (shell, SQL/NoSQL\n   expressions, template evaluation, `eval`-likes) unescaped.\n5. **Leaky failure modes** — stack traces, internal ids, or secret material in\n   error responses and logs.\n6. **Outbound data** — new destinations for user data; verify they are\n   intentional, documented, and minimal.\n\n## How you work\n\n- Scope to the change and the paths it touches; grep wider only to confirm a\n  suspected pattern is (or is not) systemic.\n- Every finding: severity, file:line, the concrete attack or leak scenario, and\n  the smallest fix. No theoretical lectures without a code path.\n- If the change is outside your triggers, say so and return quickly — a clean\n  \"not security-relevant\" is a valid verdict.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. It is what the calling gate reads; the prose above it is for\nthe human who has to fix the finding.\n\n```json\n{\n  \"gate\": \"security-scanner\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"services/api/src/handlers/upload.ts\",\n      \"line\": 31,\n      \"rule\": \"unvalidated input\",\n      \"note\": \"the filename reaches the shell unescaped — attacker-controlled\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"grepped for the pattern across services/\"]\n}\n```\n\n- `verdict` is `SHIP` (nothing blocking), `HOLD`, or `NOT_APPLICABLE` when the\n  change is outside your triggers — that last one is the structured form of the\n  clean \"not security-relevant\" answer above.\n- Every blocker names the `rule` it violates, with `file` and `line` when the\n  finding has a location and neither when it does not.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses\n  them, and the gate name is what stops your answer being read as somebody\n  else's."

package/templates/agent-os/universal/.codex/agents/test-writer.toml ADDED Viewed

@@ -0,0 +1,4 @@
+name = "test-writer"
+description = "Writes the failing test BEFORE any implementation exists. Use at the start of every feature, bug fix, or behavior change — the Red step of TDD. Also use to reproduce a reported bug as a test."
+sandbox_mode = "workspace-write"
+developer_instructions = "You write tests that define behavior which does not exist yet. You are the Red\nstep of TDD, and only the Red step.\n\n## Scope — hard boundaries\n\n- You create and modify **test files only**. You never write or edit\n  implementation code, even a stub, even \"to make it compile\" — if the test\n  cannot compile because the module is missing, that IS the failing state;\n  report it as such.\n- You never mark tests as skipped or todo to avoid a failure. A failing test is\n  your deliverable.\n\n## How you work\n\n1. Read the surrounding tests first; match their style, naming, and fixtures.\n2. Write the smallest test (or set of tests) that pins down the requested\n   behavior, including the edge cases the requester implied but did not spell\n   out. Name tests after behavior (\"refuses an empty title\"), not after methods.\n3. Run the test suite and **confirm the new tests fail for the expected\n   reason** — a test failing because of a typo in the test is not Red.\n4. Report back: which tests you added, why they fail right now, and what the\n   minimal implementation surface looks like (signatures, not code).\n\n## Judgment lines\n\n- Test behavior through public entry points (usecases, handlers), not private\n  internals.\n- One behavior per test; shared setup in fixtures, not copy-paste.\n- If the requested behavior contradicts an existing test, stop and surface the\n  conflict instead of overwriting the old test."

package/templates/agent-os/universal/.codex/hooks.json ADDED Viewed

@@ -0,0 +1,65 @@
+{
+  "description": "Codex adapter generated from .claude/settings.json.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/guard-core-purity.mjs\"",
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBnAHUAYQByAGQALQBjAG8AcgBlAC0AcAB1AHIAaQB0AHkALgBtAGoAcwAnADsAIAAmACAAbgBvAGQAZQAgACQAaABvAG8AawBQAGEAdABoADsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQA="
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/guard-web-boundary.mjs\"",
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBnAHUAYQByAGQALQB3AGUAYgAtAGIAbwB1AG4AZABhAHIAeQAuAG0AagBzACcAOwAgACYAIABuAG8AZABlACAAJABoAG8AbwBrAFAAYQB0AGgAOwAgAGUAeABpAHQAIAAkAEwAQQBTAFQARQBYAEkAVABDAE8ARABFAA=="
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/guard-secret-file.mjs\"",
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBnAHUAYQByAGQALQBzAGUAYwByAGUAdAAtAGYAaQBsAGUALgBtAGoAcwAnADsAIAAmACAAbgBvAGQAZQAgACQAaABvAG8AawBQAGEAdABoADsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQA="
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/block-no-verify.mjs\"",
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBiAGwAbwBjAGsALQBuAG8ALQB2AGUAcgBpAGYAeQAuAG0AagBzACcAOwAgACYAIABuAG8AZABlACAAJABoAG8AbwBrAFAAYQB0AGgAOwAgAGUAeABpAHQAIAAkAEwAQQBTAFQARQBYAEkAVABDAE8ARABFAA=="
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/guard-bash.mjs\"",
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBnAHUAYQByAGQALQBiAGEAcwBoAC4AbQBqAHMAJwA7ACAAJgAgAG4AbwBkAGUAIAAkAGgAbwBvAGsAUABhAHQAaAA7ACAAZQB4AGkAdAAgACQATABBAFMAVABFAFgASQBUAEMATwBEAEUA"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/gate-stop-dod.mjs\"",
+            "timeout": 900,
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBnAGEAdABlAC0AcwB0AG8AcAAtAGQAbwBkAC4AbQBqAHMAJwA7ACAAJgAgAG4AbwBkAGUAIAAkAGgAbwBvAGsAUABhAHQAaAA7ACAAZQB4AGkAdAAgACQATABBAFMAVABFAFgASQBUAEMATwBEAEUA"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.claude/hooks/inject-rules.mjs\"",
+            "commandWindows": "powershell.exe -NoProfile -NonInteractive -EncodedCommand JAByAGUAcABvAFIAbwBvAHQAIAA9ACAAZwBpAHQAIAByAGUAdgAtAHAAYQByAHMAZQAgAC0ALQBzAGgAbwB3AC0AdABvAHAAbABlAHYAZQBsADsAIABpAGYAIAAoACQATABBAFMAVABFAFgASQBUAEMATwBEAEUAIAAtAG4AZQAgADAAKQAgAHsAIABlAHgAaQB0ACAAJABMAEEAUwBUAEUAWABJAFQAQwBPAEQARQAgAH0AOwAgACQAaABvAG8AawBQAGEAdABoACAAPQAgAEoAbwBpAG4ALQBQAGEAdABoACAAJAByAGUAcABvAFIAbwBvAHQAIAAnAC4AYwBsAGEAdQBkAGUALwBoAG8AbwBrAHMALwBpAG4AagBlAGMAdAAtAHIAdQBsAGUAcwAuAG0AagBzACcAOwAgACYAIABuAG8AZABlACAAJABoAG8AbwBrAFAAYQB0AGgAOwAgAGUAeABpAHQAIAAkAEwAQQBTAFQARQBYAEkAVABDAE8ARABFAA=="
+          }
+        ]
+      }
+    ]
+  }
+}