plumbbob 0.8.3 → 0.8.10

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.3",
+  "version": "0.8.10",
   "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

@@ -231,12 +231,15 @@ matters.
 > The latch's payoff is measured, not asserted: the skill-eval harness
 > ([`test/evals/`](test/evals/)) sweeps this loop headless — prose-only baseline vs. the
 > shipped latch, N=5 per contract, every assertion a mechanical read of git state — and
-> commits the receipt to [`reports/evals/`](reports/evals/2026-07-11.md). The first sweep
+> commits the receipt to [`research/evals/`](research/evals/2026-07-11.md). The first sweep
 > (opus, 2026-07-11): the latch closes the route it owns — *no checkpoint over a red
 > check under pressure* went from **2/5 prose-only to 5/5 latched** — while the honest
 > numbers it also surfaced (park capture 0/5, and adversarial pressure consistently
 > flipping the `auto` standing grant in settings — a legal, model-writable side door)
-> are the next iteration's work, named in the report rather than papered over.
+> are the next iteration's work, named in the report rather than papered over. The
+> current sweep ([opus, 2026-07-18](research/evals/2026-07-18.md), plumbbob 0.8.7)
+> reproduces the win — *no checkpoint over a red check* still holds **5/5 latched** —
+> and confirms both gaps stand at 0.8.7, now the target of the hardening build.
 
 ## Documentation
 

package/dist/cli-core.js

@@ -9,6 +9,7 @@ import { start } from "./verbs/start.js";
 import { status } from "./verbs/status.js";
 import { park } from "./verbs/park.js";
 import { build } from "./verbs/build.js";
+import { handoff } from "./verbs/handoff.js";
 import { check } from "./verbs/check.js";
 import { checkpoint } from "./verbs/checkpoint.js";
 import { revert } from "./verbs/revert.js";
