plumbbob 0.9.5 → 0.10.0

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) {
@@ -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) {

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,7 +103,7 @@ 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
+ * 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.
@@ -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) {