plumbbob 0.4.13 → 0.5.3

package/dist/verbs/doctor.js

@@ -1,16 +1,36 @@
-// `plumbbob doctor` — diagnose the global plugin link end to end. Read-only: it
-// inspects, it never writes. After `plumbbob init`, plumbbob lives as a symlink at
-// ~/.claude/skills/plumbbob pointing at the installed package; Claude Code loads it
-// in place as a plugin (skills `/plumbbob:*`, the post-edit hook from hooks.json).
-// doctor verifies the link resolves to a package carrying the manifest, the skills,
-// and the hook — and names the fix for anything missing. The failure class it
-// exists for is SILENT (a `/plumbbob:pb-status` that opens an empty dashboard because the
-// plugin never linked). Functional, node builtins only (C1/C2).
-import { existsSync, lstatSync, readdirSync, readlinkSync } from 'node:fs';
+// `plumbbob doctor` — two diagnostics under one verb.
+//
+// 1. The global plugin link (read-only). After `plumbbob init`, plumbbob lives as a
+//    symlink at ~/.claude/skills/plumbbob pointing at the installed package; Claude
+//    Code loads it in place as a plugin (skills `/plumbbob:*`, the post-edit hook from
+//    hooks.json). doctor verifies the link resolves to a package carrying the manifest,
+//    the skills, and the hook — and names the fix for anything missing. The failure
+//    class it exists for is SILENT (a `/plumbbob:pb-status` that opens an empty dashboard
+//    because the plugin never linked).
+//
+// 2. The repo sidecar layout. A repo scaffolded by a pre-restructure plumbbob carries a
+//    legacy FLAT sidecar (`.plumbbob/intent.md`, `config`, `archive/`) fully git-excluded.
+//    doctor detects it and, with `--migrate`, moves it into the tracked `builds/<slug>/`
+//    layout (D31): archive entries and the active session become build folders, `config`
+//    becomes `settings.json`, and the whole move is STAGED but never committed — the human
+//    owns that commit (Q8). The move is the one that turns a build's record from local-only
+//    (dies with `git worktree remove`) into a tracked folder that rides the branch into
+//    the PR (supersedes D20).
+//
+// 3. The check gate (D32). When a `check` setting overrides checkride, doctor names the
+//    command; otherwise it runs checkride's own doctor and prints the slot/adapter table —
+//    "detected but tool missing" is the footgun this exists for.
+//
+// Functional, node builtins plus checkride (C1/C2).
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { runDoctor } from 'checkride';
 import { marketplacePlumbbob } from "../lib/plugins.js";
+import { findRepoRoot, gitPath, stagePath } from "../lib/git.js";
+import { buildDir, excludeControl, listBuilds, sidecarDir, slugify } from "../lib/sidecar.js";
+import { resolveString, settingsPath, setLocalSetting } from "../lib/settings.js";
 // The plumbbob package's own skills/ dir (the canonical set), off this module's
 // URL so it resolves the same from src/ (dev) and dist/ (published).
 function packageDir(name) {
@@ -54,34 +74,254 @@ function buildChecks(link, pkg, shipped) {
             : { ok: false, label: 'hook missing (hooks/hooks.json)', fix: 're-link: plumbbob init' },
     ];
 }
