create-agent-rig 0.3.0 → 0.3.2

package/templates/agent-os/universal/.claude/skills/check-premises/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: check-premises
+description: Check a queue item's claims about the code before building on them. Use immediately after taking an item and before the failing test — whenever the item asserts that something exists, is missing, is broken, or works a particular way.
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: <the queue item's text>
+---
+
+A queue item is a **claim about the code**, written by someone who was not
+reading the code at the time. "The retry path swallows the error", "there is no
+validation on that field", "the worker never gets the second message" — each of
+those is a premise, and the work that follows is only worth doing if it is true.
+
+This skill checks the premises. It runs **after selection, before the Red step**,
+and it produces one of three verdicts. It writes nothing.
+
+## Why it sits here and not in review
+
+A false premise is not caught later. Review reads the diff against the item, and
+both are wrong in the same direction: the item said the validation was missing,
+the diff adds validation, the reviewer sees a diff that does what the item asked.
+Nobody re-reads the file that had the validation all along. The cost lands as a
+duplicate implementation, a "fix" for a bug that was somewhere else entirely, or
+a refactor of a path that no caller reaches — all of it green, reviewed, merged.
+
+The check is cheap because it is narrow, and the next section is that narrowness.
+
+## 1. Write out the claims — as claims
+
+List what the item asserts about the code as it exists **now**. Two to five
+lines. Keep them in the item's own terms; do not repair them while transcribing
+— a claim you have already improved is one you will not test.
+
+Separate the claims from the request. "Add a `GET /notes/:id` route" asserts
+nothing; "the route handler bypasses the usecase layer" does.
+
+An item that asserts nothing is done here: verdict `PREMISES HOLD`, one line
+saying there were none. That is a common and perfectly good outcome.
+
+## 2. Mark the load-bearing ones
+
+🔴 **A claim is load-bearing when its falsity changes what gets built.** Only
+those get verified. **This is not an audit** of the item, the file, or the
+codebase — the moment it becomes one, it stops being cheap, gets skipped under
+time pressure, and the whole step is lost.
+
+| Load-bearing | Not |
+| --- | --- |
+| "there is no X" — if X exists, the task is already done | a stale line number in the item's description |
+| "X is called from Y" — if it is not, the fix goes in the wrong place | a misspelled symbol you can resolve at a glance |
+| "X handles the empty case by Z" — the fix is designed against Z | a claim about a file this task will not touch |
+| "nothing enforces X" — the whole task is the enforcement | a claim the task's own failing test would immediately expose |
+
+That last row is the one worth internalising: a premise the Red step would
+falsify in the next five minutes does not need checking here. This step exists
+for the premises a passing test **would not** catch — the ones about code the
+task never touches.
+
+## 3. Verify each, against the code, with a citation
+
+Read the code. Not the tests, not the docs, not another queue item — those are
+claims too. Each verified premise gets a `file:line` citation; a premise you
+believe but cannot cite is not verified, it is remembered.
+
+## 4. The verdict
+
+| Verdict | When | What happens next |
+| --- | --- | --- |
+| `PREMISES HOLD` | every load-bearing claim checked out, or there were none | proceed to the Red step |
+| `PREMISE FALSE` | a load-bearing claim is contradicted by the code | **stop and report** |
+| `UNVERIFIABLE` | a load-bearing claim could not be decided from the code | report it as unverifiable, name what would decide it, and proceed only under a **labelled assumption** |
+
+🔴 **On `PREMISE FALSE` the answer is stop and report — never quietly work around
+the false premise by building something adjacent that seems useful.** Write what
+the item claimed, what the code actually says with its citation, and what the
+task might become instead. Then let a human re-aim it. The item is wrong, and an
+agent that silently repairs a wrong item produces work nobody asked for, in a
+branch named after a task that does not exist.
+
+`UNVERIFIABLE` is not a soft pass. A probe that could not run tells you nothing —
+so the assumption travels in the open, in the item and in the PR description,
+where the next reader can see which part of the work rests on it.
+
+## Examples — the three shapes this actually catches
+
+**The thing already exists.** Item: "the payload schema does not reject an empty
+title". The schema does reject it, three lines into the validator; the reported
+bug came from a caller that never invoked the validator. Building "the missing
+check" would have added a second, divergent rule and left the real defect —
+the caller — in place. Verdict `PREMISE FALSE`; the task becomes a caller fix.
+
+**The thing is somewhere else.** Item: "the worker retries forever because the
+retry budget is not applied". The budget is applied, and correctly; the message
+returns to the queue from a path above it that never consumed the budget at all.
+The fix designed against the item would have been written in a file that was not
+the problem. Verdict `PREMISE FALSE`.
+
+**Nothing enforces it — except something does.** Item: "nothing stops a handler
+importing the storage layer directly". A hook does exactly that, and has since
+before the item was filed. Two hours of building a second enforcement mechanism,
+which would then have disagreed with the first. Verdict `PREMISE FALSE`.
+
+Note what all three have in common: the resulting work would have been correct,
+tested, reviewable, and useless. That is the failure mode this catches, and it
+is invisible to every gate downstream.
+
+## Limits — stated, because a check trusted past its reach is worse than none
+
+- **It reads the code, so it only catches what the code can contradict.** A claim
+  about runtime behaviour ("this times out in production"), about intent, or
+  about a system this repository does not contain is `UNVERIFIABLE` here, not
+  false — say so rather than guessing.
+- **It is one pass, before the work.** A premise that becomes false while the
+  task runs (a merge lands, a dependency moves) is a staleness stop rule
+  (`.claude/rules/autonomy.md`), not this skill.
+- **It has no opinion on whether the task is worth doing.** True premises and a
+  pointless task is a perfectly consistent state, and it belongs to whoever fills
+  the queue.
+- 🔴 **Nothing makes this run, and the verdict is a self-report.** No hook fires
+  when a task starts building on an unchecked claim, and no artifact outlives the
+  step — so a run that skipped it and a run that passed it look identical
+  afterwards. That is the honest description of every rule of this shape here
+  (the `loop` skill says the same about its own no-hand-feeding rule), and it is
+  why the citation matters: a `file:line` in the report is the one part of this a
+  later reader can re-check.

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -10,9 +10,9 @@ boundaries; the **queue** holds the work; `PLAN.md` holds state, standing
 decisions and the journal. This skill is the driver in between: what gets picked,
 what keeps the loop going, what stops it, and where the report goes.
 
