plumbbob 0.13.0 → 0.13.1

package/dist/lib/steplist.js

@@ -0,0 +1,128 @@
+// A step expression: the one grammar a `/plumbbob:build` range is typed in. The
+// turn hook reads it to mint a grant, the latch to land exactly what the grant
+// names, `build` to say where a range stops, and the dashboard to point at where
+// one starts, so no two of them can read the same keystrokes two ways. An
+// expression is one number, a span `N-M` with N no greater than M, or numbers
+// and spans joined by commas (`20,5-9`). It names plan numbers, never positions
+// in the build order, and it is held as the spans it was written in, so
+// `1-100000` stays two numbers rather than a hundred thousand. Pure: no fs.
+/**
+ * Parse a step expression, or null when it is anything else.
+ *
+ * Every item is a positive number or a span whose first number is no greater
+ * than its last. An empty item, a stray dash, or a space inside the expression
+ * reads as no list at all, so a malformed range names nothing and grants
+ * nothing.
+ */
+export function parseStepList(text) {
+    const spans = [];
+    for (const item of text.split(',')) {
+        const m = /^(\d+)(?:-(\d+))?$/.exec(item);
+        if (m === null)
+            return null;
+        const from = Number(m[1]);
+        const to = m[2] === undefined ? from : Number(m[2]);
+        if (!Number.isSafeInteger(to) || from < 1 || to < from)
+            return null;
+        spans.push({ from, to });
+    }
+    return spans;
+}
+/** Whether a list names step `n`. */
+export function hasStep(list, n) {
+    return list.some((span) => n >= span.from && n <= span.to);
+}
+/**
+ * Write steps back as an expression in the order given, folding each run that
+ * climbs by one into a span: `[20, 5, 6, 7, 8, 9]` writes `20,5-9`.
+ *
+ * The order is the caller's, because a list has none of its own: the card
+ * writes one in build order, so its first number is where the range starts.
+ */
+export function formatStepList(steps) {
+    const runs = [];
+    for (const n of steps) {
+        const last = runs.at(-1);
+        if (last !== undefined && n === last.to + 1) {
+            last.to = n;
+        }
+        else {
+            runs.push({ from: n, to: n });
+        }
+    }
+    return runs.map(spanText).join(',');
+}
+/**
+ * A list's normal form: its spans sorted and merged, so two ways of typing the
+ * same steps write the same line (`20, 5-9` and `5-9,20` both write `5-9,20`).
+ *
+ * The grant stores this form and never the expansion, so a range of any length
+ * is one short line.
+ */
+export function normalizeStepList(list) {
+    const merged = [];
+    for (const span of [...list].sort((a, b) => a.from - b.from)) {
+        const last = merged.at(-1);
+        if (last !== undefined && span.from <= last.to + 1) {
+            last.to = Math.max(last.to, span.to);
+        }
+        else {
+            merged.push({ from: span.from, to: span.to });
+        }
+    }
+    return merged.map(spanText).join(',');
+}
+/**
+ * The numbers a list names, in the order written, each span walked only while
+ * `known` holds and stopped at the first number it does not, which is kept.
+ *
+ * A build order is a sequence rather than a set, so its spans expand in place
+ * (`1,6,2-4` names 1, 6, 2, 3, 4). The number kept past the plan is the one a
+ * caller reports the plan lacks, and stopping there means `2-100000` costs one
+ * number past the last planned step rather than a hundred thousand.
+ */
+export function expandStepList(list, known) {
+    const numbers = [];
+    for (const span of list) {
+        for (let n = span.from; n <= span.to; n += 1) {
+            numbers.push(n);
+            if (!known(n))
+                break;
+        }
+    }
+    return numbers;
+}
+/** One span as it is typed: a lone number, or `from-to`. */
+function spanText(span) {
+    return span.from === span.to ? String(span.from) : `${span.from}-${span.to}`;
+}
+/**
+ * Read the arguments a build invocation carries, up to the first token that is
+ * not one: `--auto`, or a run of digits, commas, and dashes.
+ *
+ * Once any number carries a comma or a dash, every number and span in the run
+ * joins one list, so `20, 5-9` typed with a space reads as `20,5-9`. Trailing
+ * sentence punctuation is the sentence's (`/build 1-3.`), and so is a comma
+ * after the run's last number (`/build 2, then review`), which separates
+ * nothing.
+ */
+export function readBuildArgs(text) {
+    let auto = false;
+    const words = [];
+    for (const token of text.split(/\s+/)) {
+        const word = token.replace(/[.;:!?]+$/, '');
+        if (word === '')
+            continue;
+        if (word === '--auto') {
+            auto = true;
+            continue;
+        }
+        if (!/^[\d,-]+$/.test(word))
+            break;
+        words.push(word);
+    }
+    const items = words.map((w, i) => (i === words.length - 1 ? w.replace(/,+$/, '') : w)).filter((w) => w !== '');
+    const range = items.some((w) => /[,-]/.test(w));
+    const steps = items.length === 0 ? null : parseStepList(items.join(',').replace(/,{2,}/g, ','));
+    return { auto, range, steps };
+}

