plumbbob 0.13.1 → 0.13.3

package/dist/verbs/harvest.js

@@ -0,0 +1,224 @@
+// `plumbbob harvest`: record a harvest from the detail file. The skill decides
+// and the CLI records (D104 (harvest-records)): the model writes one proposal
+// per open park under the detail file's `## Harvest` section, the human
+// settles them in one reply, and this verb flips each settled park in
+// `build-log.md`, appends the dated Harvest lines, and, when the detail is a
+// range's, writes the range's review beneath a dated Log line, the way
+// `checkpoint` keeps a step's pause beneath its own. It commits nothing: the
+// record rides the next step's checkpoint, or the finish.
+//
+// A stop's record is latched (D103 (stop-latched)). It refuses in the turn
+// the stop card printed, since a run's long turn ends on proposals and that is
+// where a model would carry straight on into recording its own; it refuses a
+// range's detail no stop card showed, read off the digest the card's STOP
+// stamp keeps; and it refuses a range that no longer reads as landed, telling
+// a step landed and reopened from one that joined the range after it landed,
+// which moves to a range still to come. A harvest outside a stop (`# Detail · Harvest`) needs no stamp. A proposal
+// naming a handle the list lacks (`P9` with eight parked), or a class outside
+// the three, refuses the whole record, so the card and the ledger never
+// disagree about which parks are open; a park no proposal names stays open,
+// and the record says nothing about it.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { ending, notice, printEnding, transition } from "../lib/notice.js";
+import { appendHarvest, appendToSection, flipParks, harvestLines, logEntry, stopLogLine } from "../lib/buildlog.js";
+import { checkStopLatch } from "../lib/latch.js";
+import { parseBuildRanges, parseDetailStep, parseLastCheckpoint, parseOrderedSteps, stepShas } from "../lib/orient.js";
+import { activeBuild, buildLogPath, checkpointsPath, clearDetail, clearStop, detailDigest, detailPath, hasSession, intentPath, readStop, } from "../lib/sidecar.js";
+import { hasStep } from "../lib/steplist.js";
+import { boundaryEnding, harvestProposals, parkList, parseDetailRange, stopRecord } from "./handoff.js";
+// The three classes a park settles as, in the order the ending counts them.
+const CLASSES = ['blocker', 'tangent', 'pivot'];
+// Where a refusal about the proposals sends the model: the file it wrote them in.
+const FIX_PROPOSALS = 'fix the Harvest proposals in .plumbbob/detail.md';
+/**
+ * Record the harvest the detail file proposes, and the range's review when the
+ * detail is a range's.
+ *
+ * Exit 1 on any refusal: no session, a detail file that is no range's or
+ * harvest's, the latch, a range no stop card showed or no longer landed, and a
+ * proposal it cannot settle. Each refusal names the move that unblocks it.
+ */
+export function harvest(cwd, _args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write(notice({ fact: 'no active session', remedy: 'plumbbob start "<title>"' }));
+        return 1;
+    }
+    const slug = activeBuild(root);
+    const detail = readOr(detailPath(root));
+    const item = parseDetailRange(detail);
+    if (item === null && !isHarvestDetail(detail)) {
+        process.stderr.write(nothingToRecord(detail));
+        return 1;
+    }
+    const intent = readOr(intentPath(root, slug));
+    const buildLog = readOr(buildLogPath(root, slug));
+    const parks = parkList(buildLog);
+    let stop = null;
+    if (item !== null) {
+        const found = stopRange(root, slug, intent, detail, item);
+        if (typeof found === 'string') {
+            process.stderr.write(found);
+            return 1;
+        }
+        stop = found;
+    }
+    const subject = stop === null ? 'harvest not recorded' : `range ${stop.item} of ${stop.count}'s stop not recorded`;
+    const settled = settle(parks, harvestProposals(detail));
+    if (typeof settled === 'string') {
+        process.stderr.write(notice({ fact: subject, detail: [settled], remedy: FIX_PROPOSALS }));
+        return 1;
+    }
+    if (stop === null && settled.length === 0) {
+        process.stderr.write(notice({ fact: 'harvest not recorded', detail: ['the detail file settles no open park'], remedy: FIX_PROPOSALS }));
+        return 1;
+    }
+    // The review is read before the flip, so its Harvested part shows each lean
+    // the human confirmed beside the park it settled.
+    const record = stop === null ? null : stopRecord(root, slug, detail, buildLog);
+    const date = new Date().toISOString().slice(0, 10);
+    const where = stop === null ? boundaryWords(root, slug) : `at range ${stop.item} of ${stop.count}'s stop`;
+    let updated = flipParks(buildLog, settled.map((p) => p.handle));
+    updated = updated === null ? null : appendHarvest(updated, harvestLines(date, where, settled));
+    if (stop !== null) {
+        updated = updated === null ? null : appendToSection(updated, 'Log', logEntry(stopLogLine(date, stop.item, stop.count, stop.stop), record));
+    }
+    if (updated === null) {
+        process.stderr.write(notice({ fact: `${subject}`, detail: ['build-log.md is missing a section it writes to'], remedy: 'restore its Park list, Harvest, and Log sections' }));
+        return 1;
+    }
+    writeFileSync(buildLogPath(root, slug), updated);
+    clearDetail(root);
+    clearStop(root, slug);
+    // Outside a stop the label names the act, `Recorded`, since `Harvested` is
+    // the stop card's part and one label over a part that proposes and an ending
+    // that records would mean two things (D106 (leans-harvested)).
+    const counted = classWords(settled);
+    const lead = stop === null
+        ? transition({ label: 'Recorded', fact: `${settled.length} parked idea${settled.length === 1 ? '' : 's'}`, detail: [counted] })
+        : transition({ label: 'Stop', fact: `Range ${stop.item} of ${stop.count} recorded`, detail: [counted] });
+    printEnding(root, {
+        tier: 'orientation',
+        render: 'harvest',
+        text: ending({ lead, pointer: boundaryEnding(root, slug, null).pointer }),
+    });
+    return 0;
+}
+/**
+ * The range a range's detail reviews, once the record may land: the plan
+ * holds the range, a stop card showed this detail, a human turn has read it,
+ * and every step of the range has landed. Otherwise the refusal, with the move
+ * that unblocks it.
+ *
+ * An undone step in the range reads two ways, told apart by the ledger. One
+ * with a `step N <sha>` line landed and was reopened, so it lands again and
+ * the card re-renders. One with none joined the range after the card, a
+ * blocker folded into the range that just landed, and `handoff --stop` would
+ * refuse too, since the last landing no longer completes the range; so the
+ * remedy moves the step to a range still to come and runs the record again,
+ * which holds in the same reply while the detail file stays as the card
+ * showed it.
+ */
+function stopRange(root, slug, intent, detail, item) {
+    const plan = parseBuildRanges(intent);
+    const count = plan.ranges.length + plan.malformed.length;
+    const range = plan.ranges.find((r) => r.item === item);
+    const refuse = (why, remedy) => notice({ fact: `range ${item} of ${count}'s stop not recorded`, detail: [why], remedy });
+    if (range === undefined) {
+        return refuse(`the plan has no range ${item}`, `write the range's number in the header of .plumbbob/detail.md`);
+    }
+    const stamp = readStop(root, slug);
+    if (stamp === null || stamp.range !== item || stamp.detail !== detailDigest(detail)) {
+        return refuse('no stop card showed its detail', 'plumbbob handoff --stop, then end the turn on the card');
+    }
+    if (!checkStopLatch(root, stamp.turn)) {
+        return refuse("its card printed this turn, and no human turn has read it", "end the turn on the card; the human's reply is what records it");
+    }
+    const held = parseOrderedSteps(intent).filter((s) => hasStep(range.steps, s.n));
+    if (held.length === 0) {
+        return refuse('the plan holds none of its steps', 'land it, then plumbbob handoff --stop');
+    }
+    const open = held.find((s) => !s.done);
+    if (open !== undefined) {
+        // A step the ledger landed was reopened since, and lands again; one it never
+        // landed was folded into the range after the card, and moves out instead.
+        return stepShas(readOr(checkpointsPath(root, slug))).has(open.n)
+            ? refuse(`step ${open.n} is open again`, 'land it, then plumbbob handoff --stop')
+            : refuse(`step ${open.n} joined it after it landed`, `move step ${open.n} to a range still to come, then plumbbob harvest`);
+    }
+    return { item, count, stop: range.stop };
+}
+/**
+ * The open parks the proposals settle, in list order, or the words for the
+ * first proposal that cannot be recorded: one naming a handle the list lacks,
+ * or a class outside the three, each named by the handle the card prints. A park no proposal names stays open; a proposal
+ * for a park already harvested settles nothing; and the first proposal for a
+ * park is the one the card showed.
+ */
+function settle(parks, proposals) {
+    for (const proposal of proposals) {
+        if (proposal.handle < 1 || proposal.handle > parks.length) {
+            return `P${proposal.handle} is not in the list; ${parks.length} parked`;
+        }
+        if (!CLASSES.includes(proposal.kind)) {
+            return `P${proposal.handle}'s class "${proposal.kind}" is not blocker, tangent, or pivot`;
+        }
+    }
+    return parks.flatMap((park) => {
+        const proposal = proposals.find((p) => p.handle === park.handle);
+        return park.open && proposal !== undefined ? [{ handle: park.handle, kind: proposal.kind, text: park.text, reason: proposal.reason }] : [];
+    });
+}
+/** The classes settled, counted in the ending's order: `1 blocker, 2 tangents`, or `nothing parked`. */
+function classWords(settled) {
+    const words = CLASSES.flatMap((kind) => {
+        const n = settled.filter((p) => p.kind === kind).length;
+        return n === 0 ? [] : [`${n} ${kind}${n === 1 ? '' : 's'}`];
+    });
+    return words.length === 0 ? 'nothing parked' : words.join(', ');
+}
+/** Where a harvest outside a stop ran, for its dated line: the boundary of the step that landed last. */
+function boundaryWords(root, slug) {
+    const last = parseLastCheckpoint(readOr(checkpointsPath(root, slug)));
+    return last === null ? 'before the first step landed' : `at the step ${last.n} boundary`;
+}
+/**
+ * Whether a detail file is a boundary harvest's wire, read off its
+ * `# Detail · Harvest` header.
+ */
+export function isHarvestDetail(detail) {
+    const first = detail.trimStart().split('\n', 1)[0] ?? '';
+    return /^#\s+Detail\s*·\s*Harvest\s*$/.test(first);
+}
+/**
+ * The refusal for a detail file that is no range's and no harvest's: a step's
+ * is checkpoint's to record, and an empty one, or one with no header, records nothing.
+ */
+function nothingToRecord(detail) {
+    const step = parseDetailStep(detail);
+    if (step !== null) {
+        return notice({
+            fact: 'nothing to record',
+            detail: [`the detail file is Step ${step}'s, not a range's or a harvest's`],
+            remedy: `plumbbob checkpoint ${step} records a step's detail`,
+        });
+    }
+    const why = detail.trim().length === 0 ? 'the detail file is empty' : 'the detail file names no range or harvest';
+    return notice({
+        fact: 'nothing to record',
+        detail: [why],
+        remedy: 'write the proposals in .plumbbob/detail.md under `# Detail · Harvest`',
+    });
+}
+/**
+ * Read a file as UTF-8, or '' when it is missing or unreadable.
+ */
+function readOr(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/verbs/relay.js

@@ -25,7 +25,9 @@
 // has already landed. The once is counted in `RELAY` by the turn it held,
 // never by `stop_hook_active`, which checkride's gate sets on every red Stop
 // and which names no hook. It never sends `continue: false`, which would cancel
-// a sibling's block in the same round.
+// a sibling's block in the same round. A run's boundary that still owes its
+// stop card is a miss however whole the boundary was, since the card is the
+// run's ending, and its reason names `plumbbob handoff --stop` as the retry.
 //
 // The final message comes from the payload's `last_assistant_message`, never
 // from the transcript, which does not yet hold that message when Stop fires;
@@ -71,7 +73,10 @@ export function relayCheck(cwd, raw) {
     const turn = readTurn(root);
     if (record === null || turn === null || record.turn !== turn || record.held === turn)
         return null;
-    const carried = carriedEnding(record, payload.last_assistant_message, payload);
+    // A run's boundary that still owes its stop card is held whatever the turn
+    // relayed: the card is the run's ending, and `handoff --stop` overwrites
+    // this record once it prints.
+    const carried = record.owes !== undefined ? false : carriedEnding(record, payload.last_assistant_message, payload);
     // Whole, or not this check's to judge: let the turn end.
     if (carried !== false)
         return null;
@@ -206,6 +211,11 @@ function partsOf(text) {
  * turn missed, and the command or block that puts it back.
  */
 function reason(record) {
+    if (record.owes !== undefined) {
+        const { range, count, step } = record.owes;
+        return (`plumbbob: the turn ended on Step ${step}'s boundary, and range ${range} of ${count}'s stop card is still owed. ` +
+            "Write the range's detail file, run `plumbbob handoff --stop`, and end the turn on its output, whole, with nothing after it.");
+    }
     if (record.tier === 'decision') {
         const command = record.command ?? 'plumbbob handoff --full';
         return (`plumbbob: the turn did not close on the ${DECISION_NAMES[record.render] ?? 'pause'} it printed. ` +
@@ -219,6 +229,8 @@ function reason(record) {
 const DECISION_NAMES = {
     card: 'pause card',
     reminder: 'pause reminder',
+    stop: 'stop card',
+    'stop-reminder': 'stop reminder',
     plan: 'plan card',
 };
 // The command that printed an orientation ending, by its render, so the reason
@@ -226,6 +238,7 @@ const DECISION_NAMES = {
 const ORIENTATION_VERBS = {
     checkpoint: 'plumbbob checkpoint',
     'plan-commit': 'plumbbob checkpoint --plan',
+    harvest: 'plumbbob harvest',
     finish: 'plumbbob finish',
 };
 /**

package/dist/verbs/status.js

@@ -3,13 +3,19 @@
 // the in-flight STEP marker) into a where-am-I view that suggests one primary
 // next move while printing the full picture, so you can always override.
 // Read-only, always exits 0. Skills pre-inject this output to gate their own
-// behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
+// behavior, so the `NO ACTIVE SESSION` sentinel is kept exact. A stop card
+// still waiting for its reply marks its range and takes the next move. With
+// `--run`, it prints the run a `/plumbbob:run` invocation names above the
+// dashboard, and names the waiting card again beneath the run's grant.
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { PLAN_COMMIT_MARKER, commitsSince, findRepoRoot } from "../lib/git.js";
 import { SLOTS, readHarnessFile, resolveAgent, } from "../lib/agents.js";
 import { buildFolder, buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
-import { formatOrientation, lastLedgerSha, orient, parseRequestedStep } from "../lib/orient.js";
+import { readGrant } from "../lib/latch.js";
+import { formatOrientation, formatRunDashboard, lastLedgerSha, orient, parseRequestedStep, resolveRunArgs, } from "../lib/orient.js";
+import { normalizeStepList } from "../lib/steplist.js";
+import { waitingCard } from "./handoff.js";
 /**
  * Read a file as utf8, or '' when it is missing or unreadable.
  */
@@ -22,20 +28,32 @@ function readOr(path) {
     }
 }
 /**
- * Split `--invoked "<raw args>"` out of the argument list, ahead of any other
- * flag parsing.
+ * Split a flag carrying a skill invocation's raw text (`--invoked` or `--run`)
+ * out of the argument list, ahead of any other flag parsing.
  *
  * The value is the verbatim text of a skill invocation (the `$ARGUMENTS` the
- * `/plumbbob:build` skill passes through), so it can contain anything,
- * including tokens that look like this CLI's own flags; extracting it first
- * keeps such a value from confusing `resolveBuild`. A missing flag, or one
- * with no value, reads as null: no explicit ask.
+ * skill passes through), so it can contain anything, including tokens that
+ * look like this CLI's own flags; extracting it first keeps such a value from
+ * confusing `resolveBuild`. An absent flag reads as null; a flag with no value
+ * reads as `missing`, which `--invoked` takes as no explicit ask and `--run`
+ * as a run with nothing after the verb.
  */
-function takeInvoked(args) {
-    const i = args.indexOf('--invoked');
+function takeRaw(args, flag, missing) {
+    const i = args.indexOf(flag);
     if (i === -1)
-        return { invoked: null, rest: args };
-    return { invoked: args[i + 1] ?? null, rest: [...args.slice(0, i), ...args.slice(i + 2)] };
+        return { raw: null, rest: args };
+    return { raw: args[i + 1] ?? missing, rest: [...args.slice(0, i), ...args.slice(i + 2)] };
+}
+/**
+ * A grant as the GRANT file holds it in its normal form, or null for none:
+ * the text the run header holds against the grant a run would mint.
+ */
+function grantText(grant) {
+    if (grant === null)
+        return null;
+    if (grant.kind === 'auto')
+        return 'auto';
+    return grant.kind === 'steps' ? `steps ${normalizeStepList(grant.steps)}` : `range ${grant.ceiling}`;
 }
 /**
  * Print the orientation dashboard for the active build, plus its harness bindings.
@@ -46,6 +64,10 @@ function takeInvoked(args) {
  * `/plumbbob:build` skill passes its own invocation through), an explicit step
  * number in the raw text repoints the dashboard's marker, detail, and next
  * move at that step, so the injected state never contradicts the human's ask.
+ * With `--run "<raw args>"` (how the `/plumbbob:run` skill passes its own),
+ * the dashboard prints beneath a header naming the run the text resolves to
+ * and the grant the turn hook minted, or carries the refusal in its pointer
+ * when the run names nothing it can walk.
  */
 export function status(cwd, args = []) {
     const root = findRepoRoot(cwd);
@@ -53,7 +75,8 @@ export function status(cwd, args = []) {
         process.stdout.write('NO ACTIVE SESSION\n');
         return 0;
     }
-    const { invoked, rest } = takeInvoked(args);
+    const { raw: run, rest: afterRun } = takeRaw(args, '--run', '');
+    const { raw: invoked, rest } = takeRaw(afterRun, '--invoked', null);
     // A session with builds but no resolvable cursor (finish cleared it, or the repo
     // holds several builds and none is active) has no single dashboard to show, so
     // list the builds and point at `use` instead of rendering a broken, empty one.
@@ -73,19 +96,43 @@ export function status(cwd, args = []) {
     // checkpoint still surfaces. No ledger yet ⇒ nothing to reconcile against ⇒ 0.
     const checkpoints = readOr(checkpointsPath(root, slug));
     const anchor = lastLedgerSha(checkpoints);
-    const orientation = orient({
-        intent: readOr(intentPath(root, slug)),
+    const intent = readOr(intentPath(root, slug));
+    // The stop card still waiting, read once: the dashboard marks its range and
+    // names it as the move, and the run header's waiting line names it too.
+    const card = waitingCard(root, slug, intent);
+    const input = {
+        intent,
         buildLog: readOr(buildLogPath(root, slug)),
         checkpoints,
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
         spiking: inSpike(root, slug),
         requested: parseRequestedStep(invoked),
         outOfBand: anchor === null ? 0 : commitsSince(root, anchor, PLAN_COMMIT_MARKER),
-    });
-    const lines = [formatOrientation(orientation), ...harnessSection(root, slug)];
+        waiting: card?.range ?? null,
+    };
+    const dashboard = run === null
+        ? formatOrientation(orient(input))
+        : withWaiting(formatRunDashboard(input, resolveRunArgs(run, input), grantText(readGrant(root))), card);
+    const lines = [dashboard, ...harnessSection(root, slug)];
     process.stdout.write(`${lines.join('\n')}\n`);
     return 0;
 }
+/**
+ * The run dashboard with the waiting line beneath the run header's grant line,
+ * the header's fourth line, naming the stop card still waiting for its reply
+ * (`range 3 of 5's stop card, recorded before the run`). With no card waiting,
+ * or no header (a run that refuses has no grant line to ride), the dashboard
+ * is returned as it is.
+ */
+function withWaiting(dashboard, card) {
+    const lines = dashboard.split('\n');
+    const grant = lines.findIndex((l) => l.startsWith('     grant: '));
+    if (card === null || grant === -1) {
+        return dashboard;
+    }
+    lines.splice(grant + 1, 0, `     waiting: range ${card.range} of ${card.count}'s stop card, recorded before the run`);
+    return lines.join('\n');
+}
 /**
  * The active build's harness bindings: the agents bound to each slot, per
  * `defaults` and per step.

package/dist/verbs/turn.js

@@ -1,25 +1,29 @@
 // `plumbbob turn`: the turn-ledger hook. Wired to the harness's
-// UserPromptSubmit event, it runs once per prompt and maintains two of the
-// sidecar's git-excluded control files (flat files under `.plumbbob/`): it ticks
-// `TURN`, the monotonic count of human turns the checkpoint latch compares
-// against a step's entry stamp to know a human turn intervened since the step
-// began, and it rewrites `GRANT` from the literal prompt, minting a one-turn
-// self-approval only when the human typed `/build --auto` or a step range
-// (`N-M`, or a list such as `20,5-9`), clearing it otherwise (those strings can only come from a human
-// keystroke, because `build` is disable-model-invocation: a grant the model
-// could forge would be no grant). The harness also sends a background job's
+// 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 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.
+// 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 { clearRelay, findSessionRoot, notePrompt, readPrompt, setGrant, stepPath, turnPath, } from "../lib/sidecar.js";
-import { normalizeStepList, readBuildArgs } from "../lib/steplist.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 prompt, then emit the in-flight-step nudge
  * when it counted as a human turn.
@@ -87,10 +91,10 @@ function inFlightStep(root) {
  * The testable core: apply one prompt given the raw hook stdin, and say
  * whether it counted as a human turn.
  *
- * A typed prompt ticks TURN and rewrites GRANT. A notice touches neither,
- * because the latch reads TURN passing a step's entry stamp as its one sign
- * that a human answered, and a grant the human typed has to outlive a job
- * that reports back partway through the range. A notice that starts a turn of
+ * 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
@@ -112,7 +116,9 @@ export function applyTurn(cwd, raw) {
     }
     else {
         writeFileSync(turnPath(root), `${readTurn(root) + 1}\n`);
-        setGrant(root, grantFromPrompt(prompt));
+        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);
@@ -133,6 +139,12 @@ export function applyTurn(cwd, raw) {
 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.
  *
@@ -160,15 +172,84 @@ export function isNotice(prompt) {
  * 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] ?? '';
-    const args = readBuildArgs(line);
+    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 };
+    }
+}
+/**
+ * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "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

@@ -44,7 +44,9 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    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
@@ -332,6 +334,13 @@ comma), and it grants exactly the steps it names: the checkpoint refuses any oth
 ([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
@@ -364,13 +373,16 @@ out, or the next step in build order is one the range does not name),
   the whole stretch lists step 4 too (`/plumbbob:build 1-4`, or `/plumbbob:build 1,4,2,3`).
 - **At a range's stop, harvest before the next range.** No harvest runs between the steps
   inside a range, so the parks pile up, and a blocker among them would otherwise ride into
-  the next one. When the human asks what comes next at a stop with parks open (the note's
-  `parked 2 of 7 open`), the move is `/plumbbob:harvest`, then the range the card names.
+  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 what is left of the
-  range (`· range 3 of 5: /plumbbob:build 8-9`), and that is the command the human types
-  to carry on.
+  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