plumbbob 0.3.0 → 0.4.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "plumbbob",
+  "displayName": "Plumbbob",
+  "version": "0.4.0",
+  "description": "Attention-first build process — driver skills + a CLI that keep you the decider; guidance, not enforcement.",
+  "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
+  "homepage": "https://github.com/robmclarty/plumbbob#readme",
+  "repository": "https://github.com/robmclarty/plumbbob",
+  "license": "Apache-2.0",
+  "keywords": ["claude-code", "claude", "hooks", "cli", "agent", "attention-first"]
+}

package/README.md

@@ -1,89 +1,228 @@
 # Plumbbob
 
-A guidance-first build process for working *with* an LLM instead of being dragged behind one. You decide on a surface outside the chat; plumbbob orients you, runs each step's labor, and then **stops and waits for you to advance** — the human is the clock, not a lock.
+<p align="center">
+  <img src="hero.jpg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
+</p>
+
+A guidance-first build process for working *with* an LLM instead of being dragged
+behind one. It's the layer below Ridgeline: where Ridgeline runs autonomously
+without you, Plumbbob keeps you in the driver's seat for the small-to-medium work
+that doesn't justify a full autonomous build — a feature, a bug, a refactor — while
+staying deliberate rather than vibing. You decide on a surface outside the chat;
+Plumbbob orients you, runs each step's labor, and then **stops and waits for you to
+advance** — the human is the clock, not a lock.
 
 > Ridgeline is the line. Plumbbob establishes *true* before you build.
 > The LLM is a hand, not a head.
 
-This repository was built using Plumbbob v2, dogfooded on its own build under its own loop.
+This repository was built using Plumbbob v2, dogfooded on its own build under its
+own loop.
+
+## The one law
+
+**Vibe to execute, never vibe to decide.**
+
+Vibing is fine — *once every decision being carried out was already made on a
+surface outside the chat.* It becomes a slot machine only when the deciding happens
+inside the stream while code is flowing. The whole job of Plumbbob is to keep
+decisions and execution from fusing:
+
+- The **human** owns convergence. You decide, choose, pick the branch.
+- The **LLM** owns divergence in design (finding holes, generating options) and
+  convergence *only* in build (executing a decided step).
+- The **boundary** between deciding and executing is held by a **pause you
+  advance**, not a wall that refuses you.
+
+If you feel tired and lost, those two activities have fused again. The fix is never
+"prompt better." It's "stop, leave the chat, go decide, come back."
+
+## Why it works: get the plan out of your head
+
+The exhaustion is a working-memory problem. You can't *produce* intent and
+*consume* the model's output at once — consuming overwrites producing. So Plumbbob
+externalizes your plan onto durable surfaces that survive the flood:
+
+- `intent.md` — what you decided, before any code. Your canonical intent.
+- `build-log.md` — the live ledger of steps, parked ideas, and decisions.
+
+When the model floods you, you read the page, not your memory. The chat is
+ephemeral; the docs persist. **The chat is a hand; the docs are the head.**
 
 ## The shift: a clock, not a lock
 
-Plumbbob v1 enforced the deciding/executing boundary with a hard file lock (a pre-edit muzzle). v2 replaces the lock with a **clock**: nothing blocks your edits. Instead, the system does a step's work, then pauses at a verify gate for your approval before it checkpoints. You stay the decider by *advancing the clock*, not by fighting a wall.
+Plumbbob v1 enforced the deciding/executing boundary with a hard file lock — a
+pre-edit muzzle that *refused* code edits unless you were in the right state. It
+provided no real security (a determined model routed around it), so its only product
+was forced ritual.
 
-- The **human** owns convergence — you decide, you approve, you advance.
-- The **plan** lives on durable surfaces (`intent.md`, `build-log.md`), not in the chat.
-- The boundary is a **pause**, not a refusal: the system pulls up to a line and waits.
+v2 replaces the lock with a **clock**. Nothing blocks your edits. Instead, the
+system does a step's work, then pauses at a verify gate for your approval before it
+checkpoints. You stay the decider not because a wall refuses you, but because the
+loop pulls up to a line — the verify pause — and idles there until you approve.
+Pull, not block. The pause *is* the product; it is the moment your judgment enters,
+and it cannot be skipped.
 
 ## The eight skills
 
