plumbbob 0.9.3 → 0.10.0

package/skills/build/SKILL.md

@@ -1,116 +1,124 @@
 ---
 name: build
-description: The default engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable — build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses.
+description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses."
 argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
 ---
 
-# PlumbBob — build a step (the default engine)
+# PlumbBob: build a step (the default engine)
 
 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 **bundled executor** — the default engine, not the only one. It is
+This is the **bundled executor**: the default engine, not the only one. It is
 **swappable**: you can implement any step by hand, in a vibe session, or with
-another harness and go straight to `/plumbbob:verify` instead — plumbbob does not care how
+another harness and go straight to `/plumbbob:verify` instead; plumbbob does not care how
 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
-`/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.**
+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. **Running `/plumbbob:build` again is itself the clock tick.**
 
-A model note: this skill **inherits the session model** — nothing pins or switches
+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.
+differs from the model you're running as, say so before implementing; the human can
+switch with `/model` and rerun to honor it, or wave you on. Advisory, never a gate.
 
 ## What this skill does, in order
 
-1. **Pick the step.** Use the number you were invoked with (e.g. `/plumbbob:build 4`) — or,
+1. **Pick the step.** Use the number you were invoked with (for example `/plumbbob:build 4`), or,
    if you were given a range like `/plumbbob:build 1-3`, start at the first number and treat
    the second as the auto-approve ceiling (see the range note under `--auto`). With no
-   argument, don't resolve the next step yourself — the CLI does: bare `plumbbob build`
+   argument, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
    (step 2) enters the next undone step and refuses with a `/plumbbob:step` nudge when every
    step is checkpointed.
-2. **Enter the step.** Run `plumbbob build <n>` — or bare `plumbbob build` to enter the
+2. **Enter the step.** Run `plumbbob build <n>`, or bare `plumbbob build` to enter the
    next undone step (records the in-flight STEP + SEAM so `/plumbbob:status` shows the step in
    flight; the seam is awareness, not a lock).
    - **Spike-as-step.** If the step's title opens with `spike:` / `Spike:`, the increment
-     *is* the experiment — resolving a fork the plan couldn't settle on paper. After
+     *is* the experiment: resolving a fork the plan couldn't settle on paper. After
      entering it, run `plumbbob spike report "<slug>"` (the CLI scaffolds a
      `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).
+     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 (spike-reports)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d70)).
 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
+   **Decisions** and **Constraints** in `intent.md`. Build to *that*; the deciding
    already happened, off the chat.
    - **Bound `before`-agents load context first.** If `plumbbob status` shows a
-     `harness bindings:` block, this build binds agents — see **§ Running bound agents**
+     `harness bindings:` block, this build binds agents; see **§ Running bound agents**
      and load their context in before you write. No bindings, no harness: just build.
 4. **Implement** the step, and only that step, staying within the declared seam. A
    new problem or "ooh what if" that surfaces mid-build is a park, **not** an edit:
-   capture it by running `plumbbob park "<one tidy line>"` — **saying "let's defer
+   capture it by running `plumbbob park "<one tidy line>"`: **saying "let's defer
    that" writes nothing; only the park line in the build log is a capture.** When the
    *human* hands you the tangent mid-build, their message **is** the approval to park
-   it — capture it right away, say what you parked, and stay on the step. If you
+   it; capture it right away, say what you parked, and stay on the step. If you
    genuinely cannot finish without touching more than the seam, that is scope drift:
    surface it to the human rather than sprawling.
    - **Bound agents can shape the build.** If `plumbbob status` shows a
      `harness bindings:` block, a `build`-slot agent may author the diff, a `when`-cue may
-     fire an agent mid-build, and a non-`done` envelope routes by its status — see
+     fire an agent mid-build, and a non-`done` envelope routes by its status; see
      **§ Running bound agents**.
 5. **Verify, through to the pause.** Run the verify tick exactly as `/plumbbob:verify`
    does: `plumbbob check` (on red, read `.check/summary.json` and the failing slot's
    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
+   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
+   `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,
    no separate commit skill). The CLI owns the subject and appends this step to the
-   build-log's `## Log`, so the history writes itself — you only supply the body (or omit
+   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).
+   the version or changelog; that is the human's `/version` call.
+   - **`--body` reads stdin only.** 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.
+   - **A drifted subject is reconciled at the pause, never silently.** 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, **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)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)
+     refuses).
    - **If `plumbbob status` shows a `harness bindings:` block**, fold any bound
