plumbbob 0.1.3 → 0.2.3

package/dist/verbs/build.js

@@ -0,0 +1,30 @@
+// `plumbbob build <n>` — read step n's seam from intent.md, write the normalized
+// SEAM + STEP, and enter BUILD. Re-entering from REVIEW just re-derives the same
+// seam and flips back to BUILD; it never checkpoints (only `done` commits).
+import { readFileSync, writeFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession, intentPath, seamPath, stepPath, writeState } from "../lib/sidecar.js";
+import { parseStepSeam } from "../lib/intent.js";
+export function build(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 raw = args.find((a) => !a.startsWith('--'));
+    if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
+        process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n');
+        return 1;
+    }
+    const step = Number(raw);
+    const parsed = parseStepSeam(readFileSync(intentPath(root), 'utf8'), step);
+    if (!parsed.ok) {
+        process.stderr.write(`plumbbob: ${parsed.error} Fix the step's seam in intent.md, then \`build ${step}\` again.\n`);
+        return 1;
+    }
+    writeFileSync(seamPath(root), `${parsed.seam.join('\n')}\n`);
+    writeFileSync(stepPath(root), `${step}\n`);
+    writeState(root, 'BUILD');
+    process.stdout.write(`plumbbob: building step ${step} — STATE=BUILD. Edits are limited to the seam:\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
+    return 0;
+}

package/dist/verbs/done.js

@@ -0,0 +1,63 @@
+// `plumbbob done` — the step gate. Refuses on a red check, then stages the whole
+// step (D8: `git add -A`; the sidecar is git-excluded so it never lands), warns
+// about anything committed outside the SEAM, takes the checkpoint commit, records
+// its SHA, and returns to DESIGN.
+import { appendFileSync, readFileSync, rmSync } from 'node:fs';
+import { commit, findRepoRoot, stageAll, stagedPaths } from "../lib/git.js";
+import { checkpointsPath, hasSession, readState, seamPath, stepPath, writeState } from "../lib/sidecar.js";
+import { runCheck } from "../lib/check.js";
+import { matchesSeam } from "../lib/intent.js";
+export function done(cwd) {
+    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 state = readState(root);
+    if (state !== 'BUILD' && state !== 'REVIEW') {
+        process.stderr.write(`plumbbob: done runs from BUILD or REVIEW (current state is ${state ?? 'UNKNOWN'}). Run \`plumbbob build <n>\` first.\n`);
+        return 1;
+    }
+    const step = readStepNumber(root);
+    if (step === null) {
+        process.stderr.write('plumbbob: no in-flight step — run `plumbbob build <n>` first.\n');
+        return 1;
+    }
+    if (runCheck(root) !== 0) {
+        process.stderr.write('plumbbob: check failed (red) — done refuses on red. Fix it and re-run `done`.\n');
+        return 1;
+    }
+    stageAll(root);
+    const seam = readSeamTokens(root);
+    const outside = stagedPaths(root).filter((p) => !matchesSeam(p, seam));
+    if (outside.length > 0) {
+        process.stderr.write(`plumbbob: WARNING committed paths outside the SEAM: ${outside.join(', ')}. The checkpoint captures them, but scope drift may mean the plan needs revising.\n`);
+    }
+    const sha = commit(root, `plumbbob: step ${step} done`);
+    appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
+    rmSync(seamPath(root), { force: true });
+    rmSync(stepPath(root), { force: true });
+    writeState(root, 'DESIGN');
+    process.stdout.write(`plumbbob: step ${step} done — checkpoint ${sha.slice(0, 9)}. STATE=DESIGN.\n`);
+    return 0;
+}
+function readStepNumber(root) {
+    try {
+        const raw = readFileSync(stepPath(root), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSeamTokens(root) {
+    try {
+        return readFileSync(seamPath(root), 'utf8')
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/verbs/finish.js

@@ -0,0 +1,54 @@
+// `plumbbob finish` (D19/D20) — the closing gate, symmetric with the step gate.
+// Refuses unless a report exists, appends the checkpoint SHA list to it, archives
+// intent + build-log + report under .plumbbob/archive/, clears the active files,
+// and deletes SEAM, STEP, then STATE LAST (deleting STATE is what switches the
+// muzzle off, so it happens exactly at session end). Never touches git (C5).
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { findRepoRoot } from "../lib/git.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, stepPath, } from "../lib/sidecar.js";
+import { archiveSession, reportPath } from "../lib/archive.js";
+export function finish(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    if (!existsSync(reportPath(root))) {
+        process.stderr.write('plumbbob: finish refuses without a report — run `/plumbbob-report` first (it writes .plumbbob/report.md). ' +
+            'The closing gate is symmetric with the step gate: you do not walk away without capturing what happened.\n');
+        return 1;
+    }
+    appendCheckpointShas(root);
+    const archived = archiveSession(root);
+    // Clear the active files — now safely archived.
+    rmSync(intentPath(root), { force: true });
+    rmSync(buildLogPath(root), { force: true });
+    rmSync(reportPath(root), { force: true });
+    // Delete the control files LAST, STATE the very last: while STATE exists the
+    // muzzle is live, so it comes off only once everything else is torn down.
+    rmSync(seamPath(root), { force: true });
+    rmSync(stepPath(root), { force: true });
+    rmSync(join(sidecarDir(root), 'STATE'), { force: true });
+    process.stdout.write(`plumbbob: finished — archived to ${relative(root, archived)}. STATE cleared (muzzle off). ` +
+        'Run `plumbbob start "<title>"` to begin the next task.\n');
+    return 0;
+}
+// Append the recorded checkpoints (baseline + each `step n <sha>`) to the report,
+// so the archived report lists the SHAs (spec: "finish lists the SHAs in the
+// report").
+function appendCheckpointShas(root) {
+    let raw = '';
+    try {
+        raw = readFileSync(checkpointsPath(root), 'utf8');
+    }
+    catch {
+        raw = '';
+    }
+    const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .map((l) => `- ${l}`);
+    appendFileSync(reportPath(root), ['', '## Checkpoints', '', ...lines, ''].join('\n'));
+}

package/dist/verbs/mode.js

@@ -0,0 +1,26 @@
+// `plumbbob mode <x>` — the hidden escape hatch: set STATE directly when reality
+// and the machine desync. Not part of the normal flow; the lone human-only verb,
+// so the dispatch refuses it under CLAUDECODE and bash-guard blocks it from the
+// model's shell (D21 revised).
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession, readState, writeState, VALID_STATES } from "../lib/sidecar.js";
+export function mode(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 target = args[0];
+    if (target === undefined) {
+        process.stderr.write(`plumbbob: mode needs a state — one of: ${VALID_STATES.join(', ')}.\n`);
+        return 1;
+    }
+    if (!VALID_STATES.includes(target)) {
+        process.stderr.write(`plumbbob: '${target}' is not a valid state — one of: ${VALID_STATES.join(', ')}.\n`);
+        return 1;
+    }
+    const previous = readState(root) ?? 'UNKNOWN';
+    writeState(root, target);
+    process.stdout.write(`STATE: ${previous} -> ${target} (escape hatch — prefer the normal verbs when you can).\n`);
+    return 0;
+}

package/dist/verbs/park.js

@@ -0,0 +1,51 @@
+// `plumbbob park "<text>"` — the dumb capture path: append one raw line under
+// the build-log's Park list. No model turn, no composition (that is /park's job).
+// Capture is not a transition, so it runs in any context (terminal or in-session).
+import { readFileSync, writeFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession, buildLogPath } from "../lib/sidecar.js";
+export function park(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session — nothing to park to. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const text = args
+        .filter((a) => !a.startsWith('--'))
+        .join(' ')
+        .trim();
+    if (text.length === 0) {
+        process.stderr.write('plumbbob: park needs text. Try: plumbbob park "the idea you do not want to chase right now".\n');
+        return 1;
+    }
+    const path = buildLogPath(root);
+    const updated = insertParkItem(readFileSync(path, 'utf8'), text);
+    if (updated === null) {
+        process.stderr.write('plumbbob: could not find a "## Park list" section in build-log.md.\n');
+        return 1;
+    }
+    writeFileSync(path, updated);
+    process.stdout.write(`parked: ${text}\n`);
+    return 0;
+}
+// Append after the last non-blank line of the Park list section (i.e. just before
+// the next `## ` heading). Returns null if there is no Park list to append to.
+function insertParkItem(content, text) {
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((line) => line.trim() === '## Park list');
+    if (headingIdx === -1) {
+        return null;
+    }
+    let nextSection = lines.findIndex((line, i) => i > headingIdx && line.startsWith('## '));
+    if (nextSection === -1) {
+        nextSection = lines.length;
+    }
+    let insertAt = headingIdx + 1;
+    for (let i = headingIdx + 1; i < nextSection; i++) {
+        if ((lines[i] ?? '').trim() !== '') {
+            insertAt = i + 1;
+        }
+    }
+    lines.splice(insertAt, 0, `- [ ] ${text}`);
+    return lines.join('\n');
+}

package/dist/verbs/revert.js

@@ -0,0 +1,136 @@
+// `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).
+//
+// 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
+// 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';
+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, writeState } from "../lib/sidecar.js";
+import { 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);
+    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);
+    let sha;
+    if (to === null) {
+        sha = checkpoints.steps.at(-1)?.sha ?? checkpoints.baseline;
+    }
+    else {
+        const entry = checkpoints.steps.find((e) => e.n === to);
+        if (entry === undefined) {
+            process.stderr.write(`plumbbob: no checkpoint recorded for step ${to}.\n`);
+            return 1;
+        }
+        sha = entry.sha;
+    }
+    if (sha === undefined) {
+        process.stderr.write('plumbbob: no baseline recorded in checkpoints — cannot revert.\n');
+        return 1;
+    }
+    // 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));
+    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 });
+    writeState(root, 'DESIGN');
+    process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — STATE=DESIGN. Park lines and intent edits were preserved.\n`);
+    return 0;
+}
+// The repo paths that belong to plumbbob, not to the work being reverted: the
+// sidecar (already git-excluded, listed so revert is robust even where `.plumbbob/`
+// was tracked by mistake) and each installed driver skill under .claude/skills/.
+// Skill names come from plumbbob's own bundled `skills/` dir — the same source
+// `setup` copies from — so only plumbbob's own skills are protected, never the
+// user's. Only paths that currently exist are returned.
+function plumbbobOwnedPaths(root) {
+    const paths = [sidecarDir(root)];
+    try {
+        for (const name of readdirSync(fileURLToPath(new URL('../../skills', import.meta.url)))) {
+            paths.push(join(root, '.claude', 'skills', name));
+        }
+    }
+    catch {
+        // Bundled skills dir not resolvable (unexpected) — protect just the sidecar.
+    }
+    return paths.filter((p) => existsSync(p));
+}
+// `git reset --hard <sha>` is repo-wide, so paths that must survive it are copied
+// to a temp snapshot first, then copied back over whatever the reset produced.
+// Restoring on top (no pre-delete) keeps the live sidecar safe if a copy throws.
+function resetPreserving(root, sha, preserve) {
+    const snap = mkdtempSync(join(tmpdir(), 'plumbbob-revert-'));
+    try {
+        preserve.forEach((p, i) => cpSync(p, join(snap, String(i)), { recursive: true }));
+        resetHard(root, sha);
+        preserve.forEach((p, i) => cpSync(join(snap, String(i)), p, { recursive: true }));
+    }
+    finally {
+        rmSync(snap, { force: true, recursive: true });
+    }
+}
+function parseTo(args) {
+    const idx = args.indexOf('--to');
+    if (idx === -1) {
+        return null;
+    }
+    const raw = args[idx + 1];
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+        return 'invalid';
+    }
+    return Number(raw);
+}
+function readCheckpoints(root) {
+    let content = '';
+    try {
+        content = readFileSync(checkpointsPath(root), 'utf8');
+    }
+    catch {
+        return { baseline: undefined, steps: [] };
+    }
+    let baseline;
+    const steps = [];
+    for (const line of content.split('\n')) {
+        const baselineMatch = /^baseline\s+(\S+)/.exec(line);
+        if (baselineMatch) {
+            baseline = baselineMatch[1];
+            continue;
+        }
+        const stepMatch = /^step\s+(\d+)\s+(\S+)/.exec(line);
+        if (stepMatch) {
+            steps.push({ n: Number(stepMatch[1]), sha: stepMatch[2] ?? '' });
+        }
+    }
+    return { baseline, steps };
+}
+function readSeamTokens(root) {
+    try {
+        return readFileSync(seamPath(root), 'utf8')
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/verbs/review.js

@@ -0,0 +1,24 @@
+// `plumbbob review` — run the heavy check from BUILD. Green flips to REVIEW (the
+// muzzle goes back on so reading the diff can't slide into editing). Red stays in
+// BUILD. The state only advances on a green check.
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession, readState, writeState } from "../lib/sidecar.js";
+import { runCheck } from "../lib/check.js";
+export function review(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    if (readState(root) !== 'BUILD') {
+        process.stderr.write(`plumbbob: review runs from BUILD (current state is ${readState(root) ?? 'UNKNOWN'}). Run \`plumbbob build <n>\` first.\n`);
+        return 1;
+    }
+    if (runCheck(root) !== 0) {
+        process.stderr.write('plumbbob: check failed (red) — staying in BUILD. Fix it and re-run `review` (or `done` once green).\n');
+        return 1;
+    }
+    writeState(root, 'REVIEW');
+    process.stdout.write('plumbbob: check green — STATE=REVIEW. Read the diff against intent.md (edits muzzled). `build <n>` to re-enter and fix, or `done` to checkpoint.\n');
+    return 0;
+}

