plumbbob 0.9.3 → 0.10.0

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/hooks/post-edit.sh

@@ -1,12 +1,12 @@
 #!/bin/sh
-# post-edit.sh — light feedback (D25). PostToolUse, non-blocking, ALWAYS exits 0.
+# post-edit.sh — light feedback — D25 (light-then-heavy). PostToolUse, non-blocking, ALWAYS exits 0.
 # Runs file-scoped oxlint + ast-grep on the changed file and injects any failures
-# into the model's context via additionalContext (verified API, D25). No-ops when
+# into the model's context via additionalContext (verified API — D25 (light-then-heavy)). No-ops when
 # the tools are absent or there is no session. tsc is deferred to the heavy tier
-# (D25): it has no true single-file mode and would tax every keystroke.
+# — D25 (light-then-heavy): it has no true single-file mode and would tax every keystroke.
 
 # The repo root is the nearest ancestor whose .plumbbob/STATE is NON-EMPTY — the
-# per-worktree signal that a tracked build is live here (D28). STATE's existence
+# per-worktree signal that a tracked build is live here — D28 (state-cursor). STATE's existence
 # means "a session is active"; its content is the active-build cursor, so a non-empty
 # STATE is exactly "a tracked build is live" (the `--local` layout leaves STATE empty,
 # and this file-scoped check is a tracked-build affordance). `-s` tests both existence

package/hooks/pre-bash-commit.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
-# pre-bash-commit.sh — the git-commit ask-hook (D66). PreToolUse on Bash: when a
+# pre-bash-commit.sh — the git-commit ask-hook — D66 (oob-commits-surfaced). PreToolUse on Bash: when a
 # step is in flight and the model reaches for a raw `git commit`, turn that commit
 # into a permission *question*, never a wall. checkpoint owns the landing (the latch
 # lives there); this only nudges the human to route through it. ALWAYS exits 0 and
-# never `deny`s — the human decides, C5 stays intact (D66). `plumbbob checkpoint`'s
+# never `deny`s — the human decides, C5 (additive-git) stays intact — D66 (oob-commits-surfaced). `plumbbob checkpoint`'s
 # own internal `git commit` spawn never passes through hooks, so nothing self-trips.
 
 # The repo root is the nearest ancestor with an active session — `.plumbbob/STATE`,
@@ -27,7 +27,7 @@ root=$(find_root) || exit 0 # no active session here: nothing to guard
 
 # The in-flight signal is STEP (cleared when the step checkpoints): inside the
 # active build's folder when STATE names one, else the flat sidecar STEP of the
-# `--local` layout. STATE's content IS the cursor (D28) — read the first line, trim
+# `--local` layout. STATE's content IS the cursor — D28 (state-cursor) — read the first line, trim
 # whitespace, and treat the legacy `active` sentinel (pre-STATE-cursor) as no cursor.
 slug=$(head -n1 "$root/.plumbbob/STATE" 2>/dev/null | tr -d '[:space:]')
 [ "$slug" = "active" ] && slug=""

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

@@ -0,0 +1,11 @@
+{
+  "name": "checkride",
+  "displayName": "checkride",
+  "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/",
+  "repository": "https://github.com/robmclarty/checkride",
+  "license": "Apache-2.0",
+  "keywords": ["claude-code", "claude", "agent", "checkride", "ci", "triage"]
+}