package/dist/verbs/build.js

@@ -8,18 +8,21 @@ 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 { parseOrderedSteps, skippedBefore } from "../lib/orient.js";
+import { parseBuildRanges, parseOrderedSteps, rangeStanding, rangeStart, skippedBefore } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 import { readGrant } from "../lib/latch.js";
 import { notice } from "../lib/notice.js";
+import { hasStep, readBuildArgs } from "../lib/steplist.js";
 /**
  * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
- * Refuses a missing session, a malformed step argument, an `N-M` range (a
- * `/plumbbob:build` skill feature, not a CLI one), and a seam that fails to parse.
+ * Refuses a missing session, a malformed step argument, a range such as `N-M`
+ * or `20,5-9` (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 names the step when it is the last one a
- * self-approval grant reaches.
+ * self-approval grant reaches, or, under `--auto`, a call the plan's ranges
+ * reserve for the human.
  */
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -29,15 +32,15 @@ export function build(cwd, args) {
     }
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
-    // A step range like `1-3` is a `/plumbbob:build` skill affordance (auto-approve
-    // every step through the range's top, then stop), not a CLI capability: the CLI
+    // A step range like `1-3` or `20,5-9` is a `/plumbbob:build` skill affordance
+    // (auto-approve each step it names, then stop), not a CLI capability: the CLI
     // records one in-flight step at a time. Name it rather than bounce off the
