plumbbob 0.11.2 → 0.12.0

package/.claude-plugin/plugin.json

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

@@ -145,7 +145,7 @@ In Claude Code, inside any git repo with a clean tree:
    1. The bucket lives in memory, keyed by IP, refilling five tokens a minute.
    2. The clock is injected, so the test advances time instead of sleeping on it.
 
-   **Readout**: Step 1 - Add a token-bucket limiter
+   **Readout**: Step 1 - feat(limiter): add a token-bucket limiter
 
    ```text
    check        green: 7 of 7 checks
@@ -159,7 +159,7 @@ In Claude Code, inside any git repo with a clean tree:
 
    **Verdict**: ● Plumb
 
-   **Next Up**: Step 2 of 3 - Wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
+   **Next Up**: Step 2 of 3 - feat(login): wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
 
    **Your Call**:
 
@@ -186,7 +186,7 @@ In Claude Code, inside any git repo with a clean tree:
 
    **Verdict**: ● Plumb
 
-   **Next Up**: Step 2 of 3 - Wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
+   **Next Up**: Step 2 of 3 - feat(login): wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
    ```
 
    ![The boundary after looks good](docs/media/checkpoint-boundary.svg)
@@ -221,7 +221,7 @@ nothing else:
 | Skill <img alt="" width="110" height="1"> | Does |
 | ------------------------------------ | ------ |
 | `/plumbbob:plan` | plan the whole goal: open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
-| `/plumbbob:build` | implement the next planned step, then verify it to the pause: `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then pauses |
+| `/plumbbob:build` | implement the next planned step, then verify it to the pause: `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then stops |
 | `/plumbbob:finish` | finish up: write the report, make the final commit, clear for a fresh goal |
 
 **Plan-shaping moves**: optional, for when the plan needs work mid-flight:

package/dist/lib/git.js

