plumbbob 0.9.3 → 0.9.5

package/node_modules/checkride/skills/qa/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: qa
+description: Read checkride's quality artifacts — surviving mutants, dead code, duplication and the health score — and say what the test suite actually proves. Use when asked how healthy the codebase is, whether the tests are any good, where the risk or the tech debt is, what mutation testing found, or which files need better coverage. Reads a bounded report instead of megabytes of `.check/` artifacts, runs nothing, and reports which quality dimensions were never measured rather than guessing at them.
+argument-hint: "[repo-path]"
+allowed-tools: Read, Grep, Glob, Bash(node *), Bash(pnpm *), Bash(npx checkride*), Bash(yarn *), Bash(bunx *), Bash(wc *), Bash(git log *)
+---
+
+# checkride: read the quality signal
+
+checkride's gate answers one question — is the work done? — and answers it
+pass/fail. These four artifacts answer a different one: **is the suite actually
+testing anything, and where is the risk?** Nothing here is red or green. No
+threshold fires. That is exactly why this is the easiest report in the repo to
+hallucinate: with no failure to anchor to, a plausible-sounding list of eight
+issues costs nothing to write and means nothing.
+
+So the discipline is inverted from triage. The triage skill starts from a
+failure and narrows to one cause. This skill starts from evidence and stops when
+the evidence stops — which is sometimes after one finding, and sometimes after
+none.
+
+For a red gate, use the triage skill instead (`/checkride:check` under the
+plugin, `/checkride-check` in Cursor, or `checkride triage` directly). This skill
+reads what a *past* run left behind and never runs the gate itself.
+
+## 1. Run the reader
+
+```bash
+pnpm exec checkride qa
+```
+
+Substitute the repo's package manager (`npx checkride`, `yarn checkride`, `bunx
+checkride`). Pass a repo path as the one optional argument to read somewhere
+other than the current directory.
+
+If checkride is not a dependency of the target repo, run the copy the plugin
+ships instead: `node "${CLAUDE_PLUGIN_ROOT}/dist/qa/cli.js"`. Both entry points
+render the identical report.
+
+It **runs nothing** — no stryker, no fallow, not the gate. It opens `.check/`,
+folds each artifact to a ranked short list, and renders under 8 KB (the same
+ceiling `--digest` uses). In checkride's own repo that is 2.3 MB of
+`mutation.json` reduced to a page, which is the only reason a mutation finding
+is affordable at all.
+
+**Do not open any `.check/` file before this report names one.** Every count
+below comes from a full pass over the artifact; the lists are ranked, not
+truncated at random.
+
+## 2. The ledger is the answer, not the preamble
+
+Because the reader runs nothing, its first job is to say what it is actually
+holding. Two head lines, then a table — and in a default consumer repo that is
+very nearly the *whole* report.
+
+```text
+- summary: `.check/summary.json` — `schema_version` 1, 1.5m ago, 1.5s
+- covered: 3 slot(s) ran — links, docs, spell
+```
+
+- **`summary`** — what the artifacts beside it belong to, and how long ago. If it
+  reads `` `schema_version` is 2, not 1; STOP ``, then **stop**: the reader is
+  pinned to schema 1, and guessing across a version is how you invent a finding.
+- **`covered`** — the slots that run actually touched. Three of seventeen means
+  the artifacts on disk mostly belong to *some other* run, and the ledger's
+  staleness column is the only thing standing between you and reporting them as
+  current. `covered: nothing` means there is no readable summary at all, so no
+  artifact here can be dated and none of them is evidence.
+
+**Open your report with that covered count and the run's age**, the same way
+the triage skill does. A quality claim without its coverage is an assertion
+about the whole repo built from a fraction of it.
+
+| state | what it means | what it licenses you to say |
+| --- | --- | --- |
+| `read` | fresh — written by the run whose summary sits beside it | evidence, present tense |
+| `STALE` | on disk, but older than that run's start | a fact about the past, with the age always attached |
+| `not opted in` | the slot is absent from `checkride.config.json`, so no run produces it | **nothing about this dimension** — name the remedy instead |
+| `absent` | opted in, but no file — the slot has not run, or produced nothing | nothing; name the command |
+| `too-large` / `unreadable` / `unrecognized` | the bytes are there but not usable | nothing; say which, because each has a different cause |
+
+Two rules follow, and they are the ones that make this skill honest.
+
+**A gap is a finding, not an edge case.** Three of the four artifacts come from
+opt-in slots, and checkride's own gate never runs `mutation` at all. In a fresh
+consumer repo you will find `dead.json` and nothing else. The honest report
+there is the ledger plus the two commands that would produce data — *not* a page
+of quality assessment extrapolated from one artifact. The reader already prints
+the exact command or config entry for each gap; quote it rather than inventing
+one.
+
+**Never launder a stale number into a present-tense claim.** "Mutation score is
+71%" is wrong when the file is 7.6 days old. "As of a stryker run 7.6 days ago,
+71%" is right, and it carries its own warning. When a stale artifact is
+load-bearing for a finding, check whether the code moved under it:
+
+```bash
+git log -1 --format=%cr -- src/init.ts
+```
+
+If the file changed more recently than the artifact, the artifact describes code
+that no longer exists. Say so and stop — do not report its findings as current.
+
+## 3. Read in evidence order — strongest proof first
+
+The reader emits its sections in the order you should reason about them, and
+that order is not arbitrary. It ranks by **how much of the claim the artifact
+already proved for you**:
+
+1. **Surviving mutants** — the strongest evidence in the repo. Stryker *changed
+   the code* and the suite still passed. That is a demonstrated hole, not an
+   opinion, and no amount of coverage percentage can contradict it.
+2. **Dead code** — a static claim about reachability. Usually right; wrong
+   exactly where entry points are dynamic, which is why `fallow.toml`'s `entry`
+   list exists.
+3. **Structure** (`dupes`, `health`) — measurements against thresholds somebody
+   configured. A hotspot is a place to look, not a defect.
+4. **Your own reading of the source** — last, and only when it names a file and
+   a line.
+
+Work down that list and stop where the evidence stops. That is the whole
+anti-hallucination device: findings are sorted by proof, so a short report is a
+*strong* one.
+
+### Mutation: survived and no-coverage want different fixes
+
+The two undetected states look alike in a table and mean opposite things.
+
+- **No-coverage** — no test reaches the line at all. The fix is a test that
+  executes it.
+- **Survived** — a test *does* reach it and asserts nothing that would notice
+  the change. The fix is a stronger assertion in the test that already runs.
+  Adding another test that also does not look is the standard wrong answer, and
+  it raises line coverage while changing nothing.
+
+The mutator name tells you what kind of hole it is:
+
+| mutator | what its survival proves |
+| --- | --- |
+| `ConditionalExpression` | a branch condition can be forced true or false and nothing notices — usually one side of the branch is decorative. The most common survivor almost everywhere (359 of them in checkride's own repo) and the most informative |
+| `BlockStatement` | an entire function body was emptied and the suite passed. The loudest signal in the table |
+| `EqualityOperator` | a comparison flipped undetected — a boundary case nothing exercises |
+| `LogicalOperator` | one arm of an `&&` / `\|\|` is never the deciding one in any test |
+| `ArrayDeclaration`, `ObjectLiteral` | a literal was emptied unnoticed — the *contents* of that data are unasserted. Common on config tables, and often low-value (see below) |
+| `Regex`, `StringLiteral` | the pattern or text is unasserted; frequently a message nobody should assert on |
+
+**Not every survivor is worth killing.** Equivalent mutants — ones with no
+observable behavior difference — are real and common: log text, a default
+immediately overwritten, a `??` on a value that is never null. A suite driven to
+100% mutation score is a suite full of assertions on things nobody cares about.
+Rank survivors by **what the mutant proves about a path a user can reach**, and
+say when you are dismissing one and why.
+
+**Rank is not priority.** The reader ranks files by undetected count, which
+tracks file *size* at least as much as risk — `src/init.ts` tops checkride's own
+table largely because it is the biggest file with the most mutants. Read what
+the survivors are before treating the top row as the most important work.
+
+## 4. Ground the finding, or drop it
+
+A finding must be able to name three things: **the artifact it came from, the
+file and line, and — for a mutation finding — the test that should have caught
+it and did not.** If you cannot name the test file you would edit, you have a
+metric, not a finding.
+
+So for the one or two survivors that look genuinely load-bearing:
+
+1. Open the source at the sample line the report gave you (`Read` with an
+   `offset`, not the whole file).
+2. Find the test that covers it — `src/__tests__/<name>.test.ts`, or `Grep` for
+   the function name.
+3. Read what that test asserts. The finding is the sentence that comes out:
+   *"`resolveOrder` is called in three tests and all three assert only the
+   length of the result, so flipping its `<=` to `<` changes nothing they
+   check."*
+
+"Coverage could be improved here" is not that sentence.
+
+**Open at most two or three files.** If the report ranks eight, read the top one
+properly rather than all eight badly — the same economy the triage skill uses
+when it opens exactly one artifact.
+
+## 5. Report
+
+- **Evidence** — the covered-slot count, the run's age, then the ledger in a
+  line or two: what is fresh, what is stale and by how much, what was never
+  produced. Always first. A report that opens with a finding is a report that hid
+  its own uncertainty.
+- **What the artifacts prove** — findings in evidence order, each grounded per
+  step 4. As many as the evidence supports, and no more.
+- **What would produce the missing evidence** — the reader's own command or
+  config line for each gap. This is often the single most useful thing you can
+  say.
+- **Judgment** — clearly labelled as yours, last, and only where it names a
+  file.
+
+### The failure mode this skill exists to prevent
+
+**Produce no fixed-size list.** Not "top 5 issues", not eight findings, not one
+per artifact. The count is whatever the evidence supports, and **zero is a
+legitimate answer** — a repo with a fresh, empty `dead.json` and three
+unmeasured dimensions has exactly one honest thing to report: that three of four
+quality dimensions are unmeasured. Padding that to five means inventing four.
+
+Three specific ways it goes wrong:
+
+- **Restating the metric as a finding.** "Health score is 80.9/B" is the ledger.
+  A finding names which function costs the points and why.
+- **Grading the grade.** No number in `health.json` is a defect; the thresholds
+  are a configured opinion, and the score is 100 minus the penalties. When
+  nothing is over any threshold and the whole penalty is hotspots and unit size,
+  say that — do not manufacture violations to explain a B.
+- **Turning a ranked list into a to-do list.** The tables are ranked so you know
+  where to *look*. Copying the top five rows into "recommendations" is
+  transcription wearing analysis's clothes.
+
+## What this skill does not do
+
+- **It runs nothing.** Not stryker (minutes to hours, and it rewrites your
+  source while it works), not fallow, not the gate. Naming the command is the
+  deliverable; running it is the human's call.
+- **It does not gate.** None of these four dimensions has a pass/fail line, and
+  inventing one — "mutation score should be above 80" — turns a measurement into
+  a target, which is how it stops being a measurement.
+- **It does not write tests.** Naming the unasserted branch is the deliverable.
+  Writing the test is the next request, and it should start from the named
+  mutant.
+- **It does not triage a red gate.** That is the triage skill, which runs the
+  gate and reads different artifacts entirely.
+- **It does not touch the baseline.** `checkride baseline` hides findings
+  permanently; that is never a reading step.

package/node_modules/checkride/templates/shared/cspell.json

@@ -10,6 +10,7 @@
     "package.json",
     "CHANGELOG.md"
   ],
+  "ignoreRegExpList": ["/v1[0-9a-f]{16}/g"],
   "words": [
     "checkride",
     "baselined",

package/node_modules/checkride/templates/shared/oxlintrc.json

@@ -29,5 +29,5 @@
       }
     }
   ],
-  "ignorePatterns": ["dist/**", ".check/**", ".claude/**", "node_modules/**"]
+  "ignorePatterns": ["dist/**", ".check/**", ".claude/**", ".cursor/**", "node_modules/**"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",
@@ -59,7 +59,7 @@
     "vitest": "4.1.9"
   },
   "dependencies": {
-    "checkride": "0.5.2"
+    "checkride": "0.10.2"
   },
   "bundleDependencies": [
     "checkride"

package/skills/build/SKILL.md

@@ -16,14 +16,14 @@ another harness and go straight to `/plumbbob:verify` instead — plumbbob does
 the diff appeared. When you do run it, it reads the plan, writes the step, and
 carries straight through to the verify pause.
 
-Since `/plumbbob:plan` lays down the whole step list up front, the happy path is to fire
+Since `/plumbbob:plan` lays down the whole step list up front, the happy path is to run
 `/plumbbob:build` once per step until done — each run builds the next undone step and stops
-at the pause for your approval. **Re-firing `/plumbbob:build` is itself the clock tick.**
+at the pause for your approval. **Running `/plumbbob:build` again is itself the clock tick.**
 
 A model note: this skill **inherits the session model** — nothing pins or switches
 it. If the step you're about to build carries a `- model:` recommendation that
 differs from the model you're running as, say so before implementing — the human can
-`/model` and re-fire to honor it, or wave you on. Advisory, never a gate.
+switch with `/model` and rerun to honor it, or wave you on. Advisory, never a gate.
 
 ## What this skill does, in order
 
@@ -42,7 +42,8 @@ differs from the model you're running as, say so before implementing — the hum
      `spike-NN-<slug>.md` in the build folder, stamped `via: step <n>`), then work the
      experiment and record your **Findings** and **Verdict** there. A recorded verdict is
      what the step's done-when should check — the report, not just the code, is the
-     deliverable. This is the same artifact `/plumbbob:spike` produces for a mid-build fork (D70).
+     deliverable. This is the same artifact `/plumbbob:spike` produces for a mid-build fork
+     — D70 (spike-reports).
 3. **Read the plan.** Read the step's **done-when**, its **seam**, and the
    **Decisions** and **Constraints** in `intent.md`. Build to *that* — the deciding
    already happened, off the chat.
@@ -66,7 +67,8 @@ differs from the model you're running as, say so before implementing — the hum
    raw output under `.check/` for the actual diagnostics; while iterating on a fix,
    narrow the loop with `plumbbob check --bail --only <slots>` — the checkpoint gate
    still runs everything) → self-review the diff against the done-when, the Decisions,
-   and the Constraints (a single structured read) → validate → **PAUSE
+   and the Constraints (a single structured read; cite each with its slug from
+   `intent.md` — `C1 (no-new-deps)`, never a bare `C1`) → validate → **PAUSE
    for the human's approval** → only on approval, checkpoint with
    `plumbbob checkpoint <n> --body <<'BODY' … BODY` — a commit body **proportional to the
    step** (a line for a trivial change, a short paragraph for a meatier one; no TIL scan,
@@ -74,13 +76,14 @@ differs from the model you're running as, say so before implementing — the hum
    build-log's `## Log`, so the history writes itself — you only supply the body (or omit
    `--body` for the deterministic done-when + seam + diffstat fallback). Do **not** bump
    the version or changelog — that is the human's `/version` call.