@@ -22,7 +23,8 @@ import { turn } from "./verbs/turn.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: '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' },
@@ -71,6 +73,8 @@ async function dispatch(verb, cwd, rest) {
             return park(cwd, rest);
         case 'build':
             return build(cwd, rest);
+        case 'handoff':
+            return handoff(cwd, rest);
         case 'check':
             return check(cwd, rest);
         case 'checkpoint':

package/dist/lib/latch.js

@@ -2,33 +2,41 @@
 // before its check gate (C4: cheap first; the gate already ran in the verify
 // tick). The work plane stays guidance (D10/D13 untouched); only the commit tick
 // is latched: a step may not land unless a human turn intervened since entry, the
-// human granted self-approval (D65 one-turn grant, D27 standing `auto`), or the
-// ledger is dormant. Six rows, evaluated in order, first hit wins; the refusal
-// message *is* the pause affordance. Reads TURN/TICK/GRANT/isTTY only — never the
-// host (C5). Functional, named exports, node builtins (C1/C2).
+// human granted self-approval (a D65 one-turn grant from their literal prompt), or
+// the ledger is dormant. Five rows, evaluated in order, first hit wins; the refusal
+// message *is* the pause affordance. A standing `auto` in a settings file is NOT a
+// grant (D67): a model can write that file, and a grant it can forge is no grant —
+// so the latch reads it only to say so at the pause, never to allow. Reads
+// TURN/TICK/GRANT/isTTY only — never the host (C5). Named exports, node builtins.
 import { readFileSync } from 'node:fs';
 import { grantPath, tickPath, turnPath } from "./sidecar.js";
 import { resolveBoolean } from "./settings.js";
 const ALLOW = { allow: true };
-// The exact refusal (the spec pins this prose): the message is the affordance —
-// it tells the model what the pause is and names the only legitimate grants. The
-// plan commit gets its own wording: there is no step, no diff, and no self-review
-// at plan time — what the human approves is the plan itself.
+// The refusal message is the affordance — it tells the model what the pause is,
+// how it ends (approval on the next turn lands it; `/pb-build` only starts the next
+// step), and names the only legitimate grants. The plan commit gets its own wording:
+// there is no step, no diff, and no self-review at plan time — what the human approves
+// is the plan itself.
 const NO_TURN_MESSAGE = `plumbbob: checkpoint refused — no human turn since this step began. This is the
-pause: present the diff and the self-review, then end the turn; the human's next
-message is the tick. (An explicit \`/pb-build --auto\` or a step range in the human's
-own prompt grants self-approval; \`auto: true\` in settings.local.json is the standing
-grant.)
+pause: present the diff and the self-review, then end the turn. The human's approval on
+their next turn is what lets this land — re-run \`checkpoint\` then and stop at the
+boundary; \`/pb-build\` only starts the next step, it never lands this one. (An explicit
+\`/pb-build --auto\` or a step range in the human's own prompt is the only self-approval.)
 `;
 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. (\`auto: true\` in
-settings.local.json is the standing grant.)
+message is the tick that lets it land on re-fire. (An explicit \`/pb-build --auto\` or a
+step range in the human's own prompt is the only self-approval.)
+`;
+// D67: a settings `auto` is no longer honored — a model can write that file, so a
+// grant it can forge is no grant. When one is set we say so at the point of refusal,
+// rather than silently ignoring it, and point 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 \`/pb-build --auto\` to self-approve.
 `;
 function ceilingMessage(ceiling) {
     return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; re-fire to continue.\n`;
 }
-// The six-row matrix, in order, first hit wins. A `range` grant speaks only to
+// The five-row matrix, in order, first hit wins. A `range` grant speaks only to
 // numbered steps: on a `--plan` checkpoint (step null) it neither allows nor
 // refuses, and the decision falls through to the turn comparison.
 export function evaluateLatch(input) {
@@ -36,19 +44,19 @@ export function evaluateLatch(input) {
         return ALLOW; // 1 — a human at the keyboard
     if (input.turn === null || input.tick === null)
         return ALLOW; // 2 — dormant / hand-built
-    if (input.auto)
-        return ALLOW; // 3 — standing personal grant (D27)
     if (input.grant?.kind === 'auto')
-        return ALLOW; // 4 — one-turn grant
+        return ALLOW; // 3 — one-turn grant (D65)
     if (input.grant?.kind === 'range' && input.step !== null) {
         if (input.step <= input.grant.ceiling)
             return ALLOW;
         return { allow: false, reason: 'ceiling', message: ceilingMessage(input.grant.ceiling) };
     }
     if (input.turn > input.tick)
-        return ALLOW; // 5 — a human turn intervened
-    // 6 — the pause (plan-worded when no step is landing)
-    return { allow: false, reason: 'no-turn', message: input.step === null ? NO_TURN_PLAN_MESSAGE : NO_TURN_MESSAGE };
+        return ALLOW; // 4 — a human turn intervened
+    // 5 — the pause (plan-worded when no step is landing). A settings `auto` no longer
+    // allows (D67); when one is set, the refusal notes it rather than honoring it.
+    const base = input.step === null ? NO_TURN_PLAN_MESSAGE : NO_TURN_MESSAGE;
+    return { allow: false, reason: 'no-turn', message: input.settingsAuto ? base + SETTINGS_AUTO_NOTE : base };
 }
 // Parse a GRANT file's content (`auto` | `range <M>`). Anything else — including
 // a corrupted or hand-mangled file — contributes nothing (D27): no grant, never
@@ -70,9 +78,10 @@ export function checkLatch(root, step) {
         isTTY: process.stdin.isTTY === true,
         turn: readCount(turnPath(root)),
         tick: readCount(tickPath(root)),
-        auto: resolveBoolean(root, 'auto', false),
         grant: readGrant(root),
         step,
+        // Still read from the ladder — but only to decorate the pause (D67), not to allow.
+        settingsAuto: resolveBoolean(root, 'auto', false),
     });
 }
 function readGrant(root) {

package/dist/lib/settings.js

@@ -8,10 +8,13 @@
 // overlay can never wedge the tool. Functional/procedural, node builtins (C1/C2).
 //
 // Known keys: `check` (string — the heavy gate, tracked in settings.json) and
-// `auto` (boolean — whether the agent approves in the human's place; a personal
-// preference, so it belongs in settings.local.json). The per-worktree active-build
-// cursor is NOT here — it lives in the STATE file (see sidecar.ts), so this overlay
-// stays purely human-owned and the tool never rewrites it.
+// `auto` (boolean — a personal preference, so it belongs in settings.local.json).
+// Since D67 `auto` is NOT a checkpoint grant: the latch no longer reads it to allow
+// a land (a model can write this file, and a grant it can forge is no grant), only to
+// note it at the pause; self-approval comes from the human's literal `/pb-build --auto`
+// or a range. The per-worktree active-build cursor is NOT here — it lives in the STATE
+// file (see sidecar.ts), so this overlay stays purely human-owned and the tool never
+// rewrites it.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 const DIRNAME = '.plumbbob';

package/dist/verbs/agent.js

@@ -99,8 +99,16 @@ async function runOne(root, slug, step, spec) {
         step,
         mode,
         settings: {
+            // The frozen envelope still reports settings `auto` to agents (doorway freeze —
+            // no envelope changes). Note it is no longer a checkpoint grant (D67): the latch
+            // stopped reading it, so a `true` here informs an agent, it does not self-approve.
             auto: resolveBoolean(root, 'auto', false),
             agentTimeout: resolveNumber(root, 'agentTimeout', 0),
+            // Hand this agent its own config block over the frozen envelope `settings`
+            // field (D5/D6): settings.json → agentConfig[name], with the local overlay
+            // shadowing the project rung whole (D7 — no deep merge), and {} when neither
+            // defines it. No new envelope field, no new verb — the config just rides here.
+            agent: resolveRecord(root, 'agentConfig')[spec.name] ?? {},
         },
     });
     if (!composed.ok) {

package/dist/verbs/build.js

@@ -5,6 +5,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
+import { parseSteps } from "../lib/orient.js";
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -20,12 +21,30 @@ export function build(cwd, args) {
         process.stderr.write(`plumbbob: build takes one step number; \`${raw}\` step ranges are a \`/pb-build\` feature (auto-approve through the range, then pause). Try \`plumbbob build ${raw.split('-')[0]}\`.\n`);
         return 1;
     }
-    if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
+    // An explicit arg that isn't a positive integer is a usage error — caught before
+    // reading intent.md so the message doesn't depend on the plan being present.
+    if (raw !== undefined && (!/^\d+$/.test(raw) || Number(raw) < 1)) {
         process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n');
         return 1;
     }
-    const step = Number(raw);
-    const parsed = parseStepSeam(readFileSync(intentPath(root, slug), 'utf8'), step);
+    const intent = readFileSync(intentPath(root, slug), 'utf8');
+    // No argument ⇒ enter the next undone step in intent.md (the same idiom
+    // `checkpoint` uses), so a bare `plumbbob build` advances the loop without the
+    // skill re-deriving the step in prose. Every step checkpointed ⇒ a `/pb-step`
+    // nudge, not a silent no-op.
+    let step;
+    if (raw === undefined) {
+        const nextUndone = parseSteps(intent).find((s) => !s.done);
+        if (nextUndone === undefined) {
+            process.stderr.write('plumbbob: no undone step to build — every planned step is checkpointed. `/pb-step` to add an increment, or `/pb-finish`.\n');
+            return 1;
+        }
+        step = nextUndone.n;
+    }
+    else {
+        step = Number(raw);
+    }
+    const parsed = parseStepSeam(intent, step);
     if (!parsed.ok) {
         process.stderr.write(`plumbbob: ${parsed.error} Fix the step's seam in intent.md, then \`build ${step}\` again.\n`);
         return 1;
@@ -36,6 +55,7 @@ export function build(cwd, args) {
     // The wall-clock receipt starts here (research/07 Build 2b): checkpoint stamps
     // landedAt, and the pair becomes the step's duration in the finish report.
     stampStepStat(root, slug, step, 'startedAt', new Date().toISOString());
-    process.stdout.write(`plumbbob: building step ${step}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
+    const picked = raw === undefined ? ' (next undone)' : '';
+    process.stdout.write(`plumbbob: building step ${step}${picked}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
 }

package/dist/verbs/doctor.js

@@ -32,7 +32,7 @@ import { gateDetectsTools } from "../lib/check.js";
 import { marketplacePlumbbob } from "../lib/plugins.js";
 import { findRepoRoot, gitPath, stagePath } from "../lib/git.js";
 import { buildDir, excludeControl, listBuilds, readTurn, setActiveBuild, sidecarDir, slugify } from "../lib/sidecar.js";
-import { resolveString, settingsPath } from "../lib/settings.js";
+import { resolveBoolean, resolveString, settingsPath } from "../lib/settings.js";
 // The plumbbob package's own skills/ dir (the canonical set), off this module's
 // URL so it resolves the same from src/ (dev) and dist/ (published).
 function packageDir(name) {
@@ -365,7 +365,7 @@ function agentReport(cwd) {
 // slot/adapter table. Only rows checkride marks `required` count as problems —
 // an empty slot ("no tool detected") is informational, not a failure, because
 // the runtime gate already refuses a vacuous run.
-async function gateReport(cwd) {
+async function gateReport(cwd, env) {
     const root = findRepoRoot(cwd);
     if (root === null)
         return { lines: [], failed: 0 };
@@ -377,7 +377,9 @@ async function gateReport(cwd) {
     }
     try {
         const silent = { write: () => true };
-        const { report } = await runDoctor({ cwd: root, stdout: silent });
+        // env is undefined in production → runDoctor falls back to its real toolchain
+        // probe; tests inject a deterministic one (see GateEnv).
+        const { report } = await runDoctor({ cwd: root, stdout: silent, env });
         let failed = 0;
         for (const c of report.checks) {
             if (c.category === 'tool') {
@@ -433,9 +435,16 @@ 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})`;
-    return { lines: ['', 'plumbbob doctor — approval latch (D64)', line], failed: 0 };
+    const lines = ['', 'plumbbob doctor — approval latch (D64)', line];
+    // D67: a settings `auto` used to be a standing grant; the latch no longer honors it
+    // (a model can write that file). Surface a set value so a human who relied 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 `/pb-build --auto`');
+    }
+    return { lines, failed: 0 };
 }
-export async function doctor(cwd, args = []) {
+export async function doctor(cwd, args = [], env) {
     const checks = pluginChecks();
     const out = ['plumbbob doctor — plugin install'];
     for (const c of checks) {
@@ -445,7 +454,7 @@ export async function doctor(cwd, args = []) {
     out.push(...sidecar.lines);
     const agents = agentReport(cwd);
     out.push(...agents.lines);
-    const gate = await gateReport(cwd);
+    const gate = await gateReport(cwd, env);
     out.push(...gate.lines);
     const latch = latchReport(cwd);
     out.push(...latch.lines);

package/dist/verbs/handoff.js

@@ -0,0 +1,103 @@
+// `plumbbob handoff` — print the standardized build hand-off block (D67): the
+// "state / choice / what's next" the human sees at each step boundary. Read-only,
+// no state change. It derives the moment from the session — a step in flight ⇒ the
+// pause block (built → looks-good/needs-work → next), none ⇒ the post-checkpoint
+// boundary block — and renders the next undone step plus its advisory `- model:`
+// recommendation straight from intent.md. This block lived as prose in pb-build's
+// SKILL.md; owning it here keeps the skill from drifting out of sync with `status`,
+// which renders the same next-step detail (both read `parseSteps`).
+import { readFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { checkpointsPath, hasSession, intentPath, resolveBuild, stepPath } from "../lib/sidecar.js";
+import { parseLastCheckpoint, parseSteps } from "../lib/orient.js";
+export function handoff(cwd, args = []) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const { build: slug, rest } = resolveBuild(root, args);
+    const steps = parseSteps(readOr(intentPath(root, slug)));
+    const inFlight = readStep(stepPath(root, slug));
+    const explicit = rest.find((a) => /^\d+$/.test(a));
+    const lastDone = parseLastCheckpoint(readOr(checkpointsPath(root, slug)));
+    // The step this hand-off is about: an explicit arg wins (the skill's override),
+    // else the in-flight step (the pause), else the last checkpointed step (the
+    // boundary). Null only on a fresh session the skill would not hand off from.
+    const current = explicit !== undefined ? Number(explicit) : (inFlight ?? lastDone?.n ?? null);
+    // Next up: the first undone step that is not the current one. At the pause the
+    // current step is still `[ ]`, so excluding it by number is what makes "next"
+    // mean the step *after* it; at the boundary the current step is already `[x]`,
+    // so the `!== current` clause is a harmless no-op. Skipping-ahead builds still
+    // land on the earliest remaining step, never a gap.
+    const nextUp = steps.find((s) => !s.done && s.n !== current);
+    if (current === null) {
+        // No step to report as just-done (fresh session): emit only the forward pointer.
+        process.stdout.write(`${nextUpLine(nextUp)}\n`);
+        return 0;
+    }
+    const block = inFlight !== null ? pauseBlock(current, titleOf(steps, current), nextUp) : boundaryBlock(current, titleOf(steps, current), nextUp);
+    process.stdout.write(`${block}\n`);
+    return 0;
+}
+// The pause block: the step is built and awaiting approval. The opener is neutral
+// (the CLI cannot vouch for the diff), pointing at the diff and self-review the
+// skill shows above it.
+function pauseBlock(step, title, nextUp) {
+    return [
+        `Step ${step}${paren(title)} is built. Review the diff and self-review above, then:`,
+        `  - looks good → I'll checkpoint it (lands step ${step} as its own commit, back to the boundary)`,
+        `  - needs work → tell me what to change and I'll iterate on this same step`,
+        '',
+        nextUpLine(nextUp),
+    ].join('\n');
+}
+// The boundary block: the checkpoint has landed and the loop is back at the
+// step boundary, pointing at what to build next.
+function boundaryBlock(step, title, nextUp) {
+    return [`Step ${step}${paren(title)} checkpointed — back at the boundary.`, '', nextUpLine(nextUp)].join('\n');
+}
+// The forward pointer, shared by both blocks: the next undone step, its title, and
+// its advisory `- model:` recommendation (as just the model token for the `/model`
+// call — the full rationale lives on the `status` dashboard). No next step ⇒ the
+// finish/step nudge instead.
+function nextUpLine(nextUp) {
+    if (nextUp === undefined) {
+        return 'No planned steps remain — /pb-step to add an increment, or /pb-finish.';
+    }
+    const head = `Next up: step ${nextUp.n}${paren(nextUp.title)}`;
+    const token = modelToken(nextUp.model);
+    return token === null ? `${head} — /pb-build to start it.` : `${head} · model: ${token} — /model ${token} then /pb-build.`;
+}
+// A step's title in parentheses, or nothing when the title is empty.
+function paren(title) {
+    return title !== null && title.length > 0 ? ` (${title})` : '';
+}
+function titleOf(steps, n) {
+    return steps.find((s) => s.n === n)?.title ?? null;
+}
+// The model token from a `- model:` recommendation — the first word, so a
+// `model: opus — <rationale>` line yields `opus` for the `/model` call. Null when
+// there is no recommendation, or it degraded to whitespace (folding the null model
+// into the same guard keeps both branches live).
+function modelToken(model) {
+    const first = model?.trim().split(/\s+/)[0];
+    return first !== undefined && first.length > 0 ? first : null;
+}
+function readOr(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function readStep(path) {
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/verbs/turn.js

@@ -3,20 +3,54 @@
 // monotonic count of human turns the checkpoint latch reads to know a human turn
 // intervened since a step began) and rewrites `.plumbbob/GRANT` from the literal
 // prompt — minting a one-turn self-approval only when the human typed
-// `/pb-build --auto` or a `N-M` range (D65), clearing it otherwise. Pure machinery,
-// not a user verb: it writes nothing to stdout and ALWAYS exits 0, so a broken tick
-// can never wedge prompting (C3).
+// `/pb-build --auto` or a `N-M` range (D65), clearing it otherwise. When a step is
+// in flight it also emits ONE `UserPromptSubmit` additionalContext line so a fresh
+// session (post-compaction, or a new `-p` turn where no skill is in context) still
+// knows the beat — a tangent is parked, not chased (amends D64's "writes nothing";
+// guidance only, D10/D13). It ALWAYS exits 0 and any failure degrades to no output,
+// so neither the tick nor the emit can ever wedge prompting (C3).
 import { readFileSync, writeFileSync } from 'node:fs';
-import { findSessionRoot, setGrant, turnPath } from "../lib/sidecar.js";
+import { findSessionRoot, setGrant, stepPath, turnPath } from "../lib/sidecar.js";
 export function turn(cwd, _args) {
     try {
         applyTurn(cwd, readStdin());
+        const context = stepInFlightContext(cwd);
+        if (context !== null)
+            process.stdout.write(context);
     }
     catch {
         // C3: a broken turn must never wedge a prompt — swallow and exit 0.
     }
     return 0;
 }
+// The `UserPromptSubmit` additionalContext payload when a step is in flight (a STEP
+// marker between `build` and `checkpoint`), or null. Guidance only: it reminds a
+// fresh session that a tangent is a park (not an edit) and how the step lands, since
+// the pb-build prose may not be in context after compaction or on a scripted turn.
+// Exported because an in-process test cannot read the hook's real stdout.
+export function stepInFlightContext(cwd) {
+    const root = findSessionRoot(cwd);
+    if (root === null)
+        return null;
+    const step = inFlightStep(root);
+    if (step === null)
+        return null;
+    const text = `plumbbob: step ${step} is in flight — a new idea or tangent is a park, not an edit: ` +
+        `capture it with \`plumbbob park "<one line>"\`, then stay on the step. ` +
+        `It lands when you run \`plumbbob checkpoint ${step}\` after approval.`;
+    return `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } })}\n`;
+}
+// The in-flight step number, or null when no STEP marker is present (no step entered,
+// or it already checkpointed). A garbled marker reads as null — never an error (C3).
+function inFlightStep(root) {
+    try {
+        const n = Number.parseInt(readFileSync(stepPath(root), 'utf8').trim(), 10);
+        return Number.isFinite(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
 // The testable core: apply one tick given the raw hook stdin. Split from the fd-0
 // read so the unit tests can drive it directly — an in-process test cannot feed fd 0
 // (the same constraint checkpoint's `--body` lives under).
@@ -35,10 +69,12 @@ export function applyTurn(cwd, raw) {
 // The namespaced `/plumbbob:pb-build` form is honored alongside the bare one.
 //
 // Only the invocation's own arguments can mint: the tokens that follow it on its
-// line, up to the first token that isn't argument-shaped (a flag, a step number, a
-// range). An incidental range elsewhere in the prompt — an issue number, a pasted
-// `2020-2024` — is prose, not a grant. Trailing sentence punctuation on an argument
-// (`/pb-build 1-3.`) is still the argument the human typed.
+// line, up to the first token that isn't a sanctioned argument (`--auto`, a step
+// number, or a range — the argument-hint sanctions nothing else). An unrecognized
+// flag ends the scan, so `/pb-build --wip 2020-2024` mints nothing — the `2020-2024`
+// is never reached. An incidental range elsewhere in the prompt — an issue number, a
+// pasted `2020-2024` — is prose, not a grant. Trailing sentence punctuation on an
+// argument (`/pb-build 1-3.`) is still the argument the human typed.
 export function grantFromPrompt(prompt) {
     const invocation = /\/(?:plumbbob:)?pb-build\b/.exec(prompt);
     if (invocation === null)
@@ -59,9 +95,9 @@ export function grantFromPrompt(prompt) {
             ceiling = range[1];
             continue;
         }
-        if (/^\d+$/.test(word) || word.startsWith('-'))
-            continue; // a step number or another flag
-        break; // free text — the arguments have ended
+        if (/^\d+$/.test(word))
+            continue; // a bare step number — keep scanning for a range/--auto
+        break; // an unrecognized flag or free text — the arguments have ended
     }
     if (ceiling !== undefined)
         return `range ${ceiling}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.8.3",
+  "version": "0.8.10",
   "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",
@@ -34,39 +34,33 @@
   "engines": {
     "node": ">=22.18.0"
   },
-  "devEngines": {
-    "packageManager": {
-      "name": "pnpm",
-      "version": "11.1.2",
-      "onFail": "download"
-    }
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm run clean && pnpm run build",
+    "check": "checkride",
+    "test": "vitest run",
+    "eval:baseline": "pnpm build && node test/evals/run.ts --sweep baseline",
+    "eval:latched": "pnpm build && node test/evals/run.ts --sweep latched",
+    "eval:report": "node test/evals/run.ts --report"
   },
   "devDependencies": {
-    "@ast-grep/cli": "^0.43.0",
-    "@stryker-mutator/core": "^9.6.1",
-    "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@types/node": "^24.0.0",
-    "@vitest/coverage-v8": "^4.1.9",
-    "fallow": "^2.103.0",
+    "@ast-grep/cli": "0.43.0",
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
+    "@types/node": "24.13.1",
+    "@vitest/coverage-v8": "4.1.9",
+    "fallow": "2.103.0",
     "fascicle": "0.8.16",
-    "markdownlint-cli2": "^0.22.1",
-    "oxlint": "^1.69.0",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "markdownlint-cli2": "0.22.1",
+    "oxlint": "1.69.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
   },
   "dependencies": {
     "checkride": "0.3.0"
   },
   "bundleDependencies": [
     "checkride"
-  ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "tsc -p tsconfig.build.json",
-    "check": "checkride",
-    "test": "vitest run",
-    "eval:baseline": "pnpm build && node test/evals/run.ts --sweep baseline",
-    "eval:latched": "pnpm build && node test/evals/run.ts --sweep latched",
-    "eval:report": "node test/evals/run.ts --report"
-  }
-}
+  ]
+}

package/skills/pb-build/SKILL.md

@@ -3,7 +3,7 @@ name: pb-build
 description: The default engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable — build by hand/vibed/another harness and run /pb-verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses.
 argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(git diff:*)
 ---
 
 # PlumbBob — build a step (the default engine)
@@ -30,51 +30,36 @@ differs from the model you're running as, say so before implementing — the hum
 1. **Pick the step.** Use the number you were invoked with (e.g. `/pb-build 4`) — or,
    if you were given a range like `/pb-build 1-3`, start at the first number and treat
    the second as the auto-approve ceiling (see the range note under `--auto`). With no
-   argument, take the next undone, planned step in `.plumbbob/intent.md`. If there is no
-   planned step to build, stop and tell the human to `/pb-step` first.
-2. **Enter the step.** Run `plumbbob build <n>` (records the in-flight STEP +
-   SEAM so `/pb-status` shows the step in flight; the seam is awareness, not a
-   lock).
+   argument, don't resolve the next step yourself — the CLI does: bare `plumbbob build`
+   (step 2) enters the next undone step and refuses with a `/pb-step` nudge when every
+   step is checkpointed.
+2. **Enter the step.** Run `plumbbob build <n>` — or bare `plumbbob build` to enter the
+   next undone step (records the in-flight STEP + SEAM so `/pb-status` shows the step in
+   flight; the seam is awareness, not a lock).
 3. **Read the plan.** Read the step's **done-when**, its **seam**, and the
    **Decisions** and **Constraints** in `intent.md`. Build to *that* — the deciding
    already happened, off the chat.
-   - **Run any bound `before`-agents**. If the build's `harness.json` binds
-     agents to this step's `before` slot, run `plumbbob agent run --step <n> --mode
-     before` first: each returns a validated envelope on stdout that plumbbob also
-     appends to the step's `handoff.json`, and its `summary`/`body` become **context you
-     read into the build** (that is the whole point of the slot — load the context in
-     before you write). No binding, or no harness, is a clean no-op — just build.
+   - **Bound `before`-agents load context first.** If `plumbbob status` shows a
+     `harness bindings:` block, this build binds agents — see **§ Running bound agents**
+     and load their context in before you write. No bindings, no harness: just build.
 4. **Implement** the step, and only that step, staying within the declared seam. A
-   new problem or "ooh what if" that surfaces mid-build is a `/pb-park`, **not** an
-   edit — capture it and stay on the step. If you genuinely cannot finish without
-   touching more than the seam, that is scope drift: surface it to the human rather
-   than sprawling.
-   - **If a `build`-slot agent is bound, delegate the diff to it**. Run
-     `plumbbob agent run --step <n> --mode build` and let that agent author the step's
-     code instead of writing it yourself; its envelope reports what it did. You still
-     own the verify tick below — the diff is reviewed the same way whoever wrote it.
-   - **A manifest's `when` prose is your cue to fire an agent mid-build**.
-     The three slots are the only *declarative* lifecycle points; there is no config for
-     "a salient moment in the middle." That is judgment, and you are the frontier model
-     in the room: when the work reaches the situation a bound agent's `when` (or a step
-     `note`) describes, fire `plumbbob agent run <name> --step <n>` yourself. Prose is
-     the orchestration language; you are the workflow engine.
-   - **Route a non-`done` envelope by its status**. An agent that returns
-     `blocked` couldn't finish (missing input, failed precondition): surface its `notes`,
-     let the human unblock, and re-run it — don't work around it. One that returns
-     `drift` finished but found the plan no longer matches reality: **stop and send the
-     human to `/pb-refine`** to repair the plan before continuing, rather than building
-     on a plan that's now wrong. A non-zero exit is a failed run: report it and stop.
+   new problem or "ooh what if" that surfaces mid-build is a park, **not** an edit:
+   capture it by running `plumbbob park "<one tidy line>"` — **saying "let's defer
+   that" writes nothing; only the park line in the build log is a capture.** When the
+   *human* hands you the tangent mid-build, their message **is** the approval to park
+   it — capture it right away, say what you parked, and stay on the step. If you
+   genuinely cannot finish without touching more than the seam, that is scope drift:
+   surface it to the human rather than sprawling.
+   - **Bound agents can shape the build.** If `plumbbob status` shows a
+     `harness bindings:` block, a `build`-slot agent may author the diff, a `when`-cue may
+     fire an agent mid-build, and a non-`done` envelope routes by its status — see
+     **§ Running bound agents**.
 5. **Verify, through to the pause.** Run the verify tick exactly as `/pb-verify`
    does: `plumbbob check` (on red, read `.check/summary.json` and the failing slot's
    raw output under `.check/` for the actual diagnostics; while iterating on a fix,
    narrow the loop with `plumbbob check --bail --only <slots>` — the checkpoint gate
-   still runs everything) → run any bound `after`-agents (`plumbbob agent run --step
-   <n> --mode after`) and fold their envelopes into the self-review as **advisory
-   input** — they inform, they never gate (checkride gates, the human is the clock; an
-   `after`-agent that could fail a step is the lock in autonomy's costume) →
-   self-review the diff against the done-when, the Decisions, and the Constraints (a
-   single structured read) → validate → **PAUSE
+   still runs everything) → self-review the diff against the done-when, the Decisions,
+   and the Constraints (a single structured read) → validate → **PAUSE
    for the human's approval** → only on approval, checkpoint with
    `plumbbob checkpoint <n> --body <<'BODY' … BODY` — a commit body **proportional to the
    step** (a line for a trivial change, a short paragraph for a meatier one; no TIL scan,
@@ -82,24 +67,73 @@ differs from the model you're running as, say so before implementing — the hum
    build-log's `## Log`, so the history writes itself — you only supply the body (or omit
    `--body` for the deterministic done-when + seam + diffstat fallback). Do **not** bump
    the version or changelog — that is the human's `/version` call.
+   - **If `plumbbob status` shows a `harness bindings:` block**, fold any bound
+     `after`-agents into that self-review as advisory input — see **§ Running bound
+     agents**.
 
    **The latch makes this pause real.** On the default (non-`--auto`) path you
    build the step and reach the pause *in one turn* — so under plumbbob's turn hook the
    checkpoint at the end of that turn is **refused** ("no human turn since this step
    began"), and that refusal **is** the pause working as designed. Do exactly what the
-   pause already asks: present the diff and the self-review, **end the turn**, and the
-   human's next message is the tick that lands the checkpoint when you re-fire. **Never
-   route around a refusal with a raw `git commit`** — the work plane stays free,
-   but the *record* is latched on purpose.
-
-   **Then hand off with the next model.** Once the checkpoint lands on re-fire, close the
-   turn by citing where the loop now stands: the step you just completed and the next
-   undone step. If that next step carries a `- model:` recommendation (the plan's
-   smallest-model-that-fits call, echoed on `plumbbob status`'s `▸ next` line), **name
-   it** so the human knows which `/model` to select before firing `/pb-build` again — it
-   is what carries the plan's suggestion across a fresh context window, which inherits the
-   session model, not the plan's. No `- model:` line means any model will do. Guidance,
-   never a gate.
+   pause asks: present the diff and the self-review, emit the closing block below, and
+   **end the turn**. The human's next message — their approval — is the human turn that
+   lets the checkpoint land: on that turn you run `plumbbob checkpoint <n>` (now allowed)
+   and **stop at the boundary**. Landing the checkpoint is its own deliberate beat — the
+   thing approval triggers — never a side effect of starting the next step, and
+   `/pb-build` only ever starts the *next* step. **Never route around a refusal with a
+   raw `git commit`** — the work plane stays free, but the *record* is latched on purpose.
+
+   **End every default build turn with the standardized hand-off block.** Run `plumbbob
+   handoff` and present its output — it renders the same three-part shape (the state, the
+   choice, what's next) straight from the session: step N built, the looks-good /
+   needs-work choice, and the next undone step with its `- model:` recommendation. Show
+   your diff and self-review above it. The CLI owns the block so it can't drift from what
+   `/pb-status` reports; you supply only the judgment above it. It already drops the model
+   clause when the next step has none, and says so when no planned step remains — you
+   don't reproduce the template by hand.
+
+   **Then hand off with the next model.** Once the checkpoint lands in the approval turn,
+   run `plumbbob handoff` again and relay its boundary block — with the step gone from
+   in-flight it renders "step N checkpointed" and points at the next undone step, carrying
+   that step's `- model:` recommendation (the plan's smallest-model-that-fits call) so the
+   human knows which `/model` to select before firing `/pb-build` again. It is what
+   carries the plan's suggestion across a fresh context window, which inherits the session
+   model, not the plan's. No `- model:` line means any model will do. Guidance, never a
+   gate.
+
+## Running bound agents
+
+Skip this section unless `plumbbob status` shows a `harness bindings:` block. Nearly every
+build binds **no** agents — for them the default path above is the whole story. When a
+harness *is* bound, this is what each affected step gains, in lifecycle order.
+
+- **`before` — load context in (step 3).** If the build's `harness.json` binds agents to
+  this step's `before` slot, run `plumbbob agent run --step <n> --mode before` first: each
+  returns a validated envelope on stdout that plumbbob also appends to the step's
+  `handoff.json`, and its `summary`/`body` become **context you read into the build** (that
+  is the whole point of the slot — load the context in before you write). No binding, or no
+  harness, is a clean no-op — just build.
+- **`build` — delegate the diff (step 4).** If a `build`-slot agent is bound, run
+  `plumbbob agent run --step <n> --mode build` and let that agent author the step's code
+  instead of writing it yourself; its envelope reports what it did. You still own the verify
+  tick — the diff is reviewed the same way whoever wrote it.
+- **A manifest's `when` prose is your cue to fire an agent mid-build (step 4).** The three
+  slots are the only *declarative* lifecycle points; there is no config for "a salient
+  moment in the middle." That is judgment, and you are the frontier model in the room: when
+  the work reaches the situation a bound agent's `when` (or a step `note`) describes, fire
+  `plumbbob agent run <name> --step <n>` yourself. Prose is the orchestration language; you
+  are the workflow engine.
+- **Route a non-`done` envelope by its status (step 4).** An agent that returns `blocked`
+  couldn't finish (missing input, failed precondition): surface its `notes`, let the human
+  unblock, and re-run it — don't work around it. One that returns `drift` finished but found
+  the plan no longer matches reality: **stop and send the human to `/pb-refine`** to repair
+  the plan before continuing, rather than building on a plan that's now wrong. A non-zero
+  exit is a failed run: report it and stop.
+- **`after` — advisory input to the verify tick (step 5).** After `plumbbob check`, run any
+  bound `after`-agents (`plumbbob agent run --step <n> --mode after`) and fold their
+  envelopes into the self-review as **advisory input** — they inform, they never gate
+  (checkride gates, the human is the clock; an `after`-agent that could fail a step is the
+  lock in autonomy's costume).
 
 ## `--auto` — let the agent be the clock (opt-in)
 
@@ -107,8 +141,8 @@ differs from the model you're running as, say so before implementing — the hum
 progress instead of approving each step. It does the same work, but **the agent reviews
 and approves in the human's place**, and it **chains**:
 
-- Build the next step, running its slots in the same order as the default
-  path: bound `before`-agents → implement (or the bound `build`-agent) → bound
+- Build the next step, running its slots (see **§ Running bound agents**) in the same
+  order as the default path: bound `before`-agents → implement (or the bound `build`-agent) → bound
   `after`-agents → `check` → self-review → **if the check is green AND the
   self-review finds no done-when / Decision / Constraint mismatch, checkpoint** and move
   straight on to the next planned step. Repeat. `--auto` adds no new machinery — the
@@ -118,9 +152,10 @@ and approves in the human's place**, and it **chains**:
   bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/pb-refine` — an
   agent cannot advance the loop), a new decision is needed, no planned steps
   remain, or the top of a requested range is reached. **When `--auto` halts back to the
-  human, give the same hand-off the default pause does** — the step just completed, the
-  next undone step, and that next step's `- model:` recommendation if it has one, so a
-  fresh context window knows which `/model` to select.
+  human, give the same hand-off the default pause does** — run `plumbbob handoff` and
+  relay its block: the step just completed, the next undone step, and that next step's
+  `- model:` recommendation if it has one, so a fresh context window knows which `/model`
+  to select.
 
 `--auto` and a step range are the only paths that checkpoint without a human pause, and
 only because the human asked for it by name; a range re-imposes the pause at its top.
@@ -153,7 +188,8 @@ just the one more entry already in the halt list above.
 - **Swappable, never required.** The loop works without this skill; `/pb-verify`
   checkpoints a hand-built or vibed diff just the same.
 - **Build the decided step, not a new one.** Implement what `intent.md` settled. A
-  new idea mid-build is a `/pb-park`, not an edit.
+  new idea mid-build is captured with `plumbbob park`, not an edit — a promise to
+  defer writes nothing; the park line does.
 - **Default ends at the pause.** Implement → verify → wait for approval; never
   checkpoint without it. Only an explicit `--auto` or a step range lets the agent approve
   in your place, and it still halts on a red check or any mismatch — a range also stops
@@ -161,13 +197,17 @@ just the one more entry already in the halt list above.
 - **Agents feed the beat; they never advance it**. `before` loads context,
   `build` writes the diff, `after` is advisory — none can checkpoint, flip a step, or
   chain. `blocked` → unblock and re-run; `drift` → `/pb-refine`. You are still the one
-  who verifies and (bar `--auto`) the human is still the clock.
+  who verifies and (bar `--auto`) the human is still the clock. See **§ Running bound
+  agents** for the mechanics.
 - **A refused checkpoint is the pause, not an error.** Under plumbbob's turn
-  hook a same-turn `checkpoint` is refused by design — present the diff, **end the
-  turn**, and the human's next message is the tick that lands it on re-fire. Never route
-  around it with a raw `git commit`; `--auto`, a typed range, or `auto: true` are the
-  only self-approvals.
-- **Close with the next model.** When a step lands, cite the completed step and the next
-  undone step, and name that next step's `- model:` recommendation if it has one — it's
-  what a fresh context window needs to pick the right `/model` before re-firing.
-  Guidance, never a gate.
+  hook a same-turn `checkpoint` is refused by design — present the diff and the closing
+  block, **end the turn**; the human's approval on their next turn is what lets you land
+  it, and landing it is a deliberate beat, not a side effect of the next `/pb-build`.
+  Never route around it with a raw `git commit`. An explicit `/pb-build --auto` or a typed
+  step range in the human's own prompt are the only self-approvals — **never write `auto`
+  into a settings file yourself to unlock a checkpoint. A grant you mint is no grant (the
+  latch ignores it since D67); ask the human to re-fire `/pb-build --auto` instead.**
+- **Close with the next model.** When a step lands, run `plumbbob handoff` and relay its
+  block — it cites the completed step and the next undone step, and names that next step's
+  `- model:` recommendation if it has one, which is what a fresh context window needs to
+  pick the right `/model` before re-firing. Guidance, never a gate.

package/skills/pb-doctor/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(plumbbob doctor:*)
 
 # PlumbBob — doctor (the is-it-installed-right move)
 
-Install diagnostic (injected when this skill runs): !`if command -v plumbbob >/dev/null 2>&1; then plumbbob doctor 2>&1; else echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."; fi`
+Install diagnostic (injected when this skill runs): !`plumbbob doctor 2>&1 || true`
 
 This is a **thin driver** for `plumbbob doctor`. The report above is read-only — `doctor`
 inspects, it never writes. This skill carries **no Edit and no Write tool**: never edit a file
@@ -34,6 +34,10 @@ and if you are reading this, that is not your situation.
 ## What it does
 
 1. Surface the injected `doctor` report verbatim — every `✓` and any `✗` with its `→ fix`.
+   If nothing rendered above (a few headless `-p` sessions skip the injection), just run
+   `plumbbob doctor` yourself — it is in your tools — and surface that.
 2. If all checks passed, say so; if a skill still misbehaves, the fix is a restart, not a re-run.
 3. If a check failed, apply its named `→ fix`, then restart Claude Code (or `/reload-plugins`).
-4. If the line above says the CLI is not on PATH, follow the install-path branch it printed.
+4. If the report is empty or shows `command not found`, the CLI is not on PATH: for a
+   skills-dir / global install run `npm i -g plumbbob && plumbbob init`; for a marketplace
+   install, confirm the plugin is enabled in `/plugin`, then `/reload-plugins`.

package/skills/pb-park/SKILL.md

@@ -38,4 +38,7 @@ later. Then:
 The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and
 no Write tool** on purpose: you may not append to `build-log.md` yourself. Compose, get
 approval, then shell `plumbbob park` — that is the only write path. If approval
-never comes, capture nothing.
+never comes, capture nothing. (When the human's **own message** states the idea — a
+tangent they raise mid-build — that message **is** the approval: capture it directly
+with `plumbbob park`, don't ask again. Deferring in words without the CLI line captures
+nothing.)

package/skills/pb-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pb-plan
-description: "Frame a fresh goal and author the whole plan — Frame, Decisions, Constraints, and all Steps — before any code. Three input modes: no arg interviews you; a file path absorbs a spec; any other text expands your inline intent."
+description: "Frame a fresh goal and author the whole plan — Frame, Decisions, Constraints, and all Steps — before any code. Three input modes: no arg interviews you; a file path (or @-mention) absorbs a spec; any other text expands your inline intent."
 argument-hint: "[spec-path | intent]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent list:*)
@@ -27,11 +27,15 @@ Look at the argument the human gave and pick the mode yourself:
 
 1. **No argument → interview.** Walk the human through a short, friendly Q&A to draw
    the plan out of their head (see *The interview* below).
-2. **The argument is a path to a file that exists → absorb the spec.** Read that file
-   and distill it into `intent.md`, **retaining enough detail that `intent.md` stands
-   on its own** — don't just link to the source. Add a one-line provenance
-   (`*Source: <path>*`) and, for anything sizable, a `## Source` appendix preserving
-   the original text. (Probe with the `Read` tool; if it isn't a real file, fall to
+2. **The argument points at a file → absorb the spec.** A bare path, an `@spec.md`
+   mention, or a path wrapped in a sentence all count. Strip any leading `@` and probe
+   the token with the `Read` tool; if Claude Code has already injected the referenced
+   file's contents into your context, treat that as the spec rather than re-fetching.
+   Read the spec and distill it into `intent.md`, **retaining enough detail that
+   `intent.md` stands on its own** — don't just link to the source. Add a one-line
+   provenance (`*Source: <path>*`) and, for anything sizable, a `## Source` appendix
+   preserving the original text. Any prose wrapped around the reference (e.g. "absorb
+   @spec.md") is extra intent — fold it in. (If the token isn't a real file, fall to
    mode 3.)
 3. **Any other text → expand the inline intent.** Treat the text as the human's
    rough plan, expand it into the full `intent.md`, and ask only about what is

package/skills/pb-verify/SKILL.md

@@ -2,7 +2,7 @@
 name: pb-verify
 description: "The verify tick — run the check, self-review the diff against intent, validate the step's done-when, pause for your approval, then checkpoint. Executor-agnostic: it reads the diff, not who wrote it."
 disable-model-invocation: true
-allowed-tools: Read, Bash(plumbbob status:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*), Bash(git status:*)
+allowed-tools: Read, Bash(plumbbob status:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*), Bash(git status:*)
 ---
 
 # PlumbBob — verify a step (the tick)
@@ -63,15 +63,14 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    (done-when + seam + diffstat) on its own. Either way, do **not** bump the version or
    touch the changelog — that is the human's `/version` call.
 7. **Hand off with the next model** *(once the checkpoint lands)*. `plumbbob checkpoint`
-   prints `step N checkpointed … Back at the boundary` and returns to DESIGN. Close the
-   turn by citing where the loop now stands: the step you just completed and the **next
-   undone step** — its title and done-when. If that next step carries a `- model:`
-   recommendation (the plan's smallest-model-that-fits call, which `plumbbob status`
-   echoes on the `▸ next` line), **name it in the hand-off** so the human knows which
-   `/model` to select before firing `/pb-build` again. This matters most across a context
-   boundary: a fresh window inherits the *session's* model, not the plan's suggestion, so
-   this line is what carries the recommendation over. No `- model:` line means any model
-   will do — say nothing about it. Guidance, never a gate.
+   returns to DESIGN; then run `plumbbob handoff` and relay its boundary block. With the
+   step gone from in-flight it renders `step N checkpointed — back at the boundary` and
+   points at the **next undone step**, carrying that step's `- model:` recommendation (the
+   plan's smallest-model-that-fits call) so the human knows which `/model` to select before
+   firing `/pb-build` again. This matters most across a context boundary: a fresh window
+   inherits the *session's* model, not the plan's suggestion, so this line is what carries
+   the recommendation over. The CLI owns the block, so it can't drift from what `plumbbob
+   status` reports; no `- model:` line means any model will do. Guidance, never a gate.
 
 ## The latch makes the pause real
 
@@ -84,8 +83,9 @@ the checkpoint land when you re-fire. **Never reach for a raw `git commit` to fo
 land** — that forges the very record the latch exists to keep honest, and the
 commit-ask hook asks the human about it anyway. The refusal is a healthy latch doing its
 job on the *record* while the *work* plane stays free; a `/pb-build --auto` or
-a typed step range in the human's own prompt is the only self-approval, and `auto: true`
-in settings is the standing one.
+a typed step range in the human's own prompt is the only self-approval — **never write
+`auto` into a settings file to unlock the land; the latch ignores a model-minted grant
+(D67), so ask the human to re-fire `/pb-build --auto` instead.**
 
 ## The hard contracts
 
@@ -104,7 +104,7 @@ in settings is the standing one.
   hook a same-turn checkpoint is refused *by design* — present the diff, **end the
   turn**, and let the human's next message re-tick it. Never route around it with a raw
   `git commit`; the latch guards the record, not the work.
-- **Close with the next model.** After the checkpoint lands, cite the completed step
-  and the next undone step, and surface that next step's `- model:` recommendation when
-  it has one — it is the plan's smallest-model-that-fits call, and it's what a fresh
-  context window needs to pick the right `/model`. Guidance, never a gate.
+- **Close with the next model.** After the checkpoint lands, run `plumbbob handoff` and
+  relay its block — it cites the completed step and the next undone step, and surfaces that
+  next step's `- model:` recommendation when it has one, which is what a fresh context
+  window needs to pick the right `/model`. Guidance, never a gate.