plumbbob 0.13.6 → 0.13.7

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.7",
   "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

@@ -186,7 +186,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
@@ -213,7 +215,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 +224,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 +245,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 +379,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
@@ -388,7 +400,7 @@ out, or the next step in build order is one the range does not name),
 - **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
+  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/park/SKILL.md

@@ -47,12 +47,15 @@ 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.
 
 ## The one hard contract

package/skills/plan/SKILL.md

@@ -75,7 +75,24 @@ The argument only seeds how you get there.
    stake, in plain words, enough to judge it cold), then a `*lean:*` sub-line (your
    proposed resolution: one answer to react to, not a menu), so the human settles it in
    one pass without a round-trip. (A tiny, obvious question may stay one bare line; the
-   sub-lines earn their keep only when a human decision genuinely waits on it.)
+   sub-lines earn their keep only when a human decision genuinely waits on it.) The plan
+   card tables the open questions, one row each, and a cell shows only the first sentence
+   of its line, so write each to stand on that sentence: the opener asks one question in
+   one sentence, `*plain:*` opens on why it matters, and `*lean:*` opens on the answer
+   ([D118 (questions-table)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d118)).
+   The rest of each line is for the cold reader of `intent.md`. The card's
+   `yes to all leans` move (or `yes to all leans except Q3: <their answer>`) settles them
+   in one reply: on each opener line swap `*resolve by:*` for `*resolved:* <date>, <the
+   answer>`, add the Decision the answer settles, and run `plumbbob handoff --plan` again.
+   A question the human would rather let the work answer is deferred, not resolved: on
+   `defer Q3 until <what settles it>`, keep the question and swap its `*resolve by:*` for
+   `*deferred:* <date>, until <what settles it>` on the opener line, then run
+   `plumbbob handoff --plan` again. It stays open, the card lists it on a `Deferred` line
+   beneath the table, out of reach of `yes to all leans`, and the Questions row counts it
+   apart (`**1** to answer · 2 deferred`); once the work answers it, swap the marker for
+   `*resolved:*` as above
+   ([D120 (deferred-questions)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d120)).
+   Deferring is the human's call, never yours: a lean you are unsure of is still a lean.
 4. **Author the Steps.** Write the **full build plan** under `## Steps` (each step a
    small, verifiable increment) in the exact format the parser reads:
 
@@ -215,7 +232,8 @@ The argument only seeds how you get there.
      a message that asks (`expand 2`, or any question) is answered from the detail file or
      `intent.md` and changes nothing; a message that directs is what to sharpen, cheap
      now, before any code. The revert move vanishes there on its own: nothing has landed
-     to wind back.
+     to wind back. The turn is your framed plan, then that block, and nothing after it:
+     anything you would add goes above the `---` rule the block opens on.
    - **The plan commit is latched too.** Once the turn ledger exists, `checkpoint
      --plan` refuses to land in the same turn `start` stamped it: present the plan,
      **end the turn**, and the human's approving message is the tick that lets it
@@ -230,17 +248,21 @@ The argument only seeds how you get there.
      run that lands that step's range when the plan declares ranges. Relay that block whole and run no second command; the
      plan-pause card above is the one place `handoff` is still called, because no verb has
      run yet there.
-   - **Say what the commit publishes.** The close-out line names the tracked folder:
-     `.plumbbob/builds/<slug>/` now rides this branch into the PR, so teammates will
-     see the plan and build record in review. In the same breath, offer the way out:
-     a repo that won't track a tool folder can restart with `plumbbob start --local`
-     (a fully untracked sidecar) before any steps are built.
-     - **Record-only variant.** When the repo's own `.gitignore` excludes `.plumbbob/`,
-       the folder can't ride the branch; `start` flags this up front, and the plan
-       commit lands *record-only*: an empty commit whose message carries the plan
-       (the `--body` earns its keep here), the files staying untracked. Say that
-       instead: the rationale is published in `git log`, not the folder, so pass a
-       fuller `--body` than you otherwise would, since the message is the whole record.
+   - **The card says what the commit publishes.** Until the plan commit lands, the plan
+     card's `looks good` row names the tracked folder, which rides this branch into the PR
+     (teammates will see the plan and build record in review), and a `keep it local` row
+     offers the way out. You compose neither note, before the
+     card or after it. When the human picks `keep it local`, run `plumbbob start --local`
+     on the open session: it excludes `.plumbbob/` in this clone, so the plan and finish
+     commits land record-only and the folder never rides the branch. Then run
+     `plumbbob handoff --plan` and end on the card, which now says record-only. Once the
+     plan has landed, the folder is in a commit and `start --local` refuses.
+     - **Record-only variant.** When the repo's own `.gitignore` excludes `.plumbbob/`, or
+       the session was kept local, the folder can't ride the branch; `start` flags a
+       gitignored repo up front, the card's `looks good` row says record-only, and the plan
+       commit lands as an empty commit whose message carries the plan, the files staying
+       untracked. The rationale is published in `git log`, not the folder, so pass a fuller
+       `--body` than you otherwise would, since the message is the whole record.
 8. **Offer to stress-test it.** Suggest `/plumbbob:refine` to attack the frame for holes (or
    to repair the plan as it drifts). Optional, the human's call.
 

package/skills/refine/SKILL.md

@@ -38,10 +38,19 @@ is fine; refining is always available.
   may stay one bare line; the sub-lines earn their keep only when a human decision
   genuinely waits on it.)
 