-    // generic usage.
-    if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
+    // generic usage, and point at the step the range starts at.
+    if (raw !== undefined && /^\d[\d,-]*$/.test(raw) && /[,-]/.test(raw)) {
         process.stderr.write(notice({
             fact: 'build takes one step number',
             detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through its top and then stops`],
-            remedy: `plumbbob build ${raw.split('-')[0]}`,
+            remedy: `plumbbob build ${rangeEntry(intentPath(root, slug), rest.join(' '), raw)}`,
         }));
         return 1;
     }
@@ -100,11 +103,15 @@ export function build(cwd, args) {
         : skipped > 0
             ? ['explicitly requested', `skips ${skipped} undone step${skipped === 1 ? '' : 's'}`]
             : [];
-    // 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.
+    // Two lines (three on the last step a grant reaches, or on a call the plan
+    // reserves), 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.
+    // A reserved call outranks the last-step line, since the step stops at its
+    // pause rather than landing.
+    const grant = readGrant(root);
+    const reserved = grant?.kind === 'auto' ? reservedCallNotice(intent, steps, step) : '';
     process.stdout.write(notice({ fact: `building step ${step}`, detail: picked }) +
-        lastGrantedNotice(readGrant(root), steps, step) +
+        (reserved.length > 0 ? reserved : lastGrantedNotice(grant, steps, step)) +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],
@@ -112,6 +119,45 @@ export function build(cwd, args) {
         `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }
+/**
+ * The step a range typed at the CLI starts at: its first undone step in build
+ * order when the plan reads, else its first number written.
+ *
+ * Best-effort, since it only fills the refusal's remedy: a plan that cannot be
+ * read, or a range that does not parse, still points at a number the human typed.
+ */
+function rangeEntry(intent, args, raw) {
+    const list = readBuildArgs(args).steps;
+    try {
+        const start = list === null ? null : rangeStart(parseOrderedSteps(readFileSync(intent, 'utf8')), list);
+        if (start !== null)
+            return String(start);
+    }
+    catch {
+        // No plan to order by: fall back to the number typed first.
+    }
+    return /\d+/.exec(raw)?.[0] ?? '1';
+}
+/**
+ * The line saying a step ends at its pause under `--auto`, because the plan's
+ * build ranges name it as a bare range: a call the plan reserves for the
+ * human. '' for any other step.
+ *
+ * The halt is this line's and the skill's, never the latch's: the ranges are
+ * advice, so `--auto` still grants the checkpoint, and saying so as the step
+ * is entered is what puts the stop in front of the model before it lands one.
+ */
+function reservedCallNotice(intent, steps, step) {
+    const { count, holding } = rangeStanding(parseBuildRanges(intent), steps, step);
+    if (holding === null || !holding.bare) {
+        return '';
+    }
+    return notice({
+        fact: `step ${step} ends at its pause, where the plan reserves the call for the human`,
+        detail: [`range ${holding.item} of ${count}`],
+        remedy: 'hold it there for their approval, --auto or not',
+    });
+}
 /**
  * The line naming the last step a self-approval grant reaches this turn, or ''
  * for any other step and when no grant is live.
@@ -123,13 +169,26 @@ export function build(cwd, args) {
  * 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.
+ * `--auto` reaches the plan's last undone step. A range that lists its steps
+ * walks them in build order, so its top is the last undone step it names, and
+ * it reaches no further than a step it does not name.
  */
 function lastGrantedNotice(grant, steps, step) {
     if (grant === null) {
         return '';
     }
     const remedy = 'land it on green, then stop at the boundary';
+    if (grant.kind === 'steps') {
+        if (!hasStep(grant.steps, step))
+            return '';
+        const rest = steps.slice(steps.findIndex((s) => s.n === step) + 1).filter((s) => !s.done && s.n !== step);
+        const after = rest[0];
+        if (after !== undefined && hasStep(grant.steps, after.n))
+            return '';
+        return rest.some((s) => hasStep(grant.steps, s.n))
+            ? notice({ fact: `step ${step} is the last undone step in the range you granted`, remedy })
+            : notice({ fact: `step ${step} is the top of the range you granted`, remedy });
+    }
     if (grant.kind === 'range') {
         if (step === grant.ceiling) {
             return notice({ fact: `step ${step} is the top of the range you granted`, remedy });

package/dist/verbs/checkpoint.js

@@ -129,6 +129,7 @@ export async function checkpoint(cwd, args) {
             lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
             verdict: landed.verdict,
             advisories: [drift, flipNotice],
+            stop: landed.stop,
             pointer: landed.pointer,
         }),
     });

package/dist/verbs/handoff.js

@@ -41,10 +41,10 @@ import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { PLAN_COMMIT_MARKER, commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.js";
-import { blocks, printEnding } from "../lib/notice.js";
+import { blocks, printEnding, transition } from "../lib/notice.js";
 import { isArtifactPath, parseStepSeam } from "../lib/intent.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";
+import { buildOrderPhrase, countDiff, diffRowValue, foldVerdict, lastLedgerSha, normalizeDetailHeadings, parkedPhrase, parseBuildOrder, parseBuildRanges, parseConstraintCount, parseLastCheckpoint, parseOrderedSteps, parseParkTotals, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, rangeStanding, 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.
@@ -108,7 +108,7 @@ export function handoff(cwd, args = []) {
         const detail = settleDetail(root, rawDetail);
         const plan = [
             SEAM_RULE,
-            nextUpBlock(first, steps.length, where, nextUpNote(intent, buildLog, null)),
+            nextUpBlock(intent, buildLog, first, null, where),
             planCallBlock(first),
         ];
         const command = reprintCommand('--plan', undefined, named);
@@ -137,7 +137,7 @@ export function handoff(cwd, args = []) {
     if (current === null) {
         // Nothing measured yet (a fresh session): no Verdict, just the forward pointer.
         return emit(root, { tier: 'orientation', render: 'pointer' }, [
-            nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)),
+            nextUpBlock(intent, buildLog, nextUp, current, where),
         ]);
     }
     // A step is pending, and its hand-off is the pause, while it is in flight.
@@ -147,11 +147,12 @@ export function handoff(cwd, args = []) {
     // 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.
+        // The boundary: the orientation-tier ending, the state word, the Stop part
+        // where a range just landed, and the forward pointer, no decision pending
+        // and so no Your Call. The same parts the checkpoint printed for itself,
+        // from the same call.
         const landed = boundaryEnding(root, slug, current);
-        return emit(root, { tier: 'orientation', render: 'boundary' }, [landed.verdict, landed.pointer]);
+        return emit(root, { tier: 'orientation', render: 'boundary' }, [landed.verdict, landed.stop, 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
@@ -197,7 +198,7 @@ export function handoff(cwd, args = []) {
     if (inline) {
         parts.push(fence('diff', patch.split('\n')).join('\n'));
     }
-    parts.push(verdict, nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)), yourCallBlock(current, checkGreen));
+    parts.push(verdict, nextUpBlock(intent, buildLog, nextUp, current, where), yourCallBlock(current, checkGreen));
     const command = reprintCommand('--full', explicit, named);
     return emit(root, { tier: 'decision', render: 'card', command }, withRecommendation(parts, parseRecommendation(detail)));
 }
@@ -267,25 +268,52 @@ function writePause(root, slug, stamp) {
     }
 }
 /**
- * The two CLI-rendered parts of a boundary ending: the Verdict folded from
- * everything measurable right now, and the pointer at the step to come.
+ * The CLI-rendered parts of a boundary ending: the Verdict folded from
+ * everything measurable right now, the Stop part when the landing finished a
+ * range, and the pointer at the step to come.
  *
  * `step` is the step that just landed, or null at a plan commit, where nothing
- * was measured and the Verdict vanishes. A transition verb prints these beneath
- * its own lead line, so a boundary reads identically whether `checkpoint`
- * emitted it or a later `handoff` did; the paths a stray advisory named are the
- * one part that does not survive, and the commit holds those.
+ * was measured and the Verdict and the Stop part both vanish. A transition verb
+ * prints these beneath its own lead line, so a boundary reads identically
+ * whether `checkpoint` emitted it or a later `handoff` did; the paths a stray
+ * advisory named are the one part that does not survive, and the commit holds
+ * those.
  */
 export function boundaryEnding(root, slug, step) {
     const intent = readOr(intentPath(root, slug));
     const steps = parseOrderedSteps(intent);
     const nextUp = steps.find((s) => !s.done && s.n !== step);
-    const note = nextUpNote(intent, readOr(buildLogPath(root, slug)), step);
+    const where = relative(root, intentPath(root, slug));
     return {
         verdict: step === null ? null : landedVerdict(root, slug, intent, step),
-        pointer: nextUpBlock(nextUp, steps.length, relative(root, intentPath(root, slug)), note),
+        stop: stopLine(intent, steps, step, where),
+        pointer: nextUpBlock(intent, readOr(buildLogPath(root, slug)), nextUp, step, where),
     };
 }
+/**
+ * The Stop part: why the build stops at this boundary, when the step that
+ * landed was the last undone step of a range that lands its steps. One labeled
+ * line, the range over the count, a plain hyphen, the stop as the plan wrote
+ * it, and a bracket pointing at the item, where its note can be read.
+ *
+ * Null for every other boundary: a landing that leaves the range open, a bare
+ * range (its stop was its own pause), a plan without ranges, and the plan
+ * commit, where nothing landed.
+ */
+function stopLine(intent, steps, step, where) {
+    if (step === null) {
+        return null;
+    }
+    const { count, completed } = rangeStanding(parseBuildRanges(intent), steps, step);
+    if (completed === null || completed.bare) {
+        return null;
+    }
+    return transition({
+        label: 'Stop',
+        fact: `Range ${completed.item} of ${count} landed - ${completed.stop}`,
+        detail: [`details: \`${where}:${completed.line}\``],
+    });
+}
 /**
  * The step's record for the build-log's Log: the pause as the human approved
  * it, with the full story behind each highlight beneath. The Summary and its
@@ -658,10 +686,11 @@ function spikeNextUpLine(inFlight) {
 // 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
+ * The line beneath the forward pointer: the range segment, when the plan
+ * declares build ranges; the build order from the step the pointer names, when
+ * `## Build order` re-sequences the plan away from its numbering; and the park
+ * count, when anything has been parked. '' when none says anything, so a plan
+ * with no ranges, nobody re-sequenced, and an empty park list renders the
  * pointer alone, as before.
  *
  * Indented two spaces, because an indented line continues the part above it
@@ -670,9 +699,10 @@ const ORDER_CAP = 5;
  * `Nothing planned`: an unharvested list at the end of the plan is the one
  * reminder that matters there.
  */
-function nextUpNote(intent, buildLog, exclude) {
+function nextUpNote(intent, buildLog, exclude, range) {
     const parks = parseParkTotals(buildLog);
     const segments = [
+        range,
         buildOrderPhrase(remainingOrder(parseSteps(intent), parseBuildOrder(intent), exclude), ORDER_CAP),
         parks.total > 0 ? parkedPhrase(parks) : '',
     ].filter((s) => s.length > 0);
@@ -681,11 +711,41 @@ function nextUpNote(intent, buildLog, exclude) {
 /**
  * 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.
+ *
+ * `exclude` is the step the turn is about: the step in flight at a pause, the
+ * step just landed at a boundary, null at the plan pause and the plan commit.
+ * While the note suggests a range, the bracket bolds the range's model, since
+ * the run is the range and that is the `/model` the human picks before typing
+ * it.
  */
-function nextUpBlock(nextUp, total, where, note) {
-    const line = nextUpLine(nextUp, total, where);
+function nextUpBlock(intent, buildLog, nextUp, exclude, where) {
+    const steps = parseOrderedSteps(intent);
+    const range = rangeSegment(intent, steps, nextUp, exclude);
+    const line = nextUpLine(nextUp, steps.length, where, range.model ?? nextUp?.model ?? null);
+    const note = nextUpNote(intent, buildLog, exclude, range.segment);
     return note.length === 0 ? line : `${line}\n${note}`;
 }
+/**
+ * The range segment that leads the note, and the model the pointer's bracket
+ * bolds while it suggests a range: `range 3 of 5: /plumbbob:build 6-9` with
+ * the range's model, the re-cut words for a flagged range, the words for a step
+ * no range names, or '' for a plan without ranges.
+ *
+ * The step the turn is about reads as landed, so a step pause names what is
+ * left of the range once the step in flight lands. A flagged range, and a
+ * range with no `- model:` line, leave the step's model in the bracket.
+ */
+function rangeSegment(intent, steps, nextUp, exclude) {
+    const landed = steps.map((s) => (s.n === exclude ? { ...s, done: true } : s));
+    const { count, holding, command, flag } = rangeStanding(parseBuildRanges(intent), landed, nextUp?.n ?? null);
+    if (holding !== null && command !== null) {
+        return { segment: `range ${holding.item} of ${count}: ${command}`, model: holding.model };
+    }
+    if (flag === null) {
+        return { segment: '', model: null };
+    }
+    return { segment: holding === null ? flag : `range ${holding.item} of ${count} needs a re-cut (${flag})`, model: null };
+}
 /**
  * The forward pointer: the next undone step with the progress count, its
  * title, and a closing bracket carrying its advisory `- model:` recommendation
@@ -698,12 +758,12 @@ function nextUpBlock(nextUp, total, where, note) {
  * 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) {
+function nextUpLine(nextUp, total, where, model = nextUp?.model ?? null) {
     if (nextUp === undefined) {
         return '**Next Up**: Nothing planned - /plumbbob:step or /plumbbob:finish';
     }
     const title = nextUp.title.length > 0 ? ` - ${nextUp.title}` : '';
-    const token = modelToken(nextUp.model);
+    const token = modelToken(model);
     const bracket = token === null ? [] : [`model: **${capitalize(token)}**`];
     bracket.push(`details: \`${where}:${nextUp.line}\``);
     return `**Next Up**: Step ${nextUp.n} of ${total}${title} (${bracket.join(', ')})`;

package/dist/verbs/order.js

@@ -14,16 +14,18 @@ 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 { expandStepList, parseStepList } from "../lib/steplist.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`.
+ * Set the build order to the given step numbers and spans, 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.
+ * The line written is the whole remaining sequence, each span spelled out, 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
+ * neither a number nor a span, a number the plan lacks, a repeated number, or a
+ * step already checkpointed.
  */
 export function order(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -45,8 +47,9 @@ export function order(cwd, args) {
         });
         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.
+    // Numbers and spans arrive space- or comma-separated, with or without a space
+    // after a comma: `order 7 8 5`, `order 7,8,5`, and `order 1, 6, 2-4, 7, 5`
+    // all read, and a span names its steps in place, since the line is a sequence.
     const tokens = args
         .filter((a) => !a.startsWith('--'))
         .flatMap((a) => a.split(','))
@@ -60,14 +63,15 @@ export function order(cwd, args) {
         }));
         return 1;
     }
-    const stray = tokens.find((t) => !/^\d+$/.test(t));
+    const lists = tokens.map(parseStepList);
+    const stray = tokens.find((_, i) => lists[i] === null);
     if (stray !== undefined) {
-        process.stderr.write(notice({ fact: `\`${stray}\` is not a step number`, remedy: 'plumbbob order 7 8 5' }));
+        process.stderr.write(notice({ fact: `\`${stray}\` is not a step number or span`, remedy: 'plumbbob order 1, 6, 2-4, 7, 5' }));
         return 1;
     }
-    const given = tokens.map(Number);
     const steps = parseSteps(intent);
     const planned = steps.map((s) => s.n);
+    const given = expandStepList(lists.flatMap((list) => list ?? []), (n) => planned.includes(n));
     const unknown = given.find((n) => !planned.includes(n));
     if (unknown !== undefined) {
         process.stderr.write(notice({

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 { parseBuildOrder, parseSteps } from "../lib/orient.js";
+import { parseBuildOrder, parseBuildRanges, parseOrderedSteps, parseSteps, rangeStanding } 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";
 /**
@@ -94,6 +94,7 @@ function sessionFindings(root) {
     const stepInFlight = existsSync(stepPath(root, slug));
     findings.push(...phaseFindings(root, slug, stepInFlight));
     findings.push(...orderFindings(root, slug));
+    findings.push(...rangeFindings(root, slug));
     findings.push(...leftoverFindings(root, slug, stepInFlight));
     return findings;
 }
@@ -126,6 +127,35 @@ function orderFindings(root, slug) {
         },
     ];
 }
+/**
+ * A build range naming a step the plan does not hold.
+ *
+ * The section under `## Build ranges` is hand-editable, and a refine can drop
+ * a step a range names; the card then suggests no command for that range, and
+ * the dashboard says why. Reported beside the build order's own finding, never
+ * repaired: where the stop belongs now is the human's call. Silent while the
+ * plan declares no ranges.
+ */
+function rangeFindings(root, slug) {
+    const intent = readOr(intentPath(root, slug));
+    const plan = parseBuildRanges(intent);
+    if (plan.ranges.length === 0) {
+        return [];
+    }
+    const missing = rangeStanding(plan, parseOrderedSteps(intent), null).drift.filter((d) => d.kind === 'missing');
+    if (missing.length === 0) {
+        const count = `${plan.ranges.length} range${plan.ranges.length === 1 ? '' : 's'}`;
+        return [{ name: 'build ranges', ok: true, detail: `every step they name is planned (${count})` }];
+    }
+    return [
+        {
+            name: 'build ranges',
+            ok: false,
+            detail: missing.map((d) => `range ${d.item} names a step the plan lacks: ${d.words}`).join('; '),
+            hint: 're-cut the range under ## Build ranges by hand, or with /plumbbob:refine',
+        },
+    ];
+}
 /**
  * The cursor names a build that is not there.
  *