plumbbob 0.2.3 → 0.3.1

package/README.md

@@ -1,179 +1,107 @@
 # Plumbbob
 
-A manual, attention-first build process that enforces the deciding/executing
-boundary so you build *with* an LLM instead of being dragged behind one. You
-decide on a surface outside the chat; a one-word state file and a set of Claude
-Code hooks refuse to let code edits cross that line until you have.
+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.
 
-The full philosophy — the one law, the mode machine, the loop — lives in
-[`docs/plumbbob-README.md`](docs/plumbbob-README.md). This file is the
-as-built reference: what ships, how to install it, and the verbs you type.
+> Ridgeline is the line. Plumbbob establishes *true* before you build.
+> The LLM is a hand, not a head.
 
-This repository was built using Plumbbob, dogfooded on its own build under its
-own enforcement from step 5 onward.
+This repository was built using Plumbbob v2, dogfooded on its own build under its own loop.
+
+## 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.
+
+- 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.
+
+## 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.
+
+| 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).
+
+## The loop
+
+```
+/pb-plan                      frame the goal              (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)
+```
+
+**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.
 
 ## What ships
 
-- A `plumbbob` CLI (TypeScript, run natively by Node ≥ 22.18, zero runtime
-  dependencies) — the dumb mechanical verbs that move the state machine and the
-  git checkpoints.
-- Three session-gated Claude Code hooks — a pre-edit muzzle + seam-guard, a Bash
-  guard, and a non-blocking light-feedback pass. With no active session they
-  short-circuit to allow in microseconds, so a repo without a Plumbbob session
-  behaves like plain Claude Code.
-- The judgment skills — the design/finish thinking work, each human-triggered
-  (`disable-model-invocation: true`): `/plumbbob-interrogate`, `/park`,
-  `/plumbbob-triage`, `/plumbbob-report`, `/plumbbob-docs`.
-- The `pb-*` driver skills — thin chat-side triggers for the transition verbs
-  (`/pb-start`, `/pb-build`, `/pb-review`, `/pb-done`, `/pb-revert`, `/pb-wrap`,
-  `/pb-finish`, `/pb-spike`), also `disable-model-invocation: true`, so you can
-  drive the whole loop from the agent window without leaving for a terminal.
-- A `.plumbbob/` sidecar of flat control files (`STATE`, `SEAM`, `checkpoints`,
-  `intent.md`, `build-log.md`) that the hooks read with a grep.
+- 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/`.
 
 ## Install
 
-The npm package is `plumbbob`; it installs the CLI as `plumbbob` plus a `pb`
-shorthand, and ships the hooks and skills inside the package. There are two
-install shapes: project-level (self-contained, nothing global) and global.
-
-### Project-level (recommended) — nothing under `~`
+The npm package is `plumbbob`; it installs the CLI (`plumbbob` plus a `pb` shorthand) and ships the hook and skills inside the package.
 
-Add Plumbbob as a dev dependency and set it up self-contained, so everything
-lives in the repo and `node_modules` with no global install to manage:
+### Project-level (recommended)
 
 ```sh
 pnpm add -D plumbbob
-pnpm exec plumbbob setup --local   # or just `setup` — it auto-detects a project-local install
+pnpm exec plumbbob setup --local    # or --project to commit it for a team
 ```
 
-A self-contained `setup` writes **nothing** under `~/.claude`. It copies the
-skills into `<repo>/.claude/skills/` (with their bin invocation pointed at the
-project-local `node_modules/.bin/plumbbob`) and registers the hooks in place at
-`$CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks/`.
-
-| Command                              | Registers in                         | Use for                          |
-|--------------------------------------|--------------------------------------|----------------------------------|
-| `pnpm exec plumbbob setup --local`   | `<repo>/.claude/settings.local.json` | yourself, this repo (untracked)  |
-| `pnpm exec plumbbob setup --project` | `<repo>/.claude/settings.json`       | enrolling a team (committable)   |
-
-Both forms address the hooks and the skill bin through `$CLAUDE_PROJECT_DIR`, so
-a committed `settings.json` carries no machine-absolute path — a teammate runs
-`pnpm install` and re-runs `setup` to regenerate their skills copy.
+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 `~`.
 
-### Global — one install, every repo
+### Global
 
 ```sh
 npm install -g plumbbob
 plumbbob setup --global
 ```
 
-`setup --global` copies the hooks to `~/.claude/plumbbob/hooks/` and the skills
-to `~/.claude/skills/`, then registers absolute command paths in
-`~/.claude/settings.json`. The skills call a bare `plumbbob`, which the global
-install puts on your `PATH`; from a dev checkout, alias it instead:
+This copies the hook and skills under `~/.claude/` and registers them in `~/.claude/settings.json`. Restart Claude Code (or reload settings) after install.
+
+### Verify the install
 
 ```sh