-     `after`-agents into that self-review as advisory input — see **§ Running bound
+     `after`-agents into that self-review as advisory input; see **§ Running bound
      agents**.
 
    **The latch makes this pause real.** On the default (non-`--auto`) path you
-   build the step and reach the pause *in one turn* — so under plumbbob's turn hook the
+   build the step and reach the pause *in one turn*, so under plumbbob's turn hook the
    checkpoint at the end of that turn is **refused** ("no human turn since this step
    began"), and that refusal **is** the pause working as designed. Do exactly what the
    pause asks: present the diff and the self-review, emit the closing block below, and
-   **end the turn**. The human's next message — their approval — is the human turn that
+   **end the turn**. The human's next message (their approval) is the human turn that
    lets the checkpoint land: on that turn you run `plumbbob checkpoint <n>` (now allowed)
-   and **stop at the boundary**. Landing the checkpoint is its own deliberate beat — the
-   thing approval triggers — never a side effect of starting the next step, and
+   and **stop at the boundary**. Landing the checkpoint is its own deliberate beat (the
+   thing approval triggers), never a side effect of starting the next step, and
    `/plumbbob:build` only ever starts the *next* step. **Never route around a refusal with a
-   raw `git commit`** — the work plane stays free, but the *record* is latched on purpose.
+   raw `git commit`**; the work plane stays free, but the *record* is latched on purpose.
 
    **End every default build turn with the standardized hand-off block.** Run `plumbbob
-   handoff` and present its output — it renders the same three-part shape (the state, the
+   handoff` and present its output; it renders the same three-part shape (the state, the
    choice, what's next) straight from the session: step N built, the looks-good /
    needs-work choice, and the next undone step with its `- model:` recommendation. Show
    your diff and self-review above it. The CLI owns the block so it can't drift from what
    `/plumbbob:status` reports; you supply only the judgment above it. It already drops the model
-   clause when the next step has none, and says so when no planned step remains — you
+   clause when the next step has none, and says so when no planned step remains; you
    don't reproduce the template by hand.
 
    **Then hand off with the next model.** Once the checkpoint lands in the approval turn,
-   run `plumbbob handoff` again and relay its boundary block — with the step gone from
+   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.
@@ -118,38 +126,38 @@ differs from the model you're running as, say so before implementing — the hum
 ## Running bound agents
 
 Skip this section unless `plumbbob status` shows a `harness bindings:` block. Nearly every
-build binds **no** agents — for them the default path above is the whole story. When a
+build binds **no** agents; for them the default path above is the whole story. When a
 harness *is* bound, this is what each affected step gains, in lifecycle order.
 
-- **`before` — load context in (step 3).** If the build's `harness.json` binds agents to
+- **`before`: load context in (step 3).** If the build's `harness.json` binds agents to
   this step's `before` slot, run `plumbbob agent run --step <n> --mode before` first: each
   returns a validated envelope on stdout that plumbbob also appends to the step's
   `handoff.json`, and its `summary`/`body` become **context you read into the build** (that
-  is the whole point of the slot — load the context in before you write). No binding, or no
-  harness, is a clean no-op — just build.
-- **`build` — delegate the diff (step 4).** If a `build`-slot agent is bound, run
+  is the whole point of the slot: load the context in before you write). No binding, or no
+  harness, is a clean no-op: just build.
+- **`build`: delegate the diff (step 4).** If a `build`-slot agent is bound, run
   `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
+  tick; the diff is reviewed the same way whoever wrote it.
+- **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`
   couldn't finish (missing input, failed precondition): surface its `notes`, let the human
-  unblock, and re-run it — don't work around it. One that returns `drift` finished but found
+  unblock, and re-run it; don't work around it. One that returns `drift` finished but found
   the plan no longer matches reality: **stop and send the human to `/plumbbob:refine`** to repair
   the plan before continuing, rather than building on a plan that's now wrong. A non-zero
   exit is a failed run: report it and stop.
-- **`after` — advisory input to the verify tick (step 5).** After `plumbbob check`, run any
+- **`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).
+  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 would
+  be the old lock back in another form).
 