package/dist/verbs/setup.js

@@ -0,0 +1,141 @@
+// `plumbbob setup` — the installer. Two install shapes:
+//
+//   self-contained (default when plumbbob is a project-local dep; --local /
+//     --project to force) — NOTHING is written under ~/.claude. The hooks are
+//     referenced in place at $CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks/,
+//     and the skills are copied into <repo>/.claude/skills/ with their bin
+//     invocation pointed at $CLAUDE_PROJECT_DIR/node_modules/.bin/plumbbob. The
+//     registration lands in:
+//       --local   (default) <repo>/.claude/settings.local.json  — personal, untracked
+//       --project           <repo>/.claude/settings.json         — committable, enrolls the team
+//     This is the "run it from the project root, no global install" shape.
+//
+//   global (--global, or the auto default when plumbbob is NOT a project-local
+//     dep) — the original behavior: copy the hooks to ~/.claude/plumbbob/hooks/
+//     and the skills to ~/.claude/skills/, register absolute command paths in
+//     ~/.claude/settings.json, and leave the skills calling a bare `plumbbob`.
+//
+// `--uninstall` strips the registration from whichever settings file the same
+// resolution selects; installed/copied files are left in place. The hooks are
+// session-gated, so any registration is safe in every repo (C7).
+import { chmodSync, cpSync, existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRepoRoot } from "../lib/git.js";
+import { mergeRegistration, readSettings, stripRegistration, writeSettings } from "../lib/settings.js";
+const HOOK_FILES = ['pre-edit.sh', 'bash-guard.sh', 'post-edit.sh'];
+// The placeholder every skill carries in place of its `plumbbob` invocation;
+// setup substitutes it with the form the chosen install shape resolves.
+const BIN_PLACEHOLDER = '__PLUMBBOB_BIN__';
+// Self-contained installs address everything through Claude Code's project-root
+// variable so committed/portable files carry no machine-absolute path.
+const SELF_HOOKS_DIR = '$CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks';
+const SELF_BIN = '$CLAUDE_PROJECT_DIR/node_modules/.bin/plumbbob';
+export function setup(cwd, args) {
+    const home = process.env.HOME ?? homedir();
+    const mode = resolveMode(cwd, home, args);
+    if (mode === null) {
+        process.stderr.write('plumbbob: a project-scoped install writes <repo>/.claude/, but this is not a git repository. ' +
+            'Run setup from inside the repo, or use --global to install under ~/.claude.\n');
+        return 1;
+    }
+    if (args.includes('--uninstall')) {
+        writeSettings(mode.settingsFile, stripRegistration(readSettings(mode.settingsFile)));
+        process.stdout.write(`plumbbob: removed the hook registration from ${mode.settingsFile}. The installed/copied hooks and skills were left in place.\n`);
+        return 0;
+    }
+    return mode.kind === 'global' ? installGlobal(home, mode.settingsFile) : installSelfContained(mode);
+}
+// The original shape: hooks + skills copied under ~/.claude, absolute command
+// paths, skills calling a bare `plumbbob` (which the global npm install puts on
+// PATH).
+function installGlobal(home, settingsFile) {
+    const hooksDir = join(home, '.claude', 'plumbbob', 'hooks');
+    const skillsDir = join(home, '.claude', 'skills');
+    cpSync(packageDir('hooks'), hooksDir, { recursive: true });
+    for (const file of HOOK_FILES) {
+        chmodSync(join(hooksDir, file), 0o755);
+    }
+    cpSync(packageDir('skills'), skillsDir, { recursive: true });
+    substituteSkillBins(skillsDir, 'plumbbob');
+    writeSettings(settingsFile, mergeRegistration(readSettings(settingsFile), hooksDir));
+    process.stdout.write(`plumbbob: installed hooks → ${hooksDir}, skills → ${skillsDir}.\n` +
+        `plumbbob: registered the hooks in ${settingsFile} (global scope).\n` +
+        'plumbbob: restart Claude Code (or reload settings) for the hooks to take effect.\n' +
+        "plumbbob: the skills call a bare `plumbbob`; the npm install puts it (and `pb`) on PATH. From a dev checkout add `alias plumbbob='node <repo>/src/cli.ts'`.\n");
+    return 0;
+}
+// The self-contained shape: nothing under ~/.claude. Hooks are referenced in
+// place inside node_modules; only the skills are copied into the repo (Claude
+// Code discovers skills under .claude/skills/, never from node_modules), with
+// their bin invocation rewritten to the project-local binary.
+function installSelfContained(mode) {
+    const skillsDir = join(mode.repoRoot, '.claude', 'skills');
+    cpSync(packageDir('skills'), skillsDir, { recursive: true });
+    substituteSkillBins(skillsDir, SELF_BIN);
+    writeSettings(mode.settingsFile, mergeRegistration(readSettings(mode.settingsFile), SELF_HOOKS_DIR, true));
+    const note = existsSync(join(mode.repoRoot, 'node_modules', 'plumbbob', 'hooks'))
+        ? ''
+        : 'plumbbob: note — node_modules/plumbbob/ is not present in this repo yet. Add plumbbob as a dependency (e.g. `pnpm add -D plumbbob`) so the registered hooks resolve.\n';
+    const scope = mode.settingsFile.endsWith('settings.local.json') ? 'local' : 'project';
+    process.stdout.write(`plumbbob: copied skills → ${skillsDir} (bin → ${SELF_BIN}). Nothing was written under ~/.claude.\n` +
+        `plumbbob: referenced the hooks at ${SELF_HOOKS_DIR} and registered them in ${mode.settingsFile} (${scope} scope).\n` +
+        note +
+        'plumbbob: restart Claude Code (or reload settings) for the hooks to take effect.\n' +
+        'plumbbob: drive the workflow from the chat with the `pb-*` driver skills. Keep the transition verbs OUT of your settings allowlist — each driver skill self-authorizes its own verb, so a stray model-initiated transition still surfaces a permission prompt.\n');
+    return 0;
+}
+// Resolve which install shape and settings file to use. Explicit flags win;
+// with no flag, auto-detect — a project-local plumbbob installs self-contained
+// (personal, into settings.local.json), anything else installs global. Returns
+// null when a project scope is required but cwd is not in a git repo.
+function resolveMode(cwd, home, args) {
+    const globalFile = join(home, '.claude', 'settings.json');
+    if (args.includes('--global')) {
+        return { kind: 'global', settingsFile: globalFile };
+    }
+    const wantsProject = args.includes('--project');
+    const wantsLocal = args.includes('--local');
+    const auto = !wantsProject && !wantsLocal && isProjectLocal(cwd);
+    if (!wantsProject && !wantsLocal && !auto) {
+        return { kind: 'global', settingsFile: globalFile };
+    }
+    const repoRoot = findRepoRoot(cwd);
+    if (repoRoot === null) {
+        return null;
+    }
+    const file = wantsProject ? 'settings.json' : 'settings.local.json';
+    return { kind: 'self', settingsFile: join(repoRoot, '.claude', file), repoRoot };
+}
+// plumbbob is project-local when its package directory lives inside this repo's
+// node_modules (a `pnpm add` / `npm install` dependency), as opposed to a global
+// install or a dev checkout.
+function isProjectLocal(cwd) {
+    const repoRoot = findRepoRoot(cwd);
+    if (repoRoot === null) {
+        return false;
+    }
+    return packageRoot().startsWith(join(repoRoot, 'node_modules') + sep);
+}
+// Rewrite the bin placeholder in every copied skill (both the `!`...`` status
+// pre-injection and the allowed-tools patterns) to the resolved invocation.
+function substituteSkillBins(skillsDir, bin) {
+    for (const name of readdirSync(skillsDir)) {
+        const file = join(skillsDir, name, 'SKILL.md');
+        if (!statSync(join(skillsDir, name)).isDirectory() || !existsSync(file)) {
+            continue;
+        }
+        const src = readFileSync(file, 'utf8');
+        if (src.includes(BIN_PLACEHOLDER)) {
+            writeFileSync(file, src.split(BIN_PLACEHOLDER).join(bin));
+        }
+    }
+}
+// The plumbbob package root (parent of hooks/ and skills/), off this module's URL.
+function packageRoot() {
+    return fileURLToPath(new URL('../../', import.meta.url));
+}
+function packageDir(name) {
+    return join(packageRoot(), name);
+}

