plumbbob 0.9.5 → 0.10.0

package/dist/lib/buildlog.js

@@ -1,14 +1,14 @@
-// Mutations to the active build-log.md — the human-facing ledger inside the
+// Mutations to the active build-log.md: the human-facing ledger inside the
 // build's tracked `builds/<slug>/` folder. `park` appends to its Park list;
 // `checkpoint` appends to its Log so the build's history accrues line-by-line
 // *as it happens* rather than being reconstructed at finish. The `## Steps`
 // mirror and `**Current step:**` line are CLI-owned: `build`, `checkpoint`,
 // and `revert` re-render them from intent.md so the ledger's top half tracks
-// reality without a model turn. Pure string transforms — no fs, no classes;
+// reality without a model turn. Pure string transforms: no fs, no classes;
 // callers own the IO so these stay trivially testable.
 /**
- * Append `line` after the last non-blank line of the `## <heading>` section —
- * i.e. just before the next `## ` heading or EOF.
+ * Append `line` after the last non-blank line of the `## <heading>` section:
+ * that is, just before the next `## ` heading or EOF.
  *
  * Returns null when the section is absent so the caller can report rather than
  * silently corrupt the doc.
@@ -33,9 +33,9 @@ export function appendToSection(content, heading, line) {
     return lines.join('\n');
 }
 /**
- * Replace the `**Current step:**` line with `**Current step:** <label>` —
- * `build` sets it to `<n> — <title>` when a step opens; `checkpoint`/`revert`
- * reset it to `none (at the boundary)`.
+ * Replace the `**Current step:**` line with `**Current step:** <label>`:
+ * `build` sets it to the step's number and title joined by an em dash when a
+ * step opens; `checkpoint`/`revert` reset it to `none (at the boundary)`.
  *
  * Returns null when the line is absent so the caller skips rather than
  * corrupting the doc.
@@ -50,14 +50,14 @@ export function setCurrentStep(content, label) {
     return lines.join('\n');
 }
 /**
- * Regenerate the `## Steps` mirror from intent.md's parsed steps — one
+ * Regenerate the `## Steps` mirror from intent.md's parsed steps: one
  * `- ☑/☐ N. <title>` line each, in order.
  *
  * Only the mirror's own `- ☑/☐` list lines are owned; the italic instructions
  * paragraph (and any other prose) is preserved, and exactly one blank line
  * separates it from the list. Returns null when the section is absent so the
  * caller skips rather than corrupting the doc. With no steps the mirror
- * renders empty — the plan is not authored yet — rather than inventing a
+ * renders empty (the plan is not authored yet) rather than inventing a
  * placeholder.
  */
 export function syncStepsSection(content, steps) {
@@ -92,9 +92,9 @@ function isMirrorLine(line) {
  * The Log line `checkpoint` writes for a landed step: dated, names the step
  * (its title when intent.md still carries it), and carries the short SHA.
  *
- * One line of the build's history — `/plumbbob:finish` reads these instead of
+ * One line of the build's history: `/plumbbob:finish` reads these instead of
  * re-narrating the build. `stats` is the optional compact receipt of what the
- * step cost (e.g. `2 red, 34m`) — null when nothing accrued, so a clean
+ * step cost (for example `2 red, 34m`): null when nothing accrued, so a clean
  * first-try step reads as a bare line.
  */
 export function checkpointLogLine(date, step, sha, title, stats = null) {

package/dist/lib/buildlogsync.js

@@ -1,22 +1,22 @@
-// Keep the build-log's top half — the `**Current step:**` line and the `## Steps`
-// mirror — in sync with intent.md, the build's plan document. The build-log is the
+// Keep the build-log's top half (the `**Current step:**` line and the `## Steps`
+// mirror) in sync with intent.md, the build's plan document. The build-log is the
 // human-facing ledger in the build's tracked `builds/<slug>/` folder; its top half
 // is CLI-owned so it never lies: `build` sets the current-step label when a step
 // opens, `checkpoint` and `revert` reset it to the boundary, and all three
 // re-render the mirror from intent.md's parsed steps so it tracks reality without
 // a model turn. The write is best-effort (a missing or hand-edited build-log never
-// fails a verb — the checkpoints ledger and intent.md stay the source of truth),
+// fails a verb: the checkpoints ledger and intent.md stay the source of truth),
 // matching how `checkpoint`'s Log append behaves.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { buildLogPath, intentPath } from "./sidecar.js";
 import { parseSteps } from "./orient.js";
 import { setCurrentStep, syncStepsSection } from "./buildlog.js";
-/** The Current-step label for no step in flight — the loop is at the step boundary. */
+/** The Current-step label for no step in flight: the loop is at the step boundary. */
 export const AT_BOUNDARY = 'none (at the boundary)';
 /**
- * The current-step label for an open step: `<n> — <title>`, or a bare `<n>`
- * when the step carries no title. `build` passes this; the boundary verbs pass
- * AT_BOUNDARY.
+ * The current-step label for an open step: the number and title joined by an
+ * em dash, or a bare `<n>` when the step carries no title. `build` passes
+ * this; the boundary verbs pass AT_BOUNDARY.
  */
 export function stepLabel(n, title) {
     return title !== null && title.trim().length > 0 ? `${n} — ${title.trim()}` : String(n);
@@ -26,7 +26,7 @@ export function stepLabel(n, title) {
  * `label` and re-render the `## Steps` mirror from intent.md.
  *
  * Each transform is skipped when its target is absent (null), and the whole
- * thing swallows any IO error — the ledger must never block the verb.
+ * thing swallows any IO error: the ledger must never block the verb.
  */
 export function syncBuildLogState(root, slug, label) {
     try {

package/dist/lib/check.js

@@ -11,7 +11,7 @@
 //     pointers, and an all-slots-skipped run REFUSES rather than green-lighting
 //     a repo checkride can't see (a vacuous pass is not a pass).
 // Checkride's stream discipline holds: human progress goes to stderr. Exit 0 is
-// green, 1 is red, 2 means the harness itself broke — reported distinctly,
+// green, 1 is red, 2 means the harness itself broke: reported distinctly,
 // because a misconfigured gate must not read as broken code (both still block).
 import { spawnSync } from 'node:child_process';
 import { runChecks, runDoctor } from 'checkride';
@@ -21,7 +21,7 @@ import { resolveString } from "./settings.js";
  * Probe whether the check gate would have anything to run in `root`.
  *
  * A configured `check` command answers yes on its own; otherwise checkride's
- * doctor detection runs in-process — the same pass `plumbbob doctor` reports
+ * doctor detection runs in-process: the same pass `plumbbob doctor` reports
  * as a table. `start` reads this to surface "nothing to check" at plan time,
  * while the human is still deciding, instead of at the first refused
  * checkpoint.
@@ -37,19 +37,19 @@ export async function detectGate(root) {
     }
     catch {
         // A broken checkride harness is a different problem with its own reporters
-        // (doctor's ✗ row, runCheck's exit 2) — the plan-time probe stays quiet
+        // (doctor's ✗ row, runCheck's exit 2); the plan-time probe stays quiet
         // rather than mislabeling it "nothing to check".
         return { configured: null, detected: true };
     }
 }
 /**
  * Checkride's always-on repo checks: the adapters that resolve with no tool
- * config of their own — the built-in `links` slot, the pnpm-audit security
+ * config of their own: the built-in `links` slot, the pnpm-audit security
  * scan, the publint/attw package-shape probes, and the pack/smoke/snippets
  * publish-bundle slots. Several are named for their shape rather than because
  * a bare directory reports them: `publint`/`attw` resolve off a devDependency,
- * `build` off a `scripts.build` entry — which says the package can be built,
- * not that checkride can see the code that goes into it — and `snippets`
+ * `build` off a `scripts.build` entry (which says the package can be built,
+ * not that checkride can see the code that goes into it), and `snippets`
  * carries two adapters since checkride 0.10.2, so the dist-facing
  * `snippets-dist` is named beside it (this list matches ADAPTER names, not
  * slot names). Every one of them but `links` is an opt-in slot, so a default
@@ -72,7 +72,7 @@ const ALWAYS_ON_ADAPTERS = [
 ];
 /**
  * The detection rule, shared by `start`'s probe and doctor's callout: some
- * tool slot beyond the always-on family has an adapter — i.e. checkride can
+ * tool slot beyond the always-on family has an adapter: that is, checkride can
  * see the CODE (a tsconfig, a test runner, a linter…), not just the repo.
  */
 export function gateDetectsTools(checks) {
@@ -90,7 +90,7 @@ export function gateDetectsTools(checks) {
  */
 export async function runCheck(root, flags = {}, commandFlag) {
     if (gateIsRunningFor(root)) {
-        // This repo re-entering its OWN gate is never a slow gate — it is a
+        // This repo re-entering its OWN gate is never a slow gate: it is a
         // recursion whose next generation forks wider than this one. Exit 2 (the
         // harness broke), not 1: nothing has been learned about the code. A gate on
         // a DIFFERENT root is ordinary nested work (the test suite gating its
@@ -105,7 +105,7 @@ export async function runCheck(root, flags = {}, commandFlag) {
 }
 /**
  * The spawn override: stream the configured command's own output to the
- * terminal and return its exit code — the command is trusted verbatim, no
+ * terminal and return its exit code: the command is trusted verbatim, no
  * interpretation.
  */
 function runCommand(root, command, flags) {
@@ -133,7 +133,7 @@ async function runCheckride(root, flags) {
             include: flags.include !== undefined ? [...flags.include] : null,
             // Checkride's own vacuous-green refusal (0.10.2): zero checks executed is
             // an error, not a pass. It overlaps the refusal below and never reaches
-            // the human — our predicate is the broader one (it also catches a
+            // the human: our predicate is the broader one (it also catches a
             // links-only run, where a check DID execute) and fires first, so
             // plumbbob's message and its exit 1 are what a reader sees. Kept anyway:
             // it is the contract checkride asks a gate to run under, so a future
@@ -145,7 +145,7 @@ async function runCheckride(root, flags) {
     }
     catch (err) {
         // The harness broke, not the code: a malformed checkride.config.json or
-        // the like. Checkride's own CLI maps this to exit 2; so do we — a
+        // the like. Checkride's own CLI maps this to exit 2; so do we: a
         // misconfigured gate must report distinctly from red.
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`plumbbob: the check gate itself failed — ${message}\n` +
@@ -156,7 +156,7 @@ async function runCheckride(root, flags) {
         // Zero-config checkride skips slots with no detected tool; a repo it can't
         // see must refuse, not vacuously green-light the checkpoint. The built-in
         // `links` slot is always-on (empty detect list), so it alone proves
-        // nothing about the code — a links-only run is still vacuous.
+        // nothing about the code: a links-only run is still vacuous.
         process.stderr.write('plumbbob: checkride found nothing to check in this repo — refusing to call that green.\n' +
             '  Add tool configs (tsconfig, vitest, …) or a checkride.config.json custom check,\n' +
             '  or set the "check" key in .plumbbob/settings.json to gate through another command.\n');
@@ -171,7 +171,7 @@ async function runCheckride(root, flags) {
  * Name the failing slots and where their raw diagnostics landed, so the agent
  * (verify) reads the tool's own JSON instead of scraping scrollback.
  *
- * The summary is the canonical pointer — `output_file` is the adapter's
+ * The summary is the canonical pointer: `output_file` is the adapter's
  * preferred name, but non-JSON output falls back to `.check/<slot>.stdout.txt`.
  */
 function reportFailingSlots(summary) {
@@ -184,7 +184,7 @@ function reportFailingSlots(summary) {
     process.stderr.write(`plumbbob: failing slots:\n${lines.join('\n')}\n  Full report: .check/summary.json\n`);
 }
 /**
- * True when any narrowing flag was passed — the trigger for the spawn path's
+ * True when any narrowing flag was passed: the trigger for the spawn path's
  * flags-are-ignored warning.
  */
 function hasFlags(flags) {

package/dist/lib/commitbody.js

@@ -0,0 +1,72 @@
+// The `--body` stdin reader shared by `checkpoint` and `finish`: both verbs
+// take a commit body on fd 0 via a single-quoted heredoc (`--body <<'BODY'`),
+// never as an argument value. `evaluateCommitBody` is the pure decision over
+// an already-known fd-0 shape, so every shape is a direct unit test with no
+// fd tricks; `readCommitBody` gathers the real one: the mirror of latch.ts's
+// evaluateLatch/checkLatch split.
+//
+// Four fd-0 shapes reach this in practice: a heredoc is a regular file, a
+// pipe is a FIFO, an interactive terminal is a TTY, and an agent harness
+// hands the CLI a socket. The first three already degrade safely: a TTY
+// skips the read (it would never send EOF), a regular file/FIFO/`/dev/null`
+// read to EOF and fall back to the caller's own default body when empty. A
+// socket also never sends EOF on its own, so the same blind `readFileSync(0)`
+// blocks forever and, worse, drops the requested body silently. Refuse
+// instead: a silently dropped body reads as success.
+import { fstatSync, readFileSync } from 'node:fs';
+/**
+ * The refusal shown when `--body` is asked to read a socket: names the form
+ * that works so the retry succeeds instead of guessing again.
+ */
+export const SOCKET_REFUSAL = "plumbbob: --body refuses — stdin is a socket, and a socket never sends EOF the way a heredoc does, so the read would block forever and the body would be lost. Redirect it in with the `--body <<'BODY'` … `BODY` heredoc form instead.\n";
+/**
+ * Decide the `--body` outcome from an already-known fd-0 shape.
+ *
+ * Absent flag or a TTY both mean "don't read": the caller's fallback body
+ * applies. `other` covers a heredoc (regular file), a pipe (FIFO), and
+ * `/dev/null` (character device) alike: each is read to EOF, and an empty or
+ * failed read degrades to the same fallback an absent `--body` would use.
+ */
+export function evaluateCommitBody(hasBodyFlag, shape, read) {
+    if (!hasBodyFlag || shape === 'tty') {
+        return { ok: true, body: null };
+    }
+    if (shape === 'socket') {
+        return { ok: false, message: SOCKET_REFUSAL };
+    }
+    try {
+        const raw = read().trimEnd();
+        return { ok: true, body: raw.length > 0 ? raw : null };
+    }
+    catch {
+        return { ok: true, body: null };
+    }
+}
+/**
+ * Read the `--body` commit body from the real fd 0, or refuse when it can
+ * never deliver one.
+ *
+ * `checkpoint` and `finish` both call this where each used to call its own
+ * copy of `bodyArg`: one implementation, one refusal string, so the two
+ * verbs cannot drift apart on the wording.
+ */
+export function readCommitBody(args) {
+    return evaluateCommitBody(args.includes('--body'), stdinShape(), () => readFileSync(0, 'utf8'));
+}
+/**
+ * The fd-0 shape the guard cares about: a TTY skips the read (never sends
+ * EOF), a socket refuses (the same problem, but silent), everything else is
+ * read as before. An unreadable fd (no stdin attached at all) is treated the
+ * same as any other shape; the read attempt that follows fails safely.
+ */
+function stdinShape() {
+    if (process.stdin.isTTY === true) {
+        return 'tty';
+    }
+    try {
+        return fstatSync(0).isSocket() ? 'socket' : 'other';
+    }
+    catch {
+        return 'other';
+    }
+}

package/dist/lib/commitmsg.js

@@ -1,8 +1,8 @@
 // Conventional-Commit subject assembly. Plumbbob's commit subjects read as
-// `type(scope): description` — real feat/fix/chore types and a real parenthesised
-// scope — so `git log` speaks the same grammar as the rest of the branch. The
+// `type(scope): description` (real feat/fix/chore types and a real parenthesised
+// scope) so `git log` speaks the same grammar as the rest of the branch. The
 // `plumbbob`/`step N` identifiers ride a marker line at the head of the body,
-// which `withMarker` prepends — so `git log --grep plumbbob` finds every plumbbob
+// which `withMarker` prepends, so `git log --grep plumbbob` finds every plumbbob
 // commit. Functional and procedural, node builtins only, no gate: these only
 // shape a string the CLI is about to commit.
 /**
@@ -10,7 +10,7 @@
  * prefix on a step title.
  *
  * Anchoring on this closed set keeps a prose title like `Note: rewire the
- * cache` from being misread as a `Note` type — only these words, immediately
+ * cache` from being misread as a `Note` type; only these words, immediately
  * followed by an optional `(scope)`, an optional `!`, and a colon, count as an
  * author-supplied prefix.
  */
@@ -23,7 +23,7 @@ const PREFIX = new RegExp(`^(${TYPES.join('|')})(?:\\(([^)]+)\\))?(!)?:\\s+(.+)$
  *
  * `feat(escape-hatch): add the flag` → { type:'feat', scope:'escape-hatch',
  * breaking:false, description:'add the flag' }. A title with no recognised
- * prefix comes back whole as the description with a null type/scope — the
+ * prefix comes back whole as the description with a null type/scope; the
  * caller then defaults the type and fills the scope from the build.
  */
 export function parseConventionalTitle(title) {
@@ -46,11 +46,11 @@ export function conventionalSubject(parts) {
 /**
  * A Conventional subject from a step title, filling gaps from the build.
  *
- * An author-written prefix (`fix(parser): …`) is honoured verbatim — its type,
+ * An author-written prefix (`fix(parser): …`) is honoured verbatim: its type,
  * scope, breaking marker, and exact wording all win. A bare prose title
  * defaults to `defaultType` and the build `scope`, and gets its sentence-case
  * opener de-capitalised (`Add the flag` → `add the flag`) to match
- * Conventional style — while an all-caps acronym start (`API`, `OAuth`) is
+ * Conventional style, while an all-caps acronym start (`API`, `OAuth`) is
  * left alone.
  */
 export function subjectFromTitle(title, defaultType, scope) {

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.