-alias plumbbob='node /path/to/plumbbob/src/cli.ts'
+pnpm exec plumbbob doctor    # or `plumbbob doctor` for a global install
 ```
 
-`plumbbob setup --uninstall` (with the same scope flag) strips the registration;
-the installed/copied files stay in place. After installing, restart Claude Code
-(or reload settings) for the hooks to take effect.
-
-## The verbs and skills
-
-Mechanical verbs are the `plumbbob` CLI, run from your terminal. The judgment
-work is skills, invoked from the chat pane. The split is judgment-vs-mechanism.
-
-| Verb / skill               | Does                                                              | Kind          |
-|----------------------------|------------------------------------------------------------------|---------------|
-| `plumbbob start "<t>"`    | scaffold `.plumbbob/`; `STATE=DESIGN`; record the baseline      | CLI           |
-| `/plumbbob-interrogate`   | `DESIGN`; attack the frame for holes; append to Open questions   | skill (Opus)  |
-| `plumbbob build <n>`      | write `SEAM` from step n; `STATE=BUILD`                          | CLI           |
-| `plumbbob review`         | run the heavy check; if green → `STATE=REVIEW`                   | CLI           |
-| `plumbbob done`           | ensure check green; checkpoint commit + record SHA; `STATE=DESIGN` | CLI         |
-| `plumbbob park "<text>"`  | append a raw line to the park list; the model never sees it      | CLI (dumb)    |
-| `/park`                    | compose one tidy tagged line, you approve, then it shells `park` | skill (Haiku) |
-| `/plumbbob-triage`        | `DESIGN`; classify the park list blocker/tangent/pivot           | skill (Opus)  |
-| `plumbbob revert [--to n]`| `git reset --hard` to a checkpoint SHA; `STATE=DESIGN`           | CLI           |
-| `plumbbob wrap`           | `STATE=FINISH` so the report and docs skills can run             | CLI           |
-| `/plumbbob-report`        | `FINISH`; write `.plumbbob/report.md` from intent + log         | skill (Opus)  |
-| `/plumbbob-docs`          | `FINISH`; conservatively update `docs/` from canonical intent    | skill (Opus)  |
-| `plumbbob finish`         | refuse unless a report exists; archive; clear; muzzle off        | CLI           |
-| `plumbbob spike "<slug>"` | throwaway worktree experiment per option; `spike done` tears down | CLI          |
-| `plumbbob mode <x>`       | escape hatch: set `STATE` directly (not part of the normal flow) | CLI (hidden)  |
-| `plumbbob setup`          | install hooks + skills; register them (install shapes above)     | CLI           |
-
-### Driving the transitions from the chat
-
-Every transition verb also has a thin `pb-*` driver skill, so you can run the
-whole loop from the agent window without switching to a terminal: `/pb-start`,
-`/pb-build`, `/pb-review`, `/pb-done`, `/pb-revert`, `/pb-wrap`, `/pb-finish`,
-`/pb-spike`. Each shells exactly its verb and reports the result verbatim; each is
-`disable-model-invocation: true`, so *only you* can fire it.
-
-The boundary the one law protects is **human-initiated vs model-initiated**, not
-terminal-vs-chat. A `disable-model-invocation` skill is a human trigger that
-happens to live in the chat: the model can never invoke it, the deciding still
-happens in `intent.md`, and the verb is still dumb mechanism. So the transition
-verbs run in-session now (a terminal still works too) — the lone hold-out is
-`mode`, the escape hatch, which stays human-only (refused in-session, and blocked
-from the model's shell by the Bash guard). The transition verbs are deliberately
-kept out of your settings allowlist, so a stray *model-initiated* transition
-surfaces a Claude Code permission prompt; each driver skill self-authorizes only
-its own verb, only while you are running it.
-
-## The core / adapter boundary
-
-The deciding/executing core — the `plumbbob` CLI, the `.plumbbob/` sidecar, and
-the additive git footprint — is agent- and model-agnostic. Only the enforcement
-layer (the hooks, the skills, the `CLAUDECODE` verb guard) is specific to Claude
-Code, because enforcement inherently means intercepting some agent's edit tool.
-Claude Code is v1's enforcement adapter; other-agent adapters over the same core
-are a future Plumbbob, not a v1 obligation.
-
-## Ratified residual gaps
-
-These are deliberate v1 boundaries, decided on the record, not oversights:
-
-- **The archive is local-only.** `finish` lists the checkpoint SHAs in the report
-  and archives plain markdown under `.plumbbob/archive/`; it never touches git
-  (D20). The sidecar is kept untracked so a revert can never destroy captured
-  attention.
-- **The muzzle is a fence, not a wall.** The Bash guard blocks the obvious
-  shell-write escape routes around the edit hooks, but full shell-write detection
-  is unsolvable; a determined model can still get around it (D21). The fence
-  raises the cost of crossing the boundary by accident, which is the job.
-- **`tsc` is deferred to the heavy tier.** The light post-edit feedback runs
-  file-scoped oxlint + ast-grep only; `tsc` has no true single-file mode, so it
-  runs in the `pnpm check` gate inside `review`/`done` rather than per keystroke
-  (D25).
+`doctor` checks the four things that must be true — the skills are present, their bin resolves, the CLI is installed, and the post-edit hook is registered — and prints the exact fix for anything broken. Run it first if a `/pb-*` skill ever opens with an empty dashboard.
+
+## STATE is orientation, not a gate
+
+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.
+
+## Git footprint — additive only
+
+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.
 
 ## Development
 
 ```sh
 pnpm install
 pnpm check     # tsc, oxlint, ast-grep, vitest, knip, markdownlint
