plumbbob 0.9.5 → 0.10.0

package/skills/spike/SKILL.md

@@ -1,29 +1,29 @@
 ---
 name: spike
-description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, scaffold a spike report for a spike-as-step, or tear it down with `spike done`.
+description: "Human-triggered driver for `plumbbob spike`: open a throwaway worktree experiment for a genuine fork, scaffold a spike report for a spike-as-step, or tear it down with `spike done`."
 argument-hint: "<slug> | report <slug> | done"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob spike:*)
 ---
 
-# PlumbBob — spike an experiment (driver)
+# PlumbBob: spike an experiment (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 spike` 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.
+This is a **driver skill**: a chat-side trigger for the mechanical `plumbbob spike` 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.
 
 ## What it does
 
-1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/plumbbob:spike redis-cache`), `report <slug>` to scaffold a report without worktrees (`/plumbbob:spike report auth-store`), or the literal `done` to tear the current spike down (`/plumbbob:spike done`). If none is present, ask which and run nothing.
+1. Read the spike target from the way you were invoked: a slug to open one (for example `/plumbbob:spike redis-cache`), `report <slug>` to scaffold a report without worktrees (`/plumbbob:spike report auth-store`), or the literal `done` to tear the current spike down (`/plumbbob:spike done`). If none is present, ask which and run nothing.
 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.
+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 (spike-reports)
+## The spike report ([D70 (spike-reports)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d70))
 
-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:
+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:
 
 - **`/plumbbob:spike <slug>`** scaffolds the report *at open*, so findings accrue while the throwaway worktrees are still live. Fill its **Findings** and **Verdict** before `/plumbbob:spike done`.
-- **`/plumbbob:spike report <slug>`** is for a *spike-as-step* — a planned step titled `spike: …`, where the increment itself is the experiment and there are no worktrees. It stamps the report's provenance as `step <n>` when a step is in flight.
+- **`/plumbbob:spike report <slug>`** is for a *spike-as-step*: a planned step titled `spike: …`, where the increment itself is the experiment and there are no worktrees. It stamps the report's provenance as `step <n>` when a step is in flight.
 
-This skill stays Write-less: the CLI owns the file. Your job is to run the verb and, between runs, help the human fill the report's prose — but the edits land through the normal build flow, not this driver.
+This skill stays Write-less: the CLI owns the file. Your job is to run the verb and, between runs, help the human fill the report's prose, but the edits land through the normal build flow, not this driver.

package/skills/status/SKILL.md

@@ -1,26 +1,26 @@
 ---
 name: status
-description: Show the orientation dashboard — where you are, what's done, what's parked, and the next move. A thin trigger for `plumbbob status`.
+description: "Show the orientation dashboard: where you are, what's done, what's parked, and the next move. A thin trigger for `plumbbob status`."
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*)
 ---
 
-# PlumbBob — orient (the where-am-I move)
+# PlumbBob: orient (the where-am-I move)
 
 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 **thin driver** for `plumbbob status`. The dashboard above is your
-orientation — the intent, the step list, the parked/open-question counts, and the
+orientation: the intent, the step list, the parked/open-question counts, and the
 inferred next move. Report it verbatim and point the human at that next move. This
 skill carries **no Edit and no Write tool**: the CLI is the source of truth, so
 **never retry**, and never edit a file to change what the orientation says.
 
 ## What it does
 
-1. Surface the injected `status` output — the dashboard and its suggested next move.
+1. Surface the injected `status` output: the dashboard and its suggested next move.
 2. If the next step's detail carries a `model:` line, point it out: it is the
    plan's recommendation of the smallest model that can carry that step, so the human
-   can switch (e.g. `/model sonnet`) before firing `/plumbbob:build` — or ignore it. Guidance,
+   can switch (for example `/model sonnet`) before firing `/plumbbob:build`, or ignore it. Guidance,
    never a gate.
 3. If it reads `NO ACTIVE SESSION`, tell the human to `/plumbbob:plan` to frame a goal.

package/skills/step/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: step
-description: Revise the next increment just-in-time — sharpen the next undone step against what's now true, or (with input) re-cut, split, or add a step. Empty input runs an automatic sharpen. One at a time; the human approves.
+description: "Revise the next increment just-in-time: sharpen the next undone step against what's now true, or (with input) re-cut, split, or add a step. Empty input runs an automatic sharpen. One at a time; the human approves."
 argument-hint: "[what-changed]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob agent list:*)
 ---
 
-# PlumbBob — revise the next step (the single-increment move)
+# PlumbBob: revise the next step (the single-increment move)
 
 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."`
 
