plumbbob 0.10.0 → 0.10.1

package/.claude-plugin/plugin.json

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

@@ -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";
@@ -113,6 +114,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 +339,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/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/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/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.1",
+  "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/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.