plumbbob 0.13.4 → 0.13.6

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 harvest:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob order:*), Bash(plumbbob handoff:*), Bash(plumbbob harvest:*)
 ---
 
 # PlumbBob: harvest the park list
@@ -54,24 +54,37 @@ the call on each one theirs. The detail file you write first is the proposal; re
 **only after** that reply confirms them:
 
 - Write the proposals into `.plumbbob/detail.md` first, under a `# Detail · Harvest`
-  header, one line per open item in a `## Harvest` section:
-  `- P6 → tangent: <the reason, one clause>`, the class written `blocker`, `tangent`,
-  or `pivot` (for a pivot signal). A park's handle is `P` and its place in the
-  Park list, counting the harvested lines too (the count the note sizes as
-  `parked 3 of 8 open`), and it is the one name the detail file, the turn, and the
-  human's reply all use
+  header, one proposal per open item in a `## Harvest` section, with two lines indented
+  beneath it:
+
+  ```markdown
+  - P6 → tangent: <the reason, one clause>
+    - title: <two to five words naming the park>
+    - why: <why it matters, one clause>
+  ```
+
+  The class is written `blocker`, `tangent`, or `pivot` (for a pivot signal). A park's
+  handle is `P` and its place in the Park list, counting the harvested lines too (the
+  count the state table's Parked row sizes as `3 of 8 open`), and it is the one name the
+  detail file, the turn, and the human's reply all use
   ([D105 (park-handles)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d105)).
-  Then list the same proposals in the turn, each with its handle and the park's text, and
-  end the turn there.
-- A reply that changes a proposal (`make P7 a tangent`) is the human's call: rewrite
-  that line, list the proposals again, and end the turn. A reply that confirms them
-  (`looks good`) is what lets you write.
+  Then run `plumbbob handoff --harvest` and paste its output whole, verbatim, and end the
+  turn there: it prints the lean table, one row per open park with its handle and your
+  title, the park's text as the list holds it, your why, and your lean, then the moves that
+  settle it
+  ([D112 (lean-table)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d112)).
+  Write nothing before or after it; the park's text is the CLI's to quote, never yours.
+- A reply that changes a proposal (`make P7 a tangent`) is the human's call and your
+  reply: rewrite that line, say in your own words which lean moved, and end the turn
+  without printing the table again; the human who wants to see it asks, and
+  `plumbbob handoff --harvest` prints it. A reply that confirms them (`looks good`) is what
+  lets you write.
 - On that confirmation, run `plumbbob harvest`
   ([D104 (harvest-records)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d104)).
   It flips each settled item from `- [ ]` to `- [x]` in the Park list, so
   `/plumbbob:status` stops counting it as open, and records each confirmed class under
   `build-log.md`'s `## Harvest` section. Relay its ending whole, the `**Recorded**:` line
-  and the Next Up beneath it. It refuses a proposal naming a handle the list lacks (`P9`
+  and the state table beneath it. It refuses a proposal naming a handle the list lacks (`P9`
   with eight parked) or a class other than blocker, tangent, or pivot; fix the line it
   names and run it again.
 - A confirmed **blocker** also folds its decision into `intent.md`, slugged at birth

package/skills/plan/SKILL.md

@@ -163,8 +163,8 @@ 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` 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
+   `/plumbbob:run` in the Range row 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
    hook mints the grant from the plan as it stands
@@ -205,8 +205,9 @@ The argument only seeds how you get there.
      its build ranges with it (each range's command and its stop, since a stop is where
      the human will be asked, and moving one is cheapest now), then give it the cold
      read (**§ The cold read**), write the result into `.plumbbob/detail.md`, and relay `plumbbob handoff --plan`'s block whole: the CLI
-     renders the your-call block with the moves that apply before anything is recorded and
-     prints your recommendation last (the decision tier of the
+     renders the your-call block with the moves that apply before anything is recorded,
+     the state table headed by Next Up, your recommendation, and a `more details` link to
+     the cold read (the decision tier of the
      [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)),
      so the moves are relayed, never hand-composed. *looks good* marks the plan decided, and
      its row names the move the human types next: `/plumbbob:run` for the range holding
@@ -224,9 +225,9 @@ The argument only seeds how you get there.
      commit predates the ledger and stays guidance-governed; it lands without a
      refusal.)
    - **The plan commit prints its own close.** `plumbbob checkpoint --plan` emits the
-     whole boundary ending: `**Plan**: committed (<sha>)`, any advisory, and the pointer at
-     the step the build starts on, with the run that lands its range named beneath it when
-     the plan declares ranges. Relay that block whole and run no second command; 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
+     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:
@@ -282,8 +283,11 @@ read checked and found sound. A plan with a hole gets `Sharpen <the one worst ho
 and why it matters; when the read found more than one, say how many sit behind `expand`
 and name `/plumbbob:refine` as the move that writes them up as Open questions, with their
 plain and lean sub-lines, for the human to settle. Three findings at most; the rest is
-refine's. `plumbbob handoff --plan` prints the label and your recommendation as the turn's
-last text, "expand 2" opens `## 2`, and `checkpoint --plan` records the read beneath the
+refine's. A shell command you want the human to run never rides inside a sentence: end the
+sentence on a colon and give the command a fenced `sh` block of its own, one command to a
+line, which handoff keeps line for line; `/plumbbob:refine` stays in backticks in the
+sentence. `plumbbob handoff --plan` prints the label and your recommendation beneath the
+state table, then the `more details` link to the file, "expand 2" opens `## 2`, and `checkpoint --plan` records the read beneath the
 plan's line in the build-log's `## Log`, the build's first entry. The cold read is the tip of refine: it makes the
 full attack discoverable at the moment it would pay, and lets a sound plan skip it. Refine
 is where the real adversary looks; this is an estimate, and it says so by staying short.

package/skills/run/SKILL.md

@@ -111,7 +111,7 @@ ends there: relay the checkpoint's block whole and end the turn. A run whose lan
 that step completed ends on the stop card, below, even when the paused step was the range's
 last. Otherwise carry on through what is left, below. A halt the human approves with
 `looks good` lands its step the same way, and when that landing completes the run's range
-(its checkpoint block carries the `**Stop**:` part for it), the run ends on the stop card
+(its checkpoint block's table carries the `Stop` row for it), the run ends on the stop card
 too.
 
 **A range that lands its steps.** Walk it exactly as the build skill walks a typed 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 part (`**Stop**: Range 3 of 5 landed - <its stop>`); relay none of it, and end
+with the Stop row (`| Stop | Range 3 of 5 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
@@ -161,6 +161,8 @@ constraints  all honored
 ## Harvest
 
 - P<handle> → <blocker, tangent, or pivot>: <the reason, one clause>
+  - title: <two to five words naming the park>
+  - why: <why it matters, one clause>
 
 ## Recommendation
 
@@ -170,25 +172,34 @@ constraints  all honored
 The header names the range by its item number, and that is how `checkpoint` and
 `plumbbob harvest` tell the file from a step's. The three rows judge the whole range: every
 step's done-when, the decisions any step exercised, and the constraints. The Summary and the
-highlights are the range's, not its last step's, and you draw them from the range's
+numbered sections are the range's, not its last step's, and you draw them from the range's
 checkpoint bodies (`git log` over its commits) and their entries in the build-log's `## Log`,
 never from recall, since a long run can compact its context partway through and lose its
-early steps. A step that landed a hair off comes first among the highlights; five at most.
+early steps. A step that landed a hair off comes first among the sections; five at most. The
+card prints the Summary and links the rest
+([D113 (short-card)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d113)).
 
-The `## Harvest` section carries one line for every open park in the build-log's
+The `## Harvest` section carries one proposal for every open park in the build-log's
 `## Park list`. A park's handle is `P` and its place in that list, counting the harvested
-lines too, which is the count the note sizes as `parked 3 of 8 open`: the third line ever
-parked is `P3` whether or not the two above it are flipped, and the card, the detail file,
-and the human's reply all name it `P3`
+lines too, which is the count the table's Parked row sizes as `3 of 8 open`: the third line
+ever parked is `P3` whether or not the two above it are flipped, and the card, the detail
+file, and the human's reply all name it `P3`
 ([D105 (park-handles)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d105)).
 Propose one class per park by the harvest skill's rules, `tangent` for anything uncertain,
-with the reason in one clause; the card prints it as the park's lean
-(`→ lean: tangent, <the reason>`), so write the class and the reason alone and leave the
-punctuation to handoff. A park you leave out reads `no lean proposed` on the card and stays
-open. The section vanishes when no park is open, and so does the card's Harvested part
+with the reason in one clause, and beneath it two indented lines: a title of two to five
+words that names the park, and why it matters in one clause. The card prints each park as a
+row of the lean table: its handle and your title, the park's text as the list holds it, your
+why, and the lean (`tangent: <the reason>`)
+([D112 (lean-table)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d112)),
+so write the class, the reason, the title, and the why alone and leave the table to handoff.
+A park you leave out reads `no lean proposed` on the card and stays open, and a missing why
+reads `not given`. The section vanishes when no park is open, and so does the card's Harvested part
 ([D100 (stop-card)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d100)).
 The recommendation speaks to the plan's stop, the header's `stop:` line, and to the
-proposals: the move you would take on both, then why.
+proposals: the move you would take on both, then why. A shell command you want the human to
+run never rides inside a sentence: end the sentence on a colon and give the command a fenced
+`sh` block 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.
 
 *Render it and stop.* Run `plumbbob handoff --stop` and paste its output whole, verbatim, at
 top level, trailing blank line included, then end the turn. Write nothing before it or after
@@ -210,29 +221,32 @@ and the Your Call block names the replies. Read the human's message as one of th
   own, never into the range this card reviews: that range has landed, its call is the one
   being made, and the step would reopen it. Relay the record's ending whole and end the
   turn. It commits nothing; the record rides the next step's checkpoint.
-- **A change** (`make P7 a tangent`, or a change to the review) is direction. Rewrite the
-  detail file's line or section, run `plumbbob handoff --stop`, paste the whole card it
-  prints, and end the turn. Nothing is recorded until `looks good`.
+- **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.
+  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 what it prints
-  beneath your answer, which is the one-line reminder while the stop is unchanged.
-  `show the stop`, or a session without the card in front of it, takes
-  `plumbbob handoff --stop --full`.
+  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.
 - **`/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 note names the re-cut run for
-  the human to type
+  the record's ending whole and end the turn there, where its Range row 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.
 - **`/plumbbob:finish`** at the plan's last range is the finish skill's to settle: it
   records the card the way `looks good` would before it writes the report.
 
 `plumbbob harvest` refuses a proposal naming a handle the list lacks (`P9` with eight
-parked) and a class outside the three, and it refuses a detail file no card showed; fix what the refusal names, run
-`plumbbob handoff --stop` again, and end the turn on the card. One refusal takes another
+parked) and a class outside the three, and it refuses a range no card showed; fix what the
+refusal names, run `plumbbob handoff --stop` again, and end the turn on what it prints. One refusal takes another
 path: `step 13 joined it after it landed` means a blocker went into the range the card
 reviews. Move that step to a range still to come, or a bare range of its own, leave
 `.plumbbob/detail.md` as it is, fold nothing again, and run `plumbbob harvest` once more in

package/skills/verify/SKILL.md

@@ -41,8 +41,8 @@ this skill verifies it the same way: **it reads the diff, not the author**
    - the **Constraints**: are any violated?
    - any **`after`-agent findings** from step 2: advisory, weigh them, don't defer to them.
    A mismatch surfaces in exactly two places: as the failing word in its recap row, and
-   as one highlight with its full story in a detail section, never as a freeform
-   paragraph. When you cite a Decision or Constraint, carry its slug from `intent.md`
+   as a numbered section of the detail file with its full story, which the row's `→`
+   line points at, never as a freeform paragraph. When you cite a Decision or Constraint, carry its slug from `intent.md`
    (`C1 (no-new-deps)`, never a bare `C1`) so each finding reads on its own. You are
    reviewing, not building; do not fix anything.
 4. **Validate.** Decide, yes or no, whether the step's done-when is met. That verdict and
@@ -101,18 +101,23 @@ this skill verifies it the same way: **it reads the diff, not the author**
    fence's 80 columns (13 of label, 67 of value); two or more items break onto indented
    continuation lines opening with `-`, and a red row's evidence onto an indented `→` line.
 
-   The `## Summary` lead and the `## <n>` section titles are the turn's opening block:
-   handoff prints the lead behind the `**Summary**:` label, appends the `(details: …)`
-   bracket, and renders the titles as the numbered highlights, so you type neither the path
-   nor the list. Five highlights at most, each one move in plain English, drawn from the
-   self-review. The numbers are handles: "expand 2" opens `## 2`, so every highlight has a
-   section behind it. A judgment or a flag (a stray the seam row will name, a decision the
-   diff bent, a doubt about the done-when) is one of those highlights, never a paragraph of
-   its own. The recommendation is the last section: the move you would take as its own
+   The `## Summary` lead opens the card: handoff prints it behind the `**Summary**:` label.
+   The `## <n>` sections stay in the detail file, where `expand 2` opens `## 2` and the
+   build log's record keeps them; the card prints none of them and closes instead on a
+   `[more details](…)` link to the file, which handoff writes, so you type no path. Five
+   sections at most, each titled with one move in plain English, drawn from the
+   self-review. A judgment or a flag (a stray the seam row will name, a decision the diff
+   bent, a doubt about the done-when) is one of those sections, and the card carries it
+   where it bears on the call: a bent row's `→` line points at it, and your recommendation
+   names it when it changes the move. It is never a paragraph of its own. The
+   recommendation is the last section: the move you would take as its own
    sentence, closed by a period, then the reason as a capitalized sentence or two. The lead
    and the recommendation are flowing prose and handoff unwraps both to the renderer's
    width, so never hard-wrap them; handoff also prepends the bold `**Recommendation**:`
-   label, which you never type. This is the **one** file `/plumbbob:verify` writes, and it
+   label, which you never type. A shell command you want the human to run never rides
+   inside a sentence: end the sentence on a colon and give the command a fenced `sh` block
+   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. This is the **one** file `/plumbbob:verify` writes, and it
    is turn presentation, never the diff under review; the author-blind contract below still
    holds. `checkpoint` records this file beneath the step's dated line in the build-log's
    `## Log` and then truncates it (the detail plane in the
@@ -123,13 +128,14 @@ this skill verifies it the same way: **it reads the diff, not the author**
    turn. The number is what lets a diff built outside `/plumbbob:build` reach its pause:
    nothing is in flight for that diff, and a bare `handoff` would read the moment as a
    boundary and render no Your Call block. Never nest it inside a fence of
-   your own; it carries fences of its own and they cannot nest. It prints the Now line
-   naming the step you reviewed, the Summary and its highlights, the Readout fence (its
-   measured `check`, `seam`, `diff`, and `spent` rows folded with your three), a `diff`
-   fence when the change is 20 lines or fewer, the Verdict folded worst-of from the same
-   rows, Next Up, Your Call, and your recommendation last. Run it once: a second run at an
-   unchanged 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
+   your own; it carries fences of its own and they cannot nest. It prints the Summary, the
+   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 you reviewed, Next Up, and the rows beneath it), 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 <n> --full` and paste that. At the pause the check row reads green,
    since a red one stopped you back at step 1. The gate verdict's one home is that row:
    no standalone verdict line exists, and you never restate the verdict in prose. A
@@ -140,32 +146,34 @@ 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 read the reply as an ask or a direction.* A message that **asks** ("expand 2",
-   "what does that mean?", "why did the seam row flag that?") is an expand: answer it from
-   the detail file, from `git diff`, or from the build-log's `## Log` for an older step,
-   never from recall, then run `plumbbob handoff <n>` and paste its output beneath your
-   answer, whole and verbatim. The turn is your answer, then that output, and nothing after
-   it. The pause renders its card once
-   ([D87 (pause-once)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d87)):
-   while nothing about it has changed, handoff prints one line,
-   `**Next Up**: Back to Step <N> of <M> - <title>`, in place of the card the human already
-   read, so your answer stays on screen. The CLI picks the form, never you: paste whichever
-   one it prints, and never retype the card or reach for `--full` to put it beneath an
-   answer.
-
-   Two moments bring the whole card back, and in both you run `plumbbob handoff <n> --full`
-   and paste its output whole, with nothing written around it: the human asks to see the
-   pause (`show the pause`, or any wording of it), or the card is not in this conversation
-   (a fresh session, or one after `/clear`, that finds the step still at its pause). A
-   message that **directs** is needs-work: take it as what to change, and nothing lands
-   until the human says `looks good`.
+   *Then answer the reply in your own words.* 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
+   expand: answer it from the detail file, from `git diff`, or from the build-log's
+   `## 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.
+
+   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
+   written around it. Never run `--full` to read the card for yourself, after a compaction
+   or in a fresh session; what it prints is the turn's ending, and the relay check holds a
+   turn that does not close on it. Read the detail file and `plumbbob status` instead.
 
    - **Reconcile a drifted subject here, in the open.** The planned title *is* the
      checkpoint subject ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). If the diff drifted from it (the
      step landed something the title no longer describes), the body pass may propose a
-     corrected subject, but it **presents** it at this pause for explicit approval: one
-     highlight reading `planned title → proposed subject`, part of what the human OKs.
-     That highlight is a `## <n>` section title in the detail file like any other.
+     corrected subject, but it **presents** it at this pause for explicit approval, in
+     the recommendation the card shows (`Approve it, landing it as <proposed subject>.`),
+     so it is part of what the human OKs, with the reasoning in a `## <n>` section of the
+     detail file titled `planned title → proposed subject`.
      This is the exception, not the default: with **nothing presented**, the deterministic
      title-derived subject lands untouched. A silent `-m` swap is exactly the
      agent-authored subject [D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68) refuses, so a reconcile is