plumbbob 0.8.0 → 0.8.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.0",
+  "version": "0.8.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/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

@@ -10,15 +10,17 @@ 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 grants self-approval;
+\`auto: true\` in settings.local.json is the standing grant.)
 `;
 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

package/dist/lib/settings.js

@@ -9,9 +9,9 @@
 //
 // 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). `activeBuild` (the
-// per-worktree cursor) also lives in settings.local.json but is resolved by
-// sidecar.ts, not here.
+// 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.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 const DIRNAME = '.plumbbob';
@@ -70,12 +70,6 @@ export function resolveRecord(root, key) {
     const value = resolveSetting(root, key, undefined);
     return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
 }
-// Read one key from the untracked local overlay ONLY — no project or built-in
-// fallback. The `activeBuild` cursor lives here and must never resolve from the
-// tracked settings.json (it is per-worktree state, not a shared default).
-export function localSetting(root, key) {
-    return readSettings(localSettingsPath(root))[key];
-}
 // Merge one key into settings.local.json, preserving the other keys and creating
 // the file when absent. Pretty-printed so the overlay stays hand-editable. A
 // malformed existing file contributes nothing (readSettings yields {}) and is

package/dist/lib/sidecar.js

@@ -2,14 +2,18 @@
 // read it with a grep and no markdown parsing (D7). Functional/procedural,
 // node builtins only (C1/C2).
 //
-// STATE is a pure session sentinel: its EXISTENCE means "a session is active",
-// and nothing reads its content. The phase the dashboard shows (DESIGN/BUILD/
-// SPIKE) is derived, not stored — BUILD ⇔ a STEP is in flight, SPIKE ⇔ the SPIKE
-// marker is present, otherwise DESIGN.
+// STATE is the session sentinel AND the active-build cursor (D28): its EXISTENCE
+// means "a session is active", and its CONTENT names the build that session is on —
+// the two reinforce each other (a session is always on some build; the cursor is
+// meaningless without a session). Content is empty under --local / no build.
+// hasSession stays existence-only; activeBuild reads the content. Homing the cursor
+// here — not in settings.local.json — keeps that overlay purely human-owned
+// (check/auto): the tool only ever reads it, never rewrites it. The phase the
+// dashboard shows (DESIGN/BUILD/SPIKE) is derived, not stored — BUILD ⇔ a STEP is
+// in flight, SPIKE ⇔ the SPIKE marker is present, otherwise DESIGN.
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { gitPath } from "./git.js";
-import { localSetting } from "./settings.js";
 const DIRNAME = '.plumbbob';
 export function sidecarDir(root) {
     return join(root, DIRNAME);
@@ -50,19 +54,35 @@ export function listBuilds(root) {
     }
 }
 // Resolve which build a verb acts on (D28): an explicit `--build <slug>` flag →
-// the `activeBuild` cursor in settings.local.json → the sole build in `builds/`
-// → null (the caller then refuses with a hint). One-active-per-worktree holds by
-// construction: the cursor is a single scalar key in an untracked file, so it can
-// never point at two builds (D28).
+// the cursor in STATE → the sole build in `builds/` → null (the caller then refuses
+// with a hint). One-active-per-worktree holds by construction: the cursor is STATE's
+// single-line content, so it can never point at two builds (D28).
 export function activeBuild(root, flag) {
     if (flag !== undefined && flag.length > 0)
         return flag;
-    const cursor = localSetting(root, 'activeBuild');
-    if (typeof cursor === 'string' && cursor.length > 0)
+    const cursor = readCursor(root);
+    if (cursor !== null)
         return cursor;
     const builds = listBuilds(root);
     return builds.length === 1 ? (builds[0] ?? null) : null;
 }
