plumbbob 0.9.5 → 0.10.1

package/skills/finish/SKILL.md

@@ -1,44 +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). Copy each one's `D# (slug)` from `intent.md` — never a bare `D#` — so
+   - **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.
+   - **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'
@@ -48,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,7 +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` — slugged at birth
-  like any Decision (`D5 (retry-cap): <the call> — *because* <why>`), never a bare `D5`.
+- 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.)

package/skills/plan/SKILL.md

@@ -1,27 +1,27 @@
 ---
 name: plan
-description: "Frame a fresh goal and author the whole plan — Frame, Decisions, Constraints, and all Steps — before any code. Three input modes: no arg interviews you; a file path (or @-mention) absorbs a spec; any other text expands your inline intent."
+description: "Frame a fresh goal and author the whole plan (Frame, Decisions, Constraints, and all Steps) before any code. Three input modes: no arg interviews you; a file path (or @-mention) absorbs a spec; any other text expands your inline intent."
 argument-hint: "[spec-path | intent]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent list:*)
 ---
 
-# PlumbBob — plan a goal (the whole-goal move)
+# PlumbBob: plan a goal (the whole-goal 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."`
 
-`/plumbbob:plan` is the **whole-goal** move — it opens a session and gets the deciding out
+`/plumbbob:plan` is the **whole-goal** move; it opens a session and gets the deciding out
 of your head and onto `intent.md` *before* any code. By default it authors the
 **complete plan, including all the Steps**, so the happy path afterward is just
 `/plumbbob:build` until done. (Revising a single increment later is the separate `/plumbbob:step`
 move; do not confuse the two.)
 
-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. Planning is where frontier-class judgment pays for itself, so if the session is
-running a small model, suggest `/model opus` (or better) before framing — the
+running a small model, suggest `/model opus` (or better) before framing: the
 human's call, never a gate.
 
-## Three input modes (disambiguated for you — no quotes needed)
+## Three input modes (disambiguated for you; no quotes needed)
 
 Look at the argument the human gave and pick the mode yourself:
 
@@ -32,10 +32,10 @@ Look at the argument the human gave and pick the mode yourself:
    the token with the `Read` tool; if Claude Code has already injected the referenced
    file's contents into your context, treat that as the spec rather than re-fetching.
    Read the spec and distill it into `intent.md`, **retaining enough detail that
-   `intent.md` stands on its own** — don't just link to the source. Add a one-line
+   `intent.md` stands on its own**; don't just link to the source. Add a one-line
    provenance (`*Source: <path>*`) and, for anything sizable, a `## Source` appendix
