plumbbob 0.13.0 → 0.13.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -10,11 +10,12 @@
   <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
 </p>
 
-PlumbBob is a Claude Code plugin (fifteen skills and a small CLI) that runs
+PlumbBob is a Claude Code plugin (sixteen skills and a small CLI) that runs
 LLM-assisted coding as a loop you control. You and the model settle the plan in a file
-*before* any code; then the model builds one small step at a time and **stops after
-each one**, waiting for you to read the diff and approve it before anything is
-committed. It's built for the small-to-medium work that fills most days (a feature, a
+*before* any code, down to where the build will stop for you; then the model builds it
+one small step at a time, each checked and committed on its own, and **stops where the
+plan says the call is yours**, waiting for you to read what landed and approve it
+before it goes on. It's built for the small-to-medium work that fills most days (a feature, a
 bug, a refactor) where a fully autonomous build is overkill but freestyle prompting
 leaves you dragged behind the model, reacting instead of deciding.
 
@@ -32,8 +33,9 @@ PlumbBob itself, running its own loop.
 ## Who it's for
 
 - **You already build with a coding agent and end the day reviewing a wall of diff.**
-  PlumbBob turns that wall into steps you approve one at a time, each small enough to
-  read as an editor.
+  PlumbBob turns that wall into small steps, each its own commit, and stops for your
+  review where the plan says one is due, with every step small enough to read as an
+  editor.
 - **You are skeptical of AI-written code.** Nothing lands without a green check, a
   self-review against the plan, and your say-so, and the CLI refuses to record a step
   the model approved for itself.
@@ -53,20 +55,24 @@ PlumbBob itself, running its own loop.
 Everything the model must stay true to lives in one file, the build's `intent.md`
 (under `.plumbbob/builds/<slug>/`), written before any code: the **Frame** (the problem, what done looks like, what you're
 explicitly *not* doing), the **Decisions** and **Constraints** (the settled calls, each
-with its *because*), and the **Steps**: a numbered list where every step carries a
+with its *because*), the **Steps**: a numbered list where every step carries a
 **done-when** (a checkable finish line, ideally a test) and a **seam** (the files it's
-expected to touch).
+expected to touch), and the **Build ranges**: where the build stops for your call, before
+a decision the plan left open or after a stretch of steps worth reviewing.
 
 ```text
-/plumbbob:plan       decide everything on paper — frame, decisions, all steps    (once)
-  per step:
-    /plumbbob:build      implement the next step → run checks → self-review → PAUSE
-    (looks good)         → the step is committed as a checkpoint; fire /plumbbob:build again
-/plumbbob:finish     report what shipped and why, final commit, clear            (once)
+/plumbbob:plan       decide everything on paper: frame, decisions, steps, ranges     (once)
+  per range:
+    /plumbbob:run        each step: implement → check → self-review → checkpoint
+                         then STOP where the plan says: a step's pause, or the stop card
+    (one reply)          → settle the stop; fire /plumbbob:run again
+/plumbbob:finish     report what shipped and why, final commit, clear                (once)
 ```
 
-Nothing is locked and nothing refuses you: the loop does a step's labor, pulls up to
-the line, and waits for you to advance it. **You are the clock.**
+`/plumbbob:build` is the same loop a step at a time, stopping at every step's pause, for
+a plan without ranges or a stretch you want to walk slowly. Nothing is locked and nothing
+refuses you: the loop does the labor, pulls up to the line, and waits for you to advance
+it. **You are the clock.**
 
 ## What a prompt can't replicate
 
@@ -131,20 +137,23 @@ In Claude Code, inside any git repo with a clean tree:
 
 1. **Plan.** Fire `/plumbbob:plan` and give it whatever you have: nothing (it interviews
    you), a rough line (`/plumbbob:plan rate-limit POST /login, 5/min/IP, return 429`), or a