@@ -5,6 +5,7 @@
 // `--hard` only to plumbbob's own recorded checkpoint SHAs: never a
 // history-rewriting operation on anything pushed.
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 /**
  * Run git in `root` and return its trimmed stdout.
@@ -95,16 +96,30 @@ export function commitsSince(root, sha, excluding) {
     }
 }
 /**
- * The working tree's changes against the index, one entry per file, as
- * `git diff --numstat` reports them; a binary file counts 0/0.
+ * The step's whole product, one entry per file: everything changed since HEAD,
+ * staged or not, plus every non-ignored untracked file counted as all-added
+ * lines.
+ *
+ * That universe is the one `checkpoint`'s drift warning already uses after it
+ * stages, so the pause and the boundary measure the same thing. `diff HEAD`
+ * (rather than a working-tree diff merged with a cached one) nets a file
+ * staged and then edited again into a single row; `--no-renames` keeps a
+ * staged `git mv` as two plain paths instead of one `{old => new}` arrow,
+ * which is also the shape the seam row wants.
  *
  * This feeds the recap's `diff` and `seam` rows at the pause: information,
  * never a gate, so it is best-effort and never throws ([] on any failure).
  */
 export function diffNumstat(root) {
+    return [...trackedNumstat(root), ...untrackedNumstat(root)];
+}
+/**
+ * The tracked half of `diffNumstat`: what differs from HEAD, index included.
+ */
+function trackedNumstat(root) {
     let out;
     try {
-        out = runGit(root, ['diff', '--numstat']);
+        out = runGit(root, ['diff', '--numstat', '--no-renames', 'HEAD']);
     }
     catch {
         return [];
@@ -114,9 +129,59 @@ export function diffNumstat(root) {
     }
     return out.split('\n').map((line) => {
         const [added, removed, ...path] = line.split('\t');
-        return { added: toCount(added), removed: toCount(removed), path: path.join('\t') };
+        return { added: toCount(added), removed: toCount(removed), path: path.join('\t'), untracked: false };
     });
 }
+/**
+ * The untracked half of `diffNumstat`: every non-ignored new file, counted as
+ * all-added lines.
+ *
+ * The count is read in node rather than spawned per file: the alternative
+ * (`git diff --no-index --numstat /dev/null <path>`) exits 1 by design and
+ * prints the path in rename shape, so it needs an exit-1 catch and an arrow
+ * parser for every file. The trade-off, accepted: gitattributes are not
+ * consulted for a file git has never seen.
+ */
+function untrackedNumstat(root) {
+    let paths;
+    try {
+        paths = untrackedPaths(root);
+    }
+    catch {
+        return [];
+    }
+    return paths.map((path) => ({ added: addedLines(join(root, path)), removed: 0, path, untracked: true }));
+}
+/**
+ * The line count a numstat row would carry for a whole new file: newlines, plus
+ * one for an unterminated last line, the way git counts it.
+ *
+ * A NUL byte in the first 8000 bytes means binary, which numstat prints as `-`
+ * and `toCount` reads as 0. An unreadable file counts 0 as well, and the caller
+ * keeps its path either way: the seam row still has to see it.
+ */
+function addedLines(absolute) {
+    let buffer;
+    try {
+        buffer = readFileSync(absolute);
+    }
+    catch {
+        return 0;
+    }
+    if (buffer.subarray(0, 8000).includes(0)) {
+        return 0;
+    }
+    if (buffer.length === 0) {
+        return 0;
+    }
+    let lines = 0;
+    for (const byte of buffer) {
+        if (byte === 0x0a) {
+            lines += 1;
+        }
+    }
+    return buffer[buffer.length - 1] === 0x0a ? lines : lines + 1;
+}
 /**
  * A numstat count field as a number: `-` (a binary file) and anything else
  * unparseable read as 0.
@@ -126,22 +191,54 @@ function toCount(field) {
     return Number.isFinite(n) && n >= 0 ? n : 0;
 }
 /**
- * The raw `git diff` patch for `paths` (working tree against the index), or ''
- * when nothing differs or git refuses.
+ * The raw patch for `entries` (everything since HEAD, new files included), or
+ * '' when nothing differs or git refuses.
+ *
+ * Tracked paths come through one `git diff HEAD`; an untracked file has no
+ * blob to diff, so each goes through `git diff --no-index` against /dev/null,
+ * which prints the same `new file mode` header a staged new file gets. That
+ * form implies `--exit-code`, so a patch arrives as a thrown status 1 with the
+ * text on `stdout`. Entries counted at 0 added lines are skipped: they would
+ * produce nothing, and skipping them caps the spawns at the inline threshold.
  *
  * Only the pause's inline-diff fence reads this, and only after the numstat
  * count came in at 20 changed lines or fewer, so the patch is always small.
  * Best-effort like diffNumstat: information, never a gate.
  */
-export function diffPatch(root, paths) {
-    if (paths.length === 0) {
-        return '';
+export function diffPatch(root, entries) {
+    const tracked = entries.filter((e) => !e.untracked).map((e) => e.path);
+    const pieces = [];
+    if (tracked.length > 0) {
+        try {
+            pieces.push(runGit(root, ['diff', '--no-renames', 'HEAD', '--', ...tracked]));
+        }
+        catch {
+            // best-effort: a path git refuses drops out of the fence, the rest stays.
+        }
+    }
+    for (const entry of entries) {
+        if (!entry.untracked || entry.added === 0) {
+            continue;
+        }
+        pieces.push(noIndexPatch(root, entry.path));
     }
+    return pieces.filter((piece) => piece.length > 0).join('\n');
+}
+/**
+ * One untracked file's patch, `git diff --no-index` against /dev/null.
+ *
+ * The path stays repo-relative so the header reads `+++ b/src/new.ts`, the same
+ * shape `diff HEAD` prints for a staged new file. `--no-index` implies
+ * `--exit-code`: status 1 is the success case, and `encoding` is set on the
+ * spawn, so git's output arrives as a string on the error.
+ */
+function noIndexPatch(root, path) {
     try {
-        return runGit(root, ['diff', '--', ...paths]);
+        return runGit(root, ['diff', '--no-index', '--', '/dev/null', path]);
     }
-    catch {
-        return '';
+    catch (error) {
+        const failure = error;
+        return failure.status === 1 && typeof failure.stdout === 'string' ? failure.stdout.trim() : '';
     }
 }
 // --- mutation helpers (build-loop: done checkpoints, revert resets). Additive

package/dist/lib/latch.js

@@ -112,7 +112,7 @@ export function checkLatch(root, step) {
 /**
  * The current GRANT, or null when the file is absent or unparseable.
  */
-function readGrant(root) {
+export function readGrant(root) {
     try {
         return parseGrant(readFileSync(grantPath(root), 'utf8'));
     }

package/dist/lib/orient.js

@@ -741,6 +741,16 @@ export function parseSections(detail) {
 export function parseRecommendation(detail) {
     return sectionProse(detail, /^##\s+recommendation\s*$/i);
 }
+/**
+ * The step `.plumbbob/detail.md` was written for, read off its
+ * `# Detail · Step <n> · <title>` header, or null when the first line is not a
+ * step header (a plan pause's detail, or a file the model wrote without one).
+ */
+export function parseDetailStep(detail) {
+    const first = detail.trimStart().split('\n', 1)[0] ?? '';
+    const m = /^#\s+Detail\b.*?\bStep\s+(\d+)\b/.exec(first);
+    return m === null ? null : Number(m[1]);
+}
 /**
  * Render an Orientation as the plain-text dashboard `status` prints.
  */

package/dist/verbs/build.js

@@ -10,14 +10,16 @@ import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTic
 import { parseStepSeam } from "../lib/intent.js";
 import { parseSteps } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
+import { readGrant } from "../lib/latch.js";
 import { notice } from "../lib/notice.js";
 /**
  * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
  * Refuses a missing session, a malformed step argument, an `N-M` range (a
  * `/plumbbob:build` skill feature, not a CLI one), and a seam that fails to parse.
- * On entry it stamps the turn ledger and the step's start time, and re-renders
- * the build-log's Current step line.
+ * On entry it stamps the turn ledger and the step's start time, re-renders the
+ * build-log's Current step line, and says so when the step is the top of a
+ * range the human typed.
  */
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -28,12 +30,13 @@ export function build(cwd, args) {
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
     // A step range like `1-3` is a `/plumbbob:build` skill affordance (auto-approve
-    // through the range, then pause), not a CLI capability: the CLI records one
-    // in-flight step at a time. Name it rather than bounce off the generic usage.
+    // every step through the range's top, then stop), not a CLI capability: the CLI
+    // records one in-flight step at a time. Name it rather than bounce off the
+    // generic usage.
     if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
         process.stderr.write(notice({
             fact: 'build takes one step number',
-            detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through it and then pauses`],
+            detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through its top and then stops`],
             remedy: `plumbbob build ${raw.split('-')[0]}`,
         }));
         return 1;
@@ -94,9 +97,22 @@ export function build(cwd, args) {
         : skipped > 0
             ? ['explicitly requested', `skips ${skipped} undone step${skipped === 1 ? '' : 's'}`]
             : [];
-    // Two lines, one colon each, then the seam as a plain readout beneath the
-    // notice that frames it: the paths are a list, and a list is not a one-liner.
+    // The top step of a typed range lands like every step under it, and the turn
+    // ends on its checkpoint. Saying so as the step is entered puts that fact in
+    // front of the model before it chooses between landing the step and holding
+    // it at a pause, which is the choice a range kept getting wrong.
+    const grant = readGrant(root);
+    const top = grant?.kind === 'range' && grant.ceiling === step
+        ? notice({
+            fact: `step ${step} is the top of the range you granted`,
+            remedy: 'land it on green, then stop at the boundary',
+        })
+        : '';
+    // Two lines (three at a range's top), one colon each, then the seam as a
+    // plain readout beneath the notice that frames it: the paths are a list, and
+    // a list is not a one-liner.
     process.stdout.write(notice({ fact: `building step ${step}`, detail: picked }) +
+        top +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],

package/dist/verbs/checkpoint.js

@@ -16,7 +16,7 @@ import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, check
 import { runCheck } from "../lib/check.js";
 import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
-import { markStepDone, parseSteps } from "../lib/orient.js";
+import { markStepDone, parseDetailStep, parseSteps } from "../lib/orient.js";
 import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
@@ -81,13 +81,13 @@ export async function checkpoint(cwd, args) {
             : notice({ fact: 'checkpoint refused', detail: ['the check is red'], remedy: 'fix it, then run it again' }));
         return 1;
     }
-    // The step's record, as the pause showed it: measured now, before the work
-    // is staged, since the seam and diff rows read the working tree the way the
-    // pause did. It lands in the build-log's Log beneath the dated line (the
+    // The step's record, as the pause showed it: built here, before the work is
+    // staged, though both measures now run against HEAD, so staging no longer
+    // moves them. It lands in the build-log's Log beneath the dated line (the
     // tracked ledger is the archive, and it rides the branch where a commit body
     // would not survive the squash); the commit body keeps its marker and the
     // lead prose only.
-    const record = stepRecord(root, activeBuild(root), step, readDetail(root) ?? '');
+    const record = stepRecord(root, activeBuild(root), step, readDetail(root, step) ?? '');
     let sha;
     // The drift advisory is read off the index (staged, before the commit clears
     // it) but printed inside the ending below, where the fixed order puts it: the
@@ -165,7 +165,7 @@ function checkpointPlan(root, args) {
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
     // The cold read that approved the plan is the Log's first entry, beneath a
     // dated plan line; the detail file is then spent, the same as at a step.
-    const pointer = logPlan(root, sha, planRecord(readDetail(root) ?? ''));
+    const pointer = logPlan(root, sha, planRecord(readDetail(root, null) ?? ''));
     clearDetail(root);
     // Landing the plan consumes `start`'s entry stamp: a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
@@ -444,16 +444,23 @@ function fallbackBody(root, step) {
 }
 /**
  * The in-flight step's detail from `.plumbbob/detail.md`, or null when the file
- * is absent or empty.
+ * is absent, empty, or written for another step.
  *
  * The model overwrites it before every pause; checkpoint reads it once here for
  * the Log's record, and the caller clears it afterward. A missing or blank file
- * records nothing.
+ * records nothing, and so does one whose header names a different step: that
+ * file is a leftover, written after its own step had already landed, and
+ * recording it would file one step's story under another. The plan commit
+ * passes no step and takes the file as it is.
  */
-function readDetail(root) {
+function readDetail(root, step) {
     try {
         const raw = readFileSync(detailPath(root), 'utf8').trim();
-        return raw.length > 0 ? raw : null;
+        if (raw.length === 0) {
+            return null;
+        }
+        const written = step === null ? null : parseDetailStep(raw);
+        return written === null || written === step ? raw : null;
     }
     catch {
         return null;

package/dist/verbs/handoff.js

@@ -15,12 +15,12 @@
 // it cannot narrate into.
 //
 // If the CLI can compute a recap row, the CLI does: the check row comes from
-// the last run's summary, the seam row from the SEAM marker against the
-// work-plane diff, the diff row from `git diff --numstat`. The model's part
-// (`.plumbbob/detail.md`) supplies only what takes judgment: the Summary, the
-// three judgment rows, and the recommendation; the Verdict folds the same
-// assembled rows worst-of with the step's accrued stats, so the fence shows
-// exactly what the fold saw.
+// the last run's summary, the seam and diff rows from the SEAM marker against
+// the step's whole product (everything changed since HEAD, staged or not, plus
+// each non-ignored new file). The model's part (`.plumbbob/detail.md`) supplies
+// only what takes judgment: the Summary, the three judgment rows, and the
+// recommendation; the Verdict folds the same assembled rows worst-of with the
+// step's accrued stats, so the fence shows exactly what the fold saw.
 //
 // Every tier's ending is emitted here, so no skill has to fake the furniture in
 // prose: `--plan` renders the plan-pause ending and `--driver` the driver
@@ -133,7 +133,11 @@ export function handoff(cwd, args = []) {
     const verdict = verdictLine(ladder, worst);
     const counts = countDiff(work);
     const changed = counts.added + counts.removed;
-    const inline = changed > 0 && changed <= INLINE_DIFF_MAX;
+    // The patch comes first so `· inline below` is a promise the fence keeps: a
+    // small change git can still print nothing for (a vanished path) falls back
+    // to the bare counts rather than pointing at a fence that never arrives.
+    const patch = changed > 0 && changed <= INLINE_DIFF_MAX ? diffPatch(root, work) : '';
+    const inline = patch.length > 0;
     const readout = recapLines(rows, {
         diff: diffRowValue(counts, inline),
         spent: spentRowValue(spentInputs(root, slug, current, summary)),
@@ -144,10 +148,7 @@ export function handoff(cwd, args = []) {
         parts.push([readoutLabel(current, steps), '', ...fence('text', readout)].join('\n'));
     }
     if (inline) {
-        const patch = diffPatch(root, work.map((e) => e.path));
-        if (patch.length > 0) {
-            parts.push(fence('diff', patch.split('\n')).join('\n'));
-        }
+        parts.push(fence('diff', patch.split('\n')).join('\n'));
     }
     parts.push(verdict, nextUpLine(nextUp, steps.length, where), yourCallBlock(current, checkGreen));
     return emit(withRecommendation(parts, parseRecommendation(detail)));
@@ -179,10 +180,10 @@ export function boundaryEnding(root, slug, step) {
  * nests it under the Log's dated line.
  *
  * Measured, not recalled: the check, seam, and diff rows are read the same way
- * the pause read them, so this has to be built before the work is staged (the
- * seam and diff rows read the working tree). Null when the detail file carries
- * nothing to record, so a hand-built step with no detail gets the bare dated
- * line it always did.
+ * the pause read them. Both measures run against HEAD, so staging no longer
+ * moves the counts and the caller's build-then-stage order is a nicety rather
+ * than a requirement. Null when the detail file carries nothing to record, so a
+ * hand-built step with no detail gets the bare dated line it always did.
  */
 export function stepRecord(root, slug, step, detail) {
     const summary = parseSummary(detail);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Attention-first build process: 14 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",

package/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 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 /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses."
+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 /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then stops."
 argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
 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(plumbbob spike:*), Bash(git diff:*)
@@ -36,8 +36,8 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
 
 1. **Pick the step.** Use the number you were invoked with (for example `/plumbbob:build 4`), or,
    if you were given a range like `/plumbbob: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, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
+   the second as the last step you approve and land yourself (see the range note under
+   `--auto`). With no 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 `/plumbbob:step` nudge when every
    step is checkpointed.
 2. **Enter the step.** Run `plumbbob build <n>`, or bare `plumbbob build` to enter the
@@ -87,7 +87,9 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
      <<'BODY'`). Do **not** pass it as an argument value (`--body "$(cat <<'BODY'…)"`):
      `--body` ignores an argument and always reads stdin. Under an agent harness that
      stdin is a socket, and `--body` now refuses rather than blocking on one; the
-     refusal names this exact heredoc form.
+     refusal names this exact heredoc form. End that line at `<<'BODY'`, with no `2>&1`
+     after it: Claude Code's permission checker cannot analyze the extra redirect, so it
+     blocks the command or stops to ask instead of letting this skill's allowance cover it.
    - **A drifted subject is reconciled at the pause, never silently.** The planned
      title *is* the checkpoint subject ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). If the diff drifted
      from it, **present** a corrected subject at the pause (`planned title → proposed
@@ -256,30 +258,42 @@ and approves in the human's place**, and it **chains**:
   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
   `after`-agent output simply feeds the *existing* self-review halt condition.
-- **Stop and hand back to the human** the moment any of these is true: the check is red,
-  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 `/plumbbob: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, end on the same turn the default pause does**: write the detail file, run
-  `plumbbob handoff`, and paste 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.
+- **Stop and hand back to the human** the moment a halt arrives, and end the turn by the
+  kind of halt it is
+  ([D85 (range-top-lands)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d85)):
+  - **A halt on trouble leaves a step unlanded.** The check is red, 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 `/plumbbob:refine`; an agent cannot
+    advance the loop), or a new decision is needed. The step is still in flight and the
+    human has a call to make about it, so end on the same turn the default pause does:
+    write the detail file, run `plumbbob handoff`, and paste its block.
+  - **A clean halt lands its step first.** The top of a requested range is reached, or no
+    planned steps remain. That step checkpoints like every step before it, and its
+    checkpoint's block is the whole ending: relay it with nothing written around it, then
+    end the turn. Write no detail file and run no `handoff`, because nothing is pending.
+    The block already carries the Verdict the step earned and a Next Up pointing at what
+    comes next (the next undone step and its `- model:` recommendation, or the finish),
+    which is what a fresh context window needs to pick the right `/model`.
 
 `--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.
-The default (no flag, no range) always ends at the pause.
+only because the human asked for it by name. A range hands the clock back once its top
+step has landed: the step after it waits for the human's next run. The default (no flag,
+no range) always ends at the pause.
 
 ### A step range (`N-M`) is a bounded `--auto`
 
-`/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **pauses
-after step 3** instead of chaining to done. The range *is* the opt-in; you do not also
-pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
-any next step whose plan number is past the top of the range.** It adds no machinery:
-just the one more entry already in the halt list above.
-
-- **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, then pause at
-  M. `N-N` is just the single step `N` (which already ends at the pause).
+`/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **stops
+once step 3 has landed** instead of chaining to done. The range *is* the opt-in; you do not
+also pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
+any next step whose plan number is past the top of the range.** It adds no machinery: just
+the one more entry already in the halt list above, and it is a clean halt, so the top step
+is never held back for approval. The human approved it by typing the range, and
+`plumbbob build` says so as it enters that step:
+`step 3 is the top of the range you granted`.
+
+- **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, M included, then
+  relay M's checkpoint block and end the turn. `N-N` is a range like any other: it builds
+  and lands the single step `N`. Only a bare `/plumbbob:build N` ends at the pause.
 - **N > M** (for example `3-1`): that is not a range you can walk; report it and stop rather
   than guess the intent.
 - **M past the last planned step** (for example `1-9` with three steps): build through the
@@ -302,7 +316,7 @@ just the one more entry already in the halt list above.
 - **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
-  at its top.
+  once its top step lands.
 - **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` → `/plumbbob:refine`. You are still the one

package/skills/finish/SKILL.md

@@ -53,8 +53,11 @@ record.
    Redirect the heredoc *into* the command (`--body <<'BODY'`). Do **not** pass it as
    an argument value (`--body "$(cat <<'BODY'…)"`): `--body` ignores an argument and
    always reads stdin. Under an agent harness that stdin is a socket, and `--body` now
-   refuses rather than blocking on one; the refusal names this exact heredoc form. Omit
-   `--body` entirely and the commit carries the `plumbbob finish` marker subject only.
+   refuses rather than blocking on one; the refusal names this exact heredoc form. End
+   that line at `<<'BODY'`, with no `2>&1` after it: Claude Code's permission checker
+   cannot analyze the extra redirect, so it blocks the command or stops to ask instead of
+   letting this skill's allowance cover it. Omit `--body` entirely and the commit carries
+   the `plumbbob finish` marker subject only.
 3. **Point at the next goal.** Relay `plumbbob finish`'s output verbatim, blank lines
    included: its lead line, which names the branch the tracked folder now rides into the
    PR, any advisory beneath it, and `**Next Up**: Nothing planned - /plumbbob:plan`. That

package/skills/plan/SKILL.md

@@ -142,7 +142,8 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    a `plan <sha>` line in
    `checkpoints`. This keeps the first step's diff clean, so history reads
    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
+   heredoc, with nothing after `<<'BODY'` on its line, not even `2>&1`) 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 pause is a decision turn.** Present the framed plan for the human's call,
      then give it the cold read (**§ The cold read**), write the result into

package/skills/verify/SKILL.md

@@ -163,7 +163,10 @@ this skill verifies it the same way: **it reads the diff, not the author**
    Redirect the heredoc *into* the command (`--body <<'BODY'`). Do **not** pass it as
    an argument value (`--body "$(cat <<'BODY'…)"`): `--body` ignores an argument and
    always reads stdin. Under an agent harness that stdin is a socket, and `--body` now
-   refuses rather than blocking on one; the refusal names this exact heredoc form.
+   refuses rather than blocking on one; the refusal names this exact heredoc form. End
+   that line at `<<'BODY'`, with no `2>&1` after it: Claude Code's permission checker
+   cannot analyze the extra redirect, so it blocks the command or stops to ask instead of
+   letting this skill's allowance cover it.
 
    Do **not** run a TIL scan or reach for a separate commit skill; the body is yours to
    write in one breath. Omit `--body` entirely and the CLI writes a deterministic body