plumbbob 0.9.2 → 0.9.5

package/dist/lib/reentry.js

@@ -0,0 +1,70 @@
+// The gate's re-entrancy marker: which repos have a check run in flight,
+// recorded on the environment so every process in the tree can see it.
+//
+// The failure it exists to stop is not slowness, it is unbounded recursion. A
+// repo whose `check` setting is its own full pipeline (`pnpm check`) has a gate
+// that runs its test suite; anything in that suite which gates THAT SAME REPO —
+// a test driving `checkpoint` against the process cwd — spawns a second full
+// pipeline, whose suite spawns a third. Each generation forks wider than the
+// last, and nothing in the loop is aware there is a loop. The only thing that
+// ended the first observed occurrence was checkride's 600s per-check cap
+// killing one generation from the outside.
+//
+// It is scoped BY ROOT, and that is the whole design. A flat "a gate is
+// running" flag is wrong in the one case that matters most: plumbbob's own
+// suite legitimately gates dozens of fixture repos, and when the suite itself
+// is running under this repo's gate it inherits the marker — so a flat flag
+// refuses every one of them and turns a green suite red. Recursion is a repo
+// re-entering ITS OWN gate; a different root is ordinary nested work and must
+// pass through untouched.
+//
+// The marker rides the environment rather than a module-level variable because
+// the recursion crosses process boundaries (spawned shells, checkride's tool
+// subprocesses, vitest's worker forks), and a variable in one heap is invisible
+// to all of them. Node builtins only.
+import { resolve } from 'node:path';
+/** The environment key. Namespaced so nothing else can set it by accident. */
+const MARKER = 'PLUMBBOB_GATE_ROOTS';
+/** The separator. A newline cannot appear in a path, unlike `:` on a weird one. */
+const SEP = '\n';
+/**
+ * The roots with a gate in flight, as absolute paths.
+ */
+function activeRoots(env) {
+    const raw = env[MARKER] ?? '';
+    return raw.split(SEP).filter((r) => r.length > 0);
+}
+/**
+ * True when `root` already has a check gate running in this process tree.
+ *
+ * Compared as resolved absolute paths, so the same repo reached by a relative
+ * path, a symlink-free alias, or a trailing slash still counts as itself.
+ * `env` is injectable so the guard is testable without mutating the real one.
+ */
+export function gateIsRunningFor(root, env = process.env) {
+    return activeRoots(env).includes(resolve(root));
+}
+/**
+ * Run `body` with `root` recorded as gated, restoring the prior value after.
+ *
+ * The marker is set on `process.env` itself, not on a copy handed to one child:
+ * the in-process checkride path spawns its own tool subprocesses, and they
+ * inherit the parent's environment at spawn time. `finally` restores rather
+ * than deletes, so nesting a second root inside the first cannot un-mark the
+ * first when the inner call returns.
+ */
+export async function withGateMarker(root, body) {
+    const prior = process.env[MARKER];
+    process.env[MARKER] = [...activeRoots(process.env), resolve(root)].join(SEP);
+    try {
+        return await body();
+    }
+    finally {
+        if (prior === undefined) {
+            delete process.env[MARKER];
+        }
+        else {
+            process.env[MARKER] = prior;
+        }
+    }
+}

package/dist/verbs/agent.js

