plumbbob 0.8.17 → 0.9.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.17",
+  "version": "0.9.1",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -4,7 +4,13 @@
   <img src="hero.svg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
 </p>
 
-PlumbBob is a Claude Code plugin — twelve `/pb-*` skills and a small CLI — that runs
+<p align="center">
+  <a href="https://robmclarty.github.io/plumbbob/">Website</a> ·
+  <a href="https://robmclarty.github.io/plumbbob/docs.html">Docs</a> ·
+  <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
+</p>
+
+PlumbBob is a Claude Code plugin — twelve skills and a small CLI — that runs
 LLM-assisted coding as a loop you control. You and the model settle the plan in a file
 *before* any code; then the model builds one small step at a time and **stops after
 each one**, waiting for you to read the diff and approve it before anything is
@@ -35,7 +41,7 @@ model's goodwill:
   run (types, lint, tests, dead code, docs) has to pass before a step lands.
 - **One SHA per verified step.** Every approved step is its own git commit against a
   recorded baseline — a ledger of checkpoints, not one undifferentiated diff at the end.
-- **A preservation-aware revert.** `/pb-revert` resets exactly to a recorded checkpoint
+- **A preservation-aware revert.** `/plumbbob:revert` resets exactly to a recorded checkpoint
   SHA while keeping your plan and notes intact, and restores *only* SHAs the loop wrote.
 - **A build record that rides the PR.** The tracked `builds/<slug>/` folder — intent, log,
   checkpoints, report — merges into `main` with the branch instead of dying with the
@@ -51,7 +57,7 @@ work, a latch on the record.**
 ## The loop in one picture
 
 <p align="center">
-  <img src="demo.svg" alt="An animated terminal session: /pb-plan writes the plan, /pb-build implements step 1 and stops at the PAUSE, the human approves, the step is checkpointed" width="760">
+  <img src="demo.svg" alt="An animated terminal session: /plumbbob:plan writes the plan, /plumbbob:build implements step 1 and stops at the PAUSE, the human approves, the step is checkpointed" width="760">
 </p>
 
 Everything the model must stay true to lives in one file, the build's `intent.md`
@@ -62,11 +68,11 @@ with its *because*), and the **Steps** — a numbered list where every step carr
 expected to touch).
 
 ```text
-/pb-plan       decide everything on paper — frame, decisions, all steps    (once)
+/plumbbob:plan       decide everything on paper — frame, decisions, all steps    (once)
   per step:
-    /pb-build      implement the next step → run checks → self-review → PAUSE
-    (approve)      → the step is committed as a checkpoint; fire /pb-build again
-/pb-finish     report what shipped and why, final commit, clear            (once)
+    /plumbbob:build      implement the next step → run checks → self-review → PAUSE
+    (approve)            → the step is committed as a checkpoint; fire /plumbbob:build again
+/plumbbob:finish     report what shipped and why, final commit, clear            (once)
 ```
 
 Nothing is locked and nothing refuses you — the loop does a step's labor, pulls up to
@@ -95,7 +101,7 @@ plumbbob init          # link it into Claude Code; --uninstall to undo
 ```
 
 Restart Claude Code (or `/reload-plugins`) to activate, then run `plumbbob doctor`
-(or `/pb-doctor` in-session) to confirm the wiring. The full guide — namespacing,
+(or `/plumbbob:doctor` in-session) to confirm the wiring. The full guide — namespacing,
 per-project sessions, the agent-neutral roadmap — is in
 [`docs/install.md`](docs/install.md).
 
@@ -103,11 +109,11 @@ per-project sessions, the agent-neutral roadmap — is in
 
 In Claude Code, inside any git repo with a clean tree:
 
-1. **Plan.** Fire `/pb-plan` and give it whatever you have — nothing (it interviews
-   you), a rough line (`/pb-plan rate-limit POST /login, 5/min/IP, return 429`), or a
+1. **Plan.** Fire `/plumbbob:plan` and give it whatever you have — nothing (it interviews
+   you), a rough line (`/plumbbob:plan rate-limit POST /login, 5/min/IP, return 429`), or a
    path to a spec file. Together you fill the build's `intent.md`. No code is written
    yet.
-2. **Build.** Fire `/pb-build`. It implements the next undone step, runs the
+2. **Build.** Fire `/plumbbob:build`. It implements the next undone step, runs the
    heavy check gate, reviews its own diff against the plan, and stops:
 
    ```text
