plumbbob 0.9.5 → 0.10.0

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,39 @@ 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.
+ * 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
+ * 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 +227,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 +251,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 +260,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 +276,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 +295,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 +304,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 +325,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 +362,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 +381,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 +396,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 +415,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 +437,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 +451,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 +474,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 +486,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 +502,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 +519,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 +546,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 +563,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 +575,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 +586,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 +603,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/agent.js

@@ -1,17 +1,17 @@
-// `plumbbob agent <subcommand>` — the doorway to user-authored agents: anything
+// `plumbbob agent <subcommand>`: the doorway to user-authored agents: anything
 // executable that speaks the JSON envelope contract (JSON in on stdin, JSON out
-// on stdout, prose streamed on stderr). `agent list` walks the two agent tiers —
-// the repo's tracked `.plumbbob/agents/<name>/`, then the personal
-// `~/.plumbbob/agents/<name>/` — and prints each resolvable agent. `agent run
+// on stdout, prose streamed on stderr). `agent list` walks the two agent tiers
+// (the repo's tracked `.plumbbob/agents/<name>/`, then the personal
+// `~/.plumbbob/agents/<name>/`) and prints each resolvable agent. `agent run
 // <name> [--step N] [--mode before|build|after]` composes the StepContext,
 // spawns the manifest command, streams its stderr live, captures and validates
 // the child's envelope, re-emits it on this verb's own stdout (machine) with the
 // human summary on stderr, lands `parked[]` through the build-log, and appends
-// the envelope to the handoff ledger (`builds/<slug>/handoff.json` — untracked,
+// the envelope to the handoff ledger (`builds/<slug>/handoff.json`: untracked,
 // step-scoped, cleared at checkpoint) so later runs can thread it back in.
-// There is deliberately no code path here to checkpoint, flip a step, or chain
-// agents — the subprocess boundary keeps the human as the clock by
-// construction, not by policy. A thin read-write shell: resolution,
+// No code path here can checkpoint, flip a step, or chain agents, and that
+// absence is deliberate; the subprocess boundary keeps the human as the clock
+// by construction, not by policy. A thin read-write shell: resolution,
 // composition, and spawn mechanics live in lib/agents.ts.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -50,10 +50,10 @@ function list(cwd, _args) {
  * Run one named agent, or a slot's harness-bound agents, against the step in flight.
  *
  * With a name (or `--agent` flag) it runs exactly that agent, failing loud on a
- * miss — the user who typed the name asked for it specifically. With no name it
+ * miss; the user who typed the name asked for it specifically. With no name it
  * runs whatever the build's harness.json binds to the requested slot. Either
