plumbbob 0.13.0 → 0.13.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -131,8 +131,8 @@ In Claude Code, inside any git repo with a clean tree:
 
 1. **Plan.** Fire `/plumbbob:plan` and give it whatever you have: nothing (it interviews
    you), a rough line (`/plumbbob:plan rate-limit POST /login, 5/min/IP, return 429`), or a
-   path to a spec file. Together you fill the build's `intent.md`. No code is written
-   yet.
+   path to a spec file. Together you fill the build's `intent.md`: the steps, and the
+   build ranges that say where the build stops for your call. No code is written yet.
 2. **Build.** Fire `/plumbbob:build`. It implements the next undone step, runs the
    heavy check gate, reviews its own diff against the plan, and stops. What it stops on
    is one block with a fixed shape (the [turn anatomy](docs/presentation.md)): the CLI
@@ -198,7 +198,9 @@ In Claude Code, inside any git repo with a clean tree:
    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
+   *is* the clock tick. When the plan cut build ranges, the line beneath Next Up names
+   one to type instead (`· range 2 of 2: /plumbbob:build 2-3`): it lands each step it
+   names and stops where the plan reserved a call for you. 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
    and why into the build's tracked folder, makes the final commit, and clears the slate
@@ -224,8 +226,8 @@ nothing else:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 | ------------------------------------ | ------ |
-| `/plumbbob:plan` | plan the whole goal: open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
-| `/plumbbob:build` | implement the next planned step, then verify it to the pause: `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then stops |
+| `/plumbbob:plan` | plan the whole goal: open the session and author intent's Frame, Decisions, Constraints, **and all Steps**, with the build ranges that say where the build stops for you |
+| `/plumbbob:build` | implement the next planned step, then verify it to the pause: `--auto` self-approves and chains to done; a range like `1-3`, or a list like `20,5-9`, self-approves exactly the steps it names, then stops |
 | `/plumbbob:finish` | finish up: write the report, make the final commit, clear for a fresh goal |
 
 **Plan-shaping moves**: optional, for when the plan needs work mid-flight:
@@ -233,7 +235,7 @@ nothing else:
 | Skill <img alt="" width="110" height="1"> | Does |
 | ------------------------------------ | ------ |
 | `/plumbbob:step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
-| `/plumbbob:refine` | attack the frame for holes, or repair a drifted plan |
+| `/plumbbob:refine` | attack the frame for holes, or repair a drifted plan (`ranges` re-cuts the build ranges) |
 | `/plumbbob:spike` | throwaway worktree experiment for a fork the plan can't settle |
 
 **Helpers**: orient, verify, recover, diagnose:

package/dist/cli-core.js

