plumbbob 0.8.12 → 0.8.14

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "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/intent.js

@@ -149,6 +149,26 @@ export function parseBuildTitle(content) {
     }
     return '';
 }
+const SCOPE_HEADER = /^\*\*Scope:\*\*\s*(.*)$/;
+const SCOPE_PLACEHOLDER = /^<.*>$/;
+// The build's default Conventional-Commit scope (D4): the `**Scope:**` header
+// field authored once at plan time, its value read verbatim off the line with any
+// trailing `<!-- ... -->` guidance note stripped. An unfilled placeholder — an
+// empty value or an angle-bracket placeholder like `<feature>` — parses as absent
+// (D7), so a freshly scaffolded, not-yet-edited build falls through to the next
+// scope rung (the build slug) rather than landing commits scoped `(<feature>)`.
+// null when the header is absent entirely — the pre-D4 shape (C2 back-compat).
+export function parseBuildScope(content) {
+    for (const line of content.split('\n')) {
+        const m = SCOPE_HEADER.exec(line.trim());
+        if (m === null) {
+            continue;
+        }
+        const value = (m[1] ?? '').split('<!--')[0]?.trim() ?? '';
+        return value === '' || SCOPE_PLACEHOLDER.test(value) ? null : value;
+    }
+    return null;
+}
 export function scrapeBullets(content, heading) {
     const lines = content.split('\n');
     const start = lines.findIndex((l) => l.trim() === heading);

package/dist/lib/orient.js

@@ -73,10 +73,11 @@ export function markStepDone(intent, n) {
     })
         .join('\n');
 }
-// Open questions still open: `- Q\d+:` lines that do not say "resolved".
+// Open questions still open: `- Q\d+:` openers that do not say "resolved". The
+// opener may carry a slug-at-birth gloss — `- Q2 (some-slug): ...` (D3) — which
+// the count reads through; sub-lines (`*plain:*`/`*lean:*`) never match.
 export function parseOpenQuestions(intent) {
-    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+:/.test(l.trim()) && !/resolved/i.test(l))
-        .length;
+    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+(?: \([^)]+\))?:/.test(l.trim()) && !/resolved/i.test(l)).length;
 }
 // Open parked items: `- [ ]` lines under `## Park list` (the `park` verb's format).
 // A harvested item is flipped to `- [x]` by `/pb-harvest` and no longer counts; the

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

@@ -13,9 +13,10 @@ import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, check
 import { runCheck } from "../lib/check.js";
 import { checkLatch } from "../lib/latch.js";
 import { markStepDone, parseSteps } from "../lib/orient.js";