-## `--auto` — let the agent be the clock (opt-in)
+## `--auto`: let the agent be the clock (opt-in)
 
 `/plumbbob:build --auto` is the explicit escape hatch when the human wants unattended
 progress instead of approving each step. It does the same work, but **the agent reviews
@@ -159,41 +167,41 @@ and approves in the human's place**, and it **chains**:
   order as the default path: bound `before`-agents → implement (or the bound `build`-agent) → bound
   `after`-agents → `check` → self-review → **if the check is green AND the
   self-review finds no done-when / Decision / Constraint mismatch, checkpoint** and move
-  straight on to the next planned step. Repeat. `--auto` adds no new machinery — the
+  straight on to the next planned step. Repeat. `--auto` adds no new machinery; the
   `after`-agent output simply feeds the *existing* self-review halt condition.
 - **Stop and hand back to the human** the moment any of these is true: the check is red,
   the self-review finds a mismatch (surface exactly what, and do not checkpoint it), a
-  bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine` — an
+  bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine`; an
   agent cannot advance the loop), a new decision is needed, no planned steps
   remain, or the top of a requested range is reached. **When `--auto` halts back to the
-  human, give the same hand-off the default pause does** — run `plumbbob handoff` and
+  human, give the same hand-off the default pause does**; run `plumbbob handoff` and
   relay its block: the step just completed, the next undone step, and that next step's
   `- model:` recommendation if it has one, so a fresh context window knows which `/model`
   to select.
 
 `--auto` and a step range are the only paths that checkpoint without a human pause, and
 only because the human asked for it by name; a range re-imposes the pause at its top.
-The default — no flag, no range — always ends at the pause.
+The default (no flag, no range) always ends at the pause.
 
 ### A step range (`N-M`) is a bounded `--auto`
 
 `/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **pauses
-after step 3** instead of chaining to done. The range *is* the opt-in — you do not also
+after step 3** instead of chaining to done. The range *is* the opt-in; you do not also
 pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
-any next step whose plan number is past the top of the range.** It adds no machinery —
+any next step whose plan number is past the top of the range.** It adds no machinery:
 just the one more entry already in the halt list above.
 
-- **`N-M` with N ≤ M** — build N…M, self-approving and checkpointing each, then pause at
+- **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, then pause at
   M. `N-N` is just the single step `N` (which already ends at the pause).
-- **N > M** (e.g. `3-1`) — that is not a range you can walk; report it and stop rather
+- **N > M** (for example `3-1`): that is not a range you can walk; report it and stop rather
   than guess the intent.
-- **M past the last planned step** (e.g. `1-9` with three steps) — build through the
+- **M past the last planned step** (for example `1-9` with three steps): build through the
   last planned step and stop; that is the existing "no planned steps remain" halt, not
   an error.
-- **A step inside the range won't build** (missing, or its seam won't parse) — `plumbbob
+- **A step inside the range won't build** (missing, or its seam won't parse): `plumbbob
   build <n>` fails exactly as it always does; surface it and stop, the same as a red
   check. Do not skip past the gap.
-- **N is above the next undone step** — you are jumping over earlier planned work; note
+- **N is above the next undone step**: you are jumping over earlier planned work; note
   that you are skipping the steps before N, then proceed (the same latitude as a
   single-number jump like `/plumbbob:build 4`).
 
@@ -202,26 +210,27 @@ just the one more entry already in the halt list above.
 - **Swappable, never required.** The loop works without this skill; `/plumbbob:verify`
   checkpoints a hand-built or vibed diff just the same.
 - **Build the decided step, not a new one.** Implement what `intent.md` settled. A
-  new idea mid-build is captured with `plumbbob park`, not an edit — a promise to
+  new idea mid-build is captured with `plumbbob park`, not an edit: a promise to
   defer writes nothing; the park line does.
 - **Default ends at the pause.** Implement → verify → wait for approval; never
   checkpoint without it. Only an explicit `--auto` or a step range lets the agent approve
-  in your place, and it still halts on a red check or any mismatch — a range also stops
+  in your place, and it still halts on a red check or any mismatch; a range also stops
   at its top.
 - **Agents feed the beat; they never advance it**. `before` loads context,
