plumbbob 0.4.14 → 0.5.3

package/.claude-plugin/plugin.json

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

package/README.md

@@ -4,47 +4,65 @@
   <img src="hero.jpg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
 </p>
 
-A [guidance-first build process](docs/attention-first-development.md) for working
-*with* an LLM instead of being dragged behind one. It's the layer below [Ridgeline](https://github.com/robmclarty/ridgeline):
-where Ridgeline runs autonomously without you, PlumbBob keeps you in the driver's seat
-for the small-to-medium work that doesn't justify a full autonomous build — a feature,
-a bug, a refactor — while staying deliberate rather than vibing. You decide on a surface
-outside the chat; PlumbBob orients you, runs each step's labor, and then **stops and
-waits for you to advance** — the human is the clock, not a lock.
+PlumbBob is a Claude Code plugin — twelve `/pb-*` 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
+committed. It's built for the small-to-medium work that fills most days — a feature, a
+bug, a refactor — where a fully autonomous build is overkill but freestyle prompting
+leaves you dragged behind the model, reacting instead of deciding.
 
 > Establish *plumb* before you build. The LLM is a hand, not a head.
 
-The name is the method. A plumb bob is a weight on a string — gravity pulls it into
-a perfectly straight vertical line, the builder's oldest reference for *true*: the
-fixed mark you hold the work against so it never drifts out of square. PlumbBob hangs
-your **intent** as that line and keeps every step aligned to it, so the build stays
-plumb with what you decided instead of wandering off behind the model.
-
 Its one law is **vibe to execute, never vibe to decide**: the human owns every
 decision, the LLM owns the labor, and the boundary between them is a **pause you
-advance**, not a wall that refuses you. The *why* behind that — attention as the
-scarce resource — is the subject of the guidance-first article above; the *how* of
-each method is in [`docs/techniques.md`](docs/techniques.md). This repository was
-built using PlumbBob, dogfooded on its own build under its own loop.
+advance**, not a wall that refuses you. The *why* behind that — attention as the scarce
+resource — is in [`docs/attention-first-development.md`](docs/attention-first-development.md).
+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.
+
+## The loop in one picture
+
+<p align="center">
+  <img src="demo.svg" alt="An animated terminal session: /pb-plan writes the plan, /pb-build implements step 1 and stops at the PAUSE, the human approves, the step is checkpointed" width="760">
+</p>
+
+Everything the model must stay true to lives in one file, the build's `intent.md`
+(under `.plumbbob/builds/<slug>/`), written before any code: the **Frame** (the problem, what done looks like, what you're
+explicitly *not* doing), the **Decisions** and **Constraints** (the settled calls, each
+with its *because*), and the **Steps** — a numbered list where every step carries a
+**done-when** (a checkable finish line, ideally a test) and a **seam** (the files it's
+expected to touch).
+
+```text
+/pb-plan       decide everything on paper — frame, decisions, all steps    (once)
+  per step:
+    /pb-build      implement the next step → run checks → self-review → PAUSE
+    (approve)      → the step is committed as a checkpoint; fire /pb-build again
+/pb-finish     report what shipped and why, final commit, clear            (once)
+```
+
+Nothing is locked and nothing refuses you — the loop does a step's labor, pulls up to
+the line, and waits for you to advance it. **You are the clock.**
 
 ## Install
 
-PlumbBob installs **once, globally** — like `gh` or your dotfiles — in one of two
-co-equal, mutually-exclusive ways (both register a Claude Code plugin named
-`plumbbob`).
+PlumbBob installs **once, globally** — like `gh` or your dotfiles. There are two ways;
+pick one (both register a Claude Code plugin named `plumbbob`, so running both
+collides).
 