-pnpm build     # emit dist/ (what the published bin runs); prepack runs this for you
+pnpm build     # emit dist/ (what the published bin runs)
 ```
 
-The published `bin` (`plumbbob` / `pb`) points at `dist/cli.js`, not the `.ts`
-source, so a fresh install runs under plain `node` without `tsx`. The `prepack`
-hook rebuilds `dist/` before every pack/publish; you only need `pnpm build` by
-hand when you want to run the compiled output locally. From a dev checkout the
-source still runs directly (`node src/cli.ts`) via Node's type stripping.
-
-**The pnpm pin.** `package.json` pins `devEngines.packageManager` to an *exact*
-pnpm version (`11.1.2`) rather than a range, because the `^` range broke every
-pnpm command at the time of writing. That exact pin will need bumping by hand on
-the next pnpm upgrade; moving back to a ranged constraint is a future revisit.
-
-`scripts/dev-install.sh` is the development installer: it registers the hooks
-pointing at this working tree's `hooks/` (so hook edits take effect with no
-re-copy), where `plumbbob setup --global` copies them into `~/.claude/`. Use
-`dev-install.sh` while hacking on the hooks themselves; use `plumbbob setup` to
-install Plumbbob for real.
+The underlying philosophy — attention as the scarce resource — lives in [`docs/attention-first-development.md`](docs/attention-first-development.md).
 
 ## License
 

package/dist/cli.js

@@ -4,41 +4,33 @@
 // export (C1). Verbs are wired up build step by build step.
 import { start } from "./verbs/start.js";
 import { status } from "./verbs/status.js";
-import { mode } from "./verbs/mode.js";
 import { park } from "./verbs/park.js";
 import { build } from "./verbs/build.js";
-import { review } from "./verbs/review.js";
-import { done } from "./verbs/done.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 { finish } from "./verbs/finish.js";
+import { reset } from "./verbs/reset.js";
 import { setup } from "./verbs/setup.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 SEAM from step n; STATE=BUILD' },
-    { name: 'review', summary: 'run the heavy check; if green flip to STATE=REVIEW' },
-    { name: 'done', summary: 'ensure check green; checkpoint commit + record SHA; STATE=DESIGN' },
+    { 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: 'set STATE=FINISH so /plumbbob-report and /plumbbob-docs can run' },
-    { name: 'finish', summary: 'refuse unless a report is archived; archive; clear; muzzle off' },
-    { name: 'mode', summary: 'mode <x>: set STATE directly (hidden escape hatch)' },
+    { 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)' },
+    { name: 'doctor', summary: 'diagnose the install (skills, bin, hook) and print the fix for anything broken' },
 ];
-// D21 (revised): the human owns every transition — but the trigger surface is no
-// longer "terminal vs chat", it is "human-initiated vs model-initiated". The
-// human now fires transitions from the chat through the `pb-*` driver skills
-// (`disable-model-invocation: true`, so the model can never invoke them) just as
-// well as from a terminal, so the blanket in-session refusal is gone. The lone
-// hold-out is `mode`, the hidden escape hatch for desyncs: it stays human-only,
-// refused in-session (CLAUDECODE set) and also blocked from the model's shell by
-// bash-guard.sh. A stray model-initiated transition is caught by Claude Code's
-// permission prompt, since the transition verbs are deliberately kept out of the
-// settings allowlist (only each driver skill self-authorizes its own verb).
-const HUMAN_ONLY_VERBS = new Set(['mode']);
+// 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}`);
@@ -50,26 +42,24 @@ function dispatch(verb, cwd, rest) {
             return start(cwd, rest);
         case 'status':
             return status(cwd);
-        case 'mode':
-            return mode(cwd, rest);
         case 'park':
             return park(cwd, rest);
         case 'build':
             return build(cwd, rest);
-        case 'review':
-            return review(cwd);
-        case 'done':
-            return done(cwd);
+        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 'finish':
-            return finish(cwd);
+        case 'reset':
+            return reset(cwd);
         case 'setup':
             return setup(cwd, rest);
+        case 'doctor':
+            return doctor(cwd);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;
@@ -82,11 +72,6 @@ function run(argv) {
         process.stdout.write(`${formatHelp()}\n`);
         return 0;
     }
-    if (HUMAN_ONLY_VERBS.has(verb) && process.env.CLAUDECODE) {
-        process.stderr.write(`plumbbob: '${verb}' is the human's escape hatch, not a model action (you appear to be in a Claude Code session). ` +
-            `Do not retry. Ask the human to run \`plumbbob ${verb}\` themselves.\n`);
-        return 1;
-    }
     try {
         return dispatch(verb, process.cwd(), rest);
     }

package/dist/lib/archive.js

@@ -57,13 +57,16 @@ function uniqueArchiveDir(root, base) {
     return candidate;
 }
 // Copy intent + build-log + report into archive/<date>-<slug>/ and return the
-// directory created. The report must already exist (finish guards that); intent
-// and build-log always exist in an active session.
+// 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
+// close-out without a report still archives the rest.
 export function archiveSession(root) {
     const dir = uniqueArchiveDir(root, `${today()}-${slugify(sessionTitle(root))}`);
     mkdirSync(dir, { recursive: true });
     copyFileSync(intentPath(root), join(dir, 'intent.md'));
     copyFileSync(buildLogPath(root), join(dir, 'build-log.md'));
-    copyFileSync(reportPath(root), join(dir, 'report.md'));
+    if (existsSync(reportPath(root))) {
+        copyFileSync(reportPath(root), join(dir, 'report.md'));
+    }
     return dir;
 }

package/dist/lib/git.js

@@ -43,10 +43,6 @@ export function isDirty(root) {
 export function stageAll(root) {
     runGit(root, ['add', '-A']);
 }
-export function stagedPaths(root) {
-    const out = runGit(root, ['diff', '--cached', '--name-only']);
-    return out.length === 0 ? [] : out.split('\n');
-}
 export function untrackedPaths(root) {
     const out = runGit(root, ['ls-files', '--others', '--exclude-standard']);
     return out.length === 0 ? [] : out.split('\n');

package/dist/lib/intent.js

@@ -79,7 +79,7 @@ export function parseStepSeam(content, step) {
 }
 // Seam membership (D23): a repo-relative path is in-seam if it equals an exact
 // token, or is prefixed by a `dir/` grant. Shared by `done` (scope-drift warn)
-// and `revert` (untracked cleanup); the pre-edit hook reimplements it in sh.
+// and `revert` (untracked cleanup).
 export function matchesSeam(relPath, tokens) {
     return tokens.some((token) => (token.endsWith('/') ? relPath.startsWith(token) : relPath === token));
 }

package/dist/lib/orient.js

@@ -0,0 +1,160 @@
+// Orientation model for `status` (D8/D15): parse a live session into the
+// dashboard the human reads to know where they are and what to do next. Pure and
+// 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).
+// The lines of a named `## Section`, from its heading to the next `## ` (or EOF).
+function sectionLines(content, heading) {
+    const lines = content.split('\n');
+    const start = lines.findIndex((l) => l.trim() === heading);
+    if (start === -1) {
+        return [];
+    }
+    let end = lines.findIndex((l, i) => i > start && l.startsWith('## '));
+    if (end === -1) {
+        end = lines.length;
+    }
+    return lines.slice(start + 1, end);
+}
+export function parseTitle(intent) {
+    for (const line of intent.split('\n')) {
+        const m = /^#\s+(.+?)\s*$/.exec(line);
+        if (m) {
+            return m[1] ?? null;
+        }
+    }
+    return null;
+}
+// Steps under `## Steps`: `N. [ |x] Title — **done when:** ...`. The title is the
+// text up to the first em dash; `planned` is true when the step's block carries a
+// `done when` criterion. Roadmap prose lives in its own section, never here (D6).
+export function parseSteps(intent) {
+    const lines = sectionLines(intent, '## Steps');
+    const starts = [];
+    lines.forEach((line, idx) => {
+        const m = /^(\d+)\.\s+\[([ xX])\]\s+(.*)$/.exec(line);
+        if (m) {
+            const rest = m[3] ?? '';
+            starts.push({
+                n: Number(m[1]),
+                done: (m[2] ?? ' ').toLowerCase() === 'x',
+                title: (rest.split('—')[0] ?? rest).trim(),
+                idx,
+            });
+        }
+    });
+    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') };
+    });
+}
+// Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section — mechanical
+// bookkeeping for `checkpoint` so `status` reflects a checkpointed step. A no-op if
+// the step is absent or already done.
+export function markStepDone(intent, n) {
+    let inSteps = false;
+    return intent
+        .split('\n')
+        .map((line) => {
+        if (line.trim() === '## Steps') {
+            inSteps = true;
+            return line;
+        }
+        if (inSteps && line.startsWith('## ')) {
+            inSteps = false;
+        }
+        return inSteps && new RegExp(`^${n}\\.\\s+\\[ \\]`).test(line) ? line.replace('[ ]', '[x]') : line;
+    })
+        .join('\n');
+}
+// Open questions still open: `- Q\d+:` lines that do not say "resolved".
+export function parseOpenQuestions(intent) {
+    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+:/.test(l.trim()) && !/resolved/i.test(l))
+        .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
+// `(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;
+}
+export function parseLastCheckpoint(checkpoints) {
+    let last = null;
+    for (const line of checkpoints.split('\n')) {
+        const m = /^step\s+(\d+)\s+(\S+)/.exec(line.trim());
+        if (m) {
+            last = { n: Number(m[1]), sha: m[2] ?? '' };
+        }
+    }
+    return last;
+}
+// The single primary next move (D15). It suggests; the dashboard prints the full
+// list + counts so the human can always override.
+function nextMove(state, steps, inFlight, parked) {
+    switch (state) {
+        case 'SPIKE':
+            return 'close the spike — `plumbbob spike done`';
+        case 'FINISH':
+            return 'wrap up — `/pb-reset`';
+        case 'REVIEW':
+            return 'read the diff cold against intent, then `/pb-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\`)`;
+        }
+        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`';
+                }
+                // 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)`;
+            }
+            return nextUndone.planned
+                ? `build step ${nextUndone.n} — \`/pb-build\``
+                : `plan step ${nextUndone.n} — \`/pb-step\``;
+        }
+    }
+}
+export function orient(input) {
+    const steps = parseSteps(input.intent);
+    const parked = parseParked(input.buildLog);
+    return {
+        title: parseTitle(input.intent),
+        state: input.state,
+        steps,
+        lastCheckpoint: parseLastCheckpoint(input.checkpoints),
+        parked,
+        openQuestions: parseOpenQuestions(input.intent),
+        next: nextMove(input.state, steps, input.inFlight, parked),
+    };
+}
+export function formatOrientation(o) {
+    const doneCount = o.steps.filter((s) => s.done).length;
+    const nextUndone = o.steps.find((s) => !s.done);
+    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 stepsBlock = o.steps.length === 0 ? '  (no steps planned yet)' : `  steps  ${doneCount}/${o.steps.length} done\n${stepLines.join('\n')}`;
+    const cp = o.lastCheckpoint;
+    const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
+    return [
+        `Plumbbob — ${o.title ?? '(untitled)'}   [${o.state}]`,
+        '',
+        stepsBlock,
+        '',
+        cpLine,
+        `parked ${o.parked} · open questions ${o.openQuestions}`,
+        '',
+        `next → ${o.next}`,
+    ].join('\n');
+}