@@ -14,14 +14,14 @@ Current session state (injected when this skill runs): !`plumbbob status 2>/dev/
 **just-in-time revision** move: it keeps the *next* undone step honest against what the
 build has actually taught you, right before you `/plumbbob:build` it. (Framing the whole goal
 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.
+grew, but its everyday job is to sharpen, not to invent.
 
 ## 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
-  make the obvious revisions to its **done-when** and **seam** so it matches reality —
-  e.g. a file moved, a decision narrowed the scope, an earlier step already did part of
+  make the obvious revisions to its **done-when** and **seam** so it matches reality:
+  for example a file moved, a decision narrowed the scope, an earlier step already did part of
   it. This is the zero-effort "keep my next step in sync" move: if the human does
   nothing else, the next step stays current.
 - **`/plumbbob:step <what changed>` → directed revision.** Take the human's input and propose
@@ -38,21 +38,21 @@ grew — but its everyday job is to sharpen, not to invent.
    what you changed and why. Re-check the optional `- model:` recommendation too:
    a step that sharpened into rote work can drop to a smaller model; one that grew subtle
    earns a frontier one. Advisory, plain text (no backticks), never a gate.
-3. **Get the human's OK**, then write it into `## Steps` in the standard format —
-   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Keep the
+3. **Get the human's OK**, then write it into `## Steps` in the standard format:
+   `N. [ ] <title>, **done when:** <criterion>` with a `- seam:` sub-line. Keep the
    sharpened `<title>` a plain, single-line Conventional-Commit subject,
-   `type(scope): description` — it lands in `git log` verbatim, so as the step tightens
+   `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**. A sharpened step carries its own `(scope)`
-   when it touches a distinct code area — one that **overrides the build-default**
+   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 (conventional-subjects)](../../docs/decisions.md#d68)). Aim for a soft
+   bare, and the type to `feat` ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/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
    step also changed which agents it wants, sharpen that step's slot bindings
-   (`before`/`build`/`after`) and `note` at the same time — this is the just-in-time
+   (`before`/`build`/`after`) and `note` at the same time; this is the just-in-time
    counterpart to `/plumbbob:plan`'s plan-time binding. `plumbbob agent list` shows what's
    resolvable. Same rule as the plan move: bindings + prose only, never a conditional
   . Leave it untouched when the step's agents are still right, or when the build
@@ -62,6 +62,11 @@ grew — but its everyday job is to sharpen, not to invent.
 
 - **One verifiable increment.** Each step carries a done-when `/plumbbob:verify` can check
   and a seam small enough to review in one pass.
-- **Edit `## Steps` only**, in the standard format `status` and `build` parse — never
+- **Edit `## Steps` only**, in the standard format `status` and `build` parse: never
   the Roadmap, never loose prose. A done step (`[x]`) is history; do not rewrite it.
+- **Cite the plan's own numbers in the linked form.** A `D`/`C`/`Q` you write into a
+  step's done-when, seam, or notes reads `[D4 (default-waves)](#d4)`; the slug travels
+  with the number, and the link lands on the `<a id="d4">` anchor minted where the item
+  was born. Never a bare `D4`; if the item you want to cite has no anchor yet, that is a
+  `/plumbbob:refine` repair, not something to invent here.
 - **The human approves the revision** before it lands. You propose; they decide.

package/skills/verify/SKILL.md

@@ -1,69 +1,69 @@
 ---
 name: verify