- * way it composes the StepContext, spawns, and applies side effects — never
- * advancing the loop.
+ * way it composes the StepContext, spawns, and applies side effects (never
+ * advancing the loop).
  */
 async function run(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -72,7 +72,7 @@ async function run(cwd, args) {
         process.stderr.write('plumbbob: no step to run against — pass --step N, or `plumbbob build N` first.\n');
         return 1;
     }
-    // A `--agent <path>` flag still needs a name — it labels an explicit run (the
+    // A `--agent <path>` flag still needs a name; it labels an explicit run (the
     // handoff ledger and the human summary key on the name), it does not name one.
     if (parsed.name === undefined && parsed.flagPath !== undefined) {
         process.stderr.write('plumbbob: --agent needs an agent name too, for the run label. Try: plumbbob agent run reviewer --agent ./path --step 3.\n');
@@ -94,10 +94,10 @@ async function run(cwd, args) {
  * One agent's full run: resolve it, pick its slot, compose the StepContext, spawn, report.
  *
  * `ambient` marks a harness-bound run whose resolution or slot mismatch
- * degrades to a warning so a batch keeps going — a binding is ambient
+ * degrades to a warning so a batch keeps going; a binding is ambient
  * configuration the loop must survive without; an explicit ask
  * (`ambient: false`) fails loud on the same miss. A run that actually starts
- * and fails (non-zero exit, timeout, …) is a hard failure either way — the
+ * and fails (non-zero exit, timeout, …) is a hard failure either way: the
  * softening covers a *missing* agent, never a broken one.
  */
 async function runOne(root, slug, step, spec) {
@@ -126,17 +126,17 @@ async function runOne(root, slug, step, spec) {
         mode,
         settings: {
             // The envelope reports the `auto` setting to agents as information only.
-            // The checkpoint latch never reads it — a model can write a settings
+            // The checkpoint latch never reads it; a model can write a settings
             // file, so a standing `auto` cannot be a self-approval grant; approval
             // comes only from what the human literally typed. A `true` here informs
             // an agent, it does not self-approve.
             auto: resolveBoolean(root, 'auto', false),
             agentTimeout: resolveNumber(root, 'agentTimeout', 0),
             // Hand this agent its own config block over the envelope's existing
-            // `settings` field — no new envelope field, no new verb; the config just
+            // `settings` field: no new envelope field, no new verb; the config just
             // rides here. Resolution: settings.json's agentConfig[name], with the
             // untracked personal overlay (settings.local.json) replacing the project
-            // entry whole — no deep merge — and {} when neither defines it.
+            // entry whole (no deep merge) and {} when neither defines it.
             agent: resolveRecord(root, 'agentConfig')[spec.name] ?? {},
         },
     });
@@ -159,7 +159,7 @@ async function runOne(root, slug, step, spec) {
 /**
  * No name given: run the agents the build's harness.json binds to the requested slot.
  *
- * Bindings merge as a ladder — the per-step harness entry beats the harness
+ * Bindings merge as a ladder: the per-step harness entry beats the harness
  * `defaults`, which beat the settings-level `agents` key; the first level that
  * names the slot wins, replace not append. A missing bound agent degrades to a
  * warning; an absent harness, or one that binds nothing to this slot, is a
@@ -216,7 +216,7 @@ function degrade(ambient, hard, soft) {
  *
  * A value flag missing its value, or `--step` given a non-number, is a loud
  * error (returned as a string) rather than a silent default. An undeclared
- * `--flag` never arrives here — `run` screens argv against the verb spec in
+ * `--flag` never arrives here; `run` screens argv against the verb spec in
  * cli-core.ts and refuses before dispatch.
  */
 function parseRunArgs(args) {
@@ -254,7 +254,7 @@ function parseRunArgs(args) {
 /**
  * Resolve the slot the agent runs in.
  *
- * An explicit `--mode` must name a real slot AND one the manifest declares —
+ * An explicit `--mode` must name a real slot AND one the manifest declares;
  * an undeclared slot is refused loud, because the user asked for that exact
  * run. With no `--mode`, a single-slot agent uses its only slot; a multi-slot
  * agent must be told which one (harness bindings pick the slot from the
@@ -282,11 +282,11 @@ function resolveMode(flag, manifest) {
 /**
  * Map the run outcome to reporting and side effects.
  *
- * A failed run — non-zero exit, out-of-contract stdout, timeout, interrupt, or a
- * shell that never started — reports on stderr and stops with NO side effects:
+ * A failed run (non-zero exit, out-of-contract stdout, timeout, interrupt, or a
+ * shell that never started) reports on stderr and stops with NO side effects:
  * the envelope of a failed child is not authoritative. A clean run lands
  * `parked[]`, records the envelope in the handoff ledger, prints the human
- * summary on stderr, and re-emits the machine envelope on stdout — nothing else,
+ * summary on stderr, and re-emits the machine envelope on stdout, nothing else,
  * ever (the stream discipline: stdout carries the envelope alone).
  */
 function report(root, slug, name, mode, step, result) {
@@ -321,7 +321,7 @@ function failureLine(name, result) {
 /**
  * Land each parked concern through the build-log's Park list.
  *
- * The agent never writes .plumbbob/ itself — parked lines only reach the
+ * The agent never writes .plumbbob/ itself; parked lines only reach the
  * build-log through this verb. A build-log with no "## Park list" section, or no
  * build-log at all, warns once rather than losing the lines silently.
  */
@@ -351,7 +351,7 @@ function applyParked(root, slug, parked) {
 /**
  * The human-facing summary printed on stderr.
  *
- * A headline plus, for a halt, the route out — `blocked` unblocks and re-runs,
+ * A headline plus, for a halt, the route out: `blocked` unblocks and re-runs,
  * `drift` sends the plan to /plumbbob:refine. The machine envelope on stdout carries
  * the same status for the calling skill; this stderr copy is the terminal read.
  */

package/dist/verbs/build.js

@@ -1,9 +1,9 @@
-// `plumbbob build <n>` — enter a step: read step n's seam from intent.md and
+// `plumbbob build <n>`: enter a step: read step n's seam from intent.md and
 // write the normalized SEAM + STEP control files (flat, untracked, per-build).
-// The seam is the step's edit grant — the exact paths and `dir/` prefixes the
+// The seam is the step's edit grant: the exact paths and `dir/` prefixes the
 // step expects to touch, for orientation, never a lock. The STEP file is the
 // in-flight signal (the dashboard derives the BUILD phase from it); this verb
-// never checkpoints — only `checkpoint` commits.
+// never checkpoints; only `checkpoint` commits.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
@@ -11,7 +11,7 @@ import { parseStepSeam } from "../lib/intent.js";
 import { parseSteps } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 /**
- * Enter step n — or the next undone step — and write its SEAM/STEP markers.
+ * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
  * Refuses a missing session, a malformed step argument, an `N-M` range (a
  * `/plumbbob:build` skill feature, not a CLI one), and a seam that fails to parse.
@@ -27,13 +27,13 @@ export function build(cwd, args) {
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
     // A step range like `1-3` is a `/plumbbob:build` skill affordance (auto-approve
-    // through the range, then pause), not a CLI capability — the CLI records one
+    // through the range, then pause), not a CLI capability: the CLI records one
     // in-flight step at a time. Name it rather than bounce off the generic usage.
     if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
         process.stderr.write(`plumbbob: build takes one step number; \`${raw}\` step ranges are a \`/plumbbob:build\` feature (auto-approve through the range, then pause). Try \`plumbbob build ${raw.split('-')[0]}\`.\n`);
         return 1;
     }
-    // An explicit arg that isn't a positive integer is a usage error — caught before
+    // An explicit arg that isn't a positive integer is a usage error: caught before
     // reading intent.md so the message doesn't depend on the plan being present.
     if (raw !== undefined && (!/^\d+$/.test(raw) || Number(raw) < 1)) {
         process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n');
@@ -65,14 +65,14 @@ export function build(cwd, args) {
     writeFileSync(stepPath(root, slug), `${step}\n`);
     // Stamp the turn ledger on entry (TICK = TURN): the checkpoint latch demands
     // a human turn after this point before the step may land. Skipped when the
-    // ledger is dormant — a host with no hooks grows no TURN/TICK files.
+    // ledger is dormant: a host with no hooks grows no TURN/TICK files.
     stampTick(root, slug);
     // The wall-clock receipt starts here: checkpoint stamps landedAt, and the
     // pair becomes the step's duration in the finish report.
     stampStepStat(root, slug, step, 'startedAt', new Date().toISOString());
     // 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.
+    // 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;
     syncBuildLogState(root, slug, stepLabel(step, title));
     const picked = raw === undefined ? ' (next undone)' : '';

package/dist/verbs/check.js

@@ -1,14 +1,14 @@
-// `plumbbob check` — run the heavy gate and report, with NO state change. This
+// `plumbbob check`: run the heavy gate and report, with NO state change. This
 // is the read-only half of the verify tick: `/plumbbob:verify` runs it before the
 // pause so the human approves on a known-green check. The gate itself lives in
 // lib/check.ts: checkride (our sibling check-runner package) by default, or a
-// spawn command named by the `check` setting — resolved through the settings
-// ladder (flag → local overlay → tracked settings.json → default) — for repos
+// spawn command named by the `check` setting (resolved through the settings
+// ladder (flag → local overlay → tracked settings.json → default)) for repos
 // that gate through something else. Exits with the check's own code (0 = green,
 // 1 = red, 2 = the gate itself broke).
 //
 // Narrowing flags for the iteration loop (`check --bail --only types,lint`) map
-// straight onto checkride's run flags. Only this verb takes them — the
+// straight onto checkride's run flags. Only this verb takes them: the
 // checkpoint gate is always full-fat.
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession } from "../lib/sidecar.js";
@@ -35,7 +35,7 @@ export async function check(cwd, args = []) {
  * Only the declared flags are read here; an undeclared one never reaches this
  * function, because `run` screens argv against the verb spec in cli-core.ts and
  * refuses before dispatch. This used to tolerate unknown args on the grounds
- * that running the gate mattered more than flag hygiene — but the same tolerance
+ * that running the gate mattered more than flag hygiene, but the same tolerance
  * on the mutating verbs let `checkpoint --help` commit, so the screen is now
  * central and uniform.
  */
@@ -69,7 +69,7 @@ function slotList(args, flag) {
 /**
  * The one-line human verdict for a check exit code.
  *
- * A broken gate (exit 2) reports distinctly from red — a misconfigured harness
+ * A broken gate (exit 2) reports distinctly from red: a misconfigured harness
  * must never read as broken code, though both block a checkpoint.
  */
 function verdictLine(code) {