plumbbob 0.6.5 → 0.8.0

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;
 }
@@ -81,9 +108,10 @@ function planSubject(root) {
     return title ? `plumbbob: plan — ${title}` : 'plumbbob: plan';
 }
 // Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
-// intent.md. Returns null when none can be determined.
+// intent.md. Returns null when none can be determined. A `-m` value is a message,
+// never a step — `checkpoint -m "2"` must not read as step 2.
 function resolveStep(root, args) {
-    const explicit = args.find((a) => /^\d+$/.test(a));
+    const explicit = args.filter((_, i) => args[i - 1] !== '-m').find((a) => /^\d+$/.test(a));
     if (explicit !== undefined) {
         return Number(explicit);
     }
@@ -107,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`);
     }
@@ -135,7 +164,10 @@ function flipIntent(root, step) {
         writeFileSync(intentPath(root), markStepDone(readFileSync(intentPath(root), 'utf8'), step));
     }
     catch {
-        // best-effort bookkeeping; the checkpoint SHA is the source of truth.
+        // Best-effort bookkeeping — the checkpoint SHA is the source of truth — but the
+        // dashboard reads intent.md, so a swallowed failure here makes orientation lie.
+        process.stderr.write(`plumbbob: heads-up — could not flip step ${step} to [x] in intent.md; ` +
+            `the checkpoint is recorded, but the dashboard will still show step ${step} as next. Flip it by hand.\n`);
     }
 }
 // Append a dated line to the build-log's `## Log` so the build's history accrues at
@@ -146,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);
@@ -156,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).
@@ -179,9 +232,10 @@ function messageArg(args) {
 // so the skill can compose proportional prose the CLI never could. Returns null
 // when the flag is absent or stdin is empty — either way the deterministic
 // fallback body takes over. Reading fd 0 blocks until EOF, which the heredoc
-// supplies; a read error (no stdin attached) degrades to the fallback.
+// supplies; a read error (no stdin attached) degrades to the fallback, and an
+// interactive TTY — which would never send EOF — skips the read instead of hanging.
 function bodyArg(args) {
-    if (!args.includes('--body')) {
+    if (!args.includes('--body') || process.stdin.isTTY === true) {
         return null;
     }
     try {

package/dist/verbs/doctor.js

@@ -28,9 +28,10 @@ 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 { buildDir, excludeControl, listBuilds, readTurn, sidecarDir, slugify } from "../lib/sidecar.js";
 import { resolveString, settingsPath, setLocalSetting } from "../lib/settings.js";
 // The plumbbob package's own skills/ dir (the canonical set), off this module's
 // URL so it resolves the same from src/ (dev) and dist/ (published).
@@ -384,6 +385,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 +412,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 +443,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,7 +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 { checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { setLocalSetting } from "../lib/settings.js";
 import { parseTitle } from "../lib/orient.js";
 export function finish(cwd, args = []) {
@@ -20,6 +20,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 ' +
@@ -40,6 +41,12 @@ export function finish(cwd, args = []) {
     rmSync(seamPath(root, slug), { force: true });
     rmSync(stepPath(root, slug), { force: true });
     rmSync(spikePath(root, slug), { force: true });
+    // 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);
     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
@@ -81,6 +88,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

@@ -3,14 +3,15 @@
 import { fileURLToPath } from 'node:url';
 import { 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 { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
 import { settingsPath, setLocalSetting } 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');
@@ -75,7 +76,26 @@ export function start(cwd, args) {
         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/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/pre-bash-commit.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+# pre-bash-commit.sh — the git-commit ask-hook (D66). PreToolUse on Bash: when a
+# step is in flight and the model reaches for a raw `git commit`, turn that commit
+# into a permission *question*, never a wall. checkpoint owns the landing (the latch
+# lives there); this only nudges the human to route through it. ALWAYS exits 0 and
+# never `deny`s — the human decides, C5 stays intact (D66). `plumbbob checkpoint`'s
+# own internal `git commit` spawn never passes through hooks, so nothing self-trips.
+
+# The repo root is the nearest ancestor with an active session — `.plumbbob/STATE`,
+# the sentinel `start` writes and `finish` removes. Present in both the tracked and
+# the `--local` layout (the activeBuild cursor post-edit.sh probes exists only in
+# the tracked one, and this hook must guard `--local` steps too).
+find_root() {
+  d=$(pwd -P)
+  while [ -n "$d" ]; do
+    if [ -f "$d/.plumbbob/STATE" ]; then
+      printf '%s' "$d"
+      return 0
+    fi
+    [ "$d" = "/" ] && break
+    d=$(dirname "$d")
+  done
+  return 1
+}
+
+root=$(find_root) || exit 0 # no active session here: nothing to guard
+
+# The in-flight signal is STEP (cleared when the step checkpoints): inside the
+# active build's folder when the cursor names one, else the flat sidecar STEP of
+# the `--local` layout. jq if present, else the same sed fallback post-edit.sh
+# uses for its field read.
+settings="$root/.plumbbob/settings.local.json"
+slug=$(jq -r '.activeBuild // empty' "$settings" 2>/dev/null)
+[ -z "$slug" ] && slug=$(sed -n 's/.*"activeBuild"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$settings" 2>/dev/null | head -n1)
+if [ -n "$slug" ]; then
+  step_file="$root/.plumbbob/builds/$slug/STEP"
+else
+  step_file="$root/.plumbbob/STEP"
+fi
+[ -f "$step_file" ] || exit 0 # no step in flight: silent
+
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$cmd" ] && cmd=$(printf '%s' "$input" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
+[ -z "$cmd" ] && exit 0
+
+# A command *mentioning* "git commit" is prose, not a commit — a grep pattern, an
+# echoed sentence, a checkpoint --body heredoc. Best-effort strip before matching:
+# drop heredoc bodies (everything below the first `<<` line; the operator line
+# itself still counts, so `git commit -F- <<MSG` is caught) and quoted string
+# contents. A real commit that follows a heredoc body in the same command slips
+# through unasked — acceptable for an affordance that never gates.
+stripped=$(printf '%s\n' "$cmd" |
+  awk '{ print } /<</ { exit }' |
+  sed -e "s/'[^']*'//g" -e 's/"[^"]*"//g')
+
+# Match a `git … commit` invocation: `git` as a command word (start or after a
+# non-word char), then — without crossing a shell separator (`&& || ; |`) — the
+# `commit` subcommand as a whole word. This clears `git status`/`git diff`/`git log`
+# (no `commit` word) and `git log --grep=commit` (`=commit`, no space before it),
+# while still catching `git -C path commit` and `git commit -m …`.
+printf '%s' "$stripped" |
+  grep -Eq '(^|[^[:alnum:]_])git[[:space:]]+([^&|;]*[[:space:]])?commit([[:space:]]|$)' || exit 0
+
+# A step is in flight and this is a raw commit: ask (never deny — the human decides).
+# The reason is static, so a plain printf of the literal JSON needs no escaping.
+printf '%s\n' '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "plumbbob: a step is in flight — checkpoint owns the landing. Approve only if you asked for this commit."}}'
+
+exit 0