create-agent-rig 0.4.0 → 0.6.0

package/templates/agent-os/universal/.claude/rules/invariants.md

@@ -63,9 +63,38 @@ That is enough, because it stops the normal path cold and the layers behind it
 enforcement has to describe its enforcement precisely, or the first surprise
 costs it all its credibility.
 
-**Fail closed on a match, fail open on an error.** If the hook itself throws or
-gets a payload it does not understand, it must allow the edit. A crashed guard
-that blocks everything gets deleted within the hour.
+**Fail closed on a match, fail open on an error.** If the hook itself throws, or
+is handed a payload it cannot even tell apart from noise, it must allow the edit.
+A crashed guard that blocks everything gets deleted within the hour.
+
+**Refusing to inspect is a third outcome, not a match and not an error** — and it
+has two members, which the first version of this rule collapsed into one.
+
+- **A bound was crossed.** The payload is readable and inspecting it safely would
+  cost more than the guard is allowed to spend. It blocks, names the limit, and
+  tells the caller to split the change and retry — which is advice they can act
+  on, because a smaller edit really does fit.
+- **The container is unreadable.** The guard can see *what* it was handed and
+  cannot read it: an `apply_patch` command that is neither a string nor a list of
+  strings, a `tool_input` that is not an object at all. It blocks, names the
+  shape it expected, and tells the caller to resend in that shape. It must **not**
+  say "split and retry": nothing about splitting changes a container, and a
+  remedy the caller cannot act on turns a refusal into a loop.
+
+🔴 **The line between "unreadable" and "not understood" is whether the guard can
+detect it**, and getting it backwards costs a credential either way. A field that
+is simply ABSENT is the fail-open case — the guard has nothing to judge, exactly
+as it has nothing to judge when a `Write` carries no content. A field that is
+PRESENT in a shape the guard does not accept is the refusal case: it was handed
+something, it could tell that it could not read it, and reporting that is the
+one thing it is for. This distinction was written after a guard reported out
+loud that it had not looked and returned the value meaning "there was nothing to
+look at" — the edit landed, with a credential in it.
+
+**The remedy belongs to the refusal, not to the guard that prints it.** Carry it
+as a field beside the reason, decided where the reason is decided. Choosing it
+by pattern-matching the reason's wording works until somebody rewords the reason,
+and then every copy of the guard silently prints the wrong advice.
 
 **A guard that fails open must do provably bounded work — and this is the rule
 that cost the most to learn.**
@@ -75,15 +104,6 @@ means **every line of work the guard does is a potential total bypass**. Any
 exception, any timeout, any stack overflow inside it resolves to *allow* — not
 for the rule that broke, for **all** of them.
 
-Three review rounds on one hook produced three separate total bypasses, and all
-three were the same shape: an input made the guard's own code throw, and the
-fail-open catch turned that into permission.
-
-- 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.
-
 So the test is not "is it fast enough on realistic input" but **"can any input
 make it do unbounded work at all"**. In practice:
 
@@ -92,12 +112,16 @@ make it do unbounded work at all"**. In practice:
   then spread;
 - one forward pass; no rescanning, no loop that re-copies the whole string;
 - when a bound is hit, fail **closed** or keep the input intact — never silently
-  drop part of it, which is how one of those bypasses hid whole commands.
+  drop part of it, which is how one past bypass hid whole commands from the
+  guard while it reported that it had looked.
 
 And the corollary that follows from all of it: **prefer deleting a rule to adding
-one.** Each of those three bypasses arrived in a commit whose purpose was to make
-the guard stricter. Subtraction cannot introduce this class of defect; addition
-routinely does.
+one.** Subtraction cannot introduce this class of defect; addition routinely
+does.
+
+The three bypasses this rule was paid for — what each one was, and why the
+corollary is subtraction rather than more care — are in
+`docs/decisions/fail-open-guards.md`.
 
 ## State the limits — and test them
 
@@ -112,6 +136,31 @@ rely on cover that is not there) or into staleness (limits listed that were
 fixed long ago, understating the guard). Both have happened here, in the same
 file, within one review cycle.
 