-You drive the whole loop from your IDE with eight `pb-*` skills — no step numbers to remember, no raw CLI to type. `/pb-status` always names your next move.
+You drive the whole loop from your IDE with eight `/plumbbob:*` skills — no step numbers to
+remember, no raw CLI to type. Each is `disable-model-invocation`, so *you* fire
+every move, and `/plumbbob:status` always names your next one.
 
 | Skill | Does |
 |-------|------|
-| `/pb-plan` | frame a goal — scaffold the session + author intent's Frame, Decisions, Constraints |
-| `/pb-step` | plan the next increment — a title, a done-when, a seam |
-| `/pb-build` | *(optional)* implement the planned step, then verify it to the pause |
-| `/pb-verify` | the tick — check → self-review → validate → **PAUSE** → checkpoint |
-| `/pb-park` | capture an idea without chasing it |
-| `/pb-status` | orient — where you are, what's parked, and the next move |
-| `/pb-harvest` | triage parked ideas at a boundary (blocker / tangent / pivot) |
-| `/pb-reset` | close out — write the report, archive, clear for a fresh goal |
-
-Three optional power moves survive for when you need them: `/pb-revert` (recover to a checkpoint), `/pb-spike` (throwaway worktree experiment), and `/plumbbob-interrogate` (attack the frame for holes).
+| `/plumbbob:plan` | plan the whole goal — scaffold the session + author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/plumbbob:step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
+| `/plumbbob:build` | *(optional)* implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done |
+| `/plumbbob:verify` | the tick — check → self-review → validate → **PAUSE** → checkpoint |
+| `/plumbbob:park` | capture an idea without chasing it |
+| `/plumbbob:status` | orient — where you are, the next step's done-when + seam, and the next move |
+| `/plumbbob:harvest` | triage parked ideas at a boundary (blocker / tangent / pivot) |
+| `/plumbbob:wrap` | wrap up — write the report, archive safely, clear for a fresh goal |
+
+Three optional power moves survive for when you need them: `/plumbbob:revert` (recover to
+a checkpoint), `/plumbbob:spike` (throwaway worktree experiment), and `/plumbbob:refine` (attack
+the frame for holes, or repair the plan when it drifts — usable at any point).
 
 ## The loop
 
-```
-/pb-plan                      frame the goal              (once)
+The happy path is **plan the whole thing up front, then drive `/plumbbob:build` until
+done** — approving each step at its verify pause:
+
+```text
+/plumbbob:plan                      author the whole plan (incl. all steps)   (once)
   └ per step:
-       /pb-status             "what's next?"
-       /pb-step               plan the next increment
-       /pb-build  (or DIY)    implement it
-       /pb-verify             check → review → PAUSE → checkpoint
-       /pb-park               capture strays mid-build
-       /pb-harvest            triage them at a boundary
-  /pb-reset                   report + archive + clear     (once)
+       /plumbbob:status             review the next step (done-when + seam)
+       /plumbbob:step   (optional)  sharpen/revise it first if needed
+       /plumbbob:build  (or DIY)    implement it → verify → PAUSE → checkpoint
+       /plumbbob:park               capture strays mid-build
+       /plumbbob:harvest            triage them at a boundary
+  /plumbbob:wrap                    report + archive + clear                  (once)
 ```
 
-**The pluggable executor.** `/pb-build` is one way to turn a planned step into code — it is *optional*. Implement by hand, in a vibe session, or with another harness, and run `/pb-verify` instead: it reads the *diff, not the author*. Plumbbob is the harness-agnostic spine; how the diff appears is a slot you fill however you like.
+Each `/plumbbob:build` builds the next undone step and stops at the pause for your
+approval — re-firing it is itself the clock tick. (`/plumbbob:build --auto` is the opt-in
+that lets the agent self-approve and chain to done, halting on a red check or any
+mismatch.) For a worked example that walks one goal end to end — planning, building
+each step, wrapping up, archiving, and starting the next task — see
+[`docs/happy-path.md`](docs/happy-path.md).
+
+**Three ways to plan.** `/plumbbob:plan` produces the same artifact — a complete, standalone
+`intent.md` — from whichever seed you give it: **no argument** runs a short interview;
+**a file path** absorbs an out-of-band spec (retaining its detail so the plan stands on
+its own); **any other text** expands your inline intent. No quotes required — it
+disambiguates the mode itself.
+
+**The pluggable executor.** `/plumbbob:build` is one way to turn a planned step into code
+— it is *optional*. Implement by hand, in a vibe session, or with another harness,
+and run `/plumbbob:verify` instead: it reads the *diff, not the author*. Plumbbob is the
+harness-agnostic spine; how the diff appears is a slot you fill however you like.
+
+## Calibration: size everything to the work
+
+The fastest way to abandon this is ceremony on a one-liner. The discipline is
+*decisions before code*, not *always produce three files*.
+
+- **Tiny** (typo, one-liner): no session. Just fix it.
+- **Small** (a contained bug/change): `/plumbbob:plan` a frame + 2–3 decisions; one or two
+  steps; build → verify → checkpoint.
+- **Medium** (a feature touching a few modules): the full loop above.
+- **Large / architectural**: that's Ridgeline's job, not Plumbbob's.
+
+Calibration is the skill. When in doubt, smaller.
 
 ## What ships
 
-- A `plumbbob` CLI (TypeScript, run natively by Node ≥ 22.18, zero runtime dependencies) — the dumb mechanical verbs the skills shell out to. You never type it by hand.
-- One session-gated Claude Code hook — `post-edit.sh`, a non-blocking light-feedback pass that injects file-scoped lint into the model's context. (v1's pre-edit muzzle and bash-guard are gone — guidance, not enforcement.)
-- The eight `pb-*` skills plus the optional power moves, each `disable-model-invocation` so *you* fire every move.
-- A `.plumbbob/` sidecar of flat files: `STATE` (orientation only), `intent.md`, `build-log.md`, `checkpoints`, and `archive/`.
+- A `plumbbob` CLI (TypeScript, run natively by Node ≥ 22.18, zero runtime
+  dependencies) — the dumb mechanical verbs the skills shell out to. You never type
+  it by hand.
+- The eight `/plumbbob:*` skills plus the optional power moves, each
+  `disable-model-invocation` so *you* fire every move.
+- One session-gated Claude Code hook — `post-edit.sh`, a non-blocking light-feedback
+  pass that injects file-scoped lint into the model's context so it self-corrects in
+  flow. (v1's pre-edit muzzle, seam-guard, and bash-guard are gone — guidance, not
+  enforcement.)
+- A `.plumbbob/` sidecar of flat files: `STATE` (orientation only), `intent.md`,
+  `build-log.md`, `checkpoints`, and `archive/`.
+
+## Gates — two tiers, different jobs
+
+- **Light** — the non-blocking `post-edit` feedback above. Per changed file. Never
+  blocks an edit. It exists only because Claude can't see your editor's LSP, so the
+  light tier *serves the model*.
+- **Heavy** — the full `pnpm check` (tsc, oxlint, ast-grep, vitest, knip,
+  markdownlint). Not a hook: it runs *inside* `/plumbbob:verify`, which refuses to
+  checkpoint while red. The hard gate lives on the deliberate boundary, not the
+  keystroke.
 
-## Install
+## STATE is orientation, not a gate
 
-The npm package is `plumbbob`; it installs the CLI (`plumbbob` plus a `pb` shorthand) and ships the hook and skills inside the package.
+The current position lives in one word in `.plumbbob/STATE` — `DESIGN`, `BUILD`, or
+`SPIKE`. It no longer gates anything. It is read by `/plumbbob:status` to tell you where
+you are and what to do next; a wrong state is a mislabeled position on a map, not a
+locked door. The post-edit hook is session-gated: a repo with no `.plumbbob/STATE`
+behaves exactly like plain Claude Code.
 
-### Project-level (recommended)
+## Git footprint — additive only
 
-```sh
-pnpm add -D plumbbob
-pnpm exec plumbbob setup --local    # or --project to commit it for a team
+Plumbbob commits cheap checkpoint markers (`plumbbob: step n done`) on your feature
+branch and reverts to its own recorded SHAs. It **never rewrites pushed history**;
+your normal squash-merge collapses the checkpoints at PR time. `start` records the
+baseline HEAD; `revert [--to n]` does `git reset --hard` to a recorded SHA; `wrap`
+archives plain markdown under `.plumbbob/archive/` and never touches git.
+
+## The `.plumbbob/` folder
+
+```text
+.plumbbob/
+  STATE          # one word: DESIGN | BUILD | SPIKE — orientation, not a gate
+  SEAM           # the in-flight step's declared paths (awareness, not a lock)
+  STEP           # the in-flight step number
+  checkpoints    # "step N <git-sha>", one per verified step
+  intent.md      # canonical intent
+  build-log.md   # live ledger
+  archive/
+    <date>-<slug>/
+      intent.md
+      build-log.md
+      report.md
 ```
 
