plumbbob 0.9.3 → 0.10.0

package/dist/verbs/handoff.js

@@ -1,8 +1,8 @@
-// `plumbbob handoff` — print the standardized build hand-off block: the
+// `plumbbob handoff`: print the standardized build hand-off block: the
 // "state / choice / what's next" the human sees at each step boundary. Read-only,
-// no state change. It derives the moment from the session — a step in flight ⇒ the
+// no state change. It derives the moment from the session: a step in flight ⇒ the
 // pause block (built → looks-good/needs-work → next), none ⇒ the post-checkpoint
-// boundary block — and renders the next undone step plus its advisory `- model:`
+// boundary block, and renders the next undone step plus its advisory `- model:`
 // recommendation straight from intent.md, the build's plan document. Owning the
 // block here, rather than as prose in the build skill, keeps the skill from
 // drifting out of sync with `status`, which renders the same next-step detail
@@ -75,7 +75,7 @@ function boundaryBlock(step, title, nextUp) {
  * The forward pointer, shared by both blocks: the next undone step, its title,
  * and its advisory `- model:` recommendation.
  *
- * The recommendation renders as just the model token for the `/model` call —
+ * The recommendation renders as just the model token for the `/model` call;
  * the full rationale lives on the `status` dashboard. No next step ⇒ the
  * finish/step nudge instead.
  */
@@ -101,8 +101,9 @@ function titleOf(steps, n) {
     return steps.find((s) => s.n === n)?.title ?? null;
 }
 /**
- * The model token from a `- model:` recommendation — the first word, so a
- * `model: opus — <rationale>` line yields `opus` for the `/model` call.
+ * The model token from a `- model:` recommendation: the first word, so a
+ * `model: opus` line followed by an em dash and rationale yields `opus` for
+ * the `/model` call.
  *
  * Null when there is no recommendation, or it degraded to whitespace (folding
  * the null model into the same guard keeps both branches live).
@@ -112,7 +113,7 @@ function modelToken(model) {
     return first !== undefined && first.length > 0 ? first : null;
 }
 /**
- * Read a file as UTF-8, or return '' when it is missing or unreadable — an
+ * Read a file as UTF-8, or return '' when it is missing or unreadable: an
  * absent sidecar file reads as empty rather than throwing.
  */
 function readOr(path) {
@@ -124,7 +125,7 @@ function readOr(path) {
     }
 }
 /**
- * The in-flight step number from the STEP marker — the flat one-line file in
+ * The in-flight step number from the STEP marker: the flat one-line file in
  * the build folder that records which step is open. Null when no step is in
  * flight or the file holds anything but a bare number.
  */

package/dist/verbs/init.js

@@ -1,7 +1,7 @@
-// `plumbbob init [--uninstall] [--force]` — link plumbbob into Claude Code as an
+// `plumbbob init [--uninstall] [--force]`: link plumbbob into Claude Code as an
 // in-place skills-directory plugin. It symlinks the installed package into
-// ~/.claude/skills/plumbbob, where Claude Code discovers it as `plumbbob@skills-dir`
-// — the skills load namespaced (`/plumbbob:*`) and the post-edit hook auto-registers
+// ~/.claude/skills/plumbbob, where Claude Code discovers it as `plumbbob@skills-dir`:
+// the skills load namespaced (`/plumbbob:*`) and the post-edit hook auto-registers
 // from hooks/hooks.json. This non-marketplace install path is first-class by design:
 // it serves an `npm i -g` global, local dev, and clients predating plugins, and it
 // keeps plumbbob usable as a standalone CLI outside any one host rather than
@@ -10,9 +10,9 @@
 // via bin/, so it needs neither `npm i -g` nor `init`). The two are mutually
 // exclusive: both register a plugin named `plumbbob`, and a double-install collides
 // over the /plumbbob:* namespace (skills can drop to flat `/status` names). So init
-// REFUSES when a marketplace plumbbob is already installed — `--force` overrides
+// REFUSES when a marketplace plumbbob is already installed: `--force` overrides
 // (the dev-install path uses it). Global-only by design: install scope is NOT session
-// scope — sessions stay per-project via `plumbbob start`. Idempotent + reversible
+// scope: sessions stay per-project via `plumbbob start`. Idempotent + reversible
 // (`--uninstall` drops the link); it NEVER writes settings.json. Node builtins only.
 import { lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { marketplacePlumbbob } from "../lib/plugins.js";
 /**
- * The installed package root — parent of .claude-plugin/, skills/, hooks/, dist/.
+ * The installed package root: parent of .claude-plugin/, skills/, hooks/, dist/.
  *
  * Derived from this module's URL: the global install when run as the published
  * bin, the checkout in dev. No trailing slash, so it compares clean against a
@@ -64,8 +64,8 @@ function symlinkTarget(path) {
 /**
  * Link the installed package into ~/.claude/skills/plumbbob, or `--uninstall` it.
  *
- * Refuses when a marketplace plumbbob plugin is already installed — two plugins
- * named `plumbbob` collide over the /plumbbob:* namespace — unless `--force`.
+ * Refuses when a marketplace plumbbob plugin is already installed (two plugins
+ * named `plumbbob` collide over the /plumbbob:* namespace) unless `--force`.
  * Repoints a stale link from an earlier install location; already-linked is a
  * clean exit 0.
  */
@@ -95,7 +95,7 @@ export function init(args) {
             process.stdout.write(`plumbbob: already linked (${link} → ${target}). Nothing to do.\n`);
             return 0;
         }
-        rmSync(link); // a stale link from an earlier install location — repoint it
+        rmSync(link); // a stale link from an earlier install location: repoint it
     }
     symlinkSync(target, link);
     process.stdout.write(`plumbbob: linked ${link} → ${target}.\n` +

package/dist/verbs/park.js

@@ -1,6 +1,6 @@
-// `plumbbob park "<text>"` — the raw capture path for a thought you don't want
+// `plumbbob park "<text>"`: the raw capture path for a thought you don't want
 // to chase mid-step: append one flat line under the "## Park list" section of
-// build-log.md (the build's human-facing ledger). Capture stays dumb by design —
+// build-log.md (the build's human-facing ledger). Capture stays dumb by design:
 // a grep-readable append, no markdown parsing, no model turn (wording the line
 // well is /plumbbob:park's job); triage waits for a step boundary, via harvest.
 // Capture is not a state transition, so it runs in any context (terminal or
@@ -14,7 +14,7 @@ import { appendToSection } from "../lib/buildlog.js";
  *
  * All non-flag args join into a single line. Refuses when there is no active
  * session, when the text is empty, or when build-log.md lacks a "## Park list"
- * section — a park line must never vanish silently.
+ * section: a park line must never vanish silently.
  */
 export function park(cwd, args) {
     const root = findRepoRoot(cwd);

package/dist/verbs/recover.js

@@ -0,0 +1,297 @@
+// `plumbbob recover`: read the control plane and say, plainly, whether it is
+// telling the truth. Nothing else reads these files as a set: `doctor` checks
+// the install and the gate, `status` reports what the markers claim without
+// questioning them. So a session that crashed, lost its context window, or was
+// switched away mid-step can sit in a state no verb detects: the worst being a
+// cursor pointing at a build that no longer exists, which renders a perfectly
+// plausible empty dashboard instead of an error.
+//
+// Diagnosis is free and repair is asked for by name (`--fix`), the same posture
+// `doctor --migrate` takes. What `--fix` may touch is deliberately narrow: only
+// the untracked control files this tool owns and can rewrite from what it
+// already knows. It never touches a tracked artifact (intent, build-log,
+// checkpoints, reports), never touches git, and never advances the loop: a
+// recovery verb that could land a step would be a second, quieter checkpoint.
+//
+// Spike leftovers are reported and never removed: those worktrees live outside
+// the repo root and may hold work nobody copied out, so naming them is help and
+// deleting them is a gamble the human should take by hand.
+import { existsSync, readFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { parseSteps } from "../lib/orient.js";
+import { activeBuild, checkpointsPath, clearHandoff, clearTick, grantPath, handoffPath, hasSession, intentPath, inSpike, listBuilds, readTurn, setActiveBuild, setGrant, stepPath, tickPath, } from "../lib/sidecar.js";
+import { spikeBranches, spikeWorktrees } from "./spike.js";
+/**
+ * Report every inconsistency in the control plane, and with `--fix` repair the
+ * ones that can be repaired without judgment.
+ *
+ * Exits 0 when the control plane is consistent (or when every problem found was
+ * fixed), 1 while any problem is still standing, so a scripted caller can tell
+ * "clean" from "you still have to look at this".
+ */
+export function recover(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null) {
+        process.stderr.write('plumbbob: not a git repository — recover reads a repo\'s control plane.\n');
+        return 1;
+    }
+    const fix = args.includes('--fix');
+    const findings = [...sessionFindings(root), ...spikeOrphanFindings(root)];
+    const lines = ['', 'plumbbob recover — control plane'];
+    let standing = 0;
+    for (const finding of findings) {
+        if (finding.ok) {
+            lines.push(`  ✓ ${finding.name}: ${finding.detail}`);
+            continue;
+        }
+        if (fix && finding.repair !== undefined) {
+            finding.repair();
+            lines.push(`  ✓ ${finding.name}: ${finding.repaired ?? finding.detail}`);
+            continue;
+        }
+        standing += 1;
+        lines.push(`  ✗ ${finding.name}: ${finding.detail}`);
+        if (finding.hint !== undefined)
+            lines.push(`    → ${finding.hint}`);
+    }
+    const fixable = findings.filter((f) => !f.ok && f.repair !== undefined).length;
+    lines.push('', summary(standing, fixable, fix), '');
+    process.stdout.write(lines.join('\n'));
+    return standing > 0 ? 1 : 0;
+}
+/**
+ * The closing line: what is still wrong, and whether `--fix` would help.
+ */
+function summary(standing, fixable, fix) {
+    if (standing === 0) {
+        return fix ? 'control plane consistent — everything fixable was fixed.' : 'control plane consistent — nothing to recover.';
+    }
+    const problems = `${standing} problem${standing === 1 ? '' : 's'} still standing`;
+    if (fix || fixable === 0)
+        return `${problems} — each needs a call only you can make (see the → lines).`;
+    return `${problems}; ${fixable} of them recover --fix can repair. Nothing was changed.`;
+}
+/**
+ * Everything that depends on there being a session: the cursor, the phase
+ * markers, and the per-build control files.
+ *
+ * With no session there is no control plane to be wrong about: only the spike
+ * leftovers, which outlive `finish` and are checked separately.
+ */
+function sessionFindings(root) {
+    if (!hasSession(root)) {
+        return [{ name: 'session', ok: true, detail: 'none open — nothing in flight to reconcile' }];
+    }
+    const slug = activeBuild(root);
+    const findings = [];
+    // The cursor first: everything below reads through it, so a cursor pointing
+    // nowhere makes the rest meaningless rather than merely wrong.
+    const resolvable = slug !== null && existsSync(intentPath(root, slug));
+    if (!resolvable) {
+        return [cursorFinding(root, slug)];
+    }
+    findings.push({ name: 'cursor', ok: true, detail: `build "${slug}" resolves` });
+    const stepInFlight = existsSync(stepPath(root, slug));
+    findings.push(...phaseFindings(root, slug, stepInFlight));
+    findings.push(...leftoverFindings(root, slug, stepInFlight));
+    return findings;
+}
+/**
+ * The cursor names a build that is not there.
+ *
+ * This is the quiet one: `status` takes the cursor at its word, so every read
+ * comes back empty and the dashboard renders as a fresh, untouched build rather
+ * than an error. Repairable only when exactly one real build remains; with
+ * several, which one you meant is a judgment call.
+ */
+function cursorFinding(root, slug) {
+    const named = slug === null ? 'nothing' : `"${slug}"`;
+    const builds = listBuilds(root).filter((b) => existsSync(intentPath(root, b)));
+    const detail = `points at ${named}, which has no intent.md — status will render an empty dashboard rather than refuse`;
+    if (builds.length === 1) {
+        const only = builds[0];
+        return {
+            name: 'cursor',
+            ok: false,
+            detail,
+            hint: `fix: plumbbob recover --fix (re-points the cursor at "${only}", the only build left) — or plumbbob use <slug>`,
+            repair: () => setActiveBuild(root, only),
+            repaired: `re-pointed at "${only}"`,
+        };
+    }
+    const hint = builds.length === 0
+        ? 'no build folder survives here — plumbbob finish closes the session, or start a new one'
+        : `pick the one you meant: plumbbob use <slug>. Builds: ${builds.join(', ')}`;
+    return { name: 'cursor', ok: false, detail, hint };
+}
+/**
+ * Contradictions in what phase the build claims to be in.
+ *
+ * Phase is derived from the markers rather than stored, so two markers at once
+ * is not an impossible state; it is an unreadable one, and `status` resolves
+ * it by showing the spike and hiding the step entirely.
+ */
+function phaseFindings(root, slug, stepInFlight) {
+    const findings = [];
+    const spiking = inSpike(root, slug);
+    if (spiking && stepInFlight) {
+        findings.push({
+            name: 'phase',
+            ok: false,
+            detail: `both a spike and step ${readMarker(stepPath(root, slug))} are marked in flight — status shows the spike and hides the step`,
+            hint: 'close the spike first (plumbbob spike done), which returns you to the step still in flight',
+        });
+    }
+    else {
+        findings.push({
+            name: 'phase',
+            ok: true,
+            detail: spiking ? 'in a spike' : stepInFlight ? `step ${readMarker(stepPath(root, slug))} in flight` : 'at the boundary',
+        });
+    }
+    // A STEP the plan no longer contains: `refine` can rewrite `## Steps` under a
+    // step that is already in flight, and nothing reconciles the marker with it.
+    const marker = Number(readMarker(stepPath(root, slug)));
+    if (stepInFlight && Number.isInteger(marker) && marker > 0) {
+        const planned = parseSteps(readOr(intentPath(root, slug))).map((s) => s.n);
+        if (planned.length > 0 && !planned.includes(marker)) {
+            findings.push({
+                name: 'step marker',
+                ok: false,
+                detail: `step ${marker} is in flight but the plan has no step ${marker} (planned: ${planned.join(', ')})`,
+                hint: 'the plan was rewritten under the step — sharpen it with /plumbbob:step, or plumbbob revert to drop the step',
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Control files left behind by a verb that did not get to clean them up.
+ *
+ * Each of these fails quietly rather than loudly, which is why they are worth a
+ * verb: an orphaned handoff ledger feeds a finished step's agent output into
+ * the next one, and a stale TICK arms the approval latch against a span that
+ * already closed.
+ */
+function leftoverFindings(root, slug, stepInFlight) {
+    const findings = [];
+    // The handoff ledger is step-scoped and cleared by `checkpoint` alone; a
+    // revert or an abandoned step leaves it for the next step to inherit.
+    const handoffs = handoffCount(root, slug);
+    if (!stepInFlight && handoffs > 0) {
+        findings.push({
+            name: 'handoff ledger',
+            ok: false,
+            detail: `${handoffs} agent envelope${handoffs === 1 ? '' : 's'} left over at the boundary — the next step would thread them into its context`,
+            hint: 'fix: plumbbob recover --fix (clears the step-scoped ledger)',
+            repair: () => clearHandoff(root, slug),
+            repaired: `cleared ${handoffs} leftover envelope${handoffs === 1 ? '' : 's'}`,
+        });
+    }
+    else {
+        findings.push({ name: 'handoff ledger', ok: true, detail: stepInFlight ? 'in scope for the step in flight' : 'empty' });
+    }
+    // TICK is stamped when a step is entered and when `start` opens the plan
+    // pause, and cleared by the checkpoint that lands either one. At the boundary
+    // with the plan already committed, neither pause is open, so a TICK left here
+    // is measuring a span that closed.
+    const planLanded = readOr(checkpointsPath(root, slug)).split('\n').some((l) => l.startsWith('plan '));
+    if (!stepInFlight && planLanded && existsSync(tickPath(root, slug))) {
+        findings.push({
+            name: 'latch tick',
+            ok: false,
+            detail: 'a TICK stamp survives at the boundary — the approval latch is armed against a pause that already closed',
+            hint: 'fix: plumbbob recover --fix (clears the stale stamp; the latch re-arms on the next build)',
+            repair: () => clearTick(root, slug),
+            repaired: 'cleared the stale stamp',
+        });
+    }
+    else {
+        findings.push({ name: 'latch tick', ok: true, detail: stepInFlight ? 'stamped for the step in flight' : 'clear' });
+    }
+    // GRANT is rewritten on every turn tick, so it self-clears, but only while
+    // the hook runs. Without a TURN ledger nothing will ever clear it, and the
+    // latch reads a standing grant as self-approval.
+    if (existsSync(grantPath(root)) && readTurn(root) === null) {
+        findings.push({
+            name: 'self-approval grant',
+            ok: false,
+            detail: 'a GRANT survives with no turn ledger to clear it — the latch would honor it as self-approval',
+            hint: 'fix: plumbbob recover --fix (drops the grant; type /plumbbob:build --auto to mint a fresh one)',
+            repair: () => setGrant(root, null),
+            repaired: 'dropped the stranded grant',
+        });
+    }
+    return findings;
+}
+/**
+ * Spike worktrees and branches with no open spike to own them.
+ *
+ * `spike done` is the only cleanup and it refuses without the marker, so a
+ * spike interrupted by `finish`, a cursor switch, or a half-failed open strands
+ * these where no verb can reach them. Reported with the exact commands and
+ * never removed: the directories sit outside the repo and may hold the only
+ * copy of what the spike learned.
+ */
+function spikeOrphanFindings(root) {
+    if (inSpike(root, activeBuild(root))) {
+        return [{ name: 'spike leftovers', ok: true, detail: 'a spike is open — plumbbob spike done owns its cleanup' }];
+    }
+    const worktrees = spikeWorktrees(root);
+    const branches = spikeBranches(root);
+    if (worktrees.length === 0 && branches.length === 0) {
+        return [{ name: 'spike leftovers', ok: true, detail: 'none' }];
+    }
+    const parts = [
+        worktrees.length > 0 ? `${worktrees.length} worktree${worktrees.length === 1 ? '' : 's'} (${worktrees.join(', ')})` : '',
+        branches.length > 0 ? `${branches.length} branch${branches.length === 1 ? '' : 'es'} (${branches.join(', ')})` : '',
+    ].filter((p) => p.length > 0);
+    const commands = [
+        ...worktrees.map((path) => `git worktree remove --force ${path}`),
+        ...(branches.length > 0 ? [`git branch -D ${branches.join(' ')}`] : []),
+    ];
+    return [
+        {
+            name: 'spike leftovers',
+            ok: false,
+            detail: `${parts.join(' and ')} survive with no spike open — plumbbob spike done cannot reach them`,
+            hint: `remove by hand once you have salvaged anything you want: ${commands.join(' && ')}`,
+        },
+    ];
+}
+/**
+ * How many agent envelopes the step-scoped handoff ledger holds; 0 when it is
+ * absent or unreadable.
+ */
+function handoffCount(root, slug) {
+    const raw = readOr(handoffPath(root, slug));
+    if (raw.trim().length === 0)
+        return 0;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.length : 1;
+    }
+    catch {
+        return 1;
+    }
+}
+/**
+ * A control marker's trimmed content, or '?' when it cannot be read: a marker
+ * exists to be reported on, so an unreadable one must not throw mid-report.
+ */
+function readMarker(path) {
+    const raw = readOr(path).trim();
+    return raw.length > 0 ? raw : '?';
+}
+/**
+ * File content, or '' when absent: recover reads state that may be missing by
+ * definition, so every read degrades rather than throws.
+ */
+function readOr(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/verbs/revert.js

@@ -1,18 +1,18 @@
-// `plumbbob revert [--to n]` — git reset --hard to a checkpoint SHA (the most
+// `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 seam is the in-flight step's flat list of
-// granted edit paths). The artifact plane — the tracked `.plumbbob/builds/<slug>/`
-// folder holding intent, build-log, checkpoints, and park lines — would not
+// granted edit paths). The artifact plane (the tracked `.plumbbob/builds/<slug>/`
+// folder holding intent, build-log, checkpoints, and park lines) would not
 // survive a bare reset: it 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 — a rewind must never destroy recorded
+// uncommitted changes after the reset: a rewind must never destroy recorded
 // work, in either case. 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
-// skill edit — or a `pnpm up plumbbob` re-setup — together with the half-done
+// skill edit (or a `pnpm up plumbbob` re-setup) together with the half-done
 // step. revert discards the step's WORK, never plumbbob's own machinery, so those
 // paths are carried across the reset unchanged.
 import { cpSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
@@ -66,7 +66,7 @@ export function revert(cwd, args) {
     const seam = readSeamTokens(root, slug);
     const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam) && !isArtifactPath(p));
     // A revert against an in-flight step is a datapoint the finish report's stats
-    // table wants — read the STEP marker before it goes, bump the counter after
+    // table wants: read the STEP marker before it goes, bump the counter after
     // the reset (the sidecar is preserved through it, so the write survives).
     const inFlight = readInFlightStep(root, slug);
     resetPreserving(root, sha, plumbbobOwnedPaths(root));
@@ -79,7 +79,7 @@ export function revert(cwd, args) {
         bumpStepStat(root, slug, inFlight, 'reverts');
     }
     // The step is abandoned: the build-log's Current-step line returns to the
-    // boundary and its Steps mirror re-renders from the preserved intent.md —
+    // boundary and its Steps mirror re-renders from the preserved intent.md:
     // revert keeps intent edits, so intent's checkboxes stay the truth to reflect.
     // Best-effort, like every build-log write.
     syncBuildLogState(root, slug, AT_BOUNDARY);
@@ -94,9 +94,9 @@ export function revert(cwd, args) {
  * under .claude/skills/, named from plumbbob's own bundled `skills/` dir.
  *
  * The match is by name alone, and since the skills dropped their `pb-` prefix
- * those names are ordinary words — a user's own `.claude/skills/plan/` is
- * carried across the reset too. That errs toward keeping work (C4), so it is
- * the safe direction to be wrong in. Only paths that currently exist are returned.
+ * those names are ordinary words; a user's own `.claude/skills/plan/` is
+ * carried across the reset too. That errs toward keeping work (never destroy),
+ * so it is the safe direction to be wrong in. Only paths that currently exist are returned.
  */
 function plumbbobOwnedPaths(root) {
     const paths = [sidecarDir(root)];
@@ -106,7 +106,7 @@ function plumbbobOwnedPaths(root) {
         }
     }
     catch {
-        // Bundled skills dir not resolvable (unexpected) — protect just the sidecar.
+        // Bundled skills dir not resolvable (unexpected): protect just the sidecar.
     }
     return paths.filter((p) => existsSync(p));
 }
@@ -146,7 +146,7 @@ function parseTo(args) {
 /**
  * Parse the build's CHECKPOINTS record into a baseline sha and per-step shas.
  *
- * A missing or unreadable file yields an empty record — the caller then refuses
+ * A missing or unreadable file yields an empty record: the caller then refuses
  * with its own message rather than crashing here.
  */
 function readCheckpoints(root, slug) {
@@ -173,7 +173,7 @@ function readCheckpoints(root, slug) {
     return { baseline, steps };
 }
 /**
- * Read the in-flight step's seam — its edit-grant paths, one per line.
+ * Read the in-flight step's seam: its edit-grant paths, one per line.
  *
  * A missing or unreadable SEAM contributes nothing: no tokens, never an error.
  */

package/dist/verbs/spike.js

@@ -1,15 +1,15 @@
-// `plumbbob spike` — the spike lifecycle for a genuine fork the design phase
+// `plumbbob spike`: the spike lifecycle for a genuine fork the design phase
 // couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree and a
 // `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default options
-// a/b) and drops the SPIKE marker — one of the untracked per-build control files
+// a/b) and drops the SPIKE marker: one of the untracked per-build control files
 // under `.plumbbob/` that record what's in flight. The main tree stays put while
 // you experiment in the worktrees, which are hook-dormant by construction: the
 // untracked control files don't exist in a fresh checkout, so the hooks find no
 // STATE (the session sentinel) there. `spike done` removes every spike worktree
 // and branch and clears the marker.
 //
-// Every spike also leaves a durable report — `spike-NN-<slug>.md` beside
-// intent.md in the tracked `builds/<slug>/` folder — so the verdict rides the
+// Every spike also leaves a durable report (`spike-NN-<slug>.md` beside
+// intent.md in the tracked `builds/<slug>/` folder) so the verdict rides the
 // branch into the PR instead of evaporating with the throwaway worktrees.
 //
 // Worktree git calls run directly here rather than via lib/git.ts (which holds the
@@ -21,15 +21,15 @@ import { basename, dirname, join, relative } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
 import { buildFolder, clearSpike, hasSession, inSpike, listSpikeReports, markSpike, nextSpikeReportPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { readTemplate, stampTemplate } from "../lib/templates.js";
-// Worktree/branch names when the caller lists none — a fork defaults to two arms.
+// Worktree/branch names when the caller lists none: a fork defaults to two arms.
 const DEFAULT_OPTIONS = ['a', 'b'];
 /**
- * The verbatim Verdict placeholder from templates/spike-report.md — its presence
+ * The verbatim Verdict placeholder from templates/spike-report.md: its presence
  * means the spike's call was never recorded, which `spike done` nudges on.
  */
 const VERDICT_PLACEHOLDER = '*(viable | not viable | partial';
 /**
- * Entry point for `plumbbob spike` — dispatches to open, `report`, or `done`.
+ * Entry point for `plumbbob spike`: dispatches to open, `report`, or `done`.
  *
  * Requires an active session (the STATE sentinel) and resolves which build the
  * spike belongs to before dispatching.
@@ -51,11 +51,11 @@ export function spike(cwd, args) {
     return spikeStart(root, buildSlug, positionals);
 }
 /**
- * `spike report "<slug>"` — scaffold a spike report WITHOUT worktrees.
+ * `spike report "<slug>"`: scaffold a spike report WITHOUT worktrees.
  *
  * Serves 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 stamped
+ * marker: a step in flight is exactly when this runs. Provenance is stamped
  * `step <n>` when a step is in flight, else `/plumbbob:spike`.
  */
 function spikeReport(root, buildSlug, positionals) {
@@ -75,7 +75,7 @@ function spikeReport(root, buildSlug, positionals) {
  * 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 worktree-opening spike and the spike-as-step `spike report` —
+ * Shared by the worktree-opening spike and the spike-as-step `spike report`:
  * one artifact, two entry points. The CLI owns the numbering; the human never
  * creates or numbers a report.
  */
@@ -86,7 +86,7 @@ function scaffoldSpikeReport(root, buildSlug, spikeSlug, via) {
     return path;
 }
 /**
- * The build's in-flight step number, or null — reads the STEP marker `build`
+ * The build's in-flight step number, or null: reads the STEP marker `build`
  * writes.
  *
  * Used to stamp a spike-as-step report's provenance as `step <n>`.
@@ -103,7 +103,7 @@ function readInFlightStep(root, buildSlug) {
 /**
  * Open a spike: one throwaway worktree + `spike/<slug>-<opt>` branch per option.
  *
- * Refuses when a spike is already open or a step is in flight — a spike is a
+ * Refuses when a spike is already open or a step is in flight: a spike is a
  * deliberate fork from a settled boundary, so the current step must checkpoint
  * or revert first. Marks the SPIKE control file and scaffolds the report before
  * returning.
@@ -147,7 +147,7 @@ function spikeStart(root, buildSlug, positionals) {
 /**
  * Close the spike: remove every spike worktree and branch, clear the marker.
  *
- * Nudges — but never refuses — when a report's Verdict is still the template
+ * Nudges (but never refuses) when a report's Verdict is still the template
  * placeholder: guidance, not a gate.
  */
 function spikeDone(root, buildSlug) {
@@ -156,7 +156,7 @@ function spikeDone(root, buildSlug) {
         return 1;
     }
     // Check for an unrecorded verdict BEFORE teardown. The reports live in the
-    // build folder, not the spike worktrees, so they survive the removal — but 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)) {
@@ -181,7 +181,7 @@ function spikeDone(root, buildSlug) {
 }
 /**
  * The spike-report filenames in the build folder whose Verdict is still the
- * template placeholder — the ones `spike done` nudges on.
+ * template placeholder: the ones `spike done` nudges on.
  *
  * Best-effort per file: an unreadable report is skipped rather than blocking
  * the close.
@@ -198,11 +198,15 @@ function spikeReportsMissingVerdict(root, buildSlug) {
     });
 }
 /**
- * Worktree paths whose checked-out branch is under spike/ — parsed from the
+ * Worktree paths whose checked-out branch is under spike/: parsed from the
  * porcelain output (blank-line-separated `worktree <path>` / `branch <ref>`
  * blocks).
+ *
+ * Exported for `recover`, which reports the ones this verb can no longer reach
+ * (a spike interrupted before `spike done` strands them). Sharing the reader
+ * keeps one definition of what counts as a spike worktree.
  */
-function spikeWorktrees(root) {
+export function spikeWorktrees(root) {
     const out = git(root, ['worktree', 'list', '--porcelain']);
     const paths = [];
     let current = null;
@@ -218,13 +222,15 @@ function spikeWorktrees(root) {
 }
 /**
  * List the local `spike/<slug>` branch names.
+ *
+ * Exported alongside spikeWorktrees, for the same reason.
  */
-function spikeBranches(root) {
+export function spikeBranches(root) {
     const out = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/spike/']);
     return out.length === 0 ? [] : out.split('\n').filter((b) => b.length > 0);
 }
 /**
- * Slugify a raw spike name — lowercase, non-alphanumerics collapsed to dashes.
+ * Slugify a raw spike name: lowercase, non-alphanumerics collapsed to dashes.
  */
 function sanitize(raw) {
     return raw