-  `build` writes the diff, `after` is advisory — none can checkpoint, flip a step, or
+  `build` writes the diff, `after` is advisory; none can checkpoint, flip a step, or
   chain. `blocked` → unblock and re-run; `drift` → `/plumbbob:refine`. You are still the one
   who verifies and (bar `--auto`) the human is still the clock. See **§ Running bound
   agents** for the mechanics.
 - **A refused checkpoint is the pause, not an error.** Under plumbbob's turn
-  hook a same-turn `checkpoint` is refused by design — present the diff and the closing
+  hook a same-turn `checkpoint` is refused by design: present the diff and the closing
   block, **end the turn**; the human's approval on their next turn is what lets you land
   it, and landing it is a deliberate beat, not a side effect of the next `/plumbbob:build`.
   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`
+  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)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d67)); 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
+  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/doctor/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: doctor
-description: Diagnose the plugin install from inside a session — is plumbbob linked, are the skills and hook present, is there a collision. A thin trigger for `plumbbob doctor`. Matters most for a marketplace install, where the CLI is on PATH only inside Claude Code.
+description: "Diagnose the plugin install from inside a session: is plumbbob linked, are the skills and hook present, is there a collision. A thin trigger for `plumbbob doctor`. Matters most for a marketplace install, where the CLI is on PATH only inside Claude Code."
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob doctor:*)
 ---
 
-# PlumbBob — doctor (the is-it-installed-right move)
+# PlumbBob: doctor (the is-it-installed-right move)
 
 Install diagnostic (injected when this skill runs): !`plumbbob doctor 2>&1 || true`
 
-This is a **thin driver** for `plumbbob doctor`. The report above is read-only — `doctor`
+This is a **thin driver** for `plumbbob doctor`. The report above is read-only: `doctor`
 inspects, it never writes. This skill carries **no Edit and no Write tool**: never edit a file
 to change what the report says. If a check failed, surface its `→ fix` verbatim and apply
 *that* fix, then have the human **restart Claude Code (or `/reload-plugins`)**. **Never retry.**
@@ -19,23 +19,23 @@ to change what the report says. If a check failed, surface its `→ fix` verbati
 
 The CLI's reach differs by install path, and that is the whole point of running `doctor` here:
 
-- **Marketplace plugin** — `plumbbob` is on PATH **only inside a Claude Code session** (its
-  `bin/` shims are injected into the Bash tool while the plugin is enabled). There is **no
-  terminal `plumbbob`** to run. So this skill — or letting me run `plumbbob doctor` in-session
-  — is the *only* way to reach `doctor`. The fact that this skill loaded at all already proves
+- **Marketplace plugin**: `plumbbob` is on PATH **only inside a Claude Code session** (its
+  `bin/` shims are injected into the Bash tool while the plugin is enabled). **No
+  terminal `plumbbob`** exists. So this skill (or letting me run `plumbbob doctor` in-session)
+  is the *only* way to reach `doctor`. The fact that this skill loaded at all already proves
   the plugin is enabled and the shim is on PATH.
-- **Skills-dir / global install** (`npm i -g plumbbob` + `plumbbob init`) — `plumbbob` is on
+- **Skills-dir / global install** (`npm i -g plumbbob` + `plumbbob init`): `plumbbob` is on
   PATH everywhere, so terminal `plumbbob doctor` works too; this skill is just convenience.
 
 The one failure `doctor` **cannot** diagnose: a plugin that never loaded at all (no
-`/plumbbob:*` skill appears). That is a `/plugin` / `/reload-plugins` problem, not doctor's —
+`/plumbbob:*` skill appears). That is a `/plugin` / `/reload-plugins` problem, not doctor's,
 and if you are reading this, that is not your situation.
 
 ## What it does
 
-1. Surface the injected `doctor` report verbatim — every `✓` and any `✗` with its `→ fix`.
+1. Surface the injected `doctor` report verbatim: every `✓` and any `✗` with its `→ fix`.
    If nothing rendered above (a few headless `-p` sessions skip the injection), just run
-   `plumbbob doctor` yourself — it is in your tools — and surface that.
+   `plumbbob doctor` yourself (it is in your tools) and surface that.
 2. If all checks passed, say so; if a skill still misbehaves, the fix is a restart, not a re-run.
 3. If a check failed, apply its named `→ fix`, then restart Claude Code (or `/reload-plugins`).
 4. If the report is empty or shows `command not found`, the CLI is not on PATH: for a

package/skills/finish/SKILL.md

@@ -1,42 +1,44 @@
 ---
 name: finish
-description: Finish the build — write the report (what shipped, decisions, parked/harvested items, deferred tangents), then make the final commit that closes the session. The build folder rides the branch into the PR — no separate archive. Report by default, no gate.
+description: "Finish the build: write the report (what shipped, decisions, parked/harvested items, deferred tangents), then make the final commit that closes the session. The build folder rides the branch into the PR: no separate archive. Report by default, no gate."
 disable-model-invocation: true
 allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob finish:*)
 ---
 
-# PlumbBob — finish the build (the close-out)
+# PlumbBob: finish the build (the close-out)
 
 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."`
 
 `/plumbbob:finish` ends the build: it captures what happened, then makes the final commit