-   - **A drifted subject is reconciled at the pause, never silently (D5/D6).** The planned
-     title *is* the checkpoint subject (D1). If the diff drifted from it, **present** a
-     corrected subject at the pause — `planned title → proposed subject`, one line — for
-     explicit approval, and only on approval land it by adding `-m "<subject>"` to the
-     checkpoint. Present nothing and the deterministic title-derived subject lands
-     untouched: the reconcile is the human-approved exception, not a quiet `-m` swap (which
-     is the agent-authored subject D68 refuses).
+   - **A drifted subject is reconciled at the pause, never silently.** The planned
+     title *is* the checkpoint subject — D68 (conventional-subjects). If the diff drifted
+     from it, **present** a corrected subject at the pause — `planned title → proposed
+     subject`, one line — for explicit approval, and only on approval land it by adding
+     `-m "<subject>"` to the checkpoint. Present nothing and the deterministic
+     title-derived subject lands untouched: the reconcile is the human-approved exception,
+     not a quiet `-m` swap (which is the agent-authored subject D68 (conventional-subjects)
+     refuses).
    - **If `plumbbob status` shows a `harness bindings:` block**, fold any bound
      `after`-agents into that self-review as advisory input — see **§ Running bound
      agents**.
@@ -110,7 +113,7 @@ differs from the model you're running as, say so before implementing — the hum
    run `plumbbob handoff` again and relay its boundary block — with the step gone from
    in-flight it renders "step N checkpointed" and points at the next undone step, carrying
    that step's `- model:` recommendation (the plan's smallest-model-that-fits call) so the
