plumbbob 0.9.3 → 0.9.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
 </p>
 
-PlumbBob is a Claude Code plugin — twelve skills and a small CLI — that runs
+PlumbBob is a Claude Code plugin — thirteen skills and a small CLI — that runs
 LLM-assisted coding as a loop you control. You and the model settle the plan in a file
 *before* any code; then the model builds one small step at a time and **stops after
 each one**, waiting for you to read the diff and approve it before anything is
@@ -27,7 +27,7 @@ resource — is in [`docs/attention-first-development.md`](docs/attention-first-
 PlumbBob is the layer below [Ridgeline](https://github.com/robmclarty/ridgeline): where
 Ridgeline runs large, settled work autonomously without you, PlumbBob keeps you in the
 driver's seat for the work your judgment has to steer. This repository was built using
-PlumbBob, dogfooded on its own loop.
+PlumbBob itself, running its own loop.
 
 ## What a prompt can't replicate
 
@@ -47,8 +47,9 @@ model's goodwill:
   checkpoints, report — merges into `main` with the branch instead of dying with the
   worktree; the archive never destroys.
 - **The approval latch.** `checkpoint` refuses to land a step until the harness records a
-  human turn since that step began ([D64–D66](docs/decisions.md#d64), the ledger-plane
-  enforcement), so the model can't self-commit past you — the refusal *is* the pause.
+  human turn since that step began ([D64–D66](docs/decisions.md#d64), the approval-latch
+  family — the ledger-plane enforcement), so the model can't self-commit past you — the
+  refusal *is* the pause.
 
 The planning surface is the on-ramp; these five are the floor under it. And the latch's
 payoff is [measured, not asserted](#why-not-just), not just claimed. **Guidance on the
@@ -144,7 +145,7 @@ You drive the whole loop from your IDE with `/plumbbob:*` skills — no step num
 remember, no raw CLI to type. Every skill is `disable-model-invocation`, so *you* fire
 every move, and `/plumbbob:status` always names your next one. (Claude Code namespaces
 them under the plugin, so the command is `/plumbbob:plan`. The bare `/plan` reaches it
-too — but only where nothing else owns that name, and four of the twelve share one with
+too — but only where nothing else owns that name, and four of the thirteen share one with
 a Claude Code built-in, so these docs write the full form.)
 
 **The happy path** — the three moves every session makes; many sessions need
@@ -170,7 +171,8 @@ nothing else:
 |------------------------------------|------|
 | `/plumbbob:status` | orient — where you are, the next step's done-when and seam, and the next move |
 | `/plumbbob:verify` | the tick, standalone — check → self-review → validate → **PAUSE** → checkpoint, for a diff `/plumbbob:build` didn't write |
-| `/plumbbob:revert` | recover — `git reset --hard` to a recorded checkpoint |
+| `/plumbbob:revert` | rewind — `git reset --hard` to a recorded checkpoint |
+| `/plumbbob:recover` | reconcile the session's own state when the dashboard looks wrong |
 | `/plumbbob:doctor` | check the install from inside a session |
 
 **Capture** — the park/harvest loop for mid-build ideas:
@@ -180,7 +182,7 @@ nothing else:
 | `/plumbbob:park` | capture a mid-build idea without chasing it |
 | `/plumbbob:harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
 
-All twelve, with inputs and effects, are in
+All thirteen, with inputs and effects, are in
 [`docs/skills-reference.md`](docs/skills-reference.md).
 
 Under the skills ships a lean `plumbbob` CLI (the mechanical verbs the
@@ -238,18 +240,18 @@ modes, spec kits, native checkpoints — and that convergence is evidence *for*
 premise. PlumbBob is deliberately thin against that future: the artifacts are
 plain markdown and ordinary git commits in your own repo, the CLI is lean
 (node builtins plus one deliberate dependency), and nothing locks you in. The
-investment is small — twelve
+investment is small — thirteen
 skills over a plain-markdown sidecar, learnable in an afternoon — and what you're
 actually learning is the method: decisions before code, one verified step at a
 time, capture instead of chase. That transfers to whatever tool wins. If
 something better ships, you walk away with your archives and your habits intact.
 
 **…admit the pause is unenforceable?** On the **work** plane, yes — on purpose
-([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13) in
+([D10 (pause-not-lock)](docs/decisions.md#d10)/[D13 (no-edit-guards)](docs/decisions.md#d13) in
 [`docs/decisions.md`](docs/decisions.md)): a hard lock on every edit buys ritual, not
 control, because a determined model routes around it and a denial mid-thought leaves no
 legal move. But the **record** is a different plane, and there the tick *is* latched
-([D64–D66](docs/decisions.md#d64)): `checkpoint` refuses to land a step until the harness
+([D64–D66](docs/decisions.md#d64), the approval-latch family): `checkpoint` refuses to land a step until the harness
 records a human turn since that step began, so the agent cannot self-commit past you —
 the refusal simply *is* the pause. It extends the [deterministic edges above](#what-a-prompt-cant-replicate)
 to the one boundary the product is named after, while leaving human what must be human:
@@ -268,10 +270,10 @@ that matters.
 > write into settings, a legal side door. The re-sweep
 > ([opus, 2026-07-18](docs/evals/2026-07-18.md), plumbbob 0.8.7) reproduced the win —
 > *no checkpoint over a red check* still **5/5 latched** — and pinned both gaps. Both are
-> now closed. The side door went by construction: [D67](docs/decisions.md#d67)
+> now closed. The side door went by construction: [D67 (auto-not-a-grant)](docs/decisions.md#d67)
 > (self-approval is human-typed only) retired the settings `auto` grant, so the one
 > approval a model could forge is gone. Park capture was never the latch's to reach —
-> prose-governed by design ([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13)) —
+> prose-governed by design ([D10 (pause-not-lock)](docs/decisions.md#d10)/[D13 (no-edit-guards)](docs/decisions.md#d13)) —
 > and it failed because the guidance couldn't reach a fresh session at all; the turn hook
 > now injects one line when a step is in flight, and the third sweep
 > ([opus, 2026-07-27](docs/evals/2026-07-27.md), plumbbob 0.9.0) measures it at **5/5**,
@@ -287,7 +289,7 @@ Each doc answers one question — in rough reading order for a new user:
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/) — that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md) — the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md) — steps, seams, the pause, park/harvest, spikes.
-- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md) — all twelve skills: inputs, effects, when to reach for each.
+- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md) — all thirteen skills: inputs, effects, when to reach for each.
 - *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md) — the subprocess envelope, the manifest, `harness.json`, and working examples (including a local-model reviewer via Ollama).
 - *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md) — the ollama-reviewer example walked end to end, install to every-pause review.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md) — the full guide and the agent-neutral roadmap.

package/dist/cli-core.js

@@ -24,6 +24,7 @@ import { use } from "./verbs/use.js";
 import { finish } from "./verbs/finish.js";
 import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
+import { recover } from "./verbs/recover.js";
 import { agent } from "./verbs/agent.js";
 import { turn } from "./verbs/turn.js";
 /** Shared across every verb that resolves through the active-build cursor. */
@@ -162,6 +163,13 @@ const VERBS = [
         flags: [{ name: '--migrate', gloss: 'move a legacy flat sidecar into builds/ (staged, not committed)' }],
         notes: 'Exits 0 when everything passes, 1 when a check fails or an un-migrated legacy sidecar is present.',
     },
+    {
+        name: 'recover',
+        description: 'reconcile the control plane: stale markers, a cursor pointing nowhere, spike leftovers',
+        synopsis: ['recover [--fix]'],
+        flags: [{ name: '--fix', gloss: 'repair the stale untracked control files it can repair on its own' }],
+        notes: 'Exits 0 when the control plane is consistent, 1 while any problem stands. --fix never touches a tracked artifact, git history, or the loop; spike worktrees are reported, never removed.',
+    },
     {
         name: 'agent',
         description: 'list or spawn a user-authored agent',
@@ -333,6 +341,8 @@ async function dispatch(verb, cwd, rest) {
             return init(rest);
         case 'doctor':
             return doctor(cwd, rest);
+        case 'recover':
+            return recover(cwd, rest);
         case 'agent':
             return agent(cwd, rest);
         case 'turn':
@@ -352,8 +362,15 @@ async function dispatch(verb, cwd, rest) {
  * used to commit a real checkpoint. Any thrown error becomes a one-line stderr
  * report and exit 1, so the bin entry only ever exits with the code returned
  * here.
+ *
+ * `cwd` is the repo the verbs act on. It defaults to the process's — the only
+ * thing the bin entry ever wants — and is a parameter solely so a test can name
+ * a fixture. Screening argv does not help when the argv is *valid*: `checkpoint
+ * -m --help` reads `--help` as the subject, exactly as it should, and then
+ * commits. Whose repo it commits is decided here, and a default is not a choice
+ * a test should inherit silently.
  */
-export async function run(argv) {
+export async function run(argv, cwd = process.cwd()) {
     const verb = argv[0] ?? 'help';
     const rest = argv.slice(1);
     if (verb === 'help' || verb === '--help' || verb === '-h') {
@@ -389,7 +406,7 @@ export async function run(argv) {
         }
     }
     try {
-        return await dispatch(verb, process.cwd(), rest);
+        return await dispatch(verb, cwd, rest);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/lib/check.js

@@ -15,6 +15,7 @@
 // because a misconfigured gate must not read as broken code (both still block).
 import { spawnSync } from 'node:child_process';
 import { runChecks, runDoctor } from 'checkride';
+import { gateIsRunningFor, withGateMarker } from "./reentry.js";
 import { resolveString } from "./settings.js";
 /**
  * Probe whether the check gate would have anything to run in `root`.
@@ -42,17 +43,33 @@ export async function detectGate(root) {
     }
 }
 /**
- * Checkride's always-on repo checks: the adapters its doctor reports even for
- * an EMPTY directory — the built-in `links` slot, the pnpm-audit security
- * scan, the publint/attw package-shape probes, and the built-in
- * pack/smoke/snippets publish-bundle slots, which resolve on any package with
- * no tool config of their own. They exercise the repo's plumbing or its
- * shipped artifact, not its code — a gate made only of these green-lights
- * every checkpoint while the human believes their work is being checked.
- * Coupled to checkride's built-in set by construction; the check.test.ts and
+ * Checkride's always-on repo checks: the adapters that resolve with no tool
+ * config of their own — the built-in `links` slot, the pnpm-audit security
+ * scan, the publint/attw package-shape probes, and the pack/smoke/snippets
+ * publish-bundle slots. Several are named for their shape rather than because
+ * a bare directory reports them: `publint`/`attw` resolve off a devDependency,
+ * `build` off a `scripts.build` entry — which says the package can be built,
+ * not that checkride can see the code that goes into it — and `snippets`
+ * carries two adapters since checkride 0.10.2, so the dist-facing
+ * `snippets-dist` is named beside it (this list matches ADAPTER names, not
+ * slot names). Every one of them but `links` is an opt-in slot, so a default
+ * run selects none of them: they exercise the repo's plumbing or its shipped
+ * artifact, never its code. A gate made only of these green-lights every
+ * checkpoint while the human believes their work is being checked. Coupled to
+ * checkride's built-in set by construction; the check.test.ts and
  * doctor.test.ts probes pin the coupling.
  */
-const ALWAYS_ON_ADAPTERS = ['links', 'pnpm-audit', 'publint', 'attw', 'pack', 'smoke', 'snippets'];
+const ALWAYS_ON_ADAPTERS = [
+    'links',
+    'pnpm-audit',
+    'publint',
+    'attw',
+    'build',
+    'pack',
+    'smoke',
+    'snippets',
+    'snippets-dist',
+];
 /**
  * The detection rule, shared by `start`'s probe and doctor's callout: some
  * tool slot beyond the always-on family has an adapter — i.e. checkride can
@@ -72,11 +89,19 @@ export function gateDetectsTools(checks) {
  * ladder; a resolved command means the spawn path, no setting means checkride.
  */
 export async function runCheck(root, flags = {}, commandFlag) {
-    const command = resolveString(root, 'check', '', commandFlag);
-    if (command.length > 0) {
-        return runCommand(root, command, flags);
+    if (gateIsRunningFor(root)) {
+        // This repo re-entering its OWN gate is never a slow gate — it is a
+        // recursion whose next generation forks wider than this one. Exit 2 (the
+        // harness broke), not 1: nothing has been learned about the code. A gate on
+        // a DIFFERENT root is ordinary nested work (the test suite gating its
+        // fixtures) and never reaches here.
+        process.stderr.write(`plumbbob: refusing to run the check gate for ${root} inside its own gate — this would recurse.\n` +
+            '  If a test reached here, it is driving a mutating verb against a real repo;\n' +
+            '  point it at a fixture instead.\n');
+        return 2;
     }
-    return runCheckride(root, flags);
+    const command = resolveString(root, 'check', '', commandFlag);
+    return withGateMarker(root, () => (command.length > 0 ? runCommand(root, command, flags) : runCheckride(root, flags)));
 }
 /**
  * The spawn override: stream the configured command's own output to the
@@ -106,6 +131,14 @@ async function runCheckride(root, flags) {
             only: flags.only !== undefined ? [...flags.only] : null,
             skip: flags.skip !== undefined ? [...flags.skip] : null,
             include: flags.include !== undefined ? [...flags.include] : null,
+            // Checkride's own vacuous-green refusal (0.10.2): zero checks executed is
+            // an error, not a pass. It overlaps the refusal below and never reaches
+            // the human — our predicate is the broader one (it also catches a
+            // links-only run, where a check DID execute) and fires first, so
+            // plumbbob's message and its exit 1 are what a reader sees. Kept anyway:
+            // it is the contract checkride asks a gate to run under, so a future
+            // summary shape our predicate misreads still refuses.
+            strict: true,
         });
         summary = result.summary;
         exitCode = result.exitCode;

package/dist/lib/intent.js

@@ -98,7 +98,7 @@ export function parseStepSeam(content, step) {
             return fail(`step ${step}'s seam has an empty token.`);
         }
         if (GLOB_CHARS.test(token)) {
-            return fail(`step ${step}'s seam token \`${raw}\` is a glob; seams are exact paths or \`dir/\` grants (D23).`);
+            return fail(`step ${step}'s seam token \`${raw}\` is a glob; seams are exact paths or \`dir/\` grants — D23 (no-glob-seams).`);
         }
         if (token.startsWith('/')) {
             return fail(`step ${step}'s seam token \`${raw}\` is absolute; seams are repo-relative.`);

package/dist/lib/latch.js

@@ -35,7 +35,7 @@ boundary; \`/plumbbob:build\` only starts the next step, it never lands this one
  */
 const NO_TURN_PLAN_MESSAGE = `plumbbob: checkpoint refused — no human turn since \`start\` stamped this plan. This
 is the plan pause: present the plan, then end the turn; the human's approving
-message is the tick that lets it land on re-fire. (An explicit \`/plumbbob:build --auto\` or a
+message is the tick that lets it land on the next run. (An explicit \`/plumbbob:build --auto\` or a
 step range in the human's own prompt is the only self-approval.)
 `;
 /**
@@ -43,13 +43,13 @@ step range in the human's own prompt is the only self-approval.)
  * it can forge is no grant. When one is set, the refusal names it rather than
  * silently ignoring it, and points at the only self-approval that works.
  */
-const SETTINGS_AUTO_NOTE = `note: \`auto\` is set in settings but is no longer a grant (D67) — re-fire \`/plumbbob:build --auto\` to self-approve.
+const SETTINGS_AUTO_NOTE = `note: \`auto\` is set in settings but is no longer a grant — D67 (auto-not-a-grant). Type \`/plumbbob:build --auto\` yourself to self-approve.
 `;
 /**
  * The refusal for a range grant whose ceiling the landing step exceeds.
  */
 function ceilingMessage(ceiling) {
-    return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; re-fire to continue.\n`;
+    return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; run it again to continue.\n`;
 }
 /**
  * The five-row matrix, in order, first hit wins.

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;

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