-This copies the skills into `<repo>/.claude/skills/` (their bin pointed at the project-local binary) and registers the post-edit hook in place under `node_modules`. Nothing is written under `~`.
+## Install
 
-### Global
+Plumbbob is a personal tool — install it once, globally, like `gh` or your
+dotfiles. The npm package ships the CLI plus the skills and hook; `plumbbob init`
+links them into Claude Code as an in-place plugin.
 
 ```sh
-npm install -g plumbbob
-plumbbob setup --global
+npm i -g plumbbob      # the CLI (also a `pb` shorthand)
+plumbbob init          # link it into Claude Code; --uninstall to undo
 ```
 
-This copies the hook and skills under `~/.claude/` and registers them in `~/.claude/settings.json`. Restart Claude Code (or reload settings) after install.
+`init` symlinks the package into `~/.claude/skills/plumbbob`, where Claude Code
+loads it as a plugin: the skills appear namespaced as `/plumbbob:*` and the
+post-edit hook auto-registers from `hooks.json`. Nothing else under `~` is touched
+and `settings.json` is left alone — restart Claude Code (or `/reload-plugins`) to
+activate. Because it's a symlink, a later `npm i -g plumbbob@latest` stays live with
+no re-link.
 
-## STATE is orientation, not a gate
+**Sessions are per-project.** Install scope is not session scope: you install the
+tool once, but each goal lives in its own repo — `plumbbob start "<goal>"` writes a
+`.plumbbob/` sidecar there, independent of the one global link.
 
-The one-word `.plumbbob/STATE` (`DESIGN` / `BUILD` / `SPIKE`) is read by `/pb-status` to tell you where you are and what to do next. It no longer gates edits — a wrong state is a mislabeled position on a map, not a locked door. The post-edit hook is session-gated: a repo with no `.plumbbob/STATE` behaves exactly like plain Claude Code.
+**Other agents (roadmap).** The npm package is the agent-neutral carrier; a future
+`plumbbob init --host codex|cursor|zed` will place the same skills where those tools
+look. Claude Code is the first, first-class target.
 
-## Git footprint — additive only
+### Verify
+
+```sh
+plumbbob doctor
+```
 
-Plumbbob commits cheap checkpoint markers (`plumbbob: step n done`) on your feature branch and reverts to its own recorded SHAs. It never rewrites pushed history; your normal squash-merge collapses the checkpoints at PR time. `reset` archives plain markdown under `.plumbbob/archive/` and never touches git.
+`doctor` checks that the link resolves to the plugin manifest, the skills, and the
+hook, and prints the exact fix for anything broken. Run it first if a `/plumbbob:*`
+skill ever opens with an empty dashboard; [`docs/troubleshooting.md`](docs/troubleshooting.md)
+covers the rest.
 
 ## Development
 
