plumbbob 0.4.4 → 0.4.11

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: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

@@ -4,12 +4,13 @@
 // in place as a plugin (skills `/plumbbob:*`, the post-edit hook from hooks.json).
 // doctor verifies the link resolves to a package carrying the manifest, the skills,
 // and the hook — and names the fix for anything missing. The failure class it
-// exists for is SILENT (a `/plumbbob:status` that opens an empty dashboard because the
+// exists for is SILENT (a `/plumbbob:pb-status` that opens an empty dashboard because the
 // plugin never linked). Functional, node builtins only (C1/C2).
 import { existsSync, lstatSync, readdirSync, readlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { marketplacePlumbbob } from "../lib/plugins.js";
 // The plumbbob package's own skills/ dir (the canonical set), off this module's
 // URL so it resolves the same from src/ (dev) and dist/ (published).
 function packageDir(name) {
@@ -58,8 +59,25 @@ export function doctor() {
     const link = join(home, '.claude', 'skills', 'plumbbob');
     const shipped = listSkills(packageDir('skills'));
     const pkg = linkedPackage(link);
-    const checks = pkg === null ? [{ ok: false, label: `not linked — no plugin at ${link}`, fix: 'run: plumbbob init' }] : buildChecks(link, pkg, shipped);
-    const out = ['plumbbob doctor — global plugin install'];
+    const market = marketplacePlumbbob(home);
+    let checks;
+    if (pkg === null) {
+        checks =
+            market.length > 0
+                ? [{ ok: true, label: `installed via marketplace (${market.join(', ')}) — skills load as /plumbbob:*, the CLI is on PATH from the plugin bin/. No init needed.` }]
+                : [{ ok: false, label: `not linked — no plugin at ${link}`, fix: 'install the marketplace plugin (/plugin install plumbbob@<marketplace>) or run: plumbbob init' }];
+    }
+    else {
+        checks = buildChecks(link, pkg, shipped);
+        if (market.length > 0) {
+            checks.unshift({
+                ok: false,
+                label: `collision — also installed via marketplace (${market.join(', ')}); two plugins named plumbbob fight over /plumbbob:* and skills can drop to flat names`,
+                fix: 'keep one — `plumbbob init --uninstall` to use the marketplace plugin, or `/plugin uninstall` the marketplace one to keep this link',
+            });
+        }
+    }
+    const out = ['plumbbob doctor — plugin install'];
     for (const c of checks) {
         out.push(c.ok ? `  ✓ ${c.label}` : `  ✗ ${c.label}\n      → ${c.fix}`);
     }
@@ -68,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` — ensure it is on PATH (`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/init.js

@@ -1,16 +1,24 @@
-// `plumbbob init [--uninstall]` — link plumbbob into Claude Code as an in-place
-// skills-directory plugin. This is the whole install: it symlinks the installed
-// package into ~/.claude/skills/plumbbob, where Claude Code discovers it as
-// `plumbbob@skills-dir` — the skills load namespaced (`/plumbbob:*`) and the
-// post-edit hook auto-registers from hooks/hooks.json. Global-only by design:
-// plumbbob is a personal tool (like firecrawl/gh), and install scope is NOT
-// session scope — sessions stay per-project via `plumbbob start`. Idempotent +
-// reversible (`--uninstall` drops the link); it NEVER writes settings.json.
-// Functional, node builtins only (C1/C2).
+// `plumbbob init [--uninstall] [--force]` — link plumbbob into Claude Code as an
+// in-place skills-directory plugin. It symlinks the installed package into
+// ~/.claude/skills/plumbbob, where Claude Code discovers it as `plumbbob@skills-dir`
+// — the skills load namespaced (`/plumbbob:*`) and the post-edit hook auto-registers
+// from hooks/hooks.json. This is the deliberate non-marketplace install path — kept
+// first-class, not deprecated: it serves an `npm i -g` global, local dev, and clients
+// predating plugins, and keeps plumbbob usable as a standalone CLI (and, later, under
+// other agents) rather than Claude-marketplace-only. The marketplace plugin is the
+// co-equal self-contained alternative (it ships skills AND the `plumbbob` CLI on PATH
+// via bin/, so it needs neither `npm i -g` nor `init`). The two are mutually
+// exclusive: both register a plugin named `plumbbob`, and a double-install collides
+// over the /plumbbob:* namespace (skills can drop to flat `/pb-status` names). So init
+// REFUSES when a marketplace plumbbob is already installed — `--force` overrides
+// (the dev-install path uses it). Global-only by design: install scope is NOT session
+// scope — sessions stay per-project via `plumbbob start`. Idempotent + reversible
+// (`--uninstall` drops the link); it NEVER writes settings.json. Node builtins only.
 import { lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { marketplacePlumbbob } from "../lib/plugins.js";
 // The installed package root (parent of .claude-plugin/, skills/, hooks/, dist/),
 // off this module's URL — the global install when run as the published bin, the
 // checkout in dev. No trailing slash, so it compares clean against a readlink.
@@ -47,6 +55,14 @@ export function init(args) {
     if (args.includes('--uninstall')) {
         return uninstall(link);
     }
+    const market = marketplacePlumbbob(home);
+    if (market.length > 0 && !args.includes('--force')) {
+        process.stderr.write(`plumbbob: a marketplace plumbbob plugin is already installed (${market.join(', ')}).\n` +
+            'plumbbob: it already provides the skills (`/plumbbob:*`) and the `plumbbob` CLI on PATH (the plugin bin/) — no `plumbbob init` needed.\n' +
+            `plumbbob: linking ${link} would register a SECOND plugin named \`plumbbob\`; the two collide over the /plumbbob:* namespace and skills can drop to flat names (\`/pb-status\`).\n` +
+            'plumbbob: to use the skills-dir link instead, first remove the marketplace one (`/plugin uninstall plumbbob@<marketplace>`), or re-run with `--force` if you know what you are doing.\n');
+        return 1;
+    }
     mkdirSync(join(home, '.claude', 'skills'), { recursive: true });
     if (present(link)) {
         const current = symlinkTarget(link);

package/dist/verbs/park.js

@@ -1,9 +1,10 @@
 // `plumbbob park "<text>"` — the dumb capture path: append one raw line under
-// the build-log's Park list. No model turn, no composition (that is /park's job).
+// the build-log's Park list. No model turn, no composition (that is /plumbbob:pb-park's job).
 // Capture is not a transition, so it runs in any context (terminal or in-session).
 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

@@ -1,13 +1,13 @@
 // `plumbbob wrap` (D9) — the v2 close-out, replacing the v1 four-verb
 // finish ceremony. It archives intent + build-log + report
-// (the `/plumbbob:wrap` skill writes the report by default) under .plumbbob/archive/,
+// (the `/plumbbob:pb-wrap` skill writes the report by default) under .plumbbob/archive/,
 // clears the active files, and deletes the control state (STATE last). Unlike v1
 // `finish` there is NO refuse-without-report gate — guidance offers the artifact, it
 // does not wall the exit. Archive-then-clear, never destroy (C4); git untouched (C5).
 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);
@@ -20,7 +20,7 @@ export function wrap(cwd) {
     }
     else {
         process.stderr.write('plumbbob: note — no report.md found; archiving intent + build-log without one ' +
-            '(/plumbbob:wrap normally writes the report first). No gate (D9).\n');
+            '(/plumbbob:pb-wrap normally writes the report first). No gate (D9).\n');
     }
     const archived = archiveSession(root);
     // Clear the active files — now safely archived — then the control state, STATE
@@ -30,9 +30,10 @@ 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:plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
+        'Run `/plumbbob:pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
     return 0;
 }
 // Append the recorded checkpoints (baseline + each `step n <sha>`) to the report so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.4.4",
+  "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,11 +20,12 @@
   "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",
+    "bin",
     "dist",
     "hooks",
     "skills",

package/skills/{build → pb-build}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: build
+name: pb-build
 description: The optional engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Skip it to build by hand/vibed/another harness. `--auto` self-approves and chains to done.
 disable-model-invocation: true
 model: opus
@@ -12,40 +12,41 @@ Current session state (injected when this skill runs): !`plumbbob status 2>/dev/
 
 This is the **bundled executor** — one way to turn a planned step into code. It is
 **optional** (D3): you can implement any step by hand, in a vibe session, or with
-another harness and go straight to `/plumbbob:verify` instead — plumbbob does not care how
+another harness and go straight to `/plumbbob:pb-verify` instead — plumbbob does not care how
 the diff appeared. When you do run it, it reads the plan, writes the step, and
 carries straight through to the verify pause.
 
-Since `/plumbbob:plan` lays down the whole step list up front, the happy path is to fire
-`/plumbbob:build` once per step until done — each run builds the next undone step and stops
-at the pause for your approval. **Re-firing `/plumbbob:build` is itself the clock tick.**
+Since `/plumbbob:pb-plan` lays down the whole step list up front, the happy path is to fire
+`/plumbbob:pb-build` once per step until done — each run builds the next undone step and stops
+at the pause for your approval. **Re-firing `/plumbbob:pb-build` is itself the clock tick.**
 
 ## What this skill does, in order
 
-1. **Pick the step.** Use the number you were invoked with (e.g. `/plumbbob:build 4`), else
+1. **Pick the step.** Use the number you were invoked with (e.g. `/plumbbob:pb-build 4`), else
    the next undone, planned step in `.plumbbob/intent.md`. If there is no planned step
-   to build, stop and tell the human to `/plumbbob:step` first.
+   to build, stop and tell the human to `/plumbbob:pb-step` first.
 2. **Enter the step.** Run `plumbbob build <n>` (records the in-flight STEP +
-   SEAM so `/plumbbob:status` shows the step in flight; in v2 the seam is awareness, not a
+   SEAM so `/plumbbob:pb-status` shows the step in flight; in v2 the seam is awareness, not a
    lock).
 3. **Read the plan.** Read the step's **done-when**, its **seam**, and the
    **Decisions** and **Constraints** in `intent.md`. Build to *that* — the deciding
    already happened, off the chat.
 4. **Implement** the step, and only that step, staying within the declared seam. A
-   new problem or "ooh what if" that surfaces mid-build is a `/plumbbob:park`, **not** an
+   new problem or "ooh what if" that surfaces mid-build is a `/plumbbob:pb-park`, **not** an
    edit — capture it and stay on the step. If you genuinely cannot finish without
    touching more than the seam, that is scope drift: surface it to the human rather
    than sprawling.
-5. **Verify, through to the pause.** Run the verify tick exactly as `/plumbbob:verify`
+5. **Verify, through to the pause.** Run the verify tick exactly as `/plumbbob:pb-verify`
    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)
 
-`/plumbbob:build --auto` is the explicit escape hatch when the human wants unattended
+`/plumbbob:pb-build --auto` is the explicit escape hatch when the human wants unattended
 progress instead of approving each step. It does the same work, but **the agent reviews
 and approves in the human's place**, and it **chains**:
 
@@ -61,10 +62,10 @@ human asked for it by name. The default — no flag — always ends at the pause
 
 ## The hard contracts
 
-- **Optional, never required.** The loop works without this skill; `/plumbbob:verify`
+- **Optional, never required.** The loop works without this skill; `/plumbbob:pb-verify`
   checkpoints a hand-built or vibed diff just the same (D3).
 - **Build the decided step, not a new one.** Implement what `intent.md` settled. A
-  new idea mid-build is a `/plumbbob:park`, not an edit.
+  new idea mid-build is a `/plumbbob:pb-park`, not an edit.
 - **Default ends at the pause.** Implement → verify → wait for approval; never
   checkpoint without it. Only an explicit `--auto` lets the agent approve in your place,
   and it still halts on a red check or any mismatch.

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/{harvest → pb-harvest}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: harvest
+name: pb-harvest
 description: Triage the park list at a step boundary — propose one class (blocker/tangent/pivot) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent.
 disable-model-invocation: true
 model: opus
@@ -10,18 +10,19 @@ allowed-tools: Read, Edit, Bash(plumbbob status:*)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/plumbbob:harvest` is the complement of `/plumbbob:park` (D7): you parked ideas as seeds during a
+`/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: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
 
@@ -40,7 +41,7 @@ one line of reasoning, then **wait for the human to confirm or override**. Write
 **only after** per-item confirmation:
 
 - Record each confirmed class in `build-log.md`'s `## Harvest` section.
-- **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/plumbbob:status`
+- **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/plumbbob:pb-status`
   stops counting it as open.
 - A confirmed **blocker** also folds its decision into `intent.md`.
 - Never reclassify or resolve an item the human hasn't confirmed, and default every

package/skills/{park → pb-park}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: park
+name: pb-park
 description: Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park` — never by editing a file. The capture half of the park/harvest loop.
 disable-model-invocation: true
 model: haiku
@@ -10,16 +10,16 @@ allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/plumbbob:park` is the **capture** half of the loop; `/plumbbob:harvest` is where parked items
+`/plumbbob:pb-park` is the **capture** half of the loop; `/plumbbob:pb-harvest` is where parked items
 get triaged later (D7). Capturing the instant an idea arrives — instead of acting on
 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