plumbbob 0.12.0 → 0.13.0

package/dist/verbs/handoff.js

@@ -1,13 +1,21 @@
 // `plumbbob handoff`: emit the CLI-owned ending of a turn as one contiguous
-// block (docs/presentation.md). Read-only, no state change. Every part outside
+// block (docs/presentation.md). Changes no state but three: at a pause it
+// leaves the detail file with a blank line around each heading, at a step pause
+// it stamps what the card showed in `PAUSE`, and every render it prints is
+// recorded in `RELAY` for the check at the turn's end. Every part outside
 // the readout fence is a bold label, a colon, and text that wraps, one blank
 // line between blocks and no fence but the readout's own. It derives the moment
-// from the session: a step in flight ⇒ the decision-tier ending (the labeled
-// Readout and its fence, the inline diff when the change is 20 lines or fewer,
-// the Verdict, Next Up, Your Call, and the Recommendation last); a landed step
+// from the session: a step in flight ⇒ the decision-tier ending (the Now line
+// naming that step, the labeled Readout and its fence, the inline diff when
+// the change is 20 lines or fewer, the Verdict, Next Up, Your Call, and the
+// Recommendation last); a landed step
 // with none in flight ⇒ the orientation-tier ending (Verdict and Next Up); a
 // fresh session with nothing yet measured ⇒ the forward pointer alone.
 //
+// A step pause renders its card once (D87 (pause-once)). While the stamp still
+// matches, a later render is the one-line reminder, the driver pointer back at
+// the step; the card comes back when the pause changes or on `--full`.
+//
 // The whole decision turn is rendered here, its opening block included: the
 // Summary lead and the numbered highlights come out of `.plumbbob/detail.md`
 // as the markdown the model wrote, with the `(details: …)` bracket appended so
@@ -29,22 +37,18 @@
 // the step names closing the spike, a step exit (a revert, an abandon, a spike
 // closed at the boundary) finds nothing in flight and points forward, with no
 // Verdict either way, since nothing landed.
