plumbbob 0.13.6 → 0.13.8

package/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Frame a fresh goal and author the whole plan (Frame, Decisions, Constraints, all Steps, and the build ranges) before any code. Three input modes: no arg interviews you; a file path (or @-mention) absorbs a spec; any other text expands your inline intent."
 argument-hint: "[spec-path | intent]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob handoff:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent list:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob handoff:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*), Bash(plumbbob defer:*), Bash(plumbbob agent list:*)
 ---
 
 # PlumbBob: plan a goal (the whole-goal move)
@@ -75,7 +75,29 @@ 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>`, run `plumbbob defer Q3 "<what settles it>"`, which
+   keeps the question and swaps 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)).
+   A question the human keeps open on purpose, as the running log of something the build
+   tunes, is deferred the same way, until the work it logs; left on `*resolve by:*`, the
+   card counts it as a call still owed
+   ([D123 (defer-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d123)).
+   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:
 
@@ -163,7 +185,7 @@ The argument only seeds how you get there.
 
    **The card names the run, not the item.** The item's command is the range's
    definition: the form the parser reads, and the kind of stop it makes. The card names
-   `/plumbbob:run` in the Range row beneath Next Up for the range holding the next step,
+   `/plumbbob:run` on the range line beneath Next Up for the range holding the next step,
    with the steps it will land beside it, and `/plumbbob:run 3` runs range 3 by its item number
    ([D95 (run-verb)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d95)).
    A range grants nothing until the human types the run that names it, and then the turn
@@ -215,7 +237,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
@@ -226,21 +249,25 @@ The argument only seeds how you get there.
      refusal.)
    - **The plan commit prints its own close.** `plumbbob checkpoint --plan` emits the
      whole boundary ending: `**Plan**: committed (<sha>)`, any advisory, and the state
-     table headed by the pointer at the step the build starts on, its Range row naming the
+     table headed by the pointer at the step the build starts on, the range line beneath it naming the
      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

@@ -3,7 +3,7 @@ name: refine
 description: "Keep intent.md true: attack the plan for holes (append as Open questions) and refine or repair the Frame, Decisions, Constraints, Steps, and build ranges to match reality (`ranges` re-cuts the whole section). Usable at any point; you propose, the human approves."
 argument-hint: "[focus | ranges]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Bash(plumbbob status:*), Bash(plumbbob order:*)
+allowed-tools: Read, Edit, Bash(plumbbob status:*), Bash(plumbbob order:*), Bash(plumbbob defer:*)
 ---
 
 # PlumbBob: refine the plan
@@ -38,10 +38,24 @@ 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>`): run
+  `plumbbob defer Q3 "<what settles it>"`, which keeps the question and swaps 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)).
+  A question the table still shows that the human has already set aside (parked, settled
+  as a tangent, or kept open as a log) is drift: propose deferring it, until what the
+  build says it waits on, rather than asking it again
+  ([D123 (defer-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d123)).
+  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

@@ -3,7 +3,7 @@ name: run
 description: "Run what is left of the range holding the next step, or of range N: the plan's `## Build ranges` names the steps, the turn hook mints their grant from the plan, and the run walks them the way a typed range is walked, then ends on the stop card, the range's review with every open park proposed, which one reply settles. A bare range builds its one step to its pause. Reads the build skill beside it for the per-step loop."
 argument-hint: "[range-number]"
 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:*), Bash(plumbbob harvest:*), Bash(plumbbob order:*), Bash(git log:*)
+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:*), Bash(plumbbob harvest:*), Bash(plumbbob order:*), Bash(git log:*)
 ---
 
 # PlumbBob: run a range
@@ -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
@@ -214,8 +223,9 @@ The card's proposals are settled in one reply
 and the Your Call block names the replies. Read the human's message as one of them:
 
 - **`looks good`** confirms the review and locks in every lean as proposed, as the line
-  beneath the card's Your Call label says. Fold each confirmed blocker into `intent.md` by
-  the harvest skill's rules first, then run `plumbbob harvest`, which flips the parks,
+  beneath the card's Your Call label says. Fold each confirmed blocker into `intent.md`, and
+  defer each open question a confirmed tangent sets aside, by the harvest skill's rules
+  first, then run `plumbbob harvest`, which flips the parks,
   writes the Harvest lines, and writes the range's review beneath a dated line in the Log.
   A blocker that becomes a step goes into a range still to come, or a bare range of its
   own, never into the range this card reviews: that range has landed, its call is the one
@@ -224,20 +234,24 @@ 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
   `unlike the run`, the record re-cut the range the run would walk (a blocker added or moved a
   step in it), and the grant the hook minted before the record no longer covers it: relay
-  the record's ending whole and end the turn there, where its Range row names the re-cut run
+  the record's ending whole and end the turn there, where the range line beneath its Next Up names the re-cut run
   for the human to type
   ([D102 (settle-in-one-reply)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d102)).
   Otherwise relay the record's ending and walk the run from section 4.

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)).

package/skills/verify/SKILL.md

@@ -146,7 +146,7 @@ this skill verifies it the same way: **it reads the diff, not the author**
    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
@@ -154,12 +154,17 @@ this skill verifies it the same way: **it reads the diff, not the author**
    `## Log` for an older step, never from recall. A message that **directs** is needs-work:
    make the change, run the check, and say what moved and what the check found; when the
    change moves what the card said, 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 <n>` 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.
+   lands. Nothing lands until the human 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 <n>` 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 <n> --full` and paste its output whole, with nothing

package/templates/intent.md

@@ -129,7 +129,9 @@ Three lines:
   · *lean:* the model's proposed resolution: one answer to react to, not a menu
 
 The human reads *plain* to understand, then *lean* to approve or redirect: one
-pass, no round-trip.
+pass, no round-trip. The plan card tables the open questions a row each, and a cell
+shows only the first sentence of its line, so open the question, *plain*, and *lean*
+each on a sentence that stands alone: the question, why it matters, the answer.
 
 When a question resolves, swap *resolve by:* for *resolved:* <date, the call> ON THE
 OPENER LINE, e.g.
@@ -146,6 +148,22 @@ build reports zero open questions
 ([D77 (placeholder-uncounted)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d77));
 fill it in and it counts.
 
+When the human would rather let the work answer a question, it is deferred, not
+resolved: `plumbbob defer Q4 "<what settles it>"` keeps the question and swaps
+*resolve by:* for *deferred:* <date>, until <what settles it> ON THE OPENER LINE, so
+the opener reads
+
+  **Q4 (latency-budget)**: What latency budget do we hold?, *deferred:* 2026-10-31, until step 4's latency numbers
+
+It stays open and still counts, but the card lists it on a line beneath the table
+rather than in it, so `yes to all leans` leaves it alone. 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)).
+A question parked, settled as a tangent, or kept open as the running log of something
+the build tunes waits on the work too, so it is deferred the same way; left on
+*resolve by:*, the card counts it as a call still owed
+([D123 (defer-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d123)).
+
 Size to the work: a tiny build's single, obvious question may stay one bare line;
 the *plain:*/*lean:* pair earns its keep only when a human decision genuinely waits
 on it.