+// STATE's content is the active-build cursor. Empty means "no build" (--local, or a
+// session whose cursor is unset) → null, so activeBuild falls through to the
+// sole-build rule. A pre-STATE-cursor session wrote the literal `active` sentinel
+// here (the cursor lived in settings.local.json then); treat that legacy value as
+// unset so an in-flight upgrade degrades gracefully instead of chasing a build named
+// "active". `active` is thus reserved and never a valid cursor — no derived slug
+// collides (they carry a YYYY-MM-DD- prefix).
+function readCursor(root) {
+    let content;
+    try {
+        content = readFileSync(statePath(root), 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+    return content.length > 0 && content !== 'active' ? content : null;
+}
 // The build a verb should act on, plus its argv with the `--build <slug>` pair
 // stripped (D28). Every verb resolves through this: an explicit `--build <slug>`
 // wins, else the cursor / sole-build fallback of `activeBuild`. `rest` matters
@@ -197,12 +217,26 @@ function patchStepStat(root, slug, step, patch) {
 }
 // A session exists iff STATE exists. Deleting STATE (at finish) is what flips the
 // repo back to "no session" — so it is the single source of truth for "is there
-// a session". `start` calls beginSession; `finish` removes the file.
+// a session". `start` calls beginSession; `finish` removes the file. Existence is
+// the whole session signal; STATE's content is a separate axis (the cursor).
 export function hasSession(root) {
     return existsSync(statePath(root));
 }
-export function beginSession(root) {
-    writeFileSync(statePath(root), 'active\n');
+// Open the session and point its cursor at `slug` — null under --local / no build,
+// which leaves STATE present but empty so activeBuild falls through to the sole-build
+// rule. `finish` removes the file, closing the session and clearing the cursor in
+// one delete.
+export function beginSession(root, slug = null) {
+    writeCursor(root, slug);
+}
+// Re-point the cursor at an existing build (`use`) — a plain content rewrite that
+// leaves the session sentinel (STATE's existence) intact. Callers guard hasSession
+// first, so this never resurrects a finished session.
+export function setActiveBuild(root, slug) {
+    writeCursor(root, slug);
+}
+function writeCursor(root, slug) {
+    writeFileSync(statePath(root), slug === null ? '' : `${slug}\n`);
 }
 // SPIKE marker helpers — existence is the whole signal (content is irrelevant).
 export function inSpike(root, slug) {
@@ -309,10 +343,11 @@ function addExcludes(root, patterns) {
     appendFileSync(exclude, `${prefix}${missing.join('\n')}\n`);
 }
 // The narrowed control plane (D17): with `builds/<slug>/` now tracked, only the
-// per-worktree control files stay git-excluded — the local settings overlay (its
-// `activeBuild` cursor), the session sentinel, and the in-flight step markers
-// inside every build. Everything else under `.plumbbob/` (settings.json, and each
-// build's intent/build-log/checkpoints/report) rides the branch into the PR.
+// per-worktree control files stay git-excluded — the session sentinel STATE (whose
+// content is the active-build cursor, D28), the personal settings overlay, and the
+// in-flight step markers inside every build. Everything else under `.plumbbob/`
+// (settings.json, and each build's intent/build-log/checkpoints/report) rides the
+// branch into the PR.
 export function excludeControl(root) {
     addExcludes(root, [
         `${DIRNAME}/STATE`,

package/dist/verbs/agent.js

@@ -101,6 +101,11 @@ async function runOne(root, slug, step, spec) {
         settings: {
             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

@@ -31,8 +31,8 @@ import { listAgents } from "../lib/agents.js";
 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, sidecarDir, slugify } from "../lib/sidecar.js";
-import { resolveString, settingsPath, setLocalSetting } from "../lib/settings.js";
+import { buildDir, excludeControl, listBuilds, readTurn, setActiveBuild, sidecarDir, slugify } from "../lib/sidecar.js";
+import { 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) {
@@ -206,8 +206,12 @@ export function migrateSidecar(root) {
     const configPath = join(dir, 'config');
     if (existsSync(configPath)) {
         if (!existsSync(settingsPath(root))) {
+            // Carry forward ONLY what the legacy config actually held — a `check` line,
+            // nothing else. No invented `auto` (the config never had one, it defaults to
+            // false, and it belongs in settings.local.json): migration yields exactly what
+            // a fresh `start` would, plus the check. An empty config → an empty `{}`.
             const check = configCheck(configPath);
-            const settings = check === null ? { auto: false } : { check, auto: false };
+            const settings = check === null ? {} : { check };
             writeFileSync(settingsPath(root), `${JSON.stringify(settings, null, 2)}\n`);
             actions.push(check === null ? 'config → settings.json' : `config → settings.json (check: ${check})`);
         }
@@ -220,7 +224,7 @@ export function migrateSidecar(root) {
         const slug = uniqueSlug(slugify(titleFromIntent(flatIntent)), taken);
         taken.add(slug);
         moveInto(dir, buildDir(root, slug), ['intent.md', 'build-log.md', 'checkpoints', 'STEP', 'SEAM', 'SPIKE']);
-        setLocalSetting(root, 'activeBuild', slug);
+        setActiveBuild(root, slug);
         actions.push(`active session → builds/${slug} (the cursor)`);
     }
     // archive/<slug> → builds/<slug>. These are "done" by simply not being the cursor.

package/dist/verbs/finish.js

@@ -9,7 +9,6 @@ import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
 import { checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
-import { setLocalSetting } from "../lib/settings.js";
 import { parseTitle } from "../lib/orient.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
@@ -35,9 +34,10 @@ export function finish(cwd, args = []) {
         stageAll(root);
     }
     const sha = commit(root, subject(root, slug), bodyArg(args) ?? undefined);
-    // Clear the control state: the in-flight markers, the per-worktree cursor (D28),
-    // and the session sentinel (STATE last, so "no session" flips exactly at the end).
-    // The tracked artifacts stay in place — only the ephemera go.
+    // Clear the control state: the in-flight markers first, then the session sentinel
+    // last (so "no session" flips exactly at the end). Deleting STATE also drops the
+    // cursor (D28) — cursor and session share the one file now, so a single delete does
+    // both. The tracked artifacts stay in place — only the ephemera go.
     rmSync(seamPath(root, slug), { force: true });
     rmSync(stepPath(root, slug), { force: true });
     rmSync(spikePath(root, slug), { force: true });
@@ -47,12 +47,6 @@ export function finish(cwd, args = []) {
     // the next session's first landing.
     clearTick(root, slug);
     setGrant(root, null);
-    if (slug !== null) {
-        // Drop the activeBuild key — JSON.stringify omits an `undefined` value, so the
-        // cursor is removed while the other local settings (auto, …) survive. Skipped
-        // under `--local`, where there is no cursor to clear.
-        setLocalSetting(root, 'activeBuild', undefined);
-    }
     rmSync(join(sidecarDir(root), 'STATE'), { force: true });
     const where = slug === null ? '.plumbbob/' : `.plumbbob/builds/${slug}/`;
     process.stdout.write(`plumbbob: finished — ${sha.slice(0, 9)}. ${where} rides your branch into the PR. ` +

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/start.js

@@ -1,12 +1,12 @@
 // `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, open
 // the session. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
 import { fileURLToPath } from 'node:url';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { detectGate } from "../lib/check.js";
 import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
 import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
-import { settingsPath, setLocalSetting } from "../lib/settings.js";
+import { settingsPath } from "../lib/settings.js";
 // D24/D32: the gate is checkride unless a `check` setting overrides it, so
 // settings.json seeds with no `check` key at all — absence IS the default. The
 // templates' {{CHECK}} line is a human-readable echo of that.
@@ -51,8 +51,20 @@ export async function start(cwd, args) {
     }
     const sha = headSha(root);
     mkdirSync(sidecarDir(root), { recursive: true });
-    beginSession(root);
-    writeFileSync(settingsPath(root), `${JSON.stringify({ auto: false }, null, 2)}\n`);
+    // beginSession writes STATE — the session sentinel and, in its content, the cursor
+    // (D28). Point it at this build (null under --local, which has no cursor). The
+    // cursor lives in STATE, not settings.local.json, so that overlay stays human-owned.
+    beginSession(root, local ? null : slug);
+    // Scaffold the tracked settings.json ONLY when absent, and seed it EMPTY — the
+    // human owns this file once it exists (their `check` gate lives here), so a
+    // re-start must never touch it. We inject no opinions even on first create:
+    // absence of `check` already means checkride and absence of `auto` already means
+    // false (see settings.ts), so `{}` is exactly "all defaults". `auto` in
+    // particular is a personal preference that belongs in settings.local.json, not
+    // this tracked file — seeding it here was the bug that clobbered custom checks.
+    if (!existsSync(settingsPath(root))) {
+        writeFileSync(settingsPath(root), `${JSON.stringify({}, null, 2)}\n`);
+    }
     // D26: `--local` keeps today's fully-untracked flat layout (whole `.plumbbob/`
     // excluded); the default plants a tracked, PR-riding `builds/<slug>/` folder
     // (D26) and points the per-worktree cursor at it (D28), excluding only control
@@ -72,7 +84,6 @@ export async function start(cwd, args) {
         writeFileSync(join(dir, 'checkpoints'), `baseline ${sha}\n`);
         writeFileSync(join(dir, 'intent.md'), stamp(readTemplate('intent.md'), title, CHECK_ECHO));
         writeFileSync(join(dir, 'build-log.md'), stamp(readTemplate('build-log.md'), title, CHECK_ECHO));
-        setLocalSetting(root, 'activeBuild', slug);
         excludeControl(root);
         intentLocation = `.plumbbob/builds/${slug}/intent.md`;
     }

package/dist/verbs/use.js

@@ -1,14 +1,13 @@
 // `plumbbob use <slug>` (D30) — re-point the per-worktree cursor at an existing
 // build and resume it. Both switching and resuming are the same one word (Q10,
-// `nvm use`-shaped): the cursor is a single scalar key in settings.local.json, so
-// pointing it elsewhere IS the switch and one-active-per-worktree holds by
+// `nvm use`-shaped): the cursor is STATE's single-line content, so pointing it
+// elsewhere IS the switch and one-active-per-worktree holds by
 // construction (D28). It validates the target folder exists, and warns — but
 // allows — leaving a build with a step in flight: that surviving in-flight state
 // is D26's whole payoff, resumed the next time you `use` that build.
 import { existsSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { activeBuild, hasSession, intentPath, listBuilds, stepPath } from "../lib/sidecar.js";
-import { setLocalSetting } from "../lib/settings.js";
+import { activeBuild, hasSession, intentPath, listBuilds, setActiveBuild, stepPath } from "../lib/sidecar.js";
 export function use(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -32,7 +31,7 @@ export function use(cwd, args) {
         process.stderr.write(`plumbbob: note — build "${leaving}" has a step in flight; its in-flight state is preserved ` +
             `and resumes when you \`use ${leaving}\` again.\n`);
     }
-    setLocalSetting(root, 'activeBuild', target);
+    setActiveBuild(root, target);
     const resuming = existsSync(stepPath(root, target)) ? ' (a step is in flight — `status` shows where)' : '';
     process.stdout.write(`plumbbob: now on build "${target}"${resuming}. \`status\` to orient.\n`);
     return 0;

package/hooks/post-edit.sh

@@ -5,16 +5,16 @@
 # the tools are absent or there is no session. tsc is deferred to the heavy tier
 # (D25): it has no true single-file mode and would tax every keystroke.
 
-# The repo root is the nearest ancestor whose .plumbbob/settings.local.json carries
-# an `activeBuild` cursor — the per-worktree signal that a tracked build is live
-# here (D28). Grep the same way the file_path read below does: a plain pattern
-# match, no JSON parse. The cursor replaces the old .plumbbob/STATE probe as the
-# "a build is active here" root marker.
+# The repo root is the nearest ancestor whose .plumbbob/STATE is NON-EMPTY — the
+# per-worktree signal that a tracked build is live here (D28). STATE's existence
+# means "a session is active"; its content is the active-build cursor, so a non-empty
+# STATE is exactly "a tracked build is live" (the `--local` layout leaves STATE empty,
+# and this file-scoped check is a tracked-build affordance). `-s` tests both existence
+# and non-emptiness — no JSON parse, no cursor file to read.
 find_root() {
   d=$(pwd -P)
   while [ -n "$d" ]; do
-    if [ -f "$d/.plumbbob/settings.local.json" ] &&
-      grep -q '"activeBuild"' "$d/.plumbbob/settings.local.json" 2>/dev/null; then
+    if [ -s "$d/.plumbbob/STATE" ]; then
       printf '%s' "$d"
       return 0
     fi

package/hooks/pre-bash-commit.sh

@@ -8,8 +8,8 @@
 
 # The repo root is the nearest ancestor with an active session — `.plumbbob/STATE`,
 # the sentinel `start` writes and `finish` removes. Present in both the tracked and
-# the `--local` layout (the activeBuild cursor post-edit.sh probes exists only in
-# the tracked one, and this hook must guard `--local` steps too).
+# the `--local` layout (post-edit.sh only fires when STATE is non-empty, i.e. a
+# tracked build; this hook must guard `--local` steps too, so it probes existence).
 find_root() {
   d=$(pwd -P)
   while [ -n "$d" ]; do
@@ -26,12 +26,11 @@ find_root() {
 root=$(find_root) || exit 0 # no active session here: nothing to guard
 
 # The in-flight signal is STEP (cleared when the step checkpoints): inside the
-# active build's folder when the cursor names one, else the flat sidecar STEP of
-# the `--local` layout. jq if present, else the same sed fallback post-edit.sh
-# uses for its field read.
-settings="$root/.plumbbob/settings.local.json"
-slug=$(jq -r '.activeBuild // empty' "$settings" 2>/dev/null)
-[ -z "$slug" ] && slug=$(sed -n 's/.*"activeBuild"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$settings" 2>/dev/null | head -n1)
+# active build's folder when STATE names one, else the flat sidecar STEP of the
+# `--local` layout. STATE's content IS the cursor (D28) — read the first line, trim
+# whitespace, and treat the legacy `active` sentinel (pre-STATE-cursor) as no cursor.
+slug=$(head -n1 "$root/.plumbbob/STATE" 2>/dev/null | tr -d '[:space:]')
+[ "$slug" = "active" ] && slug=""
 if [ -n "$slug" ]; then
   step_file="$root/.plumbbob/builds/$slug/STEP"
 else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.8.0",
+  "version": "0.8.5",
   "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",
@@ -42,17 +42,17 @@
     }
   },
   "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"

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 agent:*), Bash(git diff:*)
 ---
 
 # PlumbBob — build a step (the default engine)
@@ -30,51 +30,33 @@ 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.
+   - **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,15 +64,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 (D64).** On the default (non-`--auto`) path you
+   **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 (D10/D13),
-   but the *record* is latched on purpose.
+   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)
 
@@ -98,8 +138,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
@@ -108,7 +148,11 @@ and approves in the human's place**, and it **chains**:
   the self-review finds a mismatch (surface exactly what, and do not checkpoint it), a
   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.
+  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** — 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.
@@ -149,9 +193,15 @@ 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.
-- **A refused checkpoint is the pause, not an error (D64).** 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.
+  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 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`; `--auto`, a typed range, or `auto: true`
+  are the only self-approvals.
+- **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-finish/SKILL.md

@@ -31,7 +31,8 @@ record.
 2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
    report and makes the final commit — subject `plumbbob: finish — <title>`,
    with an optional proportional body via `--body` (the stdin heredoc) — then
-   clears the control state (markers, the `activeBuild` cursor, STATE last). The
+   clears the control state (the in-flight markers, then `STATE` last — one delete
+   drops both the session sentinel and the active-build cursor it carries). The
    build folder stays in place, committed, and rides the branch into the PR.
 3. **Point at the next goal** — `/pb-plan` to frame the next one.
 

package/skills/pb-plan/SKILL.md

@@ -107,7 +107,7 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    baseline → plan → steps. Pass a proportional `--body` (the single-quoted stdin
    heredoc) when the rationale is worth carrying; skip it for a small plan. Do this
    only on the human's approval — the plan is their convergence.
-   - **The plan commit is latched too (D64).** Once the turn ledger exists, `checkpoint
+   - **The plan commit is latched too.** Once the turn ledger exists, `checkpoint
      --plan` refuses to land in the same turn `start` stamped it: present the plan,
      **end the turn**, and the human's approving message is the tick that lets it
      commit on re-fire — the refusal *is* the plan pause. Never route around it with a

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)
@@ -62,8 +62,17 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    write in one breath. Omit `--body` entirely and the CLI writes a deterministic body
    (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`
+   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 (D64)
+## The latch makes the pause real
 
 When this session runs under plumbbob's turn hook, `plumbbob checkpoint` **refuses to
 land a step in the same turn it was entered** — and that refusal **is** this pause, not
@@ -73,7 +82,7 @@ the self-review, **end the turn**, and the human's next message is the tick that
 the checkpoint land when you re-fire. **Never reach for a raw `git commit` to force the
 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 (D10/D13); a `/pb-build --auto` or
+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.
 
@@ -90,7 +99,11 @@ in settings is the standing one.
 - **`after`-agents advise; they never gate**. Their output feeds the
   self-review — checkride gates, the human approves. `blocked` → unblock and re-run;
   `drift` → `/pb-refine` before checkpointing. No code path makes them blocking.
-- **A refused checkpoint is the pause, never a workaround (D64).** Under the turn
+- **A refused checkpoint is the pause, never a workaround.** Under the turn
   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, 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.