-that closes the session. **Report by default** — no refuse-without-report gate,
+that closes the session. **Report by default**: no refuse-without-report gate,
 and no separate docs phase. The build folder is tracked: it merges with the
-branch and shows up in the PR, so there is nothing to archive — the folder *is* the
+branch and shows up in the PR, so there is nothing to archive; the folder *is* the
 record.
 
 ## What this skill does, in order
 
 1. **Write the report** to the active build's `report.md`
    (`.plumbbob/builds/<slug>/report.md`), from `intent.md` + `build-log.md`.
-   The build-log's `## Log` is already the chronological history — `plumbbob checkpoint`
+   The build-log's `## Log` is already the chronological history; `plumbbob checkpoint`
    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).
-   - **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.
+   - **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). 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.
    This is the "yeah, I did that" artifact. Write it by default; the human may edit it.
 2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
-   report and makes the final commit — subject `chore(<scope>): finish`, its body
-   led by a `plumbbob finish` marker plus an optional proportional `--body` — then
-   clears the control state (the in-flight markers, then `STATE` last — one delete
+   report and makes the final commit (subject `chore(<scope>): finish`, its body
+   led by a `plumbbob finish` marker plus an optional proportional `--body`), then
+   clears the control state (the in-flight markers, then `STATE` last; one delete
    drops both the session sentinel and the active-build cursor it carries). The
    build folder stays in place, committed, and rides the branch into the PR.
 
    `--body` reads the close-out message from **stdin via a single-quoted heredoc
-   redirect** — the same form the other verbs use:
+   redirect**, the same form the other verbs use:
 
    ```
    plumbbob finish --body <<'BODY'
@@ -46,16 +48,17 @@ record.
 
    Redirect the heredoc *into* the command (`--body <<'BODY'`). Do **not** pass it as
    an argument value (`--body "$(cat <<'BODY'…)"`): `--body` ignores an argument and
-   reads stdin, so that form leaves stdin open with no EOF and the command hangs. Omit
+   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. Omit
    `--body` entirely and the commit carries the `plumbbob finish` marker subject only.
-3. **Point at the next goal** — `/plumbbob:plan` to frame the next one.
+3. **Point at the next goal**: `/plumbbob:plan` to frame the next one.
 
 ## The hard contracts
 
 - **Report by default, never a gate.** Always offer the report; never wall the exit. A
-  bug fix's report can be three lines — size it to the work.
+  bug fix's report can be three lines; size it to the work.
 - **The log is the history; the report is the synthesis.** `checkpoint` already recorded
-  what shipped, step by step — finish applies the *unique additions* (the why, the deferred
+  what shipped, step by step; finish applies the *unique additions* (the why, the deferred
   tangents, the final status), it does not rewrite the timeline.
 - **The folder is the archive, never destroy**. `finish` keeps intent +
   build-log + report in `builds/<slug>/` and commits them; nothing is copied out and

package/skills/harvest/SKILL.md

@@ -1,37 +1,37 @@
 ---
 name: harvest
-description: Triage the park list at a step boundary — propose one class (blocker/tangent/pivot) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent.
+description: "Triage the park list at a step boundary: propose one class (blocker/tangent/pivot) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent."
 disable-model-invocation: true
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 
-# PlumbBob — harvest the park list
+# PlumbBob: harvest the park list
 
 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."`
 
 `/plumbbob:harvest` is the complement of `/plumbbob:park`: you parked ideas as seeds during a
-build; now, at a boundary, you harvest them — decide what each one is.
+build; now, at a boundary, you harvest them: decide what each one is.
 
-## When to run it — boundary only
+## When to run it: boundary only
 
 Harvest at a **step boundary**: after a step is checkpointed and you are back at the
 DESIGN boundary, not mid-step. Read the dashboard injected above:
 
-- `NO ACTIVE SESSION` — **refuse**; tell the human to `plumbbob start "<title>"` first.
+- `NO ACTIVE SESSION`: **refuse**; tell the human to `plumbbob start "<title>"` first.
 - A step in flight (the dashboard reads `[BUILD]`, and `next →` points at finishing the
-  step) — **refuse** and suggest finishing it with `/plumbbob:verify` before harvesting.
+  step): **refuse** and suggest finishing it with `/plumbbob:verify` before harvesting.
   Chasing parked items mid-step is the disease parking prevents.
