plumbbob 0.9.5 → 0.10.1

package/dist/lib/sidecar.js

@@ -1,22 +1,22 @@
-// The .plumbbob/ sidecar — plumbbob's control directory beside the code. Control
+// The .plumbbob/ sidecar: plumbbob's control directory beside the code. Control
 // state lives in flat files (bare numbers, plain path lists, one-line markers) so
 // shell hooks can read it with a grep and no markdown parsing. Functional and
 // procedural, node builtins only.
 //
 // Two planes share the directory: the tracked ARTIFACT plane (settings.json and
-// each build's `builds/<slug>/` folder — intent, build-log, checkpoints, report),
+// each build's `builds/<slug>/` folder: intent, build-log, checkpoints, report),
 // which rides its branch into the PR, and the git-excluded CONTROL plane (STATE,
 // the personal settings overlay, the turn ledger, and each build's in-flight
 // markers), which stays per-worktree and never commits.
 //
 // STATE is the session sentinel AND the active-build cursor: its EXISTENCE means
-// "a session is active", and its CONTENT names the build that session is on — the
+// "a session is active", and its CONTENT names the build that session is on: the
 // two reinforce each other (a session is always on some build; the cursor is
 // meaningless without a session). Content is empty under --local / no build.
 // hasSession stays existence-only; activeBuild reads the content. Homing the
-// cursor here — not in settings.local.json — keeps that overlay purely
+// cursor here (not in settings.local.json) keeps that overlay purely
 // human-owned (check/auto): the tool only ever reads it, never rewrites it. The