-Per-task procedure is unchanged: (worktree if another session may run) → failing
-test first → implement → `pr-ship` → merge on the named criterion → verify the
-deployed surface if one changed.
+Per-task procedure is unchanged: (worktree if another session may run) →
+`check-premises` → failing test first → implement → `pr-ship` → merge on the
+named criterion → verify the deployed surface if one changed.
 
 ## 0. The queue is behind an adapter
 
@@ -102,11 +102,18 @@ and the work turns out to touch an elevated path (`CLAUDE.md` →
 `elevated-paths`), run the gate anyway, record the verdict on the PR, and treat it
 as this run's elevated item for spacing.
 
+**Then, before the Red step: `check-premises`.** The item was written by someone
+who was not reading the code at the time, and everything downstream — the failing
+test, the implementation, the reviewer comparing diff to item — inherits its
+claims rather than checking them. On `PREMISE FALSE` the item is escalated (§6),
+not repaired in place: a run that silently re-aims its own task has authored work
+for itself, which is the one thing this loop does not do (§8).
+
 ## 3. What keeps the loop running, and what stops it
 
 Per-task stops (three strikes, attempt budget, invariant conflict, a blocking
-reviewer verdict) **do not end the run**: escalate that item (§5) and take the
-next one.
+reviewer verdict, a false premise in the item itself) **do not end the run**:
+escalate that item (§5) and take the next one.
 
 The run-level conditions are in `stopConditionOf` in `core.mjs`, checked in
 severity order: **queue unreadable** · **runtime regression** · **kill switch** ·
@@ -204,10 +211,14 @@ mechanises fully (`missed`, `.claude/rules/autonomy.md`) needs no self-report.
 ## 6. Escalation — two channels, by scope
 
 **Task-scoped — the item is the home, and the loop continues.** Three strikes, the
-attempt budget, an invariant conflict, or a blocking reviewer verdict:
+attempt budget, an invariant conflict, a blocking reviewer verdict, or a
+`PREMISE FALSE` verdict from `check-premises` — the last one is a
+`documented-stall` (§5), and its diagnosis is already written: what the item
+claimed, what the code says, and the citation:
 
 1. Comment the diagnosis on the queue item: what fails, what was tried, the
-   current hypothesis, links to the PR and the failing run. **Name the outcome
+   current hypothesis, and links to the PR and the failing run where they exist
+   — a premise stop has neither, and its citation stands in for both. **Name the outcome
    state in the same comment** — `incomplete` if the diagnosis cannot say which
    stage needed what. Writing `incomplete` on your own task is uncomfortable and
    is the point: the run that produced it is the only witness.
@@ -274,6 +285,7 @@ three poisons the only channel by which this project learns.
 | Does not | Why |
 | --- | --- |
 | **Create its own work items** | The queue is human-filled. Self-authored work drifts scope, and unattended it drifts unwatched |
+| **Re-aim an item whose premise turned out false** | Same rule wearing a disguise: an item silently rewritten into "what it should have said" is a work item the agent authored. Escalate it (§6) |
 | Take items needing a human decision | It cannot unblock itself; those wait in the Operator queue |
 | Take a `trigger-human` item | It would build for scale that does not exist |
 | Take two elevated items back to back | One unreviewed schema/permissions change is recoverable; a chain overnight is not |

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

@@ -19,10 +19,20 @@ blockers.
    (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.
+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. Run them as subagents, in parallel — a fresh context
+   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

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

@@ -42,6 +42,10 @@ 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.
 - **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
@@ -49,9 +53,14 @@ 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` runs before every PR; `security-scanner` runs when
-  a change touches auth, secrets, parsing, or outbound calls. Blocking findings
-  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **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
+  `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

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

@@ -9,12 +9,14 @@
     ".claude/agents/test-writer.md",
     ".claude/agents/code-reviewer.md",
     ".claude/agents/security-scanner.md",
+    ".claude/agents/prose-reviewer.md",
     ".claude/hooks/block-no-verify.mjs",
     ".claude/hooks/guard-bash.mjs",
     ".claude/hooks/gate-stop-dod.mjs",
     ".claude/hooks/inject-rules.mjs",
     ".claude/skills/pr-ship/SKILL.md",
     ".claude/skills/loop/SKILL.md",
+    ".claude/skills/check-premises/SKILL.md",
     ".claude/skills/worktree-task/SKILL.md",
     ".claude/scripts/detect-missed-gate.mjs",
     ".claude/scripts/reconcile-external-prs.mjs",