plumbbob 0.13.6 → 0.13.8

package/dist/verbs/park.js

@@ -7,12 +7,14 @@
 // step it interrupted, so the relay is one command.
 // Capture is not a state transition, so it runs in any context (terminal or
 // in-session).
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { activeBuild, hasSession, buildLogPath } from "../lib/sidecar.js";
+import { activeBuild, hasSession, buildLogPath, intentPath } from "../lib/sidecar.js";
 import { appendToSection } from "../lib/buildlog.js";
 import { ending, notice, printEnding, transition } from "../lib/notice.js";
+import { parseOpenQuestionRows } from "../lib/orient.js";
 import { driverPointer } from "./handoff.js";
+import { setAsideAdvisories } from "./defer.js";
 /**
  * Append the given text as one unchecked `- [ ]` line to the build-log's Park list.
  *
@@ -41,12 +43,20 @@ export function park(cwd, args) {
         return 1;
     }
     writeFileSync(path, updated);
+    const intent = intentPath(root);
+    const questions = parseOpenQuestionRows(existsSync(intent) ? readFileSync(intent, 'utf8') : '');
     // A park interrupts a step without ending it, so the ending is the capture
-    // and the pointer back at what was interrupted.
+    // and the pointer back at what was interrupted. A park naming a question
+    // that still waits on the human says so, since the park list never moves
+    // the card's count (D123 (defer-records)).
     printEnding(root, {
         tier: 'driver',
         render: 'park',
-        text: ending({ lead: transition({ label: 'Parked', fact: text }), pointer: driverPointer(root, activeBuild(root)) }),
+        text: ending({
+            lead: transition({ label: 'Parked', fact: text }),
+            advisories: setAsideAdvisories(text, questions),
+            pointer: driverPointer(root, activeBuild(root)),
+        }),
     });
     return 0;
 }

package/dist/verbs/recover.js

@@ -19,7 +19,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { parseBuildOrder, parseBuildRanges, parseOrderedSteps, parseSteps, rangeStanding } from "../lib/orient.js";
-import { activeBuild, checkpointsPath, clearHandoff, clearTick, grantPath, handoffPath, hasSession, intentPath, inSpike, listBuilds, readTurn, setActiveBuild, setGrant, stepPath, tickPath, } from "../lib/sidecar.js";
+import { activeBuild, clearHandoff, clearTick, grantPath, handoffPath, hasSession, intentPath, inSpike, listBuilds, planCommitted, readTurn, setActiveBuild, setGrant, stepPath, tickPath, } from "../lib/sidecar.js";
 import { spikeBranches, spikeWorktrees } from "./spike.js";
 /**
  * Report every inconsistency in the control plane, and with `--fix` repair the
@@ -255,7 +255,7 @@ function leftoverFindings(root, slug, stepInFlight) {
     // pause, and cleared by the checkpoint that lands either one. At the boundary
     // with the plan already committed, neither pause is open, so a TICK left here
     // is measuring a span that closed.
-    const planLanded = readOr(checkpointsPath(root, slug)).split('\n').some((l) => l.startsWith('plan '));
+    const planLanded = planCommitted(root, slug);
     if (!stepInFlight && planLanded && existsSync(tickPath(root, slug))) {
         findings.push({
             name: 'latch tick',

package/dist/verbs/relay.js

@@ -29,6 +29,14 @@
 // 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.
 //
+// A reminder can close the turn and still leave the human without the reply.
+// When the reply was written before a tool call and the final message is the
+// reminder alone, a client that folds text written ahead of a tool call shows
+// the line and nothing else (GitHub issue #12). That shape is held once too,
+// by a reason that asks for the reply again and ends on the line to type. It
+// names no command, since a retry that ran one would bury the reply the same
+// way (D121 (reply-after-the-tools)).
+//
 // 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;
 // the transcript supplies only the turn's earlier messages, which an
@@ -79,13 +87,53 @@ export function relayCheck(cwd, raw) {
     // 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);
+    if (carried === false)
+        return hold(root, record, reason(record));
+    // The reminder closed the turn, but the reply stood above a tool call.
+    if (carried === true && buriedReply(record, payload.last_assistant_message, payload))
+        return hold(root, record, buriedReason(record));
     // Whole, or not this check's to judge: let the turn end.
-    if (carried !== false)
-        return null;
+    return null;
+}
+/**
+ * Stamp the once in `RELAY` and emit the hold with its reason, or nothing when
+ * the stamp cannot land.
+ */
+function hold(root, record, text) {
     // A hold that cannot be counted could repeat, so it is no hold at all.
     if (!holdRelay(root, record))
         return null;
-    return `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext: reason(record) } })}\n`;
+    return `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext: text } })}\n`;
+}
+// The renders a reply at a card already shown closes on: the one line that
+// points back at the pause or the stop.
+const REMINDERS = new Set(['reminder', 'stop-reminder']);
+/**
+ * Whether a reminder that closed the turn left the reply above a tool call:
+ * the final message is the reminder alone, with no words above its label,
+ * while the turn's earlier messages carried words. The printed line itself is
+ * not counted as words, since the transcript can already hold the final
+ * message when Stop fires. A transcript the check cannot read or scope is no
+ * evidence, and neither is a turn whose earlier messages said nothing.
+ */
+function buriedReply(record, last, payload) {
+    if (!REMINDERS.has(record.render) || leadOf(last).trim().length > 0)
+        return false;
+    const earlier = turnText(payload);
+    if (earlier === null)
+        return false;
+    return earlier.split(record.text.trim()).join('').trim().length > 0;
+}
+/**
+ * The one-line reason for a reply buried above a tool call: what happened, and
+ * the line to end on, with no command to run, since a retry that ran one would
+ * leave the reply above a tool call again.
+ */
+function buriedReason(record) {
+    return (`plumbbob: the turn ended on the ${DECISION_NAMES[record.render] ?? 'pause reminder'} it printed, ` +
+        'but the reply stood above a tool call, where a client can fold it out of sight. ' +
+        'Write the reply again, in your own words, with no tool call after it, ' +
+        `and end the turn on the same line, typed as it printed: ${record.text.trim()}`);
 }
 /**
  * Whether the turn carried the recorded ending: true when it did, false when
@@ -197,7 +245,27 @@ function blockCount(part) {
  * runs to the next. Text before the first label is not part of any.
  */
 function partsOf(text) {
+    return readEnding(text).parts;
+}
+/** The text above an ending's first labeled part: the words a reply wrote above the line it closes on. */
+function leadOf(text) {
+    return readEnding(text).lead.join('\n');
+}
+/**
+ * One walk over a stretch of text: the lines before its first labeled part,
+ * and the parts themselves, each run to the next, with a fence read as one
+ * stretch so a label inside it opens nothing.
+ */
+function readEnding(text) {
+    const lead = [];
     const parts = [];
+    const keep = (line) => {
+        const last = parts.at(-1);
+        if (last === undefined)
+            lead.push(line);
+        else
+            last.lines.push(line);
+    };
     let rail = null;
     for (const line of text.split('\n')) {
         const fence = /^\s*(`{3,})/.exec(line)?.[1];
@@ -206,7 +274,7 @@ function partsOf(text) {
         }
         else if (rail !== null && fence !== undefined && fence.length >= rail.length && line.trim() === fence) {
             rail = null;
-            parts.at(-1)?.lines.push(line);
+            keep(line);
             continue;
         }
         const label = rail === null ? labelOf(line) : undefined;
@@ -214,10 +282,10 @@ function partsOf(text) {
             parts.push({ label, lines: [line] });
         }
         else {
-            parts.at(-1)?.lines.push(line);
+            keep(line);
         }
     }
-    return parts;
+    return { lead, parts };
 }
 /**
  * The label a line opens a part on, or undefined when it opens none: a bold

package/dist/verbs/start.js

@@ -7,8 +7,8 @@ import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { detectGate } from "../lib/check.js";
 import { readTemplate, stampTemplate } from "../lib/templates.js";
-import { findRepoRoot, hasCommit, headSha, isDirty, isIgnored } from "../lib/git.js";
-import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
+import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
+import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, buildFolderIgnored, planCommitted, setGrant, stampTick, } from "../lib/sidecar.js";
 import { settingsPath } from "../lib/settings.js";
 import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
 /**
@@ -41,6 +41,12 @@ export async function start(cwd, args) {
     // Every advisory the session accrues on its way open, collected rather than
     // printed: they belong inside the one ending below, in the order found.
     const advisories = [];
+    // `--local` on a session already open is the plan card's way out: keep this
+    // build untracked before its plan commit lands. It needs no title.
+    const open = local ? findRepoRoot(cwd) : null;
+    if (open !== null && hasSession(open)) {
+        return keepLocal(open);
+    }
     if (title.length === 0) {
         process.stderr.write(notice({ fact: 'start needs a title', remedy: 'plumbbob start "what you are building"' }));
         return 1;
@@ -154,7 +160,7 @@ export async function start(cwd, args) {
     // excludes the whole sidecar by design and says so, so skip the probe there.
     // Guidance only, and the session is already open: a probe hiccup stays silent
     // rather than half-crashing a scaffolded session.
-    if (!local && sidecarIsIgnored(root, slug)) {
+    if (!local && buildFolderIgnored(root, slug)) {
         advisories.push(advisory({
             fact: 'this repo gitignores .plumbbob/',
             detail: ['the build folder cannot ride the branch', 'plan and finish commits will be record-only'],
@@ -210,20 +216,40 @@ function datedSlug(title) {
     return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${base}`;
 }
 /**
- * Whether the tracked build folder is gitignored: the record-only advisory's
- * predicate, probing exactly the path `checkpoint --plan` will try to stage.
+ * Keep an open session untracked: `plumbbob start --local` typed while a build
+ * is open and its plan not yet committed, the way out the plan card offers
+ * (D117 (publish-on-the-card)).
  *
- * Best-effort: a probe that throws (a fatal `git check-ignore`) reads as
- * not-ignored so the advisory stays silent rather than crashing a session that
- * is already open.
+ * It writes the blanket `.plumbbob/` line to this clone's info/exclude, the
+ * line a `--local` start writes, so the plan and finish commits land
+ * record-only and nothing under `.plumbbob/` rides the branch. The folder
+ * keeps its place and its slug; only git's view of it changes. Refuses once the
+ * plan has landed, since the folder is in a commit by then and an exclude
+ * cannot take it back.
  */
-function sidecarIsIgnored(root, slug) {
-    try {
-        return isIgnored(root, buildDir(root, slug));
-    }
-    catch {
-        return false;
+function keepLocal(root) {
+    if (planCommitted(root)) {
+        process.stderr.write(notice({
+            fact: 'this session can no longer be kept local',
+            detail: ['its plan is already committed with the build folder'],
+            remedy: 'plumbbob finish to close it before starting another',
+        }));
+        return 1;
     }
+    excludeSidecar(root);
+    printEnding(root, {
+        tier: 'driver',
+        render: 'start',
+        text: ending({
+            lead: transition({
+                label: 'Session',
+                fact: 'kept local',
+                detail: ['.plumbbob/ excluded in this clone', 'the plan and finish commits land record-only'],
+                remedy: 'plumbbob handoff --plan to show the plan card again',
+            }),
+        }),
+    });
+    return 0;
 }
 /**
  * Read the value that follows a `--flag` in argv (for example `--slug my-build`), or

package/dist/verbs/status.js

@@ -8,14 +8,15 @@
 // `--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 { join, relative } 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 { readGrant } from "../lib/latch.js";
-import { formatOrientation, formatRunDashboard, lastLedgerSha, orient, parseRequestedStep, resolveRunArgs, } from "../lib/orient.js";
+import { formatOrientation, formatRunDashboard, lastLedgerSha, orient, parseOpenQuestionRows, parseRequestedStep, resolveRunArgs, } from "../lib/orient.js";
 import { normalizeStepList } from "../lib/steplist.js";
-import { waitingCard } from "./handoff.js";
+import { blocks, notice } from "../lib/notice.js";
+import { questionsPart, waitingCard } from "./handoff.js";
 /**
  * Read a file as utf8, or '' when it is missing or unreadable.
  */
@@ -67,7 +68,10 @@ function grantText(grant) {
  * 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.
+ * when the run names nothing it can walk. With `--questions` it prints the
+ * plan's open questions as the plan card tables them, and nothing else: the
+ * ones that wait on the human in the table, and the ones deferred to the work
+ * on a line beneath it.
  */
 export function status(cwd, args = []) {
     const root = findRepoRoot(cwd);
@@ -88,6 +92,14 @@ export function status(cwd, args = []) {
             return 0;
         }
     }
+    if (rest.includes('--questions')) {
+        // The open questions alone, as the plan card tables them: the view a skill
+        // relays when the human asks what is still open (D118 (questions-table)),
+        // with the deferred ones on their own line (D120 (deferred-questions)).
+        const part = questionsPart(parseOpenQuestionRows(readOr(intentPath(root, slug))), relative(root, intentPath(root, slug)));
+        process.stdout.write(part === null ? notice({ fact: 'no open questions in this plan' }) : blocks([part]));
+        return 0;
+    }
     const inFlightRaw = readOr(stepPath(root, slug)).trim();
     // Out-of-band commits (ones that landed outside the checkpoints ledger) are
     // surfaced here, never blocked. Counting them needs git (orient is pure), so

package/dist/verbs/turn.js

@@ -19,7 +19,10 @@
 // is in context) still knows it: mid-step, a tangent is parked, not chased;
 // at a pause or a stop whose card has shown, the message is the human's reply,
 // answered in the model's own words and closed on the one line `handoff`
-// prints, never on the card again (D110 (reply-after-the-card)). Guidance
+// prints, never on the card again (D110 (reply-after-the-card)). Every tool
+// call comes before that answer and none after it, since a client that folds
+// text written ahead of a tool call would show the line and hide the answer
+// (D121 (reply-after-the-tools)). 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';
@@ -60,8 +63,9 @@ export function turn(cwd, _args) {
  * Three beats, read off the control files. A step whose pause card has shown
  * (STEP, and PAUSE naming that step's pause) is waiting for the human's call,
  * so the message is the reply to it: answered or acted on in the model's own
- * words, and closed on the one line `handoff` prints rather than the card
- * again (D110 (reply-after-the-card)). A step in flight with no card yet is
+ * words after every tool call, and closed on the one line `handoff` prints
+ * rather than the card again (D110 (reply-after-the-card),
+ * D121 (reply-after-the-tools)). A step in flight with no card yet is
  * mid-build, where a tangent is a park and not an edit. A stop card waiting
  * for its reply is the pause's beat at a stop. At a pause or a stop, a
  * `prompt` asking to see the card (`show the pause`, the phrase the card's
@@ -127,18 +131,23 @@ function parkNudge(step) {
     return (`plumbbob: step ${step} is in flight — a new idea or tangent is a park, not an edit: ` +
         `capture it with \`plumbbob park "<one line>"\` and relay the block it prints whole, ` +
         `with nothing written around it, since that block is the whole turn. ` +
-        `The one exception is a message that also asks something: answer the question first, ` +
-        `then relay the park's block after the answer and write nothing after it. ` +
+        `The one exception is a message that also asks something: run \`plumbbob park\` first, then answer the question, ` +
+        `then end the turn on the park's block, typed as it printed, with no tool call after the answer. ` +
         `The block's pointer back at the step closes the turn either way, so run no \`plumbbob handoff\` after it. ` +
         `The step stays open and lands when you run \`plumbbob checkpoint ${step}\` after approval.`);
 }
-/** The nudge at a pause whose card has shown: the message is the reply, and the card is not printed again. */
+/**
+ * The nudge at a pause whose card has shown: the message is the reply, every
+ * tool call comes before it, and the card is not printed again.
+ */
 function pauseNudge(step) {
     return (`plumbbob: step ${step}'s card has shown, and this message is the human's reply to it. ` +
         `An approval lands the step: run \`plumbbob checkpoint ${step}\` and relay its ending. ` +
-        `Anything else is answered in your own words: answer the question, or make the change it asks for, ` +
-        `and when a change moves what the card said, write \`.plumbbob/detail.md\` again so the record matches what lands. ` +
-        `Print no card for it: run \`plumbbob handoff\` and end the turn on the one line it prints, with nothing after it. ` +
+        `Anything else is answered in your own words, after every tool call and with none after it: ` +
+        `first read what you need and make the change it asks for, ` +
+        `write \`.plumbbob/detail.md\` again when a change moves what the card said, so the record matches what lands, ` +
+        `and run \`plumbbob handoff\` last among them, keeping the one line it prints. ` +
+        REPLY_LAST +
         `Only when the human asks to see the card again, run \`plumbbob handoff --full\` and paste its output exactly as it printed, as the whole turn. ` +
         `A tangent the human hands you is still a park: \`plumbbob park "<one line>"\`.`);
 }
@@ -146,11 +155,19 @@ function pauseNudge(step) {
 function stopNudge(range, count) {
     return (`plumbbob: range ${range} of ${count}'s stop card has shown, and this message is the human's reply to it. ` +
         `An approval records the stop: fold each confirmed blocker into the plan, then run \`plumbbob harvest\` and relay its ending. ` +
-        `Anything else is answered in your own words: answer the question, or make the change it asks for ` +
-        `(a lean is its line under the detail file's \`## Harvest\`). ` +
-        `Print no card for it: run \`plumbbob handoff --stop\` and end the turn on the one line it prints, with nothing after it. ` +
+        `Anything else is answered in your own words, after every tool call and with none after it: ` +
+        `first read what you need and make the change it asks for (a lean is its line under the detail file's \`## Harvest\`), ` +
+        `and run \`plumbbob handoff --stop\` last among them, keeping the one line it prints. ` +
+        REPLY_LAST +
         `Only when the human asks to see the card again, run \`plumbbob handoff --stop --full\` and paste its output exactly as it printed, as the whole turn.`);
 }
+// How a reply at a card already shown ends, the same at a pause and a stop: the
+// answer after the last tool call, then the line, because a client that folds
+// text written before a tool call shows the line and hides the answer
+// (D121 (reply-after-the-tools)).
+const REPLY_LAST = `Then write your answer and end the turn on that line, typed as it printed, with no tool call after your answer: ` +
+    `a client that folds text written before a tool call would hide the answer and show the line alone. ` +
+    `Print no card for it. `;
 /**
  * The in-flight step number, or null when no STEP marker is present.
  *

package/package.json

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

@@ -3,7 +3,7 @@ name: build
 description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3`, or a list like `20,5-9`, self-approves exactly the steps it names, in build order, then stops."
 argument-hint: "[step-number | step-range | step-list] [--auto]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob defer:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
 ---
 
 # PlumbBob: build a step (the default engine)
@@ -66,7 +66,13 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    capture it by running `plumbbob park "<one tidy line>"`: **saying "let's defer
    that" writes nothing; only the park line in the build log is a capture.** When the
    *human* hands you the tangent mid-build, their message **is** the approval to park
-   it; capture it right away, say what you parked, and stay on the step. If you
+   it; capture it right away, say what you parked, and stay on the step. An open question
+   the human sets aside to wait on other work is deferred, not parked: run
+   `plumbbob defer Q3 "<what settles it>"`, because the card counts questions by the
+   marker on each opener and never by the park list
+   ([D123 (defer-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d123)).
+   When `plumbbob park` warns that a question it names still counts as one to answer,
+   defer it if the human said the work will settle it, and leave it to them otherwise. If you
    genuinely cannot finish without touching more than the seam, that is scope drift:
    surface it to the human rather than sprawling.
    - **Bound agents can shape the build.** If `plumbbob status` shows a
@@ -186,7 +192,9 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    of its own, one command to a line, which handoff keeps line for line. A slash command
    or a path stays in backticks in the sentence. `checkpoint` records this file beneath the step's dated
    line in the build-log's `## Log` and then truncates it, so the detail lands in the
-   tracked ledger rather than piling up on disk.
+   tracked ledger rather than piling up on disk. Write a relative link from `.plumbbob/`, where
+   the file lives (`builds/<slug>/intent.md#d5`); the record re-aims it at the build folder.
+   A decision cited by its slug in plain text (`D5 (no-link-no-reconnect)`) needs no link at all.
 
    **A bare range's pause is its stop.** When the injected dashboard's ranges block lists
    this step as a bare range (`/plumbbob:build 5`, its row marked `▸`), the plan reserved a
@@ -200,8 +208,8 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    Readout fence (its measured `check`, `seam`, `diff`, and `spent` rows folded with your
    three, the changed files listed beneath `diff`), a `diff` fence when the change is 20
    lines or fewer, Your Call, the state table (the Verdict folded worst-of from the same
-   rows, the Now row naming the step in flight, Next Up, and the Range, Order, and Parked
-   rows when they apply), your recommendation, and the `more details` link last. Run it
+   rows, the Now row naming the step in flight, Next Up with the next range on its second
+   line, and the Order and Parked rows when they apply), your recommendation, and the `more details` link last. Run it
    once: a second run at the same pause prints the one-line reminder instead of the card,
    so if that line comes back where the card belongs (you ran handoff earlier in this
    turn), run `plumbbob handoff --full` and paste that. The gate verdict's one home is that `check`
@@ -213,7 +221,7 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    one, the write-versus-relay line of
    [D78 (em-dash-ban)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d78).
 
-   *Then answer the reply in your own words.* The card shows once
+   *Then answer the reply in your own words, after every tool call.* The card shows once
    ([D110 (reply-after-the-card)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d110)):
    every later turn at this pause is your reply, closed by one line. A message that
    **asks** ("expand 2", "what does that mean?", "why did the seam row flag that?") is an
@@ -222,11 +230,16 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    make the change, run the check, and say what moved and what the check found; when the
    change moves what the card said (a judgment row, the Summary, the recommendation), write
    the detail file again so the record matches what lands. Nothing lands until the human
-   says `looks good`. Either way, then run `plumbbob handoff` and paste its output beneath
-   your reply, whole and verbatim: at a pause whose card has shown it prints one line,
-   `**Next Up**: Back to Step <N> of <M> - <title>`, whatever changed since, so your reply
-   stays on screen. The turn is your reply, then that line, and nothing after it. The CLI
-   picks the form, never you: paste whichever one it prints, and never retype the card.
+   says `looks good`. Either way, every tool call comes before your reply and none after
+   it ([D121 (reply-after-the-tools)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d121)):
+   read, edit, run the check, write the detail file, and run `plumbbob handoff` last among
+   them. At a pause whose card has shown it prints one line,
+   `**Next Up**: Back to **Step N** on <Model> - <title>`, whatever changed since. Keep
+   that line, then write your reply, and end the turn on the line, whole and verbatim. The
+   turn is your tool calls, then your reply, then that line, and nothing after it: a
+   client that folds text written before a tool call (Zed, through the agent bridge) shows
+   the line and hides a reply written above the call. The CLI picks the form, never you:
+   paste whichever one it prints, and never retype the card.
 
    The card comes back one way: the human asks to see it (`show the pause`, or any wording
    of it). Then run `plumbbob handoff --full` and paste its output whole, with nothing
@@ -238,12 +251,13 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    **Then hand off with the next model.** `plumbbob checkpoint` prints the whole boundary
    ending itself: `**Checkpoint**: Step N complete (<sha>)`, any advisory (a staged path
    outside the seam is the common one), and the state table: the Verdict the step earned,
-   the Stop row when this landing completes a range (`| Stop | Range 3 of 5 landed - <its
+   the Stop row when this landing completes a range (`| Stop | **Range 3** landed - <its
    stop> |`, the reason the build stops here), Next Up, and the rows beneath it. Relay that
    block whole, the table with the rest (the relay check holds a boundary that dropped a
    row), run no second command, and write nothing around it. A later turn at this boundary
-   is your reply; a `plumbbob handoff` there prints Next Up's one line, since the boundary
-   has shown. It is the
+   is your reply, in the same order as at a pause: a `plumbbob handoff` there prints Next
+   Up's one line, since the boundary has shown, so run it last among your tool calls, then
+   write your reply and end on that line, with no tool call after it. It is the
    orientation tier (no Your Call block, no recommendation), and its Next Up points at the
    next undone step carrying that step's `- model:` recommendation (the plan's
    smallest-model-that-fits call) so the human knows which `/model` to select before
@@ -371,9 +385,13 @@ out, or the next step in build order is one the range does not name),
 - **A step inside the range won't build** (its seam won't parse): `plumbbob build <n>` fails
   exactly as it always does; surface it and stop, the same as a red check. Do not skip past
   the gap.
-- **The range starts above the next undone step**: you are jumping over earlier planned work;
-  note that you are skipping the steps before it, then proceed (the same latitude as a
-  single-number jump like `/plumbbob:build 4`).
+- **The range starts above the next undone step** (the order reads `6, 4, 5` under
+  `/plumbbob:build 4-5`): the first step enters as a single-number jump like `/plumbbob:build 4`
+  would, with the skipped step noted. Once it lands, the next undone step in build order is
+  the one you jumped, which the range does not name, so the halt above fires there, and
+  `plumbbob build` names step 4 as the last undone step in the range, its detail naming step 6
+  as the step the walk halts before. The range that walks the whole stretch names the jumped
+  step too (`/plumbbob:build 6,4-5`).
 - **The build order puts a step the range does not name inside it** (the order reads
   `1, 4, 2, 3` under `/plumbbob:build 1-3`): the halt above fires before step 4, and
   `plumbbob build` names step 1 as the last undone step in the range. The range that walks
@@ -387,8 +405,8 @@ out, or the next step in build order is one the range does not name),
   `Parked` row, `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 state table's Range row names the run that lands
-  what is left of the range (`| Range | 3 of 5: /plumbbob:run (steps 8-9) |`), and that is
+  human approves and the step lands, the range line beneath Next Up names the run that lands
+  what is left of the range (`|  | **Range 3** on Opus: /plumbbob:run (steps 8-9) |`), and that is
   what the human types to carry on; `/plumbbob:build 8-9` lands the same steps by hand.
 
 ## The hard contracts

package/skills/harvest/SKILL.md

@@ -2,7 +2,7 @@
 name: harvest
 description: "Triage the park list at a step boundary: propose one class (blocker/tangent/pivot) for every open parked item at once, and once the human settles them in one reply, fold a confirmed blocker into intent and record the rest with plumbbob harvest. A run's stop card carries its own harvest."
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob order:*), Bash(plumbbob handoff:*), Bash(plumbbob harvest:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob order:*), Bash(plumbbob defer:*), Bash(plumbbob handoff:*), Bash(plumbbob harvest:*)
 ---
 
 # PlumbBob: harvest the park list
@@ -107,7 +107,16 @@ the call on each one theirs. The detail file you write first is the proposal; re
   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.
+- A confirmed **tangent** that sets an open question aside (its park names `Q3`, and the
+  question waits on work still to come) defers that question as well: run
+  `plumbbob defer Q3 "<what settles it>"`. Say so in the proposal's reason
+  (`tangent: Q3 waits on step 9's numbers`), so the human's confirmation covers the
+  deferral. The park list never moves the Questions count, so a tangent alone leaves the
+  card reading a call still owed, and the record's ending warns of any question a tangent
+  names that still counts as one to answer
+  ([D123 (defer-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d123)).
+- Fold a confirmed blocker into `intent.md`, and defer each question a confirmed tangent
+  sets aside, before you run `plumbbob harvest`, so the record and the plan agree when it
+  lands.
 - Never reclassify or resolve an item the human hasn't confirmed, and default every
   uncertain item to **tangent**, never to blocker.

package/skills/park/SKILL.md

@@ -4,7 +4,7 @@ description: "Compose one tidy tagged park line, get the human's OK in-turn, the
 argument-hint: "[idea]"
 disable-model-invocation: true
 model: haiku
-allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*)
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*), Bash(plumbbob defer:*)
 ---
 
 # PlumbBob: park an idea (capture, don't chase)
@@ -47,19 +47,36 @@ Then:
    the capture plus that one pointer are the whole turn, and both are the CLI's to render,
    never yours to compose from the dashboard. The capture is a one-beat interruption; the
    step keeps its focus.
-4. **A question beside the tangent is answered first.** When the human's message also
-   asks something, answer the question, then relay the park's block after the answer,
-   and write nothing after it. A message that is only a tangent ends on the block alone.
-   Either way the block's pointer back at the step closes the turn, so run no
-   `plumbbob handoff` after it. The answer is what the human asked for; dropping it to
-   keep the block alone, or stacking a second ending under the block, are the two ways
+4. **A question beside the tangent is answered after the capture.** When the human's
+   message also asks something, run `plumbbob park` first, then answer the question, then
+   end the turn on the park's block, typed as it printed, with no tool call after the
+   answer ([D121 (reply-after-the-tools)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d121)):
+   a client that folds text written before a tool call would show the block and hide the
+   answer. A message that is only a tangent ends on the block alone. Either way the
+   block's pointer back at the step closes the turn, so run no `plumbbob handoff` after
+   it. The answer is what the human asked for; dropping it to keep the block alone,
+   writing it above the capture, or stacking a second ending under the block are the ways
    this goes wrong.
 
+## A question set aside is deferred, not parked
+
+When the idea is an open question from the plan that the human wants picked up later,
+once other work lands (`leave Q3 until the latency numbers are in`), run
+`plumbbob defer Q3 "<what settles it>"` in place of the park. The question's own opener
+is where it waits, and the card counts it apart from the questions to answer; a park line
+beside it would leave the card counting it as a call still owed
+([D123 (defer-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d123)).
+`plumbbob defer` prints the same kind of block, `**Deferred**: Q3 (<slug>) until <what
+settles it>` and the pointer, and you relay it the same way. When `plumbbob park` warns that
+a question it names still counts as one to answer, relay the block as printed; whether to
+defer it is the human's call.
+
 ## The one hard contract
 
 The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and
-no Write tool** on purpose: you may not append to `build-log.md` yourself. Compose, get
-approval, then shell `plumbbob park`; that is the only write path. If approval
+no Write tool** on purpose: you may not append to `build-log.md` yourself, nor mark a
+question in `intent.md`. Compose, get approval, then shell `plumbbob park`, or
+`plumbbob defer` for a question set aside; those are the only write paths. If approval
 never comes, capture nothing. (When the human's **own message** states the idea, a
 tangent they raise mid-build, that message **is** the approval: capture it directly
 with `plumbbob park`, don't ask again. Deferring in words without the CLI line captures