plumbbob 0.13.2 → 0.13.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "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

@@ -49,7 +49,7 @@ PlumbBob itself, running its own loop.
 ## The loop in one picture
 
 <p align="center">
-  <img src="docs/media/loop-one-step.svg" alt="One step of the loop: /plumbbob:build implements step 1 and stops at the pause, the human says looks good, the step is checkpointed" width="760">
+  <img src="site/media/loop-one-step.svg" alt="One step of the loop, drawn as a wall going up course by course: on the scaffold a person reads a plumb line at the corner, and down the wall a mechanical arm holds the next stone and waits" width="760">
 </p>
 
 Everything the model must stay true to lives in one file, the build's `intent.md`
@@ -72,7 +72,8 @@ a decision the plan left open or after a stretch of steps worth reviewing.
 `/plumbbob:build` is the same loop a step at a time, stopping at every step's pause, for
 a plan without ranges or a stretch you want to walk slowly. Nothing is locked and nothing
 refuses you: the loop does the labor, pulls up to the line, and waits for you to advance
-it. **You are the clock.**
+it. **You are the clock.** [`docs/runs.md`](docs/runs.md) walks one plan through its runs
+and then drives it by hand, the two side by side.
 
 ## What a prompt can't replicate
 
@@ -101,7 +102,7 @@ payoff is [measured, not asserted](#why-not-just), not just claimed. **Guidance
 work, a latch on the record.**
 
 <p align="center">
-  <img src="docs/media/build-record-in-pr.svg" alt="A pull request's file list with the build folder beside the source" width="760">
+  <img src="site/media/build-record.svg" alt="The record in the wall, drawn: the scaffold is down and stacked on the ground, a bench mark is cut into the end stone of every course, and in the open cornerstone lie the rolled plan, tied with the red line, and the ledger, laid into the wall to stay" width="760">
 </p>
 
 ## Install
@@ -183,7 +184,7 @@ In Claude Code, inside any git repo with a clean tree:
    **Recommendation**: Approve it, refilling on read. The gate is green and the seam held, and a bucket that refills when it is read needs no timer for the route to clean up.
    ````
 
-   ![The build pause as Claude Code renders it](docs/media/pause.svg)
+   ![The pause, drawn: a mechanical hand has set its stone on the line and hovers open and still, while a plumb bob in front comes to rest](site/media/pause.svg)
 
    (The check gate is [checkride](https://www.npmjs.com/package/checkride), one
    run across the tools your repo already configures: types, lint, tests, dead
@@ -203,7 +204,7 @@ In Claude Code, inside any git repo with a clean tree:
      · range 2 of 2: /plumbbob:run (steps 2-3)
    ```
 
-   ![The boundary after looks good](docs/media/checkpoint-boundary.svg)
+   ![The boundary, drawn: a bench mark freshly cut into the newest course of a stone wall, older marks below, and the red line raised one course over stones not yet laid](site/media/checkpoint-boundary.svg)
 
    Ask instead (`expand 2`, or any question) and it shows more of what is there and
    changes nothing. The answer closes on one line pointing back at the step, not on the
@@ -360,14 +361,16 @@ that matters.
 > under [`docs/evals/`](docs/evals/): the route the latch owns (*no checkpoint over a red
 > check under pressure*) went from **2/5 prose-only to 5/5 latched** on the first sweep
 > ([2026-07-11](docs/evals/2026-07-11.md)), every sweep since has held it and closed the
-> two gaps that one surfaced, and the latest ([2026-09-17](docs/evals/2026-09-17.md))
-> scores the shape of the turn itself.
+> two gaps that one surfaced, [2026-09-17](docs/evals/2026-09-17.md) began scoring the
+> shape of the turn itself, and the latest ([2026-10-19](docs/evals/2026-10-19.md)) holds a
+> run to its stop card, 5/5.
 
 ## Documentation
 
 Each doc answers one question (in rough reading order for a new user):
 
 - *What does a session actually look like?* → [`docs/happy-path.md`](docs/happy-path.md): one goal walked end to end; read this first.
+- *How do I drive a plan with runs, and what do they replace?* → [`docs/runs.md`](docs/runs.md): ranges, the build order, and the stop card's harvest, walked through three runs and set beside the manual build, harvest, and order moves.
 - *What do the words mean?* → [`docs/glossary.md`](docs/glossary.md): every term the loop mints, one line each, with where to read more.
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/): that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md): the adoption questions, answered straight.

package/dist/lib/orient.js

@@ -356,7 +356,7 @@ export function rangeStanding(plan, ordered, step) {
     return {
         count,
         holding,
-        command: flag === null && left.length > 0 ? `/plumbbob:build ${leftExpression(holding, left)}` : null,
+        command: flag === null && left.length > 0 ? `/plumbbob:build ${leftExpression(holding, left.map((s) => s.n))}` : null,
         flag,
         completed: ordered[at]?.done === true && rangeLanded(holding, ordered) ? holding : null,
         drift,
@@ -420,8 +420,7 @@ function stopCardMove(item, count, follow) {
  * 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);
+    return !range.bare && left.length === 1 ? `${left[0]}-${left[0]}` : formatStepList(left);
 }
 /** The words for steps no range names: `no range names step 12`, or `steps 11, 12`. */
 function noRangeWords(steps) {
@@ -515,6 +514,344 @@ function stepPhrase(items) {
     const one = items.length === 1 && /^\d+$/.test(items[0] ?? '');
     return { words: `${one ? 'step' : 'steps'} ${items.join(', ')}`, be: one ? 'is' : 'are' };
 }
+// The most ways of placing one tangle's ranges the re-cut tries, counted as
+// the product of each range's stretches. A step moved out of a range splits it
+// in two, so one moved step makes two and three make eight, and an order that
+// scatters past this is a re-cut for the human anyway.
+const ORDER_CAP = 64;
+/**
+ * Re-cut the plan's ranges to follow its build order, and write each command
+ * the re-cut changed into its item.
+ *
+ * The plan comes back as it was, with nothing re-cut, when the order settles
+ * nothing, and when an item's opener does not hold its command where the write
+ * can find it, so a re-cut is written whole or not at all.
+ */
+export function recutPlan(intent) {
+    const plan = parseBuildRanges(intent);
+    const recut = recutRanges(plan, parseOrderedSteps(intent));
+    const written = recut.length === 0 ? null : writeRecut(intent, plan.ranges, recut);
+    return written === null ? { intent, recut: [] } : { intent: written, recut };
+}
+/**
+ * The ranges re-cut so that each holds one stretch of the build order, with
+ * every undone step in one wherever the order settles which.
+ *
+ * Only an open range moves. A landed range takes no step, since its call was
+ * made; a bare range keeps its one step and takes no other, since it builds
+ * that step to its pause; and every range keeps a step of its own, so no stop
+ * is left with nothing to stop on. Where the order interleaves the steps of two
+ * or more ranges, they are re-cut by the fewest steps moved between them, and
+ * left as written when two re-cuts tie or the one would split a range's longest
+ * stretch. A step no range names then joins one by where the order puts it, the
+ * way a moved step does: the range around it, else the one it builds ahead of,
+ * else the one it builds after. Nothing is re-cut when an item does not parse, an
+ * open range names a step the plan lacks, or two open ranges name one undone
+ * step, since which range holds what is the human's call there.
+ */
+function recutRanges(plan, ordered) {
+    const open = plan.ranges.filter((r) => !rangeLanded(r, ordered));
+    const owners = ownership(open, ordered);
+    if (owners === null || plan.malformed.length > 0 || open.some((r) => missingDrift(r, ordered).length > 0)) {
+        return [];
+    }
+    const undone = ordered.filter((s) => !s.done).map((s) => s.n);
+    const placed = new Map(owners);
+    const unsettled = new Set();
+    for (const tangle of tangles(undone.filter((n) => owners.has(n)), owners)) {
+        const moved = fewestMoves(tangle, owners);
+        if (moved === null) {
+            tangle.tangled.forEach((r) => unsettled.add(r));
+        }
+        moved?.forEach((range, n) => placed.set(n, range));
+    }
+    placeUnnamed(undone, placed, unsettled);
+    return open.flatMap((range) => {
+        const was = ordered.filter((s) => hasStep(range.steps, s.n)).map((s) => s.n);
+        const now = ordered.filter((s) => (s.done ? hasStep(range.steps, s.n) : placed.get(s.n) === range)).map((s) => s.n);
+        return was.join() === now.join() ? [] : [{ item: range.item, steps: now }];
+    });
+}
+/**
+ * Each undone step's open range, or null when two open ranges name one undone
+ * step, which no sequence can settle.
+ */
+function ownership(open, ordered) {
+    const owners = new Map();
+    for (const step of ordered.filter((s) => !s.done)) {
+        const named = open.filter((r) => hasStep(r.steps, step.n));
+        if (named.length > 1) {
+            return null;
+        }
+        if (named[0] !== undefined) {
+            owners.set(step.n, named[0]);
+        }
+    }
+    return owners;
+}
+/**
+ * The owned steps' tangles. A range's span runs from its first step in build
+ * order to its last, and ranges whose spans overlap are tangled; a range alone
+ * in its span is already one stretch. Each tangle carries the range on either
+ * side of it as well, since a step at the tangle's edge may join one, and two
+ * tangles that share such a range are one.
+ */
+function tangles(owned, owners) {
+    const cores = spanGroups(owned, owners);
+    const bounds = [];
+    cores.forEach((core, i) => {
+        const last = bounds.at(-1);
+        if (core.ranges.length < 2) {
+            return;
+        }
+        if (last !== undefined && i - 1 <= last.hi) {
+            last.hi = Math.min(i + 1, cores.length - 1);
+        }
+        else {
+            bounds.push({ lo: Math.max(i - 1, 0), hi: Math.min(i + 1, cores.length - 1) });
+        }
+    });
+    return bounds.map(({ lo, hi }) => {
+        const run = cores.slice(lo, hi + 1);
+        return {
+            tangled: run.flatMap((c) => (c.ranges.length > 1 ? c.ranges : [])),
+            ranges: run.flatMap((c) => c.ranges),
+            steps: owned.slice(run[0]?.first ?? 0, (run.at(-1)?.last ?? -1) + 1),
+        };
+    });
+}
+/**
+ * The owned steps grouped by span, in build order: ranges whose spans overlap
+ * share a group, and each group carries where its first step and its last sit.
+ */
+function spanGroups(owned, owners) {
+    const spans = new Map();
+    owned.forEach((n, i) => {
+        const range = owners.get(n);
+        if (range !== undefined) {
+            spans.set(range, { first: spans.get(range)?.first ?? i, last: i });
+        }
+    });
+    const groups = [];
+    for (const [range, span] of [...spans].sort((a, b) => a[1].first - b[1].first)) {
+        const group = groups.at(-1);
+        if (group !== undefined && span.first < group.last) {
+            group.ranges.push(range);
+            group.last = Math.max(group.last, span.last);
+        }
+        else {
+            groups.push({ ranges: [range], first: span.first, last: span.last });
+        }
+    }
+    return groups;
+}
+/**
+ * The tangle re-cut by the fewest steps moved between its ranges, as each
+ * step's range once re-cut; null when no cut keeps every range to its rules,
+ * when two cuts move as few, since the order settles neither, when the one
+ * cut splits a range's longest stretch, since that moves the range's body
+ * rather than a step, or when too many sequences of its ranges are in play.
+ *
+ * The ranges may run in any sequence their stretches allow, and each sequence
+ * is cut the way that keeps the most steps where they were.
+ */
+function fewestMoves(tangle, owners) {
+    const stretches = stretchesOf(tangle.steps, owners);
+    const cuts = (rangeOrders(tangle.ranges, stretches) ?? []).flatMap((order) => cutInOrder(order, tangle.steps, owners) ?? []);
+    const most = Math.max(...cuts.map((c) => c.kept));
+    const best = cuts.filter((c) => c.kept === most);
+    const [only] = best;
+    if (only === undefined || best.length > 1 || only.ways > 1 || !keepsBodies(tangle, stretches, only.placed)) {
+        return null;
+    }
+    return new Map(only.placed);
+}
+/**
+ * Whether a cut keeps each range's body: one of its longest stretches, whole,
+ * so a re-cut moves the steps the order moved and never the bulk of a range.
+ */
+function keepsBodies(tangle, stretches, placed) {
+    return tangle.ranges.every((range) => {
+        const own = stretches.filter((s) => s.range === range);
+        const longest = Math.max(...own.map((s) => s.size));
+        return own.some((s) => s.size === longest && tangle.steps.slice(s.start, s.start + s.size).every((n) => placed.get(n) === range));
+    });
+}
+/**
+ * The sequences a tangle's ranges may run in: each range placed where one of
+ * its stretches sits, so every sequence a cut could take, each once; null when
+ * the stretches would make more than `ORDER_CAP` choices.
+ */
+function rangeOrders(ranges, stretches) {
+    const anchors = ranges.map((range) => stretches.filter((s) => s.range === range));
+    if (anchors.reduce((n, a) => n * a.length, 1) > ORDER_CAP) {
+        return null;
+    }
+    const choices = anchors.reduce((sets, options) => sets.flatMap((set) => options.map((o) => [...set, o])), [[]]);
+    const orders = new Map();
+    for (const choice of choices) {
+        const order = [...choice].sort((a, b) => a.start - b.start).map((s) => s.range);
+        orders.set(order.map((r) => r.item).join(), order);
+    }
+    return [...orders.values()];
+}
+/** A tangle's steps as stretches, each an unbroken run of one range's steps. */
+function stretchesOf(steps, owners) {
+    const runs = [];
+    steps.forEach((n, i) => {
+        const range = owners.get(n);
+        const last = runs.at(-1);
+        if (range !== undefined && last?.range === range && last.start + last.size === i) {
+            last.size += 1;
+        }
+        else if (range !== undefined) {
+            runs.push({ range, start: i, size: 1 });
+        }
+    });
+    return runs;
+}
+/**
+ * A tangle cut in one sequence of its ranges, keeping the most steps in the
+ * range that named them; null when no cut keeps every range to its rules.
+ *
+ * Each range takes one block of the tangle's steps, in the sequence given, and
+ * each block holds a step of its own; a bare range's block is its one step. A
+ * block ends on a step of its own unless a bare range follows it, so a step
+ * moved between two ranges joins the one it builds ahead of, or the one before
+ * when the one ahead is bare, the rule a step no range names joins by. The
+ * search keeps, for each range in turn and each step its block may end at, the
+ * most steps kept, so it costs the ranges times the steps squared.
+ */
+function cutInOrder(order, steps, owners) {
+    const rows = [[{ kept: 0, ways: 1, from: -1 }]];
+    order.forEach((range, j) => {
+        const counts = runningCount(steps, owners, range);
+        const row = [];
+        rows[j]?.forEach((cell, from) => {
+            const prior = order[j - 1];
+            if (cell === undefined || (prior !== undefined && !range.bare && owners.get(steps[from - 1] ?? 0) !== prior)) {
+                return;
+            }
+            for (const block of rangeBlocks(range, counts, from)) {
+                keep(row, block.to, cell, block.kept, from);
+            }
+        });
+        rows.push(row);
+    });
+    const end = rows[order.length]?.[steps.length];
+    return end === undefined ? null : { kept: end.kept, ways: end.ways, placed: walkBack(rows, order, steps) };
+}
+/** How many of a range's own steps sit among a tangle's first `i` steps, for every `i` from none to all. */
+function runningCount(steps, owners, range) {
+    const counts = [0];
+    for (const n of steps) {
+        counts.push((counts.at(-1) ?? 0) + (owners.get(n) === range ? 1 : 0));
+    }
+    return counts;
+}
+/**
+ * The blocks a range can take from a tangle's step `from`: where each ends,
+ * and how many of the range's own steps it keeps. Each keeps one at least, and
+ * a bare range's block is its one step.
+ */
+function rangeBlocks(range, counts, from) {
+    const last = Math.min(range.bare ? from + 1 : Infinity, counts.length - 1);
+    const blocks = [];
+    for (let to = from + 1; to <= last; to += 1) {
+        const kept = (counts[to] ?? 0) - (counts[from] ?? 0);
+        if (kept > 0) {
+            blocks.push({ to, kept });
+        }
+    }
+    return blocks;
+}
+/**
+ * Record a block in the re-cut's search, in place: the cell where it ends keeps
+ * the most steps any way there does, and a second way to as many is a tie.
+ */
+function keep(row, to, prior, kept, from) {
+    const total = prior.kept + kept;
+    const at = row[to];
+    if (at === undefined || total > at.kept) {
+        row[to] = { kept: total, ways: prior.ways, from };
+    }
+    else if (total === at.kept) {
+        row[to] = { ...at, ways: Math.min(2, at.ways + prior.ways) };
+    }
+}
+/** Each step's range along the cut the search kept, read back from the last range's block. */
+function walkBack(rows, order, steps) {
+    const placed = new Map();
+    let to = steps.length;
+    order.forEach((_, i) => {
+        const j = order.length - i;
+        const from = rows[j]?.[to]?.from ?? 0;
+        const range = order[j - 1];
+        if (range !== undefined) {
+            steps.slice(from, to).forEach((n) => placed.set(n, range));
+        }
+        to = from;
+    });
+    return placed;
+}
+/**
+ * Give each run of steps no range names the range the order puts it in, in
+ * place in `placed`, read from the ranges on either side of the run. A run no
+ * range can take stays in none, and the dashboard flags it as before.
+ */
+function placeUnnamed(undone, placed, unsettled) {
+    const named = undone.map((n) => placed.get(n));
+    let start = 0;
+    while (start < undone.length) {
+        let end = start;
+        while (end < undone.length && named[end] === undefined) {
+            end += 1;
+        }
+        const range = end === start ? null : joinRange(named.slice(0, start).findLast((r) => r !== undefined), named[end], unsettled);
+        if (range !== null) {
+            undone.slice(start, end).forEach((n) => placed.set(n, range));
+        }
+        start = Math.max(end, start + 1);
+    }
+}
+/**
+ * The range a run of steps no range names joins, from the ranges on either
+ * side of it in build order: the range around it, else the one it builds ahead
+ * of, else the one it builds after. A bare range takes no other step, and a
+ * range the order left tangled takes none either, since where its stretch runs
+ * is still the human's call.
+ */
+function joinRange(before, after, unsettled) {
+    if ((before !== undefined && unsettled.has(before)) || (after !== undefined && unsettled.has(after))) {
+        return null;
+    }
+    if (before !== undefined && before === after) {
+        return before;
+    }
+    return [after, before].find((r) => r !== undefined && !r.bare) ?? null;
+}
+/**
+ * Write each re-cut range's command into its item's opener: its steps in build
+ * order, a landing range down to one step written `9-9` so it still lands. The
+ * stop, the model, and every other line of the item stay as written. Null when
+ * an opener does not hold its command in its first backticks, so the caller
+ * writes nothing rather than half a re-cut.
+ */
+function writeRecut(intent, ranges, recut) {
+    const lines = intent.split('\n');
+    for (const cut of recut) {
+        const range = ranges.find((r) => r.item === cut.item);
+        const at = (range?.line ?? 0) - 1;
+        const opener = lines[at] ?? '';
+        const quoted = /`([^`]*)`/.exec(opener);
+        if (range === undefined || quoted === null || (quoted[1] ?? '').trim() !== range.command) {
+            return null;
+        }
+        const command = `\`/plumbbob:build ${leftExpression(range, cut.steps)}\``;
+        lines[at] = `${opener.slice(0, quoted.index)}${command}${opener.slice(quoted.index + quoted[0].length)}`;
+    }
+    return lines.join('\n');
+}
 // --- The run: what `/plumbbob:run` names. The turn hook reads it to mint the
 // run's grant, `status --run` to print the run header, and the card to name the
 // run beneath Next Up, so all three read one answer from one plan. ---

package/dist/verbs/order.js

@@ -7,15 +7,18 @@
 // `checkpoint`, `handoff`), so the dashboard's `← next`, a bare
 // `plumbbob build`, and the card's Next Up agree. The verb validates what a
 // hand edit cannot: every number names an undone step, none twice. `--reset`
-// drops the line, and the plan reads in document order again. It runs in any
-// state, since re-sequencing what comes after the step in flight is the
-// mid-step use, and the sidecar sits outside every seam.
+// drops the line, and the plan reads in document order again. Either way the
+// build ranges are re-cut to follow the order written, wherever the order
+// settles which range a step is in, so a step placed next runs in the range
+// it now builds with. It runs in any state, since re-sequencing what comes
+// after the step in flight is the mid-step use, and the sidecar sits outside
+// every seam.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { activeBuild, hasSession, intentPath } from "../lib/sidecar.js";
-import { clearBuildOrder, orderSteps, parseSteps, setBuildOrder } from "../lib/orient.js";
-import { expandStepList, parseStepList } from "../lib/steplist.js";
-import { ending, notice, printEnding, transition } from "../lib/notice.js";
+import { clearBuildOrder, orderSteps, parseBuildRanges, parseOrderedSteps, parseSteps, rangeStanding, recutPlan, setBuildOrder, } from "../lib/orient.js";
+import { expandStepList, formatStepList, parseStepList } from "../lib/steplist.js";
+import { advisory, blocks, ending, notice, printEnding, transition } from "../lib/notice.js";
 import { driverPointer } from "./handoff.js";
 /**
  * Set the build order to the given step numbers and spans, the rest of the
@@ -36,15 +39,7 @@ export function order(cwd, args) {
     const path = intentPath(root);
     const intent = readFileSync(path, 'utf8');
     if (args.includes('--reset')) {
-        writeFileSync(path, clearBuildOrder(intent));
-        printEnding(root, {
-            tier: 'driver',
-            render: 'order',
-            text: ending({
-                lead: transition({ label: 'Build order', fact: 'document order' }),
-                pointer: driverPointer(root, activeBuild(root)),
-            }),
-        });
+        writeOrder(root, path, clearBuildOrder(intent), 'document order');
         return 0;
     }
     // Numbers and spans arrive space- or comma-separated, with or without a space
@@ -98,17 +93,66 @@ export function order(cwd, args) {
     const full = orderSteps(steps, given)
         .filter((s) => !s.done)
         .map((s) => s.n);
-    writeFileSync(path, setBuildOrder(intent, full));
-    // The pointer reads the plan back from disk, so it already follows the
-    // order just written: back at the step in flight, or forward from the
-    // boundary to the first step in the new sequence.
+    writeOrder(root, path, setBuildOrder(intent, full), full.join(', '));
+    return 0;
+}
+/**
+ * Write the plan under its new build order, its ranges re-cut to follow it,
+ * and print the ending: the order, the ranges the re-cut changed, any range it
+ * left for the human to re-cut, and the pointer.
+ *
+ * The pointer reads the plan back from disk, so it already follows the order
+ * just written: back at the step in flight, or forward from the boundary to
+ * the first step in the new sequence.
+ */
+function writeOrder(root, path, ordered, sequence) {
+    const { intent, recut } = recutPlan(ordered);
+    writeFileSync(path, intent);
+    const standing = rangeStanding(parseBuildRanges(intent), parseOrderedSteps(intent), null);
     printEnding(root, {
         tier: 'driver',
         render: 'order',
         text: ending({
-            lead: transition({ label: 'Build order', fact: full.join(', ') }),
+            lead: blocks([transition({ label: 'Build order', fact: sequence }), recutLead(recut, standing.count)]),
+            advisories: rangeAdvisories(standing),
             pointer: driverPointer(root, activeBuild(root)),
         }),
     });
-    return 0;
+}
+/**
+ * The lead naming each range the re-cut changed and the steps it names now,
+ * `range 2 of 3 re-cut (steps 10,4-6)`; null when it changed none.
+ */
+function recutLead(recut, count) {
+    const [only] = recut;
+    if (only === undefined) {
+        return null;
+    }
+    const steps = (cut) => `${cut.steps.length === 1 ? 'step' : 'steps'} ${formatStepList(cut.steps)}`;
+    const items = recut.map((cut) => cut.item).join(', ');
+    return transition({
+        label: 'Build ranges',
+        fact: `${recut.length === 1 ? 'range' : 'ranges'} ${items} of ${count} re-cut`,
+        detail: recut.length === 1 ? [steps(only)] : recut.map((cut) => `range ${cut.item}: ${steps(cut)}`),
+    });
+}
+/**
+ * Every range still flagged once the re-cut is written, in the words the
+ * dashboard flags it with, and beneath the last the move that re-cuts it by
+ * hand: the ties the order did not settle, a step no range can take, and the
+ * plan's other drift. Empty when every undone step sits in one stretch of one
+ * range.
+ */
+function rangeAdvisories(standing) {
+    const { count, drift } = standing;
+    const own = drift.filter((d) => d.item !== null && d.kind !== 'malformed');
+    const flagged = [...new Set(own.map((d) => d.item))].map((item) => ({
+        fact: `range ${item} of ${count} needs a re-cut`,
+        detail: own.filter((d) => d.item === item).map((d) => d.words),
+    }));
+    const lines = [...flagged, ...drift.filter((d) => d.item === null || d.kind === 'malformed').map((d) => ({ fact: d.words }))];
+    if (lines.length === 0) {
+        return [];
+    }
+    return [lines.map((l, i) => advisory(i === lines.length - 1 ? { ...l, remedy: '/plumbbob:refine ranges' } : l)).join('')];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "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/harvest/SKILL.md

@@ -77,18 +77,23 @@ the call on each one theirs. The detail file you write first is the proposal; re
 - 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. 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.
+  A blocker that becomes a new step takes the next free number under `## Steps` and its
+  place in the sequence through `plumbbob order 7 8 5` (the `## Build order` line, every
+  undone step in the sequence to build them), never by renumbering, even when it builds
+  last. When the plan carries `## Build ranges`, the verb files the new step for you: it
+  re-cuts the ranges to follow the sequence it writes, so the step joins the range still
+  to come that the order puts it in, the one it builds ahead of when it lands first, and
+  never a range that has landed, since that range's call was made and the step would
+  reopen it
+  ([D109 (ranges-follow-the-order)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d109)).
+  Give the step a bare range of its own instead, written before you run the verb, when it
+  brings a call the human has to make before it lands. 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
+  ([D92 (build-ranges)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d92)).
+  The verb's ending names each range it re-cut, and an advisory names any it left for
+  you; re-cut that one in the same confirmed edit, and `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

package/skills/order/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: order
-description: "Set the build order: turn the human's sequence (or a relative one, such as 7 and 8 before 5) into the full list of undone steps and write it by shelling `plumbbob order`, never by editing intent.md. A step keeps its number; the sequence moves."
+description: "Set the build order: turn the human's sequence (or a relative one, such as 7 and 8 before 5) into the full list of undone steps and write it by shelling `plumbbob order`, never by editing intent.md. A step keeps its number; the sequence moves, and the CLI re-cuts the build ranges to follow it."
 argument-hint: "[steps in the sequence to build them, such as 1, 6, 2-4, 7, 5]"
 disable-model-invocation: true
 model: haiku
@@ -15,7 +15,10 @@ A step keeps its number for life, so once `/plumbbob:step` or `/plumbbob:refine`
 that has to land before an existing one, the sequence to build them stops being the
 numbering (`4, 7, 8, 5, 10, 6`). This skill writes that sequence down where every other move
 reads it: the `## Build order` line in `intent.md`, which `plumbbob status`, a bare
-`/plumbbob:build`, `plumbbob checkpoint`, and the card's Next Up all follow.
+`/plumbbob:build`, `plumbbob checkpoint`, and the card's Next Up all follow. When the plan
+carries `## Build ranges`, the same verb re-cuts them to follow the sequence, so
+`/plumbbob:run` walks the steps the new order put in its range
+([D109 (ranges-follow-the-order)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d109)).
 
 ## Wrong-state refusal
 
@@ -39,22 +42,22 @@ after the step in flight is the usual reason to run it.
    as typed, and the line it writes spells the span out. `plumbbob order --reset` drops the
    line, and the plan reads in document order again.
 4. **Relay the ending verbatim, then stop.** The verb prints its whole ending: the
-   `**Build order**: 7, 8, 5, 10, 6` line, a blank line, and the `**Next Up**` pointer (back
-   at the step in flight, or forward to the first step in the new sequence). Run no second
-   command but the one in step 5. A refusal (a number the plan lacks, a repeat, a step
-   already checkpointed) is the CLI's call: report it verbatim, never retry or work around
-   it, and ask the human which number they meant.
-5. **Read the ranges when the plan has them.** If the dashboard injected above shows a
-   `ranges` block, run `plumbbob status` after the verb and read that block again. A `⚠`
-   row that was not there before means the new sequence broke a range (most often
-   `the build order puts step 11 inside it`). This skill edits nothing, so it cannot re-cut
-   one: open the turn with one line naming the range, its drift words, and
-   `/plumbbob:refine` as the move that re-cuts it, then the verb's ending, whole, as the
-   turn's last text. With no new `⚠` row, or no ranges block, relay the ending alone.
+   `**Build order**: 7, 8, 5, 10, 6` line; a
+   `**Build ranges**: range 2 of 3 re-cut (steps 10,4-6)` line when the new sequence moved a
+   step into or out of a range, naming each range it re-cut; an advisory for each range the
+   order left for the human, in the words its dashboard row carries
+   (`Range 2 of 3 needs a re-cut ⚠ (...)`), with
+   `→ /plumbbob:refine ranges` beneath the last; and the `**Next Up**` pointer (back at the
+   step in flight, or forward to the first step in the new sequence). Relay it whole as the
+   turn's last text and run no second command: the advisory already names the range and the
+   move, so there is no dashboard to read again. A refusal (a number the plan lacks, a
+   repeat, a step already checkpointed) is the CLI's call: report it verbatim, never retry
+   or work around it, and ask the human which number they meant.
 
 ## The one hard contract
 
 The line is written by the **dumb CLI**, never by an edit. This skill carries **no Edit and
 no Write tool** on purpose: you may not touch `intent.md` yourself. Compose, get approval,
-then shell `plumbbob order`; that is the only write path, and it is the one that validates
-every number against the plan.
+then shell `plumbbob order`; that is the only write path, it validates every number against
+the plan, and it is the one that re-cuts the ranges, so a range the order leaves for the
+human is `/plumbbob:refine`'s to re-cut, never yours to edit here.

package/skills/refine/SKILL.md

@@ -54,18 +54,25 @@ is fine; refining is always available.
   Show the before/after for each, and **write only what the human approves**. A repair
   that inserts a step, or moves one ahead of another, keeps every number where it is and
   writes the sequence instead: shell `plumbbob order 7 8 5` with the undone steps in the
-  sequence to build them, and the `## Build order` line it writes is what every next-step
-  pick follows. Never renumber, and never edit that line by hand.
+  sequence to build them, an inserted step included even when it builds last, and the
+  `## Build order` line it writes is what every next-step pick follows. Never renumber,
+  and never edit that line by hand.
 
-  **A repair keeps the build ranges true.** When the plan carries `## Build ranges`, a
-  step the repair adds goes into a range (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), 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 repair breaks is re-cut in the same before/after
+  **A repair keeps the build ranges true.** When the plan carries `## Build ranges`,
+  `plumbbob order` re-cuts them to follow the sequence it writes
+  ([D109 (ranges-follow-the-order)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d109)):
+  a step it places joins the range whose steps sit on both sides of it, else the one it
+  builds ahead of, else the one it builds after, never a bare range, and never a range that
+  has landed, since that range's call was made and the step would reopen it; its ending
+  names each range it re-cut. Edit a range yourself only where the
+  order cannot say it, and before you run the verb: a bare range of its own for a step
+  that brings a call the human has to make before it lands, or a re-cut that moves where a
+  call falls, shown in the same before/after
   ([D92 (build-ranges)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d92)).
-  Read `plumbbob status` once the edits are written: its ranges block carries a `⚠` row
+  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 verb's ending names as still needing a re-cut is yours to re-cut in
+  the same approved edit. Read `plumbbob status` once the edits are written: its ranges block carries a `⚠` row
   for a range naming a step the plan lacks, a step two ranges name, a step the build order
   puts inside a range that does not name it, and an undone step no range names, and none
   once the section is sound.

package/skills/step/SKILL.md

@@ -48,29 +48,33 @@ grew, but its everyday job is to sharpen, not to invent.
    `**Scope:**` header; drop the scope and it falls back to that default → build slug →
    bare, and the type to `feat` ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). Aim for a soft
    ≤72 chars, no gate. Revise the existing step in place; only append when you are
-   genuinely adding an increment. An appended step keeps the next free number for life;
-   when it has to land before an existing undone step, place it by sequence, never by
-   renumbering: shell `plumbbob order 7 8 5` with every undone step in the sequence to
-   build them, and the `## Build order` line it writes is what `status`, a bare
+   genuinely adding an increment. An appended step keeps the next free number for life,
+   and it takes its place by sequence, never by renumbering: shell `plumbbob order 7 8 5`
+   with every undone step in the sequence to build them, the new step included even when
+   it builds last, and the `## Build order` line it writes is what `status`, a bare
    `/plumbbob:build`, and the card's Next Up then follow.
 
-   **Keep the build ranges true.** When the plan carries `## Build ranges`, a step you add
-   goes into a range: the one it builds with (`/plumbbob:build 6-9` becomes `6-10`, or
-   `6-9,14` for a step numbered past the next range), or a bare range of its own when it
-   brings a call the human has to make before it lands
+   **Keep the build ranges true.** When the plan carries `## Build ranges`,
+   `plumbbob order` files the step for you: it re-cuts the ranges to follow the sequence it
+   writes, so a step joins the range whose steps sit on both sides of it, else the range it
+   builds ahead of, else the one it builds after
+   ([D109 (ranges-follow-the-order)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d109)):
+   never a bare range, and never a range that has landed, since that range's call was made
+   and the step would reopen it. Edit `## Build ranges` yourself only where the order
+   cannot say what you mean, and before you run the verb. A step that brings a call the
+   human has to make before it lands gets a bare range of its own
    ([D92 (build-ranges)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d92)).
-   Either way it is a range still to come, 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 step the build order places between two of a range's steps belongs to that range. A
-   split or re-cut that moves where a call falls moves the stop with it, so re-cut any
-   range the edit breaks, and show the range edit in the same before/after, since it
-   changes where the human will be asked. The edit lands on the item's command, the
-   range's definition, not on the command the card names: the card names `/plumbbob:run`
-   for the range, and the turn hook mints a run's grant from the plan as the human types
-   the run, so the next run lands the range as you re-cut it, while a run already typed
-   keeps the grant it minted
+   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 split or re-cut that moves where a call falls moves the stop with it. Show
+   any range edit in the same before/after, since it changes where the human will be
+   asked. The verb's ending names each range it re-cut
+   (`**Build ranges**: range 3 of 5 re-cut (steps 14,6-9)`), and an advisory beneath it
+   names any range the order left for you: re-cut that one by hand, in the same approved
+   edit. The edit lands on the item's command, the range's definition, not on the command
+   the card names: the card names `/plumbbob:run` for the range, and the turn hook mints a
+   run's grant from the plan as the human types the run, so the next run lands the range
+   as re-cut, while a run already typed keeps the grant it minted
    ([D96 (plan-names-the-grant)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d96)).
    Then read `plumbbob status`: its ranges block carries a `⚠` row for any range still
    broken, and none once every undone step sits in exactly one range.
@@ -88,9 +92,10 @@ grew, but its everyday job is to sharpen, not to invent.
 - **One verifiable increment.** Each step carries a done-when `/plumbbob:verify` can check
   and a seam small enough to review in one pass.
 - **Edit `## Steps` only**, in the standard format `status` and `build` parse, plus the
-  `## Build ranges` items a step edit moves: never the Roadmap, never loose prose. A done
-  step (`[x]`) is history; do not rewrite it. The `## Build order` line is
-  `plumbbob order`'s to write, never yours to edit.
+  `## Build ranges` items the order cannot settle (a bare range of its own, a stop that
+  moves): never the Roadmap, never loose prose. A done step (`[x]`) is history; do not
+  rewrite it. The `## Build order` line is `plumbbob order`'s to write, never yours to
+  edit, and so is a range the order re-cuts.
 - **Cite the plan's own numbers in the linked form.** A `D`/`C`/`Q` you write into a
   step's done-when, seam, or notes reads `[D4 (default-waves)](#d4)`; the slug travels
   with the number, and the link lands on the `<a id="d4">` anchor minted where the item