plumbbob 0.12.0 → 0.12.1

package/skills/build/SKILL.md

@@ -24,7 +24,7 @@ the diff appeared. When you do run it, it reads the plan, writes the step, and
 carries straight through to the verify pause.
 
 Since `/plumbbob:plan` lays down the whole step list up front, the happy path is to run
-`/plumbbob:build` once per step until done: each run builds the next undone step and stops
+`/plumbbob:build` once per step until done: each run builds the next undone step in build order and stops
 at the pause for your approval. **Running `/plumbbob:build` again is itself the clock tick.**
 
 A model note: this skill **inherits the session model**; nothing pins or switches
@@ -38,7 +38,8 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    if you were given a range like `/plumbbob:build 1-3`, start at the first number and treat
    the second as the last step you approve and land yourself (see the range note under
    `--auto`). With no argument, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
-   (step 2) enters the next undone step and refuses with a `/plumbbob:step` nudge when every
+   (step 2) enters the next undone step in build order (the `## Build order` line when the
+   plan has one, else the numbering) and refuses with a `/plumbbob:step` nudge when every
    step is checkpointed.
 2. **Enter the step.** Run `plumbbob build <n>`, or bare `plumbbob build` to enter the
    next undone step (records the in-flight STEP + SEAM so `/plumbbob:status` shows the step in
@@ -268,7 +269,9 @@ and approves in the human's place**, and it **chains**:
     human has a call to make about it, so end on the same turn the default pause does:
     write the detail file, run `plumbbob handoff`, and paste its block.
   - **A clean halt lands its step first.** The top of a requested range is reached, or no
-    planned steps remain. That step checkpoints like every step before it, and its
+    planned steps remain, and `plumbbob build` names that step as it enters it (for
+    example `step 3 is the last undone step in the plan`). That step checkpoints like
+    every step before it, and its
     checkpoint's block is the whole ending: relay it with nothing written around it, then
     end the turn. Write no detail file and run no `handoff`, because nothing is pending.
     The block already carries the Verdict the step earned and a Next Up pointing at what
@@ -289,7 +292,8 @@ any next step whose plan number is past the top of the range.** It adds no machi
 the one more entry already in the halt list above, and it is a clean halt, so the top step
 is never held back for approval. The human approved it by typing the range, and
 `plumbbob build` says so as it enters that step:
-`step 3 is the top of the range you granted`.
+`step 3 is the top of the range you granted`, or, when the plan ends first,
+`the last undone step in the range you granted`.
 
 - **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, M included, then
   relay M's checkpoint block and end the turn. `N-N` is a range like any other: it builds
@@ -305,6 +309,10 @@ is never held back for approval. The human approved it by typing the range, and
 - **N is above the next undone step**: you are jumping over earlier planned work; note
   that you are skipping the steps before N, then proceed (the same latitude as a
   single-number jump like `/plumbbob:build 4`).
+- **The build order puts a number past the top ahead of the rest** (the order reads
+  `1, 4, 2, 3` under `/plumbbob:build 1-3`): a range names plan numbers, so the halt above
+  fires before step 4 and `plumbbob build` names step 1 as the last undone step in the
+  range. Build a re-sequenced stretch step by step, or grant `--auto`.
 
 ## 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) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent."
 disable-model-invocation: true
-allowed-tools: Read, Edit, Bash(plumbbob status:*)
+allowed-tools: Read, Edit, Bash(plumbbob status:*), Bash(plumbbob order:*)
 ---
 
 # PlumbBob: harvest the park list
@@ -45,5 +45,8 @@ one line of reasoning, then **wait for the human to confirm or override**. Write
 - A confirmed **blocker** also folds its decision into `intent.md`, slugged at birth
   like any Decision, anchored the same way
   (`- <a id="d5"></a>**D5 (retry-cap)**: <the call>, *because* <why>`), never a bare `D5`.
+  A blocker that becomes a new step takes the next free number under `## Steps` and,
+  when it has to land before an existing undone step, its place in the sequence through
+  `plumbbob order 7 8 5` (the `## Build order` line), never by renumbering.
 - Never reclassify or resolve an item the human hasn't confirmed, and default every
   uncertain item to **tangent**, never to blocker.

package/skills/order/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: order
+description: "Set the build order: turn the human's sequence (or a relative one, such as 7 and 8 before 5) into the full list of undone steps and write it by shelling `plumbbob order`, never by editing intent.md. A step keeps its number; the sequence moves."
+argument-hint: "[steps in the sequence to build them]"
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob order:*)
+---
+
+# PlumbBob: set the build order (the sequence, not the numbering)
+
+Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."`
+
+A step keeps its number for life, so once `/plumbbob:step` or `/plumbbob:refine` appends a step
+that has to land before an existing one, the sequence to build them stops being the
+numbering (`4, 7, 8, 5, 10, 6`). This skill writes that sequence down where every other move
+reads it: the `## Build order` line in `intent.md`, which `plumbbob status`, a bare
+`/plumbbob:build`, `plumbbob checkpoint`, and the card's Next Up all follow.
+
+## Wrong-state refusal
+
+Ordering needs an **active session** with a plan. Read the dashboard injected above: if it
+is `NO ACTIVE SESSION`, **refuse** and tell the human to run `plumbbob start "<title>"` (or
+`/plumbbob:plan`) first. Any live state is fine, mid-step included: re-sequencing what comes
+after the step in flight is the usual reason to run it.
+
+## What this skill does
+
+1. **Compose the full sequence.** Read the step list and the `build order` row on the
+   dashboard. Take the human's instruction, whether a full list (`7 8 5 10 6`) or a relative
+   one ("7 and 8 before 5", "10 last"), and turn it into **every undone step, in the sequence
+   to build them**. Never renumber a step and never move one inside `## Steps`; the sequence
+   lives in this one line.
+2. **Show the sequence and get the human's OK in-turn.** When the human's own message states
+   the full sequence, that message **is** the approval: run the verb directly.
+3. **Write it by shelling `plumbbob order 7 8 5 10 6`** via Bash. `plumbbob order --reset`
+   drops the line, and the plan reads in document order again.
+4. **Relay the ending verbatim, then stop.** The verb prints its whole ending: the
+   `**Build order**: 7, 8, 5, 10, 6` line, a blank line, and the `**Next Up**` pointer (back
+   at the step in flight, or forward to the first step in the new sequence). Run no second
+   command. A refusal (a number the plan lacks, a repeat, a step already checkpointed) is the
+   CLI's call: report it verbatim, never retry or work around it, and ask the human which
+   number they meant.
+
+## The one hard contract
+
+The line is written by the **dumb CLI**, never by an edit. This skill carries **no Edit and
+no Write tool** on purpose: you may not touch `intent.md` yourself. Compose, get approval,
+then shell `plumbbob order`; that is the only write path, and it is the one that validates
+every number against the plan.

