plumbbob 0.9.5 → 0.10.1

package/dist/verbs/doctor.js

@@ -1,34 +1,34 @@
-// `plumbbob doctor` — the health report, five sections under one verb.
+// `plumbbob doctor`: the health report, five sections under one verb.
 //
 // 1. The global plugin link (read-only). After `plumbbob init`, plumbbob lives as a
 //    symlink at ~/.claude/skills/plumbbob pointing at the installed package; Claude
 //    Code loads it in place as a plugin (skills `/plumbbob:*`, the post-edit hook from
 //    hooks.json). doctor verifies the link resolves to a package carrying the manifest,
-//    the skills, and the hook — and names the fix for anything missing. The failure
+//    the skills, and the hook, and names the fix for anything missing. The failure
 //    class it exists for is SILENT (a `/plumbbob:status` that opens an empty dashboard
 //    because the plugin never linked).
 //
 // 2. The repo sidecar layout. plumbbob keeps its per-repo state in a `.plumbbob/`
 //    sidecar: a tracked artifact plane (settings.json plus one `builds/<slug>/` folder
-//    per build — intent, build-log, checkpoints, report — that rides its branch into
+//    per build (intent, build-log, checkpoints, report) that rides its branch into
 //    the PR) and a git-excluded control plane of per-worktree files. A repo scaffolded
 //    by an older plumbbob carries the legacy FLAT sidecar instead (`.plumbbob/intent.md`,
 //    `config`, `archive/`), fully git-excluded, whose record dies with
 //    `git worktree remove`. doctor detects it and, with `--migrate`, moves it into the
 //    tracked `builds/<slug>/` layout: archive entries and the active session become
 //    build folders, `config` becomes `settings.json`, and the whole move is STAGED but
-//    never committed — the human owns that commit.
+//    never committed: the human owns that commit.
 //
 // 3. Agent validation. Every resolvable user-authored agent gets its manifest and its
 //    `command` statically checked, so a broken agent surfaces here rather than mid-build.
 //
 // 4. The check gate. When a `check` setting overrides checkride (the default heavy
 //    check), doctor names the command; otherwise it runs checkride's own doctor and
-//    prints the slot/adapter table — "detected but tool missing" is the footgun this
+//    prints the slot/adapter table: "detected but tool missing" is the footgun this
 //    exists for.
 //
 // 5. The approval latch. Reports whether the harness's turn ledger is live (checkpoint
-//    can latch on a recorded human turn) or dormant (guidance only) — dormant is a
+//    can latch on a recorded human turn) or dormant (guidance only): dormant is a
 //    state, never a failure.
 //
 // Functional, node builtins plus checkride.