@@ -93,7 +232,22 @@ pnpm check     # tsc, oxlint, ast-grep, vitest, knip, markdownlint
 pnpm build     # emit dist/ (what the published bin runs)
 ```
 
-The underlying philosophy — attention as the scarce resource — lives in [`docs/attention-first-development.md`](docs/attention-first-development.md).
+## Documentation
+
+- [`docs/techniques.md`](docs/techniques.md) — the methods behind the loop, each on its own.
+- [`docs/happy-path.md`](docs/happy-path.md) — one goal walked end to end.
+- [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, and exit code.
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.
+- [`docs/decisions.md`](docs/decisions.md) — the `D#` / `C#` design-decision key.
+- [`docs/attention-first-development.md`](docs/attention-first-development.md) — the philosophy: attention as the scarce resource.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventions, and how to submit changes.
+
+## The shape, in one line
+
+The human owns convergence; the LLM owns divergence in design and convergence only
+in implementation; and the boundary between deciding and executing is a **pause you
+advance**, not a lock you fight — the system does the labor and waits for you to be
+the clock.
 
 ## License
 

package/dist/cli-core.js

@@ -0,0 +1,83 @@
+// 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. Zero runtime deps, node: builtins only (D1/C2).
+// Functional/procedural: no classes, no `this`, no default export (C1).
+import { start } from "./verbs/start.js";
+import { status } from "./verbs/status.js";
+import { park } from "./verbs/park.js";
+import { build } from "./verbs/build.js";
+import { check } from "./verbs/check.js";
+import { checkpoint } from "./verbs/checkpoint.js";
+import { revert } from "./verbs/revert.js";
+import { spike } from "./verbs/spike.js";
+import { wrap } from "./verbs/wrap.js";
+import { init } from "./verbs/init.js";
+import { doctor } from "./verbs/doctor.js";
+const VERBS = [
+    { name: 'start', summary: 'scaffold .plumbbob/; STATE=DESIGN; record the baseline commit' },
+    { name: 'status', summary: 'print the session state, or NO ACTIVE SESSION' },
+    { name: 'build', summary: 'build <n>: write the seam from step n; STATE=BUILD (orientation, not a lock)' },
+    { name: 'check', summary: 'run the heavy check and report; no state change' },
+    { name: 'checkpoint', summary: 'checkpoint [<n>]: gate on green, commit/record SHA, mark step done, STATE=DESIGN (executor-agnostic)' },
+    { name: 'revert', summary: 'revert [--to n]: git reset --hard to a checkpoint SHA; STATE=DESIGN' },
+    { name: 'park', summary: 'park "<text>": append a raw line to the park list' },
+    { name: 'spike', summary: 'spike "<slug>" | spike done: throwaway worktree experiment' },
+    { name: 'wrap', summary: 'v2 close-out: archive intent+log+report (no gate), clear the sidecar, STATE off' },
+    { name: 'init', summary: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob); --uninstall to undo' },
+    { name: 'doctor', summary: 'diagnose the plugin link (manifest, skills, hook) and print the fix for anything broken' },
+];
+// Plumbbob v2 (D1/D10/D13): the deciding/executing boundary is no longer a lock,
+// so there is nothing to defend — every verb runs the same whether a human or the
+// model triggers it. The old human-only `mode` escape hatch and its CLAUDECODE
+// in-session refusal are gone; what keeps the human the decider is the pause at
+// the step boundary (the skills), not a refusal here.
+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');
+}
+function dispatch(verb, cwd, rest) {
+    switch (verb) {
+        case 'start':
+            return start(cwd, rest);
+        case 'status':
+            return status(cwd);
+        case 'park':
+            return park(cwd, rest);
+        case 'build':
+            return build(cwd, rest);
+        case 'check':
+            return check(cwd);
+        case 'checkpoint':
+            return checkpoint(cwd, rest);
+        case 'revert':
+            return revert(cwd, rest);
+        case 'spike':
+            return spike(cwd, rest);
+        case 'wrap':
+            return wrap(cwd);
+        case 'init':
+            return init(rest);
+        case 'doctor':
+            return doctor();
+        default:
+            process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
+            return 1;
+    }
+}
+export function run(argv) {
+    const verb = argv[0] ?? 'help';
+    const rest = argv.slice(1);
+    if (verb === 'help' || verb === '--help' || verb === '-h') {
+        process.stdout.write(`${formatHelp()}\n`);
+        return 0;
+    }
+    try {
+        return dispatch(verb, process.cwd(), rest);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`plumbbob: ${verb} failed: ${message}\n`);
+        return 1;
+    }
+}

