plumbbob 0.11.3 → 0.12.1

package/.claude-plugin/plugin.json

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

@@ -10,7 +10,7 @@
   <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
 </p>
 
-PlumbBob is a Claude Code plugin (fourteen skills and a small CLI) that runs
+PlumbBob is a Claude Code plugin (fifteen skills and a small CLI) that runs
 LLM-assisted coding as a loop you control. You and the model settle the plan in a file
 *before* any code; then the model builds one small step at a time and **stops after
 each one**, waiting for you to read the diff and approve it before anything is
@@ -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:
@@ -334,7 +334,7 @@ that matters.
 > under [`docs/evals/`](docs/evals/): the route the latch owns (*no checkpoint over a red
 > check under pressure*) went from **2/5 prose-only to 5/5 latched** on the first sweep
 > ([2026-07-11](docs/evals/2026-07-11.md)), every sweep since has held it and closed the
-> two gaps that one surfaced, and the latest ([2026-09-03](docs/evals/2026-09-03.md))
+> two gaps that one surfaced, and the latest ([2026-09-17](docs/evals/2026-09-17.md))
 > scores the shape of the turn itself.
 
 ## Documentation
@@ -346,7 +346,7 @@ Each doc answers one question (in rough reading order for a new user):
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/): that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md): the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md): steps, seams, the pause, park/harvest, spikes.
-- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all fourteen skills: inputs, effects, when to reach for each.
+- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all fifteen skills: inputs, effects, when to reach for each.
 - *What does a turn look like, and who renders which part?* → [`docs/presentation.md`](docs/presentation.md): the anatomy of the pause, the boundary, and the driver turns.
 - *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md): the subprocess envelope, the manifest, `harness.json`, and working examples (including a local-model reviewer via Ollama).
 - *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md): the ollama-reviewer example walked end to end, install to every-pause review.

package/dist/cli-core.js

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { start } from "./verbs/start.js";
 import { status } from "./verbs/status.js";
 import { park } from "./verbs/park.js";
+import { order } from "./verbs/order.js";
 import { build } from "./verbs/build.js";
 import { handoff } from "./verbs/handoff.js";
 import { check } from "./verbs/check.js";
@@ -140,6 +141,14 @@ const VERBS = [
         tolerateUnknownFlags: true,
         notes: 'Refuses (exit 1) with no session, empty text, or no `## Park list` section.',
     },