-description: "The verify tick — run the check, self-review the diff against intent, validate the step's done-when, pause for your approval, then checkpoint. Executor-agnostic: it reads the diff, not who wrote it."
+description: "The verify tick: run the check, self-review the diff against intent, validate the step's done-when, pause for your approval, then checkpoint. Executor-agnostic: it reads the diff, not who wrote it."
 disable-model-invocation: true
 allowed-tools: Read, Bash(plumbbob status:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*), Bash(git status:*)
 ---
 
-# PlumbBob — verify a step (the tick)
+# PlumbBob: verify a step (the tick)
 
 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 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** — D3
-(author-blind-executor).
+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**
+([D3 (author-blind-executor)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d3)).
 
 ## What this skill does, in order
 
-1. **Check.** Run `plumbbob check` (the heavy gate — checkride unless the repo
+1. **Check.** Run `plumbbob check` (the heavy gate: checkride unless the repo
    configures a `check` override). If it comes back **red**, stop here: the gate
-   names the failing slots and where each tool's raw output landed — read
+   names the failing slots and where each tool's raw output landed: read
    `.check/summary.json`, then the failing slot's own file (`.check/<slot>.json` or
    `.check/<slot>.stdout.txt`) for the actual diagnostics instead of scraping
-   scrollback. Report what failed and do **not** pause for approval — there is
+   scrollback. Report what failed and do **not** pause for approval; there is
    nothing to approve yet. The human fixes it and re-invokes. (Exit 2 means the gate
-   itself broke — a harness problem to surface, not a code failure.)
+   itself broke: a harness problem to surface, not a code failure.)
 2. **Run any bound `after`-agents** *(optional)*. If the build's `harness.json`
    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** —
+   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
    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
+   `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
    `/plumbbob:refine` to repair the plan before checkpointing. No binding, or no harness, is a
    clean no-op.
 3. **Self-review** *(a single structured read)*. Read `git diff` and
    `.plumbbob/intent.md`, then in one pass check the diff against:
-   - the current step's **done-when** criterion — is it actually met?
-   - 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.
+   - the current step's **done-when** criterion: is it actually met?
+   - 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, 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.
+   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.** 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
+     checkpoint subject ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). 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
+     agent-authored subject [D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68) 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
-   `<type>(<scope>): <description>` composed from the step title and the build slug — and
+   `## Log`, and returns to DESIGN. The CLI owns the commit **subject** (a Conventional
+   `<type>(<scope>): <description>` composed from the step title and the build slug) and
    leads the **body** with a `plumbbob step N` marker; you own the rest of the **body**.
-   Compose a body *proportional to the step* — a one-liner for a trivial change, a short
-   paragraph on the what/why for a meatier one — and pass it on stdin:
+   Compose a body *proportional to the step* (a one-liner for a trivial change, a short
+   paragraph on the what/why for a meatier one) and pass it on stdin:
 
    ```bash
    plumbbob checkpoint <n> --body <<'BODY'
@@ -71,11 +71,16 @@ this skill verifies it the same way: **it reads the diff, not the author** — D
    BODY
    ```
 
-   Do **not** run a TIL scan or reach for a separate commit skill — the body is yours to
+   Redirect the heredoc *into* the command (`--body <<'BODY'`). Do **not** pass it as
+   an argument value (`--body "$(cat <<'BODY'…)"`): `--body` ignores an argument and
+   always reads stdin. Under an agent harness that stdin is a socket, and `--body` now
+   refuses rather than blocking on one; the refusal names this exact heredoc form.
+
+   Do **not** run a TIL scan or reach for a separate commit skill; the body is yours to
    write in one breath. Omit `--body` entirely and the CLI writes a deterministic body
    (done-when + seam + diffstat) on its own. Either way, do **not** bump the version or
-   touch the changelog — that is the human's `/version` call. And if step 5 surfaced a
-   drifted subject the human approved, land *that* subject by adding `-m "<subject>"` —
+   touch the changelog; that is the human's `/version` call. And if step 5 surfaced a
+   drifted subject the human approved, land *that* subject by adding `-m "<subject>"`,
    overriding the title-derived default for this one commit; unpresented, the CLI's
    deterministic subject stands.
 7. **Hand off with the next model** *(once the checkpoint lands)*. `plumbbob checkpoint`