-import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.js";
-import { blocks } from "../lib/notice.js";
+import { PLAN_COMMIT_MARKER, commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.js";
+import { blocks, printEnding } from "../lib/notice.js";
 import { isArtifactPath, parseStepSeam } from "../lib/intent.js";
-import { checkpointsPath, detailPath, hasSession, inSpike, intentPath, readStats, readTurn, resolveBuild, seamPath, stepPath, tickPath, } from "../lib/sidecar.js";
-import { countDiff, diffRowValue, foldVerdict, lastLedgerSha, parseConstraintCount, parseLastCheckpoint, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, recapLines, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
+import { buildLogPath, checkpointsPath, detailPath, hasSession, inSpike, intentPath, pausePath, readStats, readTurn, resolveBuild, seamPath, stepPath, tickPath, } from "../lib/sidecar.js";
+import { buildOrderPhrase, countDiff, diffRowValue, foldVerdict, lastLedgerSha, normalizeDetailHeadings, parkedPhrase, parseBuildOrder, parseConstraintCount, parseLastCheckpoint, parseOrderedSteps, parseParkTotals, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, recapLines, remainingOrder, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
 // The inline-diff threshold (docs/presentation.md): at 20 changed lines or
 // fewer the patch rides the turn; at 21 it stays in the working tree behind
 // the counted diff row.
 const INLINE_DIFF_MAX = 20;
-// plumbbob's own plan commits carry this marker on a line of their body. A
-// `chore(plan)` harvest lands between nearly every step, so counting them as
-// out-of-band would trip the advisory rung on routine housekeeping and stop
-// meaning anything within three steps.
-const PLAN_COMMIT_MARKER = '^plumbbob plan$';
 // The seam rule, and the one tier that still has a seam to mark: at the plan
 // pause the model presents the framed plan above the relay, so the rule keeps
 // a label from reading as the tail of what precedes it, and a run of blank
@@ -58,9 +62,14 @@ const SEAM_RULE = '\n---';
  *
  * Requires an active session (the STATE sentinel under `.plumbbob/`). The step
  * tiers are derived, not passed: a step in flight yields the full
- * decision-tier ending (the Readout and its fence, the inline diff when small
- * enough, the Verdict, Next Up, Your Call, and the Recommendation), a landed
- * step yields the orientation-tier ending (Verdict and Next Up, no Your Call),
+ * decision-tier ending (the Now line, the Readout and its fence, the inline
+ * diff when small enough, the Verdict, Next Up, Your Call, and the
+ * Recommendation), and so does
+ * a named step that has not landed when nothing is in flight (a hand-built diff
+ * under verify). That card renders once: a later render of the same pause, with
+ * nothing in it changed, is the one-line reminder, and `--full` prints the card
+ * whatever the stamp says. A landed step yields the orientation-tier ending
+ * (Verdict and Next Up, no Your Call),
  * and a fresh session with nothing to report yields only
  * the forward pointer. The two endings no session state can distinguish are
  * named by a flag: `--plan` is the plan pause (a decision turn about the plan,
@@ -78,10 +87,16 @@ export function handoff(cwd, args = []) {
         process.stderr.write('plumbbob: handoff: --plan and --driver name different tiers; pass one.\n');
         return 1;
     }
+    // A build named by flag rides any command that reprints this ending, since
+    // the cursor may point elsewhere.
+    const named = args.includes('--build') ? slug : null;
     const intent = readOr(intentPath(root, slug));
-    const steps = parseSteps(intent);
+    // In build order, so the pointer names the step a bare `plumbbob build`
+    // would enter; the build-log feeds the park count beneath it.
+    const steps = parseOrderedSteps(intent);
+    const buildLog = readOr(buildLogPath(root, slug));
     const inFlight = readMarker(stepPath(root, slug));
-    const detail = readOr(detailPath(root));
+    const rawDetail = readOr(detailPath(root));
     // Where a pointer sends the reader to read the step itself: the intent file
     // as the human would type it, relative to the repo root.
     const where = relative(root, intentPath(root, slug));
@@ -90,8 +105,14 @@ export function handoff(cwd, args = []) {
         // renders; the pointer and the moves both aim at the first undone step. A
         // decision turn still ends on the model's recommendation when it wrote one.
         const first = steps.find((s) => !s.done);
-        const plan = [SEAM_RULE, nextUpLine(first, steps.length, where), planCallBlock(first)];
-        return emit(withRecommendation(plan, parseRecommendation(detail)));
+        const detail = settleDetail(root, rawDetail);
+        const plan = [
+            SEAM_RULE,
+            nextUpBlock(first, steps.length, where, nextUpNote(intent, buildLog, null)),
+            planCallBlock(first),
+        ];
+        const command = reprintCommand('--plan', undefined, named);
+        return emit(root, { tier: 'decision', render: 'plan', command }, withRecommendation(plan, parseRecommendation(detail)));
     }
     const explicit = rest.find((a) => /^\d+$/.test(a));
     const lastDone = parseLastCheckpoint(readOr(checkpointsPath(root, slug)));
@@ -111,23 +132,33 @@ export function handoff(cwd, args = []) {
         // (a step exit: a revert, an abandon, a spike closed at the boundary) the
         // ordinary forward pointer stands, and no Verdict rides above it: nothing
         // landed to measure.
-        return emit([driverPointer(root, slug)]);
+        return emit(root, { tier: 'driver', render: 'driver' }, [driverPointer(root, slug)]);
     }
     if (current === null) {
         // Nothing measured yet (a fresh session): no Verdict, just the forward pointer.
-        return emit([nextUpLine(nextUp, steps.length, where)]);
+        return emit(root, { tier: 'orientation', render: 'pointer' }, [
+            nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)),
+        ]);
     }
-    if (inFlight === null) {
+    // A step is pending, and its hand-off is the pause, while it is in flight.
+    // With nothing in flight, a step the turn names that has not landed is
+    // pending too: a diff built outside `/plumbbob:build` reaches
+    // `/plumbbob:verify` with no STEP marker, and the number is how the skill says
+    // which pause to render.
+    const pending = inFlight !== null || (explicit !== undefined && steps.some((s) => s.n === current && !s.done));
+    if (!pending) {
         // The boundary: the orientation-tier ending, the state word and the forward
         // pointer, no decision pending and so no Your Call. The same two parts the
         // checkpoint printed for itself, from the same call.
         const landed = boundaryEnding(root, slug, current);
-        return emit([landed.verdict, landed.pointer]);
+        return emit(root, { tier: 'orientation', render: 'boundary' }, [landed.verdict, landed.pointer]);
     }
     // The pause: the whole turn as one contiguous block, each part a labeled line
     // with one blank line between, and the only fence the readout's own (plus the
-    // inline diff when the change is small enough). It opens on the Summary the
-    // model wrote into the detail file, so there is no seam left to rule off.
+    // inline diff when the change is small enough). It opens on the step in
+    // flight and then the Summary the model wrote into the detail file, so there
+    // is no seam left to rule off.
+    const detail = settleDetail(root, rawDetail);
     const { rows, work, summary, checkGreen } = measured(root, slug, intent, detail, current);
     const { ladder, worst } = foldVerdict(rows, accruedStats(root, slug, current));
     const verdict = verdictLine(ladder, worst);
@@ -135,23 +166,105 @@ export function handoff(cwd, args = []) {
     const changed = counts.added + counts.removed;
     // 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) : '';
+    // to the bare counts rather than pointing at a fence that never arrives. The
+    // stamp hashes it at any size, so it is read whenever there is a change.
+    const fullPatch = changed > 0 ? diffPatch(root, work) : '';
+    const patch = changed <= INLINE_DIFF_MAX ? fullPatch : '';
     const inline = patch.length > 0;
+    const diffRow = diffRowValue(counts, inline);
+    const stamp = pauseStamp(current, detail, measuredLines(rows, diffRow), fullPatch);
+    if (!rest.includes('--full') && readOr(pausePath(root, slug)).trim() === stamp) {
+        // The pause the human already read, unchanged: the answer above this line
+        // is what they asked for, and the card would push it off the screen.
+        const command = reprintCommand(null, explicit, named);
+        return emit(root, { tier: 'decision', render: 'reminder', command }, [
+            `**Next Up**: Back to ${stepPhrase(current, steps)}`,
+        ]);
+    }
+    writePause(root, slug, stamp);
     const readout = recapLines(rows, {
-        diff: diffRowValue(counts, inline),
+        diff: diffRow,
         spent: spentRowValue(spentInputs(root, slug, current, summary)),
         constraints: parseConstraintCount(intent),
     });
-    const parts = [summaryBlock(parseSummary(detail), relative(root, detailPath(root)))];
+    const parts = [
+        `**Now**: ${stepPhrase(current, steps)}`,
+        summaryBlock(parseSummary(detail), relative(root, detailPath(root))),
+    ];
     if (readout.length > 0) {
-        parts.push([readoutLabel(current, steps), '', ...fence('text', readout)].join('\n'));
+        parts.push([READOUT_LABEL, '', ...fence('text', readout)].join('\n'));
     }
     if (inline) {
         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)));
+    parts.push(verdict, nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)), yourCallBlock(current, checkGreen));
+    const command = reprintCommand('--full', explicit, named);
+    return emit(root, { tier: 'decision', render: 'card', command }, withRecommendation(parts, parseRecommendation(detail)));
+}
+/**
+ * The detail file's text with a blank line around each heading, written back to
+ * disk when that changed anything, so the file the gate lints before
+ * `checkpoint` clears it is clean whatever the model typed.
+ *
+ * The render goes out on the normalized text either way. A failed write costs
+ * only the lint guard: stdout and the exit code are the same as if it had
+ * landed.
+ */
+function settleDetail(root, raw) {
+    const clean = normalizeDetailHeadings(raw);
+    if (clean !== raw) {
+        try {
+            writeFileSync(detailPath(root), clean);
+        }
+        catch {
+            // Read-only tree or a vanished directory: the pause still renders.
+        }
+    }
+    return clean;
+}
+/**
+ * The stamp of a step pause: its number and a hash of everything on the card a
+ * later turn could change, so the reminder prints only while the pause is the
+ * one the human already read.
+ *
+ * Hashed: the detail file as normalized, the measured check and seam rows and
+ * the diff row as rendered, and the patch the diff row counts, so an edit that
+ * keeps the counts still reads as a touched file. Never `spent`: it counts
+ * turns, so it moves on every turn and would make every render look new.
+ */
+function pauseStamp(step, detail, rendered, patch) {
+    const hash = createHash('sha256');
+    for (const part of [detail, ...rendered, patch]) {
+        hash.update(part).update('\0');
+    }
+    return `${step} ${hash.digest('hex')}`;
+}
+/**
+ * The readout rows the CLI measured, as the card renders them: `check`,
+ * `seam`, and `diff`. The judgment rows ride the detail file, which the stamp
+ * hashes whole, and `spent` stays out of it.
+ */
+function measuredLines(rows, diff) {
+    const measuredRows = {};
+    if (rows.check !== undefined) {
+        measuredRows.check = rows.check;
+    }
+    if (rows.seam !== undefined) {
+        measuredRows.seam = rows.seam;
+    }
+    return recapLines(measuredRows, { diff, spent: null, constraints: 0 });
+}
+/**
+ * Record the stamp of the card just printed. A failed write costs one more
+ * full card on a later turn, never this turn's output or its exit code.
+ */
+function writePause(root, slug, stamp) {
+    try {
+        writeFileSync(pausePath(root, slug), `${stamp}\n`);
+    }
+    catch {
+        // A read-only tree or a vanished build folder: the card still renders.
+    }
 }
 /**
  * The two CLI-rendered parts of a boundary ending: the Verdict folded from
@@ -165,11 +278,12 @@ export function handoff(cwd, args = []) {
  */
 export function boundaryEnding(root, slug, step) {
     const intent = readOr(intentPath(root, slug));
-    const steps = parseSteps(intent);
+    const steps = parseOrderedSteps(intent);
     const nextUp = steps.find((s) => !s.done && s.n !== step);
+    const note = nextUpNote(intent, readOr(buildLogPath(root, slug)), step);
     return {
         verdict: step === null ? null : landedVerdict(root, slug, intent, step),
-        pointer: nextUpLine(nextUp, steps.length, relative(root, intentPath(root, slug))),
+        pointer: nextUpBlock(nextUp, steps.length, relative(root, intentPath(root, slug)), note),
     };
 }
 /**
@@ -179,6 +293,9 @@ export function boundaryEnding(root, slug, step) {
  * numbered sections' bodies, blank-line separated and unindented; the caller
  * nests it under the Log's dated line.
  *
+ * The record carries no Now line, and its Readout label stays bare like the
+ * card's: the dated Log line above it already names the step.
+ *
  * Measured, not recalled: the check, seam, and diff rows are read the same way
  * 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
@@ -208,7 +325,7 @@ export function stepRecord(root, slug, step, detail) {
         parts.push(recordSummary(summary));
     }
     if (readout.length > 0) {
-        parts.push([readoutLabel(step, parseSteps(intent)), '', ...fence('text', readout)].join('\n'));
+        parts.push([READOUT_LABEL, '', ...fence('text', readout)].join('\n'));
     }
     parts.push(verdictLine(ladder, worst));
     return [...withRecommendation(parts, recommendation), ...sectionBlocks(sections)].join('\n\n');
@@ -255,9 +372,11 @@ function sectionBlocks(sections) {
  */
 export function driverPointer(root, slug) {
     const intent = readOr(intentPath(root, slug));
-    const steps = parseSteps(intent);
+    // The forward fallback follows the build order like every other pick; the
+    // driver line itself stays one line, with no note beneath it.
+    const steps = parseOrderedSteps(intent);
     const inFlight = readMarker(stepPath(root, slug));
-    const driver = inSpike(root, slug) ? spikeNextUpLine(inFlight) : driverNextUpLine(steps, inFlight, steps.length);
+    const driver = inSpike(root, slug) ? spikeNextUpLine(inFlight) : driverNextUpLine(steps, inFlight);
     // The forward fallback skips the step just landed as well as the one open, so
     // a checkpoint whose `[x]` flip failed still points on rather than back at
     // work already recorded.
@@ -297,22 +416,33 @@ function measured(root, slug, intent, detail, step) {
     return { rows, work, summary, checkGreen: measuredCheck?.verdict === 'true' };
 }
 /**
- * Write an ending to stdout and return handoff's exit code.
+ * Print an ending, record it for the relay check, and return handoff's exit
+ * code.
  *
  * The parts are stacked by the same assembly a transition verb prints its own
  * ending through, so the block reads the same whichever command emitted it.
  */
-function emit(parts) {
-    process.stdout.write(blocks(parts));
+function emit(root, kind, parts) {
+    printEnding(root, { ...kind, text: blocks(parts) });
     return 0;
 }
+/**
+ * The command that prints a decision ending again, for the retry the relay
+ * check asks for: handoff in the form that printed it, with the step a verify
+ * pause was named by and the build a flag named, so the retry lands on the
+ * same pause with nothing in flight and the cursor elsewhere.
+ */
+function reprintCommand(form, step, build) {
+    const parts = ['plumbbob handoff', form, step, build === null ? null : `--build ${build}`];
+    return parts.filter((p) => p !== null && p !== undefined).join(' ');
+}
 /**
  * The Verdict line from an already-folded result: the ladder rung, and the
  * worst component in a trailing parenthetical when one exists.
  *
- * No step segment rides here. The identity renders once per turn: the Readout
- * label names the step, Next Up carries the progress count, and the Verdict is
- * left saying the one thing only it says.
+ * No step segment rides here. The identity renders once per turn: the Now line
+ * names the step in flight with its count, Next Up names the step to come with
+ * its own, and the Verdict is left saying the one thing only it says.
  */
 function verdictLine(ladder, worst) {
     const state = `**Verdict**: ${ladder.glyph} ${ladder.state}`;
@@ -338,13 +468,26 @@ function summaryBlock(summary, where) {
     }
     return [lead, '', ...summary.highlights.map((h) => `${h.n}. ${h.title}`)].join('\n');
 }
+// The Readout's label, bare on the card and in the record alike: the Now line
+// at the top of the card names the step the fence measures, and a label that
+// named it too would put the step on the card twice.
+const READOUT_LABEL = '**Readout**:';
 /**
- * The Readout's label: the step the fence below it measures, named once.
+ * A step named the way every pointer names it: the number, the count out of
+ * the whole plan, and the title behind a plain hyphen.
+ *
+ * The count is the plan's own, step number over total, so the Now line and
+ * Next Up agree under a re-sequenced build order. It is dropped only where it
+ * would lie: a step the plan no longer holds is its number alone, since
+ * "Step 9 of 3" would be worse than no count.
  */
-function readoutLabel(step, steps) {
-    const open = steps.find((s) => s.n === step);
-    const title = open !== undefined && open.title.length > 0 ? ` - ${open.title}` : '';
-    return `**Readout**: Step ${step}${title}`;
+function stepPhrase(n, steps) {
+    const step = steps.find((s) => s.n === n);
+    if (step === undefined) {
+        return `Step ${n}`;
+    }
+    const title = step.title.length > 0 ? ` - ${step.title}` : '';
+    return `Step ${n} of ${steps.length}${title}`;
 }
 /**
  * What the `spent` row is rendered from: the step's own stamps and counters
@@ -449,16 +592,18 @@ function readCheckSummary(root) {
  *
  * Nobody types "needs work", so the block names what really happens instead:
  * a message that asks is an expand (nothing changes), and a message that
- * directs is the fix. `revert` comes last, because a destructive move is named
- * rather than discovered. `looks good` renders only while the measured check is
- * green; offering a move that would refuse teaches a false ceremony.
+ * directs is the fix. The expand move also names the way back to the card,
+ * since an expand turn ends on the reminder and the reminder states no move.
+ * `revert` comes last, because a destructive move is named rather than
+ * discovered. `looks good` renders only while the measured check is green;
+ * offering a move that would refuse teaches a false ceremony.
  */
 function yourCallBlock(step, checkGreen) {
     const moves = [];
     if (checkGreen) {
         moves.push(callLine('`looks good`', `I checkpoint Step ${step}; back to the boundary`));
     }
-    moves.push(callLine('`expand`, or any question', 'I show more of what is there; nothing changes'));
+    moves.push(callLine('`expand`, or any question', 'I show more of what is there; nothing changes, and `show the pause` brings all of this back'));
     moves.push(callLine('anything that reads as direction', 'I take it as what to change; nothing lands until you approve'));
     moves.push(callLine('`revert`', 'I wind the work back to the last checkpoint'));
     return ['**Your Call**:', '', ...moves].join('\n');
@@ -493,16 +638,8 @@ function planCallBlock(first) {
  * step is already being built, so the `/model` call is behind us. Null when no
  * step is open, which is the caller's cue to fall back to the forward pointer.
  */
-function driverNextUpLine(steps, inFlight, total) {
-    if (inFlight === null) {
-        return null;
-    }
-    const open = steps.find((s) => s.n === inFlight);
-    const title = open !== undefined && open.title.length > 0 ? ` - ${open.title}` : '';
-    // The progress count rides every tier's pointer, but only where the plan
-    // actually holds the step: "step 9 of 3" would be worse than no count.
-    const progress = open === undefined ? '' : ` of ${total}`;
-    return `**Next Up**: Back to Step ${inFlight}${progress}${title}`;
+function driverNextUpLine(steps, inFlight) {
+    return inFlight === null ? null : `**Next Up**: Back to ${stepPhrase(inFlight, steps)}`;
 }
 /**
  * The driver pointer while a spike is open: the spike outranks the step it
@@ -517,6 +654,38 @@ function spikeNextUpLine(inFlight) {
     const back = inFlight === null ? '' : `, then back to Step ${inFlight}`;
     return `**Next Up**: Close the spike - /plumbbob:spike done${back}`;
 }
+// The card's cap on the build-order reminder: the next five steps, the rest a
+// count. The line is a reminder; the dashboard holds the whole sequence.
+const ORDER_CAP = 5;
+/**
+ * The line beneath the forward pointer: the build order from the step it
+ * names, when `## Build order` re-sequences the plan away from its numbering,
+ * and the park count, when anything has been parked; '' when neither says
+ * anything, so a plan nobody re-sequenced with an empty park list renders the
+ * pointer alone, as before.
+ *
+ * Indented two spaces, because an indented line continues the part above it
+ * to every reader of the anatomy (the advisory's `→` remedy line is the
+ * precedent), where a flush one would open a stray. The parks ride even under
+ * `Nothing planned`: an unharvested list at the end of the plan is the one
+ * reminder that matters there.
+ */
+function nextUpNote(intent, buildLog, exclude) {
+    const parks = parseParkTotals(buildLog);
+    const segments = [
+        buildOrderPhrase(remainingOrder(parseSteps(intent), parseBuildOrder(intent), exclude), ORDER_CAP),
+        parks.total > 0 ? parkedPhrase(parks) : '',
+    ].filter((s) => s.length > 0);
+    return segments.length === 0 ? '' : `  · ${segments.join(' · ')}`;
+}
+/**
+ * The forward pointer with its note beneath, as one part: `blocks` keeps a
+ * part's own newlines, so the note rides flush under the line it qualifies.
+ */
+function nextUpBlock(nextUp, total, where, note) {
+    const line = nextUpLine(nextUp, total, where);
+    return note.length === 0 ? line : `${line}\n${note}`;
+}
 /**
  * The forward pointer: the next undone step with the progress count, its
  * title, and a closing bracket carrying its advisory `- model:` recommendation
@@ -526,7 +695,8 @@ function spikeNextUpLine(inFlight) {
  * The model is the second bold token the line spends, because it is the one
  * the human acts on (a `/model` call) before the next run; the path is a bare
  * `path:line` in a code span, the one link form that opens in a host and still
- * reads as a path in a PR diff.
+ * reads as a path in a PR diff. The line alone is the driver tier's pointer;
+ * every other tier rides `nextUpNote` beneath it, through `nextUpBlock`.
  */
 function nextUpLine(nextUp, total, where) {
     if (nextUp === undefined) {

package/dist/verbs/order.js

@@ -0,0 +1,110 @@
+// `plumbbob order <n>…`: write the build order, the sequence to build the
+// remaining steps in, as the one numeric line under `## Build order` in
+// intent.md. A refined plan appends steps whose numbers say nothing about when
+// they land (a step 7 that has to go before step 5), and until this verb the
+// human carried that sequence in their head and typed it into every `build`.
+// The line is what every next-step picker reads (`status`, `build`,
+// `checkpoint`, `handoff`), so the dashboard's `← next`, a bare
+// `plumbbob build`, and the card's Next Up agree. The verb validates what a
+// hand edit cannot: every number names an undone step, none twice. `--reset`
+// drops the line, and the plan reads in document order again. It runs in any
+// state, since re-sequencing what comes after the step in flight is the
+// mid-step use, and the sidecar sits outside every seam.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { activeBuild, hasSession, intentPath } from "../lib/sidecar.js";
+import { clearBuildOrder, orderSteps, parseSteps, setBuildOrder } from "../lib/orient.js";
+import { ending, notice, printEnding, transition } from "../lib/notice.js";
+import { driverPointer } from "./handoff.js";
+/**
+ * Set the build order to the given step numbers, the rest of the undone steps
+ * following in document order, or clear it with `--reset`.
+ *
+ * The line written is the whole remaining sequence, so a cold reader of
+ * intent.md sees every undone step and not only the ones re-sequenced.
+ * Refuses (exit 1) with no session, no numbers, a token that is not a number,
+ * a number the plan lacks, a repeated number, or a step already checkpointed.
+ */
+export function order(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write(notice({ fact: 'no active session', detail: ['no plan to order'], remedy: 'plumbbob start "<title>"' }));
+        return 1;
+    }
+    const path = intentPath(root);
+    const intent = readFileSync(path, 'utf8');
+    if (args.includes('--reset')) {
+        writeFileSync(path, clearBuildOrder(intent));
+        printEnding(root, {
+            tier: 'driver',
+            render: 'order',
+            text: ending({
+                lead: transition({ label: 'Build order', fact: 'document order' }),
+                pointer: driverPointer(root, activeBuild(root)),
+            }),
+        });
+        return 0;
+    }
+    // Numbers arrive space- or comma-separated: `order 7 8 5` and `order 7,8,5`
+    // read the same, since the line they write is the comma form.
+    const tokens = args
+        .filter((a) => !a.startsWith('--'))
+        .flatMap((a) => a.split(','))
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        process.stderr.write(notice({
+            fact: 'order needs step numbers',
+            detail: ['the undone steps, in the sequence to build them'],
+            remedy: 'plumbbob order 7 8 5, or plumbbob order --reset for document order',
+        }));
+        return 1;
+    }
+    const stray = tokens.find((t) => !/^\d+$/.test(t));
+    if (stray !== undefined) {
+        process.stderr.write(notice({ fact: `\`${stray}\` is not a step number`, remedy: 'plumbbob order 7 8 5' }));
+        return 1;
+    }
+    const given = tokens.map(Number);
+    const steps = parseSteps(intent);
+    const planned = steps.map((s) => s.n);
+    const unknown = given.find((n) => !planned.includes(n));
+    if (unknown !== undefined) {
+        process.stderr.write(notice({
+            fact: `no step ${unknown} in the plan`,
+            detail: [planned.length === 0 ? 'no steps planned yet' : `planned: ${planned.join(', ')}`],
+            remedy: 'fix the number, or /plumbbob:step to add the step first',
+        }));
+        return 1;
+    }
+    const repeat = given.find((n, i) => given.indexOf(n) !== i);
+    if (repeat !== undefined) {
+        process.stderr.write(notice({ fact: `step ${repeat} is listed twice`, remedy: 'list each step once' }));
+        return 1;
+    }
+    const landed = given.find((n) => steps.find((s) => s.n === n)?.done === true);
+    if (landed !== undefined) {
+        process.stderr.write(notice({
+            fact: `step ${landed} is already checkpointed`,
+            detail: ['the order sequences what is left'],
+            remedy: 'list the undone steps only',
+        }));
+        return 1;
+    }
+    const full = orderSteps(steps, given)
+        .filter((s) => !s.done)
+        .map((s) => s.n);
+    writeFileSync(path, setBuildOrder(intent, full));
+    // The pointer reads the plan back from disk, so it already follows the
+    // order just written: back at the step in flight, or forward from the
+    // boundary to the first step in the new sequence.
+    printEnding(root, {
+        tier: 'driver',
+        render: 'order',
+        text: ending({
+            lead: transition({ label: 'Build order', fact: full.join(', ') }),
+            pointer: driverPointer(root, activeBuild(root)),
+        }),
+    });
+    return 0;
+}

package/dist/verbs/park.js

@@ -11,7 +11,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { activeBuild, hasSession, buildLogPath } from "../lib/sidecar.js";
 import { appendToSection } from "../lib/buildlog.js";
-import { ending, notice, transition } from "../lib/notice.js";
+import { ending, notice, printEnding, transition } from "../lib/notice.js";
 import { driverPointer } from "./handoff.js";
 /**
  * Append the given text as one unchecked `- [ ]` line to the build-log's Park list.
@@ -43,6 +43,10 @@ export function park(cwd, args) {
     writeFileSync(path, updated);
     // A park interrupts a step without ending it, so the ending is the capture
     // and the pointer back at what was interrupted.
-    process.stdout.write(ending({ lead: transition({ label: 'Parked', fact: text }), pointer: driverPointer(root, activeBuild(root)) }));
+    printEnding(root, {
+        tier: 'driver',
+        render: 'park',
+        text: ending({ lead: transition({ label: 'Parked', fact: text }), pointer: driverPointer(root, activeBuild(root)) }),
+    });
     return 0;
 }

package/dist/verbs/recover.js

@@ -18,7 +18,7 @@
 // deleting them is a gamble the human should take by hand.
 import { existsSync, readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { parseSteps } from "../lib/orient.js";
+import { parseBuildOrder, parseSteps } from "../lib/orient.js";
 import { activeBuild, checkpointsPath, clearHandoff, clearTick, grantPath, handoffPath, hasSession, intentPath, inSpike, listBuilds, readTurn, setActiveBuild, setGrant, stepPath, tickPath, } from "../lib/sidecar.js";
 import { spikeBranches, spikeWorktrees } from "./spike.js";
 /**
@@ -93,9 +93,39 @@ function sessionFindings(root) {
     findings.push({ name: 'cursor', ok: true, detail: `build "${slug}" resolves` });
     const stepInFlight = existsSync(stepPath(root, slug));
     findings.push(...phaseFindings(root, slug, stepInFlight));
+    findings.push(...orderFindings(root, slug));
     findings.push(...leftoverFindings(root, slug, stepInFlight));
     return findings;
 }
+/**
+ * A build order naming a step the plan does not hold.
+ *
+ * The line under `## Build order` is hand-editable, and a refine can renumber
+ * or drop the step it names; every picker just skips the number, so the plan
+ * quietly builds in a sequence nobody wrote down. Reported, never repaired:
+ * intent.md is a tracked artifact, and the sequence is a judgment call. Silent
+ * while the plan declares no order at all.
+ */
+function orderFindings(root, slug) {
+    const intent = readOr(intentPath(root, slug));
+    const order = parseBuildOrder(intent);
+    if (order.length === 0) {
+        return [];
+    }
+    const planned = parseSteps(intent).map((s) => s.n);
+    const unknown = order.filter((n) => !planned.includes(n));
+    if (unknown.length === 0) {
+        return [{ name: 'build order', ok: true, detail: `every step it lists is planned (${order.join(', ')})` }];
+    }
+    return [
+        {
+            name: 'build order',
+            ok: false,
+            detail: `the build order names step${unknown.length === 1 ? '' : 's'} ${unknown.join(', ')}, which the plan does not hold (planned: ${planned.join(', ')})`,
+            hint: 'rewrite the line with plumbbob order <n>…, or plumbbob order --reset to read the plan in document order',
+        },
+    ];
+}
 /**
  * The cursor names a build that is not there.
  *