package/dist/cli.js

@@ -1,80 +1,8 @@
 #!/usr/bin/env node
-// plumbbob CLI — hand-rolled argv dispatch, zero runtime deps, node: builtins
-// only (D1/C2). Functional/procedural: no classes, no `this`, no default
-// export (C1). Verbs are wired up build step by build step.
-import { start } from "./verbs/start.js";
-import { status } from "./verbs/status.js";
-import { park } from "./verbs/park.js";
-import { build } from "./verbs/build.js";
-import { check } from "./verbs/check.js";
-import { checkpoint } from "./verbs/checkpoint.js";
-import { revert } from "./verbs/revert.js";
-import { spike } from "./verbs/spike.js";
-import { reset } from "./verbs/reset.js";
-import { setup } from "./verbs/setup.js";
-const VERBS = [
-    { name: 'start', summary: 'scaffold .plumbbob/; STATE=DESIGN; record the baseline commit' },
-    { name: 'status', summary: 'print the session state, or NO ACTIVE SESSION' },
-    { name: 'build', summary: 'build <n>: write the seam from step n; STATE=BUILD (orientation, not a lock)' },
-    { name: 'check', summary: 'run the heavy check and report; no state change' },
-    { name: 'checkpoint', summary: 'checkpoint [<n>]: gate on green, commit/record SHA, mark step done, STATE=DESIGN (executor-agnostic)' },
-    { name: 'revert', summary: 'revert [--to n]: git reset --hard to a checkpoint SHA; STATE=DESIGN' },
-    { name: 'park', summary: 'park "<text>": append a raw line to the park list' },
-    { name: 'spike', summary: 'spike "<slug>" | spike done: throwaway worktree experiment' },
-    { name: 'reset', summary: 'v2 close-out: archive intent+log+report (no gate), clear the sidecar, STATE off' },
-    { name: 'setup', summary: 'install hooks + skills; register them (self-contained per-project by default; --global for ~/.claude)' },
-];
-// Plumbbob v2 (D1/D10/D13): the deciding/executing boundary is no longer a lock,
-// so there is nothing to defend — every verb runs the same whether a human or the
-// model triggers it. The old human-only `mode` escape hatch and its CLAUDECODE
-// in-session refusal are gone; what keeps the human the decider is the pause at
-// the step boundary (the skills), not a refusal here.
-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');
-}
-function dispatch(verb, cwd, rest) {
-    switch (verb) {
-        case 'start':
-            return start(cwd, rest);
-        case 'status':
-            return status(cwd);
-        case 'park':
-            return park(cwd, rest);
-        case 'build':
-            return build(cwd, rest);
-        case 'check':
-            return check(cwd);
-        case 'checkpoint':
-            return checkpoint(cwd, rest);
-        case 'revert':
-            return revert(cwd, rest);
-        case 'spike':
-            return spike(cwd, rest);
-        case 'reset':
-            return reset(cwd);
-        case 'setup':
-            return setup(cwd, rest);
-        default:
-            process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
-            return 1;
-    }
-}
-function run(argv) {
-    const verb = argv[0] ?? 'help';
-    const rest = argv.slice(1);
-    if (verb === 'help' || verb === '--help' || verb === '-h') {
-        process.stdout.write(`${formatHelp()}\n`);
-        return 0;
-    }
-    try {
-        return dispatch(verb, process.cwd(), rest);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`plumbbob: ${verb} failed: ${message}\n`);
-        return 1;
-    }
-}
+// plumbbob CLI entry — the published bin. All routing and the help table live in
+// cli-core.ts (unit-tested in-process); this file is only the executable shell:
+// it wires argv to the dispatcher and turns the returned code into the exit code.
+// Keeping the single process.exit here is what lets cli-core.ts be imported by a
+// test without tearing down the worker.
+import { run } from "./cli-core.js";
 process.exit(run(process.argv.slice(2)));

