plumbbob 0.9.5 → 0.10.1

package/dist/lib/git.js

@@ -1,15 +1,15 @@
-// Thin git wrapper over `node:child_process` — the CLI stays on node builtins
+// Thin git wrapper over `node:child_process`: the CLI stays on node builtins
 // plus a small deliberate dependency allowlist, and subprocess spawning is
 // centralized in files like this one. Plumbbob's git footprint is additive by
 // rule: these helpers read, locate, stage, and commit forward, and reset
-// `--hard` only to plumbbob's own recorded checkpoint SHAs — never a
+// `--hard` only to plumbbob's own recorded checkpoint SHAs: never a
 // history-rewriting operation on anything pushed.
 import { execFileSync } from 'node:child_process';
 import { isAbsolute, join } from 'node:path';
 /**
  * Run git in `root` and return its trimmed stdout.
  *
- * stderr is discarded and a non-zero exit throws — callers that tolerate
+ * stderr is discarded and a non-zero exit throws: callers that tolerate
  * failure wrap the call in their own try/catch.
  */
 function runGit(root, args) {
@@ -35,8 +35,8 @@ export function findRepoRoot(cwd) {
  * Plumbbob writes its control-plane excludes to the shared gitdir's
  * `info/exclude` (personal machinery, never the repo's `.gitignore`), and
  * `--git-path` maps common-dir entries like `info/exclude` to the shared file
- * even from a linked worktree — whose per-worktree gitdir has no `info/` and
- * which git never reads for excludes. The result is relative to `root` unless
+ * even from a linked worktree (whose per-worktree gitdir has no `info/` and
+ * which git never reads for excludes). The result is relative to `root` unless
  * already absolute.
  */
 export function gitPath(root, relative) {
@@ -68,16 +68,16 @@ export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
 /**
- * The number of commits on HEAD not reachable from `sha` — `git rev-list
+ * The number of commits on HEAD not reachable from `sha`: `git rev-list
  * --count --first-parent <sha>..HEAD`.
  *
  * `status` reads this for its receipts line: one neutral note when commits
  * landed since the last checkpoint outside plumbbob's ledger (out-of-band
  * commits are surfaced, never blocked). `--first-parent` keeps the count on
  * the branch's own line: merging upstream reads as the one merge commit, not
- * the dozens it carried — those didn't land "outside the ledger" in any sense
+ * the dozens it carried; those didn't land "outside the ledger" in any sense
  * the receipt should nag about. Best-effort and never throws: 0 when the range
- * is empty, `sha` is unknown to the repo, or HEAD is unborn — the count is
+ * is empty, `sha` is unknown to the repo, or HEAD is unborn: the count is
  * informational (the human commits freely), never a gate.
  */
 export function commitsSince(root, sha) {
@@ -92,22 +92,51 @@ export function commitsSince(root, sha) {
 // --- mutation helpers (build-loop: done checkpoints, revert resets). Additive
 // only: stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
 /**
- * Stage everything (`git add -A`) — the checkpoint sweep that carries the work
+ * Stage everything (`git add -A`): the checkpoint sweep that carries the work
  * plus plumbbob's own bookkeeping into one commit.
  */
 export function stageAll(root) {
     runGit(root, ['add', '-A']);
 }
 /**
- * Stage a single path (vs `stageAll`'s `-A`).
+ * Stage a single path (vs `stageAll`'s `-A`), returning whether it staged.
  *
  * The plan-approval commit stages only the build's artifact folder so the
- * first step's diff can't absorb the plan scaffold — plan approval gets its
- * own commit. `path` may be absolute or repo-relative — git resolves it
+ * first step's diff can't absorb the plan scaffold: plan approval gets its
+ * own commit. `path` may be absolute or repo-relative; git resolves it
  * against `root`. The `--` guards a path that could look like a flag.
+ *
+ * A repo that gitignores the sidecar has decided not to track it, and git
+ * hard-refuses an explicit `git add` of an ignored path, so probe
+ * `check-ignore` first: an ignored path is skipped and returns false (the
+ * caller's commit is then record-only), a tracked one stages and returns true.
+ * Never `git add -f`: honoring the repo's exclusion is the whole point.
  */
 export function stagePath(root, path) {
+    if (isIgnored(root, path)) {
+        return false;
+    }
     runGit(root, ['add', '--', path]);
+    return true;
+}
+/**
+ * Whether git ignores `path`: a `git check-ignore -q` probe.
+ *
+ * Exit 0 means ignored; exit 1 means not (execFileSync throws on the non-zero,
+ * caught and read as false); any other status (128, a genuine failure)
+ * propagates. `path` may be absolute or repo-relative.
+ */
+export function isIgnored(root, path) {
+    try {
+        runGit(root, ['check-ignore', '-q', '--', path]);
+        return true;
+    }
+    catch (error) {
+        if (error.status === 1) {
+            return false;
+        }
+        throw error;
+    }
 }
 /**
  * The repo-relative paths of non-ignored untracked files.
@@ -130,7 +159,7 @@ export function commit(root, subject, body) {
     return headSha(root);
 }
 /**
- * The `--stat` summary of what is currently staged (vs HEAD) — the diffstat
+ * The `--stat` summary of what is currently staged (vs HEAD): the diffstat
  * the deterministic checkpoint body carries when no `--body` prose arrives.
  * Empty when nothing is staged.
  */
@@ -138,7 +167,7 @@ export function stagedStat(root) {
     return runGit(root, ['diff', '--cached', '--stat']);
 }
 /**
- * The repo-relative paths currently staged (vs HEAD) — the set `checkpoint`
+ * The repo-relative paths currently staged (vs HEAD): the set `checkpoint`
  * checks against the step's seam (its granted edit paths) to warn about scope
  * drift. Empty when nothing is staged.
  */
@@ -147,7 +176,7 @@ export function stagedPaths(root) {
     return out.length === 0 ? [] : out.split('\n');
 }
 /**
- * Reset the worktree hard to `sha` — only ever one of plumbbob's own recorded
+ * Reset the worktree hard to `sha`: only ever one of plumbbob's own recorded
  * checkpoint SHAs, and only `revert` imports this (an ast-grep rule pins that
  * single importer).
  */

package/dist/lib/intent.js

@@ -1,16 +1,16 @@
-// The intent.md parser. intent.md is a build's plan document — title, the
+// The intent.md parser. intent.md is a build's plan document: title, the
 // numbered increments under `## Steps`, decisions, constraints, open questions.
 // This module reads it in two registers. The seam parse is strict by design: a
-// seam is a step's edit grant — the backtick-wrapped, repo-relative paths on
-// its single `seam:` sub-line — and it gates git behavior, so the parse refuses
+// seam is a step's edit grant (the backtick-wrapped, repo-relative paths on
+// its single `seam:` sub-line) and it gates git behavior, so the parse refuses
 // precisely on globs, absolute paths, a missing step, a missing seam, or more
 // than one seam line, rather than guessing. The best-effort scrapers below
 // (title, done-when, decisions, constraints) feed an agent's context, not a
-// gate, so they never refuse — they return what they can and report the lines
+// gate, so they never refuse; they return what they can and report the lines
 // they skipped.
 const GLOB_CHARS = /[*?[\]{}]/;
 /**
- * The lines belonging to step `n` under `## Steps` — from its `N. ` opener to
+ * The lines belonging to step `n` under `## Steps`: from its `N. ` opener to
  * the next opener or the section end.
  *
  * Shared by the strict seam parse and the best-effort meta scrape; it keeps the
@@ -44,12 +44,12 @@ function sliceStep(content, step) {
     return { ok: true, itemLines: lines.slice(itemStart, itemEnd) };
 }
 /**
- * Parse step `n`'s seam — the backtick-wrapped paths on its single `seam:` sub-line.
+ * Parse step `n`'s seam: the backtick-wrapped paths on its single `seam:` sub-line.
  *
  * Strict: the seam is the step's edit grant and gates git behavior, so this
  * refuses on a missing step, a missing or duplicated seam line, an empty token,
  * a glob, or an absolute path rather than guessing. Tokens are exact
- * repo-relative paths or `dir/` prefix grants — never globs.
+ * repo-relative paths or `dir/` prefix grants: never globs.
  */
 export function parseStepSeam(content, step) {
     const slice = sliceStep(content, step);
@@ -132,7 +132,7 @@ export function isArtifactPath(relPath) {
 }
 /**
  * The staged paths that fall outside the step's seam AND outside the artifact
- * plane — the scope-drift set `checkpoint` warns about.
+ * plane: the scope-drift set `checkpoint` warns about.
  *
  * Guidance, not a gate: the checkpoint still commits them. An empty seam yields
  * no drift, so callers that cannot resolve a seam simply skip the warning
@@ -171,15 +171,15 @@ export function parseStepMeta(content, step) {
     const body = collected.join(' ').replace(/^\d+\.\s*(?:\[[ xX]\]\s*)?/, '').trim();
     const m = DONE_WHEN.exec(body);
     if (m === null) {
-        return { title: stripTrailingDash(body), doneWhen: '' };
+        return { title: stripTrailingSeparator(body), doneWhen: '' };
     }
     return {
-        title: stripTrailingDash(body.slice(0, m.index)),
+        title: stripTrailingSeparator(body.slice(0, m.index)),
         doneWhen: body.slice(m.index + m[0].length).trim(),
     };
 }
 /**
- * The build title — the first `# ` heading. '' when absent.
+ * The build title: the first `# ` heading. '' when absent.
  */
 export function parseBuildTitle(content) {
     for (const line of content.split('\n')) {
@@ -193,12 +193,12 @@ export function parseBuildTitle(content) {
 const SCOPE_HEADER = /^\*\*Scope:\*\*\s*(.*)$/;
 const SCOPE_PLACEHOLDER = /^<.*>$/;
 /**
- * The build's default Conventional-Commit scope — the `**Scope:**` header field
+ * The build's default Conventional-Commit scope: the `**Scope:**` header field
  * authored once in intent.md at plan time.
  *
  * The value is read verbatim off the line, with any trailing `<!-- ... -->`
- * guidance note stripped. An unfilled placeholder — an empty value or an
- * angle-bracket placeholder like `<feature>` — parses as absent, so a freshly
+ * guidance note stripped. An unfilled placeholder (an empty value or an
+ * angle-bracket placeholder like `<feature>`) parses as absent, so a freshly
  * scaffolded, not-yet-edited build falls through to the next rung of the scope
  * fallback chain (the build slug) rather than landing commits scoped
  * `(<feature>)`. null when the header is missing entirely, so an intent.md
@@ -221,7 +221,7 @@ export function parseBuildScope(content) {
  *
  * Verbatim keeps a bullet's `*because*` rationale intact for the agent that
  * reads it. `skipped` holds any line under the heading that was neither a
- * bullet, a continuation, nor blank — a malformed bullet the caller warns
+ * bullet, a continuation, nor blank: a malformed bullet the caller warns
  * about rather than dropping silently.
  */
 export function scrapeBullets(content, heading) {
@@ -264,11 +264,12 @@ export function scrapeBullets(content, heading) {
     return { items, skipped };
 }
 /**
- * Trim a trailing em-dash or hyphen (the `Title —` separator) plus surrounding
- * space, so a title never carries the marker that introduced its done-when.
+ * Trim a trailing separator (a comma, or the legacy em dash or hyphen) plus
+ * surrounding space, so a title never carries the marker that introduced its
+ * done-when.
  */
-function stripTrailingDash(text) {
-    return text.replace(/\s*[—-]+\s*$/, '').trim();
+function stripTrailingSeparator(text) {
+    return text.replace(/\s*[—,-]+\s*$/, '').trim();
 }
 /**
  * Shorthand for a failed SeamParse.

package/dist/lib/latch.js

@@ -1,25 +1,25 @@
-// The approval latch — the ledger-plane predicate `checkpoint` evaluates before
+// The approval latch: the ledger-plane predicate `checkpoint` evaluates before
 // its check gate (the latch is cheap, so it runs first; the heavy gate already
-// ran in the verify tick). The work plane stays guidance — no edit is ever
-// blocked — but the commit tick is latched: a step may not land unless a human
+// ran in the verify tick). The work plane stays guidance (no edit is ever
+// blocked) but the commit tick is latched: a step may not land unless a human
 // turn intervened since the step was entered, the human granted a one-turn
 // self-approval from their literal prompt, or the turn ledger is dormant (a
 // host with no hooks grows no ledger, and the latch stays out of the way rather
 // than wedging). The ledger is a pair of flat sidecar control files: TURN
 // counts human prompts (ticked by the `plumbbob turn` hook), TICK stamps that
-// count when a step is entered — TURN > TICK means a human turn intervened.
+// count when a step is entered; TURN > TICK means a human turn intervened.
 // Five rows, evaluated in order, first hit wins; the refusal message *is* the
 // pause affordance. A standing `auto` in a settings file is never a grant: a
-// model can write that file, and a grant it can forge is no grant — the latch
+// model can write that file, and a grant it can forge is no grant; the latch
 // reads it only to say so at the pause, never to allow. It reads only
-// TURN/TICK/GRANT and isTTY — it never sniffs the host session. Named exports,
+// TURN/TICK/GRANT and isTTY; it never sniffs the host session. Named exports,
 // node builtins.
 import { readFileSync } from 'node:fs';
 import { grantPath, tickPath, turnPath } from "./sidecar.js";
 import { resolveBoolean } from "./settings.js";
 const ALLOW = { allow: true };
 /**
- * The refusal message is the affordance — it tells the model what the pause is,
+ * The refusal message is the affordance; it tells the model what the pause is,
  * how it ends (approval on the next turn lands it; `/plumbbob:build` only starts the
  * next step), and names the only legitimate grants.
  */
@@ -31,7 +31,7 @@ boundary; \`/plumbbob:build\` only starts the next step, it never lands this one
 `;
 /**
  * The plan commit gets its own wording: there is no step, no diff, and no
- * self-review at plan time — what the human approves is the plan itself.
+ * self-review at plan time; what the human approves is the plan itself.
  */
 const NO_TURN_PLAN_MESSAGE = `plumbbob: checkpoint refused — no human turn since \`start\` stamped this plan. This
 is the plan pause: present the plan, then end the turn; the human's approving
@@ -39,7 +39,7 @@ message is the tick that lets it land on the next run. (An explicit \`/plumbbob:
 step range in the human's own prompt is the only self-approval.)
 `;
 /**
- * A settings `auto` is never a grant — a model can write that file, and a grant
+ * A settings `auto` is never a grant; a model can write that file, and a grant
  * it can forge is no grant. When one is set, the refusal names it rather than
  * silently ignoring it, and points at the only self-approval that works.
  */
@@ -60,19 +60,19 @@ function ceilingMessage(ceiling) {
  */
 export function evaluateLatch(input) {
     if (input.isTTY)
-        return ALLOW; // 1 — a human at the keyboard
+        return ALLOW; // 1: a human at the keyboard
     if (input.turn === null || input.tick === null)
-        return ALLOW; // 2 — dormant ledger / hand-built diff
+        return ALLOW; // 2: dormant ledger / hand-built diff
     if (input.grant?.kind === 'auto')
-        return ALLOW; // 3 — one-turn grant the human typed
+        return ALLOW; // 3: one-turn grant the human typed
     if (input.grant?.kind === 'range' && input.step !== null) {
         if (input.step <= input.grant.ceiling)
             return ALLOW;
         return { allow: false, reason: 'ceiling', message: ceilingMessage(input.grant.ceiling) };
     }
     if (input.turn > input.tick)
-        return ALLOW; // 4 — a human turn intervened
-    // 5 — the pause (plan-worded when no step is landing). A settings `auto` never
+        return ALLOW; // 4: a human turn intervened
+    // 5: the pause (plan-worded when no step is landing). A settings `auto` never
     // allows; when one is set, the refusal notes it rather than honoring it.
     const base = input.step === null ? NO_TURN_PLAN_MESSAGE : NO_TURN_MESSAGE;
     return { allow: false, reason: 'no-turn', message: input.settingsAuto ? base + SETTINGS_AUTO_NOTE : base };
@@ -80,7 +80,7 @@ export function evaluateLatch(input) {
 /**
  * Parse a GRANT file's content (`auto` | `range <M>`).
  *
- * Anything else — including a corrupted or hand-mangled file — contributes
+ * Anything else (including a corrupted or hand-mangled file) contributes
  * nothing: no grant, never an error.
  */
 export function parseGrant(raw) {
@@ -105,7 +105,7 @@ export function checkLatch(root, step) {
         tick: readCount(tickPath(root)),
         grant: readGrant(root),
         step,
-        // Read from the settings ladder — but only to decorate the pause, never to allow.
+        // Read from the settings ladder, but only to decorate the pause, never to allow.
         settingsAuto: resolveBoolean(root, 'auto', false),
     });
 }

package/dist/lib/orient.js

@@ -1,5 +1,5 @@
 // The orientation model behind `status`: parse a live build session into the
-// where-am-I dashboard — title, phase, step list, last checkpoint, counts, and
+// where-am-I dashboard: title, phase, step list, last checkpoint, counts, and
 // one suggested next move. Pure and best-effort by design: it takes raw file
 // contents (no fs), and a malformed document degrades to fewer fields rather
 // than throwing.
@@ -20,7 +20,7 @@ function sectionLines(content, heading) {
     return lines.slice(start + 1, end);
 }
 /**
- * The build title — the first `# ` heading in intent.md, or null when absent.
+ * The build title: the first `# ` heading in intent.md, or null when absent.
  */
 export function parseTitle(intent) {
     for (const line of intent.split('\n')) {
@@ -32,12 +32,14 @@ export function parseTitle(intent) {
     return null;
 }
 /**
- * Parse the steps under `## Steps`: `N. [ |x] Title — **done when:** ...`.
+ * Parse the steps under `## Steps`: `N. [ |x] Title, **done when:** ...`
+ * (the legacy em-dash separator before the marker parses the same).
  *
- * The title is the text up to the first em dash; `planned` is true when the
- * step's block carries a `done when` criterion. Only `## Steps` is machine-read
- * as the build plan — narrative roadmap prose lives in its own section and
- * never lands here.
+ * The title is the text before the `**done when:**` marker on the opener line,
+ * trailing separator stripped; an opener without the marker falls back to the
+ * text up to the first em dash. `planned` is true when the step's block carries
+ * a `done when` criterion. Only `## Steps` is machine-read as the build plan;
+ * narrative roadmap prose lives in its own section and never lands here.
  */
 export function parseSteps(intent) {
     const lines = sectionLines(intent, '## Steps');
@@ -46,10 +48,12 @@ export function parseSteps(intent) {
         const m = /^(\d+)\.\s+\[([ xX])\]\s+(.*)$/.exec(line);
         if (m) {
             const rest = m[3] ?? '';
+            const marker = /\*\*done when:\*\*/i.exec(rest);
+            const head = marker ? rest.slice(0, marker.index) : (rest.split('—')[0] ?? rest);
             starts.push({
                 n: Number(m[1]),
                 done: (m[2] ?? ' ').toLowerCase() === 'x',
-                title: (rest.split('—')[0] ?? rest).trim(),
+                title: head.replace(/\s*[—,-]+\s*$/, '').trim(),
                 idx,
             });
         }
@@ -88,13 +92,28 @@ export function markStepDone(intent, n) {
 }
 /**
  * Count the questions still open: `- Q\d+:` openers under `## Open questions`
- * that do not say "resolved".
+ * that carry neither a resolution marker nor an unfilled scaffold body.
  *
- * The opener may carry a slug-at-birth gloss — `- Q2 (some-slug): ...` — which
- * the count reads through; sub-lines (`*plain:*`/`*lean:*`) never match.
+ * The opener may carry a slug-at-birth gloss (`- Q2 (some-slug): ...`) and the
+ * anchored form a citable question is born in:
+ * `- <a id="q2"></a>**Q2 (some-slug)**: ...`, which is what a `[Q2 (some-slug)](#q2)`
+ * reference site elsewhere in the file lands on. The count reads through both, and
+ * through any mix of them a hand-edited intent leaves mid-build; sub-lines
+ * (`*plain:*`/`*lean:*`) never match.
+ *
+ * Two rules settle the rest. "Resolved" counts as a marker only as a whole word, so
+ * a question whose opener still calls itself "unresolved" keeps counting; a bare
+ * substring read that as resolved and dropped a live hole off the dashboard. And an
+ * opener whose body has not been filled in yet, still opening on its `<...>`
+ * fill-in, is scaffold rather than a question, which is what makes a fresh build
+ * report zero rather than one.
  */
 export function parseOpenQuestions(intent) {
-    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+(?: \([^)]+\))?:/.test(l.trim()) && !/resolved/i.test(l)).length;
+    const opener = /^-\s+(?:<a id="[^"]*"><\/a>\s*)?\*{0,2}Q\d+(?: \([^)]+\))?\*{0,2}:\s*(.*)$/;
+    return sectionLines(intent, '## Open questions').filter((l) => {
+        const body = opener.exec(l.trim())?.[1];
+        return body !== undefined && !/\bresolved\b/i.test(l) && !/^<[^>]*>/.test(body);
+    }).length;
 }
 /**
  * Count the open parked items: `- [ ]` lines under `## Park list`.
@@ -122,12 +141,12 @@ export function parseLastCheckpoint(checkpoints) {
     return last;
 }
 /**
- * The SHA of the last ledger line of ANY kind — baseline, plan, or step.
+ * The SHA of the last ledger line of ANY kind: baseline, plan, or step.
  *
  * This is the reconciliation anchor for the out-of-band commit count: a commit
  * that lands after the plan but before the first step checkpoint is exactly the
  * window the reconciliation line exists for, so anchoring on step lines alone
- * would leave it invisible. `parseLastCheckpoint` stays step-only — it feeds
+ * would leave it invisible. `parseLastCheckpoint` stays step-only; it feeds
  * the "last checkpoint step N" display, where baseline/plan would be noise.
  */
 export function lastLedgerSha(checkpoints) {
@@ -162,7 +181,7 @@ function nextMove(spiking, steps, inFlight, parked) {
             return 'plan the first step — `/plumbbob:step`';
         }
         // Batch-default: the steps were planned up front, so finishing them usually
-        // means "finish up" — but `/plumbbob:step` can still add an increment if reality grew.
+        // means "finish up", but `/plumbbob:step` can still add an increment if reality grew.
         const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/plumbbob:harvest\`; then ` : '';
         return `${harvest}finish up — \`/plumbbob:finish\` (or \`/plumbbob:step\` to add another increment)`;
     }
@@ -207,7 +226,7 @@ export function formatOrientation(o) {
             return head;
         }
         // Surface the next step's detail so the human can review it (and `/plumbbob:step`-
-        // revise) before building. Only what's present — a rough step shows neither.
+        // revise) before building. Only what's present: a rough step shows neither.
         const detail = [];
         if (o.nextDoneWhen !== null) {
             detail.push(`        done when: ${o.nextDoneWhen}`);
@@ -225,7 +244,7 @@ export function formatOrientation(o) {
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
     // A neutral reconciliation note, only when there is something to reconcile:
     // commits landed since the last checkpoint that plumbbob's ledger didn't
-    // record. Informational — the human commits freely, so this never gates.
+    // record. Informational: the human commits freely, so this never gates.
     const receipts = o.outOfBand > 0
         ? [`${o.outOfBand} commit${o.outOfBand === 1 ? '' : 's'} since the last checkpoint landed outside plumbbob's ledger.`]
         : [];

package/dist/lib/reentry.js

@@ -3,8 +3,8 @@
 //
 // The failure it exists to stop is not slowness, it is unbounded recursion. A
 // repo whose `check` setting is its own full pipeline (`pnpm check`) has a gate
-// that runs its test suite; anything in that suite which gates THAT SAME REPO —
-// a test driving `checkpoint` against the process cwd — spawns a second full
+// that runs its test suite; anything in that suite which gates THAT SAME REPO
+// (a test driving `checkpoint` against the process cwd) spawns a second full
 // pipeline, whose suite spawns a third. Each generation forks wider than the
 // last, and nothing in the loop is aware there is a loop. The only thing that
 // ended the first observed occurrence was checkride's 600s per-check cap
@@ -13,7 +13,7 @@
 // It is scoped BY ROOT, and that is the whole design. A flat "a gate is
 // running" flag is wrong in the one case that matters most: plumbbob's own
 // suite legitimately gates dozens of fixture repos, and when the suite itself
-// is running under this repo's gate it inherits the marker — so a flat flag
+// is running under this repo's gate it inherits the marker, so a flat flag
 // refuses every one of them and turns a green suite red. Recursion is a repo
 // re-entering ITS OWN gate; a different root is ordinary nested work and must
 // pass through untouched.

package/dist/lib/settings.js

@@ -1,19 +1,19 @@
 // The settings ladder: a resolved setting comes from, in priority order,
-//   1. a CLI flag           — passed in by the verb (undefined when absent)
-//   2. settings.local.json  — untracked personal overlay, per-worktree
-//   3. settings.json        — tracked project defaults
-//   4. a built-in default   — supplied by the caller
+//   1. a CLI flag: passed in by the verb (undefined when absent)
+//   2. settings.local.json: untracked personal overlay, per-worktree
+//   3. settings.json: tracked project defaults
+//   4. a built-in default: supplied by the caller
 // The first defined rung wins. Both files are optional JSON; a missing or
 // malformed file contributes nothing rather than throwing, so a broken personal
 // overlay can never wedge the tool. Functional and procedural, node builtins only.
 //
-// Known keys: `check` (string — the command for the heavy verify gate, a project
-// default in settings.json) and `auto` (boolean — a personal preference, so it
+// Known keys: `check` (string: the command for the heavy verify gate, a project
+// default in settings.json) and `auto` (boolean: a personal preference, so it
 // belongs in settings.local.json). `auto` is NOT a checkpoint grant: the approval
-// latch never reads it to allow a land — a model can write this file, and a grant
-// it can forge is no grant — only to name it at the pause when set; self-approval
+// latch never reads it to allow a land (a model can write this file, and a grant
+// it can forge is no grant) only to name it at the pause when set; self-approval
 // comes solely from the human's literal `/build --auto` or a typed step range.
-// The per-worktree active-build cursor is NOT here — it lives in the STATE file
+// The per-worktree active-build cursor is NOT here: it lives in the STATE file
 // (see sidecar.ts), which keeps this overlay a human-authored file rather than
 // tool-managed state.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -34,7 +34,7 @@ export function localSettingsPath(root) {
 /**
  * Read one settings file as a plain object.
  *
- * A missing, malformed, or non-object file yields {} — an empty rung that
+ * A missing, malformed, or non-object file yields {}: an empty rung that
  * contributes nothing rather than wedging the tool.
  */
 function readSettings(path) {
@@ -61,7 +61,7 @@ function resolveSetting(root, key, flag) {
     return readSettings(settingsPath(root))[key];
 }
 /**
- * Resolve a string setting (e.g. `check`).
+ * Resolve a string setting (for example `check`).
  *
  * A missing rung, or one holding a non-string / blank value, yields the
  * caller's fallback rather than gating on garbage.
@@ -71,7 +71,7 @@ export function resolveString(root, key, fallback, flag) {
     return typeof value === 'string' && value.trim().length > 0 ? value : fallback;
 }
 /**
- * Resolve a boolean setting (e.g. `auto`). A missing or non-boolean rung
+ * Resolve a boolean setting (for example `auto`). A missing or non-boolean rung
  * yields the caller's fallback.
  */
 export function resolveBoolean(root, key, fallback, flag) {
@@ -79,10 +79,10 @@ export function resolveBoolean(root, key, fallback, flag) {
     return typeof value === 'boolean' ? value : fallback;
 }
 /**
- * Resolve a non-negative integer setting (e.g. `agentTimeout`).
+ * Resolve a non-negative integer setting (for example `agentTimeout`).
  *
  * A missing rung, or one holding a non-finite / negative / non-integer number,
- * yields the caller's fallback rather than a garbage timeout — 0 means "no
+ * yields the caller's fallback rather than a garbage timeout: 0 means "no
  * timeout", so a broken value must never silently become one.
  */
 export function resolveNumber(root, key, fallback, flag) {
@@ -90,11 +90,11 @@ export function resolveNumber(root, key, fallback, flag) {
     return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
 }
 /**
- * Resolve an object-valued setting (e.g. the `agents` slot-binding defaults)
+ * Resolve an object-valued setting (for example the `agents` slot-binding defaults)
  * across the same ladder.
  *
  * The first defined, object-typed rung wins; a missing rung, or one holding a
- * non-object / array / scalar, yields {} rather than garbage — mirrors the
+ * non-object / array / scalar, yields {} rather than garbage: mirrors the
  * string/boolean/number resolvers above. No flag rung: the caller (`agent
  * run`) merges these under the per-build harness bindings, not over a flag.
  */