plumbbob 0.6.6 → 0.8.0

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

package/node_modules/checkride/CHANGELOG.md

@@ -4,6 +4,114 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-07-10
+
+### Added
+
+- **Vacuous-green signal.** `summary.json` gains a top-level `checks_run` count
+  of the checks that actually executed, so "green because everything passed" and
+  "green because nothing ran" are distinguishable by every consumer: `ok: true`
+  with `checks_run: 0` means nothing was verified. A zero-check run now prints a
+  loud warning naming why each slot sat out and how to enable it, and the new
+  `--strict` flag turns that case into exit 2 (for CI and commit-hook gates; the
+  default stays a warned exit 0 so exploring a fresh repo isn't punished).
+  `checks_run` is additive — `schema_version` is unchanged.
+- **A frozen, tested contract.** `docs/contract.md` declares the surfaces
+  consumers may rely on — the exit-code taxonomy, the `summary.json`
+  additive-only discipline, the CLI flags, the programmatic exports, and the
+  pre-1.0 exact-pin policy — each locked by a new `test/contract/` suite that
+  fails the build on drift. The summary shape ships as a published JSON Schema
+  (`schema/checkride.summary.schema.json`).
+- `DEFAULT_TIMEOUT_SECONDS` is now part of the public programmatic surface.
+- New docs: a copy-paste CI guide (`docs/ci.md`), a reliability article
+  (`docs/reliability.md`), and `CONTRIBUTING.md` with the release ritual and
+  succession path.
+
+### Changed
+
+- **Per-check timeouts are on by default** (600s; override per check or globally,
+  `0` to disable). A check that exceeds it is killed (SIGTERM → grace → SIGKILL)
+  and recorded as failed with a "timed out" note — a hung tool can no longer
+  hang the definition of done. Give long-running slots (`test`, `mutation`, …) a
+  higher cap or `0` on large repos.
+- Run artifacts (`summary.json`, the raw slot files, the digest, the baseline)
+  are written atomically (temp file then rename), so a run interrupted mid-write
+  never leaves a consumer a half-written file to parse.
+
+### Fixed
+
+- The supported Node floor is now stated consistently as `>=22.18` across the
+  docs; `docs/tools.md` and `docs/getting-started.md` previously claimed `>=24`,
+  contradicting `package.json` engines.
+
+### Internal
+
+- CI runs the full suite across macOS and Linux at the Node floor (22.18.0) and
+  current (24), and the e2e suite exercises all four package managers
+  (pnpm/npm/yarn/bun) plus an interrupted-run case. Releases now publish with npm
+  provenance, and the README wears the Stryker mutation score.
+
+## [0.2.1] - 2026-07-08
+
+### Fixed
+
+- Every `checkride init` scaffold shipped a `spell` check that failed out of the
+  box: the generated AGENTS.md contract stanza uses the word "baselined", but the
+  scaffolded `cspell.json` dictionary didn't include it, so a freshly generated
+  project's first `checkride` run exited non-zero.
+
+### Internal
+
+- Added a fast local guard (`generated-spell.test.ts`) that runs cspell against an
+  in-process `init` scaffold for each shape, catching this class of drift in
+  `pnpm check` instead of only in the slower end-to-end suite.
+
+## [0.2.0] - 2026-07-08
+
+### Added
+
+- **Baseline** — adopt checkride on an existing repo without turning it into a
+  cleanup project. `checkride baseline` records current diagnostics into a
+  committed `checkride.baseline.json`; a normal run then passes a slot as long as
+  only baselined findings remain, fails listing only genuinely new ones, and
+  *ratchets* the file smaller as findings are fixed — never larger, and never
+  pruned on a partial `--only`/`--skip`/`--changed` run. `checkride init
+  --baseline` grandfathers today's debt instead of disabling failing slots.
+  Grandfathered counts surface in `.check/summary.json` as an additive
+  `baselined` field.
+- **Package-manager-agnostic runs** — checkride detects pnpm, npm, yarn, or bun
+  (from the lockfile or the `packageManager` field) and translates each tool
+  invocation accordingly; the default pnpm behavior is byte-identical to before.
+  `doctor` reports the detected manager. The `security` audit stays pnpm-only
+  until per-manager adapters land.
+- **`checkride agent-setup`** plus an `init` Stop hook — both write an idempotent
+  Claude Code Stop hook to `.claude/settings.json` that runs the gate on the
+  *detected* package manager and blocks a stop while checks are red. `agent-setup`
+  also (re)writes the AGENTS.md contract stanza for a repo set up without a full
+  `init`. Both are opt-out with `--no-hook`.
+- **`format` slot** (opt-in) — a blessed `prettier` adapter (with `biome` as an
+  alternate) that runs before `lint` and is wired into `checkride fix`. Excluded
+  from the default run so upgrading never turns a repo red; `init` can enable it
+  for greenfield projects. The `order: "first"` custom-check hatch still works for
+  bespoke formatters.
+- **`publint` and `attw` slots** (opt-in) — library-publishing checks that make
+  "the published package is correct" part of the definition of done: `publint`
+  lints the `package.json` publishing surface, `attw` verifies types resolve
+  across module systems. Detect-gated so apps that never publish don't run them.
+- **Config presets via `extends`** — `checkride.config.json` accepts `"extends":
+  "<package-or-path>"` (string or array) to inherit a shared base; local keys win,
+  and a missing or circular extend fails with a friendly message.
+- **`--digest`** — writes a token-bounded Markdown excerpt of the failing slots to
+  `.check/digest.md`, each section pointing at the authoritative raw output, so
+  agents spend less context triaging failures on large repos. Absent on a green
+  run.
+- **Custom-check `detect` field** — a custom check can declare `detect:
+  ["<file>"]` so a shared preset skips it when the file is absent and activates it
+  when present, keeping one config safe across heterogeneous repos.
+- **Published JSON Schema** — `schema/checkride.config.schema.json` describes the
+  full config surface and ships in the package; `init` writes a version-pinned
+  `$schema` pointer into generated configs for editor validation.
+
 ## [0.1.6] - 2026-06-30
 
 ### Added
@@ -130,6 +238,9 @@ The first real release. (`0.0.0` was a name-claim placeholder.)
 - Flags: `--only`, `--skip`, `--bail`, `--json`, `--changed`, `--all`,
   `--include`.
 
+[0.3.0]: https://www.npmjs.com/package/checkride/v/0.3.0
+[0.2.1]: https://www.npmjs.com/package/checkride/v/0.2.1
+[0.2.0]: https://www.npmjs.com/package/checkride/v/0.2.0
 [0.1.6]: https://www.npmjs.com/package/checkride/v/0.1.6
 [0.1.5]: https://www.npmjs.com/package/checkride/v/0.1.5
 [0.1.4]: https://www.npmjs.com/package/checkride/v/0.1.4