plumbbob 0.4.4 → 0.4.11

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
-  "displayName": "Plumbbob",
-  "version": "0.4.4",
+  "displayName": "PlumbBob",
+  "version": "0.4.11",
   "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",

package/README.md

@@ -1,4 +1,4 @@
-# Plumbbob
+# PlumbBob
 
 <p align="center">
   <img src="hero.jpg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
@@ -66,55 +66,55 @@ and it cannot be skipped.
 
 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.
+every move, and `/plumbbob:pb-status` always names your next one.
 
 | Skill | Does |
 |-------|------|
-| `/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
+| `/plumbbob:pb-plan` | plan the whole goal — scaffold the session + author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/plumbbob:pb-step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
+| `/plumbbob:pb-build` | *(optional)* implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done |
+| `/plumbbob:pb-verify` | the tick — check → self-review → validate → **PAUSE** → checkpoint |
+| `/plumbbob:pb-park` | capture an idea without chasing it |
+| `/plumbbob:pb-status` | orient — where you are, the next step's done-when + seam, and the next move |
+| `/plumbbob:pb-harvest` | triage parked ideas at a boundary (blocker / tangent / pivot) |
+| `/plumbbob:pb-wrap` | wrap up — write the report, archive safely, clear for a fresh goal |
+
+Three optional power moves survive for when you need them: `/plumbbob:pb-revert` (recover to
+a checkpoint), `/plumbbob:pb-spike` (throwaway worktree experiment), and `/plumbbob:pb-refine` (attack
 the frame for holes, or repair the plan when it drifts — usable at any point).
 
 ## The loop
 
-The happy path is **plan the whole thing up front, then drive `/plumbbob:build` until
+The happy path is **plan the whole thing up front, then drive `/plumbbob:pb-build` until
 done** — approving each step at its verify pause:
 
 ```text
-/plumbbob:plan                      author the whole plan (incl. all steps)   (once)
+/plumbbob:pb-plan                      author the whole plan (incl. all steps)   (once)
   └ per step:
-       /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)
+       /plumbbob:pb-status             review the next step (done-when + seam)
+       /plumbbob:pb-step   (optional)  sharpen/revise it first if needed
+       /plumbbob:pb-build  (or DIY)    implement it → verify → PAUSE → checkpoint
+       /plumbbob:pb-park               capture strays mid-build
+       /plumbbob:pb-harvest            triage them at a boundary
+  /plumbbob:pb-wrap                    report + archive + clear                  (once)
 ```
 
-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
+Each `/plumbbob:pb-build` builds the next undone step and stops at the pause for your
+approval — re-firing it is itself the clock tick. (`/plumbbob:pb-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
+**Three ways to plan.** `/plumbbob:pb-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
+**The pluggable executor.** `/plumbbob: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 `/plumbbob:verify` instead: it reads the *diff, not the author*. Plumbbob is the
+and run `/plumbbob: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.
 
 ## Calibration: size everything to the work
@@ -123,7 +123,7 @@ 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
+- **Small** (a contained bug/change): `/plumbbob:pb-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.
@@ -134,15 +134,16 @@ Calibration is the skill. When in doubt, smaller.
 
 - 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.
+  it by hand (beyond `plumbbob --help` and `plumbbob --version`). The marketplace
+  plugin carries it on PATH via `bin/` shims; `npm i -g` installs it globally.
 - 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/`.
+- A `.plumbbob/` sidecar of flat files: `STATE` (the session sentinel — its presence
+  means a session is live), `intent.md`, `build-log.md`, `checkpoints`, and `archive/`.
 
 ## Gates — two tiers, different jobs
 
@@ -150,17 +151,19 @@ Calibration is the skill. When in doubt, smaller.
   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
+  markdownlint). Not a hook: it runs *inside* `/plumbbob:pb-verify`, which refuses to
   checkpoint while red. The hard gate lives on the deliberate boundary, not the
   keystroke.
 
-## STATE is orientation, not a gate
+## Position is derived, not stored
 
-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.
+There is no stored state machine. The dashboard's phase — `DESIGN`, `BUILD`, or `SPIKE` —
+is *derived* from what's on disk: a `STEP` file means a step is in flight (BUILD), the
+`SPIKE` marker means a fork is open (SPIKE), otherwise you're at a boundary (DESIGN). The
+position gates nothing — it's a label on a map, read by `/plumbbob:pb-status` to tell you
+where you are and what to do next, never a locked door. `.plumbbob/STATE` is just the
+session sentinel: its presence means a session is live, and the post-edit hook is gated on
+it, so a repo with no `.plumbbob/STATE` behaves exactly like plain Claude Code.
 
 ## Git footprint — additive only
 
@@ -174,10 +177,12 @@ archives plain markdown under `.plumbbob/archive/` and never touches git.
 
 ```text
 .plumbbob/