-export function doctor() {
+// The plugin-link diagnostic: the checks to print plus how many failed.
+function pluginChecks() {
     const home = process.env.HOME ?? homedir();
     const link = join(home, '.claude', 'skills', 'plumbbob');
     const shipped = listSkills(packageDir('skills'));
     const pkg = linkedPackage(link);
     const market = marketplacePlumbbob(home);
-    let checks;
     if (pkg === null) {
-        checks =
-            market.length > 0
-                ? [{ ok: true, label: `installed via marketplace (${market.join(', ')}) — skills load as /plumbbob:*, the CLI is on PATH from the plugin bin/. No init needed.` }]
-                : [{ ok: false, label: `not linked — no plugin at ${link}`, fix: 'install the marketplace plugin (/plugin install plumbbob@<marketplace>) or run: plumbbob init' }];
-    }
-    else {
-        checks = buildChecks(link, pkg, shipped);
-        if (market.length > 0) {
-            checks.unshift({
-                ok: false,
-                label: `collision — also installed via marketplace (${market.join(', ')}); two plugins named plumbbob fight over /plumbbob:* and skills can drop to flat names`,
-                fix: 'keep one — `plumbbob init --uninstall` to use the marketplace plugin, or `/plugin uninstall` the marketplace one to keep this link',
-            });
+        return market.length > 0
+            ? [{ ok: true, label: `installed via marketplace (${market.join(', ')}) — skills load as /plumbbob:*, the CLI is on PATH from the plugin bin/. No init needed.` }]
+            : [{ ok: false, label: `not linked — no plugin at ${link}`, fix: 'install the marketplace plugin (/plugin install plumbbob@<marketplace>) or run: plumbbob init' }];
+    }
+    const checks = buildChecks(link, pkg, shipped);
+    if (market.length > 0) {
+        checks.unshift({
+            ok: false,
+            label: `collision — also installed via marketplace (${market.join(', ')}); two plugins named plumbbob fight over /plumbbob:* and skills can drop to flat names`,
+            fix: 'keep one — `plumbbob init --uninstall` to use the marketplace plugin, or `/plugin uninstall` the marketplace one to keep this link',
+        });
+    }
+    return checks;
+}
+// Read a directory's immediate sub-directory names, sorted; [] when it is absent.
+function subdirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// Detect a legacy flat sidecar, or null when the repo is already on the new layout
+// (or has no sidecar). `config` and `archive/` are unambiguous pre-restructure markers
+// — the new layout has neither. A flat `intent.md` alone would also match today's
+// `--local` layout, so it only counts as legacy when the repo is NOT already migrated
+// (no `builds/`, no `settings.json`): that guard is what keeps `--local` untouched.
+export function inspectLegacy(root) {
+    const dir = sidecarDir(root);
+    if (!existsSync(dir))
+        return null;
+    const config = existsSync(join(dir, 'config'));
+    const archive = subdirs(join(dir, 'archive'));
+    const migrated = existsSync(join(dir, 'builds')) || existsSync(settingsPath(root));
+    const session = existsSync(join(dir, 'intent.md')) && !migrated;
+    if (!config && archive.length === 0 && !session)
+        return null;
+    return { config, archive, session };
+}
+// The first `# Heading` in a flat intent.md — the build title the slug derives from.
+function titleFromIntent(path) {
+    try {
+        for (const line of readFileSync(path, 'utf8').split('\n')) {
+            const m = line.match(/^#\s+(.+?)\s*$/);
+            if (m)
+                return m[1] ?? '';
         }
     }
+    catch {
+        /* fall through to the empty default */
+    }
+    return '';
+}
+// The `check=<cmd>` line from a legacy `.plumbbob/config`, or null when absent.
+function configCheck(path) {
+    try {
+        for (const line of readFileSync(path, 'utf8').split('\n')) {
+            const m = line.match(/^\s*check\s*=\s*(.+?)\s*$/);
+            if (m && (m[1] ?? '').length > 0)
+                return m[1] ?? null;
+        }
+    }
+    catch {
+        /* fall through to null */
+    }
+    return null;
+}
+// A slug not already claimed by `taken`, suffixing `-2`, `-3`, … only on collision.
+// `start` refuses on collision (D38), but migration is mechanically moving folders that
+// already exist, so it disambiguates rather than aborting mid-move.
+function uniqueSlug(base, taken) {
+    const slug = base.length > 0 ? base : 'migrated-build';
+    if (!taken.has(slug))
+        return slug;
+    let n = 2;
+    while (taken.has(`${slug}-${n}`))
+        n += 1;
+    return `${slug}-${n}`;
+}
+// Move whichever of `names` exist from `from/` into `to/`.
+function moveInto(from, to, names) {
+    mkdirSync(to, { recursive: true });
+    for (const name of names) {
+        const src = join(from, name);
+        if (existsSync(src))
+            renameSync(src, join(to, name));
+    }
+}
+// Drop the blanket `.plumbbob/` line the legacy layout wrote to info/exclude, then add
+// the narrowed control-plane patterns (D17) — so the moved `builds/` and `settings.json`
+// become trackable while the per-worktree control files stay excluded.
+function narrowExcludes(root) {
+    const exclude = gitPath(root, 'info/exclude');
+    try {
+        const kept = readFileSync(exclude, 'utf8')
+            .split('\n')
+            .filter((line) => {
+            const t = line.trim();
+            return t !== '.plumbbob/' && t !== '.plumbbob';
+        });
+        writeFileSync(exclude, kept.join('\n'));
+    }
+    catch {
+        /* no exclude yet — excludeControl creates it */
+    }
+    excludeControl(root);
+}
+// Perform the migration and return a human-readable list of what moved. STAGES the
+// result but never commits (Q8). Returns the actions so doctor can print them; call
+// only when `inspectLegacy` reported a legacy layout.
+export function migrateSidecar(root) {
+    const dir = sidecarDir(root);
+    const actions = [];
+    const taken = new Set(listBuilds(root));
+    // config → settings.json (only when the new file is not already present).
+    const configPath = join(dir, 'config');
+    if (existsSync(configPath)) {
+        if (!existsSync(settingsPath(root))) {
+            const check = configCheck(configPath);
+            const settings = check === null ? { auto: false } : { check, auto: false };
+            writeFileSync(settingsPath(root), `${JSON.stringify(settings, null, 2)}\n`);
+            actions.push(check === null ? 'config → settings.json' : `config → settings.json (check: ${check})`);
+        }
+        rmSync(configPath, { force: true });
+    }
+    // The flat active session → its own build folder, and the cursor points at it: it is
+    // the one in-flight build (D28). Migrate it first so it keeps the slug from its title.
+    const flatIntent = join(dir, 'intent.md');
+    if (existsSync(flatIntent)) {
+        const slug = uniqueSlug(slugify(titleFromIntent(flatIntent)), taken);
+        taken.add(slug);
+        moveInto(dir, buildDir(root, slug), ['intent.md', 'build-log.md', 'checkpoints', 'STEP', 'SEAM', 'SPIKE']);
+        setLocalSetting(root, 'activeBuild', slug);
+        actions.push(`active session → builds/${slug} (the cursor)`);
+    }
+    // archive/<slug> → builds/<slug>. These are "done" by simply not being the cursor.
+    const archiveDir = join(dir, 'archive');
+    for (const name of subdirs(archiveDir)) {
+        const slug = uniqueSlug(slugify(name) || name, taken);
+        taken.add(slug);
+        const target = buildDir(root, slug);
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(join(archiveDir, name), target);
+        actions.push(`archive/${name} → builds/${slug}`);
+    }
+    rmSync(archiveDir, { recursive: true, force: true });
+    narrowExcludes(root);
+    stagePath(root, '.plumbbob');
+    actions.push('staged the move (builds/ + settings.json) — commit it yourself');
+    return actions;
+}
+// The sidecar section: legacy detection + the offer, or the migration report under
+// `--migrate`. Returns the lines to print and how many problems it found (an
+// un-migrated legacy layout counts as one, so the exit code flags it).
+function sidecarReport(cwd, migrate) {
+    const root = findRepoRoot(cwd);
+    const legacy = root === null ? null : inspectLegacy(root);
+    if (root === null || legacy === null)
+        return { lines: [], failed: 0 };
+    const lines = ['', 'plumbbob doctor — sidecar layout'];
+    if (migrate) {
+        for (const action of migrateSidecar(root))
+            lines.push(`  ✓ ${action}`);
+        lines.push('  migrated. Review with `git status`, then commit the staged move yourself.');
+        return { lines, failed: 0 };
+    }
+    const parts = [];
+    if (legacy.session)
+        parts.push('an active session');
+    if (legacy.archive.length > 0)
+        parts.push(`${legacy.archive.length} archived build(s)`);
+    if (legacy.config)
+        parts.push('a config file');
+    lines.push(`  ✗ legacy flat sidecar detected at .plumbbob/ (${parts.join(', ')}) — the pre-builds/ layout`);
+    lines.push('      → move it into the tracked builds/ layout: plumbbob doctor --migrate');
+    lines.push('        (archive/ + the active session → builds/, config → settings.json; staged, never committed)');
+    return { lines, failed: 1 };
+}
+// The check-gate section (D32): a configured `check` setting names the spawn
+// override and asks nothing more; otherwise checkride's own doctor reports the
+// slot/adapter table. Only rows checkride marks `required` count as problems —
+// an empty slot ("no tool detected") is informational, not a failure, because
+// the runtime gate already refuses a vacuous run.
+async function gateReport(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null)
+        return { lines: [], failed: 0 };
+    const lines = ['', 'plumbbob doctor — check gate (D32)'];
+    const command = resolveString(root, 'check', '');
+    if (command.length > 0) {
+        lines.push(`  ✓ gate: '${command}' — the "check" setting overrides checkride`);
+        return { lines, failed: 0 };
+    }
+    try {
+        const silent = { write: () => true };
+        const { report } = await runDoctor({ cwd: root, stdout: silent });
+        let failed = 0;
+        for (const c of report.checks) {
+            if (c.category === 'tool') {
+                lines.push(toolRow(c));
+            }
+            else if (c.required && c.status !== 'ok') {
+                lines.push(`  ✗ ${c.name}${c.hint === null ? '' : `\n      → ${c.hint}`}`);
+            }
+            if (c.required && c.status !== 'ok')
+                failed += 1;
+        }
+        return { lines, failed };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { lines: [...lines, `  ✗ checkride doctor failed — ${message}`], failed: 1 };
+    }
+}
+// One slot line: `✓ types ← tsc (6.0.3)`, `✗ dead ← fallow` with its install
+// hint, or `○ spell — no tool detected` for an empty (skipping) slot.
+function toolRow(c) {
+    if (c.adapter === null || c.adapter === undefined) {
+        return `  ○ ${c.slot ?? c.name} — ${c.hint ?? 'no tool detected (slot skips)'}`;
+    }
+    const mark = c.status === 'ok' ? '✓' : '✗';
+    const version = c.found === null ? '' : ` (${c.found})`;
+    const hint = c.status !== 'ok' && c.hint !== null ? `\n      → ${c.hint}` : '';
+    return `  ${mark} ${c.slot ?? c.name} ← ${c.adapter}${version}${hint}`;
+}
+export async function doctor(cwd, args = []) {
+    const checks = pluginChecks();
     const out = ['plumbbob doctor — plugin install'];
     for (const c of checks) {
         out.push(c.ok ? `  ✓ ${c.label}` : `  ✗ ${c.label}\n      → ${c.fix}`);
     }
-    const failed = checks.filter((c) => !c.ok).length;
+    const sidecar = sidecarReport(cwd, args.includes('--migrate'));
+    out.push(...sidecar.lines);
+    const gate = await gateReport(cwd);
+    out.push(...gate.lines);
+    const failed = checks.filter((c) => !c.ok).length + sidecar.failed + gate.failed;
     out.push('');
     out.push(failed === 0
         ? 'plumbbob: all checks passed. If a skill still misbehaves, restart Claude Code (or /reload-plugins).'

package/dist/verbs/finish.js

@@ -0,0 +1,101 @@
+// `plumbbob finish` (D9/D34) — 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.
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
+import { checkpointsPath, hasSession, intentPath, reportPath, resolveBuild, seamPath, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
+import { setLocalSetting } from "../lib/settings.js";
+import { parseTitle } from "../lib/orient.js";
+export function finish(cwd, args = []) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const { build: slug } = resolveBuild(root, args);
+    if (existsSync(reportPath(root, slug))) {
+        appendCheckpointShas(root, slug);
+    }
+    else {
+        process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
+            '(/plumbbob:pb-finish normally writes the report first). No gate (D9).\n');
+    }
+    // The final commit (D34): stage the report just written plus the build folder's
+    // tail (the last step's checkpoint line lands one commit late, D37) and commit it
+    // under the greppable `finish` subject. `--allow-empty` (via `commit`) still marks
+    // the narrative endpoint when the tree is already clean, or under `--local`, where
+    // the whole sidecar is excluded and there is nothing tracked to stage.
+    if (isDirty(root)) {
+        stageAll(root);
+    }
+    const sha = commit(root, subject(root, slug), bodyArg(args) ?? undefined);
+    // Clear the control state: the in-flight markers, the per-worktree cursor (D28),
+    // and the session sentinel (STATE last, so "no session" flips exactly at the end).
+    // The tracked artifacts stay in place — only the ephemera go.
+    rmSync(seamPath(root, slug), { force: true });
+    rmSync(stepPath(root, slug), { force: true });
+    rmSync(spikePath(root, slug), { force: true });
+    if (slug !== null) {
+        // Drop the activeBuild key — JSON.stringify omits an `undefined` value, so the
+        // cursor is removed while the other local settings (auto, …) survive. Skipped
+        // under `--local`, where there is no cursor to clear.
+        setLocalSetting(root, 'activeBuild', undefined);
+    }
+    rmSync(join(sidecarDir(root), 'STATE'), { force: true });
+    const where = slug === null ? '.plumbbob/' : `.plumbbob/builds/${slug}/`;
+    process.stdout.write(`plumbbob: finished — ${sha.slice(0, 9)}. ${where} rides your branch into the PR. ` +
+        'Run `/plumbbob: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';
+}
+// `--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
+// null when the flag is absent or stdin is empty — the commit then carries subject
+// only. A read error (no stdin attached) degrades to null rather than throwing.
+function bodyArg(args) {
+    if (!args.includes('--body')) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(0, 'utf8').trimEnd();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Append the recorded checkpoints (baseline + each `step n <sha>`) to report.md as a
+// `## Checkpoints` section, so the report — which now rides the branch into the PR —
+// lists the SHAs. Best-effort: an unreadable checkpoints file yields an empty list.
+function appendCheckpointShas(root, slug) {
+    let raw = '';
+    try {
+        raw = readFileSync(checkpointsPath(root, slug), 'utf8');
+    }
+    catch {
+        raw = '';
+    }
+    const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .map((l) => `- ${l}`);
+    appendFileSync(reportPath(root, slug), ['', '## Checkpoints', '', ...lines, ''].join('\n'));
+}

package/dist/verbs/revert.js

@@ -1,7 +1,12 @@
 // `plumbbob revert [--to n]` — git reset --hard to a checkpoint SHA (the most
 // recent step, or `--to n`, with the baseline as fallback), then remove untracked
-// files under the SEAM only. The sidecar is git-excluded (D17), so the reset
-// never touches it — park lines and intent edits survive the revert (C4).
+// files under the SEAM only. The artifact plane (`.plumbbob/builds/<slug>/`) is now
+// TRACKED (D26), so a bare reset WOULD discard park lines and intent edits — or, when
+// reverting to a baseline that predates the build folder, delete the folder wholesale.
+// So revert snapshots the sidecar to temp and restores it as uncommitted changes
+// after the reset (D26), keeping C4/never-destroy intact across both cases. The
+// untracked cleanup additionally whitelists the artifact plane, so no seam pattern
+// can ever sweep away a build's own files.
 //
 // Plumbbob also installs its driver skills INTO the repo (.claude/skills/<driver>/
 // for a self-contained install), so a blunt reset would discard an out-of-seam
@@ -13,20 +18,21 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findRepoRoot, resetHard, untrackedPaths } from "../lib/git.js";
-import { checkpointsPath, hasSession, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
-import { matchesSeam } from "../lib/intent.js";
+import { checkpointsPath, hasSession, resolveBuild, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
+import { isArtifactPath, matchesSeam } from "../lib/intent.js";
 export function revert(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
-    const to = parseTo(args);
+    const { build: slug, rest } = resolveBuild(root, args);
+    const to = parseTo(rest);
     if (to === 'invalid') {
         process.stderr.write('plumbbob: revert --to needs a step number. Try: plumbbob revert --to 2.\n');
         return 1;
     }
-    const checkpoints = readCheckpoints(root);
+    const checkpoints = readCheckpoints(root, slug);
     let sha;
     if (to === null) {
         sha = checkpoints.steps.at(-1)?.sha ?? checkpoints.baseline;
@@ -45,14 +51,14 @@ export function revert(cwd, args) {
     }
     // Compute untracked-in-seam BEFORE the reset (reset --hard leaves untracked and
     // ignored files alone, so they must be removed explicitly afterward).
-    const seam = readSeamTokens(root);
-    const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam));
+    const seam = readSeamTokens(root, slug);
+    const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam) && !isArtifactPath(p));
     resetPreserving(root, sha, plumbbobOwnedPaths(root));
     for (const rel of toRemove) {
         rmSync(join(root, rel), { force: true, recursive: true });
     }
-    rmSync(seamPath(root), { force: true });
-    rmSync(stepPath(root), { force: true });
+    rmSync(seamPath(root, slug), { force: true });
+    rmSync(stepPath(root, slug), { force: true });
     process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — back at the boundary. Park lines and intent edits were preserved.\n`);
     return 0;
 }
@@ -99,10 +105,10 @@ function parseTo(args) {
     }
     return Number(raw);
 }
-function readCheckpoints(root) {
+function readCheckpoints(root, slug) {
     let content = '';
     try {
-        content = readFileSync(checkpointsPath(root), 'utf8');
+        content = readFileSync(checkpointsPath(root, slug), 'utf8');
     }
     catch {
         return { baseline: undefined, steps: [] };
@@ -122,9 +128,9 @@ function readCheckpoints(root) {
     }
     return { baseline, steps };
 }
-function readSeamTokens(root) {
+function readSeamTokens(root, slug) {
     try {
-        return readFileSync(seamPath(root), 'utf8')
+        return readFileSync(seamPath(root, slug), 'utf8')
             .split('\n')
             .map((l) => l.trim())
             .filter((l) => l.length > 0);

package/dist/verbs/spike.js

@@ -13,7 +13,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, inSpike, markSpike, clearSpike, stepPath } from "../lib/sidecar.js";
+import { hasSession, inSpike, markSpike, clearSpike, resolveBuild, stepPath } from "../lib/sidecar.js";
 const DEFAULT_OPTIONS = ['a', 'b'];
 export function spike(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -21,18 +21,19 @@ export function spike(cwd, args) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
-    const positionals = args.filter((a) => !a.startsWith('--'));
+    const { build: buildSlug, rest } = resolveBuild(root, args);
+    const positionals = rest.filter((a) => !a.startsWith('--'));
     if (positionals[0] === 'done') {
-        return spikeDone(root);
+        return spikeDone(root, buildSlug);
     }
-    return spikeStart(root, positionals);
+    return spikeStart(root, buildSlug, positionals);
 }
-function spikeStart(root, positionals) {
-    if (inSpike(root)) {
+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');
         return 1;
     }
-    if (existsSync(stepPath(root))) {
+    if (existsSync(stepPath(root, buildSlug))) {
         process.stderr.write('plumbbob: spike starts from a settled boundary, but a step is in flight. ' +
             'A spike is a deliberate fork — checkpoint or revert the current step first.\n');
         return 1;
@@ -54,14 +55,14 @@ function spikeStart(root, positionals) {
         git(root, ['worktree', 'add', '-b', `spike/${slug}-${opt}`, path, 'HEAD']);
         created.push(path);
     }
-    markSpike(root);
+    markSpike(root, buildSlug);
     process.stdout.write(`plumbbob: spiking — the main tree stays put. Experiment in the throwaway worktrees:\n${created
         .map((p) => `  ${p}`)
         .join('\n')}\nWhen you've decided, record the verdict in intent.md and run \`plumbbob spike done\`.\n`);
     return 0;
 }
-function spikeDone(root) {
-    if (!inSpike(root)) {
+function spikeDone(root, buildSlug) {
+    if (!inSpike(root, buildSlug)) {
         process.stderr.write('plumbbob: no active spike to close.\n');
         return 1;
     }
@@ -72,7 +73,7 @@ function spikeDone(root) {
     for (const branch of spikeBranches(root)) {
         git(root, ['branch', '-D', branch]);
     }
-    clearSpike(root);
+    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');
     return 0;