plumbbob 0.9.3 → 0.10.0

package/skills/verify/SKILL.md

@@ -1,65 +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**.
+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
-   is the lock returning in autonomy's costume. 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
+   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
    `/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.
-   Surface every mismatch plainly. You are reviewing, not building — do not fix anything.
+   - 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.
 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)](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)](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'
@@ -67,11 +71,16 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    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`
@@ -79,7 +88,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.
@@ -87,17 +96,18 @@ this skill verifies it the same way: **it reads the diff, not the author**.
 ## 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 re-fire. **Never reach for a raw `git commit` to force the
-land** — that forges the very record the latch exists to keep honest, and 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
+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)](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
 
@@ -108,15 +118,15 @@ a typed step range in the human's own prompt is the only self-approval — **nev
 - **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 (D4): 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 (D7). -->
+**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,84 +37,95 @@ 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).
-The step title *is* the checkpoint's commit subject: write it as one plain line,
-`type(scope): description` — load-bearing paths live in `seam`, never jammed into the
-title (D2) — aiming for ≤72 characters (GitHub's subject convention: soft, no gate, D9).
+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 (D8). Scope
+build's `**Scope:**` header is the feature-level catch-all a step overrides. Scope
 resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
-title-type → `feat` (D3/D68). Then drive `/plumbbob:build` until done. Later steps may be
+title-type → `feat`. Then drive `/plumbbob:build` until done. Later steps may be
 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.)*