create-agent-rig 0.4.0 → 0.5.0

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

@@ -1,9 +1,9 @@
 ---
 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.
+description: Check claims about the code before building on them, or before shipping them. Use after taking a queue item and before the failing test — whenever the item asserts something exists, is missing, is broken, or works a particular way. Use again before the gate, on the run's own prose, where a behaviour claim nothing backs is UNMEASURED.
 context: fork
 allowed-tools: Read, Grep, Glob, Bash
-argument-hint: <the queue item's text>
+argument-hint: <the queue item's text, or the diff and prose to check>
 ---
 
 A queue item is a **claim about the code**, written by someone who was not
@@ -11,8 +11,33 @@ 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.
+This skill checks the premises. It writes nothing, and it has **two entry points**.
+
+| entry point | the claims are | the code is | verdicts |
+| --- | --- | --- | --- |
+| after selection, **before the Red step** | the queue item's, about code it did not read | the repository | `PREMISES HOLD` / `PREMISE FALSE` / `UNVERIFIABLE` |
+| after the work, **before the gate** | your own, in the rulebook prose the diff touches — and in the PR description if one exists yet | your diff | `PREMISES HOLD` / `UNVERIFIABLE` / `UNMEASURED` |
+
+🔴 **Why the second one exists.** A claim you wrote about a mechanism you did not run
+is cheap to write and expensive to find: `prose-reviewer` reaches it only after loading
+the whole diff, and the fix is an edit to one sentence. Same machinery, same question — *is this claim true?* — pointed
+at the text the run wrote instead of the text it was handed.
+
+The rest of this skill is written for the first entry point. The second one runs the
+same four steps with the diff as the code, and §4 carries what is different.
+
+**What "rulebook prose" means here is not a new list** — it is the set
+`.claude/rules/workflow.md` already uses for the `prose-reviewer` trigger: a rule
+file, a skill, an agent spec, a decision record, `CLAUDE.md`, the README. Where a
+rulebook file exists twice (a template source and a generated copy), check the
+**source**; the copy is composed from it. A comment in a test or a hook is in scope
+too when it asserts behaviour — the file it lives in does not change what a claim is.
+
+🔴 **`PREMISE FALSE` belongs to the first entry point only.** At the second one the
+claims are your own and the remedy is an edit, so a false one is not an escalation:
+it is `UNMEASURED`'s neighbour — delete or correct the sentence and carry on. Reading
+it as the escalation `loop` §6 defines would send a finished branch back to the queue
+over one sentence.
 
 ## Why it sits here and not in review
 
@@ -62,6 +87,10 @@ 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.
 
+At the **second** entry point this inverts for one case: a test is exactly what backs
+a behaviour claim, so reading it is the point. The rule above is about not letting a
+test's *name* stand in for what the code does; §4 says which artifacts count.
+
 ## 4. The verdict
 
 | Verdict | When | What happens next |
@@ -69,6 +98,50 @@ believe but cannot cite is not verified, it is remembered.
 | `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** |
+| `UNMEASURED` | **second entry point only:** a sentence you wrote asserts behaviour, and nothing you can point at backs it | **delete the sentence, or turn it into a pointer to the test that proves it** — before the gate |
+
+🔴 **The edit belongs to the calling session, not to this skill.** It reports; the
+caller performs the exit before the gate. (The rule is the one at the top of this
+file — it writes nothing — not a property of its tool grant.)
+
+🔴 **`UNMEASURED` has exactly two exits, and "reword it" is not one of them.** A
+behaviour claim is either backed or it is not; softening the wording keeps an
+unbacked claim in a document agents follow literally. So either the sentence goes,
+or it becomes `see guard-invariant.example.test.mjs › "blocks the violation, and the
+reason names what to do instead"` — the test's whole name, in a file this project
+carries, so one grep lands on it. `invariants.md` ("State the limits") states the norm this verdict
+enforces.
+
+**Two questions, and they have different answers — conflating them is how an unbacked
+sentence survives this check.**
+
+*Is the claim founded?* A test you can name, a command whose output is in front of
+you, or a citation to code that does the thing. What does not count: the queue item
+said so (the item is a claim too — that is what the first entry point is for), it was
+true of the previous design, or it is obviously right.
+
+*May it stay in the file as written?* Only the two forms `invariants.md` requires —
+**generated** from what it describes, or a **pointer** to the test. A command's output
+is not one of them: you saw it, the reader cannot, so a sentence resting on it is still
+`UNMEASURED` however sure you are. Point at the test that runs that command, or say
+something the reader can check.
+
+⚠ **A measurement of this project's own history fits none of the three**, and that is
+a real gap rather than an oversight: the run that produced it is not in the repository,
+and a journal entry does not travel with a rulebook that ships. So a figure about past
+runs belongs in the journal and **not** in a file other projects receive — where it
+would arrive with no backing at all.
+
+A sentence is qualitative when it names **no quantity a reader could check** — not a
+count, not a share, not a duration. "This has happened here before" qualifies; "this
+happened twice last month" does not, and moves to the journal.
+
+That is not a third exit from `UNMEASURED`. The two exits apply to **the sentence in
+front of you**: it goes, or it becomes a pointer. Writing a different sentence — one
+that claims no measurement, and so needs none — is the first exit followed by an
+unrelated edit, not a softened version of the same claim. `invariants.md` has a
+worked instance: "Both have happened here, in the same file, within one review
+cycle." No figure, no measurement claimed, and it ships.
 
 🔴 **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
@@ -81,6 +154,40 @@ branch named after a task that does not exist.
 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.
 
+### The verdict block
+
+Report in prose for the caller, then end with **exactly one** fenced `json` block
+of this shape, and nothing after it. The word is spaced in prose and one token
+inside the block; both forms are the contract.
+
+```json
+{
+  "gate": "check-premises",
+  "verdict": "PREMISE_FALSE",
+  "blockers": [
+    {
+      "file": "packages/core/src/note.ts",
+      "line": 17,
+      "rule": "the item claims the schema does not reject an empty title",
+      "note": "it does, here — the reported bug is a caller that skips the validator"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["read the validator and both call sites"]
+}
+```
+
+- `verdict` is `PREMISES_HOLD`, `PREMISE_FALSE`, `UNVERIFIABLE` or `UNMEASURED`
+  — this skill returns no other word, and none of the reviewers' words.
+- One blocker per premise that did not hold, per claim that could not be decided,
+  or per unbacked sentence — `rule` is the claim itself, `note` is what the code
+  actually says, and `file`/`line` is the citation §3 requires.
+- `PREMISES_HOLD` carries an empty `blockers` list; the other three name at
+  least one. A stop verdict without one is not an answer the caller can act on,
+  and the caller is what checks: the `loop` skill runs
+  `node .claude/scripts/verdict.mjs check <report> check-premises` on what you
+  return. Nothing in this skill runs it — this skill writes nothing at all.
+
 ## Examples — the three shapes this actually catches
 
 **The thing already exists.** Item: "the payload schema does not reject an empty
@@ -110,9 +217,10 @@ is invisible to every gate downstream.
   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.
+- **Each entry point is one pass, at its own end of the task.** A premise that goes
+  false *between* them — a merge lands, a dependency moves — is a staleness stop rule
+  (`.claude/rules/autonomy.md`), not this skill. Neither pass watches the other's
+  claims.
 - **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.