plumbbob 0.12.0 → 0.12.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.12.0",
+  "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
@@ -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/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 : [],
@@ -756,10 +957,10 @@ export function parseDetailStep(detail) {
  */
 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) => {
@@ -792,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}]`,
         '',
@@ -799,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,7 +8,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";
+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";
@@ -18,8 +18,8 @@ import { notice } from "../lib/notice.js";
  * 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, re-renders the
- * build-log's Current step line, and says so when the step is the top of a
- * range the human typed.
+ * 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);
@@ -48,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`
@@ -89,30 +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'}`]
             : [];
-    // 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.
+    // 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 }) +
-        top +
+        lastGrantedNotice(readGrant(root), steps, step) +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],
@@ -120,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, parseDetailStep, 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";
@@ -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;