package/dist/lib/settings.js

@@ -11,15 +11,18 @@ import { dirname } from 'node:path';
 // `$CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks/...` reference both contain
 // `plumbbob/hooks/`, so uninstall finds either.
 const OURS_MARKER = 'plumbbob/hooks/';
-// The PreToolUse edit matcher covers all four editing tools (D5).
+// The edit matcher covers all four editing tools (D5); v2 uses it for the
+// post-edit feedback hook (the only edit-time hook left).
 const EDIT_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
-// The three hook registration entries, pointing at `hooksDir`. Two command forms:
+// The single hook Plumbbob v2 registers: the PostToolUse light feedback (D11/D25).
+// v1's PreToolUse muzzle + bash-guard are gone (D1/D13); the merge still STRIPS any
+// leftover PreToolUse entry from an older install, it just no longer adds one. Two
+// command forms:
 //   global       — a direct absolute path to the +x copy under ~/.claude.
 //   self (viaSh) — `sh "<dir>/<file>"` against the package's hooks/ under
 //                  node_modules, addressed through `$CLAUDE_PROJECT_DIR` so the
 //                  committed/portable form carries no machine-absolute path and
 //                  needs no execute bit (pnpm's store may not preserve one).
-// Mirrors the PreToolUse/PostToolUse shape dev-install wrote.
 function registrationEntries(hooksDir, viaSh) {
     const dir = hooksDir.endsWith('/') ? hooksDir.slice(0, -1) : hooksDir;
     const command = (file) => (viaSh ? `sh "${dir}/${file}"` : `${dir}/${file}`);
@@ -27,10 +30,7 @@ function registrationEntries(hooksDir, viaSh) {
         matcher,
         hooks: [{ type: 'command', command: command(file) }],
     });
