@forwardimpact/libwiki 0.3.0 → 0.3.1

package/src/commands/ledger.js

@@ -38,7 +38,7 @@ function nextFreeIds(fold, kind, count) {
   return ids;
 }
 
-/** Read the ordered anchor sequence and fold it, resolving the repo slug. */
+/** Read the ordered anchor sequence, fold it, and resolve the repo slug. */
 async function loadFold({ gitClient, ghClient, wikiDir, issue }) {
   const url = await gitClient.remoteGetUrl("origin", { cwd: wikiDir });
   const { owner, repo } = parseOwnerRepo(url);
@@ -70,10 +70,10 @@ async function allocate(env, options) {
     };
   }
   const { fold, owner, repo } = await loadFold(env);
-  // Backfill registers an anchor for ids that predate the anchor surface, named
-  // explicitly via --ids; their event keys already exist in history. A plain
-  // allocate mints the next free ids of the kind. The conflict detector at
-  // rebuild guards against double-registering an id that already has an anchor.
+  // Backfill registers an anchor for ids that predate the anchor surface. The
+  // --ids flag names them, and their event keys already exist in history. A
+  // plain allocate mints the next free ids of the kind. The conflict detector
+  // at rebuild guards against an id that already has an anchor.
   let ids;
   if (options.ids) {
     ids = options.ids
@@ -93,8 +93,8 @@ async function allocate(env, options) {
     ids = nextFreeIds(fold, kind, count);
   }
   const body = renderAnchorBody({ kind, ids, event, note: options.note ?? "" });
-  // The anchor publication is the allocation; no projection is written here.
-  // The printed ids are provisional — a rebuild over the published sequence is
+  // The anchor publication is the allocation. This code writes no projection.
+  // The printed ids are provisional. A rebuild over the published sequence is
   // authoritative and resolves any concurrent interleave first-published-wins.
   await ghClient.apiPost(
     `repos/${owner}/${repo}/issues/${env.issue}/comments`,
@@ -118,7 +118,7 @@ function readLedgerPage(runtime, wikiDir) {
     : "";
 }
 
-/** Project the anchor record onto the ledger-page body, preserving cited prose. */
+/** Project the anchor record onto the ledger-page body. Keep cited prose. */
 async function project(env, options) {
   const { runtime, wikiDir } = env;
   const labelMode = options.gapped ? "gapped" : "renumber";
@@ -183,9 +183,9 @@ const SUBS = { allocate, rebuild, verify };
 /**
  * `gemba-wiki ledger <allocate|rebuild|verify>` — the allocation procedure that
  * keeps identity off the merge-contested page. Allocation publishes an anchor
- * comment to the obstacle issue with no projection write at allocation time;
- * rebuild and verify project the anchor record onto the ledger page and MEMORY
- * row, preserving anchor-cited prose.
+ * comment to the obstacle issue and writes no projection at allocation time.
+ * Rebuild and verify project the anchor record onto the ledger page and MEMORY
+ * row. Both keep anchor-cited prose.
  */
 export async function runLedgerCommand(ctx) {
   const { runtime, gitClient, ghClient } = ctx.deps;

package/src/commands/log.js

@@ -28,8 +28,8 @@ function commonContext(runtime, options) {
 }
 
 function lastDateHeading(text) {
-  // Match `## YYYY-MM-DD` at the start of a line, optionally followed by
-  // suffix text (e.g. `## 2026-05-19 (third activation)`).
+  // Match `## YYYY-MM-DD` at the start of a line. Suffix text can follow
+  // (e.g. `## 2026-05-19 (third activation)`).
   const re = new RegExp(WEEKLY_LOG_SEAM_RE.source, "gm");
   let last = null;
   let match;
@@ -38,12 +38,13 @@ function lastDateHeading(text) {
 }
 
 /**
- * Rotate before an append, never blocking it. A bisecting seal may now produce
- * multiple parts; the append still proceeds against the fresh current file. An
- * `incomplete` residue (a lone over-cap day-section sealed as its own part —
- * never the live file) is surfaced to stderr but does not block the append. A
- * thrown fs error is reported and swallowed: the writer rolled back, so the
- * (intact) current file still receives the new entry.
+ * Rotate before an append. The rotation never blocks the append. A seal that
+ * bisects can now produce multiple parts, and the append still proceeds
+ * against the fresh current file. An `incomplete` residue is a lone over-cap
+ * day-section sealed as its own part, never the live file. The function
+ * reports that residue to stderr, and it does not block the append. The
+ * function reports a thrown fs error and swallows it. The writer rolled back,
+ * so the (intact) current file still receives the new entry.
  */
 function rotateBeforeAppend(wikiRoot, agent, today, body, runtime) {
   try {
@@ -60,7 +61,7 @@ function rotateBeforeAppend(wikiRoot, agent, today, body, runtime) {
       createLogger("wiki", runtime).warn(
         "log",
         `day-section ${res.residue.section} alone exceeds the budget ` +
-          `(${res.residue.lines} lines, ${res.residue.words} words); ` +
+          `(${res.residue.lines} lines, ${res.residue.words} words), ` +
           `sealed as ${res.residue.path} for manual recovery`,
       );
     }
@@ -70,10 +71,11 @@ function rotateBeforeAppend(wikiRoot, agent, today, body, runtime) {
 }
 
 /**
- * Report the just-written weekly log's budget state — value, cap, and remaining
- * headroom for both the line and word budget — so a writer sees the ceiling
- * before composing the next entry rather than discovering it via a red gate.
- * Runs after every successful append, on the rotated and non-rotated path alike.
+ * Report the budget state of the weekly log just written. The report gives the
+ * value, the cap, and the headroom left for both the line budget and the word
+ * budget. A writer then sees the ceiling before the next entry, and does not
+ * find it at a red gate. This runs after every successful append, on the
+ * rotated path and the non-rotated path alike.
  */
 function reportBudget(target, runtime) {
   const text = runtime.fsSync.existsSync(target)
@@ -131,13 +133,13 @@ function runNote(runtime, options) {
     return { ok: false, code: 2 };
   }
   const fieldBlock = `### ${options.field}\n\n${options.body}\n`;
-  // Conservative budget: assume we'll prepend a date heading. Rotate on the
-  // larger `withHeading` body so the word/line projection never under-counts.
+  // Conservative budget: assume a prepended date heading. Rotate on the larger
+  // `withHeading` body so the word/line projection never under-counts.
   const withHeading = `## ${today}\n\n${fieldBlock}`;
   rotateBeforeAppend(wikiRoot, agent, today, withHeading, runtime);
   const target = weeklyLogPath(wikiRoot, agent, today);
-  // Append under the open entry if the file's last `## YYYY-MM-DD` is today;
-  // otherwise open a new entry by prepending a date heading.
+  // Append under the open entry if the file's last `## YYYY-MM-DD` is today.
+  // If it is not, prepend a date heading to open a new entry.
   const existing = runtime.fsSync.existsSync(target)
     ? runtime.fsSync.readFileSync(target, "utf-8")
     : "";

package/src/commands/memo.js

@@ -64,7 +64,10 @@ function writeBroadcast(
   return { ok: true };
 }
 
-/** Write a memo to a target agent's summary file (or broadcast to all except the sender); the sender is the required --from flag. */
+/**
+ * Write a memo to a target agent's summary file. A broadcast reaches every
+ * agent except the sender. The required --from flag names the sender.
+ */
 export function runMemoCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;

package/src/commands/product-mix.js

@@ -5,10 +5,10 @@ import { parseRepoSlug } from "../issue-list-renderer.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 
-// Resolve the monorepo's `owner/repo` slug the way `refresh.js` does: an
-// explicit `FIT_GH_REPO` env override (sandbox proxy URLs), else the origin
-// remote parsed via the injected git client. Returns null when nothing
-// parseable is found, in which case `gh` falls back to its own cwd resolution.
+// Resolve the monorepo's `owner/repo` slug the way `refresh.js` does. An
+// explicit `FIT_GH_REPO` env override wins (sandbox proxy URLs). Otherwise the
+// injected git client parses the origin remote. Returns null when nothing
+// parses. `gh` then falls back to its own cwd resolution.
 async function deriveRepo(gitClient, cwd, env) {
   if (env.FIT_GH_REPO) return env.FIT_GH_REPO;
   if (!gitClient) return null;
@@ -20,8 +20,8 @@ async function deriveRepo(gitClient, cwd, env) {
   }
 }
 
-// A missing token is non-fatal: `gh` may still resolve ambient auth, and a
-// hard fetch failure downstream collapses to a logged warning and no row.
+// A missing token is non-fatal. `gh` can still resolve ambient auth. A hard
+// fetch failure downstream collapses to a logged warning and no row.
 async function resolveToken() {
   try {
     return (await createScriptConfig("wiki")).ghToken();
@@ -30,8 +30,8 @@ async function resolveToken() {
   }
 }
 
-// `gh pr list` returns at most this many PRs; a window that hits the cap is
-// truncated, so the caller warns rather than silently undercounting.
+// `gh pr list` returns at most this many PRs. A window that hits the cap is
+// truncated, so the caller warns and does not undercount in silence.
 const FETCH_LIMIT = 200;
 
 // Fetch merged PRs in `[since, until]` and return their parsed JSON, or null on
@@ -60,7 +60,7 @@ async function fetchMergedPrs({ runtime, cwd, repo, since, until, token }) {
 }
 
 // Tally merged PRs by their classification label. A PR with neither label is
-// unlabeled; `product` wins if both are somehow present.
+// unlabeled. `product` wins if both labels are somehow present.
 function countByLabel(prs) {
   const counts = { product: 0, internal: 0, unlabeled: 0 };
   for (const pr of prs) {
@@ -75,10 +75,11 @@ function countByLabel(prs) {
 /**
  * Emit the product-vs-internal mix of merged PRs as a `product_share` metric
  * row. Counts PRs merged in `[since, until]` by their `product` / `internal`
- * label and appends `product_share = round(product / (product + internal) *
- * 100)` to `wiki/metrics/product-mix/<YYYY>.csv` via the `gemba-xmr record` write
- * path. Deterministic — re-running over the same merged PRs yields the same
- * value. A window with no labeled merged PRs emits no row (avoids a 0/0 ratio).
+ * label. Appends `product_share = round(product / (product + internal) * 100)`
+ * to `wiki/metrics/product-mix/<YYYY>.csv` through the `gemba-xmr record`
+ * write path. The result is deterministic. A second run over the same merged
+ * PRs yields the same value. A window with no labeled merged PRs emits no row
+ * (it avoids a 0/0 ratio).
  */
 export async function runProductMixCommand(ctx) {
   const { runtime, gitClient } = ctx.deps;
@@ -101,7 +102,7 @@ export async function runProductMixCommand(ctx) {
   if (prs.length >= FETCH_LIMIT) {
     logger.warn(
       "product-mix",
-      `window ${since}..${until} hit the ${FETCH_LIMIT}-PR fetch cap; product_share may undercount`,
+      `window ${since}..${until} hit the ${FETCH_LIMIT}-PR fetch cap, so product_share may undercount`,
     );
   }
 
@@ -110,7 +111,7 @@ export async function runProductMixCommand(ctx) {
   if (total === 0) {
     logger.info(
       "product-mix",
-      `no labeled merged PRs in ${since}..${until}; emitting no row`,
+      `no labeled merged PRs in ${since}..${until}, so this run emits no row`,
     );
     return { ok: true };
   }

package/src/commands/refresh.js

@@ -30,11 +30,12 @@ async function deriveParentRepo(gitClient, parentDir, env) {
 }
 
 // Compose the agent-experiments block body. On a successful tracker query the
-// body is a fresh last-successful-sync stamp followed by freshly rendered,
-// label-re-checked, sanitized item lines. On a tracker failure the previously
-// materialized body (stamp + items) is preserved verbatim so boot keeps serving
-// the last good routing surface instead of an empty one, and the timestamp is
-// not advanced, so staleness stays auditable from the stamp.
+// body is a fresh last-successful-sync stamp, then freshly rendered,
+// label-re-checked, sanitized item lines. On a tracker failure the function
+// keeps the body it materialized before (stamp + items) verbatim. Boot then
+// still serves the last good routing surface. It does not serve an empty one.
+// The function does not advance the timestamp, so the stamp keeps
+// staleness auditable.
 async function renderAgentExperimentsBlock(block, lines, ghContext, runtime) {
   const priorBody = lines.slice(block.openLine + 1, block.closeLine);
   try {
@@ -91,8 +92,8 @@ function spliceBlock(lines, block, rendered) {
   );
 }
 
-// A missing current-month storyboard is non-fatal: return null so the caller
-// can create it (see createStoryboardSkeleton) rather than fail the job.
+// A missing current-month storyboard is non-fatal. Return null so the caller
+// can create it (see createStoryboardSkeleton) and does not fail the job.
 function readStoryboardOrNull(runtime, storyboardPath) {
   try {
     return runtime.fsSync.readFileSync(storyboardPath, "utf-8");
@@ -104,10 +105,11 @@ function readStoryboardOrNull(runtime, storyboardPath) {
 
 // Create the current-month storyboard from the minimal skeleton when it does
 // not exist. Refresh is the deterministic "freshen the wiki" step and runs
-// before the session (kata-agent pre-run), so creating here guarantees the file
-// is on disk before participants look for it — without any lead having a write
-// tool. The skeleton carries the section structure and the generic issue-list
-// markers; the render pass below fills them and participants seed metric blocks.
+// before the session (kata-agent pre-run). Creation here guarantees the file
+// is on disk before participants look for it, and no lead needs a write tool.
+// The skeleton carries the section structure and the generic issue-list
+// markers. The render pass below fills them, and participants seed metric
+// blocks.
 function createStoryboardSkeleton(runtime, storyboardPath, logger) {
   const skeleton = renderStoryboardSkeleton(currentDayIso(runtime));
   runtime.fsSync.mkdirSync(path.dirname(storyboardPath), { recursive: true });
@@ -116,12 +118,12 @@ function createStoryboardSkeleton(runtime, storyboardPath, logger) {
   return skeleton;
 }
 
-// Drop every MEMORY.md `## Active Claims` row past its `expires_at`, writing the
+// Drop every MEMORY.md `## Active Claims` row past its `expires_at`. Write the
 // trimmed table back in place. Refresh is the deterministic "freshen the wiki"
-// step, so clearing lapsed claims belongs here alongside the storyboard render;
-// it runs whether or not the storyboard has marker blocks to regenerate. The
-// write is local, mirroring the storyboard splice — the caller's push publishes
-// it. A missing wiki or claims table is a clean no-op.
+// step, so a sweep of lapsed claims belongs here beside the storyboard render.
+// It runs whether or not the storyboard has marker blocks to regenerate. The
+// write is local and mirrors the storyboard splice. The caller's push
+// publishes it. A missing wiki or claims table is a clean no-op.
 function clearExpiredClaims(runtime, options, today, logger) {
   const memPath = path.join(resolveWikiRoot(runtime, options), "MEMORY.md");
   if (!runtime.fsSync.existsSync(memPath)) return;
@@ -148,8 +150,9 @@ export async function runRefreshCommand(ctx) {
   const logger = createLogger("wiki", runtime);
   const projectRoot = resolveProjectRoot(runtime);
 
-  // Independent of the storyboard render below (and its early returns), so a
-  // wiki with no storyboard or no marker blocks still gets its claims swept.
+  // This is independent of the storyboard render below (and its early
+  // returns). The sweep still runs on a wiki with no storyboard and on a wiki
+  // with no marker blocks.
   clearExpiredClaims(runtime, options, currentDayIso(runtime), logger);
 
   const storyboardPath = path.resolve(
@@ -171,14 +174,14 @@ export async function runRefreshCommand(ctx) {
   try {
     token = config.ghToken();
   } catch {
-    // Missing token is non-fatal; issue-list renders will fail with a stderr
-    // warning and the block will collapse to the notice line.
+    // A missing token is non-fatal. An issue-list render then fails with a
+    // stderr warning, and the block collapses to the notice line.
   }
   // Spawn `gh` from the project root so it resolves the monorepo's origin
   // instead of whatever git context the caller's cwd happens to be in (the
   // wiki sibling repo, a subagent worktree, a service dir, etc.). Also
-  // resolve an explicit owner/repo slug so `gh` works when origin has been
-  // rewritten to a proxy URL (sandbox environments) — `FIT_GH_REPO` env
+  // resolve an explicit owner/repo slug so `gh` works when a proxy URL
+  // replaced origin (sandbox environments). The `FIT_GH_REPO` env var
   // overrides the parsed origin.
   const ghContext = {
     cwd: projectRoot,

package/src/commands/rotate.js

@@ -6,8 +6,8 @@ import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 /**
  * Rotate the current weekly log to a sealed part file. Refuses an under-budget
- * target (exit 2) unless `--force`; the header-only floor stays a zero-exit
- * no-op even under `--force`; a missing target exits 2.
+ * target (exit 2) unless you pass `--force`. The header-only floor stays a
+ * zero-exit no-op even under `--force`. A missing target exits 2.
  */
 export function runRotateCommand(ctx) {
   const { runtime } = ctx.deps;
@@ -21,8 +21,8 @@ export function runRotateCommand(ctx) {
   const agent = resolved.agent;
   const wikiRoot = resolveWikiRoot(runtime, options);
   const today = options.today || currentDayIso(runtime);
-  // Name the resolved target before any seal: the file follows from agent +
-  // current week, not from any audit finding.
+  // Name the resolved target before any seal. The file follows from agent plus
+  // current week. No audit finding decides it.
   runtime.proc.stdout.write(
     `target → ${weeklyLogPath(wikiRoot, agent, today)}\n`,
   );
@@ -43,8 +43,8 @@ export function runRotateCommand(ctx) {
   }
   switch (result.status) {
     case "noop":
-      // The header-only floor is a benign no-op; an under-budget or missing
-      // target fails closed so a stale/typo'd invocation cannot pass silently.
+      // The header-only floor is a benign no-op. An under-budget or missing
+      // target fails closed. A stale or typo'd invocation cannot pass silently.
       if (result.reason === "floor") {
         runtime.proc.stdout.write(`no rotation needed for ${agent}\n`);
         return { ok: true };
@@ -79,14 +79,15 @@ export function runRotateCommand(ctx) {
         `section ${section} alone exceeds the budget ` +
           `(${lines} lines, ${words} words) and has no finer seam to split ` +
           `at: ${residuePath}\n` +
-          `recover it by hand — shorten the section ` +
+          `recover it by hand. Shorten the section ` +
           `(see the memory protocol's manual-recovery convention)`,
       );
       return { ok: false, code: 1 };
     }
     default:
       // Defensive: the tagged union is exhaustive above, so this is
-      // unreachable; kept so a future status can't fall through to no return.
+      // unreachable. It stays so a future status cannot fall through to no
+      // return.
       return { ok: true };
   }
 }

package/src/commands/sync.js

@@ -10,17 +10,17 @@ import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 /**
  * Commit all wiki changes and push them through the secret-gated push path.
- * A detected secret or unavailable scanner fails the command closed and names
- * the cause on stderr without attempting the push; a clean write pushes or
- * reports nothing to push. The post-push tier-1 integrity detections surface in
- * the output; they never gate the push.
+ * A detected secret or unavailable scanner fails the command closed. It names
+ * the cause on stderr and never tries the push. A clean write pushes, or it
+ * reports nothing to push. The post-push tier-1 integrity detections surface
+ * in the output. They never gate the push.
  */
 export async function runPushCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   await wikiSync.inheritIdentity();
 
-  // A caller that knows its narrower write-set passes `--paths` (repeatable);
-  // the bare session-close invocation passes none and lands the session's own
+  // A caller that knows its narrower write-set passes `--paths` (repeatable).
+  // The bare session-close invocation passes none. It lands the session's own
   // dirty set under per-session checkout isolation.
   const paths = ctx.options?.paths?.length ? ctx.options.paths : undefined;
 
@@ -28,17 +28,19 @@ export async function runPushCommand(ctx) {
   try {
     result = await wikiSync.commitAndPush("wiki: update from session", paths);
   } catch (err) {
-    // Honest CLI contract (the honest-CLI contract): non-zero on any non-land push
-    // failure, and on the ancestry guard's refusal (the ancestry guard). The Stop-hook
-    // recipe maps this to a stop-blocking exit; CI steps see a loud failure.
+    // Honest CLI contract (the honest-CLI contract): non-zero on any non-land
+    // push failure, and on the ancestry guard's refusal (the ancestry guard).
+    // The Stop-hook recipe maps this to a stop-blocking exit. CI steps see a
+    // loud failure.
     if (err instanceof WikiPushFailure || err instanceof AncestryRefusal) {
       runtime.proc.stderr.write(`${err.message}\n`);
       return { ok: false, code: 1 };
     }
     throw err;
   }
-  // Fail the command closed on a secret-gate refusal (secret detected or scanner
-  // unavailable); a clean push falls through to the normal reporting below.
+  // Fail the command closed on a secret-gate refusal (secret detected or
+  // scanner unavailable). A clean push falls through to the normal report
+  // below.
   const refusal = refusalEnvelope(runtime, result);
   if (refusal) return refusal;
   if (result.landed) {
@@ -52,7 +54,13 @@ export async function runPushCommand(ctx) {
   return { ok: true };
 }
 
-/** Fetch and rebase the local wiki on origin/master; on rebase conflict, return a non-zero envelope with a message to resolve manually or push first. After a clean pull, the tier-2 lane-record sweep surfaces any previous-session content absent at the fetched tip; it never gates the boot. */
+/**
+ * Fetch and rebase the local wiki on origin/master. On a rebase conflict,
+ * return a non-zero envelope. Its message tells the caller to resolve the
+ * conflict by hand or to push first. After a clean pull, the tier-2
+ * lane-record sweep surfaces any previous-session content absent at the
+ * fetched tip. The sweep never gates the boot.
+ */
 export async function runPullCommand(ctx) {
   const { runtime, wikiSync, gitClient } = ctx.deps;
   await wikiSync.inheritIdentity();
@@ -64,19 +72,20 @@ export async function runPullCommand(ctx) {
     if (err instanceof WikiPullConflict) {
       createLogger("wiki", runtime).error(
         "pull",
-        "rebase conflict — local divergence detected; resolve manually or push first",
+        "rebase conflict from local divergence. Resolve it by hand or push first",
       );
       return { ok: false, code: 1 };
     }
     throw err;
   }
 
-  // Tier-2 sweep on the just-rebased tree. Detection-only: any failure degrades
-  // to no detections, never throws into the flow, never changes the exit code.
+  // Tier-2 sweep on the just-rebased tree. This detects only. Any failure
+  // degrades to no detections. It never throws into the flow. It never changes
+  // the exit code.
   try {
     const wikiDir = resolveWikiRoot(runtime, ctx.options);
-    // `--today` (ISO date) overrides the wall clock for deterministic tests;
-    // a malformed value falls back to the runtime clock rather than NaN.
+    // `--today` (ISO date) overrides the wall clock for deterministic tests.
+    // A malformed value falls back to the runtime clock instead of NaN.
     const today = ctx.options.today
       ? Date.parse(ctx.options.today)
       : Number.NaN;

package/src/conflict-markers.js

@@ -1,36 +1,36 @@
-// Structural detector for unresolved git conflict markers, shared by the wiki
-// audit's `conflict.markers` rule (audit/conflict-markers-rule.js) and the
-// WikiSync pre-push guard (wiki-sync.js). One home so the two layers cannot
+// Structural detector for unresolved git conflict markers. The wiki audit's
+// `conflict.markers` rule (audit/conflict-markers-rule.js) and the WikiSync
+// pre-push guard (wiki-sync.js) both use it. One home so the two layers cannot
 // drift on what counts as a marker.
 //
-// Detection is line-anchored and structural, not a naive grep, so it does not
-// fire on markers legitimately quoted in prose:
+// Detection is line-anchored and structural. It is not a naive grep, so it
+// does not fire on markers legitimately quoted in prose:
 //
 // - Open (`<<<<<<<`) and close (`>>>>>>>`) marker lines fire UNCONDITIONALLY,
 //   per file. A seal rotation can sever one conflict block across two sealed
-//   files (the open in one, the separator + close in the other); a
-//   complete-in-file-block matcher would miss both, so each marker form stands
+//   files (the open in one, the separator + close in the other). A matcher for
+//   a complete in-file block would miss both, so each marker form stands
 //   alone. The single-space-or-end-of-line guard after the 7-char run admits
 //   the stash-pop label forms (`<<<<<<< Updated upstream`,
-//   `>>>>>>> Stashed changes`) and the branch/sha label forms while rejecting
+//   `>>>>>>> Stashed changes`) and the branch/sha label forms. It rejects
 //   longer `<`/`>` runs.
 // - The separator (`=======`) fires ONLY while a conflict block is open in the
 //   same file (block-conditioned). A lone separator with no open above it is
-//   indistinguishable from a setext-heading underline and is a deliberate
+//   indistinguishable from a setext-heading underline. It is a deliberate
 //   accepted non-detection.
-// - In a `fenceExempt` (prose) surface, occurrences inside a fenced code block
-//   are suppressed — a fence quotes content. Markers quoted in a backtick code
-//   SPAN are handled by the column-1 anchor itself: a span sits mid-line, so
-//   `^` never matches. STATUS.md and non-markdown push targets pass
-//   `fenceExempt:false`: their fenced rows are data, where a marker is never
-//   legitimate, so fence state never suppresses.
+// - In a `fenceExempt` (prose) surface, a fenced code block suppresses the
+//   occurrences inside it, because a fence quotes content. The column-1 anchor
+//   itself handles a marker quoted in a backtick code SPAN. A span sits
+//   mid-line, so `^` never matches. STATUS.md and non-markdown push targets
+//   pass `fenceExempt:false`. Their fenced rows are data, where a marker is
+//   never legitimate, so fence state never suppresses.
 
 const OPEN_RE = /^<{7}( |$)/;
 const CLOSE_RE = /^>{7}( |$)/;
 const SEPARATOR_RE = /^={7}\s*$/;
 // A fenced-code delimiter: three or more backticks or tildes, up to three
-// leading spaces of indentation (CommonMark). The info string after the run is
-// ignored — a delimiter line is never itself a marker.
+// leading spaces of indentation (CommonMark). The scanner ignores the info
+// string after the run. A delimiter line is never itself a marker.
 const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
 
 /**
@@ -50,9 +50,9 @@ export function scanConflictMarkers(text, { fenceExempt = true } = {}) {
   let insideFence = false;
   let openDepth = 0;
   for (let i = 0; i < lines.length; i++) {
-    // Strip a trailing CR so a CRLF checkout is matched identically to LF — a
-    // bare marker (`<<<<<<<\r`) would otherwise escape the `( |$)` anchor and
-    // a CRLF corruption block would publish undetected.
+    // Strip a trailing CR so this matches a CRLF checkout and an LF checkout
+    // the same way. A bare marker (`<<<<<<<\r`) would otherwise escape the
+    // `( |$)` anchor, and a CRLF corruption block would publish undetected.
     const line = lines[i].replace(/\r$/, "");
     if (FENCE_RE.test(line)) {
       insideFence = !insideFence;
@@ -69,7 +69,7 @@ export function scanConflictMarkers(text, { fenceExempt = true } = {}) {
 }
 
 // Classify a single line as a marker kind, or null. The separator is
-// block-conditioned: it only counts while a conflict block is open.
+// block-conditioned. It counts only while a conflict block is open.
 function classify(line, openDepth) {
   if (OPEN_RE.test(line)) return "open";
   if (CLOSE_RE.test(line)) return "close";