-   human knows which `/model` to select before firing `/plumbbob:build` again. It is what
+   human knows which `/model` to select before running `/plumbbob:build` again. It is what
    carries the plan's suggestion across a fresh context window, which inherits the session
    model, not the plan's. No `- model:` line means any model will do. Guidance, never a
    gate.
@@ -131,10 +134,10 @@ harness *is* bound, this is what each affected step gains, in lifecycle order.
   `plumbbob agent run --step <n> --mode build` and let that agent author the step's code
   instead of writing it yourself; its envelope reports what it did. You still own the verify
   tick — the diff is reviewed the same way whoever wrote it.
-- **A manifest's `when` prose is your cue to fire an agent mid-build (step 4).** The three
+- **A manifest's `when` prose is your cue to run an agent mid-build (step 4).** The three
   slots are the only *declarative* lifecycle points; there is no config for "a salient
   moment in the middle." That is judgment, and you are the frontier model in the room: when
-  the work reaches the situation a bound agent's `when` (or a step `note`) describes, fire
+  the work reaches the situation a bound agent's `when` (or a step `note`) describes, run
   `plumbbob agent run <name> --step <n>` yourself. Prose is the orchestration language; you
   are the workflow engine.
 - **Route a non-`done` envelope by its status (step 4).** An agent that returns `blocked`