-   preserving the original text. Any prose wrapped around the reference (e.g. "absorb
-   @spec.md") is extra intent — fold it in. (If the token isn't a real file, fall to
+   preserving the original text. Any prose wrapped around the reference (for example "absorb
+   @spec.md") is extra intent; fold it in. (If the token isn't a real file, fall to
    mode 3.)
 3. **Any other text → expand the inline intent.** Treat the text as the human's
    rough plan, expand it into the full `intent.md`, and ask only about what is
@@ -50,53 +50,56 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    to create `.plumbbob/` (baseline recorded, session opened). If a session already
    exists, say so and edit the existing `intent.md` rather than starting over.
    - **If `start` warns that the gate sees no code checks**, surface that to the
-     human now — while they're still deciding, not at the first refused
-     checkpoint — and offer to set the `check` key in `.plumbbob/settings.json`
-     (e.g. `"check": "npm test"`) before any step is built.
+     human now (while they're still deciding, not at the first refused
+     checkpoint) and offer to set the `check` key in `.plumbbob/settings.json`
+     (for example `"check": "npm test"`) before any step is built.
 2. **Frame** (`.plumbbob/intent.md`), with the human: the **Problem** in plain words,
    the **smallest thing** that solves it, what **done looks like**, and what you are
-   **explicitly NOT doing**. This is the human's convergence — propose wording, but
+   **explicitly NOT doing**. This is the human's convergence: propose wording, but
    the human decides every line.
 3. **Decisions & Constraints.** Record the settled calls (one line each, with the
-   *because*) and the hard rules the build must honor. **Slug each at birth** — mint a
-   two- or three-word slug where the item is born (`D1 (default-waves): …`,
-   `C1 (no-new-deps): …`) and copy that slug at every reference site, so a later
-   mention reads `D4 (default-waves)` and stays legible: **never a bare `D4`/`C6`/`Q2`
-   reference — always carry its gloss**, so a cold reader never has to hunt the number
-   down. An unresolved hole goes to **Open questions**, never guessed into a Decision —
-   and it goes in the expanded form the template shows: a slugged opener (the hole as a
-   question), a `*plain:*` sub-line (what's at stake, in plain words, enough to judge it
-   cold), then a `*lean:*` sub-line (your proposed resolution — one answer to react to,
-   not a menu), so the human settles it in one pass without a round-trip. (A tiny,
-   obvious question may stay one bare line; the sub-lines earn their keep only when a
-   human decision genuinely waits on it.)
-4. **Author the Steps.** Write the **full build plan** under `## Steps` — each step a
-   small, verifiable increment in the exact format the parser reads:
+   *because*) and the hard rules the build must honor. **Anchor and slug each at birth**:
+   mint a two- or three-word slug where the item is born and give it an anchor for
+   references to land on (`- <a id="d1"></a>**D1 (default-waves)**: …`,
+   `- <a id="c1"></a>**C1 (no-new-deps)**: …`), then cite it everywhere else in the file
+   as `[D4 (default-waves)](#d4)`, carrying that slug verbatim: **never a bare
+   `D4`/`C6`/`Q2` reference, and never a linkless one**: one link to the definition,
+   one glance at the gloss, so a cold reader never has to hunt the number down.
+   An unresolved hole goes to **Open questions**, never guessed into a Decision,
+   and it goes in the expanded form the template shows: an anchored, slugged opener
+   (the hole as a question, `- <a id="q1"></a>**Q1 (default-waves)**: …`, so
+   `[Q1 (default-waves)](#q1)` has somewhere to land), a `*plain:*` sub-line (what's at
+   stake, in plain words, enough to judge it cold), then a `*lean:*` sub-line (your
+   proposed resolution: one answer to react to, not a menu), so the human settles it in
+   one pass without a round-trip. (A tiny, obvious question may stay one bare line; the
+   sub-lines earn their keep only when a human decision genuinely waits on it.)
+4. **Author the Steps.** Write the **full build plan** under `## Steps` (each step a
+   small, verifiable increment) in the exact format the parser reads:
 
    ```markdown
-   1. [ ] feat(scope): <title> — **done when:** <criterion, ideally a test or check result>
+   1. [ ] feat(scope): <title>, **done when:** <criterion, ideally a test or check result>
       - seam: `<file>`, `<file>`
-      - model: <optional — smallest that can carry it, with the one-phrase why>
+      - model: <optional; smallest that can carry it, with the one-phrase why>
    ```
 
    Every step needs a **done-when** `/plumbbob:verify` can check and a **seam** (the exact
-   paths it touches). Later steps may be fuzzier than the first — that's fine; they get
+   paths it touches). Later steps may be fuzzier than the first (that's fine); they get
    sharpened just-in-time when you reach them with `/plumbbob:step`. Keep each small enough to
    verify in one review pass.
 
-   **The title *is* the commit subject — author it as one**
-   ([D68 (conventional-subjects)](../../docs/decisions.md#d68)): write each
+   **The title *is* the commit subject; author it as one**
+   ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)): write each
    `<title>` as a plain, single-line Conventional-Commit subject,
    `type(scope): description`, and it lands in `git log` verbatim (its breaking `!`
-   honored) — this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
-   Keep load-bearing detail — file paths, module names — in `seam` and `done-when`; it is
+   honored); this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
+   Keep load-bearing detail (file paths, module names) in `seam` and `done-when`; it is
    **never jammed into the title**, which has to read as plain English and as a clean