package/skills/plan/SKILL.md

@@ -85,7 +85,9 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    Every step needs a **done-when** `/plumbbob:verify` can check and a **seam** (the exact
    paths it touches). Later steps may be fuzzier than the first (that's fine); they get
    sharpened just-in-time when you reach them with `/plumbbob:step`. Keep each small enough to
-   verify in one review pass.
+   verify in one review pass. Number them in the sequence you expect to build them and
+   leave `## Build order` alone: it is for later, when a refine appends a step that has to
+   land before an existing one (`plumbbob order`).
 
    **The title *is* the commit subject; author it as one**
    ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)): write each

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, and Steps to match reality. Usable at any point; you propose, the human approves."
 argument-hint: "[focus]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Bash(plumbbob status:*)
+allowed-tools: Read, Edit, Bash(plumbbob status:*), Bash(plumbbob order:*)
 ---
 
 # PlumbBob: refine the plan
@@ -51,7 +51,11 @@ is fine; refining is always available.
   load-bearing detail (file paths, module names) in `seam` and `done-when`,
   **never jammed into the title**; the checkpoint body pass then reconciles and lands
   that subject at the verify pause.
-  Show the before/after for each, and **write only what the human approves**.
+  Show the before/after for each, and **write only what the human approves**. A repair
+  that inserts a step, or moves one ahead of another, keeps every number where it is and
+  writes the sequence instead: shell `plumbbob order 7 8 5` with the undone steps in the
+  sequence to build them, and the `## Build order` line it writes is what every next-step
+  pick follows. Never renumber, and never edit that line by hand.
 
 ## The hard contracts
 

package/skills/step/SKILL.md

@@ -3,7 +3,7 @@ name: step
 description: "Revise the next increment just-in-time: sharpen the next undone step against what's now true, or (with input) re-cut, split, or add a step. Empty input runs an automatic sharpen. One at a time; the human approves."
 argument-hint: "[what-changed]"
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob agent list:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob order:*), Bash(plumbbob agent list:*)
 ---
 
 # PlumbBob: revise the next step (the single-increment move)
@@ -48,7 +48,11 @@ grew, but its everyday job is to sharpen, not to invent.
    `**Scope:**` header; drop the scope and it falls back to that default → build slug →
    bare, and the type to `feat` ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). Aim for a soft
    ≤72 chars, no gate. Revise the existing step in place; only append when you are