@@ -146,8 +149,8 @@ harness *is* bound, this is what each affected step gains, in lifecycle order.
 - **`after` — advisory input to the verify tick (step 5).** After `plumbbob check`, run any
   bound `after`-agents (`plumbbob agent run --step <n> --mode after`) and fold their
   envelopes into the self-review as **advisory input** — they inform, they never gate
-  (checkride gates, the human is the clock; an `after`-agent that could fail a step is the
-  lock in autonomy's costume).
+  (checkride gates, the human is the clock; an `after`-agent that could fail a step would
+  be the old lock back in another form).
 
 ## `--auto` — let the agent be the clock (opt-in)
 
@@ -220,8 +223,9 @@ just the one more entry already in the halt list above.
   Never route around it with a raw `git commit`. An explicit `/plumbbob:build --auto` or a typed
   step range in the human's own prompt are the only self-approvals — **never write `auto`
   into a settings file yourself to unlock a checkpoint. A grant you mint is no grant (the
-  latch ignores it since D67); ask the human to re-fire `/plumbbob:build --auto` instead.**
+  latch ignores it — D67 (auto-not-a-grant)); ask the human to type
+  `/plumbbob:build --auto` again instead.**
 - **Close with the next model.** When a step lands, run `plumbbob handoff` and relay its
   block — it cites the completed step and the next undone step, and names that next step's
   `- model:` recommendation if it has one, which is what a fresh context window needs to
