plumbbob 0.11.3 → 0.12.1

package/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build
-description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses."
+description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then stops."
 argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
@@ -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
@@ -36,9 +36,10 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
 
 1. **Pick the step.** Use the number you were invoked with (for example `/plumbbob:build 4`), or,
    if you were given a range like `/plumbbob:build 1-3`, start at the first number and treat
-   the second as the auto-approve ceiling (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
+   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 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
@@ -87,7 +88,9 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
      <<'BODY'`). Do **not** pass it as an argument value (`--body "$(cat <<'BODY'…)"`):
      `--body` ignores an argument and always reads stdin. Under an agent harness that
      stdin is a socket, and `--body` now refuses rather than blocking on one; the
-     refusal names this exact heredoc form.
+     refusal names this exact heredoc form. End that line at `<<'BODY'`, with no `2>&1`
+     after it: Claude Code's permission checker cannot analyze the extra redirect, so it
+     blocks the command or stops to ask instead of letting this skill's allowance cover it.
    - **A drifted subject is reconciled at the pause, never silently.** 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, **present** a corrected subject at the pause (`planned title → proposed
@@ -256,30 +259,45 @@ and approves in the human's place**, and it **chains**:
   self-review finds no done-when / Decision / Constraint mismatch, checkpoint** and move
   straight on to the next planned step. Repeat. `--auto` adds no new machinery; the
   `after`-agent output simply feeds the *existing* self-review halt condition.
-- **Stop and hand back to the human** the moment any of these is true: the check is red,
-  the self-review finds a mismatch (surface exactly what, and do not checkpoint it), a
-  bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine`; an
-  agent cannot advance the loop), a new decision is needed, no planned steps
-  remain, or the top of a requested range is reached. **When `--auto` halts back to the
-  human, end on the same turn the default pause does**: write the detail file, run
-  `plumbbob handoff`, and paste its block: the step just completed, the next undone step,
-  and that next step's `- model:` recommendation if it has one, so a fresh context window
-  knows which `/model` to select.
+- **Stop and hand back to the human** the moment a halt arrives, and end the turn by the
+  kind of halt it is
+  ([D85 (range-top-lands)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d85)):
+  - **A halt on trouble leaves a step unlanded.** The check is red, the self-review finds
+    a mismatch (surface exactly what, and do not checkpoint it), a bound agent returns
+    `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine`; an agent cannot
+    advance the loop), or a new decision is needed. The step is still in flight and the
+    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, 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
+    comes next (the next undone step and its `- model:` recommendation, or the finish),
+    which is what a fresh context window needs to pick the right `/model`.
 
 `--auto` and a step range are the only paths that checkpoint without a human pause, and
-only because the human asked for it by name; a range re-imposes the pause at its top.
-The default (no flag, no range) always ends at the pause.
+only because the human asked for it by name. A range hands the clock back once its top
+step has landed: the step after it waits for the human's next run. The default (no flag,
+no range) always ends at the pause.
 
 ### A step range (`N-M`) is a bounded `--auto`
 
-`/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **pauses
-after step 3** instead of chaining to done. The range *is* the opt-in; you do not also
-pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
-any next step whose plan number is past the top of the range.** It adds no machinery:
-just the one more entry already in the halt list above.
-
-- **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, then pause at
-  M. `N-N` is just the single step `N` (which already ends at the pause).
+`/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **stops
+once step 3 has landed** instead of chaining to done. The range *is* the opt-in; you do not
+also pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
+any next step whose plan number is past the top of the range.** It adds no machinery: just
+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`, 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
+  and lands the single step `N`. Only a bare `/plumbbob:build N` ends at the pause.
 - **N > M** (for example `3-1`): that is not a range you can walk; report it and stop rather
   than guess the intent.
 - **M past the last planned step** (for example `1-9` with three steps): build through the
@@ -291,6 +309,10 @@ just the one more entry already in the halt list above.
 - **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
 
@@ -302,7 +324,7 @@ just the one more entry already in the halt list above.
 - **Default ends at the pause.** Implement → verify → wait for approval; never
   checkpoint without it. Only an explicit `--auto` or a step range lets the agent approve
   in your place, and it still halts on a red check or any mismatch; a range also stops
-  at its top.
+  once its top step lands.
 - **Agents feed the beat; they never advance it**. `before` loads context,
   `build` writes the diff, `after` is advisory; none can checkpoint, flip a step, or
   chain. `blocked` → unblock and re-run; `drift` → `/plumbbob:refine`. You are still the one

package/skills/finish/SKILL.md

@@ -53,8 +53,11 @@ record.
    Redirect the heredoc *into* the command (`--body <<'BODY'`). Do **not** pass it as
    an argument value (`--body "$(cat <<'BODY'…)"`): `--body` ignores an argument and
    always reads stdin. Under an agent harness that stdin is a socket, and `--body` now
-   refuses rather than blocking on one; the refusal names this exact heredoc form. Omit
-   `--body` entirely and the commit carries the `plumbbob finish` marker subject only.
+   refuses rather than blocking on one; the refusal names this exact heredoc form. End
+   that line at `<<'BODY'`, with no `2>&1` after it: Claude Code's permission checker
+   cannot analyze the extra redirect, so it blocks the command or stops to ask instead of
+   letting this skill's allowance cover it. Omit `--body` entirely and the commit carries
+   the `plumbbob finish` marker subject only.
 3. **Point at the next goal.** Relay `plumbbob finish`'s output verbatim, blank lines
    included: its lead line, which names the branch the tracked folder now rides into the
    PR, any advisory beneath it, and `**Next Up**: Nothing planned - /plumbbob:plan`. That

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
@@ -142,7 +144,8 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    a `plan <sha>` line in
    `checkpoints`. This keeps the first step's diff clean, so history reads
    baseline → plan → steps. Pass a proportional `--body` (the single-quoted stdin
-   heredoc) when the rationale is worth carrying; skip it for a small plan. Do this
+   heredoc, with nothing after `<<'BODY'` on its line, not even `2>&1`) when the
+   rationale is worth carrying; skip it for a small plan. Do this
    only on the human's approval; the plan is their convergence.
    - **The plan pause is a decision turn.** Present the framed plan for the human's call,
      then give it the cold read (**§ The cold read**), write the result into

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`.
@@ -163,7 +166,10 @@ this skill verifies it the same way: **it reads the diff, not the author**
    Redirect the heredoc *into* the command (`--body <<'BODY'`). Do **not** pass it as
    an argument value (`--body "$(cat <<'BODY'…)"`): `--body` ignores an argument and
    always reads stdin. Under an agent harness that stdin is a socket, and `--body` now
-   refuses rather than blocking on one; the refusal names this exact heredoc form.
+   refuses rather than blocking on one; the refusal names this exact heredoc form. End
+   that line at `<<'BODY'`, with no `2>&1` after it: Claude Code's permission checker
+   cannot analyze the extra redirect, so it blocks the command or stops to ask instead of
+   letting this skill's allowance cover it.
 
    Do **not** run a TIL scan or reach for a separate commit skill; the body is yours to
    write in one breath. Omit `--body` entirely and the CLI writes a deterministic body
@@ -191,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
@@ -217,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