plumbbob 0.9.5 → 0.10.1

package/dist/verbs/revert.js

@@ -1,18 +1,18 @@
-// `plumbbob revert [--to n]` — git reset --hard to a checkpoint SHA (the most
+// `plumbbob revert [--to n]`: git reset --hard to a checkpoint SHA (the most
 // recent step, or `--to n`, with the baseline as fallback), then remove untracked
 // files under the SEAM only (the seam is the in-flight step's flat list of
-// granted edit paths). The artifact plane — the tracked `.plumbbob/builds/<slug>/`
-// folder holding intent, build-log, checkpoints, and park lines — would not
+// granted edit paths). The artifact plane (the tracked `.plumbbob/builds/<slug>/`
+// folder holding intent, build-log, checkpoints, and park lines) would not
 // survive a bare reset: it would discard park lines and intent edits, or, when
 // reverting to a baseline that predates the build folder, delete the folder
 // wholesale. So revert snapshots the sidecar to temp and restores it as
-// uncommitted changes after the reset — a rewind must never destroy recorded
+// uncommitted changes after the reset: a rewind must never destroy recorded
 // work, in either case. The untracked cleanup additionally whitelists the
 // artifact plane, so no seam pattern can ever sweep away a build's own files.
 //
 // Plumbbob also installs its driver skills INTO the repo (.claude/skills/<driver>/
 // for a self-contained install), so a blunt reset would discard an out-of-seam
-// skill edit — or a `pnpm up plumbbob` re-setup — together with the half-done
+// skill edit (or a `pnpm up plumbbob` re-setup) together with the half-done
 // step. revert discards the step's WORK, never plumbbob's own machinery, so those
 // paths are carried across the reset unchanged.
 import { cpSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
@@ -66,7 +66,7 @@ export function revert(cwd, args) {
     const seam = readSeamTokens(root, slug);
     const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam) && !isArtifactPath(p));
     // A revert against an in-flight step is a datapoint the finish report's stats
-    // table wants — read the STEP marker before it goes, bump the counter after
+    // table wants: read the STEP marker before it goes, bump the counter after
     // the reset (the sidecar is preserved through it, so the write survives).
     const inFlight = readInFlightStep(root, slug);
     resetPreserving(root, sha, plumbbobOwnedPaths(root));
@@ -79,7 +79,7 @@ export function revert(cwd, args) {
         bumpStepStat(root, slug, inFlight, 'reverts');
     }
     // The step is abandoned: the build-log's Current-step line returns to the
-    // boundary and its Steps mirror re-renders from the preserved intent.md —
+    // boundary and its Steps mirror re-renders from the preserved intent.md:
     // revert keeps intent edits, so intent's checkboxes stay the truth to reflect.
     // Best-effort, like every build-log write.
     syncBuildLogState(root, slug, AT_BOUNDARY);
@@ -94,8 +94,8 @@ export function revert(cwd, args) {
  * under .claude/skills/, named from plumbbob's own bundled `skills/` dir.
  *
  * The match is by name alone, and since the skills dropped their `pb-` prefix
- * those names are ordinary words — a user's own `.claude/skills/plan/` is
- * carried across the reset too. That errs toward keeping work — never destroy —
+ * those names are ordinary words; a user's own `.claude/skills/plan/` is
+ * carried across the reset too. That errs toward keeping work (never destroy),
  * so it is the safe direction to be wrong in. Only paths that currently exist are returned.
  */
 function plumbbobOwnedPaths(root) {
@@ -106,7 +106,7 @@ function plumbbobOwnedPaths(root) {
         }
     }
     catch {
-        // Bundled skills dir not resolvable (unexpected) — protect just the sidecar.
+        // Bundled skills dir not resolvable (unexpected): protect just the sidecar.
     }
     return paths.filter((p) => existsSync(p));
 }
