plumbbob 0.8.18 → 0.9.1

package/dist/lib/git.js

@@ -1,15 +1,26 @@
-// Thin git wrapper over `node:child_process` (C2: node builtins plus the
-// deliberate few). Functional/procedural, no classes (C1). Plumbbob's git
-// footprint is additive (C5); these helpers only read and locate.
+// 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
+// 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
+ * failure wrap the call in their own try/catch.
+ */
 function runGit(root, args) {
     return execFileSync('git', ['-C', root, ...args], {
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
 }
-// The git toplevel for `cwd`, or null when `cwd` is not inside a git repo.
+/**
+ * The git toplevel for `cwd`, or null when `cwd` is not inside a git repo.
+ */
 export function findRepoRoot(cwd) {
     try {
         return runGit(cwd, ['rev-parse', '--show-toplevel']);
@@ -18,17 +29,29 @@ export function findRepoRoot(cwd) {
         return null;
     }
 }
-// Absolute path to a file inside the repo's *common* git dir. `--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 (D33). The result is relative to `root` unless already absolute.
+/**
+ * Absolute path to a file inside the repo's *common* git dir.
+ *
+ * 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
+ * already absolute.
+ */
 export function gitPath(root, relative) {
     const out = runGit(root, ['rev-parse', '--git-path', relative]);
     return isAbsolute(out) ? out : join(root, out);
 }
+/**
+ * The SHA of the current HEAD commit.
+ */
 export function headSha(root) {
     return runGit(root, ['rev-parse', 'HEAD']);
 }
+/**
+ * True when the repo has at least one commit (HEAD resolves).
+ */
 export function hasCommit(root) {
     try {
         runGit(root, ['rev-parse', '--verify', 'HEAD']);
@@ -38,18 +61,25 @@ export function hasCommit(root) {
         return false;
     }
 }
-// Dirty = any tracked change or non-ignored untracked file.
+/**
+ * Dirty = any tracked change or non-ignored untracked file.
+ */
 export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
-// The number of commits on HEAD not reachable from `sha` — `git rev-list --count
-// --first-parent <sha>..HEAD`. The receipts line (D66) reads this to surface commits
-// that landed since the last checkpoint outside plumbbob's ledger. `--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 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
-// informational (the human commits freely, C5), never a gate.
+/**
+ * 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 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
+ * informational (the human commits freely), never a gate.
+ */
 export function commitsSince(root, sha) {
     try {
         const n = Number.parseInt(runGit(root, ['rev-list', '--count', '--first-parent', `${sha}..HEAD`]), 10);
@@ -60,42 +90,67 @@ export function commitsSince(root, sha) {
     }
 }
 // --- mutation helpers (build-loop: done checkpoints, revert resets). Additive
-// only (C5): stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
+// only: stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
+/**
+ * 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`): the plan-approval commit stages only
-// the build's artifact folder so the first step's diff can't absorb the plan
-// scaffold (D36). `path` may be absolute or repo-relative — git resolves it against
-// `root`. The `--` guards a path that could look like a flag.
+/**
+ * Stage a single path (vs `stageAll`'s `-A`).
+ *
+ * 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
+ * against `root`. The `--` guards a path that could look like a flag.
+ */
 export function stagePath(root, path) {
     runGit(root, ['add', '--', path]);
 }
+/**
+ * The repo-relative paths of non-ignored untracked files.
+ */
 export function untrackedPaths(root) {
     const out = runGit(root, ['ls-files', '--others', '--exclude-standard']);
     return out.length === 0 ? [] : out.split('\n');
 }
-// Commit whatever is staged as a checkpoint and return its SHA. --allow-empty so
-// a step that touched only ignored files still gets a checkpoint to revert to.
-// An optional `body` becomes the commit message body: git joins the two `-m`
-// paragraphs with a blank line, so the subject stays the first line (D34).
+/**
+ * Commit whatever is staged as a checkpoint and return its SHA.
+ *
+ * `--allow-empty` so a step that touched only ignored files still gets a
+ * checkpoint to revert to. An optional `body` becomes the commit message body:
+ * git joins the two `-m` paragraphs with a blank line, so the CLI-owned
+ * subject stays the first line and the body rides beneath it.
+ */
 export function commit(root, subject, body) {
     const message = body ? ['-m', subject, '-m', body] : ['-m', subject];
     runGit(root, ['commit', '--allow-empty', ...message]);
     return headSha(root);
 }
-// The `--stat` summary of what is currently staged (vs HEAD) — the diffstat the
-// deterministic checkpoint body carries (D35). Empty when nothing is staged.
+/**
+ * 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.
+ */
 export function stagedStat(root) {
     return runGit(root, ['diff', '--cached', '--stat']);
 }
-// The repo-relative paths currently staged (vs HEAD) — the set `checkpoint`
-// checks against the step's seam to warn about scope drift. Empty when nothing is
-// staged.
+/**
+ * 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.
+ */
 export function stagedPaths(root) {
     const out = runGit(root, ['diff', '--cached', '--name-only']);
     return out.length === 0 ? [] : out.split('\n');
 }
+/**
+ * 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).
+ */
 export function resetHard(root, sha) {
     runGit(root, ['reset', '--hard', sha]);
 }

package/dist/lib/intent.js

@@ -1,11 +1,22 @@
-// The intent parser. `build <n>` reads the nth step under `## Steps` and extracts
-// its seam — the backtick-wrapped paths on the single `seam:` sub-line. The seam
-// half is strict by design (it gates git behavior): it 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 they skipped (D61).
+// 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
+// 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
+// they skipped.
 const GLOB_CHARS = /[*?[\]{}]/;
+/**
+ * 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
+ * "no Steps section" and "no such step" error strings distinct so both callers
+ * can tell them apart.
+ */
 function sliceStep(content, step) {
     const lines = content.split('\n');
     const stepsIdx = lines.findIndex((l) => l.trim() === '## Steps');
@@ -32,6 +43,14 @@ function sliceStep(content, step) {
     const itemEnd = nextStart === undefined ? sectionEnd : nextStart;
     return { ok: true, itemLines: lines.slice(itemStart, itemEnd) };
 }
+/**
+ * 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.
+ */
 export function parseStepSeam(content, step) {
     const slice = sliceStep(content, step);
     if (!slice.ok) {
@@ -52,7 +71,7 @@ export function parseStepSeam(content, step) {
     // Truncate each at an HTML-comment opener so a trailing `<!-- ... -->` note
     // (which may carry its own backticks) is never read as a seam token; a
     // continuation ends at the first line whose pre-comment text has no backtick
-    // or that opens a new sub-bullet (a `- model:` note may carry backticks too, D62).
+    // or that opens a new sub-bullet (a `- model:` note may carry backticks too).
     const seamStart = seamLines[0] ?? 0;
     const decl = [];
     for (let i = seamStart; i < itemLines.length; i++) {
@@ -88,25 +107,37 @@ export function parseStepSeam(content, step) {
     }
     return { ok: true, seam };
 }
-// Seam membership (D23): a repo-relative path is in-seam if it equals an exact
-// token, or is prefixed by a `dir/` grant. Shared by `checkpoint` (scope-drift
-// warn) and `revert` (untracked cleanup).
+/**
+ * Seam membership: a repo-relative path is in-seam if it equals an exact token,
+ * or is prefixed by a `dir/` grant.
+ *
+ * Shared by `checkpoint` (the scope-drift warning) and `revert` (untracked
+ * cleanup).
+ */
 export function matchesSeam(relPath, tokens) {
     return tokens.some((token) => (token.endsWith('/') ? relPath.startsWith(token) : relPath === token));
 }
-// Plumbbob's own artifact plane (D17): everything under `.plumbbob/` is plumbbob's
-// bookkeeping — the tracked intent/build-log/checkpoints that ride the branch, and
-// the excluded control markers. It is never the user's code, so it never counts as
-// scope drift, and `revert`'s untracked cleanup must never delete it. checkpoint
-// stages this plane itself on every tick (the `[x]` flip, the build-log line), so
-// without this whitelist every checkpoint would cry wolf about its own writes.
+/**
+ * Whether a repo-relative path is plumbbob's own bookkeeping under `.plumbbob/`.
+ *
+ * That plane holds the tracked intent/build-log/checkpoints that ride the
+ * branch, plus the git-excluded control markers. It is never the user's code,
+ * so it never counts as scope drift, and `revert`'s untracked cleanup must
+ * never delete it. `checkpoint` stages this plane itself on every tick (the
+ * `[x]` flip, the build-log line), so without this whitelist every checkpoint
+ * would cry wolf about its own writes.
+ */
 export function isArtifactPath(relPath) {
     return relPath === '.plumbbob' || relPath.startsWith('.plumbbob/');
 }
-// The staged paths that fall outside the step's seam AND outside the artifact
-// 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 rather than flagging everything.
+/**
+ * The staged paths that fall outside the step's seam AND outside the artifact
+ * 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
+ * rather than flagging everything.
+ */
 export function scopeDrift(paths, seam) {
     if (seam.length === 0) {
         return [];
@@ -114,6 +145,14 @@ export function scopeDrift(paths, seam) {
     return paths.filter((p) => !matchesSeam(p, seam) && !isArtifactPath(p));
 }
 const DONE_WHEN = /\*\*done when:\*\*/i;
+/**
+ * Scrape step `n`'s title and done-when, best-effort.
+ *
+ * `title` is the text between the `N. [ ]` opener and the `**done when:**`
+ * marker; `doneWhen` is everything after it, with wrapped continuation lines
+ * joined until the first sub-bullet (the seam line). A missing section or step
+ * yields empty strings, never a refusal.
+ */
 export function parseStepMeta(content, step) {
     const slice = sliceStep(content, step);
     if (!slice.ok) {
@@ -139,7 +178,9 @@ export function parseStepMeta(content, step) {
         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')) {
         const m = /^#\s+(.+)$/.exec(line);
@@ -151,13 +192,18 @@ export function parseBuildTitle(content) {
 }
 const SCOPE_HEADER = /^\*\*Scope:\*\*\s*(.*)$/;
 const SCOPE_PLACEHOLDER = /^<.*>$/;
-// The build's default Conventional-Commit scope (D4): the `**Scope:**` header
-// field authored once at plan time, its value 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
-// (D7), so a freshly scaffolded, not-yet-edited build falls through to the next
-// scope rung (the build slug) rather than landing commits scoped `(<feature>)`.
-// null when the header is absent entirely — the pre-D4 shape (C2 back-compat).
+/**
+ * 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
+ * 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
+ * without one behaves the same way.
+ */
 export function parseBuildScope(content) {
     for (const line of content.split('\n')) {
         const m = SCOPE_HEADER.exec(line.trim());
@@ -169,6 +215,15 @@ export function parseBuildScope(content) {
     }
     return null;
 }
+/**
+ * Scrape the top-level `- ` bullets under a `## Heading`, each verbatim with
+ * its wrapped continuation lines joined into one string.
+ *
+ * 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
+ * about rather than dropping silently.
+ */
 export function scrapeBullets(content, heading) {
     const lines = content.split('\n');
     const start = lines.findIndex((l) => l.trim() === heading);
@@ -208,11 +263,16 @@ export function scrapeBullets(content, heading) {
     flush();
     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 em-dash or hyphen (the `Title —` separator) plus surrounding
+ * space, so a title never carries the marker that introduced its done-when.
+ */
 function stripTrailingDash(text) {
     return text.replace(/\s*[—-]+\s*$/, '').trim();
 }
+/**
+ * Shorthand for a failed SeamParse.
+ */
 function fail(error) {
     return { ok: false, error };
 }

package/dist/lib/latch.js

@@ -1,51 +1,70 @@
-// The approval latch (D64) — the ledger-plane predicate `checkpoint` evaluates
-// before its check gate (C4: cheap first; the gate already ran in the verify
-// tick). The work plane stays guidance (D10/D13 untouched); only the commit tick
-// is latched: a step may not land unless a human turn intervened since entry, the
-// human granted self-approval (a D65 one-turn grant from their literal prompt), or
-// the ledger is dormant. Five rows, evaluated in order, first hit wins; the refusal
-// message *is* the pause affordance. A standing `auto` in a settings file is NOT a
-// grant (D67): a model can write that file, and a grant it can forge is no grant —
-// so the latch reads it only to say so at the pause, never to allow. Reads
-// TURN/TICK/GRANT/isTTY only — never the host (C5). Named exports, node builtins.
+// 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
+// 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.
+// 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
+// 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,
+// 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,
-// how it ends (approval on the next turn lands it; `/pb-build` only starts the next
-// step), and names the only legitimate grants. 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.
+/**
+ * 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.
+ */
 const NO_TURN_MESSAGE = `plumbbob: checkpoint refused — no human turn since this step began. This is the
 pause: present the diff and the self-review, then end the turn. The human's approval on
 their next turn is what lets this land — re-run \`checkpoint\` then and stop at the
-boundary; \`/pb-build\` only starts the next step, it never lands this one. (An explicit
-\`/pb-build --auto\` or a step range in the human's own prompt is the only self-approval.)
+boundary; \`/plumbbob:build\` only starts the next step, it never lands this one. (An explicit
+\`/plumbbob:build --auto\` or a step range in the human's own prompt is the only self-approval.)
 `;
+/**
+ * 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.
+ */
 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
-message is the tick that lets it land on re-fire. (An explicit \`/pb-build --auto\` or a
+message is the tick that lets it land on re-fire. (An explicit \`/plumbbob:build --auto\` or a
 step range in the human's own prompt is the only self-approval.)
 `;
-// D67: a settings `auto` is no longer honored — a model can write that file, so a
-// grant it can forge is no grant. When one is set we say so at the point of refusal,
-// rather than silently ignoring it, and point at the only self-approval that works.
-const SETTINGS_AUTO_NOTE = `note: \`auto\` is set in settings but is no longer a grant (D67) — re-fire \`/pb-build --auto\` to self-approve.
+/**
+ * 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.
+ */
+const SETTINGS_AUTO_NOTE = `note: \`auto\` is set in settings but is no longer a grant (D67) — re-fire \`/plumbbob:build --auto\` to self-approve.
 `;
+/**
+ * The refusal for a range grant whose ceiling the landing step exceeds.
+ */
 function ceilingMessage(ceiling) {
     return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; re-fire to continue.\n`;
 }
-// The five-row matrix, in order, first hit wins. A `range` grant speaks only to
-// numbered steps: on a `--plan` checkpoint (step null) it neither allows nor
-// refuses, and the decision falls through to the turn comparison.
+/**
+ * The five-row matrix, in order, first hit wins.
+ *
+ * A `range` grant speaks only to numbered steps: on a `--plan` checkpoint (step
+ * null) it neither allows nor refuses, and the decision falls through to the
+ * turn comparison.
+ */
 export function evaluateLatch(input) {
     if (input.isTTY)
         return ALLOW; // 1 — a human at the keyboard
     if (input.turn === null || input.tick === null)
-        return ALLOW; // 2 — dormant / hand-built
+        return ALLOW; // 2 — dormant ledger / hand-built diff
     if (input.grant?.kind === 'auto')
-        return ALLOW; // 3 — one-turn grant (D65)
+        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;
@@ -53,14 +72,17 @@ export function evaluateLatch(input) {
     }
     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` no longer
-    // allows (D67); when one is set, the refusal notes it rather than honoring it.
+    // 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 };
 }
-// Parse a GRANT file's content (`auto` | `range <M>`). Anything else — including
-// a corrupted or hand-mangled file — contributes nothing (D27): no grant, never
-// an error.
+/**
+ * Parse a GRANT file's content (`auto` | `range <M>`).
+ *
+ * Anything else — including a corrupted or hand-mangled file — contributes
+ * nothing: no grant, never an error.
+ */
 export function parseGrant(raw) {
     const trimmed = raw.trim();
     if (trimmed === 'auto')
@@ -70,9 +92,12 @@ export function parseGrant(raw) {
         return { kind: 'range', ceiling: Number(range[1]) };
     return null;
 }
-// Gather the latch's inputs from the worktree and evaluate. `step` is the step
-// number being checkpointed, or null for the plan commit (which latches on the
-// TICK that `start` stamped).
+/**
+ * Gather the latch's inputs from the worktree and evaluate.
+ *
+ * `step` is the step number being checkpointed, or null for the plan commit
+ * (which latches on the TICK that `start` stamped).
+ */
 export function checkLatch(root, step) {
     return evaluateLatch({
         isTTY: process.stdin.isTTY === true,
@@ -80,10 +105,13 @@ export function checkLatch(root, step) {
         tick: readCount(tickPath(root)),
         grant: readGrant(root),
         step,
-        // Still read from the ladder — but only to decorate the pause (D67), not to allow.
+        // Read from the settings ladder — but only to decorate the pause, never to allow.
         settingsAuto: resolveBoolean(root, 'auto', false),
     });
 }
+/**
+ * The current GRANT, or null when the file is absent or unparseable.
+ */
 function readGrant(root) {
     try {
         return parseGrant(readFileSync(grantPath(root), 'utf8'));
@@ -92,9 +120,12 @@ function readGrant(root) {
         return null;
     }
 }
-// A ledger count, or null when the file is absent or holds garbage — malformed
-// contributes nothing, and an unreadable ledger reads as dormant (row 2) rather
-// than wedging the land.
+/**
+ * A ledger count, or null when the file is absent or holds garbage.
+ *
+ * Malformed contributes nothing, and an unreadable ledger reads as dormant
+ * (row 2) rather than wedging the land.
+ */
 function readCount(path) {
     try {
         const n = Number.parseInt(readFileSync(path, 'utf8').trim(), 10);