create-agent-rig 0.4.0 → 0.6.0

package/templates/agent-os/stack/aws-cdk/.agents/skills/ro-debug/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ro-debug
+description: Investigate the deployed runtime read-only — Lambda logs and error rates, DLQ depth and message age, table reads — with the traps that have produced confidently-wrong diagnoses before. Use when something on the deployed stage misbehaves, and before writing any fix.
+allowed-tools: Bash, Read, Grep
+---
+
+# Read-only runtime investigation
+
+A fix is always a code change through a PR. This skill only **looks** — and it is
+scoped read-only so that a session diagnosing an incident cannot become a session
+mutating production state under pressure, which is when that decision is worst.
+
+## The role this assumes, and the honest caveat
+
+Every command below wants a **read-only profile**: permission to read logs,
+metrics, queue attributes and table items, and nothing else. No decrypt, no
+secret reads, no mutations — so a credential cannot leak through this path even
+by accident.
+
+⚠ **The skeleton does not provision that role.** It ships the application, not
+your account's access model, and minting a role is an **owner action** (a Tier-2
+decision — it is IAM). Until it exists, either create it once with those four
+read scopes, or accept that you are investigating with wider credentials than the
+task needs and say so in the write-up. Do not silently upgrade to an admin
+profile and carry on.
+
+```sh
+export AWS_PROFILE=<your read-only profile>
+export AWS_REGION=__REGION__
+```
+
+## Before reading ANY code to explain a runtime behaviour
+
+```sh
+git fetch origin && git rev-parse HEAD "origin/$(git symbolic-ref --short HEAD)"
+```
+
+**If the local branch differs from its remote, diagnose from the remote**
+(`git show origin/<branch>:<file>`, or a worktree). **A fetch does not move your
+checkout** — reading stale local code while describing deployed behaviour is
+the single most reliable way to produce a confident, wrong diagnosis, and it has
+happened more than once. See `.claude/rules/autonomy.md`, "Session staleness".
+
+## Recipes
+
+**Find the function first** — CDK generates the physical names, so never guess one:
+
+```sh
+aws lambda list-functions \
+  --query "Functions[?contains(FunctionName,'Notes')].FunctionName" --output text
+```
+
+**Errors in a window:**
+
+```sh
+aws logs filter-log-events --log-group-name "/aws/lambda/<fn>" \
+  --start-time <epoch-ms> --filter-pattern "ERROR" \
+  --max-items 20 --query 'events[].message' --output text
+```
+
+**DLQ depth, then message age.** Depth comes from the queue; **age does not** —
+`ApproximateAgeOfOldestMessage` is a **CloudWatch metric, not an SQS attribute**,
+and asking for it as an attribute fails with `InvalidAttributeName`:
+
+```sh
+aws sqs get-queue-attributes --queue-url <notes-dlq-url> \
+  --attribute-names ApproximateNumberOfMessages
+
+aws cloudwatch get-metric-statistics --namespace AWS/SQS \
+  --metric-name ApproximateAgeOfOldestMessage \
+  --dimensions Name=QueueName,Value=<notes-dlq-name> \
+  --start-time <iso> --end-time <iso> --period 300 --statistics Maximum
+```
+
+Age is what tells you whether a non-empty DLQ **predates** the thing you are
+investigating. A days-old backlog is not your regression, and treating it as one
+sends the whole diagnosis in the wrong direction.
+
+**Table reads** — key by whatever `packages/db` composes; nothing else knows the
+key shape:
+
+```sh
+aws dynamodb query --table-name <NotesTable output> \
+  --key-condition-expression "pk = :pk" \
+  --expression-attribute-values '{":pk":{"S":"NOTE#<id>"}}' --max-items 3
+```
+
+**Error rate:** `AWS/Lambda` `Errors`, `Sum`, by `FunctionName`, over the suspect
+window.
+
+## Interpretation rules — where wrong diagnoses actually come from
+
+- 🔴 **An empty metric result is "no signal", never "healthy".** Zero datapoints
+  means **no invocations in the window** — the function was not exercised, so the
+  metric says nothing about whether it works. Report it as no signal and go find
+  a window with traffic. This is the same rule the `post-deploy-verify` skill
+  states, and for the same reason: a vacuous pass is worse than a missing one,
+  because it gets believed.
+- 🔴 **`StackStatus: UPDATE_COMPLETE` is stale evidence.** It persists from the
+  previous deploy, so it is true of a stack whose latest deploy failed. The
+  authoritative signals are the **deploy job's conclusion**
+  (`gh run list --workflow deploy`) and the stack's `LastUpdatedTime` freshness.
+- **DNS and asset-upload failures are infrastructure flakes, not code
+  regressions.** A deploy that died at asset publish or checkout tells you nothing
+  about the change. Your own read-only calls can hit the same flake — a failed
+  probe is `unknown`, not a finding.
+- **Never work around the profile's denials — that is the point of the profile.**
+  Needing a decrypt, a secret or a mutation means the investigation has reached
+  its boundary: escalate to the human with what you found
+  (`.claude/rules/autonomy.md`, "Escalation format").
+
+## What to hand back
+
+What was observed (verbatim, not summarised), which window, which signals were
+**unavailable** and why, the current hypothesis, and the narrowest reproduction.
+A read-only investigation that ends in a named uncertainty is a good outcome; one
+that ends in a confident story built on a stale read is not.

