plumbbob 0.10.0 → 0.10.2

package/.claude-plugin/plugin.json

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

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
 </p>
 
-PlumbBob is a Claude Code plugin (thirteen skills and a small CLI) that runs
+PlumbBob is a Claude Code plugin (fourteen 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
@@ -145,7 +145,7 @@ 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 thirteen share one with
+too, but only where nothing else owns that name, and four of the fourteen 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
@@ -172,6 +172,7 @@ nothing else:
 | `/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 |
+| `/plumbbob:abandon` | drop the in-flight step, keep its work in the tree; the step stays planned |
 | `/plumbbob:recover` | reconcile the session's own state when the dashboard looks wrong |
 | `/plumbbob:doctor` | check the install from inside a session |
 
@@ -182,7 +183,7 @@ nothing else:
 | `/plumbbob:park` | capture a mid-build idea without chasing it |
 | `/plumbbob:harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
 
-All thirteen, with inputs and effects, are in
+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
@@ -240,7 +241,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 (thirteen
+investment is small (fourteen
 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
@@ -289,7 +290,7 @@ Each doc answers one question (in rough reading order for a new user):
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/): that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md): the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md): steps, seams, the pause, park/harvest, spikes.
-- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all thirteen skills: inputs, effects, when to reach for each.
+- *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all fourteen skills: inputs, effects, when to reach for each.
 - *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.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md): the full guide and the agent-neutral roadmap.

package/dist/cli-core.js

@@ -19,6 +19,7 @@ import { handoff } from "./verbs/handoff.js";
 import { check } from "./verbs/check.js";
 import { checkpoint } from "./verbs/checkpoint.js";
 import { revert } from "./verbs/revert.js";
+import { abandon } from "./verbs/abandon.js";
 import { spike } from "./verbs/spike.js";
 import { use } from "./verbs/use.js";
 import { finish } from "./verbs/finish.js";
@@ -57,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.',
     },
     {
@@ -113,6 +121,13 @@ const VERBS = [
         ],
         notes: 'Refuses (exit 1) with no session, an invalid --to, or a step with no recorded checkpoint.',
     },
