plumbbob 0.8.11 → 0.8.13

package/.claude-plugin/plugin.json

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

@@ -0,0 +1,72 @@
+// Conventional-Commit subject assembly (D68). Plumbbob's commit subjects read as
+// `type(scope): description` — real feat/fix/chore types and a real parenthesised
+// scope — so `git log` speaks the same grammar as the rest of the branch. The
+// `plumbbob`/`step N` identifiers that used to prefix the subject (the old D34
+// shape) now ride a marker line at the head of the body, which `withMarker`
+// prepends — so `git log --grep plumbbob` still finds every plumbbob commit.
+// Functional/procedural, node-builtins-only (C1/C2), no gate: these only shape a
+// string the CLI is about to commit.
+// The Conventional-Commit type vocabulary plumbbob recognises as a leading prefix
+// on a step title. Anchoring on this closed set keeps a prose title like
+// `Note: rewire the cache` from being misread as a `Note` type — only these words,
+// immediately followed by an optional `(scope)`, an optional `!`, and a colon,
+// count as an author-supplied prefix.
+const TYPES = ['feat', 'fix', 'chore', 'docs', 'refactor', 'test', 'perf', 'build', 'ci', 'style', 'revert'];
+const PREFIX = new RegExp(`^(${TYPES.join('|')})(?:\\(([^)]+)\\))?(!)?:\\s+(.+)$`);
+// Split an optional Conventional prefix off a step title. `feat(escape-hatch): add
+// the flag` → { type:'feat', scope:'escape-hatch', breaking:false, description:'add
+// the flag' }. A title with no recognised prefix comes back whole as the
+// description with a null type/scope — the caller then defaults the type and fills
+// the scope from the build.
+export function parseConventionalTitle(title) {
+    const m = PREFIX.exec(title.trim());
+    if (m === null) {
+        return { type: null, scope: null, breaking: false, description: title.trim() };
+    }
+    return { type: m[1] ?? null, scope: m[2] ?? null, breaking: m[3] === '!', description: (m[4] ?? '').trim() };
+}
+// Assemble a `type(scope)!: description` subject, omitting the `(scope)` segment
+// when there is no scope (Conventional Commits allow a bare `type: description`)
+// and the `!` when the change is not breaking.
+export function conventionalSubject(parts) {
+    const scope = parts.scope ? `(${parts.scope})` : '';
+    const bang = parts.breaking ? '!' : '';
+    return `${parts.type}${scope}${bang}: ${parts.description}`;
+}
+// A Conventional subject from a step title, filling gaps from the build. An
+// author-written prefix (`fix(parser): …`) is honoured verbatim — its type, scope,
+// breaking marker, and exact wording all win. A bare prose title defaults to
+// `defaultType` and the build `scope`, and gets its sentence-case opener
+// de-capitalised (`Add the flag` → `add the flag`) to match Conventional style —
+// while an all-caps acronym start (`API`, `OAuth`) is left alone.
+export function subjectFromTitle(title, defaultType, scope) {
+    const parsed = parseConventionalTitle(title);
+    if (parsed.type !== null) {
+        return conventionalSubject({
+            type: parsed.type,
+            scope: parsed.scope ?? scope,
+            breaking: parsed.breaking,
+            description: parsed.description,
+        });
+    }
+    return conventionalSubject({ type: defaultType, scope, description: lowerFirst(parsed.description) });
+}
+// Prepend a marker line (`plumbbob step 1`, `plumbbob plan`, `plumbbob finish`) to
+// an optional body, separated by a blank line so git keeps them as distinct
+// paragraphs. Always returns at least the marker, so every plumbbob commit carries
+// the greppable identifier in its body even when the prose is empty.
+export function withMarker(marker, body) {
+    const rest = body?.trim();
+    return rest !== undefined && rest.length > 0 ? `${marker}\n\n${rest}` : marker;
+}
+// De-capitalise a sentence-case opener but leave an acronym/proper all-caps start
+// (`API`, `OAuth`) intact: lowercase the first character only when it is uppercase
+// and the second character is not (so `Add` → `add`, but `API` stays `API`).
+function lowerFirst(text) {
+    const a = text[0] ?? '';
+    const b = text[1] ?? '';
+    if (a >= 'A' && a <= 'Z' && b >= 'A' && b <= 'Z') {
+        return text;
+    }
+    return a >= 'A' && a <= 'Z' ? a.toLowerCase() + text.slice(1) : text;
+}

package/dist/lib/sidecar.js