+**A sentence describing what a mechanism does or does not do is either generated
+from the thing it describes, or a pointer to the test that proves it** — the form is
+`see guard-invariant.example.test.mjs › "blocks the violation, and the reason names
+what to do instead"` — the test's whole name, so one grep lands on it, in a file the
+reader has. Free-standing prose about a mechanism's behaviour is a
+`prose-reviewer` blocker **by rule** (its checklist item 5), which means the finding
+is the absence of backing; nobody has to prove the claim wrong first.
+
+Why by rule rather than by discovery: it moves the check earlier. `check-premises`
+has a second entry point on the run's own prose, and it returns `UNMEASURED` for a
+claim with nothing behind it — before the gate, instead of after a cold reader has
+read the whole diff.
+
+Two exits from `UNMEASURED`, and rewording is not one of them: **delete the
+sentence, or make it a pointer.** Softening the wording leaves an unbacked claim in
+a document agents follow literally, which is the failure this whole section is
+about. A pointer also cannot quietly drift, because a renamed test makes it a dead
+reference — item 2 of the same checklist.
+
+⚠ **This norm has parts 1 and 3 of the pattern above, and not part 2.** No hook
+refuses an unbacked sentence; the check is a skill a session is told to run and the
+backstop is a reviewer nothing launches. By this file's own standard that makes it a
+rule with a reader behind it rather than a mechanism — stated here so the next
+reader does not infer cover that is not there.
+
 Two rules that follow from it:
 
 - **Match a rule's precision to the cost of a false positive.** Where a false
@@ -119,9 +168,28 @@ Two rules that follow from it:
   deliberately coarse and stop trying to out-parse the input. Where a false block
   interrupts ordinary work, stay narrow and specific. Uniform precision
   everywhere is how a guard ends up simultaneously too loose and too annoying.
-- **One mechanism, one implementation.** If two files enforce the same
-  invariant, they will disagree — and the one nobody is looking at is the one
-  that is wrong. Export it from a single module and import it.
+- **One mechanism, one implementation.** And one spelling of a fact. If two
+  files enforce the same invariant, they will disagree — and the one nobody is
+  looking at is the one that is wrong. Export it from a single module and import
+  it. The same holds for any mechanically expressible fact two artifacts encode
+  — a list, a vocabulary, a set of paths, a lane's reviewer floor: prefer one
+  source that the others derive from or are generated from. Where a second copy
+  has to stay (prose a reader needs), put a correspondence check between the two
+  that goes red in both directions — a copy that gains an entry the source
+  lacks, and a source that gains one the copy lacks — and put that check in
+  before adding prose or a memory note about keeping them aligned. The shape is
+  in the generator's `test/template/correspondence.test.ts` (absent in a
+  generated rig): the check itself, ›
+  "every point the module knows is named by the loop or pr-ship skill, and vice versa"
+  and ›
+  "the pr-ship fan-out bullets name exactly the floor of each lane, and only known lanes";
+  and the proof that it names the offender, one mutation per side, ›
+  "reports a point named in prose that no script knows (mutation: BEFORE_MERGE)",
+  › "reports a point the module knows that no prose mentions (mutation: extended POINTS)",
+  › "reports a reviewer added to a bullet the floor does not include (mutation: prose)"
+  and › "reports a floor widened in the mapping that the prose does not carry (mutation: mapping)".
+  What such a check costs is written where the check is, in the header of the
+  file that carries it.
 
 ## The worked example — and it is one project's answer, not a law
 
@@ -153,6 +221,12 @@ in this repository — so by the rule above, as they sit here, they are checks
 without tests. That is deliberate and it has a boundary: it holds only while they
 are untouched.
 
+This is the one narrow exception for a generator-authored hook: it may cite the
+generator's upstream tests **only while unchanged downstream**, and its hook
+header must identify the upstream generator tests as absent locally. That pointer
+records the evidence used to author the inherited snapshot; it does not turn the
+absent test into a local check.
+
 **The moment you edit one, its test is yours.** A guard whose behaviour has
 changed and whose test lives somewhere else is precisely the "quietly stopped
 matching" case this rule names, and nothing here would catch it. The same applies
@@ -162,6 +236,17 @@ If a hook matters enough to keep, it is worth ten minutes to copy the shape from
 `.claude/skills/new-invariant/guard-invariant.example.test.mjs` and pin the
 behaviour you actually rely on.
 