+    {
+        name: 'abandon',
+        description: 'drop the in-flight step but keep its work in the tree',
+        synopsis: ['abandon [--build <slug>]'],
+        flags: [BUILD_FLAG],
+        notes: 'Refuses (exit 1) with no session, no step in flight, or a latched boundary (no human turn since the step began). Clears STEP/SEAM/TICK/handoff and logs the abandon; never touches the working tree, git, or the intent checkbox.',
+    },
     {
         name: 'park',
         description: 'append a raw line to the park list',
@@ -331,6 +346,8 @@ async function dispatch(verb, cwd, rest) {
             return checkpoint(cwd, rest);
         case 'revert':
             return revert(cwd, rest);
+        case 'abandon':
+            return abandon(cwd, rest);
         case 'spike':
             return spike(cwd, rest);
         case 'use':

package/dist/lib/buildlog.js

@@ -102,3 +102,13 @@ export function checkpointLogLine(date, step, sha, title, stats = null) {
     const titled = title !== null && title.length > 0 ? `${head} — ${title}` : head;
     return stats !== null && stats.length > 0 ? `${titled} (${stats})` : titled;
 }
+/**
+ * The Log line `abandon` writes for a dropped-but-kept step: the first
+ * non-checkpoint event the log records. Dated, names the step (its title when
+ * intent.md still carries it), and states plainly that the work stayed in the
+ * tree, so the narrative never has a step go quiet mid-flight.
+ */
+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;
+}

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/lib/sidecar.js

@@ -191,12 +191,28 @@ export function spikePath(root, slug) {
 export function seamPath(root, slug) {
     return join(artifactDir(root, slug), 'SEAM');
 }
+/**
+ * Remove the SEAM marker: `abandon` drops the in-flight step's edit grant, the
+ * same clear `checkpoint` and `revert` do inline. Homed here so a verb not
+ * sanctioned to delete on its own can still return to the boundary; absent is a
+ * no-op.
+ */
+export function clearSeam(root, slug) {
+    rmSync(seamPath(root, slug), { force: true });
+}
 /**
  * STEP: the number of the step in flight, a bare number in a flat file.
  */
 export function stepPath(root, slug) {
     return join(artifactDir(root, slug), 'STEP');
 }
+/**
+ * Remove the STEP marker alongside SEAM, dropping the build back to the DESIGN
+ * boundary; absent is a no-op.
+ */
+export function clearStep(root, slug) {
+    rmSync(stepPath(root, slug), { force: true });
+}
 /**
  * The build's `checkpoints` ledger: the recorded SHAs of landed plan and step
  * commits, one line each.

package/dist/verbs/abandon.js

@@ -0,0 +1,122 @@
+// `plumbbob abandon`: the third exit from an in-flight step. Checkpoint lands
+// the step and revert destroys the work; abandon drops the attempt but keeps the
+// working-tree diff exactly where it is. Its only writes are the in-flight
+// control markers it clears (STEP, SEAM, TICK, and the step-scoped handoff
+// ledger), a build-log line, and the stats receipt: it touches neither the
+// working tree nor git nor the intent checkbox, so the step stays planned and
+// re-buildable with its diff still in the tree for the human to keep, rework, or
+// commit by hand.
+//
+// A step exit is a boundary crossing, so abandon honors the same approval latch
+// as checkpoint. That is not decoration: abandon clears the entry stamp the
+// latch reads, so an unlatched abandon followed by a same-turn checkpoint would
+// hand that checkpoint an unlatched land, the same side door the settings-auto
+// case closed. Every deletion routes through the sidecar helpers that own
+// control-state clears; abandon itself never calls the raw fs deleters.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { bumpStepStat, buildLogPath, clearHandoff, clearSeam, clearStep, clearTick, hasSession, intentPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
+import { checkLatch } from "../lib/latch.js";
+import { abandonLogLine, appendToSection } from "../lib/buildlog.js";
+import { parseSteps } from "../lib/orient.js";
+/**
+ * Drop the in-flight step while keeping its work: latch, clear the markers,
+ * record the event, and return to the boundary.
+ *
+ * Exit 1 on any refusal: no session, no step in flight, or a latched boundary
+ * (no human turn since the step began). Each refusal says what unblocks it.
+ */
+export function abandon(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const { build: slug } = resolveBuild(root, args);
+    const step = readInFlightStep(root, slug);
+    if (step === null) {
+        process.stderr.write('plumbbob: no step in flight to abandon. abandon drops an in-flight step; from the boundary there is nothing to drop.\n');
+        return 1;
+    }
+    // The same latch checkpoint runs, keyed on this step: a step exit is a boundary
+    // crossing, and abandon clears the entry stamp, so an unlatched abandon would
+    // hand a same-turn checkpoint an unlatched land. Refusal is the pause, not an
+    // error: exit 1 and hand the turn back.
+    const latch = checkLatch(root, step);
+    if (!latch.allow) {
+        process.stderr.write(abandonPause(latch.reason, step));
+        return 1;
+    }
+    // Keep the work: clear only the in-flight control markers, never the tree,
+    // git, or the intent checkbox. The step stays [ ] and re-buildable.
+    clearStep(root, slug);
+    clearSeam(root, slug);
+    clearTick(root, slug);
+    clearHandoff(root, slug);
+    bumpStepStat(root, slug, step, 'abandons');
+    logAbandon(root, slug, step);
+    process.stdout.write(`plumbbob: step ${step} abandoned — work kept in the tree, back at the boundary. The step stays planned.\n`);
+    return 0;
+}
+/**
+ * The abandon-worded pause affordance.
+ *
+ * abandon runs checkpoint's latch, but the pause it hits is its own: the wording
+ * names the verb the human ran and the one self-approval that lands it, rather
+ * than sending them back to `checkpoint`. A `ceiling` reason (a range grant the
+ * step overran) keeps the range wording.
+ */
+function abandonPause(reason, step) {
+    if (reason === 'ceiling') {
+        return `plumbbob: abandon refused — step ${step} is past the range you granted; pause here, then run it again to continue.\n`;
+    }
+    return `plumbbob: abandon refused — no human turn since this step began. A step exit crosses the same
+boundary as a checkpoint, so abandon honors the same pause: end the turn, and the human's approval on
+their next turn is what lets it land. (An explicit \`/plumbbob:build --auto\` or a step range in the
+human's own prompt is the only self-approval.)
+`;
+}
+/**
+ * The in-flight STEP number from the marker, or null when none is in flight.
+ */
+function readInFlightStep(root, slug) {
+    try {
+        const raw = readFileSync(stepPath(root, slug), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Append the abandon line to the build-log's `## Log`, the first non-checkpoint
+ * event the log records.
+ *
+ * Best-effort like every build-log write: a missing or odd log never fails an
+ * abandon, whose real record is the cleared markers and the stats bump.
+ */
+function logAbandon(root, slug, step) {
+    try {
+        const path = buildLogPath(root, slug);
+        const date = new Date().toISOString().slice(0, 10);
+        const line = abandonLogLine(date, step, titleForStep(root, slug, step));
+        const updated = appendToSection(readFileSync(path, 'utf8'), 'Log', line);
+        if (updated !== null) {
+            writeFileSync(path, updated);
+        }
+    }
+    catch {
+        // best-effort ledger; never fail an abandon over the build-log.
+    }
+}
+/**
+ * The step's title from intent.md, or null when absent or unreadable.
+ */
+function titleForStep(root, slug, step) {
+    try {
+        return parseSteps(readFileSync(intentPath(root, slug), 'utf8')).find((s) => s.n === step)?.title ?? null;
+    }
+    catch {
+        return 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/doctor.js

@@ -252,8 +252,11 @@ function narrowExcludes(root) {
 /**
  * Perform the migration and return a human-readable list of what moved.
  *
- * STAGES the result but never commits: the human owns that commit. Call only when
- * `inspectLegacy` reported a legacy layout; doctor prints the returned actions.
+ * STAGES the result but never commits: the human owns that commit. In a repo
+ * that gitignores the sidecar the stage is skipped (stagePath's record-only
+ * guard) and the report says so: the files move but stay untracked. Call only
+ * when `inspectLegacy` reported a legacy layout; doctor prints the returned
+ * actions.
  */
 export function migrateSidecar(root) {
     const dir = sidecarDir(root);
@@ -297,8 +300,10 @@ export function migrateSidecar(root) {
     }
     rmSync(archiveDir, { recursive: true, force: true });
     narrowExcludes(root);
-    stagePath(root, '.plumbbob');
-    actions.push('staged the move (builds/ + settings.json) — commit it yourself');
+    const staged = stagePath(root, '.plumbbob');
+    actions.push(staged
+        ? 'staged the move (builds/ + settings.json) — commit it yourself'
+        : 'moved but not staged (the sidecar is gitignored) — the files stay untracked');
     return actions;
 }
 /**

package/dist/verbs/recover.js

@@ -159,7 +159,7 @@ function phaseFindings(root, slug, stepInFlight) {
                 name: 'step marker',
                 ok: false,
                 detail: `step ${marker} is in flight but the plan has no step ${marker} (planned: ${planned.join(', ')})`,
-                hint: 'the plan was rewritten under the step — sharpen it with /plumbbob:step, or plumbbob revert to drop the step',
+                hint: 'the plan was rewritten under the step — sharpen it with /plumbbob:step, plumbbob revert to drop the step and its work, or plumbbob abandon to drop the step but keep the work',
             });
         }
     }

package/dist/verbs/spike.js

@@ -104,9 +104,9 @@ function readInFlightStep(root, buildSlug) {
  * Open a spike: one throwaway worktree + `spike/<slug>-<opt>` branch per option.
  *
  * Refuses when a spike is already open or a step is in flight: a spike is a
- * deliberate fork from a settled boundary, so the current step must checkpoint
- * or revert first. Marks the SPIKE control file and scaffolds the report before
- * returning.
+ * deliberate fork from a settled boundary, so the current step must exit first
+ * (checkpoint, abandon, or revert). Marks the SPIKE control file and scaffolds
+ * the report before returning.
  */
 function spikeStart(root, buildSlug, positionals) {
     if (inSpike(root, buildSlug)) {
@@ -115,7 +115,7 @@ function spikeStart(root, buildSlug, positionals) {
     }
     if (existsSync(stepPath(root, buildSlug))) {
         process.stderr.write('plumbbob: spike starts from a settled boundary, but a step is in flight. ' +
-            'A spike is a deliberate fork — checkpoint or revert the current step first.\n');
+            'A spike is a deliberate fork — checkpoint, abandon, or revert the current step first.\n');
         return 1;
     }
     const slug = sanitize(positionals[0] ?? '');

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,7 +1,7 @@
 {
   "name": "plumbbob",
-  "version": "0.10.0",
-  "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
+  "version": "0.10.2",
+  "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",
     "claude",
@@ -42,7 +42,8 @@
     "test": "vitest run",
     "eval:baseline": "pnpm build && node test/evals/run.ts --sweep baseline",
     "eval:latched": "pnpm build && node test/evals/run.ts --sweep latched",
-    "eval:report": "node test/evals/run.ts --report"
+    "eval:report": "node test/evals/run.ts --report",
+    "size:prose": "node scripts/count-prose.ts"
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.1",

package/skills/abandon/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: abandon
+description: "Human-triggered driver for `plumbbob abandon`: drop the in-flight step while keeping its work in the tree, and return to the boundary. The step stays planned."
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob abandon:*)
+---
+
+# PlumbBob: abandon the in-flight step (driver)
+
+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."`
+
+This is a **driver skill**: a chat-side trigger for the mechanical `plumbbob abandon` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool**; its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+Abandon is the third exit from an in-flight step. `/plumbbob:verify` lands the step and `/plumbbob:revert` destroys its work; abandon drops the attempt and keeps the working-tree diff exactly where it is. The step keeps its `[ ]` in the plan, re-buildable later, and the diff stays yours to keep, rework, or commit by hand.
+
+## What it does
+
+1. Run `plumbbob abandon` via Bash. It clears the in-flight markers (`STEP`, `SEAM`, `TICK`, and the step's agent handoff ledger), appends an abandon line to the build log, and touches neither the working tree nor git.
+2. Report the verb's output verbatim: the step it dropped, or any refusal. A step exit crosses the same boundary as a checkpoint, so abandon honors the same approval latch; a "no human turn since this step began" refusal is the pause working, not an error. End the turn, and the human's next turn is what lets a re-fired abandon land.

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/skills/recover/SKILL.md

@@ -25,4 +25,4 @@ Reach for it when the dashboard and reality disagree: `status` shows a build you
 
 - **Spike leftovers are reported, never removed.** Those worktrees sit outside the repo and may hold the only copy of what a spike learned, so the verb prints the exact `git worktree remove` / `git branch -D` commands and stops. Relay them; do not run them yourself.
 - **A contradictory phase is yours to settle.** A spike and a step both marked in flight, or a step number the plan no longer contains, need a decision about which one is real; `--fix` deliberately leaves them alone.
-- **It is not a rewind.** Recovering reconciles bookkeeping; it never restores lost work. Discarding a half-done step is `/plumbbob:revert`, and that is a different, destructive move the human asks for by name.
+- **It is not a rewind, and not an exit.** Recovering reconciles bookkeeping; it never restores lost work and never drops a step. Discarding a half-done step is `/plumbbob:revert` (destructive), and dropping one while keeping its work in the tree is `/plumbbob:abandon`; both are different moves the human asks for by name.

package/skills/revert/SKILL.md

@@ -16,5 +16,5 @@ This is a **driver skill**: a chat-side trigger for the mechanical `plumbbob rev
 ## What it does
 
 1. Read an optional target step from the way you were invoked (for example `/plumbbob:revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
-2. Run `plumbbob revert` (or `plumbbob revert --to <n>`) via Bash. This is a `git reset --hard`; it discards the current in-progress step. Run it exactly as the human asked; do not add or drop the `--to` on your own.
+2. Run `plumbbob revert` (or `plumbbob revert --to <n>`) via Bash. This is a `git reset --hard`; it discards the current in-progress step *and its work*. If the human wants to drop the step but keep the working-tree diff, that is `/plumbbob:abandon`, not revert. Run it exactly as the human asked; do not add or drop the `--to` on your own.
 3. Report the verb's output verbatim: which checkpoint it reset to, or any refusal.