plumbbob 0.13.1 → 0.13.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "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.
@@ -47,26 +49,31 @@ PlumbBob itself, running its own loop.
 ## The loop in one picture
 
 <p align="center">
-  <img src="docs/media/loop-one-step.svg" alt="One step of the loop: /plumbbob:build implements step 1 and stops at the pause, the human says looks good, the step is checkpointed" width="760">
+  <img src="site/media/loop-one-step.svg" alt="One step of the loop, drawn as a wall going up course by course: on the scaffold a person reads a plumb line at the corner, and down the wall a mechanical arm holds the next stone and waits" width="760">
 </p>
 
 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.** [`docs/runs.md`](docs/runs.md) walks one plan through its runs
+and then drives it by hand, the two side by side.
 
 ## What a prompt can't replicate
 
@@ -132,19 +139,22 @@ 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`: the steps, and the
-   build ranges that say where the build stops for your call. 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.
+   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 +171,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,10 +181,10 @@ 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)
+   ![The pause, drawn: a mechanical hand has set its stone on the line and hovers open and still, while a plumb bob in front comes to rest](site/media/pause.svg)
 
    (The check gate is [checkride](https://www.npmjs.com/package/checkride), one
    run across the tools your repo already configures: types, lint, tests, dead
@@ -181,36 +192,43 @@ 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)
+   ![The boundary, drawn: a bench mark freshly cut into the newest course of a stone wall, older marks below, and the red line raised one course over stones not yet laid](site/media/checkpoint-boundary.svg)
 
    Ask instead (`expand 2`, or any question) and it shows more of what is there and
    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. When the plan cut build ranges, the line beneath Next Up names
-   one to type instead (`· range 2 of 2: /plumbbob:build 2-3`): it lands each step it
-   names and stops where the plan reserved a call for you. 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
 
@@ -218,16 +236,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**, with the build ranges that say where the build stops for you |
-| `/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`, or a list like `20,5-9`, self-approves exactly the steps it names, then stops |
+| `/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:
@@ -236,6 +255,7 @@ nothing else:
 | ------------------------------------ | ------ |
 | `/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 (`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:
@@ -254,16 +274,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).
@@ -297,9 +317,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.
@@ -316,7 +336,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
@@ -341,19 +361,21 @@ that matters.
 > under [`docs/evals/`](docs/evals/): the route the latch owns (*no checkpoint over a red
 > check under pressure*) went from **2/5 prose-only to 5/5 latched** on the first sweep
 > ([2026-07-11](docs/evals/2026-07-11.md)), every sweep since has held it and closed the
-> two gaps that one surfaced, and the latest ([2026-09-17](docs/evals/2026-09-17.md))
-> scores the shape of the turn itself.
+> two gaps that one surfaced, [2026-09-17](docs/evals/2026-09-17.md) began scoring the
+> shape of the turn itself, and the latest ([2026-10-19](docs/evals/2026-10-19.md)) holds a
+> run to its stop card, 5/5.
 
 ## Documentation
 
 Each doc answers one question (in rough reading order for a new user):
 
 - *What does a session actually look like?* → [`docs/happy-path.md`](docs/happy-path.md): one goal walked end to end; read this first.
+- *How do I drive a plan with runs, and what do they replace?* → [`docs/runs.md`](docs/runs.md): ranges, the build order, and the stop card's harvest, walked through three runs and set beside the manual build, harvest, and order moves.
 - *What do the words mean?* → [`docs/glossary.md`](docs/glossary.md): every term the loop mints, one line each, with where to read more.
 - *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',
@@ -156,6 +163,12 @@ const VERBS = [
         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. 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',
         description: 'worktree experiment + report for a genuine fork',
@@ -365,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

@@ -127,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.
  */