-    return {
-        PreToolUse: [entry(EDIT_MATCHER, 'pre-edit.sh'), entry('Bash', 'bash-guard.sh')],
-        PostToolUse: [entry(EDIT_MATCHER, 'post-edit.sh')],
-    };
+    return { PostToolUse: [entry(EDIT_MATCHER, 'post-edit.sh')] };
 }
 function isOurs(entry) {
     return (entry.hooks ?? []).some((h) => h.command.includes(OURS_MARKER));
@@ -45,7 +45,11 @@ export function mergeRegistration(settings, hooksDir, viaSh = false) {
     const entries = registrationEntries(hooksDir, viaSh);
     const existing = settings.hooks ?? {};
     const hooks = { ...existing };
-    hooks.PreToolUse = [...stripOurs(existing.PreToolUse), ...entries.PreToolUse];
+    // Strip any leftover v1 PreToolUse muzzle/bash-guard from an older install, but
+    // add back only the PostToolUse feedback hook — v2 registers no PreToolUse.
+    if (existing.PreToolUse !== undefined) {
+        hooks.PreToolUse = stripOurs(existing.PreToolUse);
+    }
     hooks.PostToolUse = [...stripOurs(existing.PostToolUse), ...entries.PostToolUse];
     return { ...settings, hooks };
 }

package/dist/lib/sidecar.js

@@ -5,9 +5,6 @@ import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs
 import { join } from 'node:path';
 import { gitDir } from "./git.js";
 const DIRNAME = '.plumbbob';
-// The five legal control states (README mode machine). `mode` validates against
-// this; the muzzle allows edits iff STATE is BUILD or SPIKE.
-export const VALID_STATES = ['DESIGN', 'BUILD', 'REVIEW', 'SPIKE', 'FINISH'];
 export function sidecarDir(root) {
     return join(root, DIRNAME);
 }

package/dist/verbs/build.js

@@ -25,6 +25,6 @@ export function build(cwd, args) {
     writeFileSync(seamPath(root), `${parsed.seam.join('\n')}\n`);
     writeFileSync(stepPath(root), `${step}\n`);
     writeState(root, 'BUILD');
-    process.stdout.write(`plumbbob: building step ${step} — STATE=BUILD. Edits are limited to the seam:\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
+    process.stdout.write(`plumbbob: building step ${step} — STATE=BUILD. Seam (for orientation; not a lock in v2):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
 }