@@ -146,7 +146,7 @@ function parseTo(args) {
 /**
  * Parse the build's CHECKPOINTS record into a baseline sha and per-step shas.
  *
- * A missing or unreadable file yields an empty record — the caller then refuses
+ * A missing or unreadable file yields an empty record: the caller then refuses
  * with its own message rather than crashing here.
  */
 function readCheckpoints(root, slug) {
@@ -173,7 +173,7 @@ function readCheckpoints(root, slug) {
     return { baseline, steps };
 }
 /**
- * Read the in-flight step's seam — its edit-grant paths, one per line.
+ * Read the in-flight step's seam: its edit-grant paths, one per line.
  *
  * A missing or unreadable SEAM contributes nothing: no tokens, never an error.
  */

package/dist/verbs/spike.js

@@ -1,15 +1,15 @@
-// `plumbbob spike` — the spike lifecycle for a genuine fork the design phase
+// `plumbbob spike`: the spike lifecycle for a genuine fork the design phase
 // couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree and a
 // `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default options
-// a/b) and drops the SPIKE marker — one of the untracked per-build control files
+// a/b) and drops the SPIKE marker: one of the untracked per-build control files
 // under `.plumbbob/` that record what's in flight. The main tree stays put while
 // you experiment in the worktrees, which are hook-dormant by construction: the
 // untracked control files don't exist in a fresh checkout, so the hooks find no
 // STATE (the session sentinel) there. `spike done` removes every spike worktree
 // and branch and clears the marker.
 //
-// Every spike also leaves a durable report — `spike-NN-<slug>.md` beside
-// intent.md in the tracked `builds/<slug>/` folder — so the verdict rides the
+// Every spike also leaves a durable report (`spike-NN-<slug>.md` beside
+// intent.md in the tracked `builds/<slug>/` folder) so the verdict rides the
 // branch into the PR instead of evaporating with the throwaway worktrees.
 //
 // Worktree git calls run directly here rather than via lib/git.ts (which holds the
@@ -21,15 +21,15 @@ import { basename, dirname, join, relative } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
 import { buildFolder, clearSpike, hasSession, inSpike, listSpikeReports, markSpike, nextSpikeReportPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { readTemplate, stampTemplate } from "../lib/templates.js";
-// Worktree/branch names when the caller lists none — a fork defaults to two arms.
+// Worktree/branch names when the caller lists none: a fork defaults to two arms.
 const DEFAULT_OPTIONS = ['a', 'b'];
 /**
- * The verbatim Verdict placeholder from templates/spike-report.md — its presence
+ * The verbatim Verdict placeholder from templates/spike-report.md: its presence
  * means the spike's call was never recorded, which `spike done` nudges on.
  */
 const VERDICT_PLACEHOLDER = '*(viable | not viable | partial';
 /**
- * Entry point for `plumbbob spike` — dispatches to open, `report`, or `done`.
+ * Entry point for `plumbbob spike`: dispatches to open, `report`, or `done`.
  *
  * Requires an active session (the STATE sentinel) and resolves which build the
  * spike belongs to before dispatching.
@@ -51,11 +51,11 @@ export function spike(cwd, args) {
     return spikeStart(root, buildSlug, positionals);
 }
 /**
- * `spike report "<slug>"` — scaffold a spike report WITHOUT worktrees.
+ * `spike report "<slug>"`: scaffold a spike report WITHOUT worktrees.
  *
  * Serves the spike-as-step case: a planned step titled `spike: …`, where the
  * increment itself is the experiment. No boundary requirement and no SPIKE
- * marker — a step in flight is exactly when this runs. Provenance is stamped
+ * marker: a step in flight is exactly when this runs. Provenance is stamped
  * `step <n>` when a step is in flight, else `/plumbbob:spike`.
  */
 function spikeReport(root, buildSlug, positionals) {
@@ -75,7 +75,7 @@ function spikeReport(root, buildSlug, positionals) {
  * Write a fresh spike report from the template at the next free
  * `spike-NN-<slug>.md` in the build folder, and return its path.
  *
- * Shared by the worktree-opening spike and the spike-as-step `spike report` —
+ * Shared by the worktree-opening spike and the spike-as-step `spike report`:
  * one artifact, two entry points. The CLI owns the numbering; the human never
  * creates or numbers a report.
  */
@@ -86,7 +86,7 @@ function scaffoldSpikeReport(root, buildSlug, spikeSlug, via) {
     return path;
 }
 /**
- * The build's in-flight step number, or null — reads the STEP marker `build`
+ * The build's in-flight step number, or null: reads the STEP marker `build`
  * writes.
  *
  * Used to stamp a spike-as-step report's provenance as `step <n>`.
@@ -103,10 +103,10 @@ function readInFlightStep(root, buildSlug) {
 /**
  * Open a spike: one throwaway worktree + `spike/<slug>-<opt>` branch per option.
  *
- * Refuses when a spike is already open or a step is in flight — a spike is a
- * deliberate fork from a settled boundary, so the current step must checkpoint
- * or revert first. Marks the SPIKE control file and scaffolds the report before
- * returning.
+ * Refuses when a spike is already open or a step is in flight: a spike is a
+ * deliberate fork from a settled boundary, so the current step must exit first
+ * (checkpoint, abandon, or revert). Marks the SPIKE control file and scaffolds
+ * the report before returning.
  */
 function spikeStart(root, buildSlug, positionals) {
     if (inSpike(root, buildSlug)) {
@@ -115,7 +115,7 @@ function spikeStart(root, buildSlug, positionals) {
     }
     if (existsSync(stepPath(root, buildSlug))) {
         process.stderr.write('plumbbob: spike starts from a settled boundary, but a step is in flight. ' +
-            'A spike is a deliberate fork — checkpoint or revert the current step first.\n');
+            'A spike is a deliberate fork — checkpoint, abandon, or revert the current step first.\n');
         return 1;
     }
     const slug = sanitize(positionals[0] ?? '');
@@ -147,7 +147,7 @@ function spikeStart(root, buildSlug, positionals) {
 /**
  * Close the spike: remove every spike worktree and branch, clear the marker.
  *
- * Nudges — but never refuses — when a report's Verdict is still the template
+ * Nudges (but never refuses) when a report's Verdict is still the template
  * placeholder: guidance, not a gate.
  */
 function spikeDone(root, buildSlug) {
@@ -156,7 +156,7 @@ function spikeDone(root, buildSlug) {
         return 1;
     }
     // Check for an unrecorded verdict BEFORE teardown. The reports live in the
-    // build folder, not the spike worktrees, so they survive the removal — but the
+    // build folder, not the spike worktrees, so they survive the removal, but the
     // learning that fills them does not, so this is the moment to nudge.
     const unfilled = spikeReportsMissingVerdict(root, buildSlug);
     for (const path of spikeWorktrees(root)) {
@@ -181,7 +181,7 @@ function spikeDone(root, buildSlug) {
 }
 /**
  * The spike-report filenames in the build folder whose Verdict is still the
- * template placeholder — the ones `spike done` nudges on.
+ * template placeholder: the ones `spike done` nudges on.
  *
  * Best-effort per file: an unreadable report is skipped rather than blocking
  * the close.
@@ -198,7 +198,7 @@ function spikeReportsMissingVerdict(root, buildSlug) {
     });
 }
 /**
- * Worktree paths whose checked-out branch is under spike/ — parsed from the
+ * Worktree paths whose checked-out branch is under spike/: parsed from the
  * porcelain output (blank-line-separated `worktree <path>` / `branch <ref>`
  * blocks).
  *
@@ -230,7 +230,7 @@ export function spikeBranches(root) {
     return out.length === 0 ? [] : out.split('\n').filter((b) => b.length > 0);
 }
 /**
- * Slugify a raw spike name — lowercase, non-alphanumerics collapsed to dashes.
+ * Slugify a raw spike name: lowercase, non-alphanumerics collapsed to dashes.
  */
 function sanitize(raw) {
     return raw

package/dist/verbs/start.js

@@ -1,4 +1,4 @@
-// `plumbbob start "<title>"` — open a session: scaffold the sidecar (the
+// `plumbbob start "<title>"`: open a session: scaffold the sidecar (the
 // `.plumbbob/` tree of build artifacts and control files), record the baseline
 // commit, and point the session at a new build. Refuses on a dirty tree (a
 // clean baseline is the contract; `--allow-dirty` overrides), an existing
@@ -7,7 +7,7 @@ import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { detectGate } from "../lib/check.js";
 import { readTemplate, stampTemplate } from "../lib/templates.js";
-import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
+import { findRepoRoot, hasCommit, headSha, isDirty, isIgnored } from "../lib/git.js";
 import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
 import { settingsPath } from "../lib/settings.js";
 /**
@@ -15,7 +15,7 @@ import { settingsPath } from "../lib/settings.js";
  * {{CHECK}} line.
  *
  * The gate is checkride unless a `check` setting overrides it, so settings.json
- * seeds with no `check` key at all — absence IS the default; this line says
+ * seeds with no `check` key at all; absence IS the default; this line says
  * that in prose where the templates need it.
  */
 const CHECK_ECHO = 'checkride (set a "check" key in .plumbbob/settings.json to override)';
@@ -71,13 +71,13 @@ export async function start(cwd, args) {
     }
     const sha = headSha(root);
     mkdirSync(sidecarDir(root), { recursive: true });
-    // beginSession writes STATE — one file that is both the session sentinel (its
+    // beginSession writes STATE: one file that is both the session sentinel (its
     // existence means a session is live) and the active-build cursor (its single
-    // line names the build every verb acts on). Point it at this build — null
+    // line names the build every verb acts on). Point it at this build: null
     // under --local, which has no cursor. The cursor lives in STATE, not
     // settings.local.json, so that personal overlay stays purely human-owned.
     beginSession(root, local ? null : slug);
-    // Scaffold the tracked settings.json ONLY when absent, and seed it EMPTY — the
+    // Scaffold the tracked settings.json ONLY when absent, and seed it EMPTY: the
     // human owns this file once it exists (their `check` gate lives here), so a
     // re-start must never touch it. Inject no opinions even on first create:
     // absence of `check` already means checkride and absence of `auto` already
@@ -87,11 +87,11 @@ export async function start(cwd, args) {
     if (!existsSync(settingsPath(root))) {
         writeFileSync(settingsPath(root), `${JSON.stringify({}, null, 2)}\n`);
     }
-    // `--local` keeps a fully-untracked flat layout (the whole `.plumbbob/`
-    // git-excluded); the default plants a tracked `builds/<slug>/` folder — the
-    // build's record (intent, build-log, checkpoints) rides its branch into the
-    // PR — and git-excludes only the per-worktree control files. The slug is
-    // date-prefixed when derived (see datedSlug) and validated unique above —
+    // `--local` keeps a fully untracked flat layout (the whole `.plumbbob/`
+    // git-excluded); the default plants a tracked `builds/<slug>/` folder (the
+    // build's record [intent, build-log, checkpoints] rides its branch into the
+    // PR) and git-excludes only the per-worktree control files. The slug is
+    // date-prefixed when derived (see datedSlug) and validated unique above;
     // the CLI refuses a collision, never auto-suffixes.
     let intentLocation;
     if (local) {
@@ -112,18 +112,32 @@ export async function start(cwd, args) {
     }
     // The plan's entry stamp for the checkpoint latch: set TICK to the current
     // TURN, so `checkpoint --plan` only lands once the harness ledger records a
-    // human turn after this moment. Skipped when TURN is absent — a hookless host
+    // human turn after this moment. Skipped when TURN is absent: a hookless host
     // grows no ledger and the latch stays dormant, which also covers a first
     // session where the hook has never ticked; that one plan commit stays
     // guidance-governed. Any GRANT file lying around predates this session (a
-    // legitimate one is minted by a `/build` prompt, which never runs `start`)
-    // — clear it so a stale grant can't self-approve this session's plan; a
+    // legitimate one is minted by a `/build` prompt, which never runs `start`);
+    // clear it so a stale grant can't self-approve this session's plan; a
     // grant's lifetime is one turn.
     setGrant(root, null);
     stampTick(root, local ? null : slug);
     process.stdout.write(`plumbbob: started "${title}" — baseline ${sha.slice(0, 9)}. Frame and decide in ${intentLocation}; \`build\` a step once the decisions are made.\n`);
+    // The tracked layout plants `builds/<slug>/` to ride the branch into the PR,
+    // but a repo whose own `.gitignore` excludes `.plumbbob/` overrides that, and
+    // an explicit `git add` of an ignored folder is a hard error. Detect it here,
+    // once, so the record-only mode (plan/finish commits land empty; their bodies
+    // carry the record, the files stay untracked) is a known mode from the start
+    // rather than a surprise at the first `checkpoint --plan`. `--local` already
+    // excludes the whole sidecar by design and says so, so skip the probe there.
+    // Guidance only, and the session is already open: a probe hiccup stays silent
+    // rather than half-crashing a scaffolded session.
+    if (!local && sidecarIsIgnored(root, slug)) {
+        process.stderr.write('plumbbob: heads-up — this repo gitignores .plumbbob/, so the tracked build folder cannot ride the branch.\n' +
+            '  Plan and finish commits will be record-only (empty commits; the plan and report ride the commit message).\n' +
+            '  To keep the record in-tree, unignore .plumbbob/builds/ (or the whole sidecar) before the first checkpoint.\n');
+    }
     // The plan-time gate probe: if checkride sees no code checks here, say so
-    // NOW — while the human is still deciding — instead of at the first
+    // NOW (while the human is still deciding) instead of at the first
     // checkpoint, where the gate either refuses a vacuous run or, worse, greens
     // on the always-on repo checks alone. Guidance only: it never changes the
     // exit code, and a configured `check` or a probe hiccup stays silent.
@@ -139,8 +153,8 @@ export async function start(cwd, args) {
  * Derive a `YYYY-MM-DD-<slug>` build slug from the title (local time).
  *
  * The date prefix makes `builds/` sort chronologically under `listBuilds`'
- * plain lexical sort — ordering by construction, not by titling convention. An
- * explicit `--slug` bypasses this and stays verbatim — the CLI never rewrites
+ * plain lexical sort: ordering by construction, not by titling convention. An
+ * explicit `--slug` bypasses this and stays verbatim: the CLI never rewrites
  * what the caller chose. An untitleable title yields `''` so the empty-slug
  * guard fires instead of minting a date-only slug.
  */
@@ -153,7 +167,23 @@ function datedSlug(title) {
     return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${base}`;
 }
 /**
- * Read the value that follows a `--flag` in argv (e.g. `--slug my-build`), or
+ * Whether the tracked build folder is gitignored: the record-only heads-up's
+ * predicate, probing exactly the path `checkpoint --plan` will try to stage.
+ *
+ * Best-effort: a probe that throws (a fatal `git check-ignore`) reads as
+ * not-ignored so the heads-up stays silent rather than crashing a session that
+ * is already open.
+ */
+function sidecarIsIgnored(root, slug) {
+    try {
+        return isIgnored(root, buildDir(root, slug));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the value that follows a `--flag` in argv (for example `--slug my-build`), or
  * undefined when the flag is absent or trails with no value.
  */
 function flagValue(args, flag) {
@@ -161,7 +191,7 @@ function flagValue(args, flag) {
     return i >= 0 ? args[i + 1] : undefined;
 }
 /**
- * Stamp a build template's `{{TITLE}}`/`{{CHECK}}` — the check is always the
+ * Stamp a build template's `{{TITLE}}`/`{{CHECK}}`: the check is always the
  * echo constant, since an absent `check` setting IS the checkride default.
  */
 function stampBuild(template, title) {

package/dist/verbs/status.js

@@ -1,6 +1,6 @@
-// `plumbbob status` — the orientation dashboard, or NO ACTIVE SESSION. It
-// parses the live session — intent.md, the build-log, the checkpoints ledger,
-// the in-flight STEP marker — into a where-am-I view that suggests one primary
+// `plumbbob status`: the orientation dashboard, or NO ACTIVE SESSION. It
+// parses the live session (intent.md, the build-log, the checkpoints ledger,
+// the in-flight STEP marker) into a where-am-I view that suggests one primary
 // next move while printing the full picture, so you can always override.
 // Read-only, always exits 0. Skills pre-inject this output to gate their own
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
@@ -25,7 +25,7 @@ function readOr(path) {
  * Print the orientation dashboard for the active build, plus its harness bindings.
  *
  * No session prints the exact `NO ACTIVE SESSION` sentinel; a session with
- * builds but no active one lists them and points at `use`. Always exits 0 —
+ * builds but no active one lists them and points at `use`. Always exits 0:
  * status is a report, never a gate.
  */
 export function status(cwd, args = []) {
@@ -46,9 +46,9 @@ export function status(cwd, args = []) {
         }
     }
     const inFlightRaw = readOr(stepPath(root, slug)).trim();
-    // Out-of-band commits — ones that landed outside the checkpoints ledger — are
+    // Out-of-band commits (ones that landed outside the checkpoints ledger) are
     // surfaced here, never blocked. Counting them needs git (orient is pure), so
-    // status measures it: commits on HEAD since the last ledger line's SHA —
+    // status measures it: commits on HEAD since the last ledger line's SHA:
     // baseline, plan, or step, so a commit landing before the first step
     // checkpoint still surfaces. No ledger yet ⇒ nothing to reconcile against ⇒ 0.
     const checkpoints = readOr(checkpointsPath(root, slug));
@@ -70,7 +70,7 @@ export function status(cwd, args = []) {
  * `defaults` and per step.
  *
  * Bindings live in `builds/<slug>/harness.json` and status is the surface that
- * reports them — no separate `agent check` verb. Any bound agent that does not
+ * reports them: no separate `agent check` verb. Any bound agent that does not
  * resolve gets a warning, not an error: a teammate can lack a personal agent
  * and the loop still works. Returns [] when the build has no harness.json (a
  * clean no-op) or the file binds nothing, so the dashboard stays uncluttered
@@ -100,7 +100,7 @@ function harnessSection(root, slug) {
 /**
  * Render a SlotBindings as `slot: name1, name2` fragments, in slot order.
  *
- * A slot bound to no agents (an explicit "override to none") is omitted —
+ * A slot bound to no agents (an explicit "override to none") is omitted:
  * there is nothing to run and nothing to name.
  */
 function slotFragments(bindings) {

package/dist/verbs/turn.js

@@ -1,16 +1,16 @@
-// `plumbbob turn` — the turn-ledger hook. Wired to the harness's
+// `plumbbob turn`: the turn-ledger hook. Wired to the harness's
 // UserPromptSubmit event, it runs once per human prompt and maintains two of the
 // sidecar's git-excluded control files (flat files under `.plumbbob/`): it ticks
 // `TURN`, the monotonic count of human turns the checkpoint latch compares
 // against a step's entry stamp to know a human turn intervened since the step
-// began, and it rewrites `GRANT` from the literal prompt — minting a one-turn
+// began, and it rewrites `GRANT` from the literal prompt, minting a one-turn
 // self-approval only when the human typed `/build --auto` or an `N-M` step
 // range, clearing it otherwise (those strings can only come from a human
-// keystroke, because `build` is disable-model-invocation — a grant the model
+// keystroke, because `build` is disable-model-invocation: a grant the model
 // could forge would be no grant). When a step is in flight it also emits ONE
 // `UserPromptSubmit` additionalContext line so a fresh session (post-compaction,
 // or a scripted `-p` turn where no skill prose is in context) still knows the
-// beat — a tangent is parked, not chased. Guidance only: it blocks nothing. It
+// beat: a tangent is parked, not chased. Guidance only: it blocks nothing. It
 // ALWAYS exits 0 and any failure degrades to no output, so neither the tick nor
 // the emit can ever wedge prompting.
 import { readFileSync, writeFileSync } from 'node:fs';
@@ -18,7 +18,7 @@ import { findSessionRoot, setGrant, stepPath, turnPath } from "../lib/sidecar.js
 /**
  * The hook entry point: apply the tick, then emit the in-flight-step nudge.
  *
- * Always returns 0 — a broken turn must never wedge a prompt, so any failure is
+ * Always returns 0: a broken turn must never wedge a prompt, so any failure is
  * swallowed and degrades to no output.
  */
 export function turn(cwd, _args) {
@@ -29,7 +29,7 @@ export function turn(cwd, _args) {
             process.stdout.write(context);
     }
     catch {
-        // A broken turn must never wedge a prompt — swallow and exit 0.
+        // A broken turn must never wedge a prompt: swallow and exit 0.
     }
     return 0;
 }
@@ -59,7 +59,7 @@ export function stepInFlightContext(cwd) {
  * The in-flight step number, or null when no STEP marker is present.
  *
  * Absent means no step entered, or it already checkpointed. A garbled marker
- * reads as null — never an error, because the hook must not wedge a prompt.
+ * reads as null (never an error), because the hook must not wedge a prompt.
  */
 function inFlightStep(root) {
     try {
@@ -73,14 +73,14 @@ function inFlightStep(root) {
 /**
  * The testable core: apply one tick given the raw hook stdin.
  *
- * Split from the fd-0 read so the unit tests can drive it directly — an
+ * Split from the fd-0 read so the unit tests can drive it directly: an
  * in-process test cannot feed fd 0 (the same constraint checkpoint's `--body`
  * lives under).
  */
 export function applyTurn(cwd, raw) {
     const root = findSessionRoot(cwd);
     if (root === null)
-        return 0; // no active session above cwd — silent no-op.
+        return 0; // no active session above cwd: silent no-op.
     writeFileSync(turnPath(root), `${readTurn(root) + 1}\n`);
     setGrant(root, grantFromPrompt(extractPrompt(raw)));
     return 0;
@@ -90,7 +90,7 @@ export function applyTurn(cwd, raw) {
  *
  * A grant is minted only from a literal `build` invocation the human typed:
  * `build` is disable-model-invocation, so this string can only come from a
- * human keystroke, never model-authored pressure — a grant the model can forge
+ * human keystroke, never model-authored pressure: a grant the model can forge
  * is no grant. A bounded range beats `--auto` (bounded wins); a bare
  * `/build`, or any non-invocation prompt, mints nothing. The namespaced
  * `/plumbbob:build` form is honored alongside the bare one.
@@ -101,10 +101,10 @@ export function applyTurn(cwd, raw) {
  *
  * Only the invocation's own arguments can mint: the tokens that follow it on
  * its line, up to the first token that isn't a sanctioned argument (`--auto`, a
- * step number, or a range — the argument-hint sanctions nothing else). An
+ * step number, or a range; the argument-hint sanctions nothing else). An
  * unrecognized flag ends the scan, so `/build --wip 2020-2024` mints
- * nothing — the `2020-2024` is never reached. An incidental range elsewhere in
- * the prompt — an issue number, a pasted `2020-2024` — is prose, not a grant.
+ * nothing: the `2020-2024` is never reached. An incidental range elsewhere in
+ * the prompt (an issue number, a pasted `2020-2024`) is prose, not a grant.
  * Trailing sentence punctuation on an argument (`/build 1-3.`) is still the
  * argument the human typed.
  */
@@ -129,8 +129,8 @@ export function grantFromPrompt(prompt) {
             continue;
         }
         if (/^\d+$/.test(word))
-            continue; // a bare step number — keep scanning for a range/--auto
-        break; // an unrecognized flag or free text — the arguments have ended
+            continue; // a bare step number: keep scanning for a range/--auto
+        break; // an unrecognized flag or free text: the arguments have ended
     }
     if (ceiling !== undefined)
         return `range ${ceiling}`;
@@ -170,7 +170,7 @@ function readTurn(root) {
  * Read the hook JSON from fd 0, degrading to '' on any failure.
  *
  * An interactive TTY never sends EOF, so skip the read there rather than hang
- * (mirrors checkpoint's `--body`); a read error degrades to '' — extractPrompt
+ * (mirrors checkpoint's `--body`); a read error degrades to '': extractPrompt
  * then clears the grant and the tick still lands.
  */
 function readStdin() {

package/dist/verbs/use.js

@@ -1,10 +1,10 @@
-// `plumbbob use <slug>` — re-point the active-build cursor at an existing build
+// `plumbbob use <slug>`: re-point the active-build cursor at an existing build
 // and resume it, `nvm use`-shaped: switching and resuming are the same one word.
 // The cursor is the single-line content of `.plumbbob/STATE`, the untracked
 // per-worktree file whose existence means a session is live and whose one line
-// names the build that session is on — so pointing it elsewhere IS the switch,
+// names the build that session is on, so pointing it elsewhere IS the switch,
 // and one-active-per-worktree holds by construction (one line cannot name two
-// builds). It validates the target folder exists, and warns — but allows —
+// builds). It validates the target folder exists, and warns (but allows)
 // leaving a build with a step in flight: the in-flight markers live per build,
 // so that state survives the switch and resumes the next time you `use` the
 // build.
@@ -15,7 +15,7 @@ import { activeBuild, hasSession, intentPath, listBuilds, setActiveBuild, stepPa
  * Switch the active-build cursor to the named build.
  *
  * Refuses without a session, without a slug, or when the target folder has no
- * intent.md; notes — but allows — a step left in flight on the build being left.
+ * intent.md; notes (but allows) a step left in flight on the build being left.
  */
 export function use(cwd, args) {
     const root = findRepoRoot(cwd);

package/node_modules/checkride/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "checkride",
   "displayName": "checkride",
-  "version": "0.10.2",
+  "version": "0.12.2",
   "description": "Bounded, contract-aware readers for what checkride already writes: triage a red gate and read quality signal without loading megabytes of raw artifacts.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://robmclarty.github.io/checkride/",