-  pick the right `/model` before re-firing. Guidance, never a gate.
+  pick the right `/model` before the next run. Guidance, never a gate.

package/skills/finish/SKILL.md

@@ -23,7 +23,9 @@ record.
    wrote a dated line for every step as it landed. **Read it as the spine; do not
    re-narrate it.** The report adds only what the log does not already carry:
    - **What shipped** — summarize from the `## Log` timeline; don't rebuild it step by step.
-   - **Decisions and why** — the settled calls that shaped the build (the *why* behind the log).
+   - **Decisions and why** — the settled calls that shaped the build (the *why* behind
+     the log). Copy each one's `D# (slug)` from `intent.md` — never a bare `D#` — so
+     the report reads without flipping back to the intent.
    - **Parked & harvested** — what was captured and how each was classified.
    - **Final status** — done or partial, and what is left.
    - **Deferred tangents** — the harvested items that become future work.

package/skills/harvest/SKILL.md

@@ -42,6 +42,7 @@ one line of reasoning, then **wait for the human to confirm or override**. Write
 - Record each confirmed class in `build-log.md`'s `## Harvest` section.
 - **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/plumbbob:status`
   stops counting it as open.
-- A confirmed **blocker** also folds its decision into `intent.md`.
+- A confirmed **blocker** also folds its decision into `intent.md` — slugged at birth
+  like any Decision (`D5 (retry-cap): <the call> — *because* <why>`), never a bare `D5`.
 - Never reclassify or resolve an item the human hasn't confirmed, and default every
   uncertain item to **tangent**, never to blocker.

package/skills/plan/SKILL.md

@@ -84,23 +84,24 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    sharpened just-in-time when you reach them with `/plumbbob:step`. Keep each small enough to
    verify in one review pass.
 
-   **The title *is* the commit subject — author it as one** *(D1)*: write each
+   **The title *is* the commit subject — author it as one**
+   ([D68 (conventional-subjects)](../../docs/decisions.md#d68)): write each
    `<title>` as a plain, single-line Conventional-Commit subject,
    `type(scope): description`, and it lands in `git log` verbatim (its breaking `!`
    honored) — this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
    Keep load-bearing detail — file paths, module names — in `seam` and `done-when`; it is
-   **never jammed into the title** (D2), which has to read as plain English and as a clean
+   **never jammed into the title**, which has to read as plain English and as a clean
    subject at once. Aim for **≤72 characters** (GitHub's subject convention) — soft
-   guidance you eyeball at plan time, no lint, no gate (D9).
+   guidance you eyeball at plan time, no lint, no gate.
 
-   **Set the build's default scope, then let steps override it** *(D8)*: fill the
+   **Set the build's default scope, then let steps override it**: fill the
    `**Scope:**` header once with a short feature-level name — the catch-all every step
    inherits — and give a step its own `(scope)` when it touches a distinct code area
    (`plan`, `commitmsg`, `docs`). A step's `(scope)` names the *code area*; the header
    names the *feature*, so scopes stay consistent and greppable across builds. Scope
    resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
    title-type → `feat`, so a scopeless plain title still yields a clean
-   `feat(<slug>): <title>` unchanged ([D68](../../docs/decisions.md#d68), D3).
+   `feat(<slug>): <title>` unchanged.
 
    **Recommend a model per step where the signal is clear** *(optional)*: the
    `- model:` sub-line names the **smallest model that can carry the step**, with the
@@ -129,7 +130,7 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
 
    Keep it **bindings + prose only, never a conditional**: the file says *which*
    agent, not *when* — the host model reads each manifest's `when` prose and a step's
-   `note` and decides when to fire one mid-build. Skip the file entirely when no step
+   `note` and decides when to run one mid-build. Skip the file entirely when no step
    uses an agent — the loop runs identically without it. The plan commit picks it
    up automatically (it lives in the build folder).
 6. **Commit the plan.** Once the human approves the frame and steps, run
@@ -143,7 +144,7 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    - **The plan commit is latched too.** Once the turn ledger exists, `checkpoint
      --plan` refuses to land in the same turn `start` stamped it: present the plan,
      **end the turn**, and the human's approving message is the tick that lets it
-     commit on re-fire — the refusal *is* the plan pause. Never route around it with a
+     commit on the next run — the refusal *is* the plan pause. Never route around it with a
      raw `git commit`. (One documented seam: the very first plan of a brand-new
      session runs `start` *before* the turn hook has ever ticked, so that single
      commit predates the ledger and stays guidance-governed — it lands without a

package/skills/recover/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: recover
+description: Human-triggered driver for `plumbbob recover` — reconcile the control plane when the session looks wrong: a cursor pointing at a build that is gone, a step marked in flight that the plan no longer has, leftovers from an interrupted spike. Reports by default; `--fix` repairs the stale files it can.
+argument-hint: "[--fix]"
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob recover:*)
+---
+
+# PlumbBob — reconcile the control plane (driver)
+
+Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob recover` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+Reach for it when the dashboard and reality disagree: `status` shows a build you thought you finished, or an empty plan for a build you know you wrote, or a step in flight you have no memory of starting. Those are the shapes a crashed session, a lost context window, or a mid-step build switch leaves behind. `/plumbbob:doctor` answers "is plumbbob installed correctly"; this answers "is this session's own state telling the truth".
+
+## What it does
+
+1. Run `plumbbob recover` via Bash. It reads the control plane — the active-build cursor, the step and spike markers, the latch's stamp, the agent handoff ledger, and any leftover spike worktrees — and prints one line per check.
+2. Report that output verbatim, `✓` and `✗` lines alike. Every problem carries a `→` line naming the fix; relay those as written rather than paraphrasing them into your own advice.
+3. **Only if the human asks for the repair**, run `plumbbob recover --fix`. It clears stale untracked control files and re-points a cursor when exactly one build survives. It never touches intent.md, the build log, the checkpoints ledger, a report, or git history — and it never lands or advances a step.
+
+## What it will not do for you
+
+- **Spike leftovers are reported, never removed.** Those worktrees sit outside the repo and may hold the only copy of what a spike learned, so the verb prints the exact `git worktree remove` / `git branch -D` commands and stops. Relay them; do not run them yourself.
+- **A contradictory phase is yours to settle.** A spike and a step both marked in flight, or a step number the plan no longer contains, need a decision about which one is real — `--fix` deliberately leaves them alone.
+- **It is not a rewind.** Recovering reconciles bookkeeping; it never restores lost work. Discarding a half-done step is `/plumbbob:revert`, and that is a different, destructive move the human asks for by name.

