plumbbob 0.12.1 → 0.13.1

package/dist/verbs/start.js

@@ -10,7 +10,7 @@ import { readTemplate, stampTemplate } from "../lib/templates.js";
 import { findRepoRoot, hasCommit, headSha, isDirty, isIgnored } from "../lib/git.js";
 import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
 import { settingsPath } from "../lib/settings.js";
-import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
 /**
  * Human-readable echo of the default check gate, stamped into the templates'
  * {{CHECK}} line.
@@ -177,15 +177,19 @@ export async function start(cwd, args) {
     // No pointer: the plan skill owns the turn that follows, and there is no step
     // yet to aim at, so the ending closes on the remedy line that says where to
     // frame the build.
-    process.stdout.write(ending({
-        lead: transition({
-            label: 'Session',
-            fact: `started "${title}"`,
-            detail: [`baseline ${sha.slice(0, 9)}`],
-            remedy: `frame and decide in ${intentLocation}, then build a step`,
+    printEnding(root, {
+        tier: 'driver',
+        render: 'start',
+        text: ending({
+            lead: transition({
+                label: 'Session',
+                fact: `started "${title}"`,
+                detail: [`baseline ${sha.slice(0, 9)}`],
+                remedy: `frame and decide in ${intentLocation}, then build a step`,
+            }),
+            advisories,
         }),
-        advisories,
-    }));
+    });
     return 0;
 }
 /**

package/dist/verbs/status.js

@@ -6,7 +6,7 @@
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { commitsSince, findRepoRoot } from "../lib/git.js";
+import { PLAN_COMMIT_MARKER, commitsSince, findRepoRoot } from "../lib/git.js";
 import { SLOTS, readHarnessFile, resolveAgent, } from "../lib/agents.js";
 import { buildFolder, buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { formatOrientation, lastLedgerSha, orient, parseRequestedStep } from "../lib/orient.js";
@@ -80,7 +80,7 @@ export function status(cwd, args = []) {
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
         spiking: inSpike(root, slug),
         requested: parseRequestedStep(invoked),
-        outOfBand: anchor === null ? 0 : commitsSince(root, anchor),
+        outOfBand: anchor === null ? 0 : commitsSince(root, anchor, PLAN_COMMIT_MARKER),
     });
     const lines = [formatOrientation(orientation), ...harnessSection(root, slug)];
     process.stdout.write(`${lines.join('\n')}\n`);

package/dist/verbs/turn.js

@@ -1,32 +1,39 @@
 // `plumbbob turn`: the turn-ledger hook. Wired to the harness's
-// UserPromptSubmit event, it runs once per human prompt and maintains two of the
+// UserPromptSubmit event, it runs once per prompt and maintains two of the
 // sidecar's git-excluded control files (flat files under `.plumbbob/`): it ticks
 // `TURN`, the monotonic count of human turns the checkpoint latch compares
 // against a step's entry stamp to know a human turn intervened since the step
 // began, and it rewrites `GRANT` from the literal prompt, minting a one-turn
-// self-approval only when the human typed `/build --auto` or an `N-M` step
-// range, clearing it otherwise (those strings can only come from a human
+// self-approval only when the human typed `/build --auto` or a step range
+// (`N-M`, or a list such as `20,5-9`), clearing it otherwise (those strings can only come from a human
 // keystroke, because `build` is disable-model-invocation: a grant the model
-// could forge would be no grant). When a step is in flight it also emits ONE
-// `UserPromptSubmit` additionalContext line so a fresh session (post-compaction,
-// or a scripted `-p` turn where no skill prose is in context) still knows the
-// beat: a tangent is parked, not chased. Guidance only: it blocks nothing. It
-// ALWAYS exits 0 and any failure degrades to no output, so neither the tick nor
-// the emit can ever wedge prompting.
+// could forge would be no grant). The harness also sends a background job's
+// completion notice through this event, as a prompt the human never typed, so
+// a notice ticks nothing, keeps the grant, and clears only the ending `RELAY`
+// holds from an earlier turn. When a step is in flight a typed prompt also
+// emits ONE `UserPromptSubmit` additionalContext line so a fresh session
+// (post-compaction, or a scripted `-p` turn where no skill prose is in context)
+// still knows the beat: a tangent is parked, not chased, and a message that
+// also asks something is answered before the park's block. Guidance only: it
+// blocks nothing. It ALWAYS exits 0 and any failure degrades to no output, so
+// neither the tick nor the emit can ever wedge prompting.
 import { readFileSync, writeFileSync } from 'node:fs';
-import { findSessionRoot, setGrant, stepPath, turnPath } from "../lib/sidecar.js";
+import { clearRelay, findSessionRoot, notePrompt, readPrompt, setGrant, stepPath, turnPath, } from "../lib/sidecar.js";
+import { normalizeStepList, readBuildArgs } from "../lib/steplist.js";
 /**
- * The hook entry point: apply the tick, then emit the in-flight-step nudge.
+ * The hook entry point: apply the prompt, then emit the in-flight-step nudge
+ * when it counted as a human turn.
  *
  * Always returns 0: a broken turn must never wedge a prompt, so any failure is
  * swallowed and degrades to no output.
  */
 export function turn(cwd, _args) {
     try {
-        applyTurn(cwd, readStdin());
-        const context = stepInFlightContext(cwd);
-        if (context !== null)
-            process.stdout.write(context);
+        if (applyTurn(cwd, readStdin())) {
+            const context = stepInFlightContext(cwd);
+            if (context !== null)
+                process.stdout.write(context);
+        }
     }
     catch {
         // A broken turn must never wedge a prompt: swallow and exit 0.
@@ -39,8 +46,10 @@ export function turn(cwd, _args) {
  * A step is in flight when a STEP marker (the flat control file recording the
  * step between `build` and `checkpoint`) is present. Guidance only: it reminds a
  * fresh session that a tangent is a park (not an edit), that the park's own
- * block is the whole turn, and how the step lands, since neither the build nor
- * the park prose may be in context after compaction or on a scripted turn.
+ * block is the whole turn when the message is only a tangent, that a message
+ * which also asks something is answered first with the block after the answer,
+ * and how the step lands, since neither the build nor the park prose may be in
+ * context after compaction or on a scripted turn.
  * Exported because an in-process test cannot read the hook's real stdout.
  */
 export function stepInFlightContext(cwd) {
@@ -53,6 +62,9 @@ export function stepInFlightContext(cwd) {
     const text = `plumbbob: step ${step} is in flight — a new idea or tangent is a park, not an edit: ` +
         `capture it with \`plumbbob park "<one line>"\` and relay the block it prints whole, ` +
         `with nothing written around it, since that block is the whole turn. ` +
+        `The one exception is a message that also asks something: answer the question first, ` +
+        `then relay the park's block after the answer and write nothing after it. ` +
+        `The block's pointer back at the step closes the turn either way, so run no \`plumbbob handoff\` after it. ` +
         `The step stays open and lands when you run \`plumbbob checkpoint ${step}\` after approval.`;
     return `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } })}\n`;
 }
@@ -72,7 +84,17 @@ function inFlightStep(root) {
     }
 }
 /**
- * The testable core: apply one tick given the raw hook stdin.
+ * The testable core: apply one prompt given the raw hook stdin, and say
+ * whether it counted as a human turn.
+ *
+ * A typed prompt ticks TURN and rewrites GRANT. A notice touches neither,
+ * because the latch reads TURN passing a step's entry stamp as its one sign
+ * that a human answered, and a grant the human typed has to outlive a job
+ * that reports back partway through the range. A notice that starts a turn of
+ * its own clears RELAY, whose ending was judged when its own turn ended; one
+ * the harness folds into the running turn arrives under that turn's prompt id
+ * and leaves RELAY alone, since the ending the turn just printed has yet to be
+ * judged.
  *
  * Split from the fd-0 read so the unit tests can drive it directly: an
  * in-process test cannot feed fd 0 (the same constraint checkpoint's `--body`
@@ -81,10 +103,35 @@ function inFlightStep(root) {
 export function applyTurn(cwd, raw) {
     const root = findSessionRoot(cwd);
     if (root === null)
-        return 0; // no active session above cwd: silent no-op.
-    writeFileSync(turnPath(root), `${readTurn(root) + 1}\n`);
-    setGrant(root, grantFromPrompt(extractPrompt(raw)));
-    return 0;
+        return false; // no active session above cwd: silent no-op.
+    const { prompt, promptId } = readPayload(raw);
+    const notice = isNotice(prompt);
+    if (notice) {
+        if (promptId === null || promptId !== readPrompt(root))
+            clearRelay(root);
+    }
+    else {
+        writeFileSync(turnPath(root), `${readTurn(root) + 1}\n`);
+        setGrant(root, grantFromPrompt(prompt));
+    }
+    // Last, so a record that cannot be written never costs the tick or the grant.
+    notePrompt(root, promptId);
+    return !notice;
+}
+/**
+ * Whether a prompt is the harness reporting on background work rather than
+ * the human typing.
+ *
+ * Nothing in the payload marks one, but every notice opens on a frame of the
+ * harness's own at its very first character: `<task-notification>` for a
+ * finished shell job, a Monitor event, or a subagent's task, and
+ * `<agent-message ` for a subagent's or another session's report. A misread
+ * errs safe: a typed prompt taken for a notice costs one tick and one grant,
+ * so the latch only grows stricter, while a notice taken for a typed prompt
+ * is a turn no human took.
+ */
+export function isNotice(prompt) {
+    return prompt.startsWith('<task-notification>') || prompt.startsWith('<agent-message ');
 }
 /**
  * Derive the GRANT content from the human's prompt, or null to clear it.
@@ -92,9 +139,12 @@ export function applyTurn(cwd, raw) {
  * A grant is minted only from a literal `build` invocation the human typed:
  * `build` is disable-model-invocation, so this string can only come from a
  * human keystroke, never model-authored pressure: a grant the model can forge
- * is no grant. A bounded range beats `--auto` (bounded wins); a bare
- * `/build`, or any non-invocation prompt, mints nothing. The namespaced
- * `/plumbbob:build` form is honored alongside the bare one.
+ * is no grant. A range mints `steps <list>`, exactly the steps it names in
+ * their normal form (`20, 5-9` mints `steps 5-9,20`), and beats `--auto`
+ * (bounded wins), so a range that does not parse mints nothing rather than
+ * falling back to `auto`. A bare `/build`, a bare step number, or any
+ * non-invocation prompt mints nothing. The namespaced `/plumbbob:build` form is
+ * honored alongside the bare one.
  *
  * The invocation must *start* a token: a slash preceded by a word character,
  * `/`, `.`, `-`, or `~` is a path segment (`src/build`, `./build`), not a
@@ -114,43 +164,30 @@ export function grantFromPrompt(prompt) {
     if (invocation === null)
         return null;
     const line = prompt.slice(invocation.index + invocation[0].length).split('\n', 1)[0] ?? '';
-    let auto = false;
-    let ceiling;
-    for (const token of line.split(/\s+/)) {
-        const word = token.replace(/[.,;:!?]+$/, '');
-        if (word === '')
-            continue;
-        if (word === '--auto') {
-            auto = true;
-            continue;
-        }
-        const range = /^\d+-(\d+)$/.exec(word);
-        if (range !== null) {
-            ceiling = range[1];
-            continue;
-        }
-        if (/^\d+$/.test(word))
-            continue; // a bare step number: keep scanning for a range/--auto
-        break; // an unrecognized flag or free text: the arguments have ended
-    }
-    if (ceiling !== undefined)
-        return `range ${ceiling}`;
-    return auto ? 'auto' : null;
+    const args = readBuildArgs(line);
+    if (args.range)
+        return args.steps === null ? null : `steps ${normalizeStepList(args.steps)}`;
+    return args.auto ? 'auto' : null;
 }
 /**
- * Extract the `prompt` field from the UserPromptSubmit JSON, or '' otherwise.
+ * The `prompt` and `prompt_id` fields of the UserPromptSubmit JSON, as '' and
+ * null when either is absent.
  *
  * Absent, unparseable, or non-string input contributes nothing rather than
- * wedging the tool: the tick still lands (a human turn did occur) and the empty
- * prompt clears any GRANT; the verb never throws over bad stdin.
+ * wedging the tool: the tick still lands (a human turn did occur), the empty
+ * prompt clears any GRANT, and a missing id records none; the verb never
+ * throws over bad stdin.
  */
-function extractPrompt(raw) {
+function readPayload(raw) {
     try {
         const parsed = JSON.parse(raw);
-        return typeof parsed.prompt === 'string' ? parsed.prompt : '';
+        return {
+            prompt: typeof parsed.prompt === 'string' ? parsed.prompt : '',
+            promptId: typeof parsed.prompt_id === 'string' && parsed.prompt_id !== '' ? parsed.prompt_id : null,
+        };
     }
     catch {
-        return '';
+        return { prompt: '', promptId: null };
     }
 }
 /**

package/dist/verbs/use.js

@@ -11,7 +11,7 @@
 import { existsSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { activeBuild, hasSession, intentPath, listBuilds, setActiveBuild, stepPath } from "../lib/sidecar.js";
-import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
 import { driverPointer } from "./handoff.js";
 /**
  * Switch the active-build cursor to the named build.
@@ -43,22 +43,26 @@ export function use(cwd, args) {
     // The lead line, then the advisory it qualifies, then the pointer into the
     // build just switched to: one fixed order for every ending, so the relay never
     // has to guess which line leads.
-    process.stdout.write(ending({
-        lead: transition({
-            label: 'Active build',
-            fact: target,
-            detail: existsSync(stepPath(root, target)) ? ['a step is in flight'] : [],
+    printEnding(root, {
+        tier: 'driver',
+        render: 'use',
+        text: ending({
+            lead: transition({
+                label: 'Active build',
+                fact: target,
+                detail: existsSync(stepPath(root, target)) ? ['a step is in flight'] : [],
+            }),
+            advisories: left === null
+                ? []
+                : [
+                    advisory({
+                        fact: `build "${left}" has a step in flight`,
+                        detail: ['its in-flight state is preserved'],
+                        remedy: `plumbbob use ${left} to pick it back up`,
+                    }),
+                ],
+            pointer: driverPointer(root, target),
         }),
-        advisories: left === null
-            ? []
-            : [
-                advisory({
-                    fact: `build "${left}" has a step in flight`,
-                    detail: ['its in-flight state is preserved'],
-                    remedy: `plumbbob use ${left} to pick it back up`,
-                }),
-            ],
-        pointer: driverPointer(root, target),
-    }));
+    });
     return 0;
 }

package/hooks/hooks.json

@@ -22,6 +22,13 @@
           { "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/bin/plumbbob\" turn" }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/bin/plumbbob\" relay" }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "Attention-first build process: 15 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",

package/skills/build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: build
-description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then stops."
-argument-hint: "[step-number | step-range] [--auto]"
+description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3`, or a list like `20,5-9`, self-approves exactly the steps it names, in build order, then stops."
+argument-hint: "[step-number | step-range | step-list] [--auto]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
 ---
@@ -35,9 +35,10 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
 ## What this skill does, in order
 
 1. **Pick the step.** Use the number you were invoked with (for example `/plumbbob:build 4`), or,
-   if you were given a range like `/plumbbob:build 1-3`, start at the first number and treat
-   the second as the last step you approve and land yourself (see the range note under
-   `--auto`). With no argument, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
+   if you were given a range like `/plumbbob:build 1-3` or a list like `/plumbbob:build 20,5-9`,
+   start at its first undone step in build order, the one the dashboard above marks
+   `← requested`, and land only the steps it names (see the range note under `--auto`).
+   With no argument, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
    (step 2) enters the next undone step in build order (the `## Build order` line when the
    plan has one, else the numbering) and refuses with a `/plumbbob:step` nudge when every
    step is checkpointed.
@@ -144,6 +145,7 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    paragraph when the step needs explaining>
 
    ## 1 <the first highlight: one sentence, one move>
+
    <the full story: what moved, why, what was tried and dropped>
 
    ## 2 ...
@@ -180,32 +182,59 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    line in the build-log's `## Log` and then truncates it, so the detail lands in the
    tracked ledger rather than piling up on disk.
 
+   **A bare range's pause is its stop.** When the injected dashboard's ranges block lists
+   this step as a bare range (`/plumbbob:build 5`, its row marked `▸`), the plan reserved a
+   call for this pause, and the `stop:` line beneath the row names it. The recommendation
+   speaks to that call: the move you would take on the plan's question, and why, rather
+   than a verdict on the diff alone.
+
    *Paste the turn.* Run `plumbbob handoff` and paste its output whole, verbatim, at top
    level, trailing blank line included, then end the turn. Never nest it inside a fence of
-   your own; it carries fences of its own and they cannot nest. It prints the Summary and
-   its highlights, the Readout fence (its measured `check`, `seam`, `diff`, and `spent`
-   rows folded with your three), a `diff` fence when the change is 20 lines or fewer, the
-   Verdict folded worst-of from the same rows, Next Up, Your Call, and your recommendation
-   last. The gate verdict's one home is that `check` row: no standalone verdict line
-   exists, and you never restate the verdict in prose. A narrowed run names the slots it
-   skipped there (`· without test`), and that named narrowing is the whole disclosure. The
-   notice checkride's Stop hook appends after your turn is not yours to relay or repeat;
-   the trailing blank line you kept is what lands it on its own line. Relayed CLI strings
-   keep their em-dashes; your own lines never use one, the write-versus-relay line of
+   your own; it carries fences of its own and they cannot nest. It prints the Now line
+   naming the step in flight, the Summary and its highlights, the Readout fence (its
+   measured `check`, `seam`, `diff`, and `spent` rows folded with your three), a `diff`
+   fence when the change is 20 lines or fewer, the Verdict folded worst-of from the same
+   rows, Next Up, Your Call, and your recommendation last. Run it once: a second run at an
+   unchanged pause prints the one-line reminder instead of the card, so if that line comes
+   back where the card belongs (you ran handoff earlier in this turn), run
+   `plumbbob handoff --full` and paste that. The gate verdict's one home is that `check`
+   row: no standalone verdict line exists, and you never restate the verdict in prose. A
+   narrowed run names the slots it skipped there (`· without test`), and that named
+   narrowing is the whole disclosure. The notice checkride's Stop hook appends after your
+   turn is not yours to relay or repeat; the trailing blank line you kept is what lands it
+   on its own line. Relayed CLI strings keep their em-dashes; your own lines never use
+   one, the write-versus-relay line of
    [D78 (em-dash-ban)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d78).
 
    *Then read the reply as an ask or a direction.* A message that **asks** ("expand 2",
-   "what does that mean?", "why did the seam row flag that?") is an expand: answer it from the detail file, from
-   `git diff`, or from the build-log's `## Log` for an older step, never from recall, then run `plumbbob handoff` again and
-   paste it. The step is still in flight, so it renders the same pause, and the Your Call
-   block stays the CLI's to render rather than yours to retype. A message that **directs**
-   is needs-work: take it as what to change, and nothing lands until the human says
-   `looks good`.
+   "what does that mean?", "why did the seam row flag that?") is an expand: answer it from
+   the detail file, from `git diff`, or from the build-log's `## Log` for an older step,
+   never from recall, then run `plumbbob handoff` and paste its output beneath your answer,
+   whole and verbatim. The turn is your answer, then that output, and nothing after it. The
+   pause renders its card once
+   ([D87 (pause-once)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d87)):
+   while nothing about it has changed, handoff prints one line,
+   `**Next Up**: Back to Step <N> of <M> - <title>`, in place of the card the human already
+   read, so your answer stays on screen. The CLI picks the form, never you: paste whichever
+   one it prints, and never retype the card or reach for `--full` to put it beneath an
+   answer.
+
+   Two moments bring the whole card back, and in both you run `plumbbob handoff --full` and
+   paste its output whole, with nothing written around it: the human asks to see the pause
+   (`show the pause`, or any wording of it), or the card is not in this conversation (a
+   fresh session, or one after `/clear`, that finds the step still at its pause). A
+   message that **directs** is needs-work: take it as what to change, and nothing lands
+   until the human says `looks good`. Once the change is made, rewrite the detail file and
+   end on `plumbbob handoff` as the first render did; the pause has changed, so it prints
+   the whole card.
 
    **Then hand off with the next model.** `plumbbob checkpoint` prints the whole boundary
    ending itself: `**Checkpoint**: Step N complete (<sha>)`, the Verdict the step earned,
-   any advisory (a staged path outside the seam is the common one), and Next Up. Relay
-   that block whole, run no second command, and write nothing around it. It is the
+   any advisory (a staged path outside the seam is the common one), the Stop part when
+   this landing completes a range (`**Stop**: Range 3 of 5 landed - <its stop>`, the reason
+   the build stops here), and Next Up. Relay that block whole, the Stop part with the rest
+   (the relay check holds a boundary that dropped it), run no second command, and write
+   nothing around it. It is the
    orientation tier (no Your Call block, no recommendation), and it points at the next
    undone step carrying that step's `- model:` recommendation (the plan's
    smallest-model-that-fits call) so the human knows which `/model` to select before
@@ -268,7 +297,18 @@ and approves in the human's place**, and it **chains**:
     advance the loop), or a new decision is needed. The step is still in flight and the
     human has a call to make about it, so end on the same turn the default pause does:
     write the detail file, run `plumbbob handoff`, and paste its block.
-  - **A clean halt lands its step first.** The top of a requested range is reached, or no
+  - **A call the plan reserves halts at its pause.** A step the plan's `## Build ranges`
+    names as a bare range (`/plumbbob:build 10`) is a decision the plan left for the human,
+    and `plumbbob build` says so as it enters the step (`step 10 ends at its pause, where
+    the plan reserves the call for the human`). Build it, verify it, and end on the same
+    turn a halt on trouble does: write the detail file, run `plumbbob handoff`, and paste
+    its block. The latch would let it land, since `--auto` grants every step, so keeping
+    the step open is yours to do
+    ([D94 (auto-and-stops)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d94)).
+    A range that lands its steps runs through, since its stop is a review that can wait
+    for the end of the run, and a typed range stays exactly as typed.
+  - **A clean halt lands its step first.** The top of a requested range is reached (the
+    next step in build order is one the range does not name, or none is left), or no
     planned steps remain, and `plumbbob build` names that step as it enters it (for
     example `step 3 is the last undone step in the plan`). That step checkpoints like
     every step before it, and its
@@ -283,36 +323,54 @@ only because the human asked for it by name. A range hands the clock back once i
 step has landed: the step after it waits for the human's next run. The default (no flag,
 no range) always ends at the pause.
 
-### A step range (`N-M`) is a bounded `--auto`
+### A step range (`N-M`, or a list like `20,5-9`) is a bounded `--auto`
 
 `/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **stops
-once step 3 has landed** instead of chaining to done. The range *is* the opt-in; you do not
-also pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
-any next step whose plan number is past the top of the range.** It adds no machinery: just
-the one more entry already in the halt list above, and it is a clean halt, so the top step
-is never held back for approval. The human approved it by typing the range, and
-`plumbbob build` says so as it enters that step:
-`step 3 is the top of the range you granted`, or, when the plan ends first,
+once step 3 has landed** instead of chaining to done. A range may also list its steps, numbers
+and spans joined by commas (`/plumbbob:build 20,5-9`, typed with or without a space after a
+comma), and it grants exactly the steps it names: the checkpoint refuses any other
+([D91 (step-list-grants)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d91)).
+The range *is* the opt-in; you do not also pass `--auto`.
+
+Run it as the `--auto` loop, walked in build order. **Start at the range's first undone step
+in build order, however it is written** (`5-9,20` under an order that puts 20 first starts at
+20), and after each landing take the next undone step in build order. Build it if the range
+names it; **stop before building any step the range does not name**, or once none is left. It
+adds no machinery: just the one more entry already in the halt list above, and it is a clean
+halt, so the top step is never held back for approval. The human approved it by typing the
+range, and `plumbbob build` says so as it enters that step:
+`step 3 is the top of the range you granted`, or, when the walk ends early (the plan runs
+out, or the next step in build order is one the range does not name),
 `the last undone step in the range you granted`.
 
-- **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, M included, then
-  relay M's checkpoint block and end the turn. `N-N` is a range like any other: it builds
-  and lands the single step `N`. Only a bare `/plumbbob:build N` ends at the pause.
-- **N > M** (for example `3-1`): that is not a range you can walk; report it and stop rather
-  than guess the intent.
-- **M past the last planned step** (for example `1-9` with three steps): build through the
-  last planned step and stop; that is the existing "no planned steps remain" halt, not
-  an error.
-- **A step inside the range won't build** (missing, or its seam won't parse): `plumbbob
-  build <n>` fails exactly as it always does; surface it and stop, the same as a red
-  check. Do not skip past the gap.
-- **N is above the next undone step**: you are jumping over earlier planned work; note
-  that you are skipping the steps before N, then proceed (the same latitude as a
+- **A range that parses**: build each step it names in build order, self-approving and
+  checkpointing each, the last included, then relay the last one's checkpoint block and end
+  the turn. `N-N` is a range like any other: it builds and lands the single step `N`. Only a
+  bare `/plumbbob:build N` ends at the pause.
+- **A range that does not parse** (for example `3-1`, or `1--3`): that is not a range you can
+  walk, and it grants nothing; report it and stop rather than guess the intent.
+- **A number past the last planned step** (for example `1-9` with three steps): build through
+  the last planned step the range names and stop; that is the existing "no planned steps
+  remain" halt, not an error. A number the plan lacks is never reached.
+- **A step inside the range won't build** (its seam won't parse): `plumbbob build <n>` fails
+  exactly as it always does; surface it and stop, the same as a red check. Do not skip past
+  the gap.
+- **The range starts above the next undone step**: you are jumping over earlier planned work;
+  note that you are skipping the steps before it, then proceed (the same latitude as a
   single-number jump like `/plumbbob:build 4`).
-- **The build order puts a number past the top ahead of the rest** (the order reads
-  `1, 4, 2, 3` under `/plumbbob:build 1-3`): a range names plan numbers, so the halt above
-  fires before step 4 and `plumbbob build` names step 1 as the last undone step in the
-  range. Build a re-sequenced stretch step by step, or grant `--auto`.
+- **The build order puts a step the range does not name inside it** (the order reads
+  `1, 4, 2, 3` under `/plumbbob:build 1-3`): the halt above fires before step 4, and
+  `plumbbob build` names step 1 as the last undone step in the range. The range that walks
+  the whole stretch lists step 4 too (`/plumbbob:build 1-4`, or `/plumbbob:build 1,4,2,3`).
+- **At a range's stop, harvest before the next range.** No harvest runs between the steps
+  inside a range, so the parks pile up, and a blocker among them would otherwise ride into
+  the next one. When the human asks what comes next at a stop with parks open (the note's
+  `parked 2 of 7 open`), the move is `/plumbbob:harvest`, then the range the card names.
+- **After an early stop, settle the step, then rerun what is left.** A halt on trouble
+  inside a range ends at that step's pause, and the grant ends with the turn. Once the
+  human approves and the step lands, the note beneath Next Up names what is left of the
+  range (`· range 3 of 5: /plumbbob:build 8-9`), and that is the command the human types
+  to carry on.
 
 ## The hard contracts
 

package/skills/harvest/SKILL.md

@@ -23,6 +23,10 @@ DESIGN boundary, not mid-step. Read the dashboard injected above:
   Chasing parked items mid-step is the disease parking prevents.
 - At the boundary (the dashboard reads `[DESIGN]`): go ahead.
 
+A range's stop is the boundary that matters most. No harvest runs between the steps
+inside a range, so the parks it piled up wait for the stop where it lands, and a
+blocker among them is caught there before the next range builds on it.
+
 ## What this skill does
 
 Walk the **Park list** in `build-log.md` item by item and, for each, **propose exactly
@@ -47,6 +51,11 @@ one line of reasoning, then **wait for the human to confirm or override**. Write
   (`- <a id="d5"></a>**D5 (retry-cap)**: <the call>, *because* <why>`), never a bare `D5`.
   A blocker that becomes a new step takes the next free number under `## Steps` and,
   when it has to land before an existing undone step, its place in the sequence through
-  `plumbbob order 7 8 5` (the `## Build order` line), never by renumbering.
+  `plumbbob order 7 8 5` (the `## Build order` line), never by renumbering. When the plan
+  carries `## Build ranges`, the new step goes into a range too (the one it builds with,
+  or a bare range of its own when it brings a call the human has to make before it
+  lands), and a range it breaks is re-cut in the same confirmed edit
+  ([D92 (build-ranges)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d92));
+  `plumbbob status` afterward carries a `⚠` row for any range still broken.
 - Never reclassify or resolve an item the human hasn't confirmed, and default every
   uncertain item to **tangent**, never to blocker.