plumbbob 0.11.3 → 0.12.0

package/.claude-plugin/plugin.json

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

@@ -221,7 +221,7 @@ 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 pauses |
+| `/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: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:

package/dist/lib/latch.js

@@ -112,7 +112,7 @@ export function checkLatch(root, step) {
 /**
  * The current GRANT, or null when the file is absent or unparseable.
  */
-function readGrant(root) {
+export function readGrant(root) {
     try {
         return parseGrant(readFileSync(grantPath(root), 'utf8'));
     }

package/dist/lib/orient.js

@@ -741,6 +741,16 @@ export function parseSections(detail) {
 export function parseRecommendation(detail) {
     return sectionProse(detail, /^##\s+recommendation\s*$/i);
 }
+/**
+ * The step `.plumbbob/detail.md` was written for, read off its
+ * `# Detail · Step <n> · <title>` header, or null when the first line is not a
+ * step header (a plan pause's detail, or a file the model wrote without one).
+ */
+export function parseDetailStep(detail) {
+    const first = detail.trimStart().split('\n', 1)[0] ?? '';
+    const m = /^#\s+Detail\b.*?\bStep\s+(\d+)\b/.exec(first);
+    return m === null ? null : Number(m[1]);
+}
 /**
  * Render an Orientation as the plain-text dashboard `status` prints.
  */

package/dist/verbs/build.js

@@ -10,14 +10,16 @@ import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTic
 import { parseStepSeam } from "../lib/intent.js";
 import { parseSteps } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
+import { readGrant } from "../lib/latch.js";
 import { notice } from "../lib/notice.js";
 /**
  * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
  * Refuses a missing session, a malformed step argument, an `N-M` range (a
  * `/plumbbob:build` skill feature, not a CLI one), and a seam that fails to parse.
- * On entry it stamps the turn ledger and the step's start time, and re-renders
- * the build-log's Current step line.
+ * On entry it stamps the turn ledger and the step's start time, re-renders the
+ * build-log's Current step line, and says so when the step is the top of a
+ * range the human typed.
  */
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -28,12 +30,13 @@ export function build(cwd, args) {
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
     // A step range like `1-3` is a `/plumbbob:build` skill affordance (auto-approve
-    // through the range, then pause), not a CLI capability: the CLI records one
-    // in-flight step at a time. Name it rather than bounce off the generic usage.
+    // every step through the range's top, then stop), not a CLI capability: the CLI
+    // records one in-flight step at a time. Name it rather than bounce off the
+    // generic usage.
     if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
         process.stderr.write(notice({
             fact: 'build takes one step number',
-            detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through it and then pauses`],
+            detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through its top and then stops`],
             remedy: `plumbbob build ${raw.split('-')[0]}`,
         }));
         return 1;
@@ -94,9 +97,22 @@ export function build(cwd, args) {
         : skipped > 0
             ? ['explicitly requested', `skips ${skipped} undone step${skipped === 1 ? '' : 's'}`]
             : [];
-    // Two lines, one colon each, then the seam as a plain readout beneath the
-    // notice that frames it: the paths are a list, and a list is not a one-liner.
+    // The top step of a typed range lands like every step under it, and the turn
+    // ends on its checkpoint. Saying so as the step is entered puts that fact in
+    // front of the model before it chooses between landing the step and holding
+    // it at a pause, which is the choice a range kept getting wrong.
+    const grant = readGrant(root);
+    const top = grant?.kind === 'range' && grant.ceiling === step
+        ? notice({
+            fact: `step ${step} is the top of the range you granted`,
+            remedy: 'land it on green, then stop at the boundary',
+        })
+        : '';
+    // Two lines (three at a range's top), one colon each, then the seam as a
+    // plain readout beneath the notice that frames it: the paths are a list, and
+    // a list is not a one-liner.
     process.stdout.write(notice({ fact: `building step ${step}`, detail: picked }) +
+        top +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],

package/dist/verbs/checkpoint.js

@@ -16,7 +16,7 @@ import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, check
 import { runCheck } from "../lib/check.js";
 import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
-import { markStepDone, parseSteps } from "../lib/orient.js";
+import { markStepDone, parseDetailStep, parseSteps } from "../lib/orient.js";
 import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
@@ -87,7 +87,7 @@ export async function checkpoint(cwd, args) {
     // tracked ledger is the archive, and it rides the branch where a commit body
     // would not survive the squash); the commit body keeps its marker and the
     // lead prose only.
-    const record = stepRecord(root, activeBuild(root), step, readDetail(root) ?? '');
+    const record = stepRecord(root, activeBuild(root), step, readDetail(root, step) ?? '');
     let sha;
     // The drift advisory is read off the index (staged, before the commit clears
     // it) but printed inside the ending below, where the fixed order puts it: the
@@ -165,7 +165,7 @@ function checkpointPlan(root, args) {
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
     // The cold read that approved the plan is the Log's first entry, beneath a
     // dated plan line; the detail file is then spent, the same as at a step.
-    const pointer = logPlan(root, sha, planRecord(readDetail(root) ?? ''));
+    const pointer = logPlan(root, sha, planRecord(readDetail(root, null) ?? ''));
     clearDetail(root);
     // Landing the plan consumes `start`'s entry stamp: a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
@@ -444,16 +444,23 @@ function fallbackBody(root, step) {
 }
 /**
  * The in-flight step's detail from `.plumbbob/detail.md`, or null when the file
- * is absent or empty.
+ * is absent, empty, or written for another step.
  *
  * The model overwrites it before every pause; checkpoint reads it once here for
  * the Log's record, and the caller clears it afterward. A missing or blank file
- * records nothing.
+ * records nothing, and so does one whose header names a different step: that
+ * file is a leftover, written after its own step had already landed, and
+ * recording it would file one step's story under another. The plan commit
+ * passes no step and takes the file as it is.
  */
-function readDetail(root) {
+function readDetail(root, step) {
     try {
         const raw = readFileSync(detailPath(root), 'utf8').trim();
-        return raw.length > 0 ? raw : null;
+        if (raw.length === 0) {
+            return null;
+        }
+        const written = step === null ? null : parseDetailStep(raw);
+        return written === null || written === step ? raw : null;
     }
     catch {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "Attention-first build process: 14 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",

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:*)
@@ -36,8 +36,8 @@ 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`
+   the second as the last step you approve and land yourself (see the range note under
+   `--auto`). With no argument, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
    (step 2) enters the next undone step and refuses with a `/plumbbob:step` nudge when every
    step is checkpointed.
 2. **Enter the step.** Run `plumbbob build <n>`, or bare `plumbbob build` to enter the
@@ -87,7 +87,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 +258,42 @@ 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. 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`.
+
+- **`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
@@ -302,7 +316,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/plan/SKILL.md

@@ -142,7 +142,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/verify/SKILL.md

@@ -163,7 +163,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