-  STATE          # one word: DESIGN | BUILD | SPIKE — orientation, not a gate
+  STATE          # session sentinel — its presence means a session is live
   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
+  STEP           # the in-flight step number (its presence is the BUILD phase)
+  SPIKE          # marker — present while a spike fork is open
+  config         # key=value; check=<heavy-check command> (defaults to pnpm run check)
+  checkpoints    # "baseline <sha>" then "step N <sha>", one per verified step
   intent.md      # canonical intent
   build-log.md   # live ledger
   archive/
@@ -189,24 +194,34 @@ archives plain markdown under `.plumbbob/archive/` and never touches git.
 
 ## Install
 
-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.
+Plumbbob installs **once, globally** — like `gh` or your dotfiles. There are two co-equal,
+mutually-exclusive ways to do it (both register a Claude Code plugin named `plumbbob`;
+running both collides over the `/plumbbob:*` namespace).
+
+**npm global + `init`** — the npm package ships the CLI, the skills, and the hook; `plumbbob
+init` links them into Claude Code as an in-place plugin:
 
 ```sh
 npm i -g plumbbob      # the CLI (also a `pb` shorthand)
 plumbbob init          # link it into Claude Code; --uninstall to undo
 ```
 
-`init` symlinks the package into `~/.claude/skills/plumbbob`, where Claude Code
-loads it as a plugin. Claude Code namespaces a plugin's skills as
-`/plumbbob:<skill>`, so they appear as `/plumbbob:plan`, `/plumbbob:status`, and the
-rest — already clear of built-in and other-plugin commands, no prefix needed. 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.
+`init` symlinks the package into `~/.claude/skills/plumbbob`, where Claude Code loads it as a
+plugin; the post-edit hook auto-registers from `hooks.json`. Because it's a symlink, a later
+`npm i -g plumbbob@latest` stays live with no re-link.
+
+**The marketplace plugin** — self-contained: it ships the skills *and* the `plumbbob`/`pb`
+CLI on PATH (via its `bin/` shims), so it needs neither `npm i -g` nor `plumbbob init`:
+
+```text
+/plugin install plumbbob@<marketplace>
+```
+
+Either way, Claude Code namespaces the skills as `/plumbbob:<skill>`, so they appear as
+`/plumbbob:pb-plan`, `/plumbbob:pb-status`, and the rest. Nothing else under `~` is touched
+and `settings.json` is left alone — restart Claude Code (or `/reload-plugins`) to activate.
+If a marketplace plumbbob is already installed, `plumbbob init` refuses rather than create
+the collision (`--force` overrides), and `plumbbob doctor` flags a double-install.
 
 **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
@@ -222,10 +237,13 @@ look. Claude Code is the first, first-class target.
 plumbbob doctor
 ```
 
-`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.
+`doctor` works for either install path: it confirms a marketplace plugin, or checks that the
+skills-dir link resolves to the plugin manifest, the skills, and the hook — flagging a
+double-install collision — and prints the exact fix for anything broken. The terminal command
+above is for the **global / skills-dir** install; a **marketplace** plugin puts the CLI on
+PATH only *inside a Claude Code session*, so run **`/plumbbob:pb-doctor`** there instead. Run
+it first if a `/plumbbob:*` skill ever opens with an empty dashboard;
+[`docs/troubleshooting.md`](docs/troubleshooting.md) covers the rest.
 
 ## Development
 

package/bin/pb

