plumbbob 0.8.12 → 0.8.13

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/dist/cli-core.js

@@ -29,7 +29,7 @@ const VERBS = [
     { 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: 'spike', summary: 'spike "<slug>" | spike report "<slug>" | spike done: worktree experiment + report' },
     { name: 'use', summary: 'use <slug>: re-point the active-build cursor and resume that build' },
     { name: 'finish', summary: 'close-out: report + final commit (no gate), clear the control state, close the session' },
     { name: 'init', summary: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob); --uninstall to undo' },

package/dist/lib/buildlog.js

@@ -1,8 +1,10 @@
 // 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 finish (D-history).
-// Pure string transforms (no fs, no classes — C1/C2); callers own the IO so these
-// stay trivially testable.
+// `build`/`checkpoint`/`revert` keep its `## Steps` mirror and `**Current step:**`
+// line in sync with intent.md (D69), so the ledger's top half tracks reality without
+// a model turn. 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.
@@ -25,6 +27,51 @@ export function appendToSection(content, heading, line) {
     lines.splice(insertAt, 0, line);
     return lines.join('\n');
 }
+// Replace the `**Current step:**` line with `**Current step:** <label>` — `build`
+// sets it to `<n> — <title>` when a step opens; `checkpoint`/`revert` reset it to
+// `none (at the boundary)`. Returns null when the line is absent so the caller skips
+// rather than corrupting the doc (C3).
+export function setCurrentStep(content, label) {
+    const lines = content.split('\n');
+    const idx = lines.findIndex((l) => /^\*\*Current step:\*\*/.test(l.trim()));
+    if (idx === -1) {
+        return null;
+    }
+    lines[idx] = `**Current step:** ${label}`;
+    return lines.join('\n');
+}
+// Regenerate the `## Steps` mirror from intent.md's parsed steps — one
+// `- ☑/☐ N. <title>` line each, in order. Only the mirror's own `- ☑/☐` list lines
+// are owned; the italic instructions paragraph (and any other prose) is preserved,
+// and exactly one blank line separates it from the list. Returns null when the
+// section is absent (C3). With no steps the mirror renders empty — the plan is not
+// authored yet — rather than inventing a placeholder.
+export function syncStepsSection(content, steps) {
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((l) => l.trim() === '## Steps');
+    if (headingIdx === -1) {
+        return null;
+    }
+    let end = lines.findIndex((l, i) => i > headingIdx && l.startsWith('## '));
+    if (end === -1) {
+        end = lines.length;
+    }
+    // The section body minus the mirror list lines, with trailing blanks trimmed, is
+    // the prose to preserve (the instructions paragraph). Rebuild: prose, one blank,
+    // the fresh list, one blank before the next heading.
+    const prose = lines.slice(headingIdx + 1, end).filter((l) => !isMirrorLine(l));
+    while (prose.length > 0 && (prose.at(-1) ?? '').trim() === '') {
+        prose.pop();
+    }
+    const list = steps.map((s) => `- ${s.done ? '☑' : '☐'} ${s.n}. ${s.title}`);
+    const body = [...prose, ...(prose.length > 0 ? [''] : []), ...list, ''];
+    return [...lines.slice(0, headingIdx + 1), ...body, ...lines.slice(end)].join('\n');
+}
+// A mirror list line the CLI owns: `- ☑ …` / `- ☐ …`. The template's initial
+// `- ☐ 1. <step>` placeholder matches, so the first sync replaces it in place.
+function isMirrorLine(line) {
+    return /^-\s+[☑☐]/.test(line);
+}
 // 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 — `/pb-finish` reads these instead of re-narrating the build.

package/dist/lib/buildlogsync.js

@@ -0,0 +1,34 @@
+// Keep the build-log's top half — the `**Current step:**` line and the `## Steps`
+// mirror — in sync with intent.md (D69). `build` sets the current-step label when a
+// step opens; `checkpoint` and `revert` reset it to the boundary; all three re-render
+// the mirror from intent.md's parsed steps so it tracks reality without a model turn.
+// The write is best-effort (a missing or hand-edited build-log never fails a verb —
+// the checkpoints ledger and intent.md stay the source of truth), matching how
+// `checkpoint`'s Log append already behaves.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { buildLogPath, intentPath } from "./sidecar.js";
+import { parseSteps } from "./orient.js";
+import { setCurrentStep, syncStepsSection } from "./buildlog.js";
+export const AT_BOUNDARY = 'none (at the boundary)';
+// The current-step label for an open step: `<n> — <title>`, or a bare `<n>` when the
+// step carries no title. `build` passes this; the boundary verbs pass AT_BOUNDARY.
+export function stepLabel(n, title) {
+    return title !== null && title.trim().length > 0 ? `${n} — ${title.trim()}` : String(n);
+}
+// Rewrite the active build's build-log top half: set the Current step line to `label`
+// and re-render the `## Steps` mirror from intent.md. Each transform is skipped when
+// its target is absent (null), and the whole thing swallows any IO error — the ledger
+// must never block the verb.
+export function syncBuildLogState(root, slug, label) {
+    try {
+        const path = buildLogPath(root, slug);
+        const steps = parseSteps(readFileSync(intentPath(root, slug), 'utf8'));
+        let content = readFileSync(path, 'utf8');
+        content = setCurrentStep(content, label) ?? content;
+        content = syncStepsSection(content, steps) ?? content;
+        writeFileSync(path, content);
+    }
+    catch {
+        // best-effort ledger; never fail a verb over the build-log.
+    }
+}

package/dist/lib/sidecar.js

@@ -158,6 +158,31 @@ export function buildLogPath(root, slug) {
 export function reportPath(root, slug) {
     return join(artifactDir(root, slug), 'report.md');
 }
+// Spike reports (D70): `spike-NN-<slug>.md` in the build folder, beside report.md.
+// One per spike — an explicit `/pb-spike` or a planned `spike:` step — so a build with
+// several forks tells its decision history through the folder listing. NN is
+// CLI-allocated (the human never numbers them), zero-padded for a stable sort.
+// The existing spike-report filenames in the build folder, sorted. Empty when the
+// folder is absent or holds none.
+export function listSpikeReports(root, slug) {
+    try {
+        return readdirSync(artifactDir(root, slug))
+            .filter((name) => /^spike-\d\d-.+\.md$/.test(name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// The path for a NEW spike report: the next free zero-padded index (one past the
+// highest existing NN, so a gap never reallocates a number) and the sanitized spike
+// slug. Pure allocation — the caller writes the stamped template there.
+export function nextSpikeReportPath(root, slug, spikeSlug) {
+    const used = listSpikeReports(root, slug).map((name) => Number(name.slice('spike-'.length, 'spike-'.length + 2)));
+    const next = (used.length > 0 ? Math.max(...used) : 0) + 1;
+    const nn = String(next).padStart(2, '0');
+    return join(artifactDir(root, slug), `spike-${nn}-${spikeSlug}.md`);
+}
 // handoff.json is the agent-run ledger (D47): each `agent run` appends its
 // validated envelope here so a later invocation can thread earlier results into
 // the next call's `context[]` — the CLI itself is memoryless between runs, and

package/dist/lib/templates.js

@@ -0,0 +1,19 @@
+// Scaffold templates live at `<pkg-root>/templates/*.md` and carry `{{PLACEHOLDER}}`
+// tokens the verbs fill in. `start` stamps intent.md / build-log.md; `spike` stamps
+// spike-report.md. Shared here so both resolve the template dir the same way (relative
+// to the compiled module URL) and substitute with one mechanism. Pure/procedural,
+// node-builtins-only (C1/C2).
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+export function readTemplate(name) {
+    return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8');
+}
+// Replace every `{{KEY}}` with its value. Generic over the placeholder set so a new
+// template can add tokens (spike-report's `{{VIA}}`/`{{DATE}}`) without touching this.
+export function stampTemplate(template, subs) {
+    let out = template;
+    for (const [key, value] of Object.entries(subs)) {
+        out = out.split(`{{${key}}}`).join(value);
+    }
+    return out;
+}

package/dist/verbs/build.js

@@ -6,6 +6,7 @@ import { findRepoRoot } from "../lib/git.js";
 import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
 import { parseSteps } from "../lib/orient.js";
+import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -55,6 +56,10 @@ export function build(cwd, args) {
     // The wall-clock receipt starts here (research/07 Build 2b): checkpoint stamps
     // landedAt, and the pair becomes the step's duration in the finish report.
     stampStepStat(root, slug, step, 'startedAt', new Date().toISOString());
+    // The build-log's top half now shows this step in flight (D69): Current step +
+    // the ☐/☑ mirror, re-rendered from intent.md. Best-effort — never blocks the build.
+    const title = parseSteps(intent).find((s) => s.n === step)?.title ?? null;
+    syncBuildLogState(root, slug, stepLabel(step, title));
     const picked = raw === undefined ? ' (next undone)' : '';
     process.stdout.write(`plumbbob: building step ${step}${picked}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;

package/dist/verbs/checkpoint.js

@@ -16,6 +16,7 @@ import { markStepDone, parseSteps } from "../lib/orient.js";
 import { parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
+import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 export async function checkpoint(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -64,6 +65,10 @@ export async function checkpoint(cwd, args) {
     flipIntent(root, step);
     stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
     logCheckpoint(root, step, sha);
+    // The step landed: the build-log's mirror flips to ☑ and Current step returns to
+    // the boundary (D69), re-read from the intent.md `flipIntent` just wrote. The
+    // artifact-plane whitelist keeps this build-log write from ever reading as drift.
+    syncBuildLogState(root, activeBuild(root), AT_BOUNDARY);
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
     clearHandoff(root); // the agent-run ledger is step-scoped (D47) — clear it with the markers.

package/dist/verbs/revert.js

@@ -20,6 +20,7 @@ import { fileURLToPath } from 'node:url';
 import { findRepoRoot, resetHard, untrackedPaths } from "../lib/git.js";
 import { bumpStepStat, checkpointsPath, hasSession, resolveBuild, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
 import { isArtifactPath, matchesSeam } from "../lib/intent.js";
+import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 export function revert(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -66,6 +67,10 @@ export function revert(cwd, args) {
     if (inFlight !== null) {
         bumpStepStat(root, slug, inFlight, 'reverts');
     }
+    // The step is abandoned: the build-log returns to the boundary and its mirror
+    // re-renders from the preserved intent.md (D69) — revert keeps intent edits (D26),
+    // so intent's checkboxes stay the truth to reflect. Best-effort, like the rest.
+    syncBuildLogState(root, slug, AT_BOUNDARY);
     process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — back at the boundary. Park lines and intent edits were preserved.\n`);
     return 0;
 }

package/dist/verbs/spike.js

@@ -10,11 +10,15 @@
 // shared additive read/commit helpers): worktree management is spike-local, and
 // this is the only place Plumbbob creates branches.
 import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, inSpike, markSpike, clearSpike, resolveBuild, stepPath } from "../lib/sidecar.js";
+import { buildFolder, clearSpike, hasSession, inSpike, listSpikeReports, markSpike, nextSpikeReportPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
+import { readTemplate, stampTemplate } from "../lib/templates.js";
 const DEFAULT_OPTIONS = ['a', 'b'];
+// The verbatim Verdict placeholder from templates/spike-report.md — its presence means
+// the spike's call was never recorded, which `spike done` nudges on (D70).
+const VERDICT_PLACEHOLDER = '*(viable | not viable | partial';
 export function spike(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -26,8 +30,49 @@ export function spike(cwd, args) {
     if (positionals[0] === 'done') {
         return spikeDone(root, buildSlug);
     }
+    if (positionals[0] === 'report') {
+        return spikeReport(root, buildSlug, positionals.slice(1));
+    }
     return spikeStart(root, buildSlug, positionals);
 }
+// `spike report "<slug>"` (D70) — scaffold a spike report WITHOUT worktrees, for the
+// spike-as-step case (a planned step titled `spike: …`, where the increment itself is
+// the experiment). No boundary requirement and no SPIKE marker: a step in flight is
+// exactly when this runs. Provenance is `step <n>` when a STEP is in flight, else
+// `/pb-spike`.
+function spikeReport(root, buildSlug, positionals) {
+    const slug = sanitize(positionals[0] ?? '');
+    if (slug.length === 0) {
+        process.stderr.write('plumbbob: spike report needs a slug. Try: plumbbob spike report "auth-store".\n');
+        return 1;
+    }
+    const inFlight = readInFlightStep(root, buildSlug);
+    const via = inFlight !== null ? `step ${inFlight}` : '/pb-spike';
+    const path = scaffoldSpikeReport(root, buildSlug, slug, via);
+    process.stdout.write(`plumbbob: spike report scaffolded — ${relative(root, path)}. Fill Findings and the Verdict as you go; ` +
+        `a recorded Verdict is what closes a spike step.\n`);
+    return 0;
+}
+// Write a fresh spike report from the template at the next free `spike-NN-<slug>.md`
+// in the build folder, and return its path. Shared by the explicit `/pb-spike` open
+// and the spike-as-step `spike report` — one artifact, two entry points (D70).
+function scaffoldSpikeReport(root, buildSlug, spikeSlug, via) {
+    const path = nextSpikeReportPath(root, buildSlug, spikeSlug);
+    const date = new Date().toISOString().slice(0, 10);
+    writeFileSync(path, stampTemplate(readTemplate('spike-report.md'), { TITLE: spikeSlug, VIA: via, DATE: date }));
+    return path;
+}
+// The in-flight STEP number for the build, or null — reads the STEP marker `build`
+// writes. Used to stamp a spike-as-step report's provenance.
+function readInFlightStep(root, buildSlug) {
+    try {
+        const raw = readFileSync(stepPath(root, buildSlug), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
 function spikeStart(root, buildSlug, positionals) {
     if (inSpike(root, buildSlug)) {
         process.stderr.write('plumbbob: already in a spike. Run `plumbbob spike done` to close it first.\n');
@@ -56,9 +101,12 @@ function spikeStart(root, buildSlug, positionals) {
         created.push(path);
     }
     markSpike(root, buildSlug);
+    // Scaffold the report NOW, while the worktrees live (D70): findings accrue during the
+    // experiment, not from memory after the teardown. Provenance names the worktrees.
+    const report = scaffoldSpikeReport(root, buildSlug, slug, `/pb-spike — worktrees (${options.join(', ')})`);
     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`);
+        .join('\n')}\nRecord findings and the Verdict in ${relative(root, report)} as you go, then run \`plumbbob spike done\`.\n`);
     return 0;
 }
 function spikeDone(root, buildSlug) {
@@ -66,6 +114,10 @@ function spikeDone(root, buildSlug) {
         process.stderr.write('plumbbob: no active spike to close.\n');
         return 1;
     }
+    // Check for an unrecorded verdict BEFORE teardown (D70). The reports live in the
+    // build folder, not the spike worktrees, so they survive the removal — but the
+    // learning that fills them does not, so this is the moment to nudge.
+    const unfilled = spikeReportsMissingVerdict(root, buildSlug);
     for (const path of spikeWorktrees(root)) {
         git(root, ['worktree', 'remove', '--force', path]);
     }
@@ -74,10 +126,32 @@ function spikeDone(root, buildSlug) {
         git(root, ['branch', '-D', branch]);
     }
     clearSpike(root, buildSlug);
-    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');
+    // Guidance, not a gate (the enforce→guide pivot): a missing verdict is a nudge, and
+    // the spike still closes. Name the reports so the human knows where to write it.
+    if (unfilled.length > 0) {
+        process.stderr.write(`plumbbob: heads-up — no verdict recorded in ${unfilled.join(', ')}. ` +
+            `The worktrees are gone; capture the call there before it fades.\n`);
+    }
+    const reports = listSpikeReports(root, buildSlug);
+    const where = reports.length > 0 ? `the spike report${reports.length === 1 ? '' : 's'} (${reports.join(', ')})` : 'intent.md';
+    process.stdout.write(`plumbbob: spike closed — worktrees and branches removed, back at the boundary. ` +
+        `Record the verdict (which option won, and why) in ${where} before you \`build\`.\n`);
     return 0;
 }
+// The spike-report filenames in the build folder whose Verdict is still the template
+// placeholder — the ones `spike done` nudges on. Best-effort per file: an unreadable
+// report is skipped rather than blocking the close.
+function spikeReportsMissingVerdict(root, buildSlug) {
+    const dir = buildFolder(root, buildSlug);
+    return listSpikeReports(root, buildSlug).filter((name) => {
+        try {
+            return readFileSync(join(dir, name), 'utf8').includes(VERDICT_PLACEHOLDER);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 // Worktree paths whose checked-out branch is under spike/ — parsed from the
 // porcelain output (blank-line-separated `worktree <path>` / `branch <ref>` blocks).
 function spikeWorktrees(root) {

package/dist/verbs/start.js

@@ -1,9 +1,9 @@
 // `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 { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { detectGate } from "../lib/check.js";
+import { readTemplate, stampTemplate } from "../lib/templates.js";
 import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
 import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
 import { settingsPath } from "../lib/settings.js";
@@ -73,8 +73,8 @@ export async function start(cwd, args) {
     let intentLocation;
     if (local) {
         writeFileSync(checkpointsPath(root), `baseline ${sha}\n`);
-        writeFileSync(intentPath(root), stamp(readTemplate('intent.md'), title, CHECK_ECHO));
-        writeFileSync(buildLogPath(root), stamp(readTemplate('build-log.md'), title, CHECK_ECHO));
+        writeFileSync(intentPath(root), stampBuild(readTemplate('intent.md'), title));
+        writeFileSync(buildLogPath(root), stampBuild(readTemplate('build-log.md'), title));
         excludeSidecar(root);
         intentLocation = '.plumbbob/intent.md';
     }
@@ -82,8 +82,8 @@ export async function start(cwd, args) {
         const dir = buildDir(root, slug);
         mkdirSync(dir, { recursive: true });
         writeFileSync(join(dir, 'checkpoints'), `baseline ${sha}\n`);
-        writeFileSync(join(dir, 'intent.md'), stamp(readTemplate('intent.md'), title, CHECK_ECHO));
-        writeFileSync(join(dir, 'build-log.md'), stamp(readTemplate('build-log.md'), title, CHECK_ECHO));
+        writeFileSync(join(dir, 'intent.md'), stampBuild(readTemplate('intent.md'), title));
+        writeFileSync(join(dir, 'build-log.md'), stampBuild(readTemplate('build-log.md'), title));
         excludeControl(root);
         intentLocation = `.plumbbob/builds/${slug}/intent.md`;
     }
@@ -128,9 +128,8 @@ function flagValue(args, flag) {
     const i = args.indexOf(flag);
     return i >= 0 ? args[i + 1] : undefined;
 }
-function readTemplate(name) {
-    return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8');
-}
-function stamp(template, title, check) {
-    return template.split('{{TITLE}}').join(title).split('{{CHECK}}').join(check);
+// Stamp a build template's `{{TITLE}}`/`{{CHECK}}` — the check is always the echo
+// constant (absence of a `check` setting IS the default, D24/D32).
+function stampBuild(template, title) {
+    return stampTemplate(template, { TITLE: title, CHECK: CHECK_ECHO });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",

package/skills/pb-build/SKILL.md

@@ -3,7 +3,7 @@ name: pb-build
 description: The default engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable — build by hand/vibed/another harness and run /pb-verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses.
 argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(git diff:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
 ---
 
 # PlumbBob — build a step (the default engine)
@@ -36,6 +36,13 @@ differs from the model you're running as, say so before implementing — the hum
 2. **Enter the step.** Run `plumbbob build <n>` — or bare `plumbbob build` to enter the
    next undone step (records the in-flight STEP + SEAM so `/pb-status` shows the step in
    flight; the seam is awareness, not a lock).
+   - **Spike-as-step.** If the step's title opens with `spike:` / `Spike:`, the increment
+     *is* the experiment — resolving a fork the plan couldn't settle on paper. After
+     entering it, run `plumbbob spike report "<slug>"` (the CLI scaffolds a
+     `spike-NN-<slug>.md` in the build folder, stamped `via: step <n>`), then work the
+     experiment and record your **Findings** and **Verdict** there. A recorded verdict is
+     what the step's done-when should check — the report, not just the code, is the
+     deliverable. This is the same artifact `/pb-spike` produces for a mid-build fork (D70).
 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.

package/skills/pb-spike/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pb-spike
-description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, or tear it down with `spike done`.
-argument-hint: "<slug> | done"
+description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, scaffold a spike report for a spike-as-step, or tear it down with `spike done`.
+argument-hint: "<slug> | report <slug> | done"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob spike:*)
@@ -15,6 +15,15 @@ This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob
 
 ## What it does
 
-1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/pb-spike redis-cache`), or the literal `done` to tear the current spike down (`/pb-spike done`). If neither is present, ask which and run nothing.
-2. Run `plumbbob spike "<slug>"` or `plumbbob spike done` via Bash.
-3. Report the verb's output verbatim — the worktree it created or removed, or any refusal.
+1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/pb-spike redis-cache`), `report <slug>` to scaffold a report without worktrees (`/pb-spike report auth-store`), or the literal `done` to tear the current spike down (`/pb-spike done`). If none is present, ask which and run nothing.
+2. Run `plumbbob spike "<slug>"`, `plumbbob spike report "<slug>"`, or `plumbbob spike done` via Bash.
+3. Report the verb's output verbatim — the worktree it created or removed, the spike report it scaffolded, or any refusal. When the verb names a `spike-NN-<slug>.md` report, point the human at it; when `spike done` nudges that a verdict is unrecorded, relay that nudge verbatim.
+
+## The spike report (D70)
+
+Every spike leaves a durable `spike-NN-<slug>.md` in the build folder, beside `intent.md`/`report.md`, so the fork's verdict rides the branch into the PR instead of evaporating. The CLI scaffolds it from a template and numbers it — you never create or number the file:
+
+- **`/pb-spike <slug>`** scaffolds the report *at open*, so findings accrue while the throwaway worktrees are still live. Fill its **Findings** and **Verdict** before `/pb-spike done`.
+- **`/pb-spike report <slug>`** is for a *spike-as-step* — a planned step titled `spike: …`, where the increment itself is the experiment and there are no worktrees. It stamps the report's provenance as `step <n>` when a step is in flight.
+
+This skill stays Write-less: the CLI owns the file. Your job is to run the verb and, between runs, help the human fill the report's prose — but the edits land through the normal build flow, not this driver.

package/templates/build-log.md

@@ -2,7 +2,9 @@
 build-log.md — your live ledger for execution. Append constantly; reorganize at
 step boundaries. The antidote to "my plan got lost in the noise."
 
-  Steps     : where you are. One step in flight at a time.
+  Steps     : where you are. One step in flight at a time. CLI-maintained: `build`,
+              `checkpoint`, and `revert` keep this mirror and the Current step line
+              in sync with intent.md — you never hand-edit them.
   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 build's history. `plumbbob checkpoint` appends a line per step as it
@@ -16,9 +18,10 @@ step boundaries. The antidote to "my plan got lost in the noise."
 
 ## Steps
 
-*(Mirror of intent.md's Steps, with live status. Only ONE step is in flight. A step
-is done only after a checkpoint — check green + checkpoint taken, via `/pb-verify` or
-`/pb-build`.)*
+*(Mirror of intent.md's Steps, with live status — CLI-maintained, not hand-edited.
+`build`/`checkpoint`/`revert` re-render this from intent.md, and set the Current step
+line above. Only ONE step is in flight; a step is done only after a checkpoint —
+check green + checkpoint taken, via `/pb-verify` or `/pb-build`.)*
 
 - ☐ 1. <step>
 

package/templates/spike-report.md

@@ -0,0 +1,38 @@
+<!--
+spike-report.md — the durable receipt for a spike (a fork the plan couldn't settle
+on paper). One per spike, numbered and named `spike-NN-<slug>.md`, riding the build
+folder into the PR beside intent.md / report.md. Fill it while the experiment is live
+— the worktrees and their learnings are torn down at `spike done`, but this stays.
+
+Two ways a spike is born, both landing here:
+  - `/pb-spike <slug>` — an explicit mid-build fork with throwaway worktrees.
+  - a planned step titled `spike: …` — the increment IS the experiment.
+Record the Verdict before you close the spike (or check off the step).
+-->
+
+# Spike — {{TITLE}}
+
+**Via:** {{VIA}}
+**Opened:** {{DATE}}
+
+## Question
+
+*(The fork this resolves, in one or two lines. What are we uncertain about, and what
+would each answer commit us to?)*
+
+## Options tried
+
+*(Each path you actually ran, and what it took — one bullet each.)*
+
+## Findings
+
+*(What the experiment showed — evidence, not opinion. Numbers, errors, surprises.)*
+
+## Verdict
+
+**Verdict:** *(viable | not viable | partial — replace this line with the call and why)*
+
+## What this decides
+
+*(The intent.md Decision this feeds — which option won, what dies, and the one reason
+that settled it. Copy the call into intent.md's Decisions / Verdicts too.)*