package/templates/agent-os/stack/aws-cdk/.claude/agents/cdk-diff-reviewer.md

@@ -17,8 +17,9 @@ run it yourself); your output is a verdict. You never fix and never deploy.
    come as **BLOCKERS first, then nits** — one list each, with the resource
    and the rule it violates.
 3. Your message IS the review, not a summary of it: every finding carries the
-   resource, the change, the rule, and the smallest fix. End with the verdict:
-   `DEPLOY: OK` or `DEPLOY: BLOCKED`.
+   resource, the change, the rule, and the smallest fix. End with the verdict
+   block below — `SHIP` where `DEPLOY: OK` used to be, `HOLD` where
+   `DEPLOY: BLOCKED` did.
 
 ## Named rules — blockers
 
@@ -46,4 +47,41 @@ grant helper, duplication between stacks.
 - Read-only: you run `cdk diff` and read code; you never run `cdk deploy`,
   never edit files, never mutate AWS state.
 - An empty diff is a real finding too — say "no infrastructure change" and
-  verdict OK, so the gate leaves a trace either way.
+  return `SHIP`, so the gate leaves a trace either way.
+
+## The verdict block
+
+End your report with **exactly one** fenced `json` block of this shape, and
+nothing after it. It is what the calling gate reads.
+
+```json
+{
+  "gate": "cdk-diff-reviewer",
+  "verdict": "HOLD",
+  "blockers": [
+    {
+      "file": "infra/lib/api-stack.ts",
+      "line": 88,
+      "rule": "data loss",
+      "note": "the table's RemovalPolicy went to DESTROY — replacement drops it"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["cdk diff against the deployed stage"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `SHIP` (nothing blocking, including an empty diff), `HOLD`, or
+  `NOT_APPLICABLE` when the change touches no infrastructure at all.
+- Every blocker names the `rule` it violates, with `file` and `line` when it has
+  a location and neither when it does not.
+- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:
+  `node .claude/scripts/verdict.mjs check <report> cdk-diff-reviewer` is what
+  refuses them.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

package/templates/agent-os/stack/aws-cdk/.claude/rules/aws-cdk.md

@@ -20,7 +20,7 @@ infra/
   is drift, and drift is a defect — reproduce it in CDK or revert it.
 - **Every change under `infra/` passes the `cdk-diff-reviewer` agent before it
   is deployed.** The review reads the synthesized diff (what CloudFormation
-  will do), not just the source. Deploying around a BLOCKED verdict is a
+  will do), not just the source. Deploying around that agent's `HOLD` is a
   Never-tier action.
 - `cdk synth` stays region-agnostic and credential-free: synth must work on any
   machine, in CI, with nothing configured.

package/templates/agent-os/stack/aws-cdk/.claude/skills/post-deploy-verify/SKILL.md

@@ -55,6 +55,47 @@ Report exactly one, with the evidence lines that justify it:
   metric or log result means "no invocations", not "no errors"** — name a
   vacuous result honestly instead of reporting it as a pass.
 
+### The verdict block
+
+End your report with **exactly one** fenced `json` block of this shape, and
+nothing after it. The prose above it carries the evidence a human reads; this is
+what the caller acts on — and what it retypes into
+`node .claude/scripts/run-state.mjs deploy HEALTHY|REGRESSION`, which is where
+the next selection reads the verdict.
+
+```json
+{
+  "gate": "post-deploy-verify",
+  "verdict": "REGRESSION",
+  "blockers": [
+    {
+      "rule": "smoke request",
+      "note": "POST /notes returned 502 twice; expected 201"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["stack LastUpdatedTime is this deploy", "DLQ depth 0"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `HEALTHY` or `REGRESSION` — this skill has no third answer, and
+  "could not verify" is a `REGRESSION`, never a missing verdict.
+- A `REGRESSION` names one blocker per failed or unverifiable step, with the
+  observed output in its `note`. A step has no file, so `file` and `line` are
+  omitted here.
+- A `REGRESSION` naming no blocker, and a `HEALTHY` carrying one, are answers
+  the caller cannot act on. The caller is what checks: the session that ran the
+  deploy runs `node .claude/scripts/verdict.mjs check <report>
+  post-deploy-verify` before it retypes the word into `run-state.mjs`. This
+  skill runs nothing — it is read-only by construction.
+- **`headSha` is the commit that was deployed** — `git rev-parse HEAD` in the
+  checkout the deploy went out from. ⚠ **Nothing reads it yet**: `run-state.mjs`
+  stores the word alone, so the commit lives in this block and nowhere else.
+  Write it anyway — the pairing is what a later reader needs to tell a stale
+  `HEALTHY` from a current one, and `HEALTHY` is the only thing that clears the
+  `REGRESSION` latch the next selection reads.
+
 ## Boundaries
 
 - Read-only AWS calls (`describe*`, `get*`, `list*`, `filter-log-events`) plus

package/templates/agent-os/stack/aws-cdk/.codex/agents/cdk-diff-reviewer.toml

@@ -0,0 +1,4 @@
+name = "cdk-diff-reviewer"
+description = "Reviews an infrastructure change via `cdk diff` BEFORE any deploy. MUST run on every change under infra/ — a deploy without this review is a Never-tier action. Read-only; findings gate the deploy."
+sandbox_mode = "read-only"
+developer_instructions = "You review what a deploy would actually do to running infrastructure. Your\ninput is the change under `infra/` **and** the synthesized diff (`cdk diff`,\nrun it yourself); your output is a verdict. You never fix and never deploy.\n\n## How you work\n\n1. Run `cdk diff` (and read the changed `infra/` sources for intent). The diff\n   is the truth: review what CloudFormation will do, not what the TypeScript\n   looks like it does.\n2. Walk every resource change and flag it **by named rule** (below). Findings\n   come as **BLOCKERS first, then nits** — one list each, with the resource\n   and the rule it violates.\n3. Your message IS the review, not a summary of it: every finding carries the\n   resource, the change, the rule, and the smallest fix. End with the verdict\n   block below — `SHIP` where `DEPLOY: OK` used to be, `HOLD` where\n   `DEPLOY: BLOCKED` did.\n\n## Named rules — blockers\n\n- **IAM broadening.** Any policy gaining actions, resources widening to `*`,\n  or a grant that outruns what a usecase does today. Least privilege is added\n  in the same PR as the need, never \"for later\".\n- **Data loss paths.** A stateful resource (table, bucket, queue) being\n  replaced, deleted, or flipping its RemovalPolicy toward DESTROY.\n  Logical-id renames on stateful resources are replacements in disguise.\n- **Safety-net removal.** A DLQ detached, an alarm deleted or loosened, a\n  retry budget widened to infinity, a dead-letter retention shortened.\n- **Blast-radius growth.** New public surface (endpoints, permissions to\n  external principals), broadened network access, cross-stack exports that\n  make future changes harder to reverse.\n- **Cost-relevant flips.** On-demand → provisioned capacity, log retention to\n  \"forever\", memory/timeout jumps with no stated reason.\n\n## Nits (report, do not block)\n\nNaming drift, missing descriptions, constructs that could use the narrower\ngrant helper, duplication between stacks.\n\n## Boundaries\n\n- Read-only: you run `cdk diff` and read code; you never run `cdk deploy`,\n  never edit files, never mutate AWS state.\n- An empty diff is a real finding too — say \"no infrastructure change\" and\n  return `SHIP`, so the gate leaves a trace either way.\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.\n\n```json\n{\n  \"gate\": \"cdk-diff-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"infra/lib/api-stack.ts\",\n      \"line\": 88,\n      \"rule\": \"data loss\",\n      \"note\": \"the table's RemovalPolicy went to DESTROY — replacement drops it\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"cdk diff against the deployed stage\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP` (nothing blocking, including an empty diff), `HOLD`, or\n  `NOT_APPLICABLE` when the change touches no infrastructure at all.\n- Every blocker names the `rule` it violates, with `file` and `line` when it has\n  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> cdk-diff-reviewer` is what\n  refuses them.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."

package/templates/agent-os/stack/node-ts/.claude/rules/node-ts.md

@@ -55,3 +55,32 @@ gh api "repos/{owner}/{repo}/commits/$SHA/check-runs" \
 # must print: success   (a result set containing only a scanner is NOT done)
 ```
 
+**A head that gets no run at all is a third state, not a slow one.** A
+`pull_request` push can register no workflow run and emit no failure signal —
+the head sits with a scanner only, and the poll above waits forever while the
+previous head's green sits one line up in the same PR (AR-149: `69b5d65` on
+#130 got no `ci` run; `8ca26e7` on #134 got `ci` and no `e2e`). Tell "not
+registered" apart from "pending" by asking for runs by head, not by PR:
+
+```sh
+gh api "repos/{owner}/{repo}/actions/runs?head_sha=$SHA" \
+  -q '.workflow_runs[] | "\(.name) \(.event) \(.status) \(.conclusion)"'
+# one line per workflow that ran for THIS sha; a required workflow missing
+# here after a bounded wait (a few minutes) is not registered, not pending
+```
+
+⚠ The names differ in case between the two queries: `workflow_runs[].name`
+is the **workflow** name (`CI`, `E2E`), the check-runs filter above reads the
+**job** name (`ci`, `e2e`). Searching the runs list for `ci` finds nothing.
+
+Then the rule, **per required check by name**, never per head: a check with
+no run after the wait is **retriggered**, and the PR is **never merged on an
+older head's green**. The retrigger depends on the workflow — `ci.yml` has no
+`workflow_dispatch`, so an empty commit (`git commit --allow-empty`) is the
+simplest trigger it has; `e2e.yml` has one, so
+`gh workflow run e2e.yml --ref <branch>` re-runs it on the same head. Pinned
+in the generator's `test/template/pr-flow.test.ts` — absent in a generated
+rig — › "node-ts names the head that gets no run at all, and says it is
+retriggered rather than waited on" and › "the no-run branch is stated per
+required check, not per head".
+

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

@@ -0,0 +1,236 @@
+---
+name: check-premises
+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, or the diff and prose to check>
+---
+
+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 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
+
+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.
+
+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 |
+| --- | --- | --- |
+| `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
+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.
+
+### 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"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `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.
+- **`headSha` is the commit you read** — `git rev-parse HEAD` in the checkout
+  you examined. A premise check answers about a tree, and the tree moves.
+
+## 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.
+- **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.
+- 🔴 **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.