+**That boundary is audited, not remembered.** `node .claude/scripts/doctor.mjs`
+reads `.claude/.rig-manifest.json` and asks of every hook in `.claude/hooks/` (and
+`.husky/`, when it exists) whether the project owns it — the bytes differ from
+what the generator installed, or the manifest has no entry — and, if so, whether
+`<hook>.test.mjs` sits beside it. A shipped, unchanged hook is not a finding; an
+owned hook with no neighbour is; a rig with no manifest gets `unknown` for every
+hook that has no test neighbour, never a pass. Exemptions are an explicit list with reasons in
+`.claude/doctor-exemptions.json`, and the report ends with what the script did
+not check. Pinned in the generator's `test/template/doctor.test.ts` — absent in a
+generated rig — › "an owned hook without a test is a FAIL, and the run is STOP".
+
 ## Adding one
 
 Use the `new-invariant` skill. It asks what the invariant is (it will not invent

package/templates/agent-os/universal/.claude/rules/workflow.md

@@ -47,19 +47,69 @@ travels one path to merge, in this order:
 
 1. **Local checks** — the full suite, lint, typecheck, all green locally first.
    A red check is information, never something to retry until green (`autonomy.md`).
-2. **Reviewer fan-out**, by what the change touches:
-   - the `code-reviewer` agent **always**;
+2. **Reviewer fan-out**, by what the change touches — and *how much* fan-out is
+   decided first, in ascending order of cost:
+
+   | lane | what reaches it | the floor it sets |
+   | --- | --- | --- |
+   | `deterministic` | every changed file is a derived artifact git reports as modified or removed, none of them under a declared elevated path | the checks alone; no reviewer |
+   | `fast-path` | documentation outside the rulebook, and derived files under those same two rules | `prose-reviewer` |
+   | `model` | everything else, including anything unclassifiable | `code-reviewer`, **always** |
+
+   `.claude/scripts/decision-router.mjs` decides this from the **committed**
+   diff's paths — an uncommitted edit is not routed — and **risk flags escalate
+   ahead of all three**: a file under a declared elevated path, a dependency
+   manifest, a path naming auth or secrets or sessions, a deleted test —
+   including the deletion half of a rename. Any one of them means `model`,
+   however cheap the change otherwise looked. A rulebook document is code here,
+   so it never reaches the prose lane; `.md`/`.mdx` files and test paths that
+   provision nothing are inert, so a README inside an elevated directory does
+   not escalate on that ground alone. **Rulebook paths are exempt from that
+   carve-out** — `CLAUDE.md`, anything under `.claude/`, and the decision
+   records under `docs/decisions/`, which are extracted rationale and reviewed
+   like the rules they explain. The inert set is otherwise those two extensions
+   and test paths exactly — **not** the router's own notion of prose, which is
+   `.md`/`.txt`. Neither set contains the other, and reconciling them breaks a
+   gate in either direction: `docs/decisions/review-lanes.md`. The router
+   **refuses** rather than routing when it cannot decide, and a refusal is read
+   as `model`, never as a reason to skip the gate.
+
+   🔴 **The cheap lanes give something up, and the rule says what.** Dropping
+   `code-reviewer` drops two of its checks that are not about code — contract
+   drift, and "contradicts the item it claims to implement". So every lane
+   passes the queue item's text to whatever cold reader it launches. The
+   `deterministic` lane launches none, which rests on the file being generator
+   output that a check regenerates — so an added, copied, renamed or
+   status-less entry is refused it, and a test snapshot is not a derived
+   artifact at all: it *is* the behaviour claim.
+
+   The lane is a **floor, not a ceiling**. It reads paths, while the triggers
+   below read what the code *does*, and a path cannot say that a module parses
+   untrusted input. **These triggers are lane-independent and may only add** — a
+   documentation-only diff still reaches `security-scanner` when it trips one:
    - `security-scanner` when it touches auth, secrets/configuration, input
      parsing, file handling, or outbound calls;
    - `prose-reviewer` when it touches the documents that instruct agents — a
-     rule file, a skill, an agent spec, `CLAUDE.md`, the README. In this layer
-     the prose *is* the implementation, and it fails the same way code does:
-     silently, in the direction of false confidence;
+     rule file, a skill, an agent spec, a decision record under
+     `docs/decisions/`, `CLAUDE.md`, the README. In this layer the prose *is*
+     the implementation, and it fails the same way code does: silently, in the
+     direction of false confidence;
    - an infrastructure review when it touches infrastructure (the stack layer
      names the reviewing agent for the target).
 
    The `pr-ship` skill drives this fan-out and returns a SHIP / HOLD verdict
    with named blockers; blocking findings are resolved, not argued with.
+
+   **A verdict is a block, not a sentence.** Every gate ends its report with one
+   fenced `json` block of the shape `.claude/scripts/lib/verdict.mjs` defines,
+   and `pr-ship` runs `node .claude/scripts/verdict.mjs check` on each answer
+   **before** it decides anything from it. A report that does not parse — no
+   block, a word no gate returns, a blocker naming no rule, a stop naming no
+   blocker — is `incomplete`: the reviewer did not answer, which is neither a
+   pass nor a stop. Reading it as a pass is the failure the check exists to
+   prevent. What the check cannot decide for a gate the shared vocabulary does
+   not name is stated as that module's first limit; the gate reads such a word
+   against the reviewer's own spec.
 3. **Merge — on an explicit, non-lazy criterion.** Do not trust a watcher
    command that can exit before the checks have even registered. Confirm that
    the **required** check completed successfully **for this commit** — a list