-// phase the dashboard shows (DESIGN/BUILD/SPIKE) is derived, not stored — BUILD ⇔
+// phase the dashboard shows (DESIGN/BUILD/SPIKE) is derived, not stored: BUILD ⇔
 // a STEP is in flight, SPIKE ⇔ the SPIKE marker is present, otherwise DESIGN.
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -48,7 +48,7 @@ export function buildDir(root, slug) {
  * Derive a filesystem-safe slug from a build title.
  *
  * Lowercased, every run of non-alphanumerics collapsed to a single hyphen,
- * trimmed of leading/trailing hyphens. The CLI stays dumb and explicit —
+ * trimmed of leading/trailing hyphens. The CLI stays dumb and explicit:
  * collision handling belongs to the caller (`start` refuses an existing slug
  * rather than silently suffixing `-2`, and prepends the `YYYY-MM-DD-` date that
  * keeps `listBuilds`' lexical sort chronological). A title with no alphanumerics
@@ -65,7 +65,7 @@ export function slugify(title) {
  * date prefix `start` prepends stripped off.
  *
  * `2026-07-18-escape-hatch` yields the human-meaningful `escape-hatch`. Null
- * when no build resolves (`--local`, or a slug that is nothing but a date) — the
+ * when no build resolves (`--local`, or a slug that is nothing but a date); the
  * caller then omits the `(scope)` segment, which Conventional Commits permit.
  */
 export function buildScope(slug) {
@@ -76,7 +76,7 @@ export function buildScope(slug) {
     return stripped.length > 0 ? stripped : null;
 }
 /**
- * Existing build slugs — the directory names under `builds/`, sorted.
+ * Existing build slugs: the directory names under `builds/`, sorted.
  *
  * Empty when `builds/` is absent (a `--local` repo, or before the first tracked
  * `start`).
@@ -110,7 +110,7 @@ export function activeBuild(root, flag) {
     return builds.length === 1 ? (builds[0] ?? null) : null;
 }
 /**
- * STATE's content — the active-build cursor — or null when it names no build.
+ * STATE's content (the active-build cursor) or null when it names no build.
  *
  * Empty means "no build" (--local, or a session whose cursor is unset), so
  * activeBuild falls through to the sole-build rule. The literal value `active`
@@ -135,7 +135,7 @@ function readCursor(root) {
  *
  * Every verb resolves through this: an explicit `--build <slug>` wins, else the
  * cursor / sole-build fallback of `activeBuild`. `rest` matters because the slug
- * is a bare token — scanning positionals on the raw argv would let it masquerade
+ * is a bare token: scanning positionals on the raw argv would let it masquerade
  * as a step number or a spike slug, so callers scan `rest` instead.
  */
 export function resolveBuild(root, args) {
@@ -145,7 +145,7 @@ export function resolveBuild(root, args) {
     return { build: activeBuild(root, args[i + 1]), rest: [...args.slice(0, i), ...args.slice(i + 2)] };
 }
 /**
- * The STATE file — session sentinel and active-build cursor in one.
+ * The STATE file: session sentinel and active-build cursor in one.
  */
 function statePath(root) {
     return join(root, DIRNAME, 'STATE');
@@ -158,7 +158,7 @@ function statePath(root) {
  * omit it and the dir resolves from the cursor (the default the
  * executor-agnostic path reads lean on). Either way a `null` slug falls back to
  * the flat sidecar root, which covers the `--local` layout and any
- * no-cursor/no-build repo — the path reads stay stable even before a tracked
+ * no-cursor/no-build repo: the path reads stay stable even before a tracked
  * build exists or when a "no active session" guard is about to fire.
  */
 function artifactDir(root, slug) {
@@ -166,7 +166,7 @@ function artifactDir(root, slug) {
     return resolved === null ? sidecarDir(root) : buildDir(root, resolved);
 }
 /**
- * The resolved build's artifact folder — the `builds/<slug>/` dir for the active
+ * The resolved build's artifact folder: the `builds/<slug>/` dir for the active
  * build (or the flat sidecar root under `--local`/no-cursor).
  *
  * Public so the plan-approval commit can stage exactly this build's scaffold and
@@ -176,7 +176,7 @@ export function buildFolder(root, slug) {
     return artifactDir(root, slug);
 }
 /**
- * The SPIKE marker — a single-purpose presence flag, like SEAM/STEP.
+ * The SPIKE marker: a single-purpose presence flag, like SEAM/STEP.
  *
  * Written by `spike` on open, removed on `spike done`. Its existence is the one
  * signal the dashboard and the spike gates read to know "a spike is active".
@@ -185,39 +185,55 @@ export function spikePath(root, slug) {
     return join(artifactDir(root, slug), 'SPIKE');
 }
 /**
- * SEAM — the in-flight step's edit grant: a plain list of the paths the step may
+ * SEAM: the in-flight step's edit grant: a plain list of the paths the step may
  * touch, one per line, so the hooks read it with a grep and no markdown parsing.
  */
 export function seamPath(root, slug) {
     return join(artifactDir(root, slug), 'SEAM');
 }
 /**
- * STEP — the number of the step in flight, a bare number in a flat file.
+ * 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');
 }
 /**
- * The build's `checkpoints` ledger — the recorded SHAs of landed plan and 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.
  */
 export function checkpointsPath(root, slug) {
     return join(artifactDir(root, slug), 'checkpoints');
 }
 /**
- * intent.md — the build's plan: steps, seams, decisions, done-when.
+ * intent.md: the build's plan: steps, seams, decisions, done-when.
  */
 export function intentPath(root, slug) {
     return join(artifactDir(root, slug), 'intent.md');
 }
 /**
- * build-log.md — the human-facing build ledger (the Steps mirror and the Log).
+ * build-log.md: the human-facing build ledger (the Steps mirror and the Log).
  */
 export function buildLogPath(root, slug) {
     return join(artifactDir(root, slug), 'build-log.md');
 }
 /**
- * report.md — the close-out report, beside intent.md / build-log.md.
+ * report.md: the close-out report, beside intent.md / build-log.md.
  *
  * The finish skill writes it and `finish` commits it with the folder; the
  * tracked build folder is the archive, so the report rides the branch into the
@@ -227,7 +243,7 @@ export function reportPath(root, slug) {
     return join(artifactDir(root, slug), 'report.md');
 }
 // --- Spike reports: `spike-NN-<slug>.md` files in the build folder, beside
-// report.md. One per spike — an explicit `/plumbbob:spike` or a planned `spike:` step —
+// report.md. One per spike (an explicit `/plumbbob:spike` or a planned `spike:` step)
 // so a build with several forks tells its decision history through the folder
 // listing. NN is CLI-allocated (the human never numbers them), zero-padded for a
 // stable sort. ---
@@ -251,7 +267,7 @@ export function listSpikeReports(root, slug) {
  * sanitized spike slug.
  *
  * One past the highest existing NN, so a gap never reallocates a number. Pure
- * allocation — the caller writes the stamped template there.
+ * allocation: the caller writes the stamped template there.
  */
 export function nextSpikeReportPath(root, slug, spikeSlug) {
     const used = listSpikeReports(root, slug).map((name) => Number(name.slice('spike-'.length, 'spike-'.length + 2)));
@@ -260,10 +276,10 @@ export function nextSpikeReportPath(root, slug, spikeSlug) {
     return join(artifactDir(root, slug), `spike-${nn}-${spikeSlug}.md`);
 }
 /**
- * handoff.json — the agent-run ledger.
+ * handoff.json: the agent-run ledger.
  *
  * Each `agent run` appends its validated envelope here so a later invocation can
- * thread earlier results into the next call's `context[]` — the CLI itself is
+ * thread earlier results into the next call's `context[]`: the CLI itself is
  * memoryless between runs, and the file survives context-window compaction where
  * inline stdout does not. It is in-flight control state like STEP/SEAM:
  * untracked (excludeControl), scoped to the current step, cleared when the step
@@ -276,7 +292,7 @@ export function handoffPath(root, slug) {
  * Append one entry to the build's handoff.json.
  *
  * Creates the file (as a JSON array) when absent and tolerates a malformed
- * existing file by starting fresh — a corrupt ledger must never wedge a run.
+ * existing file by starting fresh: a corrupt ledger must never wedge a run.
  * Pretty-printed so it stays readable.
  */
 export function appendHandoff(root, slug, entry) {
@@ -295,7 +311,7 @@ export function appendHandoff(root, slug, entry) {
     writeFileSync(path, `${JSON.stringify(entries, null, 2)}\n`);
 }
 /**
- * Remove the build's handoff.json — the step-scoped ledger clears when the step
+ * Remove the build's handoff.json: the step-scoped ledger clears when the step
  * checkpoints, the same beat that clears STEP/SEAM.
  *
  * An absent file is a no-op (`force`).
@@ -304,13 +320,13 @@ export function clearHandoff(root, slug) {
     rmSync(handoffPath(root, slug), { force: true });
 }
 /**
- * stats.json — the per-build stats receipt, beside checkpoints.
+ * stats.json: the per-build stats receipt, beside checkpoints.
  */
 export function statsPath(root, slug) {
     return join(artifactDir(root, slug), 'stats.json');
 }
 /**
- * The whole stats file, or {} when absent or corrupt — malformed contributes
+ * The whole stats file, or {} when absent or corrupt: malformed contributes
  * nothing.
  */
 export function readStats(root, slug) {
@@ -325,14 +341,14 @@ export function readStats(root, slug) {
 /**
  * Increment one counter on one step.
  *
- * Best-effort by contract: a failed write is swallowed — the stats are a
+ * Best-effort by contract: a failed write is swallowed; the stats are a
  * receipt, never a gate on the verb that accrues them.
  */
 export function bumpStepStat(root, slug, step, key) {
     patchStepStat(root, slug, step, (current) => ({ [key]: (current[key] ?? 0) + 1 }));
 }
 /**
- * Stamp one timestamp on one step — startedAt at `build <n>`, landedAt at
+ * Stamp one timestamp on one step: startedAt at `build <n>`, landedAt at
  * checkpoint.
  *
  * Same best-effort contract as bumpStepStat.
@@ -362,7 +378,7 @@ function patchStepStat(root, slug, step, patch) {
 /**
  * A session exists iff STATE exists.
  *
- * Deleting STATE (at finish) is what flips the repo back to "no session" — the
+ * Deleting STATE (at finish) is what flips the repo back to "no session": the
  * file is the single source of truth for "is there a session". `start` calls
  * beginSession; `finish` removes the file. Existence is the whole session
  * signal; STATE's content is a separate axis (the cursor).
@@ -381,7 +397,7 @@ export function beginSession(root, slug = null) {
     writeCursor(root, slug);
 }
 /**
- * Re-point the cursor at an existing build (`use`) — a plain content rewrite
+ * Re-point the cursor at an existing build (`use`): a plain content rewrite
  * that leaves the session sentinel (STATE's existence) intact.
  *
  * Callers guard hasSession first, so this never resurrects a finished session.
@@ -396,13 +412,13 @@ function writeCursor(root, slug) {
     writeFileSync(statePath(root), slug === null ? '' : `${slug}\n`);
 }
 /**
- * True while a spike is open — the SPIKE marker exists (content is irrelevant).
+ * True while a spike is open: the SPIKE marker exists (content is irrelevant).
  */
 export function inSpike(root, slug) {
     return existsSync(spikePath(root, slug));
 }
 /**
- * Drop the SPIKE marker — existence is the whole signal.
+ * Drop the SPIKE marker: existence is the whole signal.
  */
 export function markSpike(root, slug) {
     writeFileSync(spikePath(root, slug), 'active\n');
@@ -415,20 +431,20 @@ export function clearSpike(root, slug) {
 }
 // --- The turn ledger: the checkpoint latch's inputs. `.plumbbob/TURN` is a count
 // of human prompts the model never writes, with a one-turn `.plumbbob/GRANT`
-// beside it — both flat, per-worktree control (never per-build, never committed).
+// beside it: both flat, per-worktree control (never per-build, never committed).
 // `plumbbob turn` (the UserPromptSubmit hook) ticks TURN once per human prompt
 // and rewrites GRANT from the literal prompt; the checkpoint latch reads them to
 // refuse a land until a human turn has intervened since the step was entered.
 // Kept in the sidecar so the lone GRANT `rmSync` stays where deletions of control
 // state are allowed. ---
 /**
- * TURN — the human-turn count the UserPromptSubmit hook maintains.
+ * TURN: the human-turn count the UserPromptSubmit hook maintains.
  */
 export function turnPath(root) {
     return join(root, DIRNAME, 'TURN');
 }
 /**
- * GRANT — the one-turn self-approval minted from the human's literal prompt.
+ * GRANT: the one-turn self-approval minted from the human's literal prompt.
  */
 export function grantPath(root) {
     return join(root, DIRNAME, 'GRANT');
@@ -437,8 +453,8 @@ export function grantPath(root) {
  * Rewrite (or clear) the one-turn GRANT: a non-null value is the minted grant
  * (`auto` | `range M`), null clears it.
  *
- * The turn hook calls this on every human prompt — minted on a match, cleared
- * otherwise — so a grant lives exactly one turn by construction. Pairing the
+ * The turn hook calls this on every human prompt (minted on a match, cleared
+ * otherwise) so a grant lives exactly one turn by construction. Pairing the
  * write with its delete here means a grant can never half-persist, and the
  * delete lives where deletions belong.
  */
@@ -451,7 +467,7 @@ export function setGrant(root, grant) {
     }
 }
 /**
- * TICK — the per-build entry stamp: the TURN value recorded when work was
+ * TICK: the per-build entry stamp: the TURN value recorded when work was
  * entered (`build <n>` for a step, `start` for the plan), cleared when
  * `checkpoint` lands.
  *
@@ -474,7 +490,7 @@ export function stampTick(root, slug) {
     writeFileSync(tickPath(root, slug), `${turn}\n`);
 }
 /**
- * Consume the entry stamp — `checkpoint` clears it when a step (or the plan)
+ * Consume the entry stamp: `checkpoint` clears it when a step (or the plan)
  * lands, the same beat that clears STEP/SEAM/handoff.
  *
  * Absent is a no-op; the rmSync lives here with the sidecar's other deletions.
@@ -486,7 +502,7 @@ export function clearTick(root, slug) {
  * The TURN count, or null when the ledger is absent or unreadable.
  *
  * Absence is the "dormant" signal stampTick keys off and the doctor latch probe
- * reports — never an error.
+ * reports: never an error.
  */
 export function readTurn(root) {
     try {
@@ -502,7 +518,7 @@ export function readTurn(root) {
  * `.plumbbob/STATE` file), or null when there is none.
  *
  * The turn hook runs on every human prompt in every repo; this is the cheap,
- * git-free probe that keeps it a silent no-op outside a live plumbbob session —
+ * git-free probe that keeps it a silent no-op outside a live plumbbob session:
  * filesystem only, never a host sniff.
  */
 export function findSessionRoot(cwd) {
@@ -519,8 +535,8 @@ export function findSessionRoot(cwd) {
 /**
  * Append `patterns` to the repo's info/exclude, each at most once.
  *
- * Idempotent — a re-`start` after finish must not double-add. `gitPath` resolves
- * to the *common* gitdir's exclude — the only one git reads — so this works from
+ * Idempotent: a re-`start` after finish must not double-add. `gitPath` resolves
+ * to the *common* gitdir's exclude (the only one git reads) so this works from
  * a linked worktree, whose per-worktree gitdir has no `info/`. info/exclude
  * keeps the exclusion personal machinery, never something imposed on the repo's
  * own tracked ignore file.
@@ -546,7 +562,7 @@ function addExcludes(root, patterns) {
  * Git-exclude the control plane while the artifact plane stays tracked.
  *
  * With `builds/<slug>/` tracked, only the per-worktree control files are
- * excluded — the session sentinel STATE (whose content is the active-build
+ * excluded: the session sentinel STATE (whose content is the active-build
  * cursor), the personal settings overlay, the turn ledger, and the in-flight
  * markers inside every build. Everything else under `.plumbbob/` (settings.json,
  * and each build's intent/build-log/checkpoints/report) rides the branch into
@@ -563,11 +579,11 @@ export function excludeControl(root) {
         `${DIRNAME}/builds/*/STEP`,
         `${DIRNAME}/builds/*/SEAM`,
         `${DIRNAME}/builds/*/SPIKE`,
-        // The entry stamp is in-flight control like STEP/SEAM — checkpoint's
+        // The entry stamp is in-flight control like STEP/SEAM: checkpoint's
         // stageAll must never sweep it into a step commit.
         `${DIRNAME}/builds/*/TICK`,
         // The agent-run handoff ledger is step-scoped in-flight state, not a
-        // tracked artifact — it must never ride a step commit into the PR.
+        // tracked artifact: it must never ride a step commit into the PR.
         `${DIRNAME}/builds/*/handoff.json`,
         // The checkride gate writes raw tool output to `.check/`; checkpoint's
         // stageAll must never sweep it into a step commit.
@@ -575,7 +591,7 @@ export function excludeControl(root) {
     ]);
 }
 /**
- * `start --local`: opt out of the tracked layout into a fully-untracked sidecar —
+ * `start --local`: opt out of the tracked layout into a fully untracked sidecar:
  * some team repos won't accept tool folders in-tree.
  *
  * Excludes the whole `.plumbbob/` directory.
@@ -586,7 +602,7 @@ export function excludeSidecar(root) {
 /**
  * Whether info/exclude already carries `pattern` verbatim.
  *
- * Absent or unreadable reads as "no" — the caller's job is to write it, not to
+ * Absent or unreadable reads as "no": the caller's job is to write it, not to
  * fail on a repo that has never been excluded.
  */
 function hasExclude(root, pattern) {
@@ -603,15 +619,15 @@ function hasExclude(root, pattern) {
  * Re-apply the control-plane excludes on the way into a `git add -A`.
  *
  * `start` writes them once, but a plumbbob upgraded mid-build can add a control
- * file the running session's exclude never learned — TICK, GRANT and
- * handoff.json all arrived that way — and checkpoint/finish stage with `-A`,
+ * file the running session's exclude never learned (TICK, GRANT and
+ * handoff.json all arrived that way) and checkpoint/finish stage with `-A`,
  * which would sweep the unexcluded file into the commit and ride it into the PR.
  * Idempotent, so the common path is one read and no write.
  *
- * A fully-untracked sidecar is already covered by its blanket `.plumbbob/` line;
+ * A fully untracked sidecar is already covered by its blanket `.plumbbob/` line;
  * layering the narrow patterns underneath would only add noise, so skip it. That
  * check reads info/exclude rather than the cursor because a null cursor means
- * "`--local` OR no build named" — and calling excludeSidecar on the tracked
+ * "`--local` OR no build named", and calling excludeSidecar on the tracked
  * layout would untrack the whole artifact plane.
  */
 export function refreshExcludes(root) {

package/dist/lib/templates.js

@@ -9,7 +9,7 @@ import { readFileSync } from 'node:fs';
  * Read a template by filename from the package's `templates/` directory.
  *
  * Resolved relative to the compiled module URL, so the same relative hop works
- * from `src/lib/` and `dist/lib/` alike — the templates ship with the package,
+ * from `src/lib/` and `dist/lib/` alike: the templates ship with the package,
  * never with the consumer's repo.
  */
 export function readTemplate(name) {

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;
+    }
+}