-**Marketplace plugin** — Claude Code installs the published `plumbbob` package for
-you (skills, hook, and the CLI on PATH), so you run no `npm i -g` and no `init`. It's
-published in the [`agent-tools`](https://github.com/robmclarty/agent-tools)
-marketplace — add that once, then install:
+**Marketplace plugin** — Claude Code installs the published `plumbbob` package for you
+(skills, hook, and the CLI on PATH), so you run no `npm i -g` and no `init`:
 
 ```text
 /plugin marketplace add robmclarty/agent-tools
 /plugin install plumbbob@robmclarty
 ```
 
-**npm global + `init`** — installs the CLI, then links the skills and hook into
-Claude Code in place:
+**npm global + `init`** — installs the CLI, then links the skills and hook into Claude
+Code in place:
 
 ```sh
 npm i -g plumbbob      # the CLI (also a `pb` shorthand)
@@ -56,66 +74,143 @@ Restart Claude Code (or `/reload-plugins`) to activate, then run `plumbbob docto
 per-project sessions, the agent-neutral roadmap — is in
 [`docs/install.md`](docs/install.md).
 
-## Features
+## Your first session
+
+In Claude Code, inside any git repo with a clean tree:
+
+1. **Plan.** Fire `/pb-plan` and give it whatever you have — nothing (it interviews
+   you), a rough line (`/pb-plan rate-limit POST /login, 5/min/IP, return 429`), or a
+   path to a spec file. Together you fill `.plumbbob/intent.md`. No code is written
+   yet.
+2. **Build.** Fire `/pb-build`. It implements the next undone step, runs the
+   heavy check gate, reviews its own diff against the plan, and stops:
+
+   ```text
+   PAUSE — read the diff as an editor. Approve to checkpoint, or send fixes.
+   ```
+
+   (The check gate is [checkride](https://www.npmjs.com/package/checkride) — one
+   run across the tools your repo already configures: types, lint, tests, dead
+   code, docs. To gate through your own command instead, set the `"check"` key in
+   `.plumbbob/settings.json`, e.g. `"check": "npm test"`.)
+3. **Approve** — or send fixes. On your OK it commits the step as a checkpoint, marks
+   it done, and returns to the boundary. Fire `/pb-build` again for the next step —
+   re-firing it *is* the clock tick. Whenever you lose the thread, `/pb-status` shows
+   where you are and names the next move.
+4. **Finish.** When the last step is done, `/pb-finish` writes a report of what shipped
+   and why into the build's tracked folder, makes the final commit, and clears the slate
+   for the next goal. The folder rides the branch into the PR — the build's record merges
+   into `main` instead of dying with the worktree.
+
+A mid-build "ooh, what if…" never derails the step: `/pb-park` captures it to a list
+in one line, and `/pb-harvest` triages the list between steps. One goal walked end to
+end, with the real output at every stage, is in
+[`docs/happy-path.md`](docs/happy-path.md).
+
+## The skills
 
 You drive the whole loop from your IDE with `/plumbbob:*` skills — no step numbers to
-remember, no raw CLI to type. Each is `disable-model-invocation`, so *you* fire every
-move, and `/pb-status` always names your next one. (For readability these docs write
-the short form: `/pb-plan` means `/plumbbob:pb-plan`.)
+remember, no raw CLI to type. Every skill is `disable-model-invocation`, so *you* fire
+every move, and `/pb-status` always names your next one. (Claude Code namespaces them
+under the plugin — the real command is `/plumbbob:pb-plan`; for readability these docs
+write the short form `/pb-plan`.)
 
 | Skill | Does |
 |-------|------|
-| `/pb-plan` | plan the whole goal — scaffold the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/pb-plan` | plan the whole goal — open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
 | `/pb-step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
 | `/pb-build` | *(optional)* implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done |
 | `/pb-verify` | the tick — check → self-review → validate → **PAUSE** → checkpoint |
-| `/pb-park` | capture an idea without chasing it |
-| `/pb-status` | orient — where you are, the next step's done-when + seam, and the next move |
-| `/pb-harvest` | triage parked ideas at a boundary (blocker / tangent / pivot) |
-| `/pb-wrap` | wrap up — write the report, archive safely, clear for a fresh goal |
+| `/pb-park` | capture a mid-build idea without chasing it |
+| `/pb-status` | orient — where you are, the next step's done-when and seam, and the next move |
+| `/pb-harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
+| `/pb-finish` | finish up — write the report, make the final commit, clear for a fresh goal |
 
 Three power moves round it out — `/pb-revert` (recover to a checkpoint), `/pb-spike`
-(throwaway worktree experiment), and `/pb-refine` (attack the frame for holes or
-repair a drifted plan) — plus `/pb-doctor` to check your install.
+(throwaway worktree experiment for a fork the plan can't settle), and `/pb-refine`
+(attack the frame for holes or repair a drifted plan) — plus `/pb-doctor` to check
+your install. All twelve, with inputs and effects, are in
+[`docs/skills-reference.md`](docs/skills-reference.md).
 
-Under the skills ships a zero-dependency `plumbbob` CLI (the mechanical verbs the
+Under the skills ships a lean `plumbbob` CLI (the mechanical verbs the
 skills shell out to), one session-gated post-edit hook (non-blocking lint feedback in
-flow), and a `.plumbbob/` sidecar of flat files (`intent.md`, `build-log.md`,
-checkpoints, archive). `/pb-build` is just one executor — implement a step by hand or
-in any other harness and run `/pb-verify` instead; it reads the *diff, not the author*.
-
-## Getting started
-
-The happy path is **plan the whole thing up front, then drive `/pb-build` until
-done** — approving each step at its verify pause:
-
-```text
-/pb-plan                      author the whole plan (incl. all steps)   (once)
-  └ per step:
-       /pb-status             review the next step (done-when + seam)
-       /pb-step   (optional)  sharpen/revise it first if needed
-       /pb-build  (or DIY)    implement it → verify → PAUSE → checkpoint
-       /pb-park               capture strays mid-build
-       /pb-harvest            triage them at a boundary
-  /pb-wrap                    report + archive + clear                  (once)
-```
-
-Each `/pb-build` builds the next undone step and stops at the pause for your
-approval — re-firing it is itself the clock tick. (`/pb-build --auto` is the opt-in
-that lets the agent self-approve and chain to done, halting on a red check or any
-mismatch.) For one goal walked end to end — planning, building each step, wrapping
-up, and starting the next — see [`docs/happy-path.md`](docs/happy-path.md).
+flow), and a `.plumbbob/` sidecar you can open and edit by hand at any time — a tracked
+`builds/<slug>/` folder per build (`intent.md`, `build-log.md`, `checkpoints`, `report.md`)
+that rides the branch into the PR, plus an untracked control plane (`settings.local.json`,
+the session sentinel, the in-flight markers).
+
+**`/pb-build` is optional.** It's one executor, not the loop. Implement a step by
+hand — or vibe it in another session, or in another harness entirely — and run
+`/pb-verify` instead: same checks, same pause, same checkpoint. It reads the *diff,
+not the author*.
+
+## Why "PlumbBob"
+
+The name is the method. A plumb bob is a weight on a string — gravity pulls it into a
+perfectly straight vertical line, the builder's oldest reference for *true*: the fixed
+mark you hold the work against so it never drifts out of square. PlumbBob hangs your
+**intent** as that line and keeps every step aligned to it, so the build stays plumb
+with what you decided instead of wandering off behind the model.
+
+## Why not just…?
+
+The questions a skeptic should ask, answered straight.
+
+**…use plan mode?** Plan mode is the same instinct — decide before executing —
+scoped to one session. The plan lives in the chat, so it fades with the context
+window, and the approval gates the *start* of the work, not each increment of it.
+PlumbBob puts the plan in a file in your repo that survives compaction, restarts,
+and next week; moves the approval to **every step** — each checked, reviewed
+against the plan, and committed as its own checkpoint, so a wrong turn costs one
+step, not the afternoon; and records the *whys* alongside the decisions, so the
+archive can still answer "what did we decide, and why" long after the session is
+gone. The two compose fine: plan mode — or anything else — can produce a step's
+diff, and `/pb-verify` reads it like any other.
+
+**…use git and a TODO file?** That's the honest skeleton, and if your discipline
+holds by willpower alone, it may be all you need. What the CLI adds is the
+mechanical half of the discipline, so willpower is spent only at the pause: a
+recorded baseline, one SHA per verified step, a revert that returns exactly to
+those SHAs while preserving your notes, an archive that never destroys, and a
+dashboard re-injected into every skill so the model re-orients on each move
+without you re-explaining the state.
+
+**…wait for a vendor to ship this natively?** They're converging on it — plan
+modes, spec kits, native checkpoints — and that convergence is evidence *for* the
+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
+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?** It is — on purpose (D10/D13 in
+[`docs/decisions.md`](docs/decisions.md)). A hard lock buys ritual, not control:
+a determined model routes around it. So PlumbBob enforces deterministically where
+it can — `checkpoint` refuses on a red check, `revert` restores only recorded
+SHAs — and leaves human what must be human: you, reading the diff at the pause.
+When guidance does get blown through, the checkpoint record makes recovery one
+command. Cheap recovery, not prevention, is the control that actually matters.
 
 ## Documentation
 
-- [`docs/install.md`](docs/install.md) — the full install guide and the agent-neutral roadmap.
-- [`docs/techniques.md`](docs/techniques.md) — the methods behind the loop, each on its own.
-- [`docs/happy-path.md`](docs/happy-path.md) — one goal walked end to end.
-- [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
-- [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.
-- [`docs/decisions.md`](docs/decisions.md) — the `D#` / `C#` design-decision key.
-- [`docs/attention-first-development.md`](docs/attention-first-development.md) — the philosophy: attention as the scarce resource.
-- [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventions, and how to submit changes.
+Each doc answers one question — in rough reading order for a new user:
+
+- *What does a session actually look like?* → [`docs/happy-path.md`](docs/happy-path.md) — one goal walked end to end; read this first.
+- *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 `/pb-*` skills: inputs, effects, when to reach for each.
+- *How do I install it, exactly?* → [`docs/install.md`](docs/install.md) — the full guide and the agent-neutral roadmap.
+- *What does the CLI underneath do?* → [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
+- *Something's broken.* → [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.
+- *Why is it built this way?* → [`docs/decisions.md`](docs/decisions.md) — the `D#` / `C#` design-decision key the source cites.
+- *How does it hang together inside?* → [`docs/architecture.md`](docs/architecture.md) — the layers and planes, for contributors (in progress).
+- *Why does this exist at all?* → [`docs/attention-first-development.md`](docs/attention-first-development.md) — the philosophy: attention as the scarce resource.
+- *What does it run on my machine?* → [`SECURITY.md`](SECURITY.md) — execution surface and how to report a vulnerability.
+- *How do I contribute?* → [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventions, and how to submit changes.
 
 ## License
 

package/dist/cli-core.js

@@ -1,7 +1,8 @@
 // plumbbob CLI core — argv dispatch and the help table, separated from the bin
 // entry (cli.ts) so the routing/help logic is unit-testable in-process without
-// the top-level process.exit. Zero runtime deps, node: builtins only (D1/C2).
-// Functional/procedural: no classes, no `this`, no default export (C1).
+// the top-level process.exit. Node builtins plus the deliberate few (D1/C2 —
+// currently checkride alone, via check.ts). Functional/procedural: no classes,
+// no `this`, no default export (C1).
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { start } from "./verbs/start.js";
@@ -12,21 +13,23 @@ import { check } from "./verbs/check.js";
 import { checkpoint } from "./verbs/checkpoint.js";
 import { revert } from "./verbs/revert.js";
 import { spike } from "./verbs/spike.js";
-import { wrap } from "./verbs/wrap.js";
+import { use } from "./verbs/use.js";
+import { finish } from "./verbs/finish.js";
 import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 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 (in-flight, not a lock)' },
-    { name: 'check', summary: 'run the heavy check and report; no state change' },
+    { 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 done: throwaway worktree experiment' },
-    { name: 'wrap', summary: 'close-out: archive intent+log+report (no gate), clear the sidecar, close the session' },
+    { 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 (manifest, skills, hook) and print the fix for anything broken' },
+    { name: 'doctor', summary: 'diagnose the plugin link + detect a legacy flat sidecar; doctor --migrate moves it into builds/ (staged, not committed)' },
 ];
 // PlumbBob (D1/D10/D13): the deciding/executing boundary is a pause, not a lock,
 // so there is nothing to defend — every verb runs the same whether a human or the
@@ -51,36 +54,40 @@ export function readVersion() {
         return 'unknown';
     }
 }
-function dispatch(verb, cwd, rest) {
+// Async because the checkride gate (D32) is: `check` and `checkpoint` await it;
+// every other verb returns synchronously through the same Promise-typed seam.
+async function dispatch(verb, cwd, rest) {
     switch (verb) {
         case 'start':
             return start(cwd, rest);
         case 'status':
-            return status(cwd);
+            return status(cwd, rest);
         case 'park':
             return park(cwd, rest);
         case 'build':
             return build(cwd, rest);
         case 'check':
-            return check(cwd);
+            return check(cwd, rest);
         case 'checkpoint':
             return checkpoint(cwd, rest);
         case 'revert':
             return revert(cwd, rest);
         case 'spike':
             return spike(cwd, rest);
-        case 'wrap':
-            return wrap(cwd);
+        case 'use':
+            return use(cwd, rest);
+        case 'finish':
+            return finish(cwd, rest);
         case 'init':
             return init(rest);
         case 'doctor':
-            return doctor();
+            return doctor(cwd, rest);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;
     }
 }
-export function run(argv) {
+export async function run(argv) {
     const verb = argv[0] ?? 'help';
     const rest = argv.slice(1);
     if (verb === 'help' || verb === '--help' || verb === '-h') {
@@ -92,7 +99,7 @@ export function run(argv) {
         return 0;
     }
     try {
-        return dispatch(verb, process.cwd(), rest);
+        return await dispatch(verb, process.cwd(), rest);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/cli.js

@@ -5,4 +5,4 @@
 // Keeping the single process.exit here is what lets cli-core.ts be imported by a
 // test without tearing down the worker.
 import { run } from "./cli-core.js";
-process.exit(run(process.argv.slice(2)));
+process.exit(await run(process.argv.slice(2)));

package/dist/lib/buildlog.js

@@ -1,6 +1,6 @@
 // Mutations to the active build-log.md — the human-facing ledger. `park` appends to
 // its Park list; `checkpoint` appends to its Log so the build's history accrues
-// line-by-line *as it happens* rather than being reconstructed at wrap (D-history).
+// line-by-line *as it happens* rather than being reconstructed at finish (D-history).
 // Pure string transforms (no fs, no classes — C1/C2); callers own the IO so these
 // stay trivially testable.
 // Append `line` after the last non-blank line of the `## <heading>` section — i.e.
@@ -27,7 +27,7 @@ export function appendToSection(content, heading, line) {
 }
 // The Log line `checkpoint` writes for a landed step: dated, names the step (its
 // title when intent.md still carries it), and carries the short SHA. One line of the
-// build's history — `/plumbbob:pb-wrap` reads these instead of re-narrating the build.
+// build's history — `/plumbbob:pb-finish` reads these instead of re-narrating the build.
 export function checkpointLogLine(date, step, sha, title) {
     const head = `- ${date} — step ${step} checkpointed · ${sha.slice(0, 9)}`;
     return title !== null && title.length > 0 ? `${head} — ${title}` : head;

package/dist/lib/check.js

@@ -1,26 +1,95 @@
-// The heavy check (D16/D24): the full gate that `review` and `done` refuse to
-// advance past while red. The command is read from `.plumbbob/config` (`check=`)
-// so non-pnpm repos gate too; tests point it at a stub (`true`/`false`) since a
-// real `pnpm check` would recurse into vitest (D14).
+// The heavy check (D16/D24/D32): the full gate that `verify` and `checkpoint`
+// refuse to advance past while red. Two paths through one seam:
+//   - a `check` setting resolved through the ladder (flag → settings.local.json
+//     → settings.json, D27) is a shell command → spawn it exactly as before, so
+//     any repo can gate through anything (tests point it at `true`/`false`, D14);
+//   - no setting at all → checkride, our sibling package, imported
+//     programmatically (D32): the typed summary comes back in-process, failing
+//     slots are reported with their `.check/` raw-output pointers, and an
+//     all-slots-skipped run REFUSES rather than green-lighting a repo checkride
+//     can't see (a vacuous pass is not a pass).
+// Checkride's stream discipline holds: human progress goes to stderr. Exit 0 is
+// green, 1 is red, 2 means the harness itself broke — reported distinctly,
+// because a misconfigured gate must not read as broken code (both still block).
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { configPath } from "./sidecar.js";
-const DEFAULT_CHECK = 'pnpm run check';
-function readCheckCommand(root) {
-    let config = '';
-    try {
-        config = readFileSync(configPath(root), 'utf8');
-    }
-    catch {
-        return DEFAULT_CHECK;
+import { runChecks } from 'checkride';
+import { resolveString } from "./settings.js";
+// Runs the gate in `root` and returns the exit code (0 green, 1 red, 2 harness
+// error). `commandFlag` is the optional CLI override at the top of the settings
+// 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);
     }
-    const line = config.split('\n').find((l) => l.startsWith('check='));
-    return line === undefined ? DEFAULT_CHECK : line.slice('check='.length).trim();
+    return runCheckride(root, flags);
 }
-// Runs the configured check in `root`, streaming its output to the terminal so
-// the human sees what failed. Returns the exit code (0 = green).
-export function runCheck(root) {
-    const command = readCheckCommand(root);
+// The spawn override, byte-for-byte the pre-D32 behavior: stream the command's
+// own output to the terminal and return its exit code.
+function runCommand(root, command, flags) {
+    if (hasFlags(flags)) {
+        process.stderr.write(`plumbbob: check flags only narrow the checkride gate — ignored for the configured command '${command}'.\n`);
+    }
     const result = spawnSync(command, { cwd: root, shell: true, stdio: 'inherit' });
     return result.status ?? 1;
 }
+async function runCheckride(root, flags) {
+    let summary;
+    let exitCode;
+    try {
+        const result = await runChecks({
+            cwd: root,
+            bail: flags.bail ?? false,
+            changed: flags.changed ?? false,
+            all: flags.all ?? false,
+            only: flags.only !== undefined ? [...flags.only] : null,
+            skip: flags.skip !== undefined ? [...flags.skip] : null,
+            include: flags.include !== undefined ? [...flags.include] : null,
+        });
+        summary = result.summary;
+        exitCode = result.exitCode;
+    }
+    catch (err) {
+        // The harness broke, not the code (D32): a malformed checkride.config.json
+        // or the like. Checkride's own CLI maps this to exit 2; so do we.
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`plumbbob: the check gate itself failed — ${message}\n` +
+            `  Fix checkride.config.json, or set the "check" key in .plumbbob/settings.json to gate through another command.\n`);
+        return 2;
+    }
+    if (summary.checks.every((c) => c.skipped === true || c.name === 'links')) {
+        // Zero-config checkride skips slots with no detected tool; a repo it can't
+        // see must refuse, not vacuously green-light the checkpoint (D32). The
+        // built-in `links` slot is always-on (empty detect list), so it alone
+        // proves nothing about the code — a links-only run is still vacuous.
+        process.stderr.write('plumbbob: checkride found nothing to check in this repo — refusing to call that green.\n' +
+            '  Add tool configs (tsconfig, vitest, …) or a checkride.config.json custom check,\n' +
+            '  or set the "check" key in .plumbbob/settings.json to gate through another command.\n');
+        return 1;
+    }
+    if (exitCode !== 0) {
+        reportFailingSlots(summary);
+    }
+    return exitCode;
+}
+// Name the failing slots and where their raw diagnostics landed, so the agent
+// (pb-verify) reads the tool's own JSON instead of scraping scrollback. The
+// summary is the canonical pointer — `output_file` is the adapter's preferred
+// name, but non-JSON output falls back to `.check/<slot>.stdout.txt`.
+function reportFailingSlots(summary) {
+    const failing = summary.checks.filter((c) => !c.ok);
+    const lines = failing.map((c) => {
+        const adapter = c.adapter === null ? '' : ` (${c.adapter})`;
+        const output = c.output_file === null ? `.check/${c.name}.stdout.txt` : `.check/${c.output_file}`;
+        return `  ✘ ${c.name}${adapter} — raw output: ${output}`;
+    });
+    process.stderr.write(`plumbbob: failing slots:\n${lines.join('\n')}\n  Full report: .check/summary.json\n`);
+}
+function hasFlags(flags) {
+    return (flags.bail === true ||
+        flags.changed === true ||
+        flags.all === true ||
+        flags.only !== undefined ||
+        flags.skip !== undefined ||
+        flags.include !== undefined);
+}

package/dist/lib/git.js

@@ -1,7 +1,8 @@
-// Thin git wrapper over `node:child_process` (C2: node builtins only, zero
-// runtime deps). Functional/procedural, no classes (C1). Plumbbob's git
+// Thin git wrapper over `node:child_process` (C2: node builtins plus the
+// deliberate few). Functional/procedural, no classes (C1). Plumbbob's git
 // footprint is additive (C5); these helpers only read and locate.
 import { execFileSync } from 'node:child_process';
+import { isAbsolute, join } from 'node:path';
 function runGit(root, args) {
     return execFileSync('git', ['-C', root, ...args], {
         encoding: 'utf8',
@@ -17,9 +18,13 @@ export function findRepoRoot(cwd) {
         return null;
     }
 }
-// Absolute path to the .git directory (handles worktrees/linked git dirs).
-export function gitDir(root) {
-    return runGit(root, ['rev-parse', '--absolute-git-dir']);
+// Absolute path to a file inside the repo's *common* git dir. `--git-path` maps
+// common-dir entries like `info/exclude` to the shared file even from a linked
+// worktree, whose per-worktree gitdir has no `info/` and which git never reads
+// for excludes (D33). The result is relative to `root` unless already absolute.
+export function gitPath(root, relative) {
+    const out = runGit(root, ['rev-parse', '--git-path', relative]);
+    return isAbsolute(out) ? out : join(root, out);
 }
 export function headSha(root) {
     return runGit(root, ['rev-parse', 'HEAD']);
@@ -33,8 +38,7 @@ export function hasCommit(root) {
         return false;
     }
 }
-// Dirty = any tracked change or non-ignored untracked file. The sidecar is
-// git-excluded (D17), so an active session never reads as dirty.
+// Dirty = any tracked change or non-ignored untracked file.
 export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
@@ -43,16 +47,38 @@ export function isDirty(root) {
 export function stageAll(root) {
     runGit(root, ['add', '-A']);
 }
+// Stage a single path (vs `stageAll`'s `-A`): the plan-approval commit stages only
+// the build's artifact folder so the first step's diff can't absorb the plan
+// scaffold (D36). `path` may be absolute or repo-relative — git resolves it against
+// `root`. The `--` guards a path that could look like a flag.
+export function stagePath(root, path) {
+    runGit(root, ['add', '--', path]);
+}
 export function untrackedPaths(root) {
     const out = runGit(root, ['ls-files', '--others', '--exclude-standard']);
     return out.length === 0 ? [] : out.split('\n');
 }
 // Commit whatever is staged as a checkpoint and return its SHA. --allow-empty so
 // a step that touched only ignored files still gets a checkpoint to revert to.
-export function commit(root, message) {
-    runGit(root, ['commit', '--allow-empty', '-m', message]);
+// An optional `body` becomes the commit message body: git joins the two `-m`
+// paragraphs with a blank line, so the subject stays the first line (D34).
+export function commit(root, subject, body) {
+    const message = body ? ['-m', subject, '-m', body] : ['-m', subject];
+    runGit(root, ['commit', '--allow-empty', ...message]);
     return headSha(root);
 }
+// The `--stat` summary of what is currently staged (vs HEAD) — the diffstat the
+// deterministic checkpoint body carries (D35). Empty when nothing is staged.
+export function stagedStat(root) {
+    return runGit(root, ['diff', '--cached', '--stat']);
+}
+// The repo-relative paths currently staged (vs HEAD) — the set `checkpoint`
+// checks against the step's seam to warn about scope drift. Empty when nothing is
+// staged.
+export function stagedPaths(root) {
+    const out = runGit(root, ['diff', '--cached', '--name-only']);
+    return out.length === 0 ? [] : out.split('\n');
+}
 export function resetHard(root, sha) {
     runGit(root, ['reset', '--hard', sha]);
 }