plumbbob 0.13.0 → 0.13.2

package/dist/verbs/turn.js

@@ -1,33 +1,43 @@
 // `plumbbob turn`: the turn-ledger hook. Wired to the harness's
-// UserPromptSubmit event, it runs once per human 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
-// 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, 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.
+// UserPromptSubmit event, it runs once per prompt and maintains the sidecar's
+// git-excluded turn ledger (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`, a step range (`N-M`,
+// or a list such as `20,5-9`), or `/plumbbob:run`, clearing it otherwise (those
+// strings can only come from a human keystroke, because `build` and `run` are
+// disable-model-invocation: a grant the model could forge would be no grant).
+// A run's grant is the steps left of the range the plan names, read from the
+// active build's `intent.md` at the keystroke, and `RUN` beside it marks the
+// range the run is landing. 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 the mark, 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 { parseBuildRanges, readRunArgs, resolveRun } from "../lib/orient.js";
+import { clearRelay, findSessionRoot, inSpike, intentPath, notePrompt, readPrompt, readRun, setGrant, setRun, stepPath, turnPath, } from "../lib/sidecar.js";
+import { hasStep, 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.
@@ -78,7 +88,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 and the RUN mark. A notice
+ * touches none of them, 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`
@@ -87,20 +107,56 @@ 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`);
+        const minted = mintSafely(root, prompt);
+        setGrant(root, minted.grant);
+        setRun(root, minted.run);
+    }
+    // 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 ');
+}
+// A build invocation, bare or namespaced, starting a token.
+const BUILD_INVOCATION = /(?<![\w/.~-])\/(?:plumbbob:)?build\b/;
+// A run invocation: only the namespaced verb, since a bare `/run` reaches
+// Claude Code's own skill, starting a token and ending at a space, a line's
+// end, or sentence punctuation.
+const RUN_INVOCATION = /(?<![\w/.~-])\/plumbbob:run(?=[\s.;:!?,]|$)/;
 /**
  * Derive the GRANT content from the human's prompt, or null to clear it.
  *
  * 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
@@ -116,47 +172,103 @@ export function applyTurn(cwd, raw) {
  * argument the human typed.
  */
 export function grantFromPrompt(prompt) {
-    const invocation = /(?<![\w/.~-])\/(?:plumbbob:)?build\b/.exec(prompt);
+    const invocation = BUILD_INVOCATION.exec(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
+    const args = readBuildArgs(argumentLine(prompt, invocation));
+    if (args.range)
+        return args.steps === null ? null : `steps ${normalizeStepList(args.steps)}`;
+    return args.auto ? 'auto' : null;
+}
+/**
+ * The text an invocation's arguments are read from: the rest of its line.
+ */
+function argumentLine(prompt, invocation) {
+    return prompt.slice(invocation.index + invocation[0].length).split('\n', 1)[0] ?? '';
+}
+/**
+ * The GRANT one typed prompt mints and the RUN mark it leaves, given the
+ * active build as the hook read it (null when it could not) and the range the
+ * RUN mark names now.
+ *
+ * Whichever invocation comes first in the prompt is the one the human fired.
+ * A run mints `steps <what is left>` of the range the plan names at the
+ * keystroke, and marks that range, so a later edit to the ranges or the build
+ * order leaves both as they were. A bare range's run mints nothing and marks
+ * nothing, since it builds its step to the pause, and so does a run that names
+ * nothing it can walk, a span or a list of ranges, and a plan the hook could
+ * not read. Any other prompt mints what `grantFromPrompt` reads, and keeps the
+ * mark only while a step of the marked range waits at its pause, so a halt
+ * inside the run approved with `looks good` still lands under it.
+ */
+export function mintFromPrompt(prompt, build, marked) {
+    const run = RUN_INVOCATION.exec(prompt);
+    const first = BUILD_INVOCATION.exec(prompt);
+    if (run === null || (first !== null && first.index < run.index)) {
+        return { grant: grantFromPrompt(prompt), run: heldMark(build, marked) };
+    }
+    const args = readRunArgs(argumentLine(prompt, run));
+    const resolved = args === null || build === null ? null : resolveRun({ ...build, item: args.item });
+    if (resolved?.ok !== true || resolved.grant === null)
+        return { grant: null, run: null };
+    return { grant: resolved.grant, run: resolved.range.item };
+}
+/**
+ * The RUN mark a prompt that is not a run leaves: the marked range while a
+ * step it names is in flight, so waiting at its pause, else none.
+ */
+function heldMark(build, marked) {
+    if (build === null || marked === null || build.inFlight === null)
+        return null;
+    const step = build.inFlight;
+    const range = parseBuildRanges(build.intent).ranges.find((r) => r.item === marked);
+    return range !== undefined && hasStep(range.steps, step) ? marked : null;
+}
+/**
+ * What a typed prompt mints, read against the active build, degrading to no
+ * grant and no mark on any failure, so a broken read can never leave the last
+ * turn's grant standing.
+ */
+function mintSafely(root, prompt) {
+    try {
+        return mintFromPrompt(prompt, readBuild(root), readRun(root));
+    }
+    catch {
+        return { grant: null, run: null };
     }
-    if (ceiling !== undefined)
-        return `range ${ceiling}`;
-    return auto ? 'auto' : null;
 }
 /**
- * Extract the `prompt` field from the UserPromptSubmit JSON, or '' otherwise.
+ * The active build as a run reads it: the plan's text, the step in flight,
+ * and whether a spike is open; null when the plan cannot be read, which mints
+ * no run.
+ */
+function readBuild(root) {
+    try {
+        return { intent: readFileSync(intentPath(root), 'utf8'), inFlight: inFlightStep(root), spiking: inSpike(root) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "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,15 +35,18 @@ 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.
 2. **Enter the step.** Run `plumbbob build <n>`, or bare `plumbbob build` to enter the
    next undone step (records the in-flight STEP + SEAM so `/plumbbob:status` shows the step in
-   flight; the seam is awareness, not a lock).
+   flight; the seam is awareness, not a lock). When it refuses with `no step entered` because
+   a stop card is waiting for its reply, relay the refusal whole and end the turn: the card's
+   reply is the human's, and no step is built until it records.
    - **Spike-as-step.** If the step's title opens with `spike:` / `Spike:`, the increment
      *is* the experiment: resolving a fork the plan couldn't settle on paper. After
      entering it, run `plumbbob spike report "<slug>"` (the CLI scaffolds a
@@ -181,6 +184,12 @@ 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 Now line
@@ -223,8 +232,11 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
 
    **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
@@ -287,7 +299,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
@@ -302,36 +325,64 @@ 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`.
+
+**A run hands you a range the plan names, walked the same way.** `/plumbbob:run` (the run
+skill) reads this section for its walk: its grant is the `steps` list the turn hook minted
+from the plan's `## Build ranges` when the human typed the run, in the normal form a typed
+list mints, so the latch, `plumbbob build`'s notice at the top step, and every halt below
+read it exactly as they read a typed range
+([D96 (plan-names-the-grant)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d96)).
+
+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. A run's range ends on the stop card, which lists every open park with a
+  proposed class, and the reply that settles the card records them (the run skill's
+  section on the reply at a stop). A range landed here, by a typed range, ends on the plain
+  boundary instead; when the human asks what comes next there with parks open (the note's
+  `parked 2 of 7 open`), the move is `/plumbbob:harvest`, then the run 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 the run that lands
+  what is left of the range (`· range 3 of 5: /plumbbob:run (steps 8-9)`), and that is what
+  the human types to carry on; `/plumbbob:build 8-9` lands the same steps by hand.
 
 ## The hard contracts
 

package/skills/finish/SKILL.md

@@ -2,7 +2,7 @@
 name: finish
 description: "Finish the build: write the report (what shipped, decisions, parked/harvested items, deferred tangents), then make the final commit that closes the session. The build folder rides the branch into the PR: no separate archive. Report by default, no gate."
 disable-model-invocation: true
-allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob finish:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob harvest:*), Bash(plumbbob order:*), Bash(plumbbob finish:*)
 ---
 
 # PlumbBob: finish the build (the close-out)
@@ -17,7 +17,21 @@ record.
 
 ## What this skill does, in order
 
-1. **Write the report** to the active build's `report.md`
+1. **Settle a stop card still waiting.** Read `.plumbbob/detail.md`. When it opens on a
+   `# Detail · Range <N>` header, the last range's stop card is waiting for its reply, and
+   `/plumbbob:finish` typed at it is that reply, the move its Your Call block names
+   ([D102 (settle-in-one-reply)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d102)).
+   Record it the way `looks good` would before anything else: fold each blocker its
+   `## Harvest` section proposes into `intent.md` by the harvest skill's rules (read
+   `../harvest/SKILL.md` from this skill's base directory), then run `plumbbob harvest`,
+   which writes the range's review into the Log and flips the parks the card settled. A
+   finish that skipped it would leave the last range's review out of the Log and its parks
+   open in the report. When `plumbbob harvest` refuses with `step 13 joined it after it
+   landed`, a blocker went into the range the card reviews: move that step to a range
+   still to come, or a bare range of its own, leave the detail file as it is, fold nothing
+   again, and run `plumbbob harvest` once more. On any other refusal, report what it names
+   and stop before the report. Any other detail file, or none, has nothing waiting.
+2. **Write the report** to the active build's `report.md`
    (`.plumbbob/builds/<slug>/report.md`), from `intent.md` + `build-log.md`.
    The build-log's `## Log` is already the chronological history; `plumbbob checkpoint`
    wrote a dated line for every step as it landed. **Read it as the spine; do not
@@ -34,7 +48,7 @@ record.
    `## Stats` (the per-step receipts) itself, so do **not** hand-write either; a report
    that spells them out collides with the CLI's own tail. This is the "yeah, I did that"
    artifact. Write it by default; the human may edit it.
-2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
+3. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
    report and makes the final commit (subject `chore(<scope>): finish`, its body
    led by a `plumbbob finish` marker plus an optional proportional `--body`), then
    clears the control state (the in-flight markers, then `STATE` last; one delete
@@ -58,7 +72,7 @@ record.
    cannot analyze the extra redirect, so it blocks the command or stops to ask instead of
    letting this skill's allowance cover it. Omit `--body` entirely and the commit carries
    the `plumbbob finish` marker subject only.
-3. **Point at the next goal.** Relay `plumbbob finish`'s output verbatim, blank lines
+4. **Point at the next goal.** Relay `plumbbob finish`'s output verbatim, blank lines
    included: its lead line, which names the branch the tracked folder now rides into the
    PR, any advisory beneath it, and `**Next Up**: Nothing planned - /plumbbob:plan`. That
    is the orientation tier's close (the

package/skills/harvest/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: harvest
-description: "Triage the park list at a step boundary: propose one class (blocker/tangent/pivot) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent."
+description: "Triage the park list at a step boundary: propose one class (blocker/tangent/pivot) for every open parked item at once, and once the human settles them in one reply, fold a confirmed blocker into intent and record the rest with plumbbob harvest. A run's stop card carries its own harvest."
 disable-model-invocation: true
-allowed-tools: Read, Edit, Bash(plumbbob status:*), Bash(plumbbob order:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob order:*), Bash(plumbbob harvest:*)
 ---
 
 # PlumbBob: harvest the park list
@@ -23,10 +23,21 @@ 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. A run's stop card
+carries its harvest
+([D100 (stop-card)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d100)):
+every open park is on the card with a proposed lean, and the reply that settles the card
+records them, so there is nothing left for this skill to do there. If
+`.plumbbob/detail.md` opens on a `# Detail · Range <N>` header, that card is still waiting:
+**refuse**, since writing this skill's detail file would overwrite the range's review, and
+point the human at the card's own reply (`looks good`, or a change to a lean).
+
 ## What this skill does
 
-Walk the **Park list** in `build-log.md` item by item and, for each, **propose exactly
-one class**:
+Walk the **Park list** in `build-log.md` and, for every open item, **propose exactly one
+class**, all of them at once:
 
 - **blocker**: the plan was wrong or incomplete; can't proceed. Folds into `intent.md`
   and is handled now.
@@ -35,18 +46,50 @@ one class**:
 
 ## The one hard contract
 
-You **propose**; the **human calls it**. For each item, state your proposed class and
-one line of reasoning, then **wait for the human to confirm or override**. Write
-**only after** per-item confirmation:
+You **propose**; the **human calls it**. Propose a class for every open item at once,
+with one line of reasoning each, and the human settles them all in one reply
+([D102 (settle-in-one-reply)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d102)):
+one reply per item is what made a harvest a chore, and seeing every proposal at once keeps
+the call on each one theirs. The detail file you write first is the proposal; record
+**only after** that reply confirms them:
 
-- Record each confirmed class in `build-log.md`'s `## Harvest` section.
-- **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/plumbbob:status`
-  stops counting it as open.
+- Write the proposals into `.plumbbob/detail.md` first, under a `# Detail · Harvest`
+  header, one line per open item in a `## Harvest` section:
+  `- P6 → tangent: <the reason, one clause>`, the class written `blocker`, `tangent`,
+  or `pivot` (for a pivot signal). A park's handle is `P` and its place in the
+  Park list, counting the harvested lines too (the count the note sizes as
+  `parked 3 of 8 open`), and it is the one name the detail file, the turn, and the
+  human's reply all use
+  ([D105 (park-handles)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d105)).
+  Then list the same proposals in the turn, each with its handle and the park's text, and
+  end the turn there.
+- A reply that changes a proposal (`make P7 a tangent`) is the human's call: rewrite
+  that line, list the proposals again, and end the turn. A reply that confirms them
+  (`looks good`) is what lets you write.
+- On that confirmation, run `plumbbob harvest`
+  ([D104 (harvest-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d104)).
+  It flips each settled item from `- [ ]` to `- [x]` in the Park list, so
+  `/plumbbob:status` stops counting it as open, and records each confirmed class under
+  `build-log.md`'s `## Harvest` section. Relay its ending whole, the `**Recorded**:` line
+  and the Next Up beneath it. It refuses a proposal naming a handle the list lacks (`P9`
+  with eight parked) or a class other than blocker, tangent, or pivot; fix the line it
+  names and run it again.
 - A confirmed **blocker** also folds its decision into `intent.md`, slugged at birth
   like any Decision, anchored the same way
   (`- <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: a range still to come
+  (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 never a range that has landed, since that range's call
+  was made and the step would reopen it. A new range takes the next free item number, and
+  no item is renumbered, because the stop card's stamp, the detail file's header, and
+  `plumbbob harvest` find a landed range by its number. A range the step 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.
+- Fold a confirmed blocker into `intent.md` before you run `plumbbob harvest`, so the
+  record and the plan agree when it lands.
 - Never reclassify or resolve an item the human hasn't confirmed, and default every
   uncertain item to **tangent**, never to blocker.