-- At the boundary (the dashboard reads `[DESIGN]`) — go ahead.
+- At the boundary (the dashboard reads `[DESIGN]`): go ahead.
 
 ## What this skill does
 
 Walk the **Park list** in `build-log.md` item by item and, for each, **propose exactly
 one class**:
 
-- **blocker** — the plan was wrong or incomplete; can't proceed. Folds into `intent.md`
+- **blocker**: the plan was wrong or incomplete; can't proceed. Folds into `intent.md`
   and is handled now.
-- **tangent** — a different path, not clearly better. **The default** — defer or kill.
-- **pivot signal** — real evidence the whole approach is wrong. Stop and replan.
+- **tangent**: a different path, not clearly better. **The default**: defer or kill.
+- **pivot signal**: real evidence the whole approach is wrong. Stop and replan.
 
 ## The one hard contract
 
@@ -42,6 +42,8 @@ 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, anchored the same way
+  (`- <a id="d5"></a>**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/park/SKILL.md

@@ -1,35 +1,35 @@
 ---
 name: park
-description: Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park` — never by editing a file. The capture half of the park/harvest loop.
+description: "Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park`, never by editing a file. The capture half of the park/harvest loop."
 argument-hint: "[idea]"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*)
 ---
 
-# PlumbBob — park an idea (capture, don't chase)
+# PlumbBob: park an idea (capture, don't chase)
 
 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."`
 
 `/plumbbob:park` is the **capture** half of the loop; `/plumbbob:harvest` is where parked items
-get triaged later. Capturing the instant an idea arrives — instead of acting on
-it — is the whole point: it protects the step in flight.
+get triaged later. Capturing the instant an idea arrives (instead of acting on
+it) is the whole point: it protects the step in flight.
 
 ## Wrong-state refusal
 
 Parking needs an **active session** to capture into. Read the dashboard injected above: if
 it is `NO ACTIVE SESSION`, **refuse** and tell the human to run `plumbbob start
-"<title>"` first. Any time the session is live — at the boundary, mid-step, or in a spike —
+"<title>"` first. Any time the session is live (at the boundary, mid-step, or in a spike)
 is fine; capture is always available, which is the whole point of parking.
 
 ## What this skill does
 
 Take the idea, problem, or "ooh what if" the human just had and **compose it into one
-tidy, tagged line** — short, legible, self-contained, and carrying a **one-clause why**
+tidy, tagged line**: short, legible, self-contained, and carrying a **one-clause why**
 (what it is *and* why it's worth revisiting), so it still reads cleanly weeks later when
 harvest triages it cold. Then:
 
-1. **Show the composed line to the human** and wait for **in-turn approval** — they
+1. **Show the composed line to the human** and wait for **in-turn approval**: they
    confirm it as-is or edit the wording.
 2. **Only after** that approval, capture it by running `plumbbob park "<the
    approved line>"` via Bash.
@@ -38,8 +38,8 @@ harvest triages it cold. Then:
 
 The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and
 no Write tool** on purpose: you may not append to `build-log.md` yourself. Compose, get
-approval, then shell `plumbbob park` — that is the only write path. If approval
-never comes, capture nothing. (When the human's **own message** states the idea — a
-tangent they raise mid-build — that message **is** the approval: capture it directly
+approval, then shell `plumbbob park`; that is the only write path. If approval
+never comes, capture nothing. (When the human's **own message** states the idea, a
+tangent they raise mid-build, that message **is** the approval: capture it directly
 with `plumbbob park`, don't ask again. Deferring in words without the CLI line captures
 nothing.)