@@ -44,7 +44,7 @@ import { findRepoRoot, gitPath, stagePath } from "../lib/git.js";
 import { buildDir, excludeControl, listBuilds, readTurn, setActiveBuild, sidecarDir, slugify } from "../lib/sidecar.js";
 import { resolveBoolean, resolveString, settingsPath } from "../lib/settings.js";
 /**
- * Resolve a directory shipped inside the plumbbob package (e.g. its skills/).
+ * Resolve a directory shipped inside the plumbbob package (for example its skills/).
  *
  * Resolved off this module's URL so it lands the same from src/ (dev) and
  * dist/ (published).
@@ -103,10 +103,10 @@ function buildChecks(link, pkg, shipped) {
 /**
  * The plugin-link diagnostic: how plumbbob is installed into Claude Code, as checks.
  *
- * Two install kinds are recognized: the marketplace plugin (one green line — skills
+ * Two install kinds are recognized: the marketplace plugin (one green line: skills
  * load and the CLI rides the plugin's bin/, nothing to verify piecemeal) and the
  * init-style link at ~/.claude/skills/plumbbob (verified piece by piece). Both at
- * once is a collision — two plugins named plumbbob fight over /plumbbob:* — reported
+ * once is a collision (two plugins named plumbbob fight over /plumbbob:*), reported
  * first, with the keep-one fix.
  */
 function pluginChecks() {
@@ -148,7 +148,7 @@ function subdirs(dir) {
  * Detect a legacy flat sidecar, or null when the repo is on the current layout
  * (or has no sidecar).
  *
- * `config` and `archive/` are unambiguous legacy markers — the builds/ layout has
+ * `config` and `archive/` are unambiguous legacy markers: the builds/ layout has
  * neither. A flat `intent.md` alone would also match today's `--local` layout, so it
  * only counts as legacy when the repo is NOT already migrated (no `builds/`, no
  * `settings.json`): that guard is what keeps `--local` untouched.
@@ -166,7 +166,7 @@ export function inspectLegacy(root) {
     return { config, archive, session };
 }
 /**
- * The first `# Heading` in a flat intent.md — the build title the slug derives from.
+ * The first `# Heading` in a flat intent.md: the build title the slug derives from.
  */
 function titleFromIntent(path) {
     try {
@@ -200,7 +200,7 @@ function configCheck(path) {
 /**
  * A slug not already claimed by `taken`, suffixing `-2`, `-3`, … only on collision.
  *
- * `start` refuses a colliding slug outright — the human picks a new title — but
+ * `start` refuses a colliding slug outright (the human picks a new title), but
  * migration is mechanically moving folders that already exist, so it disambiguates
  * rather than aborting mid-move.
  */
@@ -245,15 +245,18 @@ function narrowExcludes(root) {
         writeFileSync(exclude, kept.join('\n'));
     }
     catch {
-        /* no exclude yet — excludeControl creates it */
+        /* no exclude yet: excludeControl creates it */
     }
     excludeControl(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);
@@ -263,7 +266,7 @@ export function migrateSidecar(root) {
     const configPath = join(dir, 'config');
     if (existsSync(configPath)) {
         if (!existsSync(settingsPath(root))) {
-            // Carry forward ONLY what the legacy config actually held — a `check` line,
+            // Carry forward ONLY what the legacy config actually held: a `check` line,
             // nothing else. No invented `auto` (the config never had one, it defaults to
             // false, and it belongs in settings.local.json): migration yields exactly what
             // a fresh `start` would, plus the check. An empty config → an empty `{}`.
@@ -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;
 }
 /**
@@ -336,7 +341,7 @@ function sidecarReport(cwd, migrate) {
 /**
  * Interpreters recognized as the program of a manifest `command`: when the command
  * is `sh <script>` / `node <script>` / …, the checkable artifact is the script
- * argument (the interpreter reads it — the file need not carry +x), not the
+ * argument (the interpreter reads it: the file need not carry +x), not the
  * interpreter, which we trust to be on PATH.
  */
 const INTERPRETERS = new Set(['sh', 'bash', 'zsh', 'dash', 'node', 'deno', 'bun', 'python', 'python3', 'ruby', 'perl']);
@@ -344,7 +349,7 @@ const INTERPRETERS = new Set(['sh', 'bash', 'zsh', 'dash', 'node', 'deno', 'bun'
  * Expand PLUMBBOB_AGENT_DIR in a command and split it into bare tokens
  * (surrounding quotes stripped).
  *
- * A deliberately shallow split — enough for the static command check below, not a
+ * A deliberately shallow split: enough for the static command check below, not a
  * shell parser (which is neither possible nor wanted for a best-effort diagnostic).
  */
 function commandTokens(command, agentDir) {
@@ -356,11 +361,11 @@ function commandTokens(command, agentDir) {
 }
 /**
  * Statically check a manifest `command` for the silent footguns: a script file that
- * does not exist, or a directly-invoked one missing its +x bit.
+ * does not exist, or a directly invoked one missing its +x bit.
  *
  * The command is a shell string spawned via `sh -c` with the repo root as cwd, so a
  * relative path resolves against `root` and PLUMBBOB_AGENT_DIR points at the agent's
- * own dir. Best-effort by design — a path-shaped program or an interpreter's script
+ * own dir. Best-effort by design: a path-shaped program or an interpreter's script
  * argument is checked; a bare command (a PATH binary, an inline `node -e` program)
  * is trusted, because we cannot prove a shell line broken without running it.
  * Returns the problem string, or null when nothing checkable is wrong.
@@ -443,7 +448,7 @@ function agentReport(cwd) {
  *
  * A configured `check` setting names the spawn override and asks nothing more;
  * otherwise checkride's own doctor reports the slot/adapter table. Only rows
- * checkride marks `required` count as problems — an empty slot ("no tool detected")
+ * checkride marks `required` count as problems; an empty slot ("no tool detected")
  * is informational, not a failure, because the runtime gate already refuses a
  * vacuous run.
  */
@@ -474,7 +479,7 @@ async function gateReport(cwd, env) {
                 failed += 1;
         }
         // Called out where the human can see it coming: no CODE checks detected means
-        // checkpoints would be gated only by checkride's always-on repo checks — either
+        // checkpoints would be gated only by checkride's always-on repo checks: either
         // a vacuous refusal or, worse, a green that tested nothing. Informational, with
         // the exact fix; `start` surfaces the same probe at plan time.
         if (!gateDetectsTools(report.checks)) {
@@ -490,7 +495,8 @@ async function gateReport(cwd, env) {
 }
 /**
  * One slot line: `✓ types ← tsc (6.0.3)`, `✗ dead ← fallow` with its install
- * hint, or `○ spell — no tool detected` for an empty (skipping) slot.
+ * hint, or `○ spell` joined by an em dash to "no tool detected" for an empty
+ * (skipping) slot.
  */
 function toolRow(c) {
     if (c.adapter === null || c.adapter === undefined) {
@@ -507,8 +513,8 @@ function toolRow(c) {
  * The latch is `checkpoint`'s refusal to land a step until the harness has recorded
  * a human turn since the step was entered. `.plumbbob/TURN` holds a count once the
  * UserPromptSubmit hook has ticked at least once, so a present count means the latch
- * is armed — its absence means the tick is guidance-only. Dormant is a legitimate
- * state (a host with no hooks simply has no ledger), never a failure — so this
+ * is armed; its absence means the tick is guidance-only. Dormant is a legitimate
+ * state (a host with no hooks simply has no ledger), never a failure, so this
  * section adds nothing to the problem count. The dormant hint names the hook because
  * a missing ledger almost always means it never wired, and that hook rides in either
  * install kind (the marketplace plugin's hooks/hooks.json or an init-style link).
@@ -525,9 +531,9 @@ function latchReport(cwd) {
         : `  ✓ latch: live (turn ${turn})`;
     const lines = ['', 'plumbbob doctor — approval latch — D64 (approval-latch)', line];
     // The latch ignores a settings `auto`: a model can write that file, and a grant
-    // the model can forge is no grant — self-approval comes only from the human's
+    // the model can forge is no grant: self-approval comes only from the human's
     // typed `/build --auto`. Surface a set value so a human relying on it isn't
-    // silently changed — informational, never a problem.
+    // silently changed: informational, never a problem.
     if (resolveBoolean(root, 'auto', false)) {
         lines.push('  ○ auto: set in settings but not a grant since D67 (auto-not-a-grant) — self-approve per run with `/plumbbob:build --auto`');
     }

package/dist/verbs/finish.js

@@ -1,9 +1,9 @@
-// `plumbbob finish` — the close-out. It appends the checkpoint SHAs and per-step
+// `plumbbob finish`: the close-out. It appends the checkpoint SHAs and per-step
 // stats to report.md, makes the final commit, and clears the control state (the
 // untracked session and step markers under `.plumbbob/`). The build folder is NOT
-// deleted — the tracked `.plumbbob/builds/<slug>/` folder IS the archive: it
+// deleted; the tracked `.plumbbob/builds/<slug>/` folder IS the archive: it
 // merges with the branch and shows up in the PR, so nothing is copied into a
-// separate local archive. A missing report never blocks the exit — guidance
+// separate local archive. A missing report never blocks the exit: guidance
 // offers the artifact, it does not wall the door. The git footprint stays
 // additive: one forward commit under the Conventional `chore(<scope>): finish`
 // subject, with the `plumbbob finish` identifier riding a marker line at the head
@@ -11,6 +11,7 @@
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
+import { readCommitBody } from "../lib/commitbody.js";
 import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, refreshExcludes, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 import { parseBuildScope } from "../lib/intent.js";
@@ -19,7 +20,7 @@ import { parseBuildScope } from "../lib/intent.js";
  *
  * Requires an active session (the `.plumbbob/STATE` sentinel). When report.md
  * exists it gains a `## Checkpoints` SHA list and a `## Stats` table first; when
- * it doesn't, finish notes the absence and proceeds — the exit is never gated on
+ * it doesn't, finish notes the absence and proceeds; the exit is never gated on
  * a report.
  */
 export function finish(cwd, args = []) {
@@ -28,6 +29,15 @@ export function finish(cwd, args = []) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
+    // Checked before any of finish's writes: appendCheckpointShas/appendStats
+    // are plain appends, not idempotent, so a refusal after they ran would
+    // duplicate those sections on retry. A socket stdin can never deliver the
+    // requested body, so there is nothing to do first.
+    const bodyResult = readCommitBody(args);
+    if (!bodyResult.ok) {
+        process.stderr.write(bodyResult.message);
+        return 1;
+    }
     const { build: slug } = resolveBuild(root, args);
     if (existsSync(reportPath(root, slug))) {
         appendCheckpointShas(root, slug);
@@ -37,9 +47,9 @@ export function finish(cwd, args = []) {
         process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
             '(/plumbbob:finish normally writes the report first). No gate — D9 (finish-no-gate).\n');
     }
-    // The final commit: stage the report just written plus the build folder's tail —
-    // a step's commit sweeps its own bookkeeping along with the work, so the last
-    // step's `checkpoints` line lands one commit late and finish absorbs it — and
+    // The final commit: stage the report just written plus the build folder's tail
+    // (a step's commit sweeps its own bookkeeping along with the work, so the last
+    // step's `checkpoints` line lands one commit late and finish absorbs it) and
     // commit under the `finish` subject. `--allow-empty` (via `commit`) still marks
     // the narrative endpoint when the tree is already clean, or under `--local`,
     // where the whole sidecar is git-excluded and there is nothing tracked to stage.
@@ -47,18 +57,18 @@ export function finish(cwd, args = []) {
     if (isDirty(root)) {
         stageAll(root);
     }
-    const sha = commit(root, subject(root, slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
+    const sha = commit(root, subject(root, slug), withMarker('plumbbob finish', bodyResult.body ?? undefined));
     // Clear the control state: the in-flight markers first, then the session
     // sentinel last (so "no session" flips exactly at the end). Deleting STATE also
-    // drops the active-build cursor — cursor and session share that one file, so a
-    // single delete does both. The tracked artifacts stay in place — only the
+    // drops the active-build cursor: cursor and session share that one file, so a
+    // single delete does both. The tracked artifacts stay in place; only the
     // ephemera go.
     rmSync(seamPath(root, slug), { force: true });
     rmSync(stepPath(root, slug), { force: true });
     rmSync(spikePath(root, slug), { force: true });
     // The checkpoint latch's per-build entry stamp and the one-turn self-approval
     // grant go with the session: a grant lives one turn by construction, but only
-    // because every tick rewrites it — the session's last tick was the last rewrite,
+    // because every tick rewrites it: the session's last tick was the last rewrite,
     // so left behind, a stale `auto` could self-approve the next session's first
     // landing.
     clearTick(root, slug);
@@ -74,7 +84,7 @@ export function finish(cwd, args = []) {
  *
  * The scope resolves through the same build-default fallback chain as the plan
  * and step subjects: the intent.md `**Scope:**` header field, else the build
- * slug, else bare (e.g. `--local`). The `plumbbob finish` identifier rides the
+ * slug, else bare (for example `--local`). The `plumbbob finish` identifier rides the
  * body marker, not the subject.
  */
 function subject(root, slug) {
@@ -83,7 +93,7 @@ function subject(root, slug) {
 /**
  * Resolve the commit scope: the intent.md `**Scope:**` header, else the slug.
  *
- * Twin of checkpoint.ts's helper — same fallback chain, but with this verb's own
+ * Twin of checkpoint.ts's helper: same fallback chain, but with this verb's own
  * `slug` resolution instead of the active-build cursor.
  */
 function buildDefaultScope(root, slug) {
@@ -94,38 +104,15 @@ function buildDefaultScope(root, slug) {
         }
     }
     catch {
-        // no intent.md — fall through to the slug rung.
+        // no intent.md: fall through to the slug rung.
     }
     return buildScope(slug);
 }
-/**
- * Read the `--body` final-commit body from stdin, or null.
- *
- * The body arrives as a single-quoted stdin heredoc — the CLI owns every commit
- * subject, but the finish skill composes a proportional close-out body this
- * way. Returns null when the flag is absent or stdin is empty; the commit then
- * carries subject only. Reading fd 0 blocks until EOF, which the heredoc
- * supplies; a read error (no stdin attached) degrades to null, and an
- * interactive TTY — which would never send EOF — skips the read instead of
- * hanging (twin of checkpoint.ts's guard).
- */
-function bodyArg(args) {
-    if (!args.includes('--body') || process.stdin.isTTY === true) {
-        return null;
-    }
-    try {
-        const raw = readFileSync(0, 'utf8').trimEnd();
-        return raw.length > 0 ? raw : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Roll the per-step receipts into report.md as a `## Stats` table.
  *
- * One row per step plus totals — red checks, drift warnings, reverts,
- * wall-clock — so "is the loop worth it?" is a table, not a feeling. Silently
+ * One row per step plus totals (red checks, drift warnings, reverts,
+ * wall-clock) so "is the loop worth it?" is a table, not a feeling. Silently
  * skipped when nothing accrued (a build with no red/revert/drift and no
  * `build <n>` stamps has nothing to say).
  */
@@ -173,7 +160,7 @@ function wallClockMs(s) {
 /**
  * Format a wall-clock duration for the stats table.
  *
- * `—` when unknown (a hand-built step never ran `build <n>`, so it has no
+ * An em dash when unknown (a hand-built step never ran `build <n>`, so it has no
  * startedAt), `<1m` under a minute, whole minutes otherwise.
  */
 function formatWall(ms) {

package/dist/verbs/handoff.js

@@ -1,8 +1,8 @@
-// `plumbbob handoff` — print the standardized build hand-off block: the
+// `plumbbob handoff`: print the standardized build hand-off block: the
 // "state / choice / what's next" the human sees at each step boundary. Read-only,
-// no state change. It derives the moment from the session — a step in flight ⇒ the
+// no state change. It derives the moment from the session: a step in flight ⇒ the
 // pause block (built → looks-good/needs-work → next), none ⇒ the post-checkpoint
-// boundary block — and renders the next undone step plus its advisory `- model:`
+// boundary block, and renders the next undone step plus its advisory `- model:`
 // recommendation straight from intent.md, the build's plan document. Owning the
 // block here, rather than as prose in the build skill, keeps the skill from
 // drifting out of sync with `status`, which renders the same next-step detail
@@ -75,7 +75,7 @@ function boundaryBlock(step, title, nextUp) {
  * The forward pointer, shared by both blocks: the next undone step, its title,
  * and its advisory `- model:` recommendation.
  *
- * The recommendation renders as just the model token for the `/model` call —
+ * The recommendation renders as just the model token for the `/model` call;
  * the full rationale lives on the `status` dashboard. No next step ⇒ the
  * finish/step nudge instead.
  */
@@ -101,8 +101,9 @@ function titleOf(steps, n) {
     return steps.find((s) => s.n === n)?.title ?? null;
 }
 /**
- * The model token from a `- model:` recommendation — the first word, so a
- * `model: opus — <rationale>` line yields `opus` for the `/model` call.
+ * The model token from a `- model:` recommendation: the first word, so a
+ * `model: opus` line followed by an em dash and rationale yields `opus` for
+ * the `/model` call.
  *
  * Null when there is no recommendation, or it degraded to whitespace (folding
  * the null model into the same guard keeps both branches live).
@@ -112,7 +113,7 @@ function modelToken(model) {
     return first !== undefined && first.length > 0 ? first : null;
 }
 /**
- * Read a file as UTF-8, or return '' when it is missing or unreadable — an
+ * Read a file as UTF-8, or return '' when it is missing or unreadable: an
  * absent sidecar file reads as empty rather than throwing.
  */
 function readOr(path) {
@@ -124,7 +125,7 @@ function readOr(path) {
     }
 }
 /**
- * The in-flight step number from the STEP marker — the flat one-line file in
+ * The in-flight step number from the STEP marker: the flat one-line file in
  * the build folder that records which step is open. Null when no step is in
  * flight or the file holds anything but a bare number.
  */

package/dist/verbs/init.js

@@ -1,7 +1,7 @@
-// `plumbbob init [--uninstall] [--force]` — link plumbbob into Claude Code as an
+// `plumbbob init [--uninstall] [--force]`: link plumbbob into Claude Code as an
 // in-place skills-directory plugin. It symlinks the installed package into
-// ~/.claude/skills/plumbbob, where Claude Code discovers it as `plumbbob@skills-dir`
-// — the skills load namespaced (`/plumbbob:*`) and the post-edit hook auto-registers
+// ~/.claude/skills/plumbbob, where Claude Code discovers it as `plumbbob@skills-dir`:
+// the skills load namespaced (`/plumbbob:*`) and the post-edit hook auto-registers
 // from hooks/hooks.json. This non-marketplace install path is first-class by design:
 // it serves an `npm i -g` global, local dev, and clients predating plugins, and it
 // keeps plumbbob usable as a standalone CLI outside any one host rather than
@@ -10,9 +10,9 @@
 // via bin/, so it needs neither `npm i -g` nor `init`). The two are mutually
 // exclusive: both register a plugin named `plumbbob`, and a double-install collides
 // over the /plumbbob:* namespace (skills can drop to flat `/status` names). So init
-// REFUSES when a marketplace plumbbob is already installed — `--force` overrides
+// REFUSES when a marketplace plumbbob is already installed: `--force` overrides
 // (the dev-install path uses it). Global-only by design: install scope is NOT session
-// scope — sessions stay per-project via `plumbbob start`. Idempotent + reversible
+// scope: sessions stay per-project via `plumbbob start`. Idempotent + reversible
 // (`--uninstall` drops the link); it NEVER writes settings.json. Node builtins only.
 import { lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { marketplacePlumbbob } from "../lib/plugins.js";
 /**
- * The installed package root — parent of .claude-plugin/, skills/, hooks/, dist/.
+ * The installed package root: parent of .claude-plugin/, skills/, hooks/, dist/.
  *
  * Derived from this module's URL: the global install when run as the published
  * bin, the checkout in dev. No trailing slash, so it compares clean against a
@@ -64,8 +64,8 @@ function symlinkTarget(path) {
 /**
  * Link the installed package into ~/.claude/skills/plumbbob, or `--uninstall` it.
  *
- * Refuses when a marketplace plumbbob plugin is already installed — two plugins
- * named `plumbbob` collide over the /plumbbob:* namespace — unless `--force`.
+ * Refuses when a marketplace plumbbob plugin is already installed (two plugins
+ * named `plumbbob` collide over the /plumbbob:* namespace) unless `--force`.
  * Repoints a stale link from an earlier install location; already-linked is a
  * clean exit 0.
  */
@@ -95,7 +95,7 @@ export function init(args) {
             process.stdout.write(`plumbbob: already linked (${link} → ${target}). Nothing to do.\n`);
             return 0;
         }
-        rmSync(link); // a stale link from an earlier install location — repoint it
+        rmSync(link); // a stale link from an earlier install location: repoint it
     }
     symlinkSync(target, link);
     process.stdout.write(`plumbbob: linked ${link} → ${target}.\n` +

package/dist/verbs/park.js

@@ -1,6 +1,6 @@
-// `plumbbob park "<text>"` — the raw capture path for a thought you don't want
+// `plumbbob park "<text>"`: the raw capture path for a thought you don't want
 // to chase mid-step: append one flat line under the "## Park list" section of
-// build-log.md (the build's human-facing ledger). Capture stays dumb by design —
+// build-log.md (the build's human-facing ledger). Capture stays dumb by design:
 // a grep-readable append, no markdown parsing, no model turn (wording the line
 // well is /plumbbob:park's job); triage waits for a step boundary, via harvest.
 // Capture is not a state transition, so it runs in any context (terminal or
@@ -14,7 +14,7 @@ import { appendToSection } from "../lib/buildlog.js";
  *
  * All non-flag args join into a single line. Refuses when there is no active
  * session, when the text is empty, or when build-log.md lacks a "## Park list"
- * section — a park line must never vanish silently.
+ * section: a park line must never vanish silently.
  */
 export function park(cwd, args) {
     const root = findRepoRoot(cwd);

package/dist/verbs/recover.js

@@ -1,8 +1,8 @@
-// `plumbbob recover` — read the control plane and say, plainly, whether it is
+// `plumbbob recover`: read the control plane and say, plainly, whether it is
 // telling the truth. Nothing else reads these files as a set: `doctor` checks
 // the install and the gate, `status` reports what the markers claim without
 // questioning them. So a session that crashed, lost its context window, or was
-// switched away mid-step can sit in a state no verb detects — the worst being a
+// switched away mid-step can sit in a state no verb detects: the worst being a
 // cursor pointing at a build that no longer exists, which renders a perfectly
 // plausible empty dashboard instead of an error.
 //
@@ -10,7 +10,7 @@
 // `doctor --migrate` takes. What `--fix` may touch is deliberately narrow: only
 // the untracked control files this tool owns and can rewrite from what it
 // already knows. It never touches a tracked artifact (intent, build-log,
-// checkpoints, reports), never touches git, and never advances the loop — a
+// checkpoints, reports), never touches git, and never advances the loop: a
 // recovery verb that could land a step would be a second, quieter checkpoint.
 //
 // Spike leftovers are reported and never removed: those worktrees live outside
@@ -26,7 +26,7 @@ import { spikeBranches, spikeWorktrees } from "./spike.js";
  * ones that can be repaired without judgment.
  *
  * Exits 0 when the control plane is consistent (or when every problem found was
- * fixed), 1 while any problem is still standing — so a scripted caller can tell
+ * fixed), 1 while any problem is still standing, so a scripted caller can tell
  * "clean" from "you still have to look at this".
  */
 export function recover(cwd, args) {
@@ -75,7 +75,7 @@ function summary(standing, fixable, fix) {
  * Everything that depends on there being a session: the cursor, the phase
  * markers, and the per-build control files.
  *
- * With no session there is no control plane to be wrong about — only the spike
+ * With no session there is no control plane to be wrong about: only the spike
  * leftovers, which outlive `finish` and are checked separately.
  */
 function sessionFindings(root) {
@@ -101,7 +101,7 @@ function sessionFindings(root) {
  *
  * This is the quiet one: `status` takes the cursor at its word, so every read
  * comes back empty and the dashboard renders as a fresh, untouched build rather
- * than an error. Repairable only when exactly one real build remains — with
+ * than an error. Repairable only when exactly one real build remains; with
  * several, which one you meant is a judgment call.
  */
 function cursorFinding(root, slug) {
@@ -128,7 +128,7 @@ function cursorFinding(root, slug) {
  * Contradictions in what phase the build claims to be in.
  *
  * Phase is derived from the markers rather than stored, so two markers at once
- * is not an impossible state — it is an unreadable one, and `status` resolves
+ * is not an impossible state; it is an unreadable one, and `status` resolves
  * it by showing the spike and hiding the step entirely.
  */
 function phaseFindings(root, slug, stepInFlight) {
@@ -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',
             });
         }
     }
@@ -175,7 +175,7 @@ function phaseFindings(root, slug, stepInFlight) {
  */
 function leftoverFindings(root, slug, stepInFlight) {
     const findings = [];
-    // The handoff ledger is step-scoped and cleared by `checkpoint` alone — a
+    // The handoff ledger is step-scoped and cleared by `checkpoint` alone; a
     // revert or an abandoned step leaves it for the next step to inherit.
     const handoffs = handoffCount(root, slug);
     if (!stepInFlight && handoffs > 0) {
@@ -209,7 +209,7 @@ function leftoverFindings(root, slug, stepInFlight) {
     else {
         findings.push({ name: 'latch tick', ok: true, detail: stepInFlight ? 'stamped for the step in flight' : 'clear' });
     }
-    // GRANT is rewritten on every turn tick, so it self-clears — but only while
+    // GRANT is rewritten on every turn tick, so it self-clears, but only while
     // the hook runs. Without a TURN ledger nothing will ever clear it, and the
     // latch reads a standing grant as self-approval.
     if (existsSync(grantPath(root)) && readTurn(root) === null) {
@@ -276,7 +276,7 @@ function handoffCount(root, slug) {
     }
 }
 /**
- * A control marker's trimmed content, or '?' when it cannot be read — a marker
+ * A control marker's trimmed content, or '?' when it cannot be read: a marker
  * exists to be reported on, so an unreadable one must not throw mid-report.
  */
 function readMarker(path) {
@@ -284,7 +284,7 @@ function readMarker(path) {
     return raw.length > 0 ? raw : '?';
 }
 /**
- * File content, or '' when absent — recover reads state that may be missing by
+ * File content, or '' when absent: recover reads state that may be missing by
  * definition, so every read degrades rather than throws.
  */
 function readOr(path) {