-  Then walk the human through it in the chat: list every hole you appended, each as
-  its explanation first and its lean second, and invite per-question answers; the
-  human can settle any of them right there in one message, no doc-flipping, no extra
-  round-trip per hole.
+  Then show the human what is open: run `plumbbob status --questions` and paste its
+  table whole, one row per open question with why it matters and your lean, each cell
+  the first sentence of its line, so write each line to stand on that sentence. Then
+  invite per-question answers; the human can settle any of them right there in one
+  message (`yes to all leans`, or `yes to all leans except Q3: <their answer>`), no
+  doc-flipping, no extra round-trip per hole. A resolved question gets
+  `*resolved:* <date>, <the answer>` in place of its `*resolve by:*` on the opener line. The human
+  can also leave one to the work (`defer Q3 until <what settles it>`): keep the question
+  and swap its `*resolve by:*` for `*deferred:* <date>, until <what settles it>` on the
+  opener line, and the table moves it to a `Deferred` line beneath, still open
+  ([D120 (deferred-questions)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d120)).
+  Never retype the table as a list of your own
+  ([D118 (questions-table)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d118)).
 - **Repair (re-sync to reality).** When the plan has drifted (a Decision was overtaken
   by what you built, a Constraint changed, a Step no longer matches the seam, or a
   **step's title no longer describes what the diff actually does**), propose the edits

package/skills/run/SKILL.md

@@ -122,7 +122,7 @@ walk before it, since the checkpoint would refuse it. The halt list is the build
 red check, a self-review mismatch, a bound agent's `blocked` or `drift`, or a new decision
 ends at that step's pause card. `plumbbob build` names the top step as the top of the range
 you granted when it enters it. Once that step lands, its checkpoint prints the boundary
-with the Stop row (`| Stop | Range 3 of 5 landed - <its stop> |`); relay none of it, and end
+with the Stop row (`| Stop | **Range 3** landed - <its stop> |`); relay none of it, and end
 the run on the stop card, below, in the same turn.
 
 **A bare range.** `grant: none, as a bare range builds to its pause`: build the range's one
@@ -207,6 +207,15 @@ it, and record nothing in this turn: `plumbbob harvest` refuses in the turn the
 because the human has not read it yet. If the turn is held with a reason saying the stop card
 is still owed, do exactly what the reason says.
 
+*After a halt the human approved, the card comes short.* When the step that completed the
+range halted at its pause and `looks good` landed it, the human read that step's Summary,
+Readout, and recommendation a moment ago, so `plumbbob handoff --stop` prints only the
+Harvested table, the moves, the state table with its Stop row, and the link
+([D119 (short-stop-after-a-halt)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d119)).
+Write the range's detail file all the same, in full: the stop's record reads it, and
+`show the stop` prints the card whole from it. Paste the short card exactly as it printed;
+never add back the parts it left out.
+
 ## 6. The reply at a stop
 
 The card's proposals are settled in one reply
@@ -224,14 +233,18 @@ and the Your Call block names the replies. Read the human's message as one of th
 - **A change** (`make P7 a tangent`, or a change to the review) is direction, and the turn
   that makes it is your reply
   ([D110 (reply-after-the-card)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d110)).
-  Rewrite the detail file's line or section, say in your own words what moved, then run
-  `plumbbob handoff --stop` and paste the one-line reminder it prints beneath your reply.
+  Rewrite the detail file's line or section, run `plumbbob handoff --stop` last among your
+  tool calls and keep the one-line reminder it prints, then say in your own words what
+  moved and end the turn on that line, with no tool call after your reply
+  ([D121 (reply-after-the-tools)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d121)).
   The card does not come back for a change; nothing is recorded until `looks good`, which
   records every lean as the detail file then reads.
 - **A question**, or `expand 2`, is answered from the detail file, the range's commits, or
-  the Log, never from recall; then run `plumbbob handoff --stop` and paste the one-line
-  reminder it prints beneath your answer. Only `show the stop`, or any wording of it, takes
-  `plumbbob handoff --stop --full`, and never to read the card for yourself.
+  the Log, never from recall: read what you need and run `plumbbob handoff --stop` first,
+  then write the answer, and end the turn on the one-line reminder it printed, with no tool
+  call after the answer. Only `show the stop`, or any wording of it, takes
+  `plumbbob handoff --stop --full`, which prints the card whole after a short one too, and
+  never to read the card for yourself.
 - **`/plumbbob:run`** typed at the card confirms everything the way `looks good` does, and
   runs the next range. Record first: fold the blockers and run `plumbbob harvest`, then read
   `plumbbob status --run "<the same argument>"` again. When its grant line says

package/skills/status/SKILL.md

@@ -39,3 +39,10 @@ annotate it.
    the `next →` names the run to type, `/plumbbob:run` with the steps it will land beside
    it. You relay the block with the rest; a `⚠` row is `/plumbbob:refine`'s to fix.
 4. If it reads `NO ACTIVE SESSION`, tell the human to `/plumbbob:plan` to frame a goal.
+5. If the human asks what is still open, run `plumbbob status --questions` and relay its
+   output whole: a table row per question that waits on the human, linked to its entry in
+   `intent.md`, with why it matters and the lean, and a `Deferred` line beneath it naming
+   the questions left to the work and what settles each
+   ([D120 (deferred-questions)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d120)).
+   Never list the questions in your own words
+   ([D118 (questions-table)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d118)).