-   subject at once. Aim for **≤72 characters** (GitHub's subject convention) — soft
+   subject at once. Aim for **≤72 characters** (GitHub's subject convention): soft
    guidance you eyeball at plan time, no lint, no gate.
 
    **Set the build's default scope, then let steps override it**: fill the
-   `**Scope:**` header once with a short feature-level name — the catch-all every step
-   inherits — and give a step its own `(scope)` when it touches a distinct code area
+   `**Scope:**` header once with a short feature-level name (the catch-all every step
+   inherits) and give a step its own `(scope)` when it touches a distinct code area
    (`plan`, `commitmsg`, `docs`). A step's `(scope)` names the *code area*; the header
    names the *feature*, so scopes stay consistent and greppable across builds. Scope
    resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
@@ -105,19 +108,19 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
 
    **Recommend a model per step where the signal is clear** *(optional)*: the
    `- model:` sub-line names the **smallest model that can carry the step**, with the
-   one-phrase why — the human buys capability only where the step needs it. E.g.
-   `model: sonnet — mechanical, fully specified by the done-when` for rote edits;
-   `model: opus — strong-assertion test authoring` where the tests do the thinking;
-   `model: fable — subtle cross-cutting design` for judgment-heavy or creative work.
-   It is advisory metadata for the human — `/plumbbob:status` surfaces it before each build —
+   one-phrase why; the human buys capability only where the step needs it. E.g.
+   `model: sonnet (mechanical, fully specified by the done-when)` for rote edits;
+   `model: opus (strong-assertion test authoring)` where the tests do the thinking;
+   `model: fable (subtle cross-cutting design)` for judgment-heavy or creative work.
+   It is advisory metadata for the human (`/plumbbob:status` surfaces it before each build),
    never a gate, and nothing switches models automatically. Write it plain (no
    backticks) and omit it when any model would do.
 5. **Offer harness bindings** *(optional)*. If the build will lean on
    user-authored agents, author `harness.json` in the build folder (beside `intent.md`)
-   and review it at the **same plan pause**, alongside the steps — bindings are
+   and review it at the **same plan pause**, alongside the steps; bindings are
    plan-adjacent configuration, so they converge with the plan. It binds agents to a
-   step's three lifecycle slots — `before` (context in), `build` (the diff), `after`
-   (advisory review) — with an optional prose `note`; a `defaults` block binds every
+   step's three lifecycle slots, `before` (context in), `build` (the diff), and `after`
+   (advisory review), with an optional prose `note`; a `defaults` block binds every
    step. Run `plumbbob agent list` to see what's resolvable, per step:
 
    ```json
@@ -129,31 +132,37 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    ```
 
    Keep it **bindings + prose only, never a conditional**: the file says *which*
-   agent, not *when* — the host model reads each manifest's `when` prose and a step's
+   agent, not *when*; the host model reads each manifest's `when` prose and a step's
    `note` and decides when to run one mid-build. Skip the file entirely when no step
-   uses an agent — the loop runs identically without it. The plan commit picks it
+   uses an agent; the loop runs identically without it. The plan commit picks it
    up automatically (it lives in the build folder).
 6. **Commit the plan.** Once the human approves the frame and steps, run
-   `plumbbob checkpoint --plan` to commit the scaffold on its own — subject
+   `plumbbob checkpoint --plan` to commit the scaffold on its own: subject
    `chore(<scope>): plan` (with a `plumbbob plan` body marker), only `.plumbbob/builds/<slug>/`,
    a `plan <sha>` line in
    `checkpoints`. This keeps the first step's diff clean, so history reads
    baseline → plan → steps. Pass a proportional `--body` (the single-quoted stdin
    heredoc) when the rationale is worth carrying; skip it for a small plan. Do this
-   only on the human's approval — the plan is their convergence.
+   only on the human's approval; the plan is their convergence.
    - **The plan commit is latched too.** Once the turn ledger exists, `checkpoint
      --plan` refuses to land in the same turn `start` stamped it: present the plan,
      **end the turn**, and the human's approving message is the tick that lets it
-     commit on the next run — the refusal *is* the plan pause. Never route around it with a
+     commit on the next run; the refusal *is* the plan pause. Never route around it with a
      raw `git commit`. (One documented seam: the very first plan of a brand-new
      session runs `start` *before* the turn hook has ever ticked, so that single
-     commit predates the ledger and stays guidance-governed — it lands without a
+     commit predates the ledger and stays guidance-governed; it lands without a
      refusal.)
    - **Say what the commit publishes.** The close-out line names the tracked folder:
      `.plumbbob/builds/<slug>/` now rides this branch into the PR, so teammates will
      see the plan and build record in review. In the same breath, offer the way out:
      a repo that won't track a tool folder can restart with `plumbbob start --local`
      (a fully untracked sidecar) before any steps are built.
+     - **Record-only variant.** When the repo's own `.gitignore` excludes `.plumbbob/`,
+       the folder can't ride the branch; `start` flags this up front, and the plan
+       commit lands *record-only*: an empty commit whose message carries the plan
+       (the `--body` earns its keep here), the files staying untracked. Say that
+       instead: the rationale is published in `git log`, not the folder, so pass a
+       fuller `--body` than you otherwise would, since the message is the whole record.
 7. **Offer to stress-test it.** Suggest `/plumbbob:refine` to attack the frame for holes (or
    to repair the plan as it drifts). Optional, the human's call.
 
@@ -161,17 +170,17 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
 
 Make it easy and non-intrusive:
 
-- **Triage size first.** A tiny change earns a 3-line Frame and one Step, fast — never
+- **Triage size first.** A tiny change earns a 3-line Frame and one Step, fast: never
   ceremony on a one-liner. Scale the questions to the work.
 - **Propose, don't interrogate.** Offer concrete suggestions the human can **accept as-is
-  without typing** ("done-when: the 6th request in 60s returns 429 — good?"), while
+  without typing** ("done-when: the 6th request in 60s returns 429, good?"), while
   taking arbitrary detail when they want to give it, including pointers to other files.
 - **Let them double back.** They will revise as the picture sharpens; that's expected.
   They can also edit `intent.md` by hand at any time, or call `/plumbbob:refine` to repair it.
 
 ## The hard contracts
 
-- **Deciding before code.** `/plumbbob:plan` writes `intent.md` only — never source.
+- **Deciding before code.** `/plumbbob:plan` writes `intent.md` only, never source.
 - **The human converges.** You surface options and draft wording; the human picks.
   An unresolved hole is an Open question, not a guessed Decision.
 - **Stands on its own.** Whatever the input mode, the finished `intent.md` carries

package/skills/recover/SKILL.md

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

package/skills/refine/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: refine
-description: Keep intent.md true — attack the plan for holes (append as Open questions) and refine or repair the Frame, Decisions, Constraints, and Steps to match reality. Usable at any point; you propose, the human approves.
+description: "Keep intent.md true: attack the plan for holes (append as Open questions) and refine or repair the Frame, Decisions, Constraints, and Steps to match reality. Usable at any point; you propose, the human approves."
 argument-hint: "[focus]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 
-# PlumbBob — refine the plan
+# PlumbBob: refine the plan
 
 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:refine` keeps `intent.md` honest. Use it at **any point** — right after `/plumbbob:plan`
+`/plumbbob:refine` keeps `intent.md` honest. Use it at **any point**: right after `/plumbbob:plan`
 to stress-test a fresh frame, or mid-build to repair a plan that drifted from what the
 code is actually doing. It is the document-level complement to `/plumbbob:step` (which only
 sharpens the *next* step): `/plumbbob:refine` works the *whole* plan.
@@ -20,34 +20,36 @@ sharpens the *next* step): `/plumbbob:refine` works the *whole* plan.
 This skill refines an existing plan, so it needs one. Read the state injected above: if
 it is `NO ACTIVE SESSION`, **refuse** in one line and tell the human to run
 `plumbbob start "<title>"` (or `/plumbbob:plan`) first, and edit nothing. Every active state
-is fine — refining is always available.
+is fine; refining is always available.
 
 ## Two modes
 
 - **Attack (diverge in the problem space).** Hand the **Frame**, **Decisions**, and
-  **Architecture sketch** a cold, adversarial read and surface holes — ambiguities,
+  **Architecture sketch** a cold, adversarial read and surface holes: ambiguities,
   unhandled edge cases, hidden assumptions, collisions with the existing code. Append
-  each under `## Open questions` in the expanded form the template shows — an opener
-  line (the hole as a question, slugged at birth: `- Q2 (some-slug): …`), a `*plain:*`
-  sub-line (what's at stake in plain words, enough to judge it cold), and a `*lean:*`
-  sub-line (your proposed resolution — one answer to react to, not a menu). Never
-  append a hole as a Decision: resolving it is the human's convergence, not yours —
+  each under `## Open questions` in the expanded form the template shows: an opener
+  line (the hole as a question, anchored and slugged at birth like any Decision,
+  `- <a id="q2"></a>**Q2 (some-slug)**: …`, so a `[Q2 (some-slug)](#q2)` reference
+  elsewhere in the file lands on it), a `*plain:*` sub-line (what's at stake in plain
+  words, enough to judge it cold), and a `*lean:*` sub-line (your proposed resolution:
+  one answer to react to, not a menu). Never
+  append a hole as a Decision: resolving it is the human's convergence, not yours;
   the lean proposes; this mode surfaces, it does not decide. (A tiny, obvious question
   may stay one bare line; the sub-lines earn their keep only when a human decision
   genuinely waits on it.)
 
   Then walk the human through it in the chat: list every hole you appended, each as
-  its explanation first and its lean second, and invite per-question answers — the
+  its explanation first and its lean second, and invite per-question answers; the
   human can settle any of them right there in one message, no doc-flipping, no extra
   round-trip per hole.
-- **Repair (re-sync to reality).** When the plan has drifted — a Decision was overtaken
+- **Repair (re-sync to reality).** When the plan has drifted (a Decision was overtaken
   by what you built, a Constraint changed, a Step no longer matches the seam, or a
-  **step's title no longer describes what the diff actually does** — propose the edits
+  **step's title no longer describes what the diff actually does**), propose the edits
   that bring `intent.md` back in line with the truth. A step title *is* its checkpoint
-  commit subject — D68 (conventional-subjects) — so bringing a drifted one back in line
+  commit subject ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)), so bringing a drifted one back in line
   means keeping it a plain, single-line `type(scope): description` subject, with
   load-bearing detail (file paths, module names) in `seam` and `done-when`,
-  **never jammed into the title** — the checkpoint body pass then reconciles and lands
+  **never jammed into the title**; the checkpoint body pass then reconciles and lands
   that subject at the verify pause.
   Show the before/after for each, and **write only what the human approves**.
 
@@ -57,5 +59,5 @@ is fine — refining is always available.
   approves every change to `intent.md`. Never guess a hole into a Decision.
 - **Open questions for holes, edits for drift.** New uncertainty goes to
   `## Open questions`; settled drift gets repaired in place once the human OKs it.
-- **Refine the plan, not the code.** `/plumbbob:refine` touches `intent.md` only — turning a
+- **Refine the plan, not the code.** `/plumbbob:refine` touches `intent.md` only; turning a
   decision into a diff is `/plumbbob:build` or your own hands, never this skill.

package/skills/revert/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: revert
-description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to the boundary.
+description: "Human-triggered driver for `plumbbob revert`: git reset --hard to a checkpoint SHA (discarding the half-done step) and return to the boundary."
 argument-hint: "[--to <step>]"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob revert:*)
 ---
 
-# PlumbBob — revert to a checkpoint (driver)
+# PlumbBob: revert to a checkpoint (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 revert` 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 revert` 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 an optional target step from the way you were invoked (e.g. `/plumbbob:revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
-2. Run `plumbbob revert` (or `plumbbob revert --to <n>`) via Bash. This is a `git reset --hard` — it discards the current in-progress step. Run it exactly as the human asked; do not add or drop the `--to` on your own.
-3. Report the verb's output verbatim — which checkpoint it reset to, or any refusal.
+1. Read an optional target step from the way you were invoked (for example `/plumbbob:revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
+2. Run `plumbbob revert` (or `plumbbob revert --to <n>`) via Bash. This is a `git reset --hard`; it discards the current in-progress step *and its work*. If the human wants to drop the step but keep the working-tree diff, that is `/plumbbob:abandon`, not revert. Run it exactly as the human asked; do not add or drop the `--to` on your own.
+3. Report the verb's output verbatim: which checkpoint it reset to, or any refusal.