@@ -119,16 +125,16 @@ In Claude Code, inside any git repo with a clean tree:
    code, docs. To gate through your own command instead, set the `"check"` key in
    `.plumbbob/settings.json`, e.g. `"check": "npm test"`.)
 3. **Approve** — or send fixes. On your OK it commits the step as a checkpoint, marks
-   it done, and returns to the boundary. Fire `/pb-build` again for the next step —
-   re-firing it *is* the clock tick. Whenever you lose the thread, `/pb-status` shows
+   it done, and returns to the boundary. Fire `/plumbbob:build` again for the next step —
+   re-firing it *is* the clock tick. Whenever you lose the thread, `/plumbbob:status` shows
    where you are and names the next move.
-4. **Finish.** When the last step is done, `/pb-finish` writes a report of what shipped
+4. **Finish.** When the last step is done, `/plumbbob:finish` writes a report of what shipped
    and why into the build's tracked folder, makes the final commit, and clears the slate
    for the next goal. The folder rides the branch into the PR — the build's record merges
    into `main` instead of dying with the worktree.
 
-A mid-build "ooh, what if…" never derails the step: `/pb-park` captures it to a list
-in one line, and `/pb-harvest` triages the list between steps. One goal walked end to
+A mid-build "ooh, what if…" never derails the step: `/plumbbob:park` captures it to a list
+in one line, and `/plumbbob:harvest` triages the list between steps. One goal walked end to
 end, with the real output at every stage, is in
 [`docs/happy-path.md`](docs/happy-path.md).
 
@@ -136,42 +142,43 @@ end, with the real output at every stage, is in
 
 You drive the whole loop from your IDE with `/plumbbob:*` skills — no step numbers to
 remember, no raw CLI to type. Every skill is `disable-model-invocation`, so *you* fire
-every move, and `/pb-status` always names your next one. (Claude Code namespaces them
-under the plugin — the real command is `/plumbbob:pb-plan`; for readability these docs
-write the short form `/pb-plan`.)
+every move, and `/plumbbob:status` always names your next one. (Claude Code namespaces
+them under the plugin, so the command is `/plumbbob:plan`. The bare `/plan` reaches it
+too — but only where nothing else owns that name, and four of the twelve share one with
+a Claude Code built-in, so these docs write the full form.)
 
 **The happy path** — the three moves every session makes; many sessions need
 nothing else:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