-   genuinely adding an increment.
+   genuinely adding an increment. An appended step keeps the next free number for life;
+   when it has to land before an existing undone step, place it by sequence, never by
+   renumbering: shell `plumbbob order 7 8 5` with every undone step in the sequence to
+   build them, and the `## Build order` line it writes is what `status`, a bare
+   `/plumbbob:build`, and the card's Next Up then follow.
 4. **Revise the step's harness bindings if they drifted too** *(optional)*. If the
    build carries a `harness.json` (beside `intent.md`) and the reality that moved the
    step also changed which agents it wants, sharpen that step's slot bindings
@@ -63,7 +67,8 @@ grew, but its everyday job is to sharpen, not to invent.
 - **One verifiable increment.** Each step carries a done-when `/plumbbob:verify` can check
   and a seam small enough to review in one pass.
 - **Edit `## Steps` only**, in the standard format `status` and `build` parse: never
-  the Roadmap, never loose prose. A done step (`[x]`) is history; do not rewrite it.
+  the Roadmap, never loose prose. A done step (`[x]`) is history; do not rewrite it. The
+  `## Build order` line is `plumbbob order`'s to write, never yours to edit.
 - **Cite the plan's own numbers in the linked form.** A `D`/`C`/`Q` you write into a
   step's done-when, seam, or notes reads `[D4 (default-waves)](#d4)`; the slug travels
   with the number, and the link lands on the `<a id="d4">` anchor minted where the item

package/skills/verify/SKILL.md

@@ -113,8 +113,11 @@ this skill verifies it the same way: **it reads the diff, not the author**
    `## Log` and then truncates it (the detail plane in the
    [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)).
 
-   *Paste the turn.* Run `plumbbob handoff` and paste its output whole, verbatim, at top
-   level, trailing blank line included, then end the turn. Never nest it inside a fence of
+   *Paste the turn.* Run `plumbbob handoff <n>`, naming the step you reviewed, and paste
+   its output whole, verbatim, at top level, trailing blank line included, then end the
+   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 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
@@ -130,8 +133,8 @@ this skill verifies it the same way: **it reads the diff, not the author**
 
    *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` again and
-   paste it. The step is still in flight, so it renders the same pause, and the Your Call
+   `git diff`, or from the build-log's `## Log` for an older step, never from recall, then run `plumbbob handoff <n>` again and
+   paste it. The step has not landed, so it renders the same pause, and the Your Call
    block stays the CLI's to render rather than yours to retype. A message that **directs**
    is needs-work: take it as what to change, and nothing lands until the human says
    `looks good`.
@@ -194,7 +197,7 @@ When this session runs under plumbbob's turn hook, `plumbbob checkpoint` **refus
 land a step in the same turn it was entered**, and that refusal **is** this pause, not
 an error to route around. If the checkpoint prints `checkpoint refused — no human turn
 since this step began`, you have reached the pause the hard way: write the file, run
-`plumbbob handoff`, paste its block as step 5 says, **end the turn there**, and the
+`plumbbob handoff <n>`, paste its block as step 5 says, **end the turn there**, and the
 human's next message is the tick that lets
 the checkpoint land when you run it again. **Never reach for a raw `git commit` to force the
 land**; that forges the very record the latch exists to keep honest, and the
@@ -220,8 +223,8 @@ instead.**
   self-review; checkride gates, the human approves. `blocked` → unblock and re-run;
   `drift` → `/plumbbob:refine` before checkpointing. No code path makes them blocking.
 - **A refused checkpoint is the pause, never a workaround.** Under the turn
-  hook a same-turn checkpoint is refused *by design*: write the file, run `plumbbob
-  handoff`, paste its block, **end the turn there**, and let the human's next message
+  hook a same-turn checkpoint is refused *by design*: write the file, run
+  `plumbbob handoff <n>`, paste its block, **end the turn there**, and let the human's next message
   re-tick it. Never route around it with a
   raw `git commit`; the latch guards the record, not the work.
 - **Close with the next model.** When the checkpoint lands it prints the whole boundary

package/templates/intent.md

@@ -79,6 +79,15 @@ auto-syncs it), and use `/plumbbob:refine` to repair the whole plan when a block
 2. [ ] <step>, **done when:** <criterion>
    - seam: `<file>`
 
+## Build order
+
+*(Optional. The sequence to build the steps in once it stops being their numbering: one
+line of comma-separated step numbers, such as `7, 8, 5, 10, 6`; empty means document
+order. `plumbbob order 7 8 5 10 6` (`/plumbbob:order`) writes it, and `status`, `build`,
+`checkpoint`, and `handoff` all read it, so the dashboard's `← next`, a bare
+`/plumbbob:build`, and the card's Next Up agree. A step keeps its number for life; this
+line is where the sequence lives.)*
+
 ## Open questions
 
 *(Holes you could NOT resolve on paper: the one section that expands rather than