@@ -40,6 +40,18 @@ export function slugify(title) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+// The Conventional-Commit scope for a build (D68): its slug with the `YYYY-MM-DD-`
+// date prefix `start` prepends stripped off, so `2026-07-18-escape-hatch` yields the
+// human-meaningful `escape-hatch`. Null when no build resolves (`--local`, or a slug
+// that is nothing but a date) — the caller then omits the `(scope)` segment, which
+// Conventional Commits permit.
+export function buildScope(slug) {
+    if (slug === null) {
+        return null;
+    }
+    const stripped = slug.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+    return stripped.length > 0 ? stripped : null;
+}
 // Existing build slugs — the directory names under `builds/`, sorted. Empty when
 // `builds/` is absent (a `--local` repo, or before the first tracked `start`).
 export function listBuilds(root) {
@@ -146,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

@@ -9,12 +9,14 @@
 // the same way.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { buildFolder, buildLogPath, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { checkLatch } from "../lib/latch.js";
-import { markStepDone, parseSteps, parseTitle } from "../lib/orient.js";
+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)) {
@@ -53,7 +55,7 @@ export async function checkpoint(cwd, args) {
     if (isDirty(root)) {
         stageAll(root);
         warnScopeDrift(root, step);
-        const body = bodyArg(args) ?? fallbackBody(root, step);
+        const body = withMarker(`plumbbob step ${step}`, bodyArg(args) ?? fallbackBody(root, step));
         sha = commit(root, messageArg(args) ?? subjectForStep(root, step), body);
     }
     else {
@@ -63,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.
@@ -71,12 +77,12 @@ export async function checkpoint(cwd, args) {
     return 0;
 }
 // The plan-approval commit (D36): stage only the active build's artifact folder and
-// commit it as `plumbbob: plan — <title>`, then record a `plan <sha>` line. Giving
+// commit it as `chore(<scope>): plan` (D68), then record a `plan <sha>` line. Giving
 // the plan its own commit keeps the first step's diff from absorbing the scaffold, so
 // `git log` reads baseline → plan → steps. No check gate (there is no code work to
 // verify yet), no intent flip, no step markers — the plan lives entirely in DESIGN.
-// An optional `--body` (stdin heredoc, D34) rides along; the folder is whitelisted
-// artifact plane, so there is no scope-drift to warn about.
+// An optional `--body` (stdin heredoc, D68) rides after the `plumbbob plan` marker;
+// the folder is whitelisted artifact plane, so there is no scope-drift to warn about.
 function checkpointPlan(root, args) {
     // The latch (D64) covers the plan commit too, keyed on the TICK that `start`
     // stamped: the plan pause is a pause. No step number — a range grant does not
@@ -87,7 +93,7 @@ function checkpointPlan(root, args) {
         return 1;
     }
     stagePath(root, buildFolder(root));
-    const sha = commit(root, planSubject(root), bodyArg(args) ?? undefined);
+    const sha = commit(root, planSubject(root), withMarker('plumbbob plan', bodyArg(args) ?? undefined));
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
     // The plan landing consumes `start`'s entry stamp (D64): a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
@@ -95,17 +101,11 @@ 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: the intent's `# <title>`, else a bare
-// `plumbbob: plan` when the title can't be read (mirrors `subjectForStep`'s fallback).
+// 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.
 function planSubject(root) {
-    let title = null;
-    try {
-        title = parseTitle(readFileSync(intentPath(root), 'utf8'));
-    }
-    catch {
-        title = null;
-    }
-    return title ? `plumbbob: plan — ${title}` : 'plumbbob: plan';
+    return conventionalSubject({ type: 'chore', scope: buildScope(activeBuild(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,
@@ -209,12 +209,18 @@ function statsSuffix(root, step) {
     }
     return parts.length > 0 ? parts.join(', ') : null;
 }
-// The CLI-owned, deterministic commit subject: the step's title when intent.md still
-// carries one, else the bare `plumbbob: step N done` fallback (D34 — the CLI owns the
-// subject; a `-m` override or `--body` prose is a separate concern).
+// 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.
 function subjectForStep(root, step) {
+    const scope = buildScope(activeBuild(root));
     const title = titleForStep(root, step);
-    return title ? `plumbbob: step ${step} — ${title}` : `plumbbob: step ${step} done`;
+    return title !== null && title.trim().length > 0
+        ? subjectFromTitle(title, 'feat', scope)
+        : conventionalSubject({ type: 'chore', scope, description: 'checkpoint' });
 }
 function titleForStep(root, step) {
     try {

package/dist/verbs/finish.js

@@ -1,15 +1,16 @@
-// `plumbbob finish` (D9/D34) — the close-out: append the checkpoint SHAs to the
+// `plumbbob finish` (D9/D68) — the close-out: append the checkpoint SHAs to the
 // report, make the final commit, and clear the control state. The build folder is
 // NOT deleted — it IS the archive now (D29): tracked, it merges with the branch and
 // shows up in the PR, so nothing is copied into a local-only `archive/` (that
 // helper retired with this step). No refuse-without-report gate — guidance offers
 // the artifact, it does not wall the exit (D9). Git footprint stays additive (C5):
-// one forward commit under the greppable `plumbbob: finish — <title>` subject.
+// one forward commit under the Conventional `chore(<scope>): finish` subject, its
+// `plumbbob finish` identifier riding the body marker (D68).
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
-import { checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
-import { parseTitle } from "../lib/orient.js";
+import { buildScope, checkpointsPath, clearTick, hasSession, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
+import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -33,7 +34,7 @@ export function finish(cwd, args = []) {
     if (isDirty(root)) {
         stageAll(root);
     }
-    const sha = commit(root, subject(root, slug), bodyArg(args) ?? undefined);
+    const sha = commit(root, subject(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
@@ -53,18 +54,12 @@ 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 (D34): `plumbbob: finish — <title>`, mirroring
-// the step-checkpoint format exactly so one greppable shape spans the whole history.
-// Falls back to a bare `plumbbob: finish` when intent.md carries no title.
-function subject(root, slug) {
-    let title = null;
-    try {
-        title = parseTitle(readFileSync(intentPath(root, slug), 'utf8'));
-    }
-    catch {
-        title = null;
-    }
-    return title ? `plumbbob: finish — ${title}` : 'plumbbob: finish';
+// 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' });
 }
 // `--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.11",
+  "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-finish/SKILL.md

@@ -29,8 +29,9 @@ record.
    - **Deferred tangents** — the harvested items that become future work.
    This is the "yeah, I did that" artifact. Write it by default; the human may edit it.
 2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
-   report and makes the final commit — subject `plumbbob: finish — <title>`,
-   with an optional proportional body via `--body` (the stdin heredoc) — then
+   report and makes the final commit — subject `chore(<scope>): finish`, its body
+   led by a `plumbbob finish` marker plus an optional proportional `--body` (the
+   stdin heredoc) — then
    clears the control state (the in-flight markers, then `STATE` last — one delete
    drops both the session sentinel and the active-build cursor it carries). The
    build folder stays in place, committed, and rides the branch into the PR.

package/skills/pb-plan/SKILL.md

@@ -74,6 +74,13 @@ 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)).
+
    **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
    one-phrase why — the human buys capability only where the step needs it. E.g.
@@ -106,7 +113,8 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    up automatically (it lives in the build folder).
 6. **Commit the plan.** Once the human approves the frame and steps, run
    `plumbbob checkpoint --plan` to commit the scaffold on its own — subject
-   `plumbbob: plan — <title>`, only `.plumbbob/builds/<slug>/`, a `plan <sha>` line in
+   `chore(<scope>): plan` (with a `plumbbob plan` body marker), only `.plumbbob/builds/<slug>/`,
+   a `plan <sha>` line in
    `checkpoints`. This keeps the first step's diff clean, so history reads
    baseline → plan → steps. Pass a proportional `--body` (the single-quoted stdin
    heredoc) when the rationale is worth carrying; skip it for a small plan. Do this

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,8 +39,11 @@ 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. 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. 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.
 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

@@ -47,10 +47,11 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    the human is the clock. Never checkpoint without it.
 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**
-   (`plumbbob: step N — <title>`); you own the **body**. Compose a body *proportional to
-   the step* — a one-liner for a trivial change, a short paragraph on the what/why for a
-   meatier one — and pass it on stdin:
+   `## Log`, and returns to DESIGN. The CLI owns the commit **subject** — a Conventional
+   `<type>(<scope>): <description>` composed from the step title and the build slug — and
+   leads the **body** with a `plumbbob step N` marker; you own the rest of the **body**.
+   Compose a body *proportional to the step* — a one-liner for a trivial change, a short
+   paragraph on the what/why for a meatier one — and pass it on stdin:
 
    ```bash
    plumbbob checkpoint <n> --body <<'BODY'

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

@@ -50,11 +50,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).
-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.)*
+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
+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.)*
 
-1. [ ] <step> — **done when:** <criterion, ideally a test or check result>
+1. [ ] feat: <step> — **done when:** <criterion, ideally a test or check result>
    - seam: `<file>`, `<file>`
    - model: <smallest that can carry it, e.g. sonnet — mechanical, fully specified>
 2. [ ] <step> — **done when:** <criterion>

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