@@ -91,17 +96,17 @@ this skill verifies it the same way: **it reads the diff, not the author** — D
 ## The latch makes the pause real
 
 When this session runs under plumbbob's turn hook, `plumbbob checkpoint` **refuses to
-land a step in the same turn it was entered** — and that refusal **is** this pause, not
-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
+land a step in the same turn it was entered**, and that refusal **is** this pause, not
+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 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
+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
+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 (auto-not-a-grant) — so ask the human to type `/plumbbob:build --auto` again
+([D67 (auto-not-a-grant)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d67)), so ask the human to type `/plumbbob:build --auto` again
 instead.**
 
 ## The hard contracts
@@ -113,15 +118,15 @@ instead.**
 - **Red means stop, not pause.** A failing check is not an approval decision; report
   it and end your turn.
 - **You review; you do not build.** If the self-review finds a problem, surface it
-  and stop — fixing is a new build beat, not part of verify.
+  and stop; fixing is a new build beat, not part of verify.
 - **`after`-agents advise; they never gate**. Their output feeds the
-  self-review — checkride gates, the human approves. `blocked` → unblock and re-run;
+  self-review; checkride gates, the human approves. `blocked` → unblock and re-run;
   `drift` → `/plumbbob:refine` before checkpointing. No code path makes them blocking.
 - **A refused checkpoint is the pause, never a workaround.** Under the turn
-  hook a same-turn checkpoint is refused *by design* — present the diff, **end the
+  hook a same-turn checkpoint is refused *by design*: present the diff, **end the
   turn**, and let the human's next message re-tick it. Never route around it with a raw
   `git commit`; the latch guards the record, not the work.
 - **Close with the next model.** After the checkpoint lands, run `plumbbob handoff` and
-  relay its block — it cites the completed step and the next undone step, and surfaces that
+  relay its block; it cites the completed step and the next undone step, and surfaces that
   next step's `- model:` recommendation when it has one, which is what a fresh context
   window needs to pick the right `/model`. Guidance, never a gate.

package/templates/build-log.md

@@ -1,26 +1,26 @@
 <!--
-build-log.md — your live ledger for execution. Append constantly; reorganize at
+build-log.md: your live ledger for execution. Append constantly; reorganize at
 step boundaries. The antidote to "my plan got lost in the noise."
 
   Steps     : where you are. One step in flight at a time. CLI-maintained: `build`,
               `checkpoint`, and `revert` keep this mirror and the Current step line
-              in sync with intent.md — you never hand-edit them.
+              in sync with intent.md; you never hand-edit them.
   Park list : where ideas go so you do not chase them. CAPTURE, never act inline.
   Harvest   : the boundary ritual that keeps you on one branch.
   Log       : the build's history. `plumbbob checkpoint` appends a line per step as it
               lands; feeds the /plumbbob:finish report, which rides the branch into the PR.
 -->
 
-# Build log — {{TITLE}}
+# Build log: {{TITLE}}
 
 **Current step:** none (at the boundary)
 **Heavy check:** {{CHECK}}
 
 ## Steps
 
