plumbbob 0.10.1 → 0.10.3

package/.claude-plugin/plugin.json

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

@@ -152,7 +152,7 @@ a Claude Code built-in, so these docs write the full form.)
 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:finish` | finish up: write the report, make the final commit, clear for a fresh goal |
@@ -160,7 +160,7 @@ nothing else:
 **Plan-shaping moves**: optional, for when the plan needs work mid-flight:
 
 | 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:spike` | throwaway worktree experiment for a fork the plan can't settle |
@@ -168,7 +168,7 @@ nothing else:
 **Helpers**: orient, verify, recover, diagnose:
 
 | Skill <img alt="" width="110" height="1"> | Does |
-|------------------------------------|------|
+| ------------------------------------ | ------ |
 | `/plumbbob:status` | orient: where you are, the next step's done-when and seam, and the next move |
 | `/plumbbob:verify` | the tick, standalone: check → self-review → validate → **PAUSE** → checkpoint, for a diff `/plumbbob:build` didn't write |
 | `/plumbbob:revert` | rewind: `git reset --hard` to a recorded checkpoint |
@@ -179,7 +179,7 @@ nothing else:
 **Capture**: the park/harvest loop for mid-build ideas:
 
 | 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) |
 

package/dist/cli-core.js

@@ -58,8 +58,15 @@ const VERBS = [
     {
         name: 'status',
         description: 'print the orientation dashboard, or NO ACTIVE SESSION',
-        synopsis: ['status [--build <slug>]'],
-        flags: [BUILD_FLAG],
+        synopsis: ['status [--build <slug>] [--invoked "<args>"]'],
+        flags: [
+            BUILD_FLAG,
+            {
+                name: '--invoked',
+                value: '"<args>"',
+                gloss: 'the raw skill invocation; an explicit step number in it repoints the dashboard at that step',
+            },
+        ],
         notes: 'Read-only; always exits 0. With no cursor it lists the available builds.',
     },
     {

package/dist/lib/buildlog.js

@@ -10,6 +10,12 @@
  * Append `line` after the last non-blank line of the `## <heading>` section:
  * that is, just before the next `## ` heading or EOF.
  *
+ * When `line` is a list item and the line above it is prose (the Park list's
+ * guidance blockquote, the Log's instructions paragraph), a blank line goes in
+ * first. Markdown wants lists separated from prose (MD032), and a consumer
+ * repo that lints `.plumbbob/**` turns the missing blank into a red gate at
+ * the first park or checkpoint of a build.
+ *
  * Returns null when the section is absent so the caller can report rather than
  * silently corrupt the doc.
  */
@@ -29,9 +35,19 @@ export function appendToSection(content, heading, line) {
             insertAt = i + 1;
         }
     }
-    lines.splice(insertAt, 0, line);
+    const prev = lines[insertAt - 1] ?? '';
+    const needsBlank = isListLine(line) && prev.trim() !== '' && !isListLine(prev);
+    lines.splice(insertAt, 0, ...(needsBlank ? ['', line] : [line]));
     return lines.join('\n');
 }
+/**
+ * A markdown list line: `-`, `*`, or `+` after optional indent. Every caller
+ * of appendToSection appends one of these, so the blank-line rule above keys
+ * on the line it lands after, not on which verb is writing.
+ */
+function isListLine(line) {
+    return /^\s*[-*+]\s/.test(line);
+}
 /**
  * Replace the `**Current step:**` line with `**Current step:** <label>`:
  * `build` sets it to the step's number and title joined by an em dash when a

package/dist/lib/orient.js

@@ -159,21 +159,70 @@ export function lastLedgerSha(checkpoints) {
     }
     return last;
 }
+/**
+ * The step number an explicit skill invocation asks for, out of the raw
+ * argument text `status --invoked` receives.
+ *
+ * The first whitespace-separated token shaped like `22` or `22-24` names the
+ * step (a range asks to start at its first number); flags such as `--auto` and
+ * anything else parse to null, meaning "no explicit ask", which leaves the
+ * dashboard's own suggestion in charge. Null in means null out, so a host that
+ * never substitutes the invocation degrades to today's rendering.
+ */
+export function parseRequestedStep(raw) {
+    if (raw === null) {
+        return null;
+    }
+    for (const token of raw.trim().split(/\s+/)) {
+        const m = /^(\d+)(?:-\d+)?$/.exec(token);
+        if (m) {
+            const n = Number(m[1]);
+            return n >= 1 ? n : null;
+        }
+    }
+    return null;
+}
 /**
  * The single primary next move the dashboard suggests.
  *
  * It suggests; the dashboard prints the full list + counts so the human can
- * always override. The phase is derived: a spike in progress and an in-flight
- * step each have one obvious next move; otherwise you are at the boundary and
- * the move follows from the steps.
+ * always override. An explicitly requested step outranks the derived
+ * suggestion: the request IS the human's override, so the move names that step
+ * (noting anything it skips or collides with) rather than arguing for the
+ * default. Otherwise the phase decides: a spike in progress and an in-flight
+ * step each have one obvious next move; else you are at the boundary and the
+ * move follows from the steps.
  */
-function nextMove(spiking, steps, inFlight, parked) {
+function nextMove(spiking, steps, inFlight, parked, requested) {
+    const target = requested === null ? undefined : steps.find((s) => s.n === requested);
+    if (requested !== null && target === undefined) {
+        return `step ${requested} is not in the plan (${steps.length} step${steps.length === 1 ? '' : 's'} planned) — report the mismatch rather than guess`;
+    }
     if (spiking) {
-        return 'close the spike — `plumbbob spike done`';
+        const tail = target === undefined ? '' : `; then build step ${target.n} (explicitly requested)`;
+        return `close the spike — \`plumbbob spike done\`${tail}`;
     }
     if (inFlight !== null) {
+        if (target !== undefined && target.n !== inFlight) {
+            return `build step ${target.n} — explicitly requested (step ${inFlight} is still in flight: \`/plumbbob:verify\` it or \`/plumbbob:abandon\` it first)`;
+        }
         return `finish step ${inFlight} — \`/plumbbob:verify\` (or keep editing, then \`/plumbbob:verify\`)`;
     }
+    if (target !== undefined) {
+        if (target.done) {
+            return `build step ${target.n} — explicitly requested (already checkpointed)`;
+        }
+        const skipped = steps.filter((s) => !s.done && s.n < target.n).length;
+        const notes = [];
+        if (skipped > 0) {
+            notes.push(`skips ${skipped} undone step${skipped === 1 ? '' : 's'}`);
+        }
+        if (!target.planned) {
+            notes.push('still unplanned: `/plumbbob:step` it first');
+        }
+        const suffix = notes.length > 0 ? ` (${notes.join('; ')})` : '';
+        return `build step ${target.n} — explicitly requested${suffix}`;
+    }
     // At the boundary (DESIGN): the move follows from the steps.
     const nextUndone = steps.find((s) => !s.done);
     if (nextUndone === undefined) {
@@ -195,8 +244,13 @@ function nextMove(spiking, steps, inFlight, parked) {
 export function orient(input) {
     const steps = parseSteps(input.intent);
     const parked = parseParked(input.buildLog);
-    const nextUndone = steps.find((s) => !s.done);
-    const seamParse = nextUndone === undefined ? null : parseStepSeam(input.intent, nextUndone.n);
+    // The target the dashboard details: the explicitly requested step when it
+    // exists in the plan, else the next undone. A requested number that names no
+    // planned step carries nothing here; the next-move line reports the mismatch
+    // while the rest of the dashboard renders as usual.
+    const requestedStep = input.requested === null ? undefined : steps.find((s) => s.n === input.requested);
+    const target = requestedStep ?? steps.find((s) => !s.done);
+    const seamParse = target === undefined ? null : parseStepSeam(input.intent, target.n);
     const phase = input.spiking ? 'SPIKE' : input.inFlight !== null ? 'BUILD' : 'DESIGN';
     return {
         title: parseTitle(input.intent),
@@ -205,10 +259,11 @@ export function orient(input) {
         lastCheckpoint: parseLastCheckpoint(input.checkpoints),
         parked,
         openQuestions: parseOpenQuestions(input.intent),
-        next: nextMove(input.spiking, steps, input.inFlight, parked),
-        nextDoneWhen: nextUndone?.doneWhen ?? null,
+        next: nextMove(input.spiking, steps, input.inFlight, parked, input.requested),
+        requested: requestedStep?.n ?? null,
+        nextDoneWhen: target?.doneWhen ?? null,
         nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
-        nextModel: nextUndone?.model ?? null,
+        nextModel: target?.model ?? null,
         outOfBand: input.outOfBand,
     };
 }
@@ -218,14 +273,19 @@ export function orient(input) {
 export function formatOrientation(o) {
     const doneCount = o.steps.filter((s) => s.done).length;
     const nextUndone = o.steps.find((s) => !s.done);
+    // One arrow, always: an explicitly requested step takes the marker and the
+    // detail rows, so the injected state never argues with the invocation. With
+    // no (valid) request the next undone step keeps them, as ever.
+    const requestedStep = o.requested === null ? undefined : o.steps.find((s) => s.n === o.requested);
+    const marked = requestedStep ?? nextUndone;
     const stepLines = o.steps.map((s) => {
-        const marker = s.done ? '✓' : s === nextUndone ? '▸' : ' ';
-        const tail = s === nextUndone ? '   ← next' : '';
+        const marker = s.done ? '✓' : s === marked ? '▸' : ' ';
+        const tail = s === marked ? (requestedStep === undefined ? '   ← next' : '   ← requested') : '';
         const head = `  ${marker} ${s.n}  ${s.title}${tail}`;
-        if (s !== nextUndone) {
+        if (s !== marked) {
             return head;
         }
-        // Surface the next step's detail so the human can review it (and `/plumbbob:step`-
+        // Surface the target step's detail so the human can review it (and `/plumbbob:step`-
         // revise) before building. Only what's present: a rough step shows neither.
         const detail = [];
         if (o.nextDoneWhen !== null) {

package/dist/verbs/build.js

@@ -40,13 +40,14 @@ export function build(cwd, args) {
         return 1;
     }
     const intent = readFileSync(intentPath(root, slug), 'utf8');
+    const steps = parseSteps(intent);
     // No argument ⇒ enter the next undone step in intent.md (the same idiom
     // `checkpoint` uses), so a bare `plumbbob build` advances the loop without the
     // skill re-deriving the step in prose. Every step checkpointed ⇒ a `/plumbbob:step`
     // nudge, not a silent no-op.
     let step;
     if (raw === undefined) {
-        const nextUndone = parseSteps(intent).find((s) => !s.done);
+        const nextUndone = steps.find((s) => !s.done);
         if (nextUndone === undefined) {
             process.stderr.write('plumbbob: no undone step to build — every planned step is checkpointed. `/plumbbob:step` to add an increment, or `/plumbbob:finish`.\n');
             return 1;
@@ -73,9 +74,17 @@ export function build(cwd, args) {
     // The build-log's top half is CLI-owned so it never lies: show this step in
     // flight: Current step plus the ☐/☑ mirror, re-rendered from intent.md.
     // Best-effort: a missing or hand-edited build-log never blocks the build.
-    const title = parseSteps(intent).find((s) => s.n === step)?.title ?? null;
+    const title = steps.find((s) => s.n === step)?.title ?? null;
     syncBuildLogState(root, slug, stepLabel(step, title));
-    const picked = raw === undefined ? ' (next undone)' : '';
+    // An explicit jump past undone work says so out loud: the entered step and
+    // the count it skips read back to the human (and to the transcript), so a
+    // deliberate `build 22` and a confused one look different on the page.
+    const skipped = raw === undefined ? 0 : steps.filter((s) => !s.done && s.n < step).length;
+    const picked = raw === undefined
+        ? ' (next undone)'
+        : skipped > 0
+            ? ` (explicitly requested; skips ${skipped} undone step${skipped === 1 ? '' : 's'})`
+            : '';
     process.stdout.write(`plumbbob: building step ${step}${picked}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
 }

package/dist/verbs/finish.js

@@ -140,7 +140,7 @@ function appendStats(root, slug) {
         '## Stats',
         '',
         '| step | red checks | drift warnings | reverts | wall-clock |',
-        '|------|------------|----------------|---------|------------|',
+        '| ---- | ---------- | -------------- | ------- | ---------- |',
         ...rows,
         `| **total** | ${totals.redChecks} | ${totals.driftWarnings} | ${totals.reverts} | ${formatWall(totals.wallMs > 0 ? totals.wallMs : null)} |`,
         '',

package/dist/verbs/status.js

@@ -9,7 +9,7 @@ import { join } from 'node:path';
 import { commitsSince, findRepoRoot } from "../lib/git.js";
 import { SLOTS, readHarnessFile, resolveAgent, } from "../lib/agents.js";
 import { buildFolder, buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
-import { formatOrientation, lastLedgerSha, orient } from "../lib/orient.js";
+import { formatOrientation, lastLedgerSha, orient, parseRequestedStep } from "../lib/orient.js";
 /**
  * Read a file as utf8, or '' when it is missing or unreadable.
  */
@@ -21,12 +21,31 @@ function readOr(path) {
         return '';
     }
 }
+/**
+ * Split `--invoked "<raw args>"` out of the argument list, ahead of any other
+ * flag parsing.
+ *
+ * The value is the verbatim text of a skill invocation (the `$ARGUMENTS` the
+ * `/plumbbob:build` skill passes through), so it can contain anything,
+ * including tokens that look like this CLI's own flags; extracting it first
+ * keeps such a value from confusing `resolveBuild`. A missing flag, or one
+ * with no value, reads as null: no explicit ask.
+ */
+function takeInvoked(args) {
+    const i = args.indexOf('--invoked');
+    if (i === -1)
+        return { invoked: null, rest: args };
+    return { invoked: args[i + 1] ?? null, rest: [...args.slice(0, i), ...args.slice(i + 2)] };
+}
 /**
  * Print the orientation dashboard for the active build, plus its harness bindings.
  *
  * No session prints the exact `NO ACTIVE SESSION` sentinel; a session with
  * builds but no active one lists them and points at `use`. Always exits 0:
- * status is a report, never a gate.
+ * status is a report, never a gate. With `--invoked "<raw args>"` (how the
+ * `/plumbbob:build` skill passes its own invocation through), an explicit step
+ * number in the raw text repoints the dashboard's marker, detail, and next
+ * move at that step, so the injected state never contradicts the human's ask.
  */
 export function status(cwd, args = []) {
     const root = findRepoRoot(cwd);
@@ -34,10 +53,11 @@ export function status(cwd, args = []) {
         process.stdout.write('NO ACTIVE SESSION\n');
         return 0;
     }
+    const { invoked, rest } = takeInvoked(args);
     // A session with builds but no resolvable cursor (finish cleared it, or the repo
     // holds several builds and none is active) has no single dashboard to show, so
     // list the builds and point at `use` instead of rendering a broken, empty one.
-    const { build: slug } = resolveBuild(root, args);
+    const { build: slug } = resolveBuild(root, rest);
     if (slug === null) {
         const builds = listBuilds(root);
         if (builds.length > 0) {
@@ -59,6 +79,7 @@ export function status(cwd, args = []) {
         checkpoints,
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
         spiking: inSpike(root, slug),
+        requested: parseRequestedStep(invoked),
         outOfBand: anchor === null ? 0 : commitsSince(root, anchor),
     });
     const lines = [formatOrientation(orientation), ...harnessSection(root, slug)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "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",
@@ -53,6 +53,7 @@
     "@types/node": "26.2.0",
     "@vitest/coverage-v8": "4.1.10",
     "@vvago/vale": "3.17.1",
+    "cspell": "10.0.1",
     "fallow": "3.14.0",
     "fascicle": "0.8.16",
     "markdownlint-cli2": "0.23.2",

package/skills/build/SKILL.md

@@ -8,7 +8,14 @@ allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*
 
 # PlumbBob: build a step (the default engine)
 
-Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."`
+Current session state (injected when this skill runs): !`plumbbob status --invoked "$ARGUMENTS" 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."`
+
+**The invocation outranks the injected state.** The dashboard above is computed from
+the plan; the arguments you were invoked with are the human's explicit ask. When they
+name a step, build that step, whatever any `next →` line suggests. The CLI already
+repoints the dashboard at an explicit step number when it can see one (`--invoked`),
+so a surviving mismatch means the invocation text never reached it, and the typed
+number still wins.
 
 This is the **bundled executor**: the default engine, not the only one. It is
 **swappable**: you can implement any step by hand, in a vibe session, or with

package/templates/build-log.md

@@ -36,11 +36,11 @@ check green + checkpoint taken, via `/plumbbob:verify` or `/plumbbob:build`.)*
 Classify each parked item as exactly ONE. Naming it before acting is what keeps you
 from sprawling across branches.
 
-| Class            | Meaning                                   | Action                          |
-|------------------|-------------------------------------------|---------------------------------|
-| **blocker**      | Plan was wrong/incomplete; can't proceed  | `/plumbbob:revert`, fold into intent  |
-| **tangent**      | A different path, not clearly better      | Defer or kill. Default here.    |
-| **pivot signal** | Evidence the whole approach is wrong      | Stop. Replan deliberately.      |
+| Class            | Meaning                                   | Action                               |
+| ---------------- | ----------------------------------------- | ------------------------------------ |
+| **blocker**      | Plan was wrong/incomplete; can't proceed  | `/plumbbob:revert`, fold into intent |
+| **tangent**      | A different path, not clearly better      | Defer or kill. Default here.         |
+| **pivot signal** | Evidence the whole approach is wrong      | Stop. Replan deliberately.           |
 
 > Reality check: almost everything that *feels* like a pivot is a tangent. Require a
 > failed assumption, not a shinier idea, before you pivot.