-import { parseStepSeam, scopeDrift } from "../lib/intent.js";
+import { parseBuildScope, 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.
@@ -96,11 +101,12 @@ function checkpointPlan(root, args) {
     process.stdout.write(`plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
     return 0;
 }
-// The plan commit's CLI-owned subject (D68): `chore(<scope>): plan`, the scope drawn
-// from the active build's slug (a bare `chore: plan` when none resolves). The
-// `plumbbob plan` identifier rides the body marker, not the subject.
+// The plan commit's CLI-owned subject (D68): `chore(<scope>): plan`, the scope
+// resolved through the build-default fallback chain (a bare `chore: plan` when
+// none resolves). The `plumbbob plan` identifier rides the body marker, not the
+// subject.
 function planSubject(root) {
-    return conventionalSubject({ type: 'chore', scope: buildScope(activeBuild(root)), description: 'plan' });
+    return conventionalSubject({ type: 'chore', scope: buildDefaultScope(root), description: 'plan' });
 }
 // Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
 // intent.md. Returns null when none can be determined. A `-m` value is a message,
@@ -205,18 +211,36 @@ function statsSuffix(root, step) {
     return parts.length > 0 ? parts.join(', ') : null;
 }
 // The CLI-owned, deterministic commit subject (D68): a Conventional `type(scope):
-// description`. The scope comes from the active build's slug; the type and wording
-// come from the step's title — an author-written prefix (`fix(parser): …`) is honoured
-// verbatim, a bare title defaults to `feat`. A titleless step falls back to
-// `chore(<scope>): checkpoint`. The `plumbbob`/`step N` identifiers ride the body
-// marker, not the subject; a `-m` override or `--body` prose is a separate concern.
+// description`. The type and wording come from the step's title — an author-written
+// prefix (`fix(parser): …`) is honoured verbatim, a bare title defaults to `feat`.
+// The scope falls back through the chain (D3): the title's own `(scope)` wins
+// (handled inside `subjectFromTitle`), else `buildDefaultScope`. A titleless step
+// falls back to `chore(<scope>): checkpoint`. The `plumbbob`/`step N` identifiers
+// ride the body marker, not the subject; a `-m` override or `--body` prose is a
+// separate concern.
 function subjectForStep(root, step) {
-    const scope = buildScope(activeBuild(root));
+    const scope = buildDefaultScope(root);
     const title = titleForStep(root, step);
     return title !== null && title.trim().length > 0
         ? subjectFromTitle(title, 'feat', scope)
         : conventionalSubject({ type: 'chore', scope, description: 'checkpoint' });
 }
+// The build-default Conventional scope (D3/D4): the `**Scope:**` header field in
+// intent.md when authored and filled, else the build slug (D68's original rung,
+// now the penultimate one), else null — a bare subject (C2 back-compat: a build
+// with neither field behaves exactly as before D4).
+function buildDefaultScope(root) {
+    try {
+        const fromHeader = parseBuildScope(readFileSync(intentPath(root), 'utf8'));
+        if (fromHeader !== null) {
+            return fromHeader;
+        }
+    }
+    catch {
+        // no intent.md yet — fall through to the slug rung.
+    }
+    return buildScope(activeBuild(root));
+}
 function titleForStep(root, step) {
     try {
         return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.title ?? null;

package/dist/verbs/finish.js

@@ -9,8 +9,9 @@
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
-import { buildScope, checkpointsPath, clearTick, hasSession, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
+import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
+import { parseBuildScope } from "../lib/intent.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -34,7 +35,7 @@ export function finish(cwd, args = []) {
     if (isDirty(root)) {
         stageAll(root);
     }
-    const sha = commit(root, subject(slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
+    const sha = commit(root, subject(root, slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
     // Clear the control state: the in-flight markers first, then the session sentinel
     // last (so "no session" flips exactly at the end). Deleting STATE also drops the
     // cursor (D28) — cursor and session share the one file now, so a single delete does
@@ -54,12 +55,27 @@ export function finish(cwd, args = []) {
         'Run `/pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
     return 0;
 }
-// The CLI-owned final-commit subject (D68): `chore(<scope>): finish`, the scope drawn
-// from the build's slug (a bare `chore: finish` when none resolves, e.g. `--local`),
-// mirroring the plan/step Conventional shape so one grammar spans the whole history.
-// The `plumbbob finish` identifier rides the body marker, not the subject.
-function subject(slug) {
-    return conventionalSubject({ type: 'chore', scope: buildScope(slug), description: 'finish' });
+// The CLI-owned final-commit subject (D68): `chore(<scope>): finish`, the scope
+// resolved through the same build-default fallback chain as plan/step subjects
+// (D3/D4): the `**Scope:**` header field, else the build slug, else bare (e.g.
+// `--local`). The `plumbbob finish` identifier rides the body marker, not the
+// subject.
+function subject(root, slug) {
+    return conventionalSubject({ type: 'chore', scope: buildDefaultScope(root, slug), description: 'finish' });
+}
+// See checkpoint.ts's twin of this helper (same fallback, this verb's own `slug`
+// resolution instead of the active-build cursor).
+function buildDefaultScope(root, slug) {
+    try {
+        const fromHeader = parseBuildScope(readFileSync(intentPath(root, slug), 'utf8'));
+        if (fromHeader !== null) {
+            return fromHeader;
+        }
+    }
+    catch {
+        // no intent.md — fall through to the slug rung.
+    }
+    return buildScope(slug);
 }
 // `--body` reads the final-commit body from stdin (the single-quoted heredoc of
 // D34), so the pb-finish skill can compose a proportional close-out message. Returns

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.14",
   "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.
@@ -67,6 +74,13 @@ differs from the model you're running as, say so before implementing — the hum
    build-log's `## Log`, so the history writes itself — you only supply the body (or omit
    `--body` for the deterministic done-when + seam + diffstat fallback). Do **not** bump
    the version or changelog — that is the human's `/version` call.
+   - **A drifted subject is reconciled at the pause, never silently (D5/D6).** The planned
+     title *is* the checkpoint subject (D1). If the diff drifted from it, **present** a
+     corrected subject at the pause — `planned title → proposed subject`, one line — for
+     explicit approval, and only on approval land it by adding `-m "<subject>"` to the
+     checkpoint. Present nothing and the deterministic title-derived subject lands
+     untouched: the reconcile is the human-approved exception, not a quiet `-m` swap (which
+     is the agent-authored subject D68 refuses).
    - **If `plumbbob status` shows a `harness bindings:` block**, fold any bound
      `after`-agents into that self-review as advisory input — see **§ Running bound
      agents**.

package/skills/pb-park/SKILL.md

@@ -25,8 +25,9 @@ is fine; capture is always available, which is the whole point of parking.
 ## What this skill does
 
 Take the idea, problem, or "ooh what if" the human just had and **compose it into one
-tidy, tagged line** — short, legible, self-contained, so it still reads cleanly weeks
-later. Then:
+tidy, tagged line** — short, legible, self-contained, and carrying a **one-clause why**
+(what it is *and* why it's worth revisiting), so it still reads cleanly weeks later when
+harvest triages it cold. Then:
 
 1. **Show the composed line to the human** and wait for **in-turn approval** — they
    confirm it as-is or edit the wording.

package/skills/pb-plan/SKILL.md

@@ -58,13 +58,23 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    **explicitly NOT doing**. This is the human's convergence — propose wording, but
    the human decides every line.
 3. **Decisions & Constraints.** Record the settled calls (one line each, with the
-   *because*) and the hard rules the build must honor. An unresolved hole goes to
-   **Open questions**, never guessed into a Decision.
+   *because*) and the hard rules the build must honor. **Slug each at birth** — mint a
+   two- or three-word slug where the item is born (`D1 (default-waves): …`,
+   `C1 (no-new-deps): …`) and copy that slug at every reference site, so a later
+   mention reads `D4 (default-waves)` and stays legible: **never a bare `D4`/`C6`/`Q2`
+   reference — always carry its gloss**, so a cold reader never has to hunt the number
+   down. An unresolved hole goes to **Open questions**, never guessed into a Decision —
+   and it goes in the expanded form the template shows: a slugged opener (the hole as a
+   question), a `*plain:*` sub-line (what's at stake, in plain words, enough to judge it
+   cold), then a `*lean:*` sub-line (your proposed resolution — one answer to react to,
+   not a menu), so the human settles it in one pass without a round-trip. (A tiny,
+   obvious question may stay one bare line; the sub-lines earn their keep only when a
+   human decision genuinely waits on it.)
 4. **Author the Steps.** Write the **full build plan** under `## Steps` — each step a
    small, verifiable increment in the exact format the parser reads:
 
    ```markdown
-   1. [ ] <title> — **done when:** <criterion, ideally a test or check result>
+   1. [ ] feat(scope): <title> — **done when:** <criterion, ideally a test or check result>
       - seam: `<file>`, `<file>`
       - model: <optional — smallest that can carry it, with the one-phrase why>
    ```
@@ -74,12 +84,23 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    sharpened just-in-time when you reach them with `/pb-step`. Keep each small enough to
    verify in one review pass.
 
-   **Give the title a Conventional-Commit type where the change has one** *(optional)*:
-   a `<title>` that opens with `fix:`, `feat(escape-hatch):`, `chore:`, … becomes the
-   checkpoint's commit subject verbatim (its scope and breaking `!` honored) — this is
-   how each step lands a *real* `feat`/`fix`/`chore` in `git log`. Skip the prefix and
-   the checkpoint defaults the type to `feat` and draws the scope from the build slug, so
-   a plain title still yields a clean `feat(<slug>): <title>` ([D68](../../docs/decisions.md#d68)).
+   **The title *is* the commit subject — author it as one** *(D1)*: write each
+   `<title>` as a plain, single-line Conventional-Commit subject,
+   `type(scope): description`, and it lands in `git log` verbatim (its breaking `!`
+   honored) — this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
+   Keep load-bearing detail — file paths, module names — in `seam` and `done-when`; it is
+   **never jammed into the title** (D2), which has to read as plain English and as a clean
+   subject at once. Aim for **≤72 characters** (GitHub's subject convention) — soft
+   guidance you eyeball at plan time, no lint, no gate (D9).
+
+   **Set the build's default scope, then let steps override it** *(D8)*: fill the
+   `**Scope:**` header once with a short feature-level name — the catch-all every step
+   inherits — and give a step its own `(scope)` when it touches a distinct code area
+   (`pb-plan`, `commitmsg`, `docs`). A step's `(scope)` names the *code area*; the header
+   names the *feature*, so scopes stay consistent and greppable across builds. Scope
+   resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
+   title-type → `feat`, so a scopeless plain title still yields a clean
+   `feat(<slug>): <title>` unchanged ([D68](../../docs/decisions.md#d68), D3).
 
    **Recommend a model per step where the signal is clear** *(optional)*: the
    `- model:` sub-line names the **smallest model that can carry the step**, with the

package/skills/pb-refine/SKILL.md

@@ -27,13 +27,28 @@ is fine — refining is always available.
 - **Attack (diverge in the problem space).** Hand the **Frame**, **Decisions**, and
   **Architecture sketch** a cold, adversarial read and surface holes — ambiguities,
   unhandled edge cases, hidden assumptions, collisions with the existing code. Append
-  each as a one-line question under `## Open questions`, **never** as a Decision:
-  resolving a hole is the human's convergence, not yours. This mode surfaces; it does
-  not decide.
+  each under `## Open questions` in the expanded form the template shows — an opener
+  line (the hole as a question, slugged at birth: `- Q2 (some-slug): …`), a `*plain:*`
+  sub-line (what's at stake in plain words, enough to judge it cold), and a `*lean:*`
+  sub-line (your proposed resolution — one answer to react to, not a menu). Never
+  append a hole as a Decision: resolving it is the human's convergence, not yours —
+  the lean proposes; this mode surfaces, it does not decide. (A tiny, obvious question
+  may stay one bare line; the sub-lines earn their keep only when a human decision
+  genuinely waits on it.)
+
+  Then walk the human through it in the chat: list every hole you appended, each as
+  its explanation first and its lean second, and invite per-question answers — the
+  human can settle any of them right there in one message, no doc-flipping, no extra
+  round-trip per hole.
 - **Repair (re-sync to reality).** When the plan has drifted — a Decision was overtaken
-  by what you built, a Constraint changed, a Step no longer matches the seam — propose
-  the edits that bring `intent.md` back in line with the truth. Show the before/after for
-  each, and **write only what the human approves**.
+  by what you built, a Constraint changed, a Step no longer matches the seam, or a
+  **step's title no longer describes what the diff actually does** — propose the edits
+  that bring `intent.md` back in line with the truth. A step title *is* its checkpoint
+  commit subject (D1), so bringing a drifted one back in line means keeping it a plain,
+  single-line `type(scope): description` subject, with load-bearing detail (file paths,
+  module names) in `seam` and `done-when`, **never jammed into the title** (D2) — the
+  checkpoint body pass then reconciles and lands that subject at the verify pause (D5).
+  Show the before/after for each, and **write only what the human approves**.
 
 ## The hard contracts
 

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/skills/pb-step/SKILL.md

@@ -39,11 +39,16 @@ grew — but its everyday job is to sharpen, not to invent.
    a step that sharpened into rote work can drop to a smaller model; one that grew subtle
    earns a frontier one. Advisory, plain text (no backticks), never a gate.
 3. **Get the human's OK**, then write it into `## Steps` in the standard format —
-   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Give the
-   `<title>` an optional Conventional-Commit prefix (`fix:`, `feat(scope):`, …) when the
-   change has a clear type — it becomes the checkpoint's commit subject; a plain title
-   defaults to `feat` with the build slug as scope ([D68](../../docs/decisions.md#d68)).
-   Revise the existing step in place; only append when you are genuinely adding an increment.
+   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Keep the
+   sharpened `<title>` a plain, single-line Conventional-Commit subject,
+   `type(scope): description` — it lands in `git log` verbatim, so as the step tightens
+   keep load-bearing detail (file paths, module names) in `seam` and `done-when`,
+   **never jammed into the title** (D1/D2). A sharpened step carries its own `(scope)`
+   when it touches a distinct code area — one that **overrides the build-default**
+   `**Scope:**` header; drop the scope and it falls back to that default → build slug →
+   bare, and the type to `feat` ([D68](../../docs/decisions.md#d68), D8). Aim for a soft
+   ≤72 chars, no gate (D9). Revise the existing step in place; only append when you are
+   genuinely adding an increment.
 4. **Revise the step's harness bindings if they drifted too** *(optional)*. If the
    build carries a `harness.json` (beside `intent.md`) and the reality that moved the
    step also changed which agents it wants, sharpen that step's slot bindings

package/skills/pb-verify/SKILL.md

@@ -45,6 +45,14 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    findings), and the validation, then
    **stop and wait for the human's explicit approval.** This is the convergence beat;
    the human is the clock. Never checkpoint without it.
+   - **Reconcile a drifted subject here, in the open (D5).** The planned title *is* the
+     checkpoint subject (D1). If the diff drifted from it — the step landed something the
+     title no longer describes — the body pass may propose a corrected subject, but it
+     **presents** it at this pause for explicit approval: show `planned title → proposed
+     subject`, one line, as part of what the human OKs. This is the exception, not the
+     default (D6): with **nothing presented**, the deterministic title-derived subject
+     lands untouched. A silent `-m` swap is exactly the agent-authored subject D68 refuses
+     — so a reconcile is *only ever* the visible, approved kind.
 6. **Checkpoint** *(only after approval)*. Run `plumbbob checkpoint`: it makes the WIP
    commit, records the SHA, flips the step to done, appends the step to the build-log's
    `## Log`, and returns to DESIGN. The CLI owns the commit **subject** — a Conventional
@@ -62,7 +70,10 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    Do **not** run a TIL scan or reach for a separate commit skill — the body is yours to
    write in one breath. Omit `--body` entirely and the CLI writes a deterministic body
    (done-when + seam + diffstat) on its own. Either way, do **not** bump the version or
-   touch the changelog — that is the human's `/version` call.
+   touch the changelog — that is the human's `/version` call. And if step 5 surfaced a
+   drifted subject the human approved, land *that* subject by adding `-m "<subject>"` —
+   overriding the title-derived default for this one commit; unpresented, the CLI's
+   deterministic subject stands.
 7. **Hand off with the next model** *(once the checkpoint lands)*. `plumbbob checkpoint`
    returns to DESIGN; then run `plumbbob handoff` and relay its boundary block. With the
    step gone from in-flight it renders `step N checkpointed — back at the boundary` and

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/intent.md

@@ -5,12 +5,18 @@ head; the chat is the hand. When the model floods you, read this, not your memor
 Size to the work: a small change fills Frame + a couple of Decisions and deletes
 the rest; a medium feature fills it all. Opinionated where decided, explicit where
 open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
+
+One rule runs through the whole doc: compress what's settled; expand what's pending.
+Decisions and Constraints stay one line each — they re-inject into every build step,
+so their tokens recur. Open questions expand into plain-then-lean prose — a human
+reads them once, to decide, and that legibility buys back a chat round-trip.
 -->
 
 # {{TITLE}}
 
 **Phase** (your own bookkeeping while framing): frame
 **Size:** tiny | small | medium
+**Scope:** <short-scope>  <!-- the build's default commit scope (D4): a short feature-level name each step's own `(scope)` overrides. Leave the `<…>` placeholder (or blank) and it parses as absent — commits fall through to the build slug (D7). -->
 
 ## Frame
 
@@ -31,16 +37,20 @@ open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
 
 ## Decisions
 
-*(One line each. Settled, not re-litigated in the chat. Grows as you resolve the
-holes `/pb-refine` surfaces, and as blockers fold in during BUILD.)*
+*(One line each — settled, not re-litigated in the chat. Grows as you resolve the
+holes `/pb-refine` surfaces, and as blockers fold in during BUILD. Mint a two- or
+three-word slug where each item is born — `D1 (slug-here)` — and copy that slug at
+every reference site, so a later `D4 (default-waves)` never decays into a bare `D4`
+a cold reader has to hunt down.)*
 
-- D1: <decision> — *because* <the one reason that mattered>
+- D1 (slug-here): <decision> — *because* <the one reason that mattered>
 
 ## Constraints
 
-*(Hard rules the build must honor. `/pb-verify` and `/pb-refine` read against these.)*
+*(Hard rules the build must honor. `/pb-verify` and `/pb-refine` read against these.
+Slug and gloss them at birth too — `C1 (no-new-deps)` — same one line, same rule.)*
 
-- C1: <e.g. functional/procedural only; no new dependencies>
+- C1 (no-new-deps): <e.g. functional/procedural only; no new dependencies>
 
 ## Steps
 
@@ -50,9 +60,13 @@ which `/pb-build` records in the build folder's `SEAM` for orientation — aware
 An optional **model** line recommends the smallest model that can carry the step —
 mechanical work runs fine on a small model; subtle or creative work earns a frontier
 one. Advisory for the human, never a gate; write it plain, no backticks (D62).
-A step title may open with a Conventional-Commit type (`fix:`, `feat(scope):`) — it
-becomes the checkpoint's commit subject; skip it and the subject defaults to `feat`,
-scoped by the build slug (D68). Then drive `/pb-build` until done. Later steps may be
+The step title *is* the checkpoint's commit subject: write it as one plain line,
+`type(scope): description` — load-bearing paths live in `seam`, never jammed into the
+title (D2) — aiming for ≤72 characters (GitHub's subject convention: soft, no gate, D9).
+The `(scope)` names the primary code area the step touches (`pb-plan`, `commitmsg`); the
+build's `**Scope:**` header is the feature-level catch-all a step overrides (D8). Scope
+resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
+title-type → `feat` (D3/D68). Then drive `/pb-build` until done. Later steps may be
 fuzzier than the first; sharpen the next one just-in-time with `/pb-step` (empty input
 auto-syncs it), and use `/pb-refine` to repair the whole plan when a blocker rewrites it.)*
 
@@ -64,10 +78,40 @@ auto-syncs it), and use `/pb-refine` to repair the whole plan when a blocker rew
 
 ## Open questions
 
-*(Holes you could NOT resolve on paper. Do not guess them into Decisions. A genuine
-fork goes to a SPIKE; record the verdict below and in Decisions.)*
+*(Holes you could NOT resolve on paper — the one section that expands rather than
+compresses. Do not guess them into Decisions; a genuine fork goes to a SPIKE, with
+the verdict recorded below and in Decisions.)*
+
+<!--
+Write each open question so a cold reader could answer it without flipping back to
+the code or the chat — that cold-reader test is the whole point of expanding it.
+Three lines:
+
+  · the opener — the hole as a question, slugged at birth, tagged
+    *resolve by:* decide | spike | ask
+  · *plain:* — what's at stake, in plain words: the context and the cost of getting
+    it wrong, enough to judge it cold
+  · *lean:* — the model's proposed resolution: one answer to react to, not a menu
+
+The human reads *plain* to understand, then *lean* to approve or redirect — one
+pass, no round-trip.
+
+When a question resolves, swap *resolve by:* for *resolved:* <date, the call> ON THE
+OPENER LINE, e.g.
+
+  - Q3 (default-waves): *resolved:* 2026-07-18, default off
+
+The status counter reads opener lines only, so a *resolved:* left on a *plain:* or
+*lean:* sub-line leaves the question still counted as open.
+
+Size to the work: a tiny build's single, obvious question may stay one bare line —
+the *plain:*/*lean:* pair earns its keep only when a human decision genuinely waits
+on it.
+-->
 
-- Q1: <unresolved> — *resolve by:* decide | spike | ask
+- Q1 (slug-here): <the unresolved hole, framed as a question> — *resolve by:* decide | spike | ask
+  - *plain:* <what's at stake, in plain words — enough to judge it cold>
+  - *lean:* <the model's proposed resolution — the answer to react to>
 
 ## Verdicts
 

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.)*