plumbbob 0.12.1 → 0.13.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "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

@@ -131,8 +131,8 @@ 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.
+   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
@@ -140,12 +140,14 @@ In Claude Code, inside any git repo with a clean tree:
    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`)
 
    1. The bucket lives in memory, keyed by IP, refilling five tokens a minute.
    2. The clock is injected, so the test advances time instead of sleeping on it.
 
-   **Readout**: Step 1 - feat(limiter): add a token-bucket limiter
+   **Readout**:
 
    ```text
    check        green: 7 of 7 checks
@@ -164,7 +166,7 @@ In Claude Code, inside any git repo with a clean tree:
    **Your Call**:
 
    - `looks good` → I checkpoint Step 1; back to the boundary
-   - `expand`, or any question → I show more of what is there; nothing changes
+   - `expand`, or any question → I show more of what is there; nothing changes, and `show the pause` brings all of this back
    - 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
 
@@ -192,9 +194,13 @@ In Claude Code, inside any git repo with a clean tree:
    ![The boundary after looks good](docs/media/checkpoint-boundary.svg)
 
    Ask instead (`expand 2`, or any question) and it shows more of what is there and
-   changes nothing; 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
+   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
@@ -220,8 +226,8 @@ nothing else:
 
 | 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: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: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:
@@ -229,7 +235,7 @@ 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:spike` | throwaway worktree experiment for a fork the plan can't settle |
 
 **Helpers**: orient, verify, recover, diagnose:
@@ -254,9 +260,10 @@ All fourteen, 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), three hooks (a non-blocking post-edit lint, a `git commit`
-ask-hook while a step is in flight, and the per-prompt turn ledger the approval latch
-reads), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
+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
 `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).

package/dist/cli-core.js

@@ -28,6 +28,7 @@ import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 import { recover } from "./verbs/recover.js";
 import { agent } from "./verbs/agent.js";
+import { relay } from "./verbs/relay.js";
 import { turn } from "./verbs/turn.js";
 /** Shared across every verb that resolves through the active-build cursor. */
 const BUILD_FLAG = {
@@ -80,15 +81,16 @@ const VERBS = [
     },
     {
         name: 'handoff',
-        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver); read-only',
-        synopsis: ['handoff [<n>] [--plan] [--driver] [--build <slug>]'],
+        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>]'],
         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: '--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" },
             BUILD_FLAG,
         ],
-        notes: 'Read-only; refuses (exit 1) with no session, or with --plan and --driver together.',
+        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.',
     },
     {
         name: 'check',
@@ -144,10 +146,15 @@ 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: 'spike',
@@ -225,6 +232,13 @@ const VERBS = [
         tolerateUnknownFlags: true,
         notes: 'Reads the hook payload from stdin and always exits 0 — a broken hook must never wedge a prompt.',
     },
+    {
+        name: 'relay',
+        description: 'Stop hook machinery: check that the turn carried the ending it printed (not a user verb)',
+        synopsis: ['relay'],
+        tolerateUnknownFlags: true,
+        notes: "Reads the hook payload from stdin and always exits 0: a broken hook must never wedge a turn's end.",
+    },
 ];
 /**
  * Render the verb table for `plumbbob help`.
@@ -379,6 +393,8 @@ async function dispatch(verb, cwd, rest) {
             return agent(cwd, rest);
         case 'turn':
             return turn(cwd, rest);
+        case 'relay':
+            return relay(cwd, rest);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;

package/dist/lib/git.js

@@ -68,18 +68,30 @@ export function hasCommit(root) {
 export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
+/**
+ * The body line that marks a plan commit made by hand (a `chore(plan)`
+ * harvest). A harvest lands between nearly every step, so counting it as
+ * out-of-band would trip the advisory on routine housekeeping and stop meaning
+ * anything within three steps. `status` and `handoff` both pass it to
+ * `commitsSince`, which is what keeps the two counts one quantity.
+ */
+export const PLAN_COMMIT_MARKER = '^plumbbob plan$';
 /**
  * The number of commits on HEAD not reachable from `sha`: `git rev-list
  * --count --first-parent <sha>..HEAD`.
  *
- * `status` reads this for its receipts line: one neutral note when commits
- * landed since the last checkpoint outside plumbbob's ledger (out-of-band
- * commits are surfaced, never blocked). `--first-parent` keeps the count on
- * the branch's own line: merging upstream reads as the one merge commit, not
- * the dozens it carried; those didn't land "outside the ledger" in any sense
- * the receipt should nag about. `excluding` is a commit-message pattern whose
- * matches are left out of the count, which is how a caller drops plumbbob's own
- * commits from a tally of what landed around them.
+ * `status` and `handoff` both read this for their out-of-band count: one
+ * neutral note when commits landed since the last checkpoint outside
+ * plumbbob's ledger (out-of-band commits are surfaced, never blocked). Two
+ * mechanisms keep plumbbob's own commits out of that count. A commit any
+ * plumbbob verb makes is recorded in the ledger and becomes the anchor, so the
+ * range starts after it. A plan commit made by hand carries
+ * `PLAN_COMMIT_MARKER` on a line of its body, and both callers pass it as
+ * `excluding` so the range drops it. `--first-parent` keeps the count on the
+ * branch's own line: merging upstream reads as the one merge commit, not the
+ * dozens it carried; those didn't land "outside the ledger" in any sense the
+ * receipt should nag about. `excluding` is a commit-message pattern whose
+ * matches are left out of the count.
  *
  * Best-effort and never throws: 0 when the range is empty, `sha` is unknown to
  * the repo, or HEAD is unborn: the count is informational (the human commits

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]) };

package/dist/lib/notice.js

@@ -11,7 +11,10 @@
 // the edge, and an optional indented arrow line carrying what to do next. One
 // shape, so moving it is one edit rather than a sweep. The pointer at the next
 // step is not a line's job: `handoff` renders one, and the verb prints it as
-// the ending's last part. Pure string assembly, no fs, no gate.
+// the ending's last part. The formatters are pure string assembly, no fs, no
+// gate; `printEnding` is the one function here that writes, and every ending
+// a verb prints goes through it so the relay check knows what was said.
+import { writeRelay } from "./sidecar.js";
 /** The column budget a notice line aims to fit, matching the readout fence. */
 const WIDTH = 80;
 /** The fewest detail items a degraded parenthetical still names, so the count has a universe to size. */
@@ -64,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.
@@ -83,6 +87,17 @@ export function blocks(parts) {
     const kept = parts.filter((p) => p !== null && p.trim().length > 0);
     return `${kept.map((p) => p.replace(/\n+$/, '')).join('\n\n')}\n\n`;
 }
+/**
+ * Print an ending to stdout and record it in RELAY, for the Stop check that
+ * the turn closed on it.
+ *
+ * Stdout first, and the record never throws: a failed write leaves the
+ * printed ending and the verb's exit code exactly as they would have been.
+ */
+export function printEnding(root, relay) {
+    process.stdout.write(relay.text);
+    writeRelay(root, relay);
+}
 /**
  * The head, its trailing parenthetical, and the remedy line beneath, assembled.
  *