package/dist/verbs/spike.js

@@ -0,0 +1,113 @@
+// `plumbbob spike` (D18) — the spike lifecycle for a genuine fork the design
+// phase couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree +
+// `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default opts a/b)
+// and sets STATE=SPIKE; the main tree stays DESIGN-locked while you experiment in
+// the worktrees, which are hook-dormant by construction — the untracked sidecar
+// (D17) doesn't exist in a fresh checkout, so the hooks find no STATE there.
+// `spike done` removes every spike worktree + branch and returns to DESIGN.
+//
+// Worktree git calls run directly here rather than via lib/git.ts (which holds the
+// 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 { findRepoRoot } from "../lib/git.js";
+import { hasSession, readState, writeState } from "../lib/sidecar.js";
+const DEFAULT_OPTIONS = ['a', 'b'];
+export function spike(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 positionals = args.filter((a) => !a.startsWith('--'));
+    if (positionals[0] === 'done') {
+        return spikeDone(root);
+    }
+    return spikeStart(root, positionals);
+}
+function spikeStart(root, positionals) {
+    const state = readState(root);
+    if (state === 'SPIKE') {
+        process.stderr.write('plumbbob: already in a spike. Run `plumbbob spike done` to close it first.\n');
+        return 1;
+    }
+    if (state !== 'DESIGN') {
+        process.stderr.write(`plumbbob: spike starts from DESIGN (current state is ${state ?? 'UNKNOWN'}). ` +
+            'A spike is a deliberate fork — close the current step first with `done`.\n');
+        return 1;
+    }
+    const slug = sanitize(positionals[0] ?? '');
+    if (slug.length === 0) {
+        process.stderr.write('plumbbob: spike needs a slug. Try: plumbbob spike "auth-store" a b.\n');
+        return 1;
+    }
+    const explicit = positionals.slice(1).map(sanitize).filter((o) => o.length > 0);
+    const options = explicit.length > 0 ? explicit : DEFAULT_OPTIONS;
+    const created = [];
+    for (const opt of options) {
+        const path = join(dirname(root), `${basename(root)}-spike-${slug}-${opt}`);
+        if (existsSync(path)) {
+            process.stderr.write(`plumbbob: ${path} already exists — remove it or run \`plumbbob spike done\` first.\n`);
+            return 1;
+        }
+        git(root, ['worktree', 'add', '-b', `spike/${slug}-${opt}`, path, 'HEAD']);
+        created.push(path);
+    }
+    writeState(root, 'SPIKE');
+    process.stdout.write(`plumbbob: STATE=SPIKE — the main tree stays DESIGN-locked. 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) {
+    const state = readState(root);
+    if (state !== 'SPIKE') {
+        process.stderr.write(`plumbbob: no active spike (state is ${state ?? 'UNKNOWN'}).\n`);
+        return 1;
+    }
+    for (const path of spikeWorktrees(root)) {
+        git(root, ['worktree', 'remove', '--force', path]);
+    }
+    git(root, ['worktree', 'prune']);
+    for (const branch of spikeBranches(root)) {
+        git(root, ['branch', '-D', branch]);
+    }
+    writeState(root, 'DESIGN');
+    process.stdout.write('plumbbob: spike closed — STATE=DESIGN, worktrees and branches removed. ' +
+        'Record the verdict (which option won, and why) in intent.md before you `build`.\n');
+    return 0;
+}
+// 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) {
+    const out = git(root, ['worktree', 'list', '--porcelain']);
+    const paths = [];
+    let current = null;
+    for (const line of out.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            current = line.slice('worktree '.length);
+        }
+        else if (current !== null && line.startsWith('branch refs/heads/spike/')) {
+            paths.push(current);
+        }
+    }
+    return paths;
+}
+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);
+}
+function sanitize(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function git(root, args) {
+    return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'inherit'],
+    }).trim();
+}