+    {
+        name: 'order',
+        description: 'set the build order: the undone steps in the sequence to build them',
+        synopsis: ['order <n> [<n>…]', 'order --reset'],
+        args: [{ name: '<n>…', gloss: 'undone step numbers in the sequence to build them; the rest follow in document order' }],
+        flags: [{ name: '--reset', gloss: 'drop the line, so the plan reads in document order again' }],
+        notes: 'Writes the one numeric line under `## Build order` in intent.md, which status, build, checkpoint, and handoff all read. Refuses (exit 1) with no session, no numbers, a number the plan lacks, a repeat, or a step already checkpointed.',
+    },
     {
         name: 'spike',
         description: 'worktree experiment + report for a genuine fork',
@@ -340,6 +349,8 @@ async function dispatch(verb, cwd, rest) {
             return status(cwd, rest);
         case 'park':
             return park(cwd, rest);
+        case 'order':
+            return order(cwd, rest);
         case 'build':
             return build(cwd, rest);
         case 'handoff':

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

@@ -15,11 +15,15 @@ function sectionLines(content, heading) {
     if (start === -1) {
         return { offset: 0, lines: [] };
     }
-    let end = lines.findIndex((l, i) => i > start && l.startsWith('## '));
-    if (end === -1) {
-        end = lines.length;
-    }
-    return { offset: start + 1, lines: lines.slice(start + 1, end) };
+    return { offset: start + 1, lines: lines.slice(start + 1, sectionEnd(lines, start)) };
+}
+/**
+ * The index of the line that ends the section opened at `heading`: the next
+ * `## ` heading, or one past the last line when none follows.
+ */
+function sectionEnd(lines, heading) {
+    const end = lines.findIndex((l, i) => i > heading && l.startsWith('## '));
+    return end === -1 ? lines.length : end;
 }
 /**
  * The build title: the first `# ` heading in intent.md, or null when absent.
@@ -70,6 +74,166 @@ export function parseSteps(intent) {
         return { n: s.n, done: s.done, title: s.title, planned: /done when/i.test(block), doneWhen, model, line: offset + s.idx + 1 };
     });
 }
+// A build-order line: step numbers and commas, nothing else. A trailing comma
+// is tolerated, since a hand edit leaves one behind.
+const BUILD_ORDER_LINE = /^\d+(?:\s*,\s*\d+)*\s*,?$/;
+/**
+ * The build order declared under `## Build order`: the step numbers on the
+ * first line that is nothing but numbers and commas, in the sequence written.
+ *
+ * The line is the plan's own statement of what to build next once the
+ * numbering stops carrying it (a refined plan appends a step 7 that has to
+ * land before step 5), and `plumbbob order` is the verb that writes it. The
+ * template's guidance, a comment, and an absent section all read as `[]`,
+ * which every picker takes to mean document order. Numbers come back
+ * verbatim, repeats and unknowns included: `orderSteps` does the cleaning, and
+ * `recover` wants the raw read to say which number the plan lacks.
+ */
+export function parseBuildOrder(intent) {
+    const line = sectionLines(intent, '## Build order')
+        .lines.map((l) => l.trim())
+        .find((l) => BUILD_ORDER_LINE.test(l));
+    if (line === undefined) {
+        return [];
+    }
+    return line
+        .split(',')
+        .map((n) => n.trim())
+        .filter((n) => n.length > 0)
+        .map(Number);
+}
+/**
+ * The steps in build order: the numbers `order` lists first, in that sequence,
+ * then every step it leaves out, in document order.
+ *
+ * A listed number takes the first step in document order that carries it, and
+ * a repeat of the number is ignored, so a doubled entry cannot double a step; a
+ * number no step carries is dropped. An empty order is the identity, which is
+ * what a plan with no `## Build order` section reads as. The steps themselves
+ * never change, only the sequence, so `n`, `line`, and `done` stay what
+ * `parseSteps` read.
+ */
+export function orderSteps(steps, order) {
+    const taken = new Set();
+    const ordered = [];
+    for (const n of order) {
+        const step = steps.find((s) => s.n === n);
+        if (step !== undefined && !taken.has(step)) {
+            taken.add(step);
+            ordered.push(step);
+        }
+    }
+    return [...ordered, ...steps.filter((s) => !taken.has(s))];
+}
+/**
+ * The plan's steps in build order: `parseSteps` merged with `parseBuildOrder`.
+ *
+ * The one call every next-step picker makes, so the dashboard's `← next`, a
+ * bare `plumbbob build`, `checkpoint`'s fallback, and the card's Next Up
+ * cannot disagree about which step comes next.
+ */
+export function parseOrderedSteps(intent) {
+    return orderSteps(parseSteps(intent), parseBuildOrder(intent));
+}
+/**
+ * The undone steps that come before step `n` in `ordered`: what an explicit
+ * `build n` skips. Empty when `n` is not in the list.
+ */
+export function skippedBefore(ordered, n) {
+    const at = ordered.findIndex((s) => s.n === n);
+    return at === -1 ? [] : ordered.slice(0, at).filter((s) => !s.done);
+}
+/**
+ * The reminder the card and the dashboard render: the undone step numbers
+ * (minus `exclude`, the step a pause is about) in build order, when that
+ * sequence departs from document order; `[]` when the numbering already
+ * carries it, so a plan nobody re-sequenced renders nothing new.
+ */
+export function remainingOrder(steps, order, exclude) {
+    const left = (list) => list.filter((s) => !s.done && s.n !== exclude).map((s) => s.n);
+    const byOrder = left(orderSteps(steps, order));
+    const byDocument = left(steps);
+    return byOrder.some((n, i) => n !== byDocument[i]) ? byOrder : [];
+}
+/**
+ * The build order as a phrase: the next `cap` step numbers in sequence, the
+ * rest folded to a count (`and 2 more`), the way a long detail degrades on
+ * every one-liner; '' for an empty order. With no cap, the whole sequence,
+ * which is the dashboard's row.
+ */
+export function buildOrderPhrase(order, cap) {
+    if (order.length === 0) {
+        return '';
+    }
+    const shown = cap === undefined ? order : order.slice(0, cap);
+    const rest = order.length - shown.length;
+    return `build order ${shown.join(', ')}${rest > 0 ? ` (and ${rest} more)` : ''}`;
+}
+/**
+ * Write `order` as the one numeric line under `## Build order`: in place of
+ * the line already there, else last in the section, else in a new section
+ * opened right after `## Steps`, so the sequence sits beside the steps it
+ * sequences. Mechanical bookkeeping for `plumbbob order`, the way
+ * `markStepDone` is for `checkpoint`.
+ */
+export function setBuildOrder(intent, order) {
+    const lines = intent.split('\n');
+    const text = order.join(', ');
+    const heading = lines.findIndex((l) => l.trim() === '## Build order');
+    if (heading !== -1) {
+        const end = sectionEnd(lines, heading);
+        const at = lines.findIndex((l, i) => i > heading && i < end && BUILD_ORDER_LINE.test(l.trim()));
+        if (at !== -1) {
+            lines[at] = text;
+            return lines.join('\n');
+        }
+        insertAfterContent(lines, heading, end, [text]);
+        return lines.join('\n');
+    }
+    const steps = lines.findIndex((l) => l.trim() === '## Steps');
+    const end = steps === -1 ? lines.length : sectionEnd(lines, steps);
+    insertAfterContent(lines, steps, end, ['## Build order', '', text]);
+    return lines.join('\n');
+}
+/**
+ * Splice `block` in after the last non-blank line before `end` (and after
+ * `from`), one blank line on each side, without doubling a blank that is
+ * already there.
+ */
+function insertAfterContent(lines, from, end, block) {
+    let last = end - 1;
+    while (last > from && (lines[last] ?? '').trim() === '') {
+        last -= 1;
+    }
+    const at = last + 1;
+    const followed = at < lines.length && (lines[at] ?? '').trim() === '';
+    lines.splice(at, 0, '', ...block, ...(followed ? [] : ['']));
+}
+/**
+ * Drop the numeric line under `## Build order`, and the section itself when
+ * nothing but blank lines is left in it, so the plan reads in document order
+ * again. A plan with no line is returned unchanged.
+ */
+export function clearBuildOrder(intent) {
+    const lines = intent.split('\n');
+    const heading = lines.findIndex((l) => l.trim() === '## Build order');
+    if (heading === -1) {
+        return intent;
+    }
+    const at = lines.findIndex((l, i) => i > heading && i < sectionEnd(lines, heading) && BUILD_ORDER_LINE.test(l.trim()));
+    if (at === -1) {
+        return intent;
+    }
+    lines.splice(at, 1);
+    if ((lines[at - 1] ?? '').trim() === '' && (at >= lines.length || (lines[at] ?? '').trim() === '')) {
+        lines.splice(at - 1, 1);
+    }
+    const body = lines.slice(heading + 1, sectionEnd(lines, heading));
+    if (body.every((l) => l.trim() === '')) {
+        lines.splice(heading, body.length + 1);
+    }
+    return lines.join('\n');
+}
 /**
  * Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section.
  *
@@ -118,15 +282,43 @@ export function parseOpenQuestions(intent) {
     }).length;
 }
 /**
- * Count the open parked items: `- [ ]` lines under `## Park list`.
+ * Count the park list: the `- [ ]` lines still open, and every checklist line
+ * under `## Park list`, harvested `- [x]` ones included.
  *
  * A parked item is a mid-build idea the `park` verb appends as a flat checklist
- * line for later triage; `/plumbbob:harvest` flips a triaged one to `- [x]` and it
- * stops counting. The `(none yet)` placeholder and the blockquote instructions
- * never match.
+ * line for later triage; `/plumbbob:harvest` flips a triaged one to `- [x]`, so
+ * the pair reads `parked 2 of 7 open` and a harvest shows as the gap between
+ * the two. The `(none yet)` placeholder and the blockquote instructions never
+ * match.
+ */
+export function parseParkTotals(buildLog) {
+    let open = 0;
+    let total = 0;
+    for (const line of sectionLines(buildLog, '## Park list').lines) {
+        const m = /^-\s+\[([ xX])\]\s+\S/.exec(line.trim());
+        if (m === null) {
+            continue;
+        }
+        total += 1;
+        if (m[1] === ' ') {
+            open += 1;
+        }
+    }
+    return { open, total };
+}
+/**
+ * Count the open parked items alone: `- [ ]` lines under `## Park list`.
  */
 export function parseParked(buildLog) {
-    return sectionLines(buildLog, '## Park list').lines.filter((l) => /^-\s+\[ \]\s+\S/.test(l.trim())).length;
+    return parseParkTotals(buildLog).open;
+}
+/**
+ * The park count as both surfaces say it: `parked 2 of 7 open` once anything
+ * has been parked, the open count against everything ever parked; `parked 0`
+ * with nothing on the list yet.
+ */
+export function parkedPhrase(totals) {
+    return totals.total === 0 ? 'parked 0' : `parked ${totals.open} of ${totals.total} open`;
 }
 /**
  * Count the constraints declared under `## Constraints`: the section's
@@ -225,7 +417,7 @@ function nextMove(spiking, steps, inFlight, parked, requested) {
         if (target.done) {
             return `build step ${target.n} — explicitly requested (already checkpointed)`;
         }
-        const skipped = steps.filter((s) => !s.done && s.n < target.n).length;
+        const skipped = skippedBefore(steps, target.n).length;
         const notes = [];
         if (skipped > 0) {
             notes.push(`skips ${skipped} undone step${skipped === 1 ? '' : 's'}`);
@@ -256,13 +448,19 @@ function nextMove(spiking, steps, inFlight, parked, requested) {
  */
 export function orient(input) {
     const steps = parseSteps(input.intent);
-    const parked = parseParked(input.buildLog);
+    // The build order re-sequences the picks and nothing else: the step block
+    // still renders in document order, with the marker showing where the
+    // sequence actually goes.
+    const order = parseBuildOrder(input.intent);
+    const ordered = orderSteps(steps, order);
+    const parks = parseParkTotals(input.buildLog);
     // The target the dashboard details: the explicitly requested step when it
     // exists in the plan, else the next undone. A requested number that names no
     // planned step carries nothing here; the next-move line reports the mismatch
     // while the rest of the dashboard renders as usual.
     const requestedStep = input.requested === null ? undefined : steps.find((s) => s.n === input.requested);
-    const target = requestedStep ?? steps.find((s) => !s.done);
+    const nextUndone = ordered.find((s) => !s.done);
+    const target = requestedStep ?? nextUndone;
     const seamParse = target === undefined ? null : parseStepSeam(input.intent, target.n);
     const phase = input.spiking ? 'SPIKE' : input.inFlight !== null ? 'BUILD' : 'DESIGN';
     return {
@@ -270,9 +468,12 @@ export function orient(input) {
         phase,
         steps,
         lastCheckpoint: parseLastCheckpoint(input.checkpoints),
-        parked,
+        parked: parks.open,
+        parkedTotal: parks.total,
         openQuestions: parseOpenQuestions(input.intent),
-        next: nextMove(input.spiking, steps, input.inFlight, parked, input.requested),
+        next: nextMove(input.spiking, ordered, input.inFlight, parks.open, input.requested),
+        nextUndone: nextUndone?.n ?? null,
+        buildOrder: remainingOrder(steps, order, null),
         requested: requestedStep?.n ?? null,
         nextDoneWhen: target?.doneWhen ?? null,
         nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
@@ -741,15 +942,25 @@ 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.
  */
 export function formatOrientation(o) {
     const doneCount = o.steps.filter((s) => s.done).length;
-    const nextUndone = o.steps.find((s) => !s.done);
+    const nextUndone = o.nextUndone === null ? undefined : o.steps.find((s) => s.n === o.nextUndone);
     // One arrow, always: an explicitly requested step takes the marker and the
     // detail rows, so the injected state never argues with the invocation. With
-    // no (valid) request the next undone step keeps them, as ever.
+    // no (valid) request the next undone step in build order keeps them, as ever.
     const requestedStep = o.requested === null ? undefined : o.steps.find((s) => s.n === o.requested);
     const marked = requestedStep ?? nextUndone;
     const stepLines = o.steps.map((s) => {
@@ -782,6 +993,9 @@ export function formatOrientation(o) {
     const receipts = o.outOfBand > 0
         ? [`${o.outOfBand} commit${o.outOfBand === 1 ? '' : 's'} since the last checkpoint landed outside plumbbob's ledger.`]
         : [];
+    // The build order, whole, only when it departs from the numbering: the
+    // dashboard is the reference surface, so nothing is folded to a count here.
+    const orderRow = o.buildOrder.length > 0 ? [`build order  ${o.buildOrder.join(', ')}`] : [];
     return [
         `PlumbBob — ${o.title ?? '(untitled)'}   [${o.phase}]`,
         '',
@@ -789,7 +1003,8 @@ export function formatOrientation(o) {
         '',
         cpLine,
         ...receipts,
-        `parked ${o.parked} · open questions ${o.openQuestions}`,
+        ...orderRow,
+        `${parkedPhrase({ open: o.parked, total: o.parkedTotal })} · open questions ${o.openQuestions}`,
         '',
         `next → ${o.next}`,
     ].join('\n');

package/dist/verbs/build.js

@@ -8,16 +8,18 @@ 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";
+import { parseOrderedSteps, skippedBefore } 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 names the step when it is the last one a
+ * self-approval grant reaches.
  */
 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;
@@ -45,7 +48,9 @@ export function build(cwd, args) {
         return 1;
     }
     const intent = readFileSync(intentPath(root, slug), 'utf8');
-    const steps = parseSteps(intent);
+    // In build order: the sequence `## Build order` declares when a refined plan
+    // has one, else the numbering, so this pick and the dashboard's agree.
+    const steps = parseOrderedSteps(intent);
     // 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 `/plumbbob:step`
@@ -86,17 +91,20 @@ export function build(cwd, args) {
     const title = steps.find((s) => s.n === step)?.title ?? null;
     syncBuildLogState(root, slug, stepLabel(step, title));
     // An explicit jump past undone work says so out loud: the entered step and
-    // the count it skips read back to the human (and to the transcript), so a
-    // deliberate `build 22` and a confused one look different on the page.
-    const skipped = raw === undefined ? 0 : steps.filter((s) => !s.done && s.n < step).length;
+    // the count it skips (the undone steps ahead of it in build order) read back
+    // to the human (and to the transcript), so a deliberate `build 22` and a
+    // confused one look different on the page.
+    const skipped = raw === undefined ? 0 : skippedBefore(steps, step).length;
     const picked = raw === undefined
         ? ['next undone']
         : 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.
+    // Two lines (three on the last step a grant reaches), 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 }) +
+        lastGrantedNotice(readGrant(root), steps, step) +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],
@@ -104,3 +112,34 @@ export function build(cwd, args) {
         `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }
+/**
+ * The line naming the last step a self-approval grant reaches this turn, or ''
+ * for any other step and when no grant is live.
+ *
+ * That step lands like every step before it, and then the turn ends on its
+ * checkpoint: a clean halt. Saying so as the step is entered puts the fact in
+ * front of the model before it chooses between landing the step and holding it
+ * at a pause, which is the choice a clean halt kept getting wrong. A range
+ * reaches its top, or the last undone step under its top when the plan ends
+ * first, or when the build order puts a number past the top ahead of the rest
+ * (a range names plan numbers, and the skill halts before one past its top);
+ * `--auto` reaches the plan's last undone step.
+ */
+function lastGrantedNotice(grant, steps, step) {
+    if (grant === null) {
+        return '';
+    }
+    const remedy = 'land it on green, then stop at the boundary';
+    if (grant.kind === 'range') {
+        if (step === grant.ceiling) {
+            return notice({ fact: `step ${step} is the top of the range you granted`, remedy });
+        }
+        const after = steps.slice(steps.findIndex((s) => s.n === step) + 1).find((s) => !s.done);
+        const more = after !== undefined && after.n <= grant.ceiling;
+        return step < grant.ceiling && !more
+            ? notice({ fact: `step ${step} is the last undone step in the range you granted`, remedy })
+            : '';
+    }
+    const more = steps.some((s) => !s.done && s.n !== step);
+    return more ? '' : notice({ fact: `step ${step} is the last undone step in the plan`, remedy });
+}

package/dist/verbs/checkpoint.js

@@ -3,7 +3,7 @@
 // `/plumbbob:build` run, your own hands, a vibe session, or another harness all
 // checkpoint identically. It does NOT require a STEP marker (the flat control
 // file recording the step in flight): the step is whatever you pass, else the
-// in-flight STEP, else the next undone step in intent.md. It evaluates the
+// in-flight STEP, else the next undone step in intent.md's build order. It evaluates the
 // approval latch, gates on a green check, commits any pending work (or records
 // the existing HEAD when the tree is already clean: the human's commit skill
 // may have committed first), records the SHA, flips the intent checkbox to
@@ -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, parseOrderedSteps, 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";
@@ -87,7 +87,7 @@ export async function checkpoint(cwd, args) {
     // 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.
@@ -200,7 +200,7 @@ function planSubject(root) {
 /**
  * Resolve the step being checkpointed, or null when none can be determined.
  *
- * Explicit arg > in-flight STEP file > first undone step in intent.md. A `-m`
+ * Explicit arg > in-flight STEP file > first undone step in build order. A `-m`
  * value is a message, never a step: `checkpoint -m "2"` must not read as
  * step 2.
  */
@@ -214,7 +214,7 @@ function resolveStep(root, args) {
         return inFlight;
     }
     try {
-        return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => !s.done)?.n ?? null;
+        return parseOrderedSteps(readFileSync(intentPath(root), 'utf8')).find((s) => !s.done)?.n ?? null;
     }
     catch {
         return null;
@@ -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;