-*(Mirror of intent.md's Steps, with live status — CLI-maintained, not hand-edited.
+*(Mirror of intent.md's Steps, with live status; CLI-maintained, not hand-edited.
 `build`/`checkpoint`/`revert` re-render this from intent.md, and set the Current step
-line above. Only ONE step is in flight; a step is done only after a checkpoint —
+line above. Only ONE step is in flight; a step is done only after a checkpoint:
 check green + checkpoint taken, via `/plumbbob:verify` or `/plumbbob:build`.)*
 
 - ☐ 1. <step>
@@ -52,8 +52,8 @@ Harvest results this boundary:
 ## Log
 
 *(The build's history, oldest first. `plumbbob checkpoint` appends a dated line here
-every time a step lands — via `/plumbbob:build` or `/plumbbob:verify` — so this
+every time a step lands (via `/plumbbob:build` or `/plumbbob:verify`), so this
 fills in as you go, not at the end. Add your own decision/event lines too: this is what
-you point at to say "I did that — the LLM helped, but those were my calls."
+you point at to say "I did that: the LLM helped, but those were my calls."
 `/plumbbob:finish` reads this for the report; `plumbbob finish` commits it with the build
 folder, so it rides the branch into the PR.)*

package/templates/intent.md

@@ -1,5 +1,5 @@
 <!--
-intent.md — your canonical intent, written in DESIGN before any code. This is the
+intent.md: your canonical intent, written in DESIGN before any code. This is the
 head; the chat is the hand. When the model floods you, read this, not your memory.
 
 Size to the work: a small change fills Frame + a couple of Decisions and deletes
@@ -7,8 +7,8 @@ the rest; a medium feature fills it all. Opinionated where decided, explicit whe
 open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
 
 One rule runs through the whole doc: compress what's settled; expand what's pending.
-Decisions and Constraints stay one line each — they re-inject into every build step,
-so their tokens recur. Open questions expand into plain-then-lean prose — a human
+Decisions and Constraints stay one line each; they re-inject into every build step,
+so their tokens recur. Open questions expand into plain-then-lean prose; a human
 reads them once, to decide, and that legibility buys back a chat round-trip.
 -->
 
@@ -16,11 +16,11 @@ reads them once, to decide, and that legibility buys back a chat round-trip.
 
 **Phase** (your own bookkeeping while framing): frame
 **Size:** tiny | small | medium
-**Scope:** <short-scope>  <!-- the build's default commit scope — D68 (conventional-subjects): a short feature-level name each step's own `(scope)` overrides. Leave the `<…>` placeholder (or blank) and it parses as absent — commits fall through to the build slug. -->
+**Scope:** <short-scope>  <!-- the build's default commit scope (plumbbob [D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)): a short feature-level name each step's own `(scope)` overrides. Leave the `<…>` placeholder (or blank) and it parses as absent; commits fall through to the build slug. -->
 
 ## Frame
 
-*(You, on paper first. The problem in plain words — before any solution.)*
+*(You, on paper first. The problem in plain words, before any solution.)*
 
 - **Problem:** <what is wrong or missing, and why it matters>
 - **Smallest thing that solves it:** <the minimal change, not the ideal system>
@@ -37,32 +37,34 @@ reads them once, to decide, and that legibility buys back a chat round-trip.
 
 ## Decisions
 
-*(One line each — settled, not re-litigated in the chat. Grows as you resolve the
-holes `/plumbbob:refine` surfaces, and as blockers fold in during BUILD. Mint a two- or
-three-word slug where each item is born — `D1 (slug-here)` — and copy that slug at
-every reference site, so a later `D4 (default-waves)` never decays into a bare `D4`
-a cold reader has to hunt down.)*
+*(One line each: settled, not re-litigated in the chat. Grows as you resolve the
+holes `/plumbbob:refine` surfaces, and as blockers fold in during BUILD. **Anchor and slug
+each item where it is born**: a two- or three-word slug, and an `<a id="…">` for
+references to land on; then cite it from anywhere else in this file as
+`[D1 (slug-here)](#d1)`, carrying that same slug verbatim. One link, one glance: a later
+`D4` never decays into a bare number a cold reader has to hunt down.)*
 
-- D1 (slug-here): <decision> — *because* <the one reason that mattered>
+- <a id="d1"></a>**D1 (slug-here)**: <decision>, *because* <the one reason that mattered>
 
 ## Constraints
 
 *(Hard rules the build must honor. `/plumbbob:verify` and `/plumbbob:refine` read against these.
-Slug and gloss them at birth too — `C1 (no-new-deps)` — same one line, same rule.)*
+Anchor and slug them at birth too (cited as `[C1 (no-new-deps)](#c1)`): same one line,
+same rule.)*
 
-- C1 (no-new-deps): <e.g. functional/procedural only; no new dependencies>
+- <a id="c1"></a>**C1 (no-new-deps)**: <for example functional/procedural only; no new dependencies>
 
 ## Steps
 