-   path to a spec file. Together you fill the build's `intent.md`. No code is written
-   yet.
-2. **Build.** Fire `/plumbbob:build`. It implements the next undone step, runs the
-   heavy check gate, reviews its own diff against the plan, and stops. What it stops on
-   is one block with a fixed shape (the [turn anatomy](docs/presentation.md)): the CLI
-   measures the check, the seam, and the diff, the model supplies only the judgment, and
-   nothing is written around it.
+   path to a spec file. Together you fill the build's `intent.md`: the steps, and the
+   build ranges that say where the build stops for your call. For a three-step rate
+   limiter that might be step 1 alone, to settle how the bucket refills, then steps 2
+   and 3 together. No code is written yet.
+2. **Run.** Fire `/plumbbob:run`. It runs the range holding the next step, here step 1
+   alone, so it implements that step, runs the heavy check gate, reviews its own diff
+   against the plan, and stops at the step's pause, where the plan reserved your call.
+   What it stops on is one block with a fixed shape (the
+   [turn anatomy](docs/presentation.md)): the CLI measures the check, the seam, and the
+   diff, the model supplies only the judgment, and nothing is written around it.
 
    ````markdown
    **Now**: Step 1 of 3 - feat(limiter): add a token-bucket limiter
 
-   **Summary**: A per-IP token bucket now refuses the 6th attempt inside a minute. (details: `.plumbbob/detail.md`)
+   **Summary**: A per-IP token bucket now refuses the 6th attempt inside a minute. (details: [detail.md](.plumbbob/detail.md))
 
-   1. The bucket lives in memory, keyed by IP, refilling five tokens a minute.
+   1. The bucket lives in memory, keyed by IP, refilling on read: five tokens a minute.
    2. The clock is injected, so the test advances time instead of sleeping on it.
 
    **Readout**:
@@ -161,7 +170,8 @@ In Claude Code, inside any git repo with a clean tree:
 
    **Verdict**: ● Plumb
 