package/dist/lib/archive.js

@@ -58,7 +58,7 @@ function uniqueArchiveDir(root, base) {
 }
 // Copy intent + build-log + report into archive/<date>-<slug>/ and return the
 // directory created. Intent and build-log always exist in an active session; the
-// report is copied only when present — v2 `reset` does not gate on it (D9), so a
+// report is copied only when present — v2 `wrap` does not gate on it (D9), so a
 // close-out without a report still archives the rest.
 export function archiveSession(root) {
     const dir = uniqueArchiveDir(root, `${today()}-${slugify(sessionTitle(root))}`);

package/dist/lib/orient.js

@@ -3,6 +3,7 @@
 // best-effort — it takes raw file contents (no fs), and a malformed doc degrades
 // to fewer fields rather than throwing. Functional/procedural, no classes, no
 // default export (C1).
+import { parseStepSeam } from "./intent.js";
 // The lines of a named `## Section`, from its heading to the next `## ` (or EOF).
 function sectionLines(content, heading) {
     const lines = content.split('\n');
@@ -45,8 +46,10 @@ export function parseSteps(intent) {
     });
     return starts.map((s, i) => {
         const blockEnd = starts[i + 1]?.idx ?? lines.length;
-        const block = lines.slice(s.idx, blockEnd).join('\n').toLowerCase();
-        return { n: s.n, done: s.done, title: s.title, planned: block.includes('done when') };
+        const block = lines.slice(s.idx, blockEnd).join('\n');
+        const dw = /\*\*done when:\*\*\s*(.+)/i.exec(block);
+        const doneWhen = dw ? (dw[1] ?? '').trim() : null;
+        return { n: s.n, done: s.done, title: s.title, planned: /done when/i.test(block), doneWhen };
     });
 }
 // Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section — mechanical
@@ -74,7 +77,7 @@ export function parseOpenQuestions(intent) {
         .length;
 }
 // Open parked items: `- [ ]` lines under `## Park list` (the `park` verb's format).