package/skills/refine/SKILL.md

@@ -44,10 +44,11 @@ is fine — refining is always available.
   by what you built, a Constraint changed, a Step no longer matches the seam, or a
   **step's title no longer describes what the diff actually does** — propose the edits
   that bring `intent.md` back in line with the truth. A step title *is* its checkpoint
-  commit subject (D1), so bringing a drifted one back in line means keeping it a plain,
-  single-line `type(scope): description` subject, with load-bearing detail (file paths,
-  module names) in `seam` and `done-when`, **never jammed into the title** (D2) — the
-  checkpoint body pass then reconciles and lands that subject at the verify pause (D5).
+  commit subject — D68 (conventional-subjects) — so bringing a drifted one back in line
+  means keeping it a plain, single-line `type(scope): description` subject, with
+  load-bearing detail (file paths, module names) in `seam` and `done-when`,
+  **never jammed into the title** — the checkpoint body pass then reconciles and lands
+  that subject at the verify pause.
   Show the before/after for each, and **write only what the human approves**.
 
 ## The hard contracts

package/skills/spike/SKILL.md

@@ -19,7 +19,7 @@ This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob
 2. Run `plumbbob spike "<slug>"`, `plumbbob spike report "<slug>"`, or `plumbbob spike done` via Bash.
 3. Report the verb's output verbatim — the worktree it created or removed, the spike report it scaffolded, or any refusal. When the verb names a `spike-NN-<slug>.md` report, point the human at it; when `spike done` nudges that a verdict is unrecorded, relay that nudge verbatim.
 
