plumbbob 0.6.6 → 0.8.3

package/dist/verbs/checkpoint.js

@@ -9,8 +9,9 @@
 // the same way.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { buildFolder, buildLogPath, checkpointsPath, clearHandoff, hasSession, intentPath, seamPath, stepPath, } from "../lib/sidecar.js";
+import { buildFolder, buildLogPath, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
+import { checkLatch } from "../lib/latch.js";
 import { markStepDone, parseSteps, parseTitle } from "../lib/orient.js";
 import { parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
@@ -28,8 +29,21 @@ export async function checkpoint(cwd, args) {
         process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
         return 1;
     }
+    // The approval latch (D64) precedes the check gate (C4): the tick may not land
+    // without a human turn since entry, a grant, or a dormant ledger. The refusal
+    // message is the pause affordance — exit 1 and hand the turn back.
+    const latch = checkLatch(root, step);
+    if (!latch.allow) {
+        process.stderr.write(latch.message);
+        return 1;
+    }
     const gate = await runCheck(root);
     if (gate !== 0) {
+        if (gate === 1) {
+            // The dogfood receipt (research/07 Build 2b): red attempts before green
+            // are a per-step count. Harness breakage (2) is not a red check.
+            bumpStepStat(root, undefined, step, 'redChecks');
+        }
         process.stderr.write(gate === 2
             ? 'plumbbob: the check gate itself broke — checkpoint refuses until the harness is fixed.\n'
             : 'plumbbob: check failed (red) — checkpoint refuses on red. Fix it and re-run.\n');
@@ -47,10 +61,12 @@ export async function checkpoint(cwd, args) {
     }
     appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
     flipIntent(root, step);
+    stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
     logCheckpoint(root, step, sha);
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
     clearHandoff(root); // the agent-run ledger is step-scoped (D47) — clear it with the markers.
+    clearTick(root); // the entry stamp (D64) is spent — the next `build <n>` re-stamps.
     process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
     return 0;
 }
@@ -62,9 +78,20 @@ export async function checkpoint(cwd, args) {
 // An optional `--body` (stdin heredoc, D34) rides along; the folder is whitelisted
 // artifact plane, so there is no scope-drift to warn about.
 function checkpointPlan(root, args) {
+    // The latch (D64) covers the plan commit too, keyed on the TICK that `start`
+    // stamped: the plan pause is a pause. No step number — a range grant does not
+    // speak to a plan.
+    const latch = checkLatch(root, null);
+    if (!latch.allow) {
+        process.stderr.write(latch.message);
+        return 1;
+    }
     stagePath(root, buildFolder(root));
     const sha = commit(root, planSubject(root), bodyArg(args) ?? undefined);
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
+    // The plan landing consumes `start`'s entry stamp (D64): a later hand-built diff
+    // (no `build <n>`) must find no stale TICK and stay guidance-governed.
+    clearTick(root);
     process.stdout.write(`plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
     return 0;
 }
@@ -108,6 +135,7 @@ function warnScopeDrift(root, step) {
     const seam = seamTokens(root, step);
     const outside = scopeDrift(stagedPaths(root), seam);
     if (outside.length > 0) {
+        bumpStepStat(root, undefined, step, 'driftWarnings'); // the dogfood receipt (research/07 2b)
         process.stderr.write(`plumbbob: heads-up — staged paths outside step ${step}'s seam: ${outside.join(', ')}. ` +
             `The checkpoint captures them; if that's real scope drift, the plan may need a \`/pb-step\` revision.\n`);
     }
@@ -150,7 +178,7 @@ function logCheckpoint(root, step, sha) {
     try {
         const path = buildLogPath(root);
         const date = new Date().toISOString().slice(0, 10);
-        const line = checkpointLogLine(date, step, sha, titleForStep(root, step));
+        const line = checkpointLogLine(date, step, sha, titleForStep(root, step), statsSuffix(root, step));
         const updated = appendToSection(readFileSync(path, 'utf8'), 'Log', line);
         if (updated !== null) {
             writeFileSync(path, updated);
@@ -160,6 +188,27 @@ function logCheckpoint(root, step, sha) {
         // best-effort ledger; never fail a checkpoint over the build-log.
     }
 }
+// The compact receipt riding the Log line (research/07 Build 2b): only what
+// accrued — a clean first-try step gets no suffix at all. Wall-clock needs both
+// stamps (a hand-built step never ran `build <n>`, so it has no startedAt).
+function statsSuffix(root, step) {
+    const stats = readStats(root)[String(step)];
+    if (stats === undefined)
+        return null;
+    const parts = [];
+    if ((stats.redChecks ?? 0) > 0)
+        parts.push(`${stats.redChecks} red`);
+    if ((stats.driftWarnings ?? 0) > 0)
+        parts.push(`${stats.driftWarnings} drift`);
+    if ((stats.reverts ?? 0) > 0)
+        parts.push(`${stats.reverts} revert${stats.reverts === 1 ? '' : 's'}`);
+    if (stats.startedAt !== undefined && stats.landedAt !== undefined) {
+        const ms = Date.parse(stats.landedAt) - Date.parse(stats.startedAt);
+        if (Number.isFinite(ms) && ms >= 0)
+            parts.push(ms < 60_000 ? '<1m' : `${Math.round(ms / 60_000)}m`);
+    }
+    return parts.length > 0 ? parts.join(', ') : null;
+}
 // The CLI-owned, deterministic commit subject: the step's title when intent.md still
 // carries one, else the bare `plumbbob: step N done` fallback (D34 — the CLI owns the
 // subject; a `-m` override or `--body` prose is a separate concern).

package/dist/verbs/doctor.js

@@ -28,10 +28,11 @@ import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runDoctor } from 'checkride';
 import { listAgents } from "../lib/agents.js";
+import { gateDetectsTools } from "../lib/check.js";
 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";
+import { buildDir, excludeControl, listBuilds, readTurn, setActiveBuild, sidecarDir, slugify } from "../lib/sidecar.js";
+import { resolveString, settingsPath } 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) {
@@ -205,8 +206,12 @@ export function migrateSidecar(root) {
     const configPath = join(dir, 'config');
     if (existsSync(configPath)) {
         if (!existsSync(settingsPath(root))) {
+            // Carry forward ONLY what the legacy config actually held — a `check` line,
+            // nothing else. No invented `auto` (the config never had one, it defaults to
+            // false, and it belongs in settings.local.json): migration yields exactly what
+            // a fresh `start` would, plus the check. An empty config → an empty `{}`.
             const check = configCheck(configPath);
-            const settings = check === null ? { auto: false } : { check, auto: false };
+            const settings = check === null ? {} : { check };
             writeFileSync(settingsPath(root), `${JSON.stringify(settings, null, 2)}\n`);
             actions.push(check === null ? 'config → settings.json' : `config → settings.json (check: ${check})`);
         }
@@ -219,7 +224,7 @@ export function migrateSidecar(root) {
         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);
+        setActiveBuild(root, slug);
         actions.push(`active session → builds/${slug} (the cursor)`);
     }
     // archive/<slug> → builds/<slug>. These are "done" by simply not being the cursor.
@@ -384,6 +389,15 @@ async function gateReport(cwd) {
             if (c.required && c.status !== 'ok')
                 failed += 1;
         }
+        // The week-1 bounce, called out where the human can see it coming
+        // (research/07 Build 2a): no CODE checks detected means checkpoints are
+        // gated only by checkride's always-on repo checks — either a vacuous
+        // refusal or, worse, a green that tested nothing. Informational, with the
+        // exact fix; `start` surfaces the same probe at plan time.
+        if (!gateDetectsTools(report.checks)) {
+            lines.push('  ○ gate: no code checks detected — checkpoints would be gated by the always-on repo checks alone;' +
+                ' set {"check": "npm test"} in .plumbbob/settings.json, or add tool configs checkride can see');
+        }
         return { lines, failed };
     }
     catch (err) {
@@ -402,6 +416,25 @@ function toolRow(c) {
     const hint = c.status !== 'ok' && c.hint !== null ? `\n      → ${c.hint}` : '';
     return `  ${mark} ${c.slot ?? c.name} ← ${c.adapter}${version}${hint}`;
 }
+// The approval-latch health probe (D64): is the turn ledger live? `.plumbbob/TURN`
+// holds a count once the UserPromptSubmit hook has ticked at least once, so a present
+// count means the checkpoint latch is armed — its absence means the tick is
+// guidance-only. Dormant is a legitimate state (a host with no hooks behaves exactly
+// as it always has), never a failure — so this section adds nothing to the problem
+// count. The dormant hint names the hook because a missing ledger almost always means
+// it never wired, and that hook rides in either install kind (the marketplace
+// plugin's hooks/hooks.json or an init-style link). Outside a repo there is no
+// worktree ledger to read, so the section is skipped entirely.
+function latchReport(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null)
+        return { lines: [], failed: 0 };
+    const turn = readTurn(root);
+    const line = turn === null
+        ? '  ○ latch: dormant — guidance only (no turn ledger yet; it ticks on your first prompt when the UserPromptSubmit hook is wired — re-run after one to confirm)'
+        : `  ✓ latch: live (turn ${turn})`;
+    return { lines: ['', 'plumbbob doctor — approval latch (D64)', line], failed: 0 };
+}
 export async function doctor(cwd, args = []) {
     const checks = pluginChecks();
     const out = ['plumbbob doctor — plugin install'];
@@ -414,7 +447,9 @@ export async function doctor(cwd, args = []) {
     out.push(...agents.lines);
     const gate = await gateReport(cwd);
     out.push(...gate.lines);
-    const failed = checks.filter((c) => !c.ok).length + sidecar.failed + agents.failed + gate.failed;
+    const latch = latchReport(cwd);
+    out.push(...latch.lines);
+    const failed = checks.filter((c) => !c.ok).length + sidecar.failed + agents.failed + gate.failed + latch.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

@@ -8,8 +8,7 @@
 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 { checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { parseTitle } from "../lib/orient.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
@@ -20,6 +19,7 @@ export function finish(cwd, args = []) {
     const { build: slug } = resolveBuild(root, args);
     if (existsSync(reportPath(root, slug))) {
         appendCheckpointShas(root, slug);
+        appendStats(root, slug);
     }
     else {
         process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
@@ -34,18 +34,19 @@ export function finish(cwd, args = []) {
         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.
+    // Clear the control state: the in-flight markers first, then the session sentinel
+    // last (so "no session" flips exactly at the end). Deleting STATE also drops the
+    // cursor (D28) — cursor and session share the one file now, so a single delete does
+    // both. 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);
-    }
+    // The latch's per-build entry stamp and the one-turn grant go with the session
+    // (D64/D65): a grant is one-turn by construction, but the session's last tick is
+    // the last time it was rewritten — left behind, a stale `auto` could self-approve
+    // the next session's first landing.
+    clearTick(root, slug);
+    setGrant(root, null);
     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. ` +
@@ -81,6 +82,55 @@ function bodyArg(args) {
         return null;
     }
 }
+// Roll the per-step receipts (research/07 Build 2b) into report.md as a `## Stats`
+// table — one row per step plus totals, so "is the loop worth it?" is a table,
+// not a feeling. Silently skipped when nothing accrued (an old build, a build
+// with no red/revert/drift and no `build <n>` stamps has nothing to say).
+function appendStats(root, slug) {
+    const stats = readStats(root, slug);
+    const steps = Object.keys(stats)
+        .map(Number)
+        .filter((n) => Number.isFinite(n))
+        .sort((a, b) => a - b);
+    if (steps.length === 0) {
+        return;
+    }
+    const totals = { redChecks: 0, driftWarnings: 0, reverts: 0, wallMs: 0 };
+    const rows = steps.map((n) => {
+        const s = stats[String(n)] ?? {};
+        totals.redChecks += s.redChecks ?? 0;
+        totals.driftWarnings += s.driftWarnings ?? 0;
+        totals.reverts += s.reverts ?? 0;
+        const wall = wallClockMs(s);
+        totals.wallMs += wall ?? 0;
+        return `| ${n} | ${s.redChecks ?? 0} | ${s.driftWarnings ?? 0} | ${s.reverts ?? 0} | ${formatWall(wall)} |`;
+    });
+    appendFileSync(reportPath(root, slug), [
+        '',
+        '## Stats',
+        '',
+        '| step | red checks | drift warnings | reverts | wall-clock |',
+        '|------|------------|----------------|---------|------------|',
+        ...rows,
+        `| **total** | ${totals.redChecks} | ${totals.driftWarnings} | ${totals.reverts} | ${formatWall(totals.wallMs > 0 ? totals.wallMs : null)} |`,
+        '',
+    ].join('\n'));
+}
+function wallClockMs(s) {
+    if (s.startedAt === undefined || s.landedAt === undefined) {
+        return null;
+    }
+    const ms = Date.parse(s.landedAt) - Date.parse(s.startedAt);
+    return Number.isFinite(ms) && ms >= 0 ? ms : null;
+}
+// `—` when unknown (a hand-built step never ran `build <n>`, so it has no
+// startedAt), `<1m` under a minute, whole minutes otherwise.
+function formatWall(ms) {
+    if (ms === null) {
+        return '—';
+    }
+    return ms < 60_000 ? '<1m' : `${Math.round(ms / 60_000)}m`;
+}
 // 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.

package/dist/verbs/revert.js

@@ -18,7 +18,7 @@ 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, resolveBuild, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
+import { bumpStepStat, 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);
@@ -53,12 +53,19 @@ export function revert(cwd, args) {
     // ignored files alone, so they must be removed explicitly afterward).
     const seam = readSeamTokens(root, slug);
     const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam) && !isArtifactPath(p));
+    // The dogfood receipt (research/07 2b): a revert against an in-flight step is a
+    // datapoint — read the marker before it goes, bump after the reset (the sidecar
+    // is preserved through it, so the write survives).
+    const inFlight = readInFlightStep(root, slug);
     resetPreserving(root, sha, plumbbobOwnedPaths(root));
     for (const rel of toRemove) {
         rmSync(join(root, rel), { force: true, recursive: true });
     }
     rmSync(seamPath(root, slug), { force: true });
     rmSync(stepPath(root, slug), { force: true });
+    if (inFlight !== null) {
+        bumpStepStat(root, slug, inFlight, 'reverts');
+    }
     process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — back at the boundary. Park lines and intent edits were preserved.\n`);
     return 0;
 }
@@ -139,3 +146,14 @@ function readSeamTokens(root, slug) {
         return [];
     }
 }
+// The in-flight STEP number, or null when none — read for the revert receipt
+// before the marker is cleared.
+function readInFlightStep(root, slug) {
+    try {
+        const raw = readFileSync(stepPath(root, slug), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/verbs/start.js

@@ -1,16 +1,17 @@
 // `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, open
 // the session. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
 import { fileURLToPath } from 'node:url';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { detectGate } from "../lib/check.js";
 import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
-import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, } from "../lib/sidecar.js";
-import { settingsPath, setLocalSetting } from "../lib/settings.js";
+import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
+import { settingsPath } from "../lib/settings.js";
 // D24/D32: the gate is checkride unless a `check` setting overrides it, so
 // settings.json seeds with no `check` key at all — absence IS the default. The
 // templates' {{CHECK}} line is a human-readable echo of that.
 const CHECK_ECHO = 'checkride (set a "check" key in .plumbbob/settings.json to override)';
-export function start(cwd, args) {
+export async function start(cwd, args) {
     const positionals = args.filter((a) => !a.startsWith('--'));
     const allowDirty = args.includes('--allow-dirty');
     const local = args.includes('--local');
@@ -50,8 +51,20 @@ export function start(cwd, args) {
     }
     const sha = headSha(root);
     mkdirSync(sidecarDir(root), { recursive: true });
-    beginSession(root);
-    writeFileSync(settingsPath(root), `${JSON.stringify({ auto: false }, null, 2)}\n`);
+    // beginSession writes STATE — the session sentinel and, in its content, the cursor
+    // (D28). Point it at this build (null under --local, which has no cursor). The
+    // cursor lives in STATE, not settings.local.json, so that overlay stays human-owned.
+    beginSession(root, local ? null : slug);
+    // Scaffold the tracked settings.json ONLY when absent, and seed it EMPTY — the
+    // human owns this file once it exists (their `check` gate lives here), so a
+    // re-start must never touch it. We inject no opinions even on first create:
+    // absence of `check` already means checkride and absence of `auto` already means
+    // false (see settings.ts), so `{}` is exactly "all defaults". `auto` in
+    // particular is a personal preference that belongs in settings.local.json, not
+    // this tracked file — seeding it here was the bug that clobbered custom checks.
+    if (!existsSync(settingsPath(root))) {
+        writeFileSync(settingsPath(root), `${JSON.stringify({}, null, 2)}\n`);
+    }
     // D26: `--local` keeps today's fully-untracked flat layout (whole `.plumbbob/`
     // excluded); the default plants a tracked, PR-riding `builds/<slug>/` folder
     // (D26) and points the per-worktree cursor at it (D28), excluding only control
@@ -71,11 +84,29 @@ export function start(cwd, args) {
         writeFileSync(join(dir, 'checkpoints'), `baseline ${sha}\n`);
         writeFileSync(join(dir, 'intent.md'), stamp(readTemplate('intent.md'), title, CHECK_ECHO));
         writeFileSync(join(dir, 'build-log.md'), stamp(readTemplate('build-log.md'), title, CHECK_ECHO));
-        setLocalSetting(root, 'activeBuild', slug);
         excludeControl(root);
         intentLocation = `.plumbbob/builds/${slug}/intent.md`;
     }
+    // The plan's entry stamp (D64): `checkpoint --plan` latches on this tick. Skipped
+    // when TURN is absent — including the known first-session seam where the hook has
+    // never ticked, which leaves that one plan commit guidance-governed. Any grant
+    // lying around is a leftover from an earlier session (a legitimate one is minted
+    // by a `/pb-build` prompt, which never runs `start`) — clear it so a stale `auto`
+    // can't self-approve this session's plan (D65: one-turn lifetime).
+    setGrant(root, null);
+    stampTick(root, local ? null : slug);
     process.stdout.write(`plumbbob: started "${title}" — baseline ${sha.slice(0, 9)}. Frame and decide in ${intentLocation}; \`build\` a step once the decisions are made.\n`);
+    // The plan-time gate probe (research/07 Build 2a): if checkride sees no code
+    // checks here, say so NOW — while the human is still deciding — instead of at
+    // the first checkpoint, where the gate either refuses a vacuous run or, worse,
+    // greens on the always-on repo checks alone. Guidance only: never the exit
+    // code (C1), and a configured `check` or a probe hiccup stays silent.
+    const gate = await detectGate(root);
+    if (gate.configured === null && !gate.detected) {
+        process.stderr.write('plumbbob: heads-up — the check gate sees no code checks in this repo (checkride detected no tools).\n' +
+            '  Set one while you are still planning: add {"check": "npm test"} to .plumbbob/settings.json.\n' +
+            '  Checkpoints gate on it — with nothing to run, the gate refuses or greens vacuously.\n');
+    }
     return 0;
 }
 // Derived slugs carry a `YYYY-MM-DD-` prefix (local time) so `builds/` sorts

package/dist/verbs/status.js

@@ -3,10 +3,10 @@
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { findRepoRoot } from "../lib/git.js";
+import { commitsSince, findRepoRoot } from "../lib/git.js";
 import { SLOTS, readHarnessFile, resolveAgent, } from "../lib/agents.js";
 import { buildFolder, buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
-import { formatOrientation, orient } from "../lib/orient.js";
+import { formatOrientation, lastLedgerSha, orient } from "../lib/orient.js";
 function readOr(path) {
     try {
         return readFileSync(path, 'utf8');
@@ -33,12 +33,19 @@ export function status(cwd, args = []) {
         }
     }
     const inFlightRaw = readOr(stepPath(root, slug)).trim();
+    // The out-of-band count (D66) needs git (orient is pure), so status measures it:
+    // commits on HEAD since the last ledger line's SHA — baseline, plan, or step, so
+    // a commit landing before the first step checkpoint still surfaces. No ledger yet
+    // ⇒ nothing to reconcile against ⇒ 0.
+    const checkpoints = readOr(checkpointsPath(root, slug));
+    const anchor = lastLedgerSha(checkpoints);
     const orientation = orient({
         intent: readOr(intentPath(root, slug)),
         buildLog: readOr(buildLogPath(root, slug)),
-        checkpoints: readOr(checkpointsPath(root, slug)),
+        checkpoints,
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
         spiking: inSpike(root, slug),
+        outOfBand: anchor === null ? 0 : commitsSince(root, anchor),
     });
     const lines = [formatOrientation(orientation), ...harnessSection(root, slug)];
     process.stdout.write(`${lines.join('\n')}\n`);

package/dist/verbs/turn.js

@@ -0,0 +1,106 @@
+// `plumbbob turn` — the turn-ledger hook (D64). Wired to Claude Code's
+// UserPromptSubmit, it runs once per human prompt: it ticks `.plumbbob/TURN` (the
+// monotonic count of human turns the checkpoint latch reads to know a human turn
+// intervened since a step began) and rewrites `.plumbbob/GRANT` from the literal
+// prompt — minting a one-turn self-approval only when the human typed
+// `/pb-build --auto` or a `N-M` range (D65), clearing it otherwise. Pure machinery,
+// not a user verb: it writes nothing to stdout and ALWAYS exits 0, so a broken tick
+// can never wedge prompting (C3).
+import { readFileSync, writeFileSync } from 'node:fs';
+import { findSessionRoot, setGrant, turnPath } from "../lib/sidecar.js";
+export function turn(cwd, _args) {
+    try {
+        applyTurn(cwd, readStdin());
+    }
+    catch {
+        // C3: a broken turn must never wedge a prompt — swallow and exit 0.
+    }
+    return 0;
+}
+// The testable core: apply one tick given the raw hook stdin. Split from the fd-0
+// read so the unit tests can drive it directly — an in-process test cannot feed fd 0
+// (the same constraint checkpoint's `--body` lives under).
+export function applyTurn(cwd, raw) {
+    const root = findSessionRoot(cwd);
+    if (root === null)
+        return 0; // no active session above cwd — silent no-op.
+    writeFileSync(turnPath(root), `${readTurn(root) + 1}\n`);
+    setGrant(root, grantFromPrompt(extractPrompt(raw)));
+    return 0;
+}
+// GRANT is minted only from a literal `pb-build` invocation the human typed:
+// `pb-build` is disable-model-invocation, so this string can only come from a human
+// keystroke, never model-authored pressure (D65). A bounded range beats `--auto`
+// (bounded wins); a bare `/pb-build`, or any non-invocation prompt, mints nothing.
+// The namespaced `/plumbbob:pb-build` form is honored alongside the bare one.
+//
+// Only the invocation's own arguments can mint: the tokens that follow it on its
+// line, up to the first token that isn't argument-shaped (a flag, a step number, a
+// range). An incidental range elsewhere in the prompt — an issue number, a pasted
+// `2020-2024` — is prose, not a grant. Trailing sentence punctuation on an argument
+// (`/pb-build 1-3.`) is still the argument the human typed.
+export function grantFromPrompt(prompt) {
+    const invocation = /\/(?:plumbbob:)?pb-build\b/.exec(prompt);
+    if (invocation === null)
+        return null;
+    const line = prompt.slice(invocation.index + invocation[0].length).split('\n', 1)[0] ?? '';
+    let auto = false;
+    let ceiling;
+    for (const token of line.split(/\s+/)) {
+        const word = token.replace(/[.,;:!?]+$/, '');
+        if (word === '')
+            continue;
+        if (word === '--auto') {
+            auto = true;
+            continue;
+        }
+        const range = /^\d+-(\d+)$/.exec(word);
+        if (range !== null) {
+            ceiling = range[1];
+            continue;
+        }
+        if (/^\d+$/.test(word) || word.startsWith('-'))
+            continue; // a step number or another flag
+        break; // free text — the arguments have ended
+    }
+    if (ceiling !== undefined)
+        return `range ${ceiling}`;
+    return auto ? 'auto' : null;
+}
+// Extract the `prompt` field from the UserPromptSubmit JSON, or '' when the input is
+// absent, unparseable, or carries no string prompt. Malformed input contributes
+// nothing (D27): the tick still lands (a human turn did occur) and the empty prompt
+// clears any GRANT; the verb never throws over bad stdin.
+function extractPrompt(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.prompt === 'string' ? parsed.prompt : '';
+    }
+    catch {
+        return '';
+    }
+}
+// The current TURN as a non-negative integer, or 0 when the ledger is absent or
+// unreadable — so the first tick creates it at 1.
+function readTurn(root) {
+    try {
+        const n = Number.parseInt(readFileSync(turnPath(root), 'utf8').trim(), 10);
+        return Number.isFinite(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+// Read the hook JSON from fd 0. An interactive TTY never sends EOF, so skip the read
+// there rather than hang (mirrors checkpoint's `--body`); a read error degrades to
+// '' — extractPrompt then clears the grant and the tick still lands.
+function readStdin() {
+    if (process.stdin.isTTY === true)
+        return '';
+    try {
+        return readFileSync(0, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/verbs/use.js

@@ -1,14 +1,13 @@
 // `plumbbob use <slug>` (D30) — re-point the per-worktree cursor at an existing
 // build and resume it. Both switching and resuming are the same one word (Q10,
-// `nvm use`-shaped): the cursor is a single scalar key in settings.local.json, so
-// pointing it elsewhere IS the switch and one-active-per-worktree holds by
+// `nvm use`-shaped): the cursor is STATE's single-line content, so pointing it
+// elsewhere IS the switch and one-active-per-worktree holds by
 // construction (D28). It validates the target folder exists, and warns — but
 // allows — leaving a build with a step in flight: that surviving in-flight state
 // is D26's whole payoff, resumed the next time you `use` that build.
 import { existsSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { activeBuild, hasSession, intentPath, listBuilds, stepPath } from "../lib/sidecar.js";
-import { setLocalSetting } from "../lib/settings.js";
+import { activeBuild, hasSession, intentPath, listBuilds, setActiveBuild, stepPath } from "../lib/sidecar.js";
 export function use(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -32,7 +31,7 @@ export function use(cwd, args) {
         process.stderr.write(`plumbbob: note — build "${leaving}" has a step in flight; its in-flight state is preserved ` +
             `and resumes when you \`use ${leaving}\` again.\n`);
     }
-    setLocalSetting(root, 'activeBuild', target);
+    setActiveBuild(root, target);
     const resuming = existsSync(stepPath(root, target)) ? ' (a step is in flight — `status` shows where)' : '';
     process.stdout.write(`plumbbob: now on build "${target}"${resuming}. \`status\` to orient.\n`);
     return 0;

package/hooks/hooks.json

@@ -1,5 +1,13 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-bash-commit.sh\"" }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit|NotebookEdit",
@@ -7,6 +15,13 @@
           { "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/post-edit.sh\"" }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/bin/plumbbob\" turn" }
+        ]
+      }
     ]
   }
 }

package/hooks/post-edit.sh

@@ -5,16 +5,16 @@
 # the tools are absent or there is no session. tsc is deferred to the heavy tier
 # (D25): it has no true single-file mode and would tax every keystroke.
 
-# The repo root is the nearest ancestor whose .plumbbob/settings.local.json carries
-# an `activeBuild` cursor — the per-worktree signal that a tracked build is live
-# here (D28). Grep the same way the file_path read below does: a plain pattern
-# match, no JSON parse. The cursor replaces the old .plumbbob/STATE probe as the
-# "a build is active here" root marker.
+# The repo root is the nearest ancestor whose .plumbbob/STATE is NON-EMPTY — the
+# per-worktree signal that a tracked build is live here (D28). STATE's existence
+# means "a session is active"; its content is the active-build cursor, so a non-empty
+# STATE is exactly "a tracked build is live" (the `--local` layout leaves STATE empty,
+# and this file-scoped check is a tracked-build affordance). `-s` tests both existence
+# and non-emptiness — no JSON parse, no cursor file to read.
 find_root() {
   d=$(pwd -P)
   while [ -n "$d" ]; do
-    if [ -f "$d/.plumbbob/settings.local.json" ] &&
-      grep -q '"activeBuild"' "$d/.plumbbob/settings.local.json" 2>/dev/null; then
+    if [ -s "$d/.plumbbob/STATE" ]; then
       printf '%s' "$d"
       return 0
     fi