plumbbob 0.8.3 → 0.8.5

package/.claude-plugin/plugin.json

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

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.8.3",
+  "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,24 +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.** 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 +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
@@ -118,9 +149,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.
@@ -161,13 +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.
+  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`; `--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-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
 
@@ -104,7 +103,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.