@@ -103,12 +103,12 @@ async function run(cwd, args) {
 async function runOne(root, slug, step, spec) {
     const resolution = resolveAgent(root, spec.name, spec.flagPath !== undefined ? { flagPath: spec.flagPath } : {});
     if (!resolution.ok) {
-        return degrade(spec.ambient, `plumbbob: ${resolution.error}`, `plumbbob: bound agent "${spec.name}" did not resolve — ${resolution.error} Skipping (D54 — the loop works without it).`);
+        return degrade(spec.ambient, `plumbbob: ${resolution.error}`, `plumbbob: bound agent "${spec.name}" did not resolve — ${resolution.error} Skipping — D54 (bindings-degrade-soft): the loop works without it.`);
     }
     const { manifest, dir } = resolution.agent;
     const resolved = resolveMode(spec.mode, manifest);
     if (!resolved.ok) {
-        return degrade(spec.ambient, resolved.error, `plumbbob: bound agent "${spec.name}" — ${resolved.error.replace(/^plumbbob:\s*/, '')} Skipping (D54).`);
+        return degrade(spec.ambient, resolved.error, `plumbbob: bound agent "${spec.name}" — ${resolved.error.replace(/^plumbbob:\s*/, '')} Skipping — D54 (bindings-degrade-soft).`);
     }
     const mode = resolved.mode;
     let intent;
@@ -215,8 +215,9 @@ function degrade(ambient, hard, soft) {
  * agent name and the value flags.
  *
  * A value flag missing its value, or `--step` given a non-number, is a loud
- * error (returned as a string) rather than a silent default. Unknown `--flags`
- * are ignored — the point is the named agent.
+ * error (returned as a string) rather than a silent default. An undeclared
+ * `--flag` never arrives here — `run` screens argv against the verb spec in
+ * cli-core.ts and refuses before dispatch.
  */
 function parseRunArgs(args) {
     const positionals = [];

package/dist/verbs/check.js

@@ -32,8 +32,12 @@ export async function check(cwd, args = []) {
 /**
  * Map argv onto checkride's flags: bare booleans plus comma-separated slot lists.
  *
- * Unknown args are ignored rather than refused — running the gate is the point,
- * not flag hygiene.
+ * Only the declared flags are read here; an undeclared one never reaches this
+ * function, because `run` screens argv against the verb spec in cli-core.ts and
+ * refuses before dispatch. This used to tolerate unknown args on the grounds
+ * that running the gate mattered more than flag hygiene — but the same tolerance
+ * on the mutating verbs let `checkpoint --help` commit, so the screen is now
+ * central and uniform.
  */
 function parseFlags(args) {
     return {

package/dist/verbs/doctor.js

@@ -423,7 +423,7 @@ function agentReport(cwd) {
     const listings = listAgents(root);
     if (listings.length === 0)
         return { lines: [], failed: 0 };
-    const lines = ['', 'plumbbob doctor — agents (D48)'];
+    const lines = ['', 'plumbbob doctor — agents — D48 (doctor-validates-agents)'];
     let failed = 0;
     for (const listing of listings) {
         const problem = agentProblem(listing, root);
@@ -451,7 +451,7 @@ async function gateReport(cwd, env) {
     const root = findRepoRoot(cwd);
     if (root === null)
         return { lines: [], failed: 0 };
-    const lines = ['', 'plumbbob doctor — check gate (D32)'];
+    const lines = ['', 'plumbbob doctor — check gate — D32 (checkride-gate)'];
     const command = resolveString(root, 'check', '');
     if (command.length > 0) {
         lines.push(`  ✓ gate: '${command}' — the "check" setting overrides checkride`);
@@ -523,13 +523,13 @@ function latchReport(cwd) {
     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})`;
-    const lines = ['', 'plumbbob doctor — approval latch (D64)', line];
+    const lines = ['', 'plumbbob doctor — approval latch — D64 (approval-latch)', line];
     // The latch ignores a settings `auto`: a model can write that file, and a grant
     // the model can forge is no grant — self-approval comes only from the human's
     // typed `/build --auto`. Surface a set value so a human relying on it isn't
     // silently changed — informational, never a problem.
     if (resolveBoolean(root, 'auto', false)) {
-        lines.push('  ○ auto: set in settings but not a grant since D67 — self-approve per run with `/plumbbob:build --auto`');
+        lines.push('  ○ auto: set in settings but not a grant since D67 (auto-not-a-grant) — self-approve per run with `/plumbbob:build --auto`');
     }
     return { lines, failed: 0 };
 }

package/dist/verbs/finish.js

@@ -35,7 +35,7 @@ export function finish(cwd, args = []) {
     }
     else {
         process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
-            '(/plumbbob:finish normally writes the report first). No gate (D9).\n');
+            '(/plumbbob:finish normally writes the report first). No gate — D9 (finish-no-gate).\n');
     }
     // The final commit: stage the report just written plus the build folder's tail —
     // a step's commit sweeps its own bookkeeping along with the work, so the last

package/dist/verbs/recover.js

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

package/dist/verbs/revert.js

@@ -95,8 +95,8 @@ export function revert(cwd, args) {
  *
  * The match is by name alone, and since the skills dropped their `pb-` prefix
  * those names are ordinary words — a user's own `.claude/skills/plan/` is
- * carried across the reset too. That errs toward keeping work (C4), so it is
- * the safe direction to be wrong in. Only paths that currently exist are returned.
+ * carried across the reset too. That errs toward keeping work — never destroy —
+ * so it is the safe direction to be wrong in. Only paths that currently exist are returned.
  */
 function plumbbobOwnedPaths(root) {
     const paths = [sidecarDir(root)];

package/dist/verbs/spike.js

@@ -201,8 +201,12 @@ function spikeReportsMissingVerdict(root, buildSlug) {
  * Worktree paths whose checked-out branch is under spike/ — parsed from the
  * porcelain output (blank-line-separated `worktree <path>` / `branch <ref>`
  * blocks).
+ *
+ * Exported for `recover`, which reports the ones this verb can no longer reach
+ * (a spike interrupted before `spike done` strands them). Sharing the reader
+ * keeps one definition of what counts as a spike worktree.
  */
-function spikeWorktrees(root) {
+export function spikeWorktrees(root) {
     const out = git(root, ['worktree', 'list', '--porcelain']);
     const paths = [];
     let current = null;
@@ -218,8 +222,10 @@ function spikeWorktrees(root) {
 }
 /**
  * List the local `spike/<slug>` branch names.
+ *
+ * Exported alongside spikeWorktrees, for the same reason.
  */
-function spikeBranches(root) {
+export function spikeBranches(root) {
     const out = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/spike/']);
     return out.length === 0 ? [] : out.split('\n').filter((b) => b.length > 0);
 }

package/hooks/post-edit.sh

@@ -1,12 +1,12 @@
 #!/bin/sh
-# post-edit.sh — light feedback (D25). PostToolUse, non-blocking, ALWAYS exits 0.
+# post-edit.sh — light feedback — D25 (light-then-heavy). PostToolUse, non-blocking, ALWAYS exits 0.
 # Runs file-scoped oxlint + ast-grep on the changed file and injects any failures
-# into the model's context via additionalContext (verified API, D25). No-ops when
+# into the model's context via additionalContext (verified API — D25 (light-then-heavy)). No-ops when
 # 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.
+# — D25 (light-then-heavy): it has no true single-file mode and would tax every keystroke.
 
 # 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
+# per-worktree signal that a tracked build is live here — D28 (state-cursor). 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

package/hooks/pre-bash-commit.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
-# pre-bash-commit.sh — the git-commit ask-hook (D66). PreToolUse on Bash: when a
+# pre-bash-commit.sh — the git-commit ask-hook — D66 (oob-commits-surfaced). 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
+# never `deny`s — the human decides, C5 (additive-git) stays intact — D66 (oob-commits-surfaced). `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`,
@@ -27,7 +27,7 @@ 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 STATE names one, else the flat sidecar STEP of the
-# `--local` layout. STATE's content IS the cursor (D28) — read the first line, trim
+# `--local` layout. STATE's content IS the cursor — D28 (state-cursor) — read the first line, trim
 # whitespace, and treat the legacy `active` sentinel (pre-STATE-cursor) as no cursor.
 slug=$(head -n1 "$root/.plumbbob/STATE" 2>/dev/null | tr -d '[:space:]')
 [ "$slug" = "active" ] && slug=""

package/node_modules/checkride/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "checkride",
+  "displayName": "checkride",
+  "version": "0.10.2",
+  "description": "Bounded, contract-aware readers for what checkride already writes: triage a red gate and read quality signal without loading megabytes of raw artifacts.",
+  "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
+  "homepage": "https://robmclarty.github.io/checkride/",
+  "repository": "https://github.com/robmclarty/checkride",
+  "license": "Apache-2.0",
+  "keywords": ["claude-code", "claude", "agent", "checkride", "ci", "triage"]
+}