@@ -146,10 +146,15 @@ const VERBS = [
     {
         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' }],
+        synopsis: ['order <steps>', 'order --reset'],
+        args: [
+            {
+                name: '<steps>',
+                gloss: 'undone step numbers and spans (2-4) in the sequence to build them, space- or comma-separated (1, 6, 2-4, 7, 5); 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.',
+        notes: 'Writes the one numeric line under `## Build order` in intent.md, which status, build, checkpoint, and handoff all read. A span is spelled out on the line. Refuses (exit 1) with no session, no numbers, a span that runs backward, a number the plan lacks, a repeat, or a step already checkpointed.',
     },
     {
         name: 'spike',

package/dist/lib/latch.js

@@ -17,6 +17,7 @@
 import { readFileSync } from 'node:fs';
 import { grantPath, tickPath, turnPath } from "./sidecar.js";
 import { resolveBoolean } from "./settings.js";
+import { hasStep, normalizeStepList, parseStepList } from "./steplist.js";
 const ALLOW = { allow: true };
 /**
  * The refusal message is the affordance; it tells the model what the pause is,
@@ -51,12 +52,20 @@ const SETTINGS_AUTO_NOTE = `note: \`auto\` is set in settings but is no longer a
 function ceilingMessage(ceiling) {
     return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; run it again to continue.\n`;
 }
+/**
+ * The refusal for a step a list grant does not name, naming the steps it does.
+ */
+function outsideMessage(step, steps) {
+    return `plumbbob: checkpoint refused — step ${step} is not in the range you granted (${normalizeStepList(steps)}) — pause here; run it again to continue.\n`;
+}
 /**
  * The five-row matrix, in order, first hit wins.
  *
- * A `range` grant speaks only to numbered steps: on a `--plan` checkpoint (step
+ * A range grant speaks only to numbered steps: on a `--plan` checkpoint (step
  * null) it neither allows nor refuses, and the decision falls through to the
- * turn comparison.
+ * turn comparison. A `steps` grant lands exactly the steps the human typed and
+ * refuses any other, so no later edit to the plan or its build order can widen
+ * it; both kinds refuse with the `ceiling` reason, a step outside the range.
  */
 export function evaluateLatch(input) {
     if (input.isTTY)
@@ -65,6 +74,11 @@ export function evaluateLatch(input) {
         return ALLOW; // 2: dormant ledger / hand-built diff
     if (input.grant?.kind === 'auto')
         return ALLOW; // 3: one-turn grant the human typed
+    if (input.grant?.kind === 'steps' && input.step !== null) {
+        if (hasStep(input.grant.steps, input.step))
+            return ALLOW;
+        return { allow: false, reason: 'ceiling', message: outsideMessage(input.step, input.grant.steps) };
+    }
     if (input.grant?.kind === 'range' && input.step !== null) {
         if (input.step <= input.grant.ceiling)
             return ALLOW;
@@ -78,15 +92,19 @@ export function evaluateLatch(input) {
     return { allow: false, reason: 'no-turn', message: input.settingsAuto ? base + SETTINGS_AUTO_NOTE : base };
 }
 /**
- * Parse a GRANT file's content (`auto` | `range <M>`).
+ * Parse a GRANT file's content (`auto` | `steps <list>` | `range <M>`).
  *
- * Anything else (including a corrupted or hand-mangled file) contributes
- * nothing: no grant, never an error.
+ * Anything else (including a corrupted or hand-mangled file, or a list that
+ * does not parse) contributes nothing: no grant, never an error.
  */
 export function parseGrant(raw) {
     const trimmed = raw.trim();
     if (trimmed === 'auto')
         return { kind: 'auto' };
+    const listed = /^steps (\S+)$/.exec(trimmed);
+    const steps = listed === null ? null : parseStepList(listed[1] ?? '');
+    if (steps !== null)
+        return { kind: 'steps', steps };
     const range = /^range (\d+)$/.exec(trimmed);
     if (range !== null)
         return { kind: 'range', ceiling: Number(range[1]) };

package/dist/lib/notice.js

@@ -67,13 +67,14 @@ export function advisory(a) {
 }
 /**
  * Assemble a transition's whole ending: the labeled lead line, the Verdict
- * where one was measured, the advisories, and the pointer.
+ * where one was measured, the advisories, the Stop part where a range landed,
+ * and the pointer.
  *
  * The order is the type's field order, so a verb composes parts and never a
  * sequence. A part with nothing in it vanishes rather than leaving a gap.
  */
 export function ending(e) {
-    return blocks([e.lead, e.verdict ?? null, ...(e.advisories ?? []), e.pointer ?? null]);
+    return blocks([e.lead, e.verdict ?? null, ...(e.advisories ?? []), e.stop ?? null, e.pointer ?? null]);
 }
 /**
  * Stack a turn's parts: one blank line between each, one beneath the last.

package/dist/lib/orient.js

@@ -4,6 +4,7 @@
 // contents (no fs), and a malformed document degrades to fewer fields rather
 // than throwing.
 import { parseStepSeam, scopeDrift } from "./intent.js";
+import { expandStepList, formatStepList, hasStep, normalizeStepList, parseStepList, readBuildArgs, } from "./steplist.js";
 /**
  * The lines of a named `## Section`, from its heading to the next `## ` (or
  * EOF), with the offset of the first line so a caller can name an absolute
@@ -74,33 +75,35 @@ 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*,?$/;
+// A build-order line: step numbers and spans (`2-4`) joined by commas, with or
+// without a space after each, and nothing else. A trailing comma is tolerated,
+// since a hand edit leaves one behind.
+const BUILD_ORDER_LINE = /^\d+(?:-\d+)?(?:\s*,\s*\d+(?:-\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.
+ * first line that is nothing but numbers, spans, and commas, in the sequence
+ * written, each span spelled out in place (`1, 6, 2-4` reads 1, 6, 2, 3, 4).
  *
  * 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.
+ * which every picker takes to mean document order, and so does a line holding
+ * a span that runs backward. 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. A span stops at the first number past the
+ * plan, which it keeps for `recover` to name.
  */
 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) {
+    const list = line === undefined ? null : parseStepList(line.replace(/\s+/g, '').replace(/,$/, ''));
+    if (list === null) {
         return [];
     }
-    return line
-        .split(',')
-        .map((n) => n.trim())
-        .filter((n) => n.length > 0)
-        .map(Number);
+    const planned = new Set(parseSteps(intent).map((s) => s.n));
+    return expandStepList(list, (n) => planned.has(n));
 }
 /**
  * The steps in build order: the numbers `order` lists first, in that sequence,
@@ -234,6 +237,246 @@ export function clearBuildOrder(intent) {
     }
     return lines.join('\n');
 }
+// A range's opener: the item's number, the command in backticks, a comma, and
+// the stop's text from `**stop:**` to the end of the line.
+const RANGE_OPENER = /^`([^`]*)`\s*,?\s*\*\*stop:\*\*\s*(.*)$/i;
+// A `<...>` fill-in the template ships, still waiting for its words.
+const FILL_IN = /<[^<>]+>/;
+/**
+ * Parse the ranges under `## Build ranges`: one numbered item per range, the
+ * command in backticks, then `**stop:**` and the stop's text, then an optional
+ * `- model:` sub-line.
+ *
+ * The command's steps go through the turn hook's own reader, so the card can
+ * never suggest a command the hook reads another way. A paragraph before the
+ * list and any sub-line but the model are the reader's. An item still holding
+ * a `<...>` fill-in in its command or stop is scaffold, the template's
+ * placeholder waiting for words, and reads as neither a range nor a report; any
+ * other item that fails the grammar is reported by its number and never
+ * thrown. A plan without the section, a build's record from before ranges
+ * existed under another heading, and a section holding only the placeholder
+ * all read as no ranges.
+ */
+export function parseBuildRanges(intent) {
+    const { offset, lines } = sectionLines(intent, '## Build ranges');
+    const ranges = [];
+    const malformed = [];
+    const openers = lines.flatMap((l, idx) => {
+        const m = /^(\d+)\.\s+(.*)$/.exec(l);
+        return m === null ? [] : [{ item: Number(m[1]), text: m[2] ?? '', idx }];
+    });
+    openers.forEach((o, i) => {
+        const block = lines.slice(o.idx + 1, openers[i + 1]?.idx ?? lines.length);
+        const text = [o.text, ...wrappedLines(block)].join(' ').trim();
+        if (FILL_IN.test(text)) {
+            return;
+        }
+        const range = readRange(o.item, text, block, offset + o.idx + 1);
+        if (range === null) {
+            malformed.push(o.item);
+        }
+        else {
+            ranges.push(range);
+        }
+    });
+    return { ranges, malformed };
+}
+/**
+ * The lines an item's opener wraps onto: each line after it, trimmed, up to the
+ * first blank line, sub-line, or heading.
+ */
+function wrappedLines(block) {
+    const end = block.findIndex((l) => l.trim() === '' || /^\s*[-*+]\s/.test(l) || l.startsWith('#'));
+    return block.slice(0, end === -1 ? block.length : end).map((l) => l.trim());
+}
+/**
+ * One item read as a range, or null when it is not one: a command other than
+ * `/plumbbob:build` with steps and nothing after them, a bare command naming
+ * more than one step, or a stop with no text.
+ */
+function readRange(item, text, block, line) {
+    const m = RANGE_OPENER.exec(text);
+    const args = /^\/plumbbob:build\s+([\d,\s-]+)$/.exec((m?.[1] ?? '').trim())?.[1];
+    const stop = (m?.[2] ?? '').trim();
+    if (args === undefined || stop === '') {
+        return null;
+    }
+    const read = readBuildArgs(args);
+    const single = read.steps?.length === 1 && read.steps[0]?.from === read.steps[0]?.to;
+    if (read.steps === null || (!read.range && !single)) {
+        return null;
+    }
+    const model = /^\s*-\s*model:\s*(.+)$/im.exec(block.join('\n'))?.[1]?.trim() ?? null;
+    return {
+        item,
+        command: (m?.[1] ?? '').trim(),
+        steps: read.steps,
+        bare: !read.range,
+        stop,
+        model: model === null || FILL_IN.test(model) ? null : model,
+        line,
+    };
+}
+/**
+ * Where the build stands in its ranges, read from `step`: the range holding
+ * it, the command that runs what is left of that range, the range its landing
+ * completed, and every range the plan has outgrown.
+ *
+ * Nothing is stored. A range is landed once every step it names is done, and
+ * what is left of it is its undone steps from `step` on, in build order, so a
+ * step pause names what is left once the step in flight lands. A landing
+ * range down to one step writes it `9-9`, which lands it, where a bare range
+ * stays bare. `ordered` is the plan's steps in build order, landed ones
+ * included. With no range that parses, no step sits outside one, so a fresh
+ * build's placeholder flags nothing.
+ */
+export function rangeStanding(plan, ordered, step) {
+    const drift = rangeDrift(plan, ordered);
+    const count = plan.ranges.length + plan.malformed.length;
+    const at = ordered.findIndex((s) => s.n === step);
+    const holding = plan.ranges.find((r) => step !== null && hasStep(r.steps, step));
+    if (holding === undefined) {
+        const outside = step !== null && plan.ranges.length > 0 && ordered[at]?.done === false;
+        return { count, holding: null, command: null, flag: outside ? noRangeWords([step]) : null, completed: null, drift };
+    }
+    const flag = drift.find((d) => d.item === holding.item && d.kind !== 'malformed')?.words ?? null;
+    const left = at === -1 ? [] : ordered.slice(at).filter((s) => !s.done && hasStep(holding.steps, s.n));
+    return {
+        count,
+        holding,
+        command: flag === null && left.length > 0 ? `/plumbbob:build ${leftExpression(holding, left)}` : null,
+        flag,
+        completed: ordered[at]?.done === true && rangeLanded(holding, ordered) ? holding : null,
+        drift,
+    };
+}
+/** Whether a range has landed: the plan holds a step it names, and every one it holds is done. */
+function rangeLanded(range, ordered) {
+    const held = ordered.filter((s) => hasStep(range.steps, s.n));
+    return held.length > 0 && held.every((s) => s.done);
+}
+/**
+ * The ranges block the dashboard renders, and the move it suggests: the range
+ * holding the next undone step and the command that runs what is left of it.
+ *
+ * Null for a plan without ranges, so the block vanishes. The move is null when
+ * the next step sits in no range, its range is flagged, or the step is still
+ * unplanned, which leaves the dashboard's own step move in charge.
+ */
+function rangesView(intent, ordered, next) {
+    const plan = parseBuildRanges(intent);
+    const standing = rangeStanding(plan, ordered, next?.n ?? null);
+    if (standing.count === 0) {
+        return { view: null, move: null };
+    }
+    const own = (item) => standing.drift.filter((d) => d.item === item && d.kind !== 'malformed');
+    const rows = plan.ranges.map((range) => ({
+        range,
+        landed: rangeLanded(range, ordered),
+        next: range === standing.holding,
+        drift: own(range.item).map((d) => d.words),
+    }));
+    const view = { count: standing.count, rows, plan: standing.drift.filter((d) => d.item === null || d.kind === 'malformed').map((d) => d.words) };
+    const { holding, command } = standing;
+    const move = holding === null || command === null || next?.planned !== true ? null : `build range ${holding.item} of ${standing.count} — \`${command}\``;
+    return { view, move };
+}
+/**
+ * What is left of a range as the steps of a command: a landing range's last
+ * step written `9-9` so the command lands it, else the steps in build order
+ * with each climbing run folded to a span, a bare range's lone number included.
+ */
+function leftExpression(range, left) {
+    const ns = left.map((s) => s.n);
+    return !range.bare && ns.length === 1 ? `${ns[0]}-${ns[0]}` : formatStepList(ns);
+}
+/** The words for steps no range names: `no range names step 12`, or `steps 11, 12`. */
+function noRangeWords(steps) {
+    return `no range names ${stepPhrase(steps.map(String)).words}`;
+}
+/**
+ * Every report on the ranges, in the order the dashboard lists them: each
+ * range's own (a step the plan lacks, a step another range also names, a step
+ * from outside it the build order puts among its own), then the undone steps
+ * no range names, then the items that do not parse.
+ *
+ * A step the build order puts inside a range, and a step no range names,
+ * count only while undone, since a landed step cannot cut a run short. The
+ * coverage check runs only once a real range parses.
+ */
+function rangeDrift(plan, ordered) {
+    const own = plan.ranges.flatMap((r) => [
+        ...missingDrift(r, ordered),
+        ...sharedDrift(r, plan.ranges, ordered),
+        ...insideDrift(r, ordered),
+    ]);
+    const outside = ordered.filter((s) => !s.done && !plan.ranges.some((r) => hasStep(r.steps, s.n))).map((s) => s.n);
+    const uncovered = plan.ranges.length > 0 && outside.length > 0 ? [{ kind: 'uncovered', item: null, words: noRangeWords(outside) }] : [];
+    const malformed = plan.malformed.map((item) => ({ kind: 'malformed', item, words: `item ${item} under Build ranges does not parse` }));
+    return [...own, ...uncovered, ...malformed];
+}
+/**
+ * A range naming steps the plan lacks, reported as the spans it names past
+ * the plan's steps, so a span of any width is read without being counted out.
+ */
+function missingDrift(range, ordered) {
+    const held = ordered.map((s) => s.n).sort((a, b) => a - b);
+    const gaps = [];
+    for (const span of range.steps) {
+        let from = span.from;
+        for (const n of held.filter((h) => h >= span.from && h <= span.to)) {
+            if (n > from) {
+                gaps.push({ from, to: n - 1 });
+            }
+            from = Math.max(from, n + 1);
+        }
+        if (from <= span.to) {
+            gaps.push({ from, to: span.to });
+        }
+    }
+    if (gaps.length === 0) {
+        return [];
+    }
+    const { words, be } = stepPhrase(normalizeStepList(gaps).split(','));
+    return [{ kind: 'missing', item: range.item, words: `${words} ${be} not in the plan` }];
+}
+/** A range sharing steps with another range, one report for each other range. */
+function sharedDrift(range, ranges, ordered) {
+    const mine = ordered.filter((s) => hasStep(range.steps, s.n));
+    return ranges.flatMap((other) => {
+        const both = other === range ? [] : mine.filter((s) => hasStep(other.steps, s.n)).map((s) => String(s.n));
+        if (both.length === 0) {
+            return [];
+        }
+        const { words, be } = stepPhrase(both);
+        return [{ kind: 'shared', item: range.item, words: `${words} ${be} also in range ${other.item}` }];
+    });
+}
+/**
+ * A range the build order cuts short: an undone step it does not name, placed
+ * between two of its own, where a run of the range halts.
+ *
+ * An outside step ahead of the range's first step builds first and cuts
+ * nothing, and the card names its range before this one.
+ */
+function insideDrift(range, ordered) {
+    const first = ordered.findIndex((s) => hasStep(range.steps, s.n));
+    const last = ordered.findLastIndex((s) => hasStep(range.steps, s.n));
+    const inside = first === -1 ? [] : ordered.slice(first + 1, last).filter((s) => !s.done && !hasStep(range.steps, s.n));
+    if (inside.length === 0) {
+        return [];
+    }
+    const words = stepPhrase(inside.map((s) => String(s.n))).words;
+    return [{ kind: 'inside', item: range.item, words: `the build order puts ${words} inside it` }];
+}
+/**
+ * Steps as a phrase, with the verb that agrees: `step 12` and `is`, or
+ * `steps 11, 12` and `are`. Each item is a number or a span as it is typed.
+ */
+function stepPhrase(items) {
+    const one = items.length === 1 && /^\d+$/.test(items[0] ?? '');
+    return { words: `${one ? 'step' : 'steps'} ${items.join(', ')}`, be: one ? 'is' : 'are' };
+}
 /**
  * Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section.
  *
@@ -365,27 +608,29 @@ export function lastLedgerSha(checkpoints) {
     return last;
 }
 /**
- * The step number an explicit skill invocation asks for, out of the raw
- * argument text `status --invoked` receives.
+ * The steps an explicit skill invocation asks for, out of the raw argument
+ * text `status --invoked` receives, read the way the turn hook reads a typed
+ * range.
  *
- * The first whitespace-separated token shaped like `22` or `22-24` names the
- * step (a range asks to start at its first number); flags such as `--auto` and
- * anything else parse to null, meaning "no explicit ask", which leaves the
- * dashboard's own suggestion in charge. Null in means null out, so a host that
- * never substitutes the invocation degrades to today's rendering.
+ * A step number names one step, and a range or a list names the steps it
+ * holds (`orient` starts it at the first undone one in build order); `--auto`
+ * alone, a range that does not parse, and free text parse to null, meaning "no
+ * explicit ask", which leaves the dashboard's own suggestion in charge. Null in
+ * means null out, so a host that never substitutes the invocation degrades to
+ * today's rendering.
  */
 export function parseRequestedStep(raw) {
-    if (raw === null) {
-        return null;
-    }
-    for (const token of raw.trim().split(/\s+/)) {
-        const m = /^(\d+)(?:-\d+)?$/.exec(token);
-        if (m) {
-            const n = Number(m[1]);
-            return n >= 1 ? n : null;
-        }
-    }
-    return null;
+    return raw === null ? null : readBuildArgs(raw.trim()).steps;
+}
+/**
+ * The step a requested list starts at: its first undone step in build order,
+ * however the list was written; its first step in build order when every one
+ * has landed; or its first number written when the plan holds none of them, so
+ * the dashboard reports that number missing. Null for an empty list.
+ */
+export function rangeStart(ordered, list) {
+    const named = ordered.filter((s) => hasStep(list, s.n));
+    return (named.find((s) => !s.done) ?? named[0])?.n ?? list[0]?.from ?? null;
 }
 /**
  * The single primary next move the dashboard suggests.
@@ -454,15 +699,22 @@ export function orient(input) {
     const order = parseBuildOrder(input.intent);
     const ordered = orderSteps(steps, order);
     const parks = parseParkTotals(input.buildLog);
+    // The step an explicit ask points at: the number typed, or where a typed
+    // range starts in build order.
+    const requested = input.requested === null ? null : rangeStart(ordered, input.requested);
     // 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 requestedStep = requested === null ? undefined : steps.find((s) => s.n === requested);
     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';
+    // At the boundary with nothing asked for, the move names the range holding
+    // the next step; a spike, a step in flight, or a request keeps its own.
+    const ranges = rangesView(input.intent, ordered, nextUndone);
+    const atBoundary = !input.spiking && input.inFlight === null && requested === null;
     return {
         title: parseTitle(input.intent),
         phase,
@@ -471,9 +723,10 @@ export function orient(input) {
         parked: parks.open,
         parkedTotal: parks.total,
         openQuestions: parseOpenQuestions(input.intent),
-        next: nextMove(input.spiking, ordered, input.inFlight, parks.open, input.requested),
+        next: (atBoundary ? ranges.move : null) ?? nextMove(input.spiking, ordered, input.inFlight, parks.open, requested),
         nextUndone: nextUndone?.n ?? null,
         buildOrder: remainingOrder(steps, order, null),
+        ranges: ranges.view,
         requested: requestedStep?.n ?? null,
         nextDoneWhen: target?.doneWhen ?? null,
         nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
@@ -1024,6 +1277,7 @@ export function formatOrientation(o) {
         return detail.length > 0 ? [head, ...detail].join('\n') : head;
     });
     const stepsBlock = o.steps.length === 0 ? '  (no steps planned yet)' : `  steps  ${doneCount}/${o.steps.length} done\n${stepLines.join('\n')}`;
+    const rangesBlock = o.ranges === null ? [] : [formatRanges(o.ranges), ''];
     const cp = o.lastCheckpoint;
     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:
@@ -1043,6 +1297,7 @@ export function formatOrientation(o) {
         '',
         stepsBlock,
         '',
+        ...rangesBlock,
         cpLine,
         ...receipts,
         ...orderRow,
@@ -1051,3 +1306,22 @@ export function formatOrientation(o) {
         `next → ${o.next}`,
     ].join('\n');
 }
+/**
+ * The dashboard's ranges block, in the step list's own grammar: a count, then a
+ * row per range with its command as the plan wrote it and its model, `✓` for
+ * a range landed and `▸` with the `← next` tail for the one holding the next
+ * step. An undone range carries its stop beneath it, since the stops ahead are
+ * what the human steers by, and a landed one folds to its row. A range's drift
+ * rides beneath it, and the plan's own rows close the block.
+ */
+function formatRanges(view) {
+    const landed = view.rows.filter((r) => r.landed).length;
+    const rows = view.rows.flatMap((r) => {
+        const marker = r.landed ? '✓' : r.next ? '▸' : ' ';
+        const model = r.range.model === null ? '' : ` · ${r.range.model}`;
+        const head = `  ${marker} ${r.range.item}  ${r.range.command}${model}${r.next ? '   ← next' : ''}`;
+        const stop = r.landed ? [] : [`        stop: ${r.range.stop}`];
+        return [head, ...stop, ...r.drift.map((words) => `        ⚠ needs a re-cut: ${words}`)];
+    });
+    return [`  ranges  ${landed} of ${view.count} done`, ...rows, ...view.plan.map((words) => `  ⚠ ${words}`)].join('\n');
+}

package/dist/lib/sidecar.js

@@ -473,6 +473,9 @@ export function clearSpike(root, slug) {
 // `plumbbob turn` (the UserPromptSubmit hook) ticks TURN once per human prompt
 // and rewrites GRANT from the literal prompt; the checkpoint latch reads them to
 // refuse a land until a human turn has intervened since the step was entered.
+// A background job's notice reaches the same hook and ticks neither; PROMPT,
+// beside them, records the id of the last prompt the hook saw, so the hook can
+// tell a notice folded into the running turn from one that starts its own.
 // Kept in the sidecar so the lone GRANT `rmSync` stays where deletions of control
 // state are allowed. ---
 /**
@@ -504,6 +507,41 @@ export function setGrant(root, grant) {
         writeFileSync(grantPath(root), `${grant}\n`);
     }
 }
+/**
+ * PROMPT: the id of the last prompt the turn hook saw, typed or not.
+ */
+export function promptPath(root) {
+    return join(root, DIRNAME, 'PROMPT');
+}
+/**
+ * The id of the last prompt the turn hook saw, or null when none is recorded.
+ *
+ * A notice the harness folds into a running turn arrives under that turn's id,
+ * where one that starts a turn of its own arrives under a fresh one, so the
+ * hook compares a notice's id against this one to tell the two apart.
+ */
+export function readPrompt(root) {
+    try {
+        const id = readFileSync(promptPath(root), 'utf8').trim();
+        return id === '' ? null : id;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record the id of the prompt the hook just saw, or clear the record when the
+ * payload carried none, so a stale id can never make a later notice look as
+ * though it joined the running turn.
+ */
+export function notePrompt(root, id) {
+    if (id === null) {
+        rmSync(promptPath(root), { force: true });
+    }
+    else {
+        writeFileSync(promptPath(root), `${id}\n`);
+    }
+}
 /**
  * TICK: the per-build entry stamp: the TURN value recorded when work was
  * entered (`build <n>` for a step, `start` for the plan), cleared when
@@ -612,6 +650,18 @@ export function writeRelay(root, relay) {
         // A read-only tree or a directory in the way: the ending already printed.
     }
 }
+/**
+ * Drop the recorded ending, so the `Stop` check has nothing to judge until a
+ * verb prints another.
+ *
+ * The turn hook calls this when a background job's notice starts a turn of its
+ * own. The ending was judged when its own turn ended, and a notice leaves TURN
+ * where it was, so without this the notice's turn would read as the one that
+ * printed the ending and be held open for a card the human has already read.
+ */
+export function clearRelay(root) {
+    rmSync(relayPath(root), { force: true });
+}
 /**
  * Stamp the record with the turn the check held open over it, so the check
  * holds at most once per turn. False when the stamp could not be written, and
@@ -739,6 +789,9 @@ export function excludeControl(root) {
         // never writes, and never commits.
         `${DIRNAME}/TURN`,
         `${DIRNAME}/GRANT`,
+        // The id of the last prompt the turn hook saw, which tells a notice folded
+        // into the running turn from one that starts its own.
+        `${DIRNAME}/PROMPT`,
         // The in-flight step's detail file: flat per-session control the model
         // overwrites before every pause. checkpoint records it in the build-log's
         // Log and then clears it, so its archive is the tracked ledger, never this