plumbbob 0.4.8 → 0.4.11

package/.claude-plugin/plugin.json

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

@@ -142,8 +142,8 @@ Calibration is the skill. When in doubt, smaller.
   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
 
@@ -155,13 +155,15 @@ Calibration is the skill. When in doubt, smaller.
   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:pb-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
 
@@ -175,9 +177,10 @@ 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
+  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
@@ -236,8 +239,10 @@ plumbbob doctor
 
 `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. Run it first if a
-`/plumbbob:*` skill ever opens with an empty dashboard;
+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

@@ -1,6 +1,15 @@
 #!/bin/sh
-# pb — short alias for `plumbbob` (see bin/plumbbob for the full note). Same PATH
-# shim: resolves the bundled CLI relative to this file so the plugin works on PATH
-# without a global install.
-here=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+# 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

@@ -1,9 +1,26 @@
 #!/bin/sh
-# plumbbob — PATH shim for the marketplace / plugin install. Claude Code adds this
-# bin/ dir to the Bash tool's PATH while the plugin is enabled (the plugins `bin/`
-# convention), so the driver skills can shell a bare `plumbbob` without a global
-# `npm i -g`. The CLI is resolved relative to this file, so it works from the
-# plugin's install/cache dir wherever that lands. Requires node >=22 on PATH (the
-# same requirement as the published `bin`/`dist/cli.js` shebang).
-here=$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)
+# 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

@@ -16,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' },
 ];

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

@@ -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:pb-wrap`';
-        case 'REVIEW':
-            return 'read the diff cold against intent, then `/plumbbob:pb-verify`';
-        case 'BUILD': {
-            const n = inFlight ?? steps.find((s) => !s.done)?.n;
-            return n === undefined
-                ? 'finish the step in flight — `/plumbbob:pb-verify`'
-                : `finish step ${n} — \`/plumbbob:pb-verify\` (or keep editing, then \`/plumbbob: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 — `/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\``;
+// 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 : [],
     };
@@ -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/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/checkpoint.js

@@ -1,16 +1,18 @@
 // `plumbbob checkpoint [<n>] [-m <msg>]` — the executor-agnostic commit tick (D3).