-   **Next Up**: Step 2 of 3 - feat(login): wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
+   **Next Up**: Step 2 of 3 - feat(login): wire the limiter into POST /login (model: **Sonnet**, details: [intent.md:28](.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md#L28))
+     · range 1 of 2 lands with step 1
 
    **Your Call**:
 
@@ -170,7 +180,7 @@ In Claude Code, inside any git repo with a clean tree:
    - anything that reads as direction → I take it as what to change; nothing lands until you approve
    - `revert` → I wind the work back to the last checkpoint
 
-   **Recommendation**: Approve it. The gate is green, the seam held, and every call the step made is one the plan already decided.
+   **Recommendation**: Approve it, refilling on read. The gate is green and the seam held, and a bucket that refills when it is read needs no timer for the route to clean up.
    ````
 
    ![The build pause as Claude Code renders it](docs/media/pause.svg)
@@ -181,14 +191,16 @@ In Claude Code, inside any git repo with a clean tree:
    `.plumbbob/settings.json`, for example `"check": "npm test"`; in a repo where
    checkride finds no tools at all, `start` says so up front and names that key.)
 3. **Reply.** Say `looks good` and it commits the step as a checkpoint, marks it done,
-   and returns to the boundary with the same three lines every landed step gets:
+   and returns to the boundary, where the line beneath Next Up names the run to type
+   next and the steps it will land:
 
    ```text
-   **Checkpoint**: Step 1 complete (a1b2c3d4e, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/build-log.md:44`)
+   **Checkpoint**: Step 1 complete (a1b2c3d4e, details: [build-log.md:70](.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/build-log.md#L70))
 
    **Verdict**: ● Plumb
 
-   **Next Up**: Step 2 of 3 - feat(login): wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
+   **Next Up**: Step 2 of 3 - feat(login): wire the limiter into POST /login (model: **Sonnet**, details: [intent.md:28](.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md#L28))
+     · range 2 of 2: /plumbbob:run (steps 2-3)
    ```
 
    ![The boundary after looks good](docs/media/checkpoint-boundary.svg)
@@ -197,18 +209,25 @@ In Claude Code, inside any git repo with a clean tree:
    changes nothing. The answer closes on one line pointing back at the step, not on the
    whole block again, since you have already read it; say `show the pause` to see the
    block again. Direct it and it takes that as the fix, and nothing lands until you say
-   `looks good`. Then fire `/plumbbob:build` again for the next step: re-firing it
-   *is* the clock tick. Whenever you lose the thread, `/plumbbob:status` shows where you
-   are and names the next move.
-4. **Finish.** When the last step is done, `/plumbbob:finish` writes a report of what shipped
-   and why into the build's tracked folder, makes the final commit, and clears the slate
-   for the next goal. The folder rides the branch into the PR: the build's record merges
-   into `main` instead of dying with the worktree.
+   `looks good`.
+4. **Run again.** Fire `/plumbbob:run` again; re-firing it *is* the clock tick. Range 2
+   lands steps 2 and 3, each on a green check with no pause between them, and ends on the
+   **stop card**: the range's review (a summary of both steps, a readout measured across
+   them, the Verdict), with every idea parked along the way listed under `Harvested` and
+   a lean proposed for each. One reply settles it: `looks good` records the review and
+   every lean, and `make P1 a blocker` changes one first. `/plumbbob:build` stays the
+   granular move whenever you want it, one step to its pause. Whenever you lose the
+   thread, `/plumbbob:status` shows where you are and names the next move.
+5. **Finish.** When the last range lands, answer its stop card with `/plumbbob:finish`: it
+   records the card, writes a report of what shipped and why into the build's tracked
+   folder, makes the final commit, and clears the slate for the next goal. The folder
+   rides the branch into the PR: the build's record merges into `main` instead of dying
+   with the worktree.
 
 A mid-build "ooh, what if…" never derails the step: `/plumbbob:park` captures it to a list
-in one line, and `/plumbbob:harvest` triages the list between steps. One goal walked end to
-end, with the real output at every stage, is in
-[`docs/happy-path.md`](docs/happy-path.md).
+in one line, and the next stop card proposes a class for it, settled with the rest of the
+review (`/plumbbob:harvest` triages the list anywhere else). One goal walked end to end,
+with the real output at every stage, is in [`docs/happy-path.md`](docs/happy-path.md).
 
 ## The skills
 
@@ -216,16 +235,17 @@ You drive the whole loop from your IDE with `/plumbbob:*` skills: no step number
 remember, no raw CLI to type. Every skill is `disable-model-invocation`, so *you* fire
 every move, and `/plumbbob:status` always names your next one. (Claude Code namespaces
 them under the plugin, so the command is `/plumbbob:plan`. The bare `/plan` reaches it
-too, but only where nothing else owns that name, and four of the fourteen share one with
+too, but only where nothing else owns that name, and five of the sixteen share one with
 a Claude Code built-in, so these docs write the full form.)
 
-**The happy path**: the three moves every session makes; many sessions need
-nothing else:
+**The happy path**: plan, run each range, finish; many sessions need nothing else, and
+build is the same loop a step at a time:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 | ------------------------------------ | ------ |
-| `/plumbbob:plan` | plan the whole goal: open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
-| `/plumbbob:build` | implement the next planned step, then verify it to the pause: `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then stops |
+| `/plumbbob:plan` | plan the whole goal: open the session and author intent's Frame, Decisions, Constraints, **and all Steps**, with the build ranges that say where the build stops for you |
+| `/plumbbob:run` | run what is left of the range holding the next step (or range N) and stop where the plan says: at a step's pause, or on the stop card that reviews what landed and settles every parked idea in one reply |
+| `/plumbbob:build` | the granular move: implement the next planned step, then verify it to the pause; `--auto` self-approves and chains to done, and a range like `1-3`, or a list like `20,5-9`, self-approves exactly the steps it names, then stops |
 | `/plumbbob:finish` | finish up: write the report, make the final commit, clear for a fresh goal |
 
 **Plan-shaping moves**: optional, for when the plan needs work mid-flight:
@@ -233,7 +253,8 @@ nothing else:
 | Skill <img alt="" width="110" height="1"> | Does |
 | ------------------------------------ | ------ |
 | `/plumbbob:step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
-| `/plumbbob:refine` | attack the frame for holes, or repair a drifted plan |
+| `/plumbbob:refine` | attack the frame for holes, or repair a drifted plan (`ranges` re-cuts the build ranges) |
+| `/plumbbob:order` | set the build order: the undone steps in the sequence to build them |
 | `/plumbbob:spike` | throwaway worktree experiment for a fork the plan can't settle |
 
 **Helpers**: orient, verify, recover, diagnose:
@@ -252,16 +273,16 @@ nothing else:
 | Skill <img alt="" width="110" height="1"> | Does |
 | ------------------------------------ | ------ |
 | `/plumbbob:park` | capture a mid-build idea without chasing it |
-| `/plumbbob:harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
+| `/plumbbob:harvest` | triage parked ideas between steps (blocker / tangent / pivot); a run's stop card carries its own |
 
-All fourteen, with inputs and effects, are in
+All sixteen, with inputs and effects, are in
 [`docs/skills-reference.md`](docs/skills-reference.md).
 
 Under the skills ships a lean `plumbbob` CLI (the mechanical verbs the
 skills shell out to), four hooks (a non-blocking post-edit lint, a `git commit`
 ask-hook while a step is in flight, the per-prompt turn ledger the approval latch
-reads, and a check at each turn's end that the turn relayed the ending plumbbob
-printed), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
+reads, which also mints a run's grant, and a check at each turn's end that the turn
+relayed the ending plumbbob printed), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
 `builds/<slug>/` folder per build (`intent.md`, `build-log.md`, `checkpoints`, `report.md`)
 that rides the branch into the PR, plus an untracked control plane (`settings.local.json`,
 the session sentinel, the in-flight markers).
@@ -295,9 +316,9 @@ The questions a skeptic should ask, answered straight.
 scoped to one session. The plan lives in the chat, so it fades with the context
 window, and the approval gates the *start* of the work, not each increment of it.
 PlumbBob puts the plan in a file in your repo that survives compaction, restarts,
-and next week; moves the approval to **every step** (each checked, reviewed
-against the plan, and committed as its own checkpoint), so a wrong turn costs one
-step, not the afternoon; and records the *whys* alongside the decisions, so the
+and next week; moves the approval to **the stops the plan names**, down to every step
+when you want it, with each step checked, reviewed against the plan, and committed as
+its own checkpoint, so a wrong turn costs one step, not the afternoon; and records the *whys* alongside the decisions, so the
 archive can still answer "what did we decide, and why" long after the session is
 gone. The two compose fine: plan mode (or anything else) can produce a step's
 diff, and `/plumbbob:verify` reads it like any other.
@@ -314,7 +335,7 @@ modes, spec kits, native checkpoints), and that convergence is evidence *for* th
 premise. PlumbBob is deliberately thin against that future: the artifacts are
 plain markdown and ordinary git commits in your own repo, the CLI is lean
 (node builtins plus one deliberate dependency), and nothing locks you in. The
-investment is small (fourteen
+investment is small (sixteen
 skills over a plain-markdown sidecar, learnable in an afternoon), and what you're
 actually learning is the method: decisions before code, one verified step at a
 time, capture instead of chase. That transfers to whatever tool wins. If
@@ -351,7 +372,7 @@ Each doc answers one question (in rough reading order for a new user):
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/): that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md): the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md): steps, seams, the pause, park/harvest, spikes.
-- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all fifteen skills: inputs, effects, when to reach for each.
+- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all sixteen skills: inputs, effects, when to reach for each.
 - *What does a turn look like, and who renders which part?* → [`docs/presentation.md`](docs/presentation.md): the anatomy of the pause, the boundary, and the driver turns.
 - *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md): the subprocess envelope, the manifest, `harness.json`, and working examples (including a local-model reviewer via Ollama).
 - *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md): the ollama-reviewer example walked end to end, install to every-pause review.