-*(The build plan. `/plumbbob:plan` authors the **whole list up front** — each step a small,
+*(The build plan. `/plumbbob:plan` authors the **whole list up front**: each step a small,
 verifiable increment with its own **done-when** and **seam** (the paths it will touch,
-which `/plumbbob:build` records in the build folder's `SEAM` for orientation — awareness, not a lock).
-An optional **model** line recommends the smallest model that can carry the step —
+which `/plumbbob:build` records in the build folder's `SEAM` for orientation: awareness, not a lock).
+An optional **model** line recommends the smallest model that can carry the step:
 mechanical work runs fine on a small model; subtle or creative work earns a frontier
-one. Advisory for the human, never a gate; write it plain, no backticks — D62
-(model-recommendation). The step title *is* the checkpoint's commit subject — D68
-(conventional-subjects): write it as one plain line, `type(scope): description` —
-load-bearing paths live in `seam`, never jammed into the title — aiming for ≤72
+one. Advisory for the human, never a gate; write it plain, no backticks (plumbbob
+[D62 (model-recommendation)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d62)). The step title *is* the checkpoint's commit subject
+(plumbbob [D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)): write it as one plain line, `type(scope): description`
+(load-bearing paths live in `seam`, never jammed into the title), aiming for ≤72
 characters (GitHub's subject convention: soft, no gate).
 The `(scope)` names the primary code area the step touches (`plan`, `commitmsg`); the
 build's `**Scope:**` header is the feature-level catch-all a step overrides. Scope
@@ -71,51 +73,59 @@ title-type → `feat`. Then drive `/plumbbob:build` until done. Later steps may
 fuzzier than the first; sharpen the next one just-in-time with `/plumbbob:step` (empty input
 auto-syncs it), and use `/plumbbob:refine` to repair the whole plan when a blocker rewrites it.)*
 
-1. [ ] feat: <step> — **done when:** <criterion, ideally a test or check result>
+1. [ ] feat: <step>, **done when:** <criterion, ideally a test or check result>
    - seam: `<file>`, `<file>`
-   - model: <smallest that can carry it, e.g. sonnet — mechanical, fully specified>
-2. [ ] <step> — **done when:** <criterion>
+   - model: <smallest that can carry it, for example sonnet (mechanical, fully specified)>
+2. [ ] <step>, **done when:** <criterion>
    - seam: `<file>`
 
 ## Open questions
 
-*(Holes you could NOT resolve on paper — the one section that expands rather than
+*(Holes you could NOT resolve on paper: the one section that expands rather than
 compresses. Do not guess them into Decisions; a genuine fork goes to a SPIKE, with
 the verdict recorded below and in Decisions.)*
 
 <!--
 Write each open question so a cold reader could answer it without flipping back to
-the code or the chat — that cold-reader test is the whole point of expanding it.
+the code or the chat; that cold-reader test is the whole point of expanding it.
 Three lines:
 
-  · the opener — the hole as a question, slugged at birth, tagged
-    *resolve by:* decide | spike | ask
-  · *plain:* — what's at stake, in plain words: the context and the cost of getting
+  · the opener: the hole as a question, anchored and slugged at birth the same way a
+    Decision is (`- <a id="q1"></a>**Q1 (slug-here)**: …`, so a `[Q1 (slug-here)](#q1)`
+    reference has somewhere to land), tagged *resolve by:* decide | spike | ask
+  · *plain:* what's at stake, in plain words: the context and the cost of getting
     it wrong, enough to judge it cold
-  · *lean:* — the model's proposed resolution: one answer to react to, not a menu
+  · *lean:* the model's proposed resolution: one answer to react to, not a menu
 
-The human reads *plain* to understand, then *lean* to approve or redirect — one
+The human reads *plain* to understand, then *lean* to approve or redirect: one
 pass, no round-trip.
 
 When a question resolves, swap *resolve by:* for *resolved:* <date, the call> ON THE
 OPENER LINE, e.g.
 
-  - Q3 (default-waves): *resolved:* 2026-07-18, default off
+  - <a id="q3"></a>**Q3 (default-waves)**: *resolved:* 2026-07-18, default off
 
 The status counter reads opener lines only, so a *resolved:* left on a *plain:* or
-*lean:* sub-line leaves the question still counted as open.
-
-Size to the work: a tiny build's single, obvious question may stay one bare line —
+*lean:* sub-line leaves the question still counted as open
+([D76 (resolved-on-opener)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d76)).
+It reads "resolved" as a whole word, so an opener that still calls itself
+"unresolved" keeps counting. The scaffolded Q1 below stays uncounted for as long as
+its body is unfilled, still opening on its `<...>` fill-in, which is how a fresh
+build reports zero open questions
+([D77 (placeholder-uncounted)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d77));
+fill it in and it counts.
+
+Size to the work: a tiny build's single, obvious question may stay one bare line;
 the *plain:*/*lean:* pair earns its keep only when a human decision genuinely waits
 on it.
 -->
 
-- Q1 (slug-here): <the unresolved hole, framed as a question> — *resolve by:* decide | spike | ask
-  - *plain:* <what's at stake, in plain words — enough to judge it cold>
-  - *lean:* <the model's proposed resolution — the answer to react to>
+- <a id="q1"></a>**Q1 (slug-here)**: <the unresolved hole, framed as a question>, *resolve by:* decide | spike | ask
+  - *plain:* <what's at stake, in plain words, enough to judge it cold>
+  - *lean:* <the model's proposed resolution: the answer to react to>
 
 ## Verdicts
 
-*(Filled in as spikes and forks resolve — the audit trail of "these were my calls.")*
+*(Filled in as spikes and forks resolve: the audit trail of "these were my calls.")*
 
-- <date> — <fork> → chose <option> because <reason>; deleted <the rest>
+- <date>: <fork> → chose <option> because <reason>; deleted <the rest>

package/templates/spike-report.md

@@ -1,16 +1,16 @@
 <!--
-spike-report.md — the durable receipt for a spike (a fork the plan couldn't settle
+spike-report.md: the durable receipt for a spike (a fork the plan couldn't settle
 on paper). One per spike, numbered and named `spike-NN-<slug>.md`, riding the build
-folder into the PR beside intent.md / report.md. Fill it while the experiment is live
-— the worktrees and their learnings are torn down at `spike done`, but this stays.
+folder into the PR beside intent.md / report.md. Fill it while the experiment is
+live; the worktrees and their learnings are torn down at `spike done`, but this stays.
 
 Two ways a spike is born, both landing here:
-  - `/plumbbob:spike <slug>` — an explicit mid-build fork with throwaway worktrees.
-  - a planned step titled `spike: …` — the increment IS the experiment.
+  - `/plumbbob:spike <slug>`: an explicit mid-build fork with throwaway worktrees.
+  - a planned step titled `spike: …`: the increment IS the experiment.
 Record the Verdict before you close the spike (or check off the step).
 -->
 
-# Spike — {{TITLE}}
+# Spike: {{TITLE}}
 
 **Via:** {{VIA}}
 **Opened:** {{DATE}}
@@ -22,17 +22,17 @@ would each answer commit us to?)*
 
 ## Options tried
 
-*(Each path you actually ran, and what it took — one bullet each.)*
+*(Each path you actually ran, and what it took: one bullet each.)*
 
 ## Findings
 
-*(What the experiment showed — evidence, not opinion. Numbers, errors, surprises.)*
+*(What the experiment showed: evidence, not opinion. Numbers, errors, surprises.)*
 
 ## Verdict
 
-**Verdict:** *(viable | not viable | partial — replace this line with the call and why)*
+**Verdict:** *(viable | not viable | partial; replace this line with the call and why)*
 
 ## What this decides
 
-*(The intent.md Decision this feeds — which option won, what dies, and the one reason
+*(The intent.md Decision this feeds: which option won, what dies, and the one reason
 that settled it. Copy the call into intent.md's Decisions / Verdicts too.)*