plumbbob 0.12.0 → 0.13.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -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
@@ -140,12 +140,14 @@ In Claude Code, inside any git repo with a clean tree:
    nothing is written around it.
 
    ````markdown
+   **Now**: Step 1 of 3 - feat(limiter): add a token-bucket limiter
+
    **Summary**: A per-IP token bucket now refuses the 6th attempt inside a minute. (details: `.plumbbob/detail.md`)
 
    1. The bucket lives in memory, keyed by IP, refilling five tokens a minute.
    2. The clock is injected, so the test advances time instead of sleeping on it.
 
-   **Readout**: Step 1 - feat(limiter): add a token-bucket limiter
+   **Readout**:
 
    ```text
    check        green: 7 of 7 checks
@@ -164,7 +166,7 @@ In Claude Code, inside any git repo with a clean tree:
    **Your Call**:
 
    - `looks good` → I checkpoint Step 1; back to the boundary
-   - `expand`, or any question → I show more of what is there; nothing changes
+   - `expand`, or any question → I show more of what is there; nothing changes, and `show the pause` brings all of this back
    - anything that reads as direction → I take it as what to change; nothing lands until you approve
    - `revert` → I wind the work back to the last checkpoint
 
@@ -192,8 +194,10 @@ In Claude Code, inside any git repo with a clean tree:
    ![The boundary after looks good](docs/media/checkpoint-boundary.svg)
 
    Ask instead (`expand 2`, or any question) and it shows more of what is there and
-   changes nothing; direct it and it takes that as the fix, and nothing lands until you
-   say `looks good`. Then fire `/plumbbob:build` again for the next step: re-firing it
+   changes nothing. The answer closes on one line pointing back at the step, not on the
+   whole block again, since you have already read it; say `show the pause` to see the
+   block again. Direct it and it takes that as the fix, and nothing lands until you say
+   `looks good`. Then fire `/plumbbob:build` again for the next step: re-firing it
    *is* the clock tick. Whenever you lose the thread, `/plumbbob:status` shows where you
    are and names the next move.
 4. **Finish.** When the last step is done, `/plumbbob:finish` writes a report of what shipped
@@ -254,9 +258,10 @@ All fourteen, with inputs and effects, are in
 [`docs/skills-reference.md`](docs/skills-reference.md).
 
 Under the skills ships a lean `plumbbob` CLI (the mechanical verbs the
-skills shell out to), three hooks (a non-blocking post-edit lint, a `git commit`
-ask-hook while a step is in flight, and the per-prompt turn ledger the approval latch
-reads), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
+skills shell out to), four hooks (a non-blocking post-edit lint, a `git commit`
+ask-hook while a step is in flight, the per-prompt turn ledger the approval latch
+reads, and a check at each turn's end that the turn relayed the ending plumbbob
+printed), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
 `builds/<slug>/` folder per build (`intent.md`, `build-log.md`, `checkpoints`, `report.md`)
 that rides the branch into the PR, plus an untracked control plane (`settings.local.json`,
 the session sentinel, the in-flight markers).
@@ -334,7 +339,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 +351,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";
@@ -27,6 +28,7 @@ import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 import { recover } from "./verbs/recover.js";
 import { agent } from "./verbs/agent.js";
+import { relay } from "./verbs/relay.js";
 import { turn } from "./verbs/turn.js";
 /** Shared across every verb that resolves through the active-build cursor. */
 const BUILD_FLAG = {
@@ -79,15 +81,16 @@ const VERBS = [
     },
     {
         name: 'handoff',
-        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver); read-only',
-        synopsis: ['handoff [<n>] [--plan] [--driver] [--build <slug>]'],
+        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver), or a reminder for a pause already shown',
+        synopsis: ['handoff [<n>] [--full] [--plan] [--driver] [--build <slug>]'],
         args: [{ name: '<n>', gloss: 'step to report on (default: the in-flight step, else the last checkpointed one)' }],
         flags: [
+            { name: '--full', gloss: 'print the whole pause card even when that pause was already shown' },
             { name: '--plan', gloss: 'render the plan-pause card instead of a step tier' },
             { name: '--driver', gloss: "render a driver turn's pointer back at the open step" },
             BUILD_FLAG,
         ],
-        notes: 'Read-only; refuses (exit 1) with no session, or with --plan and --driver together.',
+        notes: 'Writes only the detail file (a blank line around each heading) and the PAUSE stamp; refuses (exit 1) with no session, or with --plan and --driver together.',
     },
     {
         name: 'check',
@@ -140,6 +143,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',
@@ -216,6 +227,13 @@ const VERBS = [
         tolerateUnknownFlags: true,
         notes: 'Reads the hook payload from stdin and always exits 0 — a broken hook must never wedge a prompt.',
     },
+    {
+        name: 'relay',
+        description: 'Stop hook machinery: check that the turn carried the ending it printed (not a user verb)',
+        synopsis: ['relay'],
+        tolerateUnknownFlags: true,
+        notes: "Reads the hook payload from stdin and always exits 0: a broken hook must never wedge a turn's end.",
+    },
 ];
 /**
  * Render the verb table for `plumbbob help`.
@@ -340,6 +358,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':
@@ -368,6 +388,8 @@ async function dispatch(verb, cwd, rest) {
             return agent(cwd, rest);
         case 'turn':
             return turn(cwd, rest);
+        case 'relay':
+            return relay(cwd, rest);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;

package/dist/lib/git.js

@@ -68,18 +68,30 @@ export function hasCommit(root) {
 export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
+/**
+ * The body line that marks a plan commit made by hand (a `chore(plan)`
+ * harvest). A harvest lands between nearly every step, so counting it as
+ * out-of-band would trip the advisory on routine housekeeping and stop meaning
+ * anything within three steps. `status` and `handoff` both pass it to
+ * `commitsSince`, which is what keeps the two counts one quantity.
+ */
+export const PLAN_COMMIT_MARKER = '^plumbbob plan$';
 /**
  * The number of commits on HEAD not reachable from `sha`: `git rev-list
  * --count --first-parent <sha>..HEAD`.
  *
- * `status` reads this for its receipts line: one neutral note when commits
- * landed since the last checkpoint outside plumbbob's ledger (out-of-band
- * commits are surfaced, never blocked). `--first-parent` keeps the count on
- * the branch's own line: merging upstream reads as the one merge commit, not
- * the dozens it carried; those didn't land "outside the ledger" in any sense
- * the receipt should nag about. `excluding` is a commit-message pattern whose
- * matches are left out of the count, which is how a caller drops plumbbob's own
- * commits from a tally of what landed around them.
+ * `status` and `handoff` both read this for their out-of-band count: one
+ * neutral note when commits landed since the last checkpoint outside
+ * plumbbob's ledger (out-of-band commits are surfaced, never blocked). Two
+ * mechanisms keep plumbbob's own commits out of that count. A commit any
+ * plumbbob verb makes is recorded in the ledger and becomes the anchor, so the
+ * range starts after it. A plan commit made by hand carries
+ * `PLAN_COMMIT_MARKER` on a line of its body, and both callers pass it as
+ * `excluding` so the range drops it. `--first-parent` keeps the count on the
+ * branch's own line: merging upstream reads as the one merge commit, not the
+ * dozens it carried; those didn't land "outside the ledger" in any sense the
+ * receipt should nag about. `excluding` is a commit-message pattern whose
+ * matches are left out of the count.
  *
  * Best-effort and never throws: 0 when the range is empty, `sha` is unknown to
  * the repo, or HEAD is unborn: the count is informational (the human commits

package/dist/lib/notice.js

@@ -11,7 +11,10 @@
 // the edge, and an optional indented arrow line carrying what to do next. One
 // shape, so moving it is one edit rather than a sweep. The pointer at the next
 // step is not a line's job: `handoff` renders one, and the verb prints it as
-// the ending's last part. Pure string assembly, no fs, no gate.
+// the ending's last part. The formatters are pure string assembly, no fs, no
+// gate; `printEnding` is the one function here that writes, and every ending
+// a verb prints goes through it so the relay check knows what was said.
+import { writeRelay } from "./sidecar.js";
 /** The column budget a notice line aims to fit, matching the readout fence. */
 const WIDTH = 80;
 /** The fewest detail items a degraded parenthetical still names, so the count has a universe to size. */
@@ -83,6 +86,17 @@ export function blocks(parts) {
     const kept = parts.filter((p) => p !== null && p.trim().length > 0);
     return `${kept.map((p) => p.replace(/\n+$/, '')).join('\n\n')}\n\n`;
 }
+/**
+ * Print an ending to stdout and record it in RELAY, for the Stop check that
+ * the turn closed on it.
+ *
+ * Stdout first, and the record never throws: a failed write leaves the
+ * printed ending and the verb's exit code exactly as they would have been.
+ */
+export function printEnding(root, relay) {
+    process.stdout.write(relay.text);
+    writeRelay(root, relay);
+}
 /**
  * The head, its trailing parenthetical, and the remedy line beneath, assembled.
  *

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 : [],
@@ -702,6 +903,45 @@ export function parseSummary(detail) {
     }
     return { lead, highlights };
 }
+/**
+ * `.plumbbob/detail.md` with a blank line around every heading, and everything
+ * else as written.
+ *
+ * A model copying the detail template can run a heading straight into its body
+ * or its predecessor, and markdownlint's MD022 fails that file wherever
+ * `.plumbbob/` is linted, which turns a downstream checkpoint red. Heading lines
+ * inside a fenced block are content, not headings, so a fence is left whole.
+ * Pure and idempotent: text that already has its blank lines comes back byte for
+ * byte, so a caller can compare the result to the input to learn whether
+ * anything needed fixing.
+ */
+export function normalizeDetailHeadings(detail) {
+    const out = [];
+    let fence = null;
+    let afterHeading = false;
+    for (const line of detail.split('\n')) {
+        if (fence !== null) {
+            const close = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line)?.[1];
+            if (close !== undefined && close.startsWith(fence.char) && close.length >= fence.length) {
+                fence = null;
+            }
+            out.push(line);
+            continue;
+        }
+        const heading = /^ {0,3}#{1,6}(\s|$)/.test(line);
+        const prior = out[out.length - 1];
+        if ((heading || afterHeading) && line.trim() !== '' && prior !== undefined && prior.trim() !== '') {
+            out.push('');
+        }
+        const open = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (open !== undefined) {
+            fence = { char: open.charAt(0), length: open.length };
+        }
+        out.push(line);
+        afterHeading = heading;
+    }
+    return out.join('\n');
+}
 /**
  * The `## <n>` sections of `.plumbbob/detail.md` with their bodies: the full
  * story behind each highlight, in the order the model wrote them. The body is
@@ -756,10 +996,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) => {
@@ -788,10 +1028,16 @@ export function formatOrientation(o) {
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
     // A neutral reconciliation note, only when there is something to reconcile:
     // commits landed since the last checkpoint that plumbbob's ledger didn't
-    // record. Informational: the human commits freely, so this never gates.
+    // record. A commit a plumbbob verb makes starts the range, and a hand-made
+    // plan commit drops out on its `plumbbob plan` body marker, so the count is
+    // the same one `handoff` folds into its Verdict. Informational: the human
+    // commits freely, so this never gates.
     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 +1045,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');