-// Unlike v1 `done`, it does NOT require BUILD state or a STEP file: the step is
-// whatever you pass, else the in-flight STEP, else the next undone step in intent.
-// 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: `/plumbbob:pb-build`, your hands,
-// a vibe session, or another harness all checkpoint the same way.
+// Unlike v1 `done`, it does NOT require a STEP file: the step is whatever you pass,
+// else the in-flight STEP, else the next undone step in intent. 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]`, and clears any STEP/SEAM (which returns
+// the dashboard to the DESIGN boundary). The diff's author is irrelevant:
+// `/plumbbob:pb-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";
-import { checkpointsPath, hasSession, intentPath, seamPath, stepPath, writeState } from "../lib/sidecar.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, stepPath } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { markStepDone, parseSteps } from "../lib/orient.js";
+import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
 export function checkpoint(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -36,10 +38,10 @@ export function checkpoint(cwd, args) {
     }
     appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
     flipIntent(root, step);
+    logCheckpoint(root, step, sha);
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
-    writeState(root, 'DESIGN');
-    process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. STATE=DESIGN.\n`);
+    process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
     return 0;
 }
 // Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
@@ -68,6 +70,32 @@ function flipIntent(root, step) {
         // best-effort bookkeeping; the checkpoint SHA is the source of truth.
     }
 }
+// Append a dated line to the build-log's `## Log` so the build's history accrues at
+// each checkpoint instead of being reconstructed at wrap. The step's title is lifted
+// from intent.md when still present. Best-effort: a missing/odd build-log never blocks
+// a checkpoint — the `checkpoints` SHA is the source of truth.
+function logCheckpoint(root, step, sha) {
+    try {
+        const path = buildLogPath(root);
+        const date = new Date().toISOString().slice(0, 10);
+        const line = checkpointLogLine(date, step, sha, titleForStep(root, step));
+        const updated = appendToSection(readFileSync(path, 'utf8'), 'Log', line);
+        if (updated !== null) {
+            writeFileSync(path, updated);
+        }
+    }
+    catch {
+        // best-effort ledger; never fail a checkpoint over the build-log.
+    }
+}
+function titleForStep(root, step) {
+    try {
+        return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.title ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function messageArg(args) {
     const i = args.indexOf('-m');
     return i !== -1 && i + 1 < args.length ? (args[i + 1] ?? null) : null;

package/dist/verbs/doctor.js

@@ -86,7 +86,7 @@ export function doctor() {
     out.push(failed === 0
         ? 'plumbbob: all checks passed. If a skill still misbehaves, restart Claude Code (or /reload-plugins).'
         : `plumbbob: ${failed} problem(s) — apply the → fixes, then restart Claude Code.`);
-    out.push('plumbbob: skills shell a bare `plumbbob`. The marketplace plugin puts it on PATH via bin/; for the skills-dir/global install run `npm i -g plumbbob`. Sessions are per-project via `plumbbob start`.');
+    out.push('plumbbob: skills shell a bare `plumbbob`. The marketplace plugin puts it on PATH only inside a Claude Code session (via bin/) — there is no terminal `plumbbob`; for one (or the skills-dir install) run `npm i -g plumbbob`. In-session you can also run this as `/plumbbob:pb-doctor`. Sessions are per-project via `plumbbob start`.');
     process.stdout.write(`${out.join('\n')}\n`);
     return failed === 0 ? 0 : 1;
 }

package/dist/verbs/park.js

@@ -4,6 +4,7 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, buildLogPath } from "../lib/sidecar.js";
+import { appendToSection } from "../lib/buildlog.js";
 export function park(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -19,7 +20,7 @@ export function park(cwd, args) {
         return 1;
     }
     const path = buildLogPath(root);
-    const updated = insertParkItem(readFileSync(path, 'utf8'), text);
+    const updated = appendToSection(readFileSync(path, 'utf8'), 'Park list', `- [ ] ${text}`);
     if (updated === null) {
         process.stderr.write('plumbbob: could not find a "## Park list" section in build-log.md.\n');
         return 1;
@@ -28,24 +29,3 @@ export function park(cwd, args) {
     process.stdout.write(`parked: ${text}\n`);
     return 0;
 }
-// Append after the last non-blank line of the Park list section (i.e. just before
-// the next `## ` heading). Returns null if there is no Park list to append to.
-function insertParkItem(content, text) {
-    const lines = content.split('\n');
-    const headingIdx = lines.findIndex((line) => line.trim() === '## Park list');
-    if (headingIdx === -1) {
-        return null;
-    }
-    let nextSection = lines.findIndex((line, i) => i > headingIdx && line.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, `- [ ] ${text}`);
-    return lines.join('\n');
-}

package/dist/verbs/revert.js

@@ -13,7 +13,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findRepoRoot, resetHard, untrackedPaths } from "../lib/git.js";
-import { checkpointsPath, hasSession, seamPath, sidecarDir, stepPath, writeState } from "../lib/sidecar.js";
+import { checkpointsPath, hasSession, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
 import { matchesSeam } from "../lib/intent.js";
 export function revert(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -53,8 +53,7 @@ export function revert(cwd, args) {
     }
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
-    writeState(root, 'DESIGN');
-    process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — STATE=DESIGN. Park lines and intent edits were preserved.\n`);
+    process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — back at the boundary. Park lines and intent edits were preserved.\n`);
     return 0;
 }
 // The repo paths that belong to plumbbob, not to the work being reverted: the

package/dist/verbs/spike.js

@@ -1,10 +1,10 @@
 // `plumbbob spike` (D18) — the spike lifecycle for a genuine fork the design
 // phase couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree +
 // `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default opts a/b)
-// and sets STATE=SPIKE; the main tree stays DESIGN-locked while you experiment in
-// the worktrees, which are hook-dormant by construction — the untracked sidecar
-// (D17) doesn't exist in a fresh checkout, so the hooks find no STATE there.
-// `spike done` removes every spike worktree + branch and returns to DESIGN.
+// and drops the SPIKE marker; the main tree stays put while you experiment in the
+// worktrees, which are hook-dormant by construction — the untracked sidecar (D17)
+// doesn't exist in a fresh checkout, so the hooks find no STATE there.
+// `spike done` removes every spike worktree + branch and clears the marker.
 //
 // Worktree git calls run directly here rather than via lib/git.ts (which holds the
 // shared additive read/commit helpers): worktree management is spike-local, and
@@ -13,7 +13,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, readState, writeState } from "../lib/sidecar.js";
+import { hasSession, inSpike, markSpike, clearSpike, stepPath } from "../lib/sidecar.js";
 const DEFAULT_OPTIONS = ['a', 'b'];
 export function spike(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -28,14 +28,13 @@ export function spike(cwd, args) {
     return spikeStart(root, positionals);
 }
 function spikeStart(root, positionals) {
-    const state = readState(root);
-    if (state === 'SPIKE') {
+    if (inSpike(root)) {
         process.stderr.write('plumbbob: already in a spike. Run `plumbbob spike done` to close it first.\n');
         return 1;
     }
-    if (state !== 'DESIGN') {
-        process.stderr.write(`plumbbob: spike starts from DESIGN (current state is ${state ?? 'UNKNOWN'}). ` +
-            'A spike is a deliberate fork — close the current step first with `done`.\n');
+    if (existsSync(stepPath(root))) {
+        process.stderr.write('plumbbob: spike starts from a settled boundary, but a step is in flight. ' +
+            'A spike is a deliberate fork — checkpoint or revert the current step first.\n');
         return 1;
     }
     const slug = sanitize(positionals[0] ?? '');
@@ -55,16 +54,15 @@ function spikeStart(root, positionals) {
         git(root, ['worktree', 'add', '-b', `spike/${slug}-${opt}`, path, 'HEAD']);
         created.push(path);
     }
-    writeState(root, 'SPIKE');
-    process.stdout.write(`plumbbob: STATE=SPIKE — the main tree stays DESIGN-locked. Experiment in the throwaway worktrees:\n${created
+    markSpike(root);
+    process.stdout.write(`plumbbob: spiking — the main tree stays put. Experiment in the throwaway worktrees:\n${created
         .map((p) => `  ${p}`)
         .join('\n')}\nWhen you've decided, record the verdict in intent.md and run \`plumbbob spike done\`.\n`);
     return 0;
 }
 function spikeDone(root) {
-    const state = readState(root);
-    if (state !== 'SPIKE') {
-        process.stderr.write(`plumbbob: no active spike (state is ${state ?? 'UNKNOWN'}).\n`);
+    if (!inSpike(root)) {
+        process.stderr.write('plumbbob: no active spike to close.\n');
         return 1;
     }
     for (const path of spikeWorktrees(root)) {
@@ -74,8 +72,8 @@ function spikeDone(root) {
     for (const branch of spikeBranches(root)) {
         git(root, ['branch', '-D', branch]);
     }
-    writeState(root, 'DESIGN');
-    process.stdout.write('plumbbob: spike closed — STATE=DESIGN, worktrees and branches removed. ' +
+    clearSpike(root);
+    process.stdout.write('plumbbob: spike closed — worktrees and branches removed, back at the boundary. ' +
         'Record the verdict (which option won, and why) in intent.md before you `build`.\n');
     return 0;
 }

package/dist/verbs/start.js

@@ -1,10 +1,10 @@
-// `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, enter
-// DESIGN. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
+// `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, open
+// the session. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
 import { fileURLToPath } from 'node:url';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
-import { sidecarDir, checkpointsPath, configPath, intentPath, buildLogPath, writeState, hasSession, excludeSidecar, } from "../lib/sidecar.js";
+import { sidecarDir, checkpointsPath, configPath, intentPath, buildLogPath, beginSession, hasSession, excludeSidecar, } from "../lib/sidecar.js";
 const DEFAULT_CHECK = 'pnpm run check';
 export function start(cwd, args) {
     const positionals = args.filter((a) => !a.startsWith('--'));
@@ -37,7 +37,7 @@ export function start(cwd, args) {
     const sha = headSha(root);
     const check = detectCheck(root);
     mkdirSync(sidecarDir(root), { recursive: true });
-    writeState(root, 'DESIGN');
+    beginSession(root);
     writeFileSync(checkpointsPath(root), `baseline ${sha}\n`);
     writeFileSync(configPath(root), `check=${check.command}\n`);
     writeFileSync(intentPath(root), stamp(readTemplate('intent.md'), title, check.command));
@@ -46,7 +46,7 @@ export function start(cwd, args) {
     if (check.warn) {
         process.stderr.write(`plumbbob: WARNING the heavy check '${check.command}' is not defined in this repo's package.json. Edit .plumbbob/config (check=...) to set the real gate before \`review\`/\`done\`.\n`);
     }
-    process.stdout.write(`plumbbob: started "${title}" — STATE=DESIGN, baseline ${sha.slice(0, 9)}. Frame and decide in .plumbbob/intent.md; flip to BUILD only once the decisions are made.\n`);
+    process.stdout.write(`plumbbob: started "${title}" — baseline ${sha.slice(0, 9)}. Frame and decide in .plumbbob/intent.md; \`build\` a step once the decisions are made.\n`);
     return 0;
 }
 // D24: default the heavy check to `pnpm run check`; warn (but still record it)

package/dist/verbs/status.js

@@ -3,7 +3,7 @@
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
 import { readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, intentPath, readState, stepPath } from "../lib/sidecar.js";
+import { buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, stepPath } from "../lib/sidecar.js";
 import { formatOrientation, orient } from "../lib/orient.js";
 function readOr(path) {
     try {
@@ -21,11 +21,11 @@ export function status(cwd) {
     }
     const inFlightRaw = readOr(stepPath(root)).trim();
     const orientation = orient({
-        state: readState(root) ?? 'UNKNOWN',
         intent: readOr(intentPath(root)),
         buildLog: readOr(buildLogPath(root)),
         checkpoints: readOr(checkpointsPath(root)),
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
+        spiking: inSpike(root),
     });
     process.stdout.write(`${formatOrientation(orientation)}\n`);
     return 0;

package/dist/verbs/wrap.js

@@ -7,7 +7,7 @@
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, spikePath, stepPath } from "../lib/sidecar.js";
 import { archiveSession, reportPath } from "../lib/archive.js";
 export function wrap(cwd) {
     const root = findRepoRoot(cwd);
@@ -30,6 +30,7 @@ export function wrap(cwd) {
     rmSync(reportPath(root), { force: true });
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
+    rmSync(spikePath(root), { force: true });
     rmSync(join(sidecarDir(root), 'STATE'), { force: true });
     process.stdout.write(`plumbbob: wrap — archived to ${relative(root, archived)}. Sidecar cleared. ` +
         'Run `/plumbbob:pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.4.8",
+  "version": "0.4.11",
   "description": "Attention-first build process: 11 skills + a CLI that keep you the decider — guidance, not enforcement.",
   "keywords": [
     "claude-code",
@@ -20,8 +20,8 @@
   "license": "Apache-2.0",
   "author": "Rob McLarty <hello@robmclarty.com>",
   "bin": {
-    "plumbbob": "dist/cli.js",
-    "pb": "dist/cli.js"
+    "plumbbob": "bin/plumbbob",
+    "pb": "bin/pb"
   },
   "files": [
     ".claude-plugin",

package/skills/pb-build/SKILL.md

@@ -40,8 +40,9 @@ at the pause for your approval. **Re-firing `/plumbbob:pb-build` is itself the c
    does: `plumbbob check` → self-review the diff against the done-when, the
    Decisions, and the Constraints (a single structured read, D16) → validate → **PAUSE
    for the human's approval** → only on approval, checkpoint with
-   `plumbbob checkpoint`. Do **not** bump the version or changelog — that is
-   the human's `/version` call.
+   `plumbbob checkpoint` (which also appends this step to the build-log's `## Log` — the
+   history writes itself at each checkpoint, so you don't hand-log it). Do **not** bump
+   the version or changelog — that is the human's `/version` call.
 
 ## `--auto` — let the agent be the clock (opt-in)
 

package/skills/pb-doctor/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pb-doctor
+description: Diagnose the plugin install from inside a session — is plumbbob linked, are the skills and hook present, is there a collision. A thin trigger for `plumbbob doctor`. Matters most for a marketplace install, where the CLI is on PATH only inside Claude Code.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(plumbbob doctor:*)
+---
+
+# Plumbbob — doctor (the is-it-installed-right move)
+
+Install diagnostic (injected when this skill runs): !`if command -v plumbbob >/dev/null 2>&1; then plumbbob doctor 2>&1; else echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."; fi`
+
+This is a **thin driver** for `plumbbob doctor`. The report above is read-only — `doctor`
+inspects, it never writes. This skill carries **no Edit and no Write tool**: never edit a file
+to change what the report says. If a check failed, surface its `→ fix` verbatim and apply
+*that* fix, then have the human **restart Claude Code (or `/reload-plugins`)**. **Never retry.**
+
+## Why a skill (and not just the terminal)
+
+The CLI's reach differs by install path, and that is the whole point of running `doctor` here:
+
+- **Marketplace plugin** — `plumbbob` is on PATH **only inside a Claude Code session** (its
+  `bin/` shims are injected into the Bash tool while the plugin is enabled). There is **no
+  terminal `plumbbob`** to run. So this skill — or letting me run `plumbbob doctor` in-session
+  — is the *only* way to reach `doctor`. The fact that this skill loaded at all already proves
+  the plugin is enabled and the shim is on PATH.
+- **Skills-dir / global install** (`npm i -g plumbbob` + `plumbbob init`) — `plumbbob` is on
+  PATH everywhere, so terminal `plumbbob doctor` works too; this skill is just convenience.
+
+The one failure `doctor` **cannot** diagnose: a plugin that never loaded at all (no
+`/plumbbob:*` skill appears). That is a `/plugin` / `/reload-plugins` problem, not doctor's —
+and if you are reading this, that is not your situation.
+
+## What it does
+
+1. Surface the injected `doctor` report verbatim — every `✓` and any `✗` with its `→ fix`.
+2. If all checks passed, say so; if a skill still misbehaves, the fix is a restart, not a re-run.
+3. If a check failed, apply its named `→ fix`, then restart Claude Code (or `/reload-plugins`).
+4. If the line above says the CLI is not on PATH, follow the install-path branch it printed.

package/skills/pb-harvest/SKILL.md

@@ -13,15 +13,16 @@ Current session state (injected when this skill runs): !`plumbbob status 2>/dev/
 `/plumbbob:pb-harvest` is the complement of `/plumbbob:pb-park` (D7): you parked ideas as seeds during a
 build; now, at a boundary, you harvest them — decide what each one is.
 
-## When to run it — wrong-state refusal
+## When to run it — boundary only
 
-Harvest at a **step boundary**: after a step is checkpointed and you are back in
-DESIGN, not mid-step. Read the state injected above:
+Harvest at a **step boundary**: after a step is checkpointed and you are back at the
+DESIGN boundary, not mid-step. Read the dashboard injected above:
 
 - `NO ACTIVE SESSION` — **refuse**; tell the human to `plumbbob start "<title>"` first.
-- `BUILD` — a step is in flight; **refuse** and suggest finishing it with `/plumbbob:pb-verify`
-  before harvesting. Chasing parked items mid-step is the disease parking prevents.
-- `DESIGN` (and other settled states) — go ahead.
+- A step in flight (the dashboard reads `[BUILD]`, and `next →` points at finishing the
+  step) — **refuse** and suggest finishing it with `/plumbbob:pb-verify` before harvesting.
+  Chasing parked items mid-step is the disease parking prevents.
+- At the boundary (the dashboard reads `[DESIGN]`) — go ahead.
 
 ## What this skill does
 

package/skills/pb-park/SKILL.md

@@ -16,10 +16,10 @@ it — is the whole point: it protects the step in flight.
 
 ## Wrong-state refusal
 
-Parking needs an **active session** to capture into. Read the state injected above: if
+Parking needs an **active session** to capture into. Read the dashboard injected above: if
 it is `NO ACTIVE SESSION`, **refuse** and tell the human to run `plumbbob start
-"<title>"` first. Every active state (`DESIGN`, `BUILD`, `SPIKE`, `FINISH`) is fine —
-capture is always available, which is the whole point of parking.
+"<title>"` first. Any time the session is live — at the boundary, mid-step, or in a spike —
+is fine; capture is always available, which is the whole point of parking.
 
 ## What this skill does
 

package/skills/pb-plan/SKILL.md

@@ -38,7 +38,7 @@ an agent can follow with `/plumbbob:pb-build`. The argument only seeds how you g
 ## What this skill does
 
 1. **Scaffold.** If there is no active session, run `plumbbob start "<title>"`
-   to create `.plumbbob/` (STATE=DESIGN, baseline recorded). If a session already
+   to create `.plumbbob/` (baseline recorded, session opened). If a session already
    exists, say so and edit the existing `intent.md` rather than starting over.
 2. **Frame** (`.plumbbob/intent.md`), with the human: the **Problem** in plain words,
    the **smallest thing** that solves it, what **done looks like**, and what you are

package/skills/pb-revert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pb-revert
-description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to DESIGN.
+description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to the boundary.
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob revert:*)

package/skills/pb-verify/SKILL.md

@@ -31,9 +31,9 @@ this skill verifies it the same way: **it reads the diff, not the author** (D3).
    the human is the clock. Never checkpoint without it.
 5. **Checkpoint** *(only after approval)*. Commit the work — the human's
    commit-with-TIL skill for a rich message, or let `checkpoint` make the WIP commit
-   — then run `plumbbob checkpoint` to record the SHA, flip the step to done,
-   and return to DESIGN. Do **not** bump the version or touch the changelog — that is
-   the human's `/version` call.
+   — then run `plumbbob checkpoint` to record the SHA, flip the step to done, append the
+   step to the build-log's `## Log`, and return to DESIGN. Do **not** bump the version or
+   touch the changelog — that is the human's `/version` call.
 
 ## The hard contracts
 

package/skills/pb-wrap/SKILL.md

@@ -16,9 +16,12 @@ and no separate docs phase.
 
 ## What this skill does, in order
 
-1. **Write the report** to `.plumbbob/report.md`, from `intent.md` + `build-log.md`:
-   - **What shipped** — the steps completed and what they delivered.
-   - **Decisions and why** — the settled calls that shaped the build.
+1. **Write the report** to `.plumbbob/report.md`, from `intent.md` + `build-log.md`.
+   The build-log's `## Log` is already the chronological history — `plumbbob checkpoint`
+   wrote a dated line for every step as it landed. **Read it as the spine; do not
+   re-narrate it.** The report adds only what the log does not already carry:
+   - **What shipped** — summarize from the `## Log` timeline; don't rebuild it step by step.
+   - **Decisions and why** — the settled calls that shaped the build (the *why* behind the log).
    - **Parked & harvested** — what was captured and how each was classified.
    - **Final status** — done or partial, and what is left.
    - **Deferred tangents** — the harvested items that become future work.
@@ -33,6 +36,9 @@ and no separate docs phase.
 
 - **Report by default, never a gate.** Always offer the report; never wall the exit. A
   bug fix's report can be three lines — size it to the work.
+- **The log is the history; the report is the synthesis.** `checkpoint` already recorded
+  what shipped, step by step — wrap applies the *unique additions* (the why, the deferred
+  tangents, the final status), it does not rewrite the timeline.
 - **Archive-then-clear, never destroy** (C4). The archive is the record; the active
   files only clear once they are safely copied.
 - **No version bump, no docs phase.** Updating real docs is a separate, explicit ask;

package/templates/build-log.md

@@ -5,12 +5,13 @@ step boundaries. The antidote to "my plan got lost in the noise."
   Steps     : where you are. One step in flight at a time.
   Park list : where ideas go so you do not chase them. CAPTURE, never act inline.
   Harvest   : the boundary ritual that keeps you on one branch.
-  Log       : the audit trail. Feeds the /plumbbob:pb-wrap report, then gets archived.
+  Log       : the build's history. `plumbbob checkpoint` appends a line per step as it
+              lands; feeds the /plumbbob:pb-wrap report, then gets archived.
 -->
 
 # Build log — {{TITLE}}
 
-**Current step:** none (DESIGN) · **STATE:** DESIGN
+**Current step:** none (at the boundary)
 **Heavy check:** {{CHECK}}
 
 ## Steps
@@ -47,8 +48,9 @@ Harvest results this boundary:
 
 ## Log
 
-*(Append-only. One decision or event per line, dated. What you point at to say "I
-did that — the LLM helped, but those were my calls." `/plumbbob:pb-wrap` reads this for the
-report; `plumbbob wrap` archives it under `.plumbbob/archive/`.)*
-
-- <date> — <decision / event / what shipped this step>
+*(The build's history, oldest first. `plumbbob checkpoint` appends a dated line here
+every time a step lands — via `/plumbbob:pb-build` or `/plumbbob:pb-verify` — so this
+fills in as you go, not at the end. Add your own decision/event lines too: this is what
+you point at to say "I did that — the LLM helped, but those were my calls."
+`/plumbbob:pb-wrap` reads this for the report; `plumbbob wrap` archives it under
+`.plumbbob/archive/`.)*

package/templates/intent.md

@@ -9,8 +9,7 @@ open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
 
 # {{TITLE}}
 
-**STATE:** DESIGN
-**Phase** (bookkeeping while in DESIGN): frame
+**Phase** (your own bookkeeping while framing): frame
 **Size:** tiny | small | medium
 
 ## Frame