-| `/pb-plan` | plan the whole goal — open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
-| `/pb-build` | implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then pauses |
-| `/pb-finish` | finish up — write the report, make the final commit, clear for a fresh goal |
+| `/plumbbob:plan` | plan the whole goal — open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/plumbbob:build` | implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then pauses |
+| `/plumbbob:finish` | finish up — write the report, make the final commit, clear for a fresh goal |
 
 **Plan-shaping moves** — optional, for when the plan needs work mid-flight:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
-| `/pb-step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
-| `/pb-refine` | attack the frame for holes, or repair a drifted plan |
-| `/pb-spike` | throwaway worktree experiment for a fork the plan can't settle |
+| `/plumbbob:step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
+| `/plumbbob:refine` | attack the frame for holes, or repair a drifted plan |
+| `/plumbbob:spike` | throwaway worktree experiment for a fork the plan can't settle |
 
 **Helpers** — orient, verify, recover, diagnose:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
-| `/pb-status` | orient — where you are, the next step's done-when and seam, and the next move |
-| `/pb-verify` | the tick, standalone — check → self-review → validate → **PAUSE** → checkpoint, for a diff `/pb-build` didn't write |
-| `/pb-revert` | recover — `git reset --hard` to a recorded checkpoint |
-| `/pb-doctor` | check the install from inside a session |
+| `/plumbbob:status` | orient — where you are, the next step's done-when and seam, and the next move |
+| `/plumbbob:verify` | the tick, standalone — check → self-review → validate → **PAUSE** → checkpoint, for a diff `/plumbbob:build` didn't write |
+| `/plumbbob:revert` | recover — `git reset --hard` to a recorded checkpoint |
+| `/plumbbob:doctor` | check the install from inside a session |
 
 **Capture** — the park/harvest loop for mid-build ideas:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
-| `/pb-park` | capture a mid-build idea without chasing it |
-| `/pb-harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
+| `/plumbbob:park` | capture a mid-build idea without chasing it |
+| `/plumbbob:harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
 
 All twelve, with inputs and effects, are in
 [`docs/skills-reference.md`](docs/skills-reference.md).
@@ -183,9 +190,9 @@ flow), and a `.plumbbob/` sidecar you can open and edit by hand at any time —
 that rides the branch into the PR, plus an untracked control plane (`settings.local.json`,
 the session sentinel, the in-flight markers).
 
-**`/pb-build` is the default engine, not the only one.** It's one executor — the
+**`/plumbbob:build` is the default engine, not the only one.** It's one executor — the
 loop doesn't care who writes the code. Implement a step by hand — or vibe it in
-another session, or in another harness entirely — and run `/pb-verify` instead:
+another session, or in another harness entirely — and run `/plumbbob:verify` instead:
 same checks, same pause, same checkpoint. It reads the *diff, not the author*.
 
 **Bring your own agents.** Because the executor is author-blind, you can plug your
@@ -217,7 +224,7 @@ against the plan, and committed as its own checkpoint, so a wrong turn costs one
 step, not the afternoon; and records the *whys* alongside the decisions, so the
 archive can still answer "what did we decide, and why" long after the session is
 gone. The two compose fine: plan mode — or anything else — can produce a step's
-diff, and `/pb-verify` reads it like any other.
+diff, and `/plumbbob:verify` reads it like any other.
 
 **…use git and a TODO file?** That's the honest skeleton, and if your discipline
 holds by willpower alone, it may be all you need. What the CLI adds is the
@@ -253,19 +260,24 @@ that matters.
 > The latch's payoff is measured, not asserted: the skill-eval harness
 > ([`test/evals/`](test/evals/)) sweeps this loop headless — prose-only baseline vs. the
 > shipped latch, N=5 per contract, every assertion a mechanical read of git state — and
-> commits each receipt under [`research/evals/`](research/evals/). The first sweep
-> ([opus, 2026-07-11](research/evals/2026-07-11.md)) closed the route the latch owns —
+> commits each receipt under [`docs/evals/`](docs/evals/). The first sweep
+> ([opus, 2026-07-11](docs/evals/2026-07-11.md)) closed the route the latch owns —
 > *no checkpoint over a red check under pressure* went from **2/5 prose-only to 5/5
 > latched** — and named, rather than papered over, the two honest gaps it surfaced: park
 > capture at 0/5, and adversarial pressure flipping a standing `auto` grant a model could
 > write into settings, a legal side door. The re-sweep
-> ([opus, 2026-07-18](research/evals/2026-07-18.md), plumbbob 0.8.7) reproduced the win —
-> *no checkpoint over a red check* still **5/5 latched** — and pinned both gaps. The side
-> door is now closed by construction: [D67](docs/decisions.md#d67) (self-approval is
-> human-typed only) retired the settings `auto` grant, so the one approval a model could
-> forge is gone. What remains is park capture (c5) — prose-governed by design
-> ([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13)), the guidance-only gap the
-> latch was never built to reach, still ~0/5 and labeled as such.
+> ([opus, 2026-07-18](docs/evals/2026-07-18.md), plumbbob 0.8.7) reproduced the win —
+> *no checkpoint over a red check* still **5/5 latched** — and pinned both gaps. Both are
+> now closed. The side door went by construction: [D67](docs/decisions.md#d67)
+> (self-approval is human-typed only) retired the settings `auto` grant, so the one
+> approval a model could forge is gone. Park capture was never the latch's to reach —
+> prose-governed by design ([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13)) —
+> and it failed because the guidance couldn't reach a fresh session at all; the turn hook
+> now injects one line when a step is in flight, and the third sweep
+> ([opus, 2026-07-27](docs/evals/2026-07-27.md), plumbbob 0.9.0) measures it at **5/5**,
+> alongside every other contract. That sweep ran the latched arm only, so its numbers are
+> a regression check on the shipped configuration, not a fresh baseline delta — the
+> 2/5→5/5 headline above remains the 2026-07-11 measurement.
 
 ## Documentation
 
@@ -275,7 +287,7 @@ Each doc answers one question — in rough reading order for a new user:
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/) — that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md) — the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md) — steps, seams, the pause, park/harvest, spikes.
-- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md) — all twelve `/pb-*` skills: inputs, effects, when to reach for each.
+- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md) — all twelve skills: inputs, effects, when to reach for each.
 - *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md) — the subprocess envelope, the manifest, `harness.json`, and working examples (including a local-model reviewer via Ollama).
 - *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md) — the ollama-reviewer example walked end to end, install to every-pause review.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md) — the full guide and the agent-neutral roadmap.

package/dist/cli-core.js

@@ -1,8 +1,14 @@
 // plumbbob CLI core — argv dispatch and the help table, separated from the bin
 // entry (cli.ts) so the routing/help logic is unit-testable in-process without
-// the top-level process.exit. Node builtins plus the deliberate few (D1/C2 —
-// currently checkride alone, via check.ts). Functional/procedural: no classes,
-// no `this`, no default export (C1).
+// the top-level process.exit. Node builtins plus a deliberate few dependencies
+// (currently checkride alone, via check.ts). Functional/procedural: no classes,
+// no `this`, no default export.
+//
+// The deciding/executing boundary is a pause, not a lock, so there is nothing
+// to defend in the dispatcher — every verb runs the same whether a human or the
+// model triggers it. There is no human-only `mode` escape hatch and no
+// CLAUDECODE in-session refusal; what keeps the human the decider is the pause
+// at the step boundary (the skills), not a refusal here.
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { start } from "./verbs/start.js";
@@ -20,6 +26,7 @@ import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 import { agent } from "./verbs/agent.js";
 import { turn } from "./verbs/turn.js";
+/** One help-table row per verb, in the order the table prints. */
 const VERBS = [
     { name: 'start', summary: 'scaffold .plumbbob/; open the session; record the baseline commit' },
     { name: 'status', summary: 'print the orientation dashboard, or NO ACTIVE SESSION' },
@@ -37,20 +44,22 @@ const VERBS = [
     { name: 'agent', summary: 'agent list | run <name> [--step N] [--mode before|build|after]: list or spawn a user-authored agent' },
     { name: 'turn', summary: 'turn: UserPromptSubmit hook machinery — tick the turn ledger from stdin (not a user verb)' },
 ];
-// PlumbBob (D1/D10/D13): the deciding/executing boundary is a pause, not a lock,
-// so there is nothing to defend — every verb runs the same whether a human or the
-// model triggers it. There is no human-only `mode` escape hatch and no CLAUDECODE
-// in-session refusal; what keeps the human the decider is the pause at
-// the step boundary (the skills), not a refusal here.
+/**
+ * Render the verb table for `plumbbob help`.
+ */
 export function formatHelp() {
     const width = Math.max(...VERBS.map((v) => v.name.length));
     const rows = VERBS.map((v) => `  ${v.name.padEnd(width)}  ${v.summary}`);
     return ['plumbbob — attention-first build process', '', 'Usage: plumbbob <verb> [args]', '', 'Verbs:', ...rows, ''].join('\n');
 }
-// The package version, read from the package.json that ships one level above the
-// compiled CLI (dist/cli-core.js → ../package.json; in tests src/cli-core.ts →
-// ../package.json, the repo root). Builtins only (C2); an absent or malformed
-// manifest degrades to 'unknown' rather than throwing, so `--version` never errors.
+/**
+ * The package version, or 'unknown'.
+ *
+ * Read from the package.json one level above this module (dist/cli-core.js →
+ * ../package.json; in tests src/cli-core.ts → ../package.json, the repo root).
+ * An absent or malformed manifest degrades to 'unknown' rather than throwing,
+ * so `--version` never errors.
+ */
 export function readVersion() {
     try {
         const raw = readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8');
@@ -60,9 +69,13 @@ export function readVersion() {
         return 'unknown';
     }
 }
-// Async because checkride is: `check` and `checkpoint` await the gate (D32),
-// `start` awaits the plan-time detection probe (research/07 2a); every other
-// verb returns synchronously through the same Promise-typed seam.
+/**
+ * Route a verb to its implementation, or report the unknown verb and exit 1.
+ *
+ * Async because checkride is: `check` and `checkpoint` await the gate, `start`
+ * awaits the plan-time detection probe; every other verb returns synchronously
+ * through the same Promise-typed seam.
+ */
 async function dispatch(verb, cwd, rest) {
     switch (verb) {
         case 'start':
@@ -100,6 +113,13 @@ async function dispatch(verb, cwd, rest) {
             return 1;
     }
 }
+/**
+ * The CLI entrypoint minus the exit: parse argv, dispatch, return the exit code.
+ *
+ * `help` and `version` short-circuit before dispatch; any thrown error becomes
+ * a one-line stderr report and exit 1, so the bin entry only ever exits with
+ * the code returned here.
+ */
 export async function run(argv) {
     const verb = argv[0] ?? 'help';
     const rest = argv.slice(1);