plumbbob 0.9.2 → 0.9.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.9.2",
+  "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,33 +24,270 @@ 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";
-/** One help-table row per verb, in the order the table prints. */
+/** Shared across every verb that resolves through the active-build cursor. */
+const BUILD_FLAG = {
+    name: '--build',
+    value: '<slug>',
+    gloss: 'target a specific build instead of the active cursor',
+};
+/**
+ * The full CLI spec, in the order the help table prints.
+ *
+ * One table drives three things: the top-level verb table, per-verb `--help`,
+ * and the unknown-flag refusal in `run`. Keeping it as data rather than inline
+ * writes is the deliberate exception to the write-at-the-call-site convention —
+ * a synopsis has to be readable by the validator, not just printable.
+ */
 const VERBS = [
-    { name: 'start', summary: 'scaffold .plumbbob/; open the session; record the baseline commit' },
-    { name: 'status', summary: 'print the orientation dashboard, or NO ACTIVE SESSION' },
-    { name: 'build', summary: 'build [<n>]: write the seam from step n, or the next undone step (in-flight, not a lock)' },
-    { name: 'handoff', summary: 'print the standardized build hand-off block (pause or post-checkpoint); read-only' },
-    { name: 'check', summary: 'run the heavy check and report; no state change (--bail --only a,b … narrow the checkride gate)' },
-    { name: 'checkpoint', summary: 'checkpoint [<n>]: gate on green, commit/record SHA, mark step done (executor-agnostic)' },
-    { name: 'revert', summary: 'revert [--to n]: git reset --hard to a checkpoint SHA' },
-    { name: 'park', summary: 'park "<text>": append a raw line to the park list' },
-    { name: 'spike', summary: 'spike "<slug>" | spike report "<slug>" | spike done: worktree experiment + report' },
-    { name: 'use', summary: 'use <slug>: re-point the active-build cursor and resume that build' },
-    { name: 'finish', summary: 'close-out: report + final commit (no gate), clear the control state, close the session' },
-    { name: 'init', summary: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob); --uninstall to undo' },
-    { name: 'doctor', summary: 'diagnose the plugin link + detect a legacy flat sidecar; doctor --migrate moves it into builds/ (staged, not committed)' },
-    { name: 'agent', summary: 'agent list | run <name> [--step N] [--mode before|build|after]: list or spawn a user-authored agent' },
-    { name: 'turn', summary: 'turn: UserPromptSubmit hook machinery — tick the turn ledger from stdin (not a user verb)' },
+    {
+        name: 'start',
+        description: 'scaffold .plumbbob/; open the session; record the baseline commit',
+        synopsis: ['start "<title>" [--slug <name>] [--local] [--allow-dirty]'],
+        args: [{ name: '<title>', gloss: 'what you are building (quoted)' }],
+        flags: [
+            { name: '--slug', value: '<name>', gloss: 'use this slug verbatim instead of the derived YYYY-MM-DD-<title-slug>' },
+            { name: '--local', gloss: 'opt into the old fully-untracked flat layout' },
+            { name: '--allow-dirty', gloss: 'record the current HEAD as baseline despite a dirty tree' },
+        ],
+        notes: 'Refuses (exit 1) on an empty title, a slug collision, a non-git directory, a repo with no commits, an already-active session, or a dirty tree.',
+    },
+    {
+        name: 'status',
+        description: 'print the orientation dashboard, or NO ACTIVE SESSION',
+        synopsis: ['status [--build <slug>]'],
+        flags: [BUILD_FLAG],
+        notes: 'Read-only; always exits 0. With no cursor it lists the available builds.',
+    },
+    {
+        name: 'build',
+        description: 'write the seam from step n, or the next undone step (in-flight, not a lock)',
+        synopsis: ['build [<n>] [--build <slug>]'],
+        args: [{ name: '<n>', gloss: 'step to build (default: the next undone step)' }],
+        flags: [BUILD_FLAG],
+        notes: 'Refuses (exit 1) with no session, a non-numeric or < 1 step, or a seam it cannot parse.',
+    },
+    {
+        name: 'handoff',
+        description: 'print the standardized build hand-off block (pause or post-checkpoint); read-only',
+        synopsis: ['handoff [<n>] [--build <slug>]'],
+        args: [{ name: '<n>', gloss: 'step to report on (default: the in-flight step, else the last checkpointed one)' }],
+        flags: [BUILD_FLAG],
+        notes: 'Read-only; refuses (exit 1) only with no session.',
+    },
+    {
+        name: 'check',
+        description: 'run the heavy check and report; no state change',
+        synopsis: ['check [--bail] [--changed] [--all] [--only a,b] [--skip a,b] [--include a,b]'],
+        flags: [
+            { name: '--bail', gloss: 'stop at the first red slot' },
+            { name: '--changed', gloss: 'limit the run to changed files' },
+            { name: '--all', gloss: 'run every slot' },
+            { name: '--only', value: '<a,b>', gloss: 'run only these slots' },
+            { name: '--skip', value: '<a,b>', gloss: 'run every slot except these' },
+            { name: '--include', value: '<a,b>', gloss: 'add these slots to the run' },
+        ],
+        notes: 'Exits 0 green, 1 red, 2 when the gate itself broke. The flags narrow a checkride run and are warned-and-ignored on the `check` settings-override path.',
+    },
+    {
+        name: 'checkpoint',
+        description: 'gate on green, commit/record SHA, mark step done (executor-agnostic)',
+        synopsis: ['checkpoint [<n>] [-m <msg>] [--body]', 'checkpoint --plan [--body]'],
+        args: [{ name: '<n>', gloss: 'step to checkpoint (else the in-flight STEP, else the first undone step)' }],
+        flags: [
+            { name: '--plan', gloss: "commit only the build's artifact folder as chore(<scope>): plan" },
+            { name: '-m', value: '<msg>', gloss: 'override the CLI-owned Conventional subject' },
+            { name: '--body', gloss: 'read the commit body from stdin (heredoc)' },
+        ],
+        notes: 'Refuses (exit 1) with no session, no resolvable step, or a red check.',
+    },
+    {
+        name: 'revert',
+        description: 'git reset --hard to a checkpoint SHA',
+        synopsis: ['revert [--to <n>] [--build <slug>]'],
+        flags: [
+            { name: '--to', value: '<n>', gloss: "revert to step n's checkpoint (default: the last, else the baseline)" },
+            BUILD_FLAG,
+        ],
+        notes: 'Refuses (exit 1) with no session, an invalid --to, or a step with no recorded checkpoint.',
+    },
+    {
+        name: 'park',
+        description: 'append a raw line to the park list',
+        synopsis: ['park "<text>"'],
+        args: [{ name: '<text>', gloss: 'the note to park (free text; quote it)' }],
+        tolerateUnknownFlags: true,
+        notes: 'Refuses (exit 1) with no session, empty text, or no `## Park list` section.',
+    },
+    {
+        name: 'spike',
+        description: 'worktree experiment + report for a genuine fork',
+        synopsis: ['spike "<slug>" [opt…] [--build <slug>]', 'spike report "<slug>"', 'spike done'],
+        args: [
+            { name: '<slug>', gloss: 'name of the experiment' },
+            { name: '[opt…]', gloss: 'the options to fork (default: a and b)' },
+        ],
+        flags: [BUILD_FLAG],
+        notes: 'Refuses (exit 1) with no session, a step already in flight, an empty slug, or a worktree path that already exists.',
+    },
+    {
+        name: 'use',
+        description: 're-point the active-build cursor and resume that build',
+        synopsis: ['use <slug>'],
+        args: [{ name: '<slug>', gloss: 'the build folder under .plumbbob/builds/ to resume' }],
+        notes: 'Refuses (exit 1) with an empty slug or a slug with no build folder; warns (but allows) leaving a step in flight.',
+    },
+    {
+        name: 'finish',
+        description: 'close-out: report + final commit (no gate), clear the control state, close the session',
+        synopsis: ['finish [--body] [--build <slug>]'],
+        flags: [{ name: '--body', gloss: 'read the commit body from stdin (heredoc)' }, BUILD_FLAG],
+        notes: 'Refuses (exit 1) only with no session. There is no refuse-without-report gate.',
+    },
+    {
+        name: 'init',
+        description: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob)',
+        synopsis: ['init [--uninstall] [--force]'],
+        flags: [
+            { name: '--uninstall', gloss: 'drop the link' },
+            { name: '--force', gloss: 'override the marketplace double-install guard' },
+        ],
+        notes: 'Idempotent and global-only; it never writes settings.json. Restart Claude Code (or /reload-plugins) to activate.',
+    },
+    {
+        name: 'doctor',
+        description: 'diagnose the plugin link + check gate; detect a legacy flat sidecar',
+        synopsis: ['doctor [--migrate]'],
+        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',
+        synopsis: [
+            'agent list',
+            'agent run <name> [--step N] [--mode before|build|after] [--agent <path>] [--build <slug>]',
+            'agent run --mode before|build|after [--step N]',
+        ],
+        args: [
+            { name: 'list', gloss: 'print every resolvable agent — name, origin tier, slots, description' },
+            { name: 'run', gloss: 'spawn an agent through the doorway; no code path advances the loop' },
+        ],
+        flags: [
+            { name: '--step', value: '<n>', gloss: 'pick the step (else the in-flight STEP)' },
+            { name: '--mode', value: '<slot>', gloss: 'the slot to run in: before, build, or after' },
+            { name: '--agent', value: '<path>', gloss: 'point at an explicit agent directory (top of the ladder)' },
+            BUILD_FLAG,
+        ],
+        notes: 'Exits 0 on a clean run, 1 on a failed one. See docs/agents.md for the author contract.',
+    },
+    {
+        name: 'turn',
+        description: 'UserPromptSubmit hook machinery — tick the turn ledger from stdin (not a user verb)',
+        synopsis: ['turn'],
+        tolerateUnknownFlags: true,
+        notes: 'Reads the hook payload from stdin and always exits 0 — a broken hook must never wedge a prompt.',
+    },
 ];
 /**
  * Render the verb table for `plumbbob help`.
  */
 export function formatHelp() {
     const width = Math.max(...VERBS.map((v) => v.name.length));
-    const rows = VERBS.map((v) => `  ${v.name.padEnd(width)}  ${v.summary}`);
-    return ['plumbbob — attention-first build process', '', 'Usage: plumbbob <verb> [args]', '', 'Verbs:', ...rows, ''].join('\n');
+    const rows = VERBS.map((v) => `  ${v.name.padEnd(width)}  ${v.description}`);
+    return [
+        'plumbbob — attention-first build process',
+        '',
+        'Usage: plumbbob <verb> [args]',
+        '',
+        'Verbs:',
+        ...rows,
+        '',
+        "Run 'plumbbob <verb> --help' for a verb's arguments and flags.",
+        '',
+    ].join('\n');
+}
+/**
+ * Render the synopsis, argument, and flag block for `plumbbob <verb> --help`,
+ * or null when the name is not a verb.
+ *
+ * Arguments and flags share one aligned column so the reader scans a single
+ * list; a flag that takes a value prints as `--only <a,b>` so the spelling in
+ * the help is the spelling you type.
+ */
+export function formatVerbHelp(name) {
+    const spec = verbSpec(name);
+    if (spec === null)
+        return null;
+    const entries = [
+        ...(spec.args ?? []).map((a) => ({ label: a.name, gloss: a.gloss })),
+        ...(spec.flags ?? []).map((f) => ({
+            label: f.value === undefined ? f.name : `${f.name} ${f.value}`,
+            gloss: f.gloss,
+        })),
+    ];
+    const width = Math.max(0, ...entries.map((e) => e.label.length));
+    const rows = entries.map((e) => `  ${e.label.padEnd(width)}  ${e.gloss}`);
+    return [
+        ...spec.synopsis.map((s) => `plumbbob ${s}`),
+        '',
+        spec.description,
+        ...(rows.length > 0 ? ['', ...rows] : []),
+        ...(spec.notes === undefined ? [] : ['', spec.notes]),
+        '',
+        `See: docs/cli-reference.md#${spec.name}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Look up a verb's spec by name, or null when the name is not a verb.
+ */
+export function verbSpec(name) {
+    return VERBS.find((v) => v.name === name) ?? null;
+}
+/**
+ * Every verb name, in table order — the contract tests iterate this.
+ */
+export function verbNames() {
+    return VERBS.map((v) => v.name);
+}
+/**
+ * Walk a verb's argv against its spec: did it ask for help, and what did it
+ * spell wrong?
+ *
+ * Value-consuming flags swallow their next token, so a value that happens to
+ * look like a flag (`checkpoint -m "--help"`) is read as the value it is. Bare
+ * `--help`/`-h` are recognized for every verb without being declared.
+ */
+function scanFlags(spec, args) {
+    const known = new Map((spec.flags ?? []).map((f) => [f.name, f]));
+    const unknown = [];
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const flag = known.get(arg);
+        if (flag !== undefined) {
+            if (flag.value !== undefined)
+                i++;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+        }
+        else if (arg.startsWith('-') && arg.length > 1) {
+            unknown.push(arg);
+        }
+    }
+    return { help, unknown };
 }
 /**
  * The package version, or 'unknown'.
@@ -104,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':
@@ -116,23 +355,58 @@ async function dispatch(verb, cwd, rest) {
 /**
  * The CLI entrypoint minus the exit: parse argv, dispatch, return the exit code.
  *
- * `help` and `version` short-circuit before dispatch; any thrown error becomes
- * a one-line stderr report and exit 1, so the bin entry only ever exits with
- * the code returned here.
+ * `help` and `version` short-circuit before dispatch, as do per-verb `--help`
+ * and the unknown-flag refusal. Screening flags *here* rather than in each verb
+ * is what makes it safe by construction: a mutating verb can no longer be
+ * reached by an argv it does not understand, which is how `checkpoint --help`
+ * 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') {
-        process.stdout.write(`${formatHelp()}\n`);
+        // `plumbbob help <verb>` is the same page as `plumbbob <verb> --help` —
+        // both spellings get typed, so both work.
+        const topic = rest.find((a) => !a.startsWith('-'));
+        if (topic === undefined) {
+            process.stdout.write(`${formatHelp()}\n`);
+            return 0;
+        }
+        const help = formatVerbHelp(topic);
+        if (help === null) {
+            process.stderr.write(`plumbbob: unknown verb '${topic}'. Run 'plumbbob help' for the verb table.\n`);
+            return 1;
+        }
+        process.stdout.write(`${help}\n`);
         return 0;
     }
     if (verb === 'version' || verb === '--version' || verb === '-v') {
         process.stdout.write(`plumbbob ${readVersion()}\n`);
         return 0;
     }
+    const spec = verbSpec(verb);
+    if (spec !== null) {
+        const { help, unknown } = scanFlags(spec, rest);
+        if (help) {
+            process.stdout.write(`${formatVerbHelp(verb)}\n`);
+            return 0;
+        }
+        if (unknown.length > 0 && spec.tolerateUnknownFlags !== true) {
+            process.stderr.write(`plumbbob: ${verb}: unknown flag '${unknown[0]}'. Run 'plumbbob ${verb} --help' for the flags.\n`);
+            return 1;
+        }
+    }
     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.