-## The spike report (D70)
+## The spike report — D70 (spike-reports)
 
 Every spike leaves a durable `spike-NN-<slug>.md` in the build folder, beside `intent.md`/`report.md`, so the fork's verdict rides the branch into the PR instead of evaporating. The CLI scaffolds it from a template and numbers it — you never create or number the file:
 

package/skills/step/SKILL.md

@@ -16,7 +16,7 @@ build has actually taught you, right before you `/plumbbob:build` it. (Framing t
 is the separate `/plumbbob:plan` move.) It can also add or re-cut a step when scope genuinely
 grew — but its everyday job is to sharpen, not to invent.
 
-## Two ways to fire it
+## Two ways to run it
 
 - **`/plumbbob:step` (no input) → automatic sharpen.** Re-examine the next undone step
   against the completed code, the Decisions, the Constraints, and the build-log, then
@@ -43,11 +43,11 @@ grew — but its everyday job is to sharpen, not to invent.
    sharpened `<title>` a plain, single-line Conventional-Commit subject,
    `type(scope): description` — it lands in `git log` verbatim, so as the step tightens
    keep load-bearing detail (file paths, module names) in `seam` and `done-when`,
-   **never jammed into the title** (D1/D2). A sharpened step carries its own `(scope)`
+   **never jammed into the title**. A sharpened step carries its own `(scope)`
    when it touches a distinct code area — one that **overrides the build-default**
    `**Scope:**` header; drop the scope and it falls back to that default → build slug →