@@ -0,0 +1,15 @@
+#!/bin/sh
+# pb — short alias for `plumbbob` (see bin/plumbbob for the full note). Same dual
+# role: the npm `bin` entry for `pb` (so npm ships it 0755) and the plugin PATH shim.
+# Resolves any symlink chain so it works on PATH, globally linked, or as a dep.
+src=$0
+while [ -h "$src" ]; do
+  dir=$(CDPATH='' cd -- "$(dirname -- "$src")" && pwd)
+  link=$(readlink -- "$src")
+  case $link in
+    /*) src=$link ;;
+    *)  src=$dir/$link ;;
+  esac
+done
+here=$(CDPATH='' cd -- "$(dirname -- "$src")" && pwd)
+exec node "$here/../dist/cli.js" "$@"

package/bin/plumbbob

@@ -0,0 +1,26 @@
+#!/bin/sh
+# plumbbob — the package's `bin` entry AND the marketplace/plugin PATH shim.
+#
+# Pointing the npm `bin` at THIS file (not dist/cli.js) is deliberate: npm/pacote
+# rewrites every packed file to 0644 except the ones named in `bin`, which it stamps
+# 0755 — regardless of the mode in git. Claude Code adds this bin/ dir to the Bash
+# tool's PATH while the plugin is enabled, so the shim must arrive executable; naming
+# it in `bin` is what carries the +x bit through an npm-sourced plugin install.
+# (dist/cli.js no longer needs its own bit — it is always run as `node` below.)
+#
+# As the npm bin, this file is also symlinked into a bin dir by `npm i -g` and by a
+# local node_modules/.bin dep, so $0 can reach us through one or more symlinks.
+# Resolve the chain to the real file, then run the bundled CLI relative to it — so it
+# works on PATH (plugin), globally linked, and as a dep. Requires node >=22 on PATH
+# (same as dist/cli.js's shebang).
+src=$0
+while [ -h "$src" ]; do
+  dir=$(CDPATH='' cd -- "$(dirname -- "$src")" && pwd)
+  link=$(readlink -- "$src")
+  case $link in
+    /*) src=$link ;;
+    *)  src=$dir/$link ;;
+  esac
+done
+here=$(CDPATH='' cd -- "$(dirname -- "$src")" && pwd)
+exec node "$here/../dist/cli.js" "$@"

package/dist/cli-core.js

@@ -2,6 +2,8 @@
 // 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 { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { start } from "./verbs/start.js";
 import { status } from "./verbs/status.js";
 import { park } from "./verbs/park.js";
@@ -14,15 +16,15 @@ 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: 'start', summary: 'scaffold .plumbbob/; open the session; record the baseline commit' },
+    { name: 'status', summary: 'print the orientation dashboard, or NO ACTIVE SESSION' },
+    { name: 'build', summary: 'build <n>: write the seam from step n (in-flight, 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: 'checkpoint', summary: 'checkpoint [<n>]: gate on green, commit/record SHA, mark step done (executor-agnostic)' },
+    { name: 'revert', summary: 'revert [--to n]: git reset --hard to a checkpoint SHA' },
     { 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: 'wrap', summary: 'v2 close-out: archive intent+log+report (no gate), clear the sidecar, close the session' },
     { 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' },
 ];
@@ -36,6 +38,19 @@ export function formatHelp() {
     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.
+export function readVersion() {
+    try {
+        const raw = readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8');
+        return JSON.parse(raw).version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 function dispatch(verb, cwd, rest) {
     switch (verb) {
         case 'start':
@@ -72,6 +87,10 @@ export function run(argv) {
         process.stdout.write(`${formatHelp()}\n`);
         return 0;
     }
+    if (verb === 'version' || verb === '--version' || verb === '-v') {
+        process.stdout.write(`plumbbob ${readVersion()}\n`);
+        return 0;
+    }
     try {
         return dispatch(verb, process.cwd(), rest);
     }

package/dist/lib/buildlog.js

@@ -0,0 +1,34 @@
+// Mutations to the active build-log.md — the human-facing ledger. `park` appends to
+// its Park list; `checkpoint` appends to its Log so the build's history accrues
+// line-by-line *as it happens* rather than being reconstructed at wrap (D-history).
+// Pure string transforms (no fs, no classes — C1/C2); callers own the IO so these
+// stay trivially testable.
+// Append `line` after the last non-blank line of the `## <heading>` section — i.e.
+// just before the next `## ` heading or EOF. Returns null when the section is absent
+// so the caller can report rather than silently corrupt the doc.
+export function appendToSection(content, heading, line) {
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((l) => l.trim() === `## ${heading}`);
+    if (headingIdx === -1) {
+        return null;
+    }
+    let nextSection = lines.findIndex((l, i) => i > headingIdx && l.startsWith('## '));
+    if (nextSection === -1) {
+        nextSection = lines.length;
+    }
+    let insertAt = headingIdx + 1;
+    for (let i = headingIdx + 1; i < nextSection; i++) {
+        if ((lines[i] ?? '').trim() !== '') {
+            insertAt = i + 1;
+        }
+    }
+    lines.splice(insertAt, 0, line);
+    return lines.join('\n');
+}
+// The Log line `checkpoint` writes for a landed step: dated, names the step (its
+// title when intent.md still carries it), and carries the short SHA. One line of the
+// build's history — `/plumbbob:pb-wrap` reads these instead of re-narrating the build.
+export function checkpointLogLine(date, step, sha, title) {
+    const head = `- ${date} — step ${step} checkpointed · ${sha.slice(0, 9)}`;
+    return title !== null && title.length > 0 ? `${head} — ${title}` : head;
+}

package/dist/lib/orient.js

@@ -77,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 `/plumbbob:harvest` and no longer counts; the
+// A harvested item is flipped to `- [x]` by `/plumbbob: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;
@@ -93,52 +93,45 @@ export function parseLastCheckpoint(checkpoints) {
     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 — `/plumbbob:wrap`';
-        case 'REVIEW':
-            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 — `/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 — `/plumbbob:step`';
-                }
-                // 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} — \`/plumbbob:build\` (or \`/plumbbob:step\` to revise it first)`
-                : `plan step ${nextUndone.n} — \`/plumbbob:step\``;
+// list + counts so the human can always override. The phase is derived: a spike
+// in progress and an in-flight step each have one obvious next move; otherwise you
+// are at the boundary and the move follows from the steps.
+function nextMove(spiking, steps, inFlight, parked) {
+    if (spiking) {
+        return 'close the spike — `plumbbob spike done`';
+    }
+    if (inFlight !== null) {
+        return `finish step ${inFlight} — \`/plumbbob:pb-verify\` (or keep editing, then \`/plumbbob:pb-verify\`)`;
+    }
+    // At the boundary (DESIGN): the move follows from the steps.
+    const nextUndone = steps.find((s) => !s.done);
+    if (nextUndone === undefined) {
+        if (steps.length === 0) {
+            return 'plan the first step — `/plumbbob:pb-step`';
         }
+        // Batch-default: the steps were planned up front, so finishing them usually
+        // means "wrap up" — but `/plumbbob:pb-step` can still add an increment if reality grew.
+        const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/plumbbob:pb-harvest\`; then ` : '';
+        return `${harvest}wrap up — \`/plumbbob:pb-wrap\` (or \`/plumbbob:pb-step\` to add another increment)`;
     }
+    return nextUndone.planned
+        ? `build step ${nextUndone.n} — \`/plumbbob:pb-build\` (or \`/plumbbob:pb-step\` to revise it first)`
+        : `plan step ${nextUndone.n} — \`/plumbbob:pb-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);
+    const phase = input.spiking ? 'SPIKE' : input.inFlight !== null ? 'BUILD' : 'DESIGN';
     return {
         title: parseTitle(input.intent),
-        state: input.state,
+        phase,
         steps,
         lastCheckpoint: parseLastCheckpoint(input.checkpoints),
         parked,
         openQuestions: parseOpenQuestions(input.intent),
-        next: nextMove(input.state, steps, input.inFlight, parked),
+        next: nextMove(input.spiking, steps, input.inFlight, parked),
         nextDoneWhen: nextUndone?.doneWhen ?? null,
         nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
     };
@@ -153,7 +146,7 @@ export function formatOrientation(o) {
         if (s !== nextUndone) {
             return head;
         }
-        // Surface the next step's detail so the human can review it (and `/plumbbob:step`-
+        // Surface the next step's detail so the human can review it (and `/plumbbob:pb-step`-
         // revise) before building. Only what's present — a rough step shows neither.
         const detail = [];
         if (o.nextDoneWhen !== null) {
@@ -168,7 +161,7 @@ export function formatOrientation(o) {
     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}]`,
+        `Plumbbob — ${o.title ?? '(untitled)'}   [${o.phase}]`,
         '',
         stepsBlock,
         '',

package/dist/lib/plugins.js

@@ -0,0 +1,24 @@
+// Detect a marketplace-installed plumbbob plugin from Claude Code's plugin state.
+// Used to keep the skills-dir install (`plumbbob init`) from colliding with a
+// marketplace install: two plugins both named `plumbbob` fight over the
+// `/plumbbob:*` namespace and the skills can drop to flat names (`/pb-status`).
+// Read-only, node builtins only (C1/C2): a missing / unreadable / malformed file
+// means "none installed".
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// Marketplace plugin ids for plumbbob recorded in installed_plugins.json
+// (e.g. "plumbbob@robmclarty"). Empty when none, or the file is absent/unreadable.
+// `plumbbob@<marketplace>` matches; `plumbbob-spike@x` and the like do not.
+export function marketplacePlumbbob(home) {
+    try {
+        const raw = readFileSync(join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+        const plugins = JSON.parse(raw).plugins;
+        if (plugins === undefined || plugins === null) {
+            return [];
+        }
+        return Object.keys(plugins).filter((id) => id === 'plumbbob' || id.startsWith('plumbbob@'));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/sidecar.js

@@ -1,7 +1,12 @@
 // The .plumbbob/ sidecar: control state lives in flat files so the hooks can
 // read it with a grep and no markdown parsing (D7). Functional/procedural,
 // node builtins only (C1/C2).
-import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+//
+// STATE is a pure session sentinel: its EXISTENCE means "a session is active",
+// and nothing reads its content. The phase the dashboard shows (DESIGN/BUILD/
+// SPIKE) is derived, not stored — BUILD ⇔ a STEP is in flight, SPIKE ⇔ the SPIKE
+// marker is present, otherwise DESIGN.
+import { existsSync, readFileSync, writeFileSync, appendFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { gitDir } from "./git.js";
 const DIRNAME = '.plumbbob';
@@ -11,6 +16,12 @@ export function sidecarDir(root) {
 function statePath(root) {
     return join(root, DIRNAME, 'STATE');
 }
+// The SPIKE marker (a single-purpose presence flag, like SEAM/STEP): written by
+// `spike` on open, removed on `spike done`. Its existence is the one signal that
+// the dashboard and the spike gates read to know "a spike is active".
+export function spikePath(root) {
+    return join(root, DIRNAME, 'SPIKE');
+}
 // SEAM and STEP carry the in-flight step (D4/D7): a plain path list and a bare
 // number, so the hooks read them with a grep and no markdown parsing.
 export function seamPath(root) {
@@ -31,21 +42,24 @@ export function intentPath(root) {
 export function buildLogPath(root) {
     return join(root, DIRNAME, 'build-log.md');
 }
-// A session exists iff STATE exists. Deleting STATE (at finish) is what switches
-// the muzzle off — so it is the single source of truth for "is there a session".
+// A session exists iff STATE exists. Deleting STATE (at wrap) is what flips the
+// repo back to "no session" — so it is the single source of truth for "is there
+// a session". `start` calls beginSession; `wrap` removes the file.
 export function hasSession(root) {
     return existsSync(statePath(root));
 }
-export function readState(root) {
-    try {
-        return readFileSync(statePath(root), 'utf8').trim();
-    }
-    catch {
-        return null;
-    }
+export function beginSession(root) {
+    writeFileSync(statePath(root), 'active\n');
+}
+// SPIKE marker helpers — existence is the whole signal (content is irrelevant).
+export function inSpike(root) {
+    return existsSync(spikePath(root));
+}
+export function markSpike(root) {
+    writeFileSync(spikePath(root), 'active\n');
 }
-export function writeState(root, state) {
-    writeFileSync(statePath(root), `${state}\n`);
+export function clearSpike(root) {
+    rmSync(spikePath(root), { force: true });
 }
 // D17: keep the sidecar untracked by appending `.plumbbob/` to the repo's
 // git/info/exclude. Idempotent — a re-`start` after finish must not double-add.

package/dist/verbs/build.js

@@ -1,9 +1,9 @@
 // `plumbbob build <n>` — read step n's seam from intent.md, write the normalized
-// SEAM + STEP, and enter BUILD. Re-entering from REVIEW just re-derives the same
-// seam and flips back to BUILD; it never checkpoints (only `done` commits).
+// SEAM + STEP. The STEP file is the in-flight signal (the dashboard derives the
+// BUILD phase from it); it never checkpoints (only `checkpoint` commits).
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, intentPath, seamPath, stepPath, writeState } from "../lib/sidecar.js";
+import { hasSession, intentPath, seamPath, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -24,7 +24,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. Seam (for orientation; not a lock in v2):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
+    process.stdout.write(`plumbbob: building step ${step}. Seam (for orientation; not a lock in v2):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
 }

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: `/plumbbob:verify` runs this before the
+// change. The read-only half of the verify tick: `/plumbbob:pb-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";