package/dist/cli-core.js

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { start } from "./verbs/start.js";
 import { status } from "./verbs/status.js";
 import { park } from "./verbs/park.js";
+import { harvest } from "./verbs/harvest.js";
 import { order } from "./verbs/order.js";
 import { build } from "./verbs/build.js";
 import { handoff } from "./verbs/handoff.js";
@@ -60,7 +61,7 @@ const VERBS = [
     {
         name: 'status',
         description: 'print the orientation dashboard, or NO ACTIVE SESSION',
-        synopsis: ['status [--build <slug>] [--invoked "<args>"]'],
+        synopsis: ['status [--build <slug>] [--invoked "<args>"] [--run "<args>"]'],
         flags: [
             BUILD_FLAG,
             {
@@ -68,6 +69,11 @@ const VERBS = [
                 value: '"<args>"',
                 gloss: 'the raw skill invocation; an explicit step number in it repoints the dashboard at that step',
             },
+            {
+                name: '--run',
+                value: '"<args>"',
+                gloss: 'the raw /plumbbob:run invocation; prints the run it names above the dashboard, or the refusal as its pointer',
+            },
         ],
         notes: 'Read-only; always exits 0. With no cursor it lists the available builds.',
     },
@@ -77,20 +83,21 @@ const VERBS = [
         synopsis: ['build [<n>] [--build <slug>]'],
         args: [{ name: '<n>', gloss: 'step to build (default: the next undone step)' }],
         flags: [BUILD_FLAG],
-        notes: 'Refuses (exit 1) with no session, a non-numeric or < 1 step, or a seam it cannot parse.',
+        notes: "Refuses (exit 1) with no session, a non-numeric or < 1 step, a seam it cannot parse, or a stop card still waiting for its reply, since the step's pause would write over the range's review; the remedy names the reply that records the card.",
     },
     {
         name: 'handoff',
-        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver), or a reminder for a pause already shown',
-        synopsis: ['handoff [<n>] [--full] [--plan] [--driver] [--build <slug>]'],
+        description: 'print the footer card that ends a turn (pause, boundary, plan, driver, or stop), or a reminder for a pause or a stop already shown',
+        synopsis: ['handoff [<n>] [--full] [--plan] [--driver] [--stop] [--build <slug>]'],
         args: [{ name: '<n>', gloss: 'step to report on (default: the in-flight step, else the last checkpointed one)' }],
         flags: [
-            { name: '--full', gloss: 'print the whole pause card even when that pause was already shown' },
+            { name: '--full', gloss: 'print the whole pause card, or with --stop the whole stop card, even when it was already shown' },
             { name: '--plan', gloss: 'render the plan-pause card instead of a step tier' },
             { name: '--driver', gloss: "render a driver turn's pointer back at the open step" },
+            { name: '--stop', gloss: "render the stop card for the range the last landing completed, from the range's detail file" },
             BUILD_FLAG,
         ],
-        notes: 'Writes only the detail file (a blank line around each heading) and the PAUSE stamp; refuses (exit 1) with no session, or with --plan and --driver together.',
+        notes: "Writes only the detail file (a blank line around each heading), the PAUSE stamp, and with --stop the STOP stamp; refuses (exit 1) with no session, with two of --plan, --driver, and --stop together, and with --stop when a step is in flight, no range that lands its steps just landed, or the detail file is not that range's.",
     },
     {
         name: 'check',
@@ -146,10 +153,21 @@ const VERBS = [
     {
         name: 'order',
         description: 'set the build order: the undone steps in the sequence to build them',
-        synopsis: ['order <n> [<n>…]', 'order --reset'],
-        args: [{ name: '<n>…', gloss: 'undone step numbers in the sequence to build them; the rest follow in document order' }],
+        synopsis: ['order <steps>', 'order --reset'],
+        args: [
+            {
+                name: '<steps>',
+                gloss: 'undone step numbers and spans (2-4) in the sequence to build them, space- or comma-separated (1, 6, 2-4, 7, 5); the rest follow in document order',
+            },
+        ],
         flags: [{ name: '--reset', gloss: 'drop the line, so the plan reads in document order again' }],
-        notes: 'Writes the one numeric line under `## Build order` in intent.md, which status, build, checkpoint, and handoff all read. Refuses (exit 1) with no session, no numbers, a number the plan lacks, a repeat, or a step already checkpointed.',
+        notes: 'Writes the one numeric line under `## Build order` in intent.md, which status, build, checkpoint, and handoff all read. A span is spelled out on the line. Refuses (exit 1) with no session, no numbers, a span that runs backward, a number the plan lacks, a repeat, or a step already checkpointed.',
+    },
+    {
+        name: 'harvest',
+        description: "record a harvest from the detail file, and at a run's stop the range's review",
+        synopsis: ['harvest'],
+        notes: "Reads the detail file's `## Harvest` proposals (`- park 6 → tangent: <reason>`), flips each settled park in build-log.md, appends the dated Harvest lines, and, when the detail is a range's, writes the range's review beneath a dated Log line; then clears the detail file and the STOP stamp, and commits nothing. Refuses (exit 1) with no session, a detail file that is no range's or harvest's, a range's detail in the turn its stop card printed, one no stop card showed, one whose range is open again, or one whose range a step joined after it landed, and a proposal naming a park the list lacks or a class other than blocker, tangent, or pivot.",
     },
     {
         name: 'spike',
@@ -360,6 +378,8 @@ async function dispatch(verb, cwd, rest) {
             return park(cwd, rest);
         case 'order':
             return order(cwd, rest);
+        case 'harvest':
+            return harvest(cwd, rest);
         case 'build':
             return build(cwd, rest);
         case 'handoff':

package/dist/lib/buildlog.js

@@ -150,3 +150,80 @@ export function abandonLogLine(date, step, title) {
     const head = `- ${date} — step ${step} abandoned · work kept in tree`;
     return title !== null && title.length > 0 ? `${head} — ${title}` : head;
 }
+/**
+ * Flip the parks named by `handles` from `- [ ]` to `- [x]` under `## Park
+ * list`, where a park's handle is its place in the list, counting every line
+ * ever parked, the same lines `parseParkTotals` counts. A handle already
+ * flipped, or past the end of the list, is left as it is.
+ *
+ * Returns null when the section is absent so the caller can report rather than
+ * silently corrupt the doc.
+ */
+export function flipParks(content, handles) {
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((l) => l.trim() === '## Park list');
+    if (headingIdx === -1) {
+        return null;
+    }
+    let handle = 0;
+    for (let i = headingIdx + 1; i < lines.length && !(lines[i] ?? '').startsWith('## '); i++) {
+        const line = lines[i] ?? '';
+        if (!/^-\s+\[[ xX]\]\s+\S/.test(line.trim())) {
+            continue;
+        }
+        handle += 1;
+        if (handles.includes(handle)) {
+            lines[i] = line.replace(/\[ \]/, '[x]');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * The dated lines a harvest appends under `## Harvest`: one saying where it
+ * ran and how many parks it settled, then one per park, its class in bold,
+ * then its handle and text, and the reason behind the arrow the card showed it
+ * with. Empty when nothing was settled.
+ */
+export function harvestLines(date, where, settled) {
+    if (settled.length === 0) {
+        return [];
+    }
+    const count = `${settled.length} parked idea${settled.length === 1 ? '' : 's'}`;
+    return [
+        `- ${date}, ${where}: ${count}, classified.`,
+        ...settled.map((p) => `- **${p.kind}**: park ${p.handle} · ${p.text}${p.reason.length === 0 ? '' : ` → ${p.reason}`}`),
+    ];
+}
+/**
+ * Append the harvest's lines to `## Harvest`, dropping the template's
+ * `- (none yet)` placeholder on the first one. Returns null when the section
+ * is absent.
+ */
+export function appendHarvest(content, lines) {
+    const all = content.split('\n');
+    const headingIdx = all.findIndex((l) => /^## Harvest\b/.test(l.trim()));
+    if (headingIdx === -1) {
+        return null;
+    }
+    const heading = (all[headingIdx] ?? '').trim().slice(3);
+    const end = all.findIndex((l, i) => i > headingIdx && l.startsWith('## '));
+    const placeholder = all.findIndex((l, i) => i > headingIdx && (end === -1 || i < end) && l.trim() === '- (none yet)');
+    if (placeholder !== -1 && lines.length > 0) {
+        // The blank above it goes too, since the first line appended brings its own.
+        const blank = (all[placeholder - 1] ?? '').trim() === '' ? 1 : 0;
+        all.splice(placeholder - blank, 1 + blank);
+    }
+    let updated = all.join('\n');
+    for (const line of lines) {
+        updated = updated === null ? null : appendToSection(updated, heading, line);
+    }
+    return updated;
+}
+/**
+ * The Log line `plumbbob harvest` writes for a stop it recorded: dated, the
+ * range over the plan's count, and the stop as the plan wrote it. The range's
+ * review rides beneath it, as a step's pause rides beneath its checkpoint.
+ */
+export function stopLogLine(date, range, count, stop) {
+    return `- ${date} — range ${range} of ${count}'s stop recorded — ${stop}`;
+}

package/dist/lib/git.js

@@ -136,6 +136,36 @@ function trackedNumstat(root) {
     catch {
         return [];
     }
+    return numstatLines(out);
+}
+/**
+ * One commit's product, one entry per file: what it changed against its
+ * parent, or against the empty tree for a root commit.
+ *
+ * The stop card's range readout reads this for each checkpoint the range
+ * landed, where the pause reads `diffNumstat` for the working tree: a landed
+ * step's work is its commit, and the tree is clean by then. `--no-renames`
+ * keeps a moved file as two plain paths, the shape the seam row wants, as it
+ * does at the pause.
+ *
+ * Information, never a gate: best-effort and never throws ([] for a sha the
+ * repo does not know).
+ */
+export function commitNumstat(root, sha) {
+    let out;
+    try {
+        out = runGit(root, ['diff-tree', '--no-commit-id', '--numstat', '--no-renames', '-r', '--root', sha]);
+    }
+    catch {
+        return [];
+    }
+    return numstatLines(out);
+}
+/**
+ * Numstat output as entries: `-` (a binary file) counts 0, and every path is
+ * one git has a blob for.
+ */
+function numstatLines(out) {
     if (out.length === 0) {
         return [];
     }
@@ -144,6 +174,29 @@ function trackedNumstat(root) {
         return { added: toCount(added), removed: toCount(removed), path: path.join('\t'), untracked: false };
     });
 }
+/**
+ * The commits on the first-parent line from `from` (exclusive) to `to`
+ * (inclusive), newest first, leaving out those whose message matches
+ * `excluding`.
+ *
+ * The stop card counts the commits outside the ledger across a range with
+ * this, the way `commitsSince` counts them since the last checkpoint: the
+ * caller takes the ledger's own shas out of the list, and passes
+ * `PLAN_COMMIT_MARKER` so a hand-made plan commit never reads as out-of-band.
+ *
+ * Best-effort and never throws: [] for an empty span or a sha the repo does
+ * not know.
+ */
+export function commitsBetween(root, from, to, excluding) {
+    try {
+        const skip = excluding === undefined ? [] : ['--grep', excluding, '--invert-grep'];
+        const out = runGit(root, ['rev-list', '--first-parent', ...skip, `${from}..${to}`]);
+        return out.length === 0 ? [] : out.split('\n');
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * The untracked half of `diffNumstat`: every non-ignored new file, counted as
  * all-added lines.

package/dist/lib/latch.js

@@ -17,6 +17,7 @@
 import { readFileSync } from 'node:fs';
 import { grantPath, tickPath, turnPath } from "./sidecar.js";
 import { resolveBoolean } from "./settings.js";
+import { hasStep, normalizeStepList, parseStepList } from "./steplist.js";
 const ALLOW = { allow: true };
 /**
  * The refusal message is the affordance; it tells the model what the pause is,
@@ -51,12 +52,20 @@ const SETTINGS_AUTO_NOTE = `note: \`auto\` is set in settings but is no longer a
 function ceilingMessage(ceiling) {
     return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; run it again to continue.\n`;
 }
+/**
+ * The refusal for a step a list grant does not name, naming the steps it does.
+ */
+function outsideMessage(step, steps) {
+    return `plumbbob: checkpoint refused — step ${step} is not in the range you granted (${normalizeStepList(steps)}) — pause here; run it again to continue.\n`;
+}
 /**
  * The five-row matrix, in order, first hit wins.
  *
- * A `range` grant speaks only to numbered steps: on a `--plan` checkpoint (step
+ * A range grant speaks only to numbered steps: on a `--plan` checkpoint (step
  * null) it neither allows nor refuses, and the decision falls through to the
- * turn comparison.
+ * turn comparison. A `steps` grant lands exactly the steps the human typed and
+ * refuses any other, so no later edit to the plan or its build order can widen
+ * it; both kinds refuse with the `ceiling` reason, a step outside the range.
  */
 export function evaluateLatch(input) {
     if (input.isTTY)
@@ -65,6 +74,11 @@ export function evaluateLatch(input) {
         return ALLOW; // 2: dormant ledger / hand-built diff
     if (input.grant?.kind === 'auto')
         return ALLOW; // 3: one-turn grant the human typed
+    if (input.grant?.kind === 'steps' && input.step !== null) {
+        if (hasStep(input.grant.steps, input.step))
+            return ALLOW;
+        return { allow: false, reason: 'ceiling', message: outsideMessage(input.step, input.grant.steps) };
+    }
     if (input.grant?.kind === 'range' && input.step !== null) {
         if (input.step <= input.grant.ceiling)
             return ALLOW;
@@ -78,15 +92,19 @@ export function evaluateLatch(input) {
     return { allow: false, reason: 'no-turn', message: input.settingsAuto ? base + SETTINGS_AUTO_NOTE : base };
 }
 /**
- * Parse a GRANT file's content (`auto` | `range <M>`).
+ * Parse a GRANT file's content (`auto` | `steps <list>` | `range <M>`).
  *
- * Anything else (including a corrupted or hand-mangled file) contributes
- * nothing: no grant, never an error.
+ * Anything else (including a corrupted or hand-mangled file, or a list that
+ * does not parse) contributes nothing: no grant, never an error.
  */
 export function parseGrant(raw) {
     const trimmed = raw.trim();
     if (trimmed === 'auto')
         return { kind: 'auto' };
+    const listed = /^steps (\S+)$/.exec(trimmed);
+    const steps = listed === null ? null : parseStepList(listed[1] ?? '');
+    if (steps !== null)
+        return { kind: 'steps', steps };
     const range = /^range (\d+)$/.exec(trimmed);
     if (range !== null)
         return { kind: 'range', ceiling: Number(range[1]) };
@@ -109,6 +127,29 @@ export function checkLatch(root, step) {
         settingsAuto: resolveBoolean(root, 'auto', false),
     });
 }
+/**
+ * Whether a stop's record may land: a human at the keyboard, a dormant ledger,
+ * or a human turn since the stop card printed.
+ *
+ * No grant opens it. A run's long turn ends on proposals, which is where a
+ * model would carry straight on into recording its own, so neither a typed
+ * range nor `--auto` stands in for the human reading the card; the reply that
+ * settles it is always a turn after the one the card printed in.
+ */
+export function evaluateStopLatch(input) {
+    if (input.isTTY)
+        return true;
+    if (input.turn === null || input.printed === null)
+        return true;
+    return input.turn > input.printed;
+}
+/**
+ * Gather the stop latch's inputs from the worktree and evaluate, for the stop
+ * card stamped as printed in turn `printed`.
+ */
+export function checkStopLatch(root, printed) {
+    return evaluateStopLatch({ isTTY: process.stdin.isTTY === true, turn: readCount(turnPath(root)), printed });
+}
 /**
  * The current GRANT, or null when the file is absent or unparseable.
  */

package/dist/lib/notice.js

@@ -67,13 +67,14 @@ export function advisory(a) {
 }
 /**
  * Assemble a transition's whole ending: the labeled lead line, the Verdict
- * where one was measured, the advisories, and the pointer.
+ * where one was measured, the advisories, the Stop part where a range landed,
+ * and the pointer.
  *
  * The order is the type's field order, so a verb composes parts and never a
  * sequence. A part with nothing in it vanishes rather than leaving a gap.
  */
 export function ending(e) {
-    return blocks([e.lead, e.verdict ?? null, ...(e.advisories ?? []), e.pointer ?? null]);
+    return blocks([e.lead, e.verdict ?? null, ...(e.advisories ?? []), e.stop ?? null, e.pointer ?? null]);
 }
 /**
  * Stack a turn's parts: one blank line between each, one beneath the last.