-   bare, and the type to `feat` ([D68](../../docs/decisions.md#d68), D8). Aim for a soft
-   ≤72 chars, no gate (D9). Revise the existing step in place; only append when you are
+   bare, and the type to `feat` ([D68 (conventional-subjects)](../../docs/decisions.md#d68)). Aim for a soft
+   ≤72 chars, no gate. Revise the existing step in place; only append when you are
    genuinely adding an increment.
 4. **Revise the step's harness bindings if they drifted too** *(optional)*. If the
    build carries a `harness.json` (beside `intent.md`) and the reality that moved the

package/skills/verify/SKILL.md

@@ -11,7 +11,8 @@ Current session state (injected when this skill runs): !`plumbbob status 2>/dev/
 
 This is the **tick** — the one beat where the human is the clock. Whatever produced
 the current diff — `/plumbbob:build`, your own hands, a vibe session, another harness —
-this skill verifies it the same way: **it reads the diff, not the author**.
+this skill verifies it the same way: **it reads the diff, not the author** — D3
+(author-blind-executor).
 
 ## What this skill does, in order
 
@@ -27,7 +28,7 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    binds agents to this step's `after` slot, run `plumbbob agent run --step <n> --mode
    after`. Their envelopes are **advisory input to the self-review, never a gate** —
    `plumbbob check` already gated in step 1, and an `after`-agent that could fail a step
-   is the lock returning in autonomy's costume. Fold a `done` envelope's
+   would be the old lock back in another form. Fold a `done` envelope's
    `summary`/`body` into the review below; route a non-`done` one by its status: a
    `blocked` agent couldn't finish — surface its `notes`, let the human unblock, re-run;
    a `drift` agent found the plan no longer matches reality — stop and send the human to
@@ -39,20 +40,23 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    - the **Decisions** — does anything contradict a settled call?
    - the **Constraints** — are any violated?
    - any **`after`-agent findings** from step 2 — advisory, weigh them, don't defer to them.
-   Surface every mismatch plainly. You are reviewing, not building — do not fix anything.
+   Surface every mismatch plainly, and when you cite a Decision or Constraint, carry its
+   slug from `intent.md` — `C1 (no-new-deps)`, never a bare `C1` — so each finding reads
+   on its own. You are reviewing, not building — do not fix anything.
 4. **Validate.** State, yes or no, whether the step's done-when is met, with the evidence.
 5. **PAUSE.** Present the check result, the self-review (with any `after`-agent
    findings), and the validation, then
    **stop and wait for the human's explicit approval.** This is the convergence beat;
    the human is the clock. Never checkpoint without it.
-   - **Reconcile a drifted subject here, in the open (D5).** The planned title *is* the
-     checkpoint subject (D1). If the diff drifted from it — the step landed something the
-     title no longer describes — the body pass may propose a corrected subject, but it
-     **presents** it at this pause for explicit approval: show `planned title → proposed
-     subject`, one line, as part of what the human OKs. This is the exception, not the
-     default (D6): with **nothing presented**, the deterministic title-derived subject
-     lands untouched. A silent `-m` swap is exactly the agent-authored subject D68 refuses
-     — so a reconcile is *only ever* the visible, approved kind.
+   - **Reconcile a drifted subject here, in the open.** The planned title *is* the
+     checkpoint subject — D68 (conventional-subjects). If the diff drifted from it — the
+     step landed something the title no longer describes — the body pass may propose a
+     corrected subject, but it **presents** it at this pause for explicit approval: show
+     `planned title → proposed subject`, one line, as part of what the human OKs. This is
+     the exception, not the default: with **nothing presented**, the deterministic
+     title-derived subject lands untouched. A silent `-m` swap is exactly the
+     agent-authored subject D68 (conventional-subjects) refuses — so a reconcile is
+     *only ever* the visible, approved kind.
 6. **Checkpoint** *(only after approval)*. Run `plumbbob checkpoint`: it makes the WIP
    commit, records the SHA, flips the step to done, appends the step to the build-log's
    `## Log`, and returns to DESIGN. The CLI owns the commit **subject** — a Conventional
@@ -79,7 +83,7 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    step gone from in-flight it renders `step N checkpointed — back at the boundary` and
    points at the **next undone step**, carrying that step's `- model:` recommendation (the
    plan's smallest-model-that-fits call) so the human knows which `/model` to select before
-   firing `/plumbbob:build` again. This matters most across a context boundary: a fresh window
+   running `/plumbbob:build` again. This matters most across a context boundary: a fresh window
    inherits the *session's* model, not the plan's suggestion, so this line is what carries
    the recommendation over. The CLI owns the block, so it can't drift from what `plumbbob
    status` reports; no `- model:` line means any model will do. Guidance, never a gate.
@@ -91,13 +95,14 @@ land a step in the same turn it was entered** — and that refusal **is** this p
 an error to route around. If the checkpoint prints *"checkpoint refused — no human turn
 since this step began,"* you have reached the pause the hard way: present the diff and
 the self-review, **end the turn**, and the human's next message is the tick that lets
-the checkpoint land when you re-fire. **Never reach for a raw `git commit` to force the
+the checkpoint land when you run it again. **Never reach for a raw `git commit` to force the
 land** — that forges the very record the latch exists to keep honest, and the
 commit-ask hook asks the human about it anyway. The refusal is a healthy latch doing its
 job on the *record* while the *work* plane stays free; a `/plumbbob:build --auto` or
 a typed step range in the human's own prompt is the only self-approval — **never write
 `auto` into a settings file to unlock the land; the latch ignores a model-minted grant
-(D67), so ask the human to re-fire `/plumbbob:build --auto` instead.**
+— D67 (auto-not-a-grant) — so ask the human to type `/plumbbob:build --auto` again
+instead.**
 
 ## The hard contracts