plumbbob 0.13.0 → 0.13.2

package/dist/verbs/handoff.js

@@ -33,18 +33,22 @@
 // Every tier's ending is emitted here, so no skill has to fake the furniture in
 // prose: `--plan` renders the plan-pause ending and `--driver` the driver
 // turn's pointer, the two endings the session state cannot tell apart from the
-// ones above. The driver pointer reads the phase it lands in: a spike open over
+// ones above, and `--stop` the stop card that closes a run's range, which reads
+// a boundary the session state cannot tell from a plain one either. The stop
+// card renders once too, under its own stamp in `STOP`, which also carries the
+// turn it printed in for `plumbbob harvest`'s latch. The driver pointer reads the phase it lands in: a spike open over
 // the step names closing the spike, a step exit (a revert, an abandon, a spike
 // closed at the boundary) finds nothing in flight and points forward, with no
 // Verdict either way, since nothing landed.
 import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { PLAN_COMMIT_MARKER, commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.js";
-import { blocks, printEnding } from "../lib/notice.js";
+import { basename, join, relative } from 'node:path';
+import { PLAN_COMMIT_MARKER, commitNumstat, commitsBetween, commitsSince, diffNumstat, diffPatch, findRepoRoot, } from "../lib/git.js";
+import { blocks, notice, printEnding, transition } from "../lib/notice.js";
+import { hasStep } from "../lib/steplist.js";
 import { isArtifactPath, parseStepSeam } from "../lib/intent.js";
-import { buildLogPath, checkpointsPath, detailPath, hasSession, inSpike, intentPath, pausePath, readStats, readTurn, resolveBuild, seamPath, stepPath, tickPath, } from "../lib/sidecar.js";
-import { buildOrderPhrase, countDiff, diffRowValue, foldVerdict, lastLedgerSha, normalizeDetailHeadings, parkedPhrase, parseBuildOrder, parseConstraintCount, parseLastCheckpoint, parseOrderedSteps, parseParkTotals, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, recapLines, remainingOrder, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
+import { buildLogPath, checkpointsPath, detailPath, hasSession, inSpike, intentPath, pausePath, readStats, readStop, readTurn, resolveBuild, seamPath, stepPath, tickPath, writeStop, } from "../lib/sidecar.js";
+import { buildOrderPhrase, countDiff, diffRowValue, foldVerdict, lastLedgerSha, measureRange, normalizeDetailHeadings, parkedPhrase, parseBuildOrder, parseBuildRanges, parseConstraintCount, parseLastCheckpoint, parseOrderedSteps, parseParkTotals, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, rangeLanded, rangeSpan, rangeStanding, recapLines, remainingOrder, resolveRun, runBracket, seamRowFromDiff, spentRowValue, stopFollowUp, summaryCheckRow, } from "../lib/orient.js";
 // The inline-diff threshold (docs/presentation.md): at 20 changed lines or
 // fewer the patch rides the turn; at 21 it stays in the working tree behind
 // the counted diff row.
@@ -83,13 +87,17 @@ export function handoff(cwd, args = []) {
         return 1;
     }
     const { build: slug, rest } = resolveBuild(root, args);
-    if (rest.includes('--plan') && rest.includes('--driver')) {
-        process.stderr.write('plumbbob: handoff: --plan and --driver name different tiers; pass one.\n');
+    const tiers = ['--plan', '--driver', '--stop'].filter((flag) => rest.includes(flag));
+    if (tiers.length > 1) {
+        process.stderr.write(`plumbbob: handoff: ${tiers.join(' and ')} name different tiers; pass one.\n`);
         return 1;
     }
     // A build named by flag rides any command that reprints this ending, since
     // the cursor may point elsewhere.
     const named = args.includes('--build') ? slug : null;
+    if (rest.includes('--stop')) {
+        return stopCard(root, slug, named, rest.includes('--full'));
+    }
     const intent = readOr(intentPath(root, slug));
     // In build order, so the pointer names the step a bare `plumbbob build`
     // would enter; the build-log feeds the park count beneath it.
@@ -108,8 +116,8 @@ export function handoff(cwd, args = []) {
         const detail = settleDetail(root, rawDetail);
         const plan = [
             SEAM_RULE,
-            nextUpBlock(first, steps.length, where, nextUpNote(intent, buildLog, null)),
-            planCallBlock(first),
+            nextUpBlock(intent, buildLog, first, null, where),
+            planCallBlock(first, cardRun(intent, null)),
         ];
         const command = reprintCommand('--plan', undefined, named);
         return emit(root, { tier: 'decision', render: 'plan', command }, withRecommendation(plan, parseRecommendation(detail)));
@@ -137,7 +145,7 @@ export function handoff(cwd, args = []) {
     if (current === null) {
         // Nothing measured yet (a fresh session): no Verdict, just the forward pointer.
         return emit(root, { tier: 'orientation', render: 'pointer' }, [
-            nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)),
+            nextUpBlock(intent, buildLog, nextUp, current, where),
         ]);
     }
     // A step is pending, and its hand-off is the pause, while it is in flight.
@@ -147,11 +155,12 @@ export function handoff(cwd, args = []) {
     // which pause to render.
     const pending = inFlight !== null || (explicit !== undefined && steps.some((s) => s.n === current && !s.done));
     if (!pending) {
-        // The boundary: the orientation-tier ending, the state word and the forward
-        // pointer, no decision pending and so no Your Call. The same two parts the
-        // checkpoint printed for itself, from the same call.
+        // The boundary: the orientation-tier ending, the state word, the Stop part
+        // where a range just landed, and the forward pointer, no decision pending
+        // and so no Your Call. The same parts the checkpoint printed for itself,
+        // from the same call.
         const landed = boundaryEnding(root, slug, current);
-        return emit(root, { tier: 'orientation', render: 'boundary' }, [landed.verdict, landed.pointer]);
+        return emit(root, { tier: 'orientation', render: 'boundary' }, [landed.verdict, landed.stop, landed.pointer]);
     }
     // The pause: the whole turn as one contiguous block, each part a labeled line
     // with one blank line between, and the only fence the readout's own (plus the
@@ -197,7 +206,7 @@ export function handoff(cwd, args = []) {
     if (inline) {
         parts.push(fence('diff', patch.split('\n')).join('\n'));
     }
-    parts.push(verdict, nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)), yourCallBlock(current, checkGreen));
+    parts.push(verdict, nextUpBlock(intent, buildLog, nextUp, current, where), yourCallBlock(current, checkGreen, cardRun(intent, current)));
     const command = reprintCommand('--full', explicit, named);
     return emit(root, { tier: 'decision', render: 'card', command }, withRecommendation(parts, parseRecommendation(detail)));
 }
@@ -267,25 +276,416 @@ function writePause(root, slug, stamp) {
     }
 }
 /**
- * The two CLI-rendered parts of a boundary ending: the Verdict folded from
- * everything measurable right now, and the pointer at the step to come.
+ * The CLI-rendered parts of a boundary ending: the Verdict folded from
+ * everything measurable right now, the Stop part when the landing finished a
+ * range, and the pointer at the step to come.
  *
  * `step` is the step that just landed, or null at a plan commit, where nothing
- * was measured and the Verdict vanishes. A transition verb prints these beneath
- * its own lead line, so a boundary reads identically whether `checkpoint`
- * emitted it or a later `handoff` did; the paths a stray advisory named are the
- * one part that does not survive, and the commit holds those.
+ * was measured and the Verdict and the Stop part both vanish. A transition verb
+ * prints these beneath its own lead line, so a boundary reads identically
+ * whether `checkpoint` emitted it or a later `handoff` did; the paths a stray
+ * advisory named are the one part that does not survive, and the commit holds
+ * those.
  */
 export function boundaryEnding(root, slug, step) {
     const intent = readOr(intentPath(root, slug));
     const steps = parseOrderedSteps(intent);
     const nextUp = steps.find((s) => !s.done && s.n !== step);
-    const note = nextUpNote(intent, readOr(buildLogPath(root, slug)), step);
+    const where = relative(root, intentPath(root, slug));
+    const landed = landedRange(intent, steps, step);
     return {
         verdict: step === null ? null : landedVerdict(root, slug, intent, step),
-        pointer: nextUpBlock(nextUp, steps.length, relative(root, intentPath(root, slug)), note),
+        stop: landed === null ? null : stopLead(landed, where),
+        range: landed === null ? null : { item: landed.range.item, count: landed.count },
+        pointer: nextUpBlock(intent, readOr(buildLogPath(root, slug)), nextUp, step, where),
     };
 }
+/**
+ * The range that lands its steps whose last undone step was `step`, now
+ * landed, or null for every other landing: one that leaves its range open, a
+ * bare range (its stop was its own pause), a step no range names, a plan
+ * without ranges, and the plan commit, where nothing landed.
+ */
+function landedRange(intent, steps, step) {
+    if (step === null) {
+        return null;
+    }
+    const { count, completed } = rangeStanding(parseBuildRanges(intent), steps, step);
+    return completed === null || completed.bare ? null : { range: completed, count, step };
+}
+/**
+ * The Stop part: why the build stops at this boundary. One labeled line, the
+ * range over the count, a plain hyphen, the stop as the plan wrote it, and a
+ * bracket pointing at the item, where its note can be read. The stop card
+ * opens on the same line, moved to the top of the card.
+ */
+function stopLead(landed, where) {
+    return transition({
+        label: 'Stop',
+        fact: `Range ${landed.range.item} of ${landed.count} landed - ${landed.range.stop}`,
+        detail: [detailsLink(where, landed.range.line)],
+    });
+}
+/**
+ * The `details:` clause every bracket on a card carries, in its short linked
+ * form: the file's name and line as the link's text, and its path from the
+ * repo root with a `#L41` fragment as the target. With no line, the name links
+ * the whole file, as the Summary lead's does, since the whole file is the
+ * detail.
+ *
+ * The full path was noise on every card while the name alone still says which
+ * file, and a relative target keeps any one machine's path out of a pasted
+ * card (D107 (short-linked-paths)).
+ */
+export function detailsLink(path, line) {
+    const name = basename(path);
+    return line === null ? `details: [${name}](${path})` : `details: [${name}:${line}](${path}#L${line})`;
+}
+/**
+ * The stop card that closes a run's range (docs/presentation.md): the Stop
+ * lead, the range's Summary and highlights from the range's detail file, the
+ * Readout measured across the range, the Verdict, the Harvested part while a
+ * park is open, Next Up, Your Call, and the recommendation.
+ *
+ * It renders for the range the last landing completed, and refuses with a
+ * step in flight, with no range just landed, and with a detail file written
+ * for anything but that range, since a card with none of the model's review
+ * on it would ask the human to approve nothing. It renders once per stop:
+ * while the STOP stamp matches the range and what the card showed, a later
+ * render is the one-line reminder, and `--full` prints the card whatever the
+ * stamp says. Every card it prints rewrites the stamp with the turn it printed
+ * in, which is the turn `plumbbob harvest` waits past.
+ */
+function stopCard(root, slug, named, full) {
+    const intent = readOr(intentPath(root, slug));
+    const steps = parseOrderedSteps(intent);
+    const landed = stopRange(root, slug, intent, steps);
+    if (typeof landed === 'string') {
+        process.stderr.write(landed);
+        return 1;
+    }
+    const { range, count, step } = landed;
+    const detail = settleDetail(root, readOr(detailPath(root)));
+    if (parseDetailRange(detail) !== range.item) {
+        process.stderr.write(notice({
+            fact: 'no stop card to render',
+            detail: [`the detail file is not range ${range.item}'s`],
+            remedy: `write range ${range.item}'s detail in .plumbbob/detail.md, then plumbbob handoff --stop`,
+        }));
+        return 1;
+    }
+    const where = relative(root, intentPath(root, slug));
+    const buildLog = readOr(buildLogPath(root, slug));
+    const review = stopReview(root, slug, intent, range, detail);
+    const parks = parkList(buildLog);
+    const harvest = harvestPart(parks, harvestProposals(detail));
+    const hash = stopHash(detail, review.stamped, harvest ?? '');
+    const stamp = readStop(root, slug);
+    if (!full && stamp !== null && stamp.range === range.item && stamp.hash === hash) {
+        // The stop the human already read, unchanged: the answer above this line
+        // is what they asked for, and the card would push it off the screen.
+        const command = reprintCommand('--stop', undefined, named);
+        return emit(root, { tier: 'decision', render: 'stop-reminder', command }, [
+            `**Next Up**: Back to Range ${range.item} of ${count}'s stop - ${range.stop}`,
+        ]);
+    }
+    writeStop(root, slug, { range: range.item, turn: readTurn(root), hash });
+    const nextUp = steps.find((s) => !s.done && s.n !== step);
+    const parts = [
+        stopLead(landed, where),
+        summaryBlock(parseSummary(detail), relative(root, detailPath(root))),
+    ];
+    if (review.readout.length > 0) {
+        parts.push([READOUT_LABEL, '', ...fence('text', review.readout)].join('\n'));
+    }
+    parts.push(review.verdict);
+    if (harvest !== null) {
+        parts.push(harvest);
+    }
+    parts.push(
+    // The note carries no parks segment here: the Harvested lead above sizes the list.
+    nextUpBlock(intent, '', nextUp, step, where), stopCallBlock(leanExample(parks, harvestProposals(detail)), intent));
+    const command = reprintCommand('--stop --full', undefined, named);
+    return emit(root, { tier: 'decision', render: 'stop', command }, withRecommendation(parts, parseRecommendation(detail)));
+}
+/**
+ * The range the stop card reviews: the one the last landing completed, or the
+ * refusal that says why no stop card renders, with the move that does render
+ * this moment.
+ */
+function stopRange(root, slug, intent, steps) {
+    const refuse = (why, remedy) => notice({ fact: 'no stop card to render', detail: [why], remedy });
+    const inFlight = readMarker(stepPath(root, slug));
+    if (inFlight !== null) {
+        return refuse(`step ${inFlight} is in flight`, 'plumbbob handoff renders its pause');
+    }
+    const last = parseLastCheckpoint(readOr(checkpointsPath(root, slug)));
+    if (last === null) {
+        return refuse('no step has landed', 'plumbbob handoff renders the pointer');
+    }
+    const landed = landedRange(intent, steps, last.n);
+    if (landed === null) {
+        const { completed, count } = rangeStanding(parseBuildRanges(intent), steps, last.n);
+        const why = completed === null
+            ? `step ${last.n} landed last, and completed no range`
+            : `range ${completed.item} of ${count} is bare, and its stop was step ${last.n}'s pause`;
+        return refuse(why, 'plumbbob handoff renders this boundary');
+    }
+    return landed;
+}
+/**
+ * Measure a landed range and fold its Verdict: the CLI's rows across the
+ * range's commits, the ledger, stats.json, and the last check, joined with
+ * the three judgment rows the range's detail wrote, the measured ones winning
+ * where both exist.
+ *
+ * The card and the record read the review through this one call, so the Log
+ * keeps exactly what the card showed.
+ */
+function stopReview(root, slug, intent, range, detail) {
+    const measure = rangeMeasure(root, slug, intent, range);
+    const rows = { ...(parseRecap(detail, 'range')?.rows ?? {}), ...measure.rows };
+    const { ladder, worst } = foldVerdict(rows, measure.stats, 'range');
+    return {
+        readout: recapLines(rows, {
+            steps: measure.steps,
+            diff: measure.diff,
+            spent: measure.spent,
+            constraints: parseConstraintCount(intent),
+        }),
+        verdict: verdictLine(ladder, worst),
+        stamped: recapLines(measure.rows, { steps: measure.steps, diff: measure.diff, spent: null, constraints: 0 }),
+    };
+}
+/**
+ * Read what a landed range's measures are taken from: each checkpoint's
+ * commit the ledger names for a step of the range, the first-parent commits
+ * across the range's span for the out-of-band count, stats.json, and the last
+ * check's summary.
+ */
+function rangeMeasure(root, slug, intent, range) {
+    const checkpoints = readOr(checkpointsPath(root, slug));
+    const commits = {};
+    for (const line of checkpoints.split('\n')) {
+        const m = /^step\s+(\d+)\s+(\S+)/.exec(line.trim());
+        const sha = m?.[2];
+        if (sha !== undefined && hasStep(range.steps, Number(m?.[1]))) {
+            commits[sha] = commitNumstat(root, sha);
+        }
+    }
+    const span = rangeSpan(checkpoints, range);
+    return measureRange({
+        range,
+        intent,
+        checkpoints,
+        stats: readStats(root, slug),
+        commits,
+        between: span === null ? [] : commitsBetween(root, span.from, span.to, PLAN_COMMIT_MARKER),
+        summary: readCheckSummary(root),
+    });
+}
+/**
+ * The stamp's hash of a stop card: the range's detail file, the measured rows
+ * as rendered, and the Harvested part, which reads the park list. Never `spent`,
+ * as at a pause.
+ */
+function stopHash(detail, measured, harvest) {
+    const hash = createHash('sha256');
+    for (const part of [detail, ...measured, harvest]) {
+        hash.update(part).update('\0');
+    }
+    return hash.digest('hex');
+}
+/**
+ * The park list under `build-log.md`'s `## Park list`, each line with its
+ * handle: its place in the list, counting every line ever parked, harvested
+ * ones included.
+ *
+ * A line is never deleted from the list, only flipped, so the handle is
+ * stable for the life of the build, and it counts the same lines the note's
+ * `parked 3 of 8 open` does. The stop card prints the handle and the text
+ * from here, and `plumbbob harvest` matches a proposal to its park by the
+ * handle alone.
+ */
+export function parkList(buildLog) {
+    const lines = buildLog.split('\n');
+    const start = lines.findIndex((l) => l.trim() === '## Park list');
+    if (start === -1) {
+        return [];
+    }
+    const end = lines.findIndex((l, i) => i > start && l.startsWith('## '));
+    return lines.slice(start + 1, end === -1 ? lines.length : end).flatMap((line) => {
+        const m = /^-\s+\[([ xX])\]\s+(\S.*)$/.exec(line.trim());
+        return m === null ? [] : [{ open: m[1] === ' ', text: (m[2] ?? '').trim() }];
+    }).map((park, i) => ({ handle: i + 1, ...park }));
+}
+/**
+ * The proposals under a detail file's `## Harvest` section, one per
+ * `- P6 → tangent: <the reason>` line, in the order written. The handle is the
+ * one the card prints (D105 (park-handles)); the `- park 6 →` form a detail
+ * written before it carried is still read.
+ *
+ * The class is read as written, whatever its word: the card shows the
+ * proposal the model made, and `plumbbob harvest` is what refuses one outside
+ * blocker, tangent, and pivot. A line in any other shape is not a proposal.
+ */
+export function harvestProposals(detail) {
+    const lines = detail.split('\n');
+    const start = lines.findIndex((l) => /^##\s+Harvest\s*$/i.test(l.trim()));
+    if (start === -1) {
+        return [];
+    }
+    const end = lines.findIndex((l, i) => i > start && l.startsWith('## '));
+    return lines.slice(start + 1, end === -1 ? lines.length : end).flatMap((line) => {
+        const m = /^-\s+(?:P|park\s+)(\d+)\s*(?:→|->)\s*([\w-]+)\s*(?::\s*(.*))?$/i.exec(line.trim());
+        return m === null ? [] : [{ handle: Number(m[1]), kind: (m[2] ?? '').toLowerCase(), reason: (m[3] ?? '').trim() }];
+    });
+}
+/**
+ * The range a detail file reviews, read off its `# Detail · Range <n> · <stop>`
+ * header, or null when the first line is not a range's header (a step's
+ * detail, a boundary harvest's, or a file written without one).
+ */
+export function parseDetailRange(detail) {
+    const first = detail.trimStart().split('\n', 1)[0] ?? '';
+    const m = /^#\s+Detail\s*·\s*Range\s+(\d+)\b/.exec(first);
+    return m === null ? null : Number(m[1]);
+}
+/**
+ * The stop card still waiting for its reply, or null when none waits: a STOP
+ * stamp, a detail file whose header names the stamp's range, and that range
+ * still parsing and reading as landed. The record clears the stamp and the
+ * detail file, so the wait ends with it.
+ *
+ * The digest is left to the record's own latch: a detail file rewritten for
+ * a re-render that has not run yet still waits, and a stamp from before the
+ * digest carries none. The landed condition is what keeps a re-cut from
+ * wedging the build, since a range re-cut to take a new step stops waiting.
+ * The stamp is the build's own but the detail file is the session's, so in a
+ * session of several builds, a stamp left in this build and another build's
+ * card for the same range number read as this build's card waiting.
+ */
+export function waitingCard(root, slug, intent) {
+    const stamp = readStop(root, slug);
+    if (stamp === null || parseDetailRange(readOr(detailPath(root))) !== stamp.range) {
+        return null;
+    }
+    const plan = parseBuildRanges(intent);
+    const range = plan.ranges.find((r) => r.item === stamp.range);
+    if (range === undefined || !rangeLanded(range, parseOrderedSteps(intent))) {
+        return null;
+    }
+    return { range: range.item, count: plan.ranges.length + plan.malformed.length };
+}
+/**
+ * The Harvested part: a lead that sizes the list, then one bullet per open
+ * park in list order, its `P6` handle and text from the list and, behind the
+ * arrow, the lean the detail file proposes: `lean: tangent, <the reason>`. A
+ * park the detail left out reads `no lean proposed`, so a silent omission is
+ * one on the card. Null with no park open, which renders the card without the
+ * part.
+ *
+ * A bullet, never a numbered item, because a markdown list renumbers: open
+ * parks 6 and 8 would render as 6 and 7, and the number read would not be the
+ * one the record matches (D105 (park-handles)).
+ */
+function harvestPart(parks, proposals) {
+    const open = parks.filter((p) => p.open);
+    if (open.length === 0) {
+        return null;
+    }
+    const items = open.map((park) => {
+        const proposal = proposals.find((p) => p.handle === park.handle);
+        const lean = proposal === undefined ? 'no lean proposed' : proposal.reason.length === 0 ? `lean: ${proposal.kind}` : `lean: ${proposal.kind}, ${proposal.reason}`;
+        return `- P${park.handle} · ${park.text} → ${lean}`;
+    });
+    const lead = `**Harvested**: ${open.length} of ${parks.length} parked idea${parks.length === 1 ? '' : 's'} open`;
+    return [lead, '', ...items].join('\n');
+}
+/**
+ * The stop card's Your Call block: the replies that settle the card in one
+ * message, each recording the review and every lean before what it names.
+ *
+ * While a park is open (`example` set), one line beneath the label says that
+ * approving locks in each lean and that changing one means saying so first,
+ * with the example naming a handle on the card, since the reply is a decision
+ * on every lean at once (D106 (leans-harvested)); the direction row then
+ * carries no example of its own. The second row is the move after the stop,
+ * read through `stopFollowUp` so the dashboard and `plumbbob build`'s refusal
+ * name the same one: the next range's run, the finish on the plan's last
+ * range, and nothing when the run would refuse (a flagged range, or a next
+ * step no range names), where the note beneath Next Up carries the drift
+ * words. With no park open, no line renders, the rows record the review alone,
+ * and direction is a change to it.
+ */
+function stopCallBlock(example, intent) {
+    const parked = example !== null;
+    const what = parked ? 'them' : 'it';
+    const moves = [
+        callLine('`looks good`', parked ? 'I record the review and every lean as proposed, folding a blocker into the plan; back to the boundary' : 'I record the review; back to the boundary'),
+    ];
+    const follow = stopFollowUp(intent);
+    if (follow === 'finish') {
+        moves.push(callLine('`/plumbbob:finish`', `I record ${what} the same way, then write the report and close the build`));
+    }
+    else if (follow !== null) {
+        moves.push(callLine('`/plumbbob:run`', `I record ${what} the same way, then run range ${follow.range.item} of ${follow.count} to its stop`));
+    }
+    moves.push(callLine('anything that reads as direction', `I re-render the card with the ${parked ? 'lean' : 'review'} changed; nothing is recorded until you approve`), callLine('`expand`, or any question', 'I show more of what is there; nothing changes, and `show the stop` brings all of this back'));
+    const lockIn = parked ? [`Approving locks in each lean above; to change one, say so first (\`${example}\`).`, ''] : [];
+    return ['**Your Call**:', '', ...lockIn, ...moves].join('\n');
+}
+/**
+ * The lock-in line's example, a reply naming a park on this card by its
+ * handle: the first open park recast as the class its lean is not, a blocker
+ * for a tangent, a pivot, or no lean at all, and a tangent for a blocker, so
+ * it always names a change the card could take. Null with no park open, where
+ * there is no lean to change.
+ */
+function leanExample(parks, proposals) {
+    const first = parks.find((p) => p.open);
+    if (first === undefined) {
+        return null;
+    }
+    const kind = proposals.find((p) => p.handle === first.handle)?.kind;
+    return `make P${first.handle} a ${kind === 'blocker' ? 'tangent' : 'blocker'}`;
+}
+/**
+ * A stop's record for the Log: the card as the human settled it, with the
+ * full story behind each highlight beneath. The Summary and its highlights,
+ * the Readout fence, the Verdict, the Harvested part, the recommendation, then
+ * the numbered sections' bodies, blank-line separated and unindented; the
+ * caller nests it under the range's dated Log line.
+ *
+ * Measured, not recalled, through the same review the card rendered. The
+ * Harvested part reads the park list as `buildLog` holds it, so the caller
+ * passes the list from before its record flips the settled parks, and the
+ * part shows each class the human confirmed. Null when the detail file
+ * reviews no range the plan declares.
+ */
+export function stopRecord(root, slug, detail, buildLog) {
+    const intent = readOr(intentPath(root, slug));
+    const item = parseDetailRange(detail);
+    const range = parseBuildRanges(intent).ranges.find((r) => r.item === item);
+    if (range === undefined) {
+        return null;
+    }
+    const review = stopReview(root, slug, intent, range, detail);
+    const summary = parseSummary(detail);
+    const parts = [];
+    if (summary !== null) {
+        parts.push(recordSummary(summary));
+    }
+    if (review.readout.length > 0) {
+        parts.push([READOUT_LABEL, '', ...fence('text', review.readout)].join('\n'));
+    }
+    parts.push(review.verdict);
+    const harvest = harvestPart(parkList(buildLog), harvestProposals(detail));
+    if (harvest !== null) {
+        parts.push(harvest);
+    }
+    return [...withRecommendation(parts, parseRecommendation(detail)), ...sectionBlocks(parseSections(detail))].join('\n\n');
+}
 /**
  * The step's record for the build-log's Log: the pause as the human approved
  * it, with the full story behind each highlight beneath. The Summary and its
@@ -462,7 +862,7 @@ function summaryBlock(summary, where) {
     if (summary === null) {
         return '';
     }
-    const lead = `**Summary**: ${summary.lead} (details: \`${where}\`)`;
+    const lead = `**Summary**: ${summary.lead} (${detailsLink(where, null)})`;
     if (summary.highlights.length === 0) {
         return lead;
     }
@@ -597,11 +997,20 @@ function readCheckSummary(root) {
  * `revert` comes last, because a destructive move is named rather than
  * discovered. `looks good` renders only while the measured check is green;
  * offering a move that would refuse teaches a false ceremony.
+ *
+ * `run` is what `/plumbbob:run` typed at this pause names. Inside a range
+ * that lands its steps, with steps still ahead of this one, the run rides
+ * second as the other approval: it lands this step and the rest of the range.
+ * At a bare range's pause, and at a range's last step, it does no more than
+ * `looks good`, so the block keeps its four moves.
  */
-function yourCallBlock(step, checkGreen) {
+function yourCallBlock(step, checkGreen, run) {
     const moves = [];
     if (checkGreen) {
         moves.push(callLine('`looks good`', `I checkpoint Step ${step}; back to the boundary`));
+        if (run.ok && !run.range.bare && run.left[0] === step && run.left.length > 1) {
+            moves.push(callLine('`/plumbbob:run`', `I checkpoint Step ${step}, then run the rest of range ${run.range.item} to its stop`));
+        }
     }
     moves.push(callLine('`expand`, or any question', 'I show more of what is there; nothing changes, and `show the pause` brings all of this back'));
     moves.push(callLine('anything that reads as direction', 'I take it as what to change; nothing lands until you approve'));
@@ -621,9 +1030,14 @@ function callLine(move, outcome) {
  * there. Nothing is recorded yet, so `revert` has nothing to wind back to and
  * vanishes; `looks good` names the step the plan starts at, which is Step 1 at
  * the plan pause and the first undone step after a mid-build refine.
+ *
+ * When that step sits in a range the run can walk, `looks good` names the run
+ * instead, since the run is what the human types next; a step in no range, or
+ * in a flagged one, keeps the build.
  */
-function planCallBlock(first) {
-    const starts = first === undefined ? '' : `; /plumbbob:build starts Step ${first.n}`;
+function planCallBlock(first, run) {
+    const build = first === undefined ? '' : `; /plumbbob:build starts Step ${first.n}`;
+    const starts = run.ok ? `; /plumbbob:run runs range ${run.range.item} from Step ${run.left[0]}` : build;
     return [
         '**Your Call**:',
         '',
@@ -658,10 +1072,11 @@ function spikeNextUpLine(inFlight) {
 // count. The line is a reminder; the dashboard holds the whole sequence.
 const ORDER_CAP = 5;
 /**
- * The line beneath the forward pointer: the build order from the step it
- * names, when `## Build order` re-sequences the plan away from its numbering,
- * and the park count, when anything has been parked; '' when neither says
- * anything, so a plan nobody re-sequenced with an empty park list renders the
+ * The line beneath the forward pointer: the range segment, when the plan
+ * declares build ranges; the build order from the step the pointer names, when
+ * `## Build order` re-sequences the plan away from its numbering; and the park
+ * count, when anything has been parked. '' when none says anything, so a plan
+ * with no ranges, nobody re-sequenced, and an empty park list renders the
  * pointer alone, as before.
  *
  * Indented two spaces, because an indented line continues the part above it
@@ -670,9 +1085,10 @@ const ORDER_CAP = 5;
  * `Nothing planned`: an unharvested list at the end of the plan is the one
  * reminder that matters there.
  */
-function nextUpNote(intent, buildLog, exclude) {
+function nextUpNote(intent, buildLog, exclude, range) {
     const parks = parseParkTotals(buildLog);
     const segments = [
+        range,
         buildOrderPhrase(remainingOrder(parseSteps(intent), parseBuildOrder(intent), exclude), ORDER_CAP),
         parks.total > 0 ? parkedPhrase(parks) : '',
     ].filter((s) => s.length > 0);
@@ -681,11 +1097,61 @@ function nextUpNote(intent, buildLog, exclude) {
 /**
  * The forward pointer with its note beneath, as one part: `blocks` keeps a
  * part's own newlines, so the note rides flush under the line it qualifies.
+ *
+ * `exclude` is the step the turn is about: the step in flight at a pause, the
+ * step just landed at a boundary, null at the plan pause and the plan commit.
+ * While the note suggests a range, the bracket bolds the range's model, since
+ * the run is the range and that is the `/model` the human picks before typing
+ * it.
  */
-function nextUpBlock(nextUp, total, where, note) {
-    const line = nextUpLine(nextUp, total, where);
+function nextUpBlock(intent, buildLog, nextUp, exclude, where) {
+    const steps = parseOrderedSteps(intent);
+    const range = rangeSegment(intent, steps, nextUp, exclude);
+    const line = nextUpLine(nextUp, steps.length, where, range.model ?? nextUp?.model ?? null);
+    const note = nextUpNote(intent, buildLog, exclude, range.segment);
     return note.length === 0 ? line : `${line}\n${note}`;
 }
+/**
+ * The range segment that leads the note, and the model the pointer's bracket
+ * bolds while it suggests a range: the run `/plumbbob:run` typed now would
+ * walk, `range 3 of 5: /plumbbob:run (steps 6-9)`, with the model of the range
+ * holding the step Next Up names; the re-cut words for a flagged range; the
+ * words for a step no range names; or '' for a plan without ranges.
+ *
+ * The bracket is the grant the hook would mint. At a step pause that is the
+ * range holding the step in flight, its bracket opening on that step, since a
+ * run typed there lands it first; at the pause on a range's last step, where
+ * a run ends on that range's stop, the segment names no run
+ * (`range 3 of 5 lands with step 9`). The model is read with the step the turn
+ * is about landed, so at that last-step pause it is the next range's, the one
+ * the human picks a model for. A flagged range, and a range with no
+ * `- model:` line, leave the step's model in the bracket.
+ */
+function rangeSegment(intent, steps, nextUp, exclude) {
+    const landed = steps.map((s) => (s.n === exclude ? { ...s, done: true } : s));
+    const { holding, command } = rangeStanding(parseBuildRanges(intent), landed, nextUp?.n ?? null);
+    const model = holding !== null && command !== null ? holding.model : null;
+    const paused = steps.some((s) => s.n === exclude && !s.done) ? exclude : null;
+    const run = cardRun(intent, paused);
+    if (run.ok) {
+        const name = `range ${run.range.item} of ${run.count}`;
+        const lands = paused !== null && run.left.length === 1;
+        return { segment: lands ? `${name} lands with step ${paused}` : `${name}: /plumbbob:run (${runBracket(run)})`, model };
+    }
+    if (run.kind === 'uncovered') {
+        return { segment: run.words, model };
+    }
+    return { segment: run.kind === 'flagged' ? `range ${run.item} of ${run.count} needs a re-cut (${run.words})` : '', model };
+}
+/**
+ * The run `/plumbbob:run` typed now would walk, as the card names it: the
+ * range holding `paused`, the step waiting at its pause, or with none the
+ * range holding the next undone step. A spike open is the run's refusal to
+ * make, not the card's, so the card names the run that waits beyond it.
+ */
+function cardRun(intent, paused) {
+    return resolveRun({ intent, inFlight: paused, spiking: false, item: null });
+}
 /**
  * The forward pointer: the next undone step with the progress count, its
  * title, and a closing bracket carrying its advisory `- model:` recommendation
@@ -693,19 +1159,19 @@ function nextUpBlock(nextUp, total, where, note) {
  * instead.
  *
  * The model is the second bold token the line spends, because it is the one
- * the human acts on (a `/model` call) before the next run; the path is a bare
- * `path:line` in a code span, the one link form that opens in a host and still
- * reads as a path in a PR diff. The line alone is the driver tier's pointer;
- * every other tier rides `nextUpNote` beneath it, through `nextUpBlock`.
+ * the human acts on (a `/model` call) before the next run; the path is the
+ * short link every `details:` bracket carries (`detailsLink`). The line alone
+ * is the driver tier's pointer; every other tier rides `nextUpNote` beneath
+ * it, through `nextUpBlock`.
  */
-function nextUpLine(nextUp, total, where) {
+function nextUpLine(nextUp, total, where, model = nextUp?.model ?? null) {
     if (nextUp === undefined) {
         return '**Next Up**: Nothing planned - /plumbbob:step or /plumbbob:finish';
     }
     const title = nextUp.title.length > 0 ? ` - ${nextUp.title}` : '';
-    const token = modelToken(nextUp.model);
+    const token = modelToken(model);
     const bracket = token === null ? [] : [`model: **${capitalize(token)}**`];
-    bracket.push(`details: \`${where}:${nextUp.line}\``);
+    bracket.push(detailsLink(where, nextUp.line));
     return `**Next Up**: Step ${nextUp.n} of ${total}${title} (${bracket.join(', ')})`;
 }
 /**