-// A harvested item is flipped to `- [x]` by `/pb-harvest` and no longer counts; the
+// A harvested item is flipped to `- [x]` by `/plumbbob:harvest` and no longer counts; the
 // `(none yet)` placeholder and the blockquote instructions never match.
 export function parseParked(buildLog) {
     return sectionLines(buildLog, '## Park list').filter((l) => /^-\s+\[ \]\s+\S/.test(l.trim())).length;
@@ -96,36 +99,38 @@ function nextMove(state, steps, inFlight, parked) {
         case 'SPIKE':
             return 'close the spike — `plumbbob spike done`';
         case 'FINISH':
-            return 'wrap up — `/pb-reset`';
+            return 'wrap up — `/plumbbob:wrap`';
         case 'REVIEW':
-            return 'read the diff cold against intent, then `/pb-verify`';
+            return 'read the diff cold against intent, then `/plumbbob:verify`';
         case 'BUILD': {
             const n = inFlight ?? steps.find((s) => !s.done)?.n;
             return n === undefined
-                ? 'finish the step in flight — `/pb-verify`'
-                : `finish step ${n} — \`/pb-verify\` (or keep editing, then \`/pb-verify\`)`;
+                ? 'finish the step in flight — `/plumbbob:verify`'
+                : `finish step ${n} — \`/plumbbob:verify\` (or keep editing, then \`/plumbbob:verify\`)`;
         }
         default: {
             // DESIGN (and any unknown state): you are at the boundary.
             const nextUndone = steps.find((s) => !s.done);
             if (nextUndone === undefined) {
                 if (steps.length === 0) {
-                    return 'plan the first step — `/pb-step`';
+                    return 'plan the first step — `/plumbbob:step`';
                 }
-                // Just-in-time (D6): finishing the *planned* steps usually means "plan the
-                // next," not "done" — only the human knows which, so offer both.
-                const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/pb-harvest\`; then ` : '';
-                return `${harvest}plan the next step — \`/pb-step\` (or \`/pb-reset\` to wrap up if you're done)`;
+                // Batch-default: the steps were planned up front, so finishing them usually
+                // means "wrap up" — but `/plumbbob:step` can still add an increment if reality grew.
+                const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/plumbbob:harvest\`; then ` : '';
+                return `${harvest}wrap up — \`/plumbbob:wrap\` (or \`/plumbbob:step\` to add another increment)`;
             }
             return nextUndone.planned
-                ? `build step ${nextUndone.n} — \`/pb-build\``
-                : `plan step ${nextUndone.n} — \`/pb-step\``;
+                ? `build step ${nextUndone.n} — \`/plumbbob:build\` (or \`/plumbbob:step\` to revise it first)`
+                : `plan step ${nextUndone.n} — \`/plumbbob:step\``;
         }
     }
 }
 export function orient(input) {
     const steps = parseSteps(input.intent);
     const parked = parseParked(input.buildLog);
+    const nextUndone = steps.find((s) => !s.done);
+    const seamParse = nextUndone === undefined ? null : parseStepSeam(input.intent, nextUndone.n);
     return {
         title: parseTitle(input.intent),
         state: input.state,
@@ -134,6 +139,8 @@ export function orient(input) {
         parked,
         openQuestions: parseOpenQuestions(input.intent),
         next: nextMove(input.state, steps, input.inFlight, parked),
+        nextDoneWhen: nextUndone?.doneWhen ?? null,
+        nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
     };
 }
 export function formatOrientation(o) {
@@ -142,7 +149,20 @@ export function formatOrientation(o) {
     const stepLines = o.steps.map((s) => {
         const marker = s.done ? '✓' : s === nextUndone ? '▸' : ' ';
         const tail = s === nextUndone ? '   ← next' : '';
-        return `  ${marker} ${s.n}  ${s.title}${tail}`;
+        const head = `  ${marker} ${s.n}  ${s.title}${tail}`;
+        if (s !== nextUndone) {
+            return head;
+        }
+        // Surface the next step's detail so the human can review it (and `/plumbbob:step`-
+        // revise) before building. Only what's present — a rough step shows neither.
+        const detail = [];
+        if (o.nextDoneWhen !== null) {
+            detail.push(`        done when: ${o.nextDoneWhen}`);
+        }
+        if (o.nextSeam.length > 0) {
+            detail.push(`        seam: ${o.nextSeam.join(', ')}`);
+        }
+        return detail.length > 0 ? [head, ...detail].join('\n') : head;
     });
     const stepsBlock = o.steps.length === 0 ? '  (no steps planned yet)' : `  steps  ${doneCount}/${o.steps.length} done\n${stepLines.join('\n')}`;
     const cp = o.lastCheckpoint;

package/dist/verbs/check.js

@@ -1,5 +1,5 @@
 // `plumbbob check` — run the heavy gate (D16/D24) and report, with NO state
-// change. The read-only half of the verify tick: `/pb-verify` runs this before the
+// change. The read-only half of the verify tick: `/plumbbob:verify` runs this before the
 // pause so the human approves on a known-green check. Exits with the check's own
 // code (0 = green).
 import { findRepoRoot } from "../lib/git.js";

package/dist/verbs/checkpoint.js

@@ -4,7 +4,7 @@
 // It gates on a green check, then commits any pending work (or records the existing
 // HEAD when the tree is already clean — the human's commit skill may have committed
 // first), records the SHA, flips the intent checkbox to `[x]`, clears any STEP/SEAM,
-// and returns to DESIGN. The diff's author is irrelevant: `/pb-build`, your hands,
+// and returns to DESIGN. The diff's author is irrelevant: `/plumbbob:build`, your hands,
 // a vibe session, or another harness all checkpoint the same way.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll } from "../lib/git.js";