@forwardimpact/libwiki 0.3.0 → 0.3.2

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";

package/src/constants.js

@@ -4,18 +4,19 @@ export const BROADCAST_TARGET = "all";
 
 export const MEMORY_FILE = "MEMORY.md";
 
-// Row-structured singleton surfaces under the sync-merge discipline: when a
+// Row-structured singleton surfaces under the sync-merge discipline. When a
 // landing on one of these is contended, the resolution re-runs the row
-// operation against the fresh remote tip (rebase the operation, not the
-// lines), never a textual merge. Founding member: MEMORY.md (the Active Claims
-// table). STATUS.md phase rows join as their own re-apply operations land.
-// Metrics CSV appends take the complementary union-merge path below.
+// operation against the fresh remote tip. It rebases the operation. It does
+// not rebase the lines, and it never does a textual merge. Founding member:
+// MEMORY.md (the Active Claims table). STATUS.md phase rows join as their own
+// re-apply operations land. Metrics CSV appends take the complementary
+// union-merge path below.
 export const SINGLETON_PATHS = new Set([MEMORY_FILE]);
 
 // The tracked `.gitattributes` declaration that makes concurrent appends to
-// metrics CSVs union-merge (keep both sides' rows) on every publish path,
-// instead of conflicting or side-picking. Carried by the wiki repo itself so
-// it governs every clone.
+// metrics CSVs union-merge (keep both sides' rows) on every publish path. The
+// appends then never conflict, and nothing picks one side. The wiki repo
+// carries the declaration itself, so it governs every clone.
 export const GITATTRIBUTES_FILE = ".gitattributes";
 export const METRICS_CSV_MERGE_ATTRIBUTE = "metrics/**/*.csv merge=union";
 export const ACTIVE_CLAIMS_HEADING = "## Active Claims";
@@ -25,9 +26,9 @@ export const ACTIVE_CLAIMS_TABLE_SEPARATOR =
   "| --- | --- | --- | --- | --- | --- |";
 
 // Match a rendered pipe-table row (header or separator) line-anchored and
-// whitespace-tolerant between cells. Deriving the matcher from the rendered
-// literal keeps the claims parser (active-claims.js) and the audit
-// (audit/rules.js) from drifting on the column set — one literal, one matcher.
+// whitespace-tolerant between cells. The matcher comes from the rendered
+// literal, so the claims parser (active-claims.js) and the audit
+// (audit/rules.js) cannot drift on the column set. One literal, one matcher.
 function pipeRowRe(literal, flags) {
   const cells = literal
     .split("|")
@@ -51,8 +52,8 @@ export const DECISION_HEADING = "### Decision";
 // Unified budgets for the audited surfaces (summary, weekly-log, storyboard,
 // memory). They keep per-surface rule pairs so the limits can diverge as the
 // context-tax model says one surface should be looser or tighter. MEMORY.md is
-// the tightest: it is read on every boot and holds settled cross-cutting state,
-// not history, so its budget is sized to keep the on-boot read cheap.
+// the tightest. Every boot reads it, and it holds settled cross-cutting state
+// and no history. So its budget keeps the on-boot read cheap.
 export const SUMMARY_LINE_BUDGET = 496;
 export const SUMMARY_WORD_BUDGET = 2048;
 export const WEEKLY_LOG_LINE_BUDGET = 496;
@@ -70,25 +71,27 @@ export const WEEKLY_LOG_NAME_RE = /^([a-z][a-z-]*)-(\d{4})-W(\d{2})\.md$/;
 export const WEEKLY_LOG_PART_NAME_RE =
   /^([a-z][a-z-]*)-(\d{4})-W(\d{2})-part\d+\.md$/;
 
-// Day-section seam: `## YYYY-MM-DD` at line start, a trailing suffix tolerated
-// (e.g. `## 2026-05-19 (third activation)`). One home so the rotation
-// seam-finder (weekly-log.js), the `log` command's last-entry probe
-// (commands/log.js), and the audit's heading-grammar-drift rule (audit/rules.js)
-// cannot disagree on what a conforming entry heading is. Source has no flags;
-// call sites add `g`/`m` as needed via `new RegExp(WEEKLY_LOG_SEAM_RE.source, …)`.
+// Day-section seam: `## YYYY-MM-DD` at line start. The matcher tolerates a
+// trailing suffix (e.g. `## 2026-05-19 (third activation)`). One home so the
+// rotation seam-finder (weekly-log.js), the `log` command's last-entry probe
+// (commands/log.js), and the audit's heading-grammar-drift rule
+// (audit/rules.js) cannot disagree on what a conforming entry heading is. The
+// source has no flags. Call sites add `g`/`m` as needed with
+// `new RegExp(WEEKLY_LOG_SEAM_RE.source, …)`.
 export const WEEKLY_LOG_SEAM_RE = /^## (\d{4}-\d{2}-\d{2})/;
 
-// Tier-2 integrity sweep idle-gap: lane-authored commits separated by more
-// than this delimit sessions in the wiki history. 30 minutes.
+// Idle-gap for the tier-2 integrity sweep. Lane-authored commits with a gap
+// larger than this value delimit sessions in the wiki history. 30 minutes.
 export const SESSION_GAP_MS = 30 * 60 * 1000;
 
 // Carry-surface filename and H1 convention: `<agent>-carries.md` with an H1
-// `# <agent> — Carries`. The name capture group is the agent prefix (used by
-// the H1↔filename agreement rule). A Carry entry names its clearance trigger
-// with the `**Carry-clearance:**` marker — the existing live convention in
-// `wiki/release-engineer.md § Message Inbox`, preserved verbatim so the
-// migration relocates without re-marking. One home so the audit's classifier
-// (audit/scopes.js) and rules (audit/rules.js) cannot drift on the syntax.
+// `# <agent> — Carries`. The name capture group is the agent prefix, which the
+// H1↔filename agreement rule uses. A Carry entry names its clearance trigger
+// with the `**Carry-clearance:**` marker. That is the existing live convention
+// in `wiki/release-engineer.md § Message Inbox`, kept verbatim so the
+// migration relocates the entry and does not re-mark it. One home so the
+// audit's classifier (audit/scopes.js) and rules (audit/rules.js) cannot drift
+// on the syntax.
 export const CARRY_SURFACE_NAME_RE = /^(.+)-carries\.md$/;
 export const CARRY_SURFACE_H1_RE = /^# (.+) — Carries$/;
 export const CARRY_CLEARANCE_MARKER_RE = /\*\*Carry-clearance:\*\*/;
@@ -98,8 +101,9 @@ export const CARRY_CLEARANCE_MARKER_RE = /\*\*Carry-clearance:\*\*/;
 // refresh." notice). One home so the marker scanner (marker-scanner.js) and the
 // audit's balance check (audit/rules.js) cannot drift on the syntax.
 // Capture groups: 1 metric, 2 csvPath, 3 optional prior-read anchor date. The
-// `prior=YYYY-MM-DD` token sits before the trailing-text group so the "Do not
-// edit" notice is still tolerated and does not swallow the anchor.
+// `prior=YYYY-MM-DD` token sits before the trailing-text group, so the scanner
+// still tolerates the "Do not edit" notice and the notice does not swallow the
+// anchor.
 export const XMR_OPEN_RE =
   /^<!--\s*xmr:([^:\s]+):(\S+)(?:\s+prior=(\d{4}-\d{2}-\d{2}))?(?:\s+[^>]*?)?\s*-->\s*$/;
 export const XMR_CLOSE_RE = /^<!--\s*\/xmr(?:\s+[^>]*?)?\s*-->\s*$/;
@@ -108,9 +112,9 @@ export const ISSUE_OPEN_RE =
 export const ISSUE_CLOSE_RE =
   /^<!--\s*\/(obstacles|experiments)(?:\s+[^>]*?)?\s*-->\s*$/;
 
-// Materialized per-agent experiments surface. A distinct marker
-// kind from `experiments:open` — it carries attributed, sanitized items plus a
-// last-successful-sync stamp, and is read offline by `gemba-wiki boot`. One home
+// Materialized per-agent experiments surface. This is a distinct marker kind
+// from `experiments:open`. It carries attributed, sanitized items plus a
+// last-successful-sync stamp, and `gemba-wiki boot` reads it offline. One home
 // so the scanner (marker-scanner.js), the refresh renderer (commands/refresh.js),
 // the boot parser (boot.js), and the audit balance check (audit/rules.js) cannot
 // drift on the syntax.
@@ -121,7 +125,7 @@ export const AGENT_EXPERIMENTS_CLOSE_RE =
 export const LAST_SYNC_RE =
   /^<!--\s*last-successful-sync:\s*(\d{4}-\d{2}-\d{2})\s*-->\s*$/;
 // Attributed item line: `- #<n> [<agent>] <title> (by <author>)`. The author
-// suffix is mandatory and anchored at end; the title group is greedy, which is
+// suffix is mandatory and anchored at end. The title group is greedy, which is
 // unambiguous because sanitizeTitle defuses any embedded ` (by ` token.
 export const AGENT_EXPERIMENT_ITEM_RE =
   /^- #(\d+) \[([a-z][a-z-]*)\] (.*) \(by (.+)\)$/;

package/src/gitattributes.js

@@ -5,18 +5,19 @@ import {
 } from "./constants.js";
 
 /**
- * Ensure the wiki's tracked `.gitattributes` declares the metrics-CSV union
+ * Make sure the wiki's tracked `.gitattributes` declares the metrics-CSV union
  * merge attribute (`metrics/**\/*.csv merge=union`), idempotently.
  *
- * Present-and-correct means no write: if the exact attribute line already
- * appears in the file, the file is left byte-unchanged and `{ changed: false }`
- * is returned. Otherwise the line is appended (preserving any existing
- * `.gitattributes` content) or the file is created with just that line, and
- * `{ changed: true }` is returned.
+ * A present and correct line means no write. If the exact attribute line
+ * already appears in the file, the function leaves the file byte-unchanged and
+ * returns `{ changed: false }`. Otherwise it appends the line and keeps any
+ * existing `.gitattributes` content, or it creates the file with only that
+ * line. It then returns `{ changed: true }`.
  *
  * The single union declaration governs every clone because it is a tracked
- * worktree file; per-clone config (`core.attributesFile`, `.git/info/attributes`)
- * would not propagate to the sibling sessions that cause the loss.
+ * worktree file. Per-clone config (`core.attributesFile`,
+ * `.git/info/attributes`) would not propagate to the sibling sessions that
+ * cause the loss.
  *
  * @param {string} wikiDir - The wiki clone directory.
  * @param {import('node:fs')} fsSync - Synchronous filesystem surface (`runtime.fsSync`).
@@ -30,7 +31,7 @@ export function ensureMetricsCsvMergeAttribute(wikiDir, fsSync) {
       .split("\n")
       .some((line) => line.trim() === METRICS_CSV_MERGE_ATTRIBUTE);
     if (present) return { changed: false };
-    // Append the line, keeping existing content and ending with a newline.
+    // Append the line. Keep existing content and end with a newline.
     const base = text.endsWith("\n") || text === "" ? text : `${text}\n`;
     fsSync.writeFileSync(filePath, `${base}${METRICS_CSV_MERGE_ATTRIBUTE}\n`);
     return { changed: true };

package/src/integrity.js

@@ -3,8 +3,8 @@ import { SESSION_GAP_MS } from "./constants.js";
 import { isLaneFile, enumerateLaneFiles } from "./lane-files.js";
 
 /**
- * Normalize a content line for content-keyed presence: strip a trailing CR and
- * trailing whitespace. Blank lines normalize to "" and are dropped by callers.
+ * Normalize a content line for content-keyed presence. Strip a trailing CR and
+ * trailing whitespace. A blank line normalizes to "". Callers drop it.
  * @param {string} line
  * @returns {string}
  */
@@ -13,10 +13,10 @@ export function normLine(line) {
 }
 
 /**
- * Parse `git diff --unified=0` text into per-file change records, attributing
+ * Parse `git diff --unified=0` text into per-file change records. Attribute
  * each `+`/`-` line to the file named by the most recent `+++ b/<path>` header.
- * The `+++`/`---`/`@@` framing lines are not content. `/dev/null` targets
- * (pure deletions) are kept as the home for their removed lines.
+ * The `+++`/`---`/`@@` framing lines are not content. The parser keeps
+ * `/dev/null` targets (pure deletions) as the home for their removed lines.
  * @param {string} diffText
  * @returns {Array<{home: string, added: string[], removed: string[]}>}
  */
@@ -38,7 +38,7 @@ export function parseDiff(diffText) {
   return [...byHome.values()];
 }
 
-/** Whether a diff line is framing (`---`, `@@`, `diff`, `index`) rather than content. */
+/** Whether a diff line is framing (`---`, `@@`, `diff`, `index`) and carries no content. */
 function isDiffFraming(raw) {
   return (
     raw.startsWith("--- ") ||
@@ -48,7 +48,7 @@ function isDiffFraming(raw) {
   );
 }
 
-/** Strip a diff target's `a/`/`b/` prefix; `/dev/null` stays as-is. */
+/** Strip a diff target's `a/`/`b/` prefix. `/dev/null` stays as-is. */
 function stripDiffTarget(target) {
   const t = target.trim();
   if (t === "/dev/null") return t;
@@ -57,10 +57,11 @@ function stripDiffTarget(target) {
 
 /**
  * Compose a window of change records (oldest→newest) into the surviving
- * addition assertions, then return those absent from the tip. Content-keyed on
- * `norm(line)`: a later own-lane deletion of an earlier-added line cancels its
- * assertion (additions-only, own-deletions cancel). A surviving assertion is
- * present iff its normalized line appears anywhere in `tipText`.
+ * addition assertions. Then return those absent from the tip. The composition
+ * is content-keyed on `norm(line)`. A later own-lane deletion of an
+ * earlier-added line cancels its assertion (additions-only, own-deletions
+ * cancel). A surviving assertion is present iff its normalized line appears
+ * anywhere in `tipText`.
  *
  * @param {Array<{home: string, added: string[], removed: string[]}>} changes
  *   Window changes, oldest→newest.
@@ -78,7 +79,7 @@ export function findAbsent(changes, tipText, norm) {
   return absent;
 }
 
-/** Compose window changes into surviving additions; a later removal cancels its key. */
+/** Compose window changes into surviving additions. A later removal cancels its key. */
 function composeAssertions(changes, norm) {
   const asserted = new Map(); // norm(line) -> { contentId, pushHome }
   for (const change of changes) {
@@ -108,10 +109,10 @@ function normalizedKeySet(text, norm) {
 
 /**
  * Resolve the previous-session push set from lane-authored commits (newest
- * first) by idle-gap. Tier 2 runs at boot before the current session has
- * pushed, so the most recent contiguous run is the previous session. Vacuous
- * only for empty history; the degenerate (content-unresolvable) case is raised
- * by {@link sweepTier2}, not here.
+ * first) by idle-gap. Tier 2 runs at boot before the current session pushes,
+ * so the most recent contiguous run is the previous session. The result is
+ * vacuous only for empty history. {@link sweepTier2} raises the degenerate
+ * (content-unresolvable) case. This function does not raise it.
  *
  * @param {Array<{sha: string, when: number}>} commits - Newest first.
  * @param {number} gapMs - Idle-gap threshold (ms).
@@ -121,7 +122,7 @@ export function previousSessionWindow(commits, gapMs) {
   if (commits.length === 0) return { kind: "vacuous" };
   const tipRun = [commits[0]];
   for (let i = 1; i < commits.length; i++) {
-    // commits are newest-first; `when` is seconds, gap threshold is ms.
+    // commits are newest-first. `when` is seconds. The gap threshold is ms.
     const gap = (commits[i - 1].when - commits[i].when) * 1000;
     if (gap > gapMs) break;
     tipRun.push(commits[i]);
@@ -130,8 +131,8 @@ export function previousSessionWindow(commits, gapMs) {
 }
 
 /**
- * Build a detection record. `detectedAt` is the binding wall-clock stamp (ISO);
- * an exposure figure derived from commit timestamps carries the labeled
+ * Build a detection record. `detectedAt` is the binding wall-clock stamp
+ * (ISO). An exposure figure derived from commit timestamps carries the labeled
  * `commit-timestamp` fallback basis.
  *
  * @param {object} d
@@ -166,8 +167,9 @@ export function makeDetection({
 
 /**
  * Render detections to flow output text. Empty input renders the empty string
- * (clean-path silence). One line per detection naming tier, push-time home, and
- * content identity; exposure (when present) is labeled with its fallback basis.
+ * (clean-path silence). Each detection gets one line that names the tier, the
+ * push-time home, and the content identity. The line labels exposure with its
+ * fallback basis when exposure is present.
  * @param {object[]} detections
  * @returns {string}
  */
@@ -186,10 +188,10 @@ export function renderDetections(detections) {
 }
 
 /**
- * Tier-2 boot sweep: verify the lane's previous-session push set is still
- * content-present at the fetched (rebased) origin tip, returning detections for
+ * Tier-2 boot sweep. Verify the lane's previous-session push set is still
+ * content-present at the fetched (rebased) origin tip. Return detections for
  * any absence. Reads git and lane files from `wikiDir` (the rebased tree).
- * Never writes, never throws into the flow (the caller wraps it).
+ * Never writes. Never throws into the flow (the caller wraps it).
  *
  * @param {object} ctx
  * @param {import('@forwardimpact/libutil/runtime').Runtime} ctx.runtime
@@ -202,7 +204,7 @@ export function renderDetections(detections) {
 export async function sweepTier2({ runtime, gitClient, wikiDir, agent, now }) {
   const email = await gitClient.configGet("user.email", { cwd: wikiDir });
   if (!email) {
-    // Lane identity unresolvable — never a silent vacuous pass.
+    // Lane identity unresolvable. Never a silent vacuous pass.
     return [
       makeDetection({
         tier: 2,
@@ -221,7 +223,7 @@ export async function sweepTier2({ runtime, gitClient, wikiDir, agent, now }) {
 
   const detections = [];
   const changes = [];
-  // Oldest→newest so own-deletion cancellation composes in commit order.
+  // Oldest→newest so own-deletions cancel in commit order.
   const ordered = [...window.commits].reverse();
   for (const commit of ordered) {
     const diff = await gitClient.diffRange(`${commit.sha}~1 ${commit.sha}`, {
@@ -250,7 +252,7 @@ export async function sweepTier2({ runtime, gitClient, wikiDir, agent, now }) {
 
   for (const absent of findAbsent(changes, tipText, normLine)) {
     // Exposure runs from the LAST window commit that added this exact line
-    // (its most recent assertion at origin), not merely a same-home commit.
+    // (its most recent assertion at origin). A same-home commit does not count.
     const when = lastAssertionTime(changes, absent.contentId);
     const exposureSeconds =
       when != null ? Math.round(now / 1000 - when) : undefined;

package/src/issue-list-renderer.js

@@ -3,10 +3,11 @@ import { createLogger } from "@forwardimpact/libtelemetry";
 import { sanitizeCrossingField, sanitizeTitle } from "./sanitize.js";
 
 /**
- * Thrown when the tracker query for the agent-experiments materialization fails
- * (non-zero exit or unparseable JSON). Distinct from returning `[]` so the
- * refresh command can keep the previously materialized block instead of wiping
- * the routing surface when the tracker is briefly unavailable.
+ * `renderAgentExperiments` throws this when the tracker query for the
+ * agent-experiments materialization fails (non-zero exit or unparseable JSON).
+ * This error differs from a `[]` return. It lets the refresh command keep the
+ * previously materialized block when the tracker is briefly unavailable. The
+ * command does not wipe the routing surface.
  */
 export class TrackerQueryError extends Error {
   /** @param {string} reason */
@@ -18,7 +19,12 @@ export class TrackerQueryError extends Error {
 
 const AGENT_LABEL_RE = /^agent:([a-z][a-z-]*)$/;
 
-/** Parse `owner/repo` from a git origin URL. Tolerates http(s), ssh, and proxy-rewritten URLs (e.g. `http://host/git/owner/repo`) by taking the last two path segments after stripping `.git`. Returns null when nothing parseable is found. */
+/**
+ * Parse `owner/repo` from a git origin URL. Tolerates http(s), ssh, and
+ * proxy-rewritten URLs (e.g. `http://host/git/owner/repo`). It strips `.git`.
+ * Then it takes the last two path segments. Returns null when it finds nothing
+ * parseable.
+ */
 export function parseRepoSlug(originUrl) {
   if (!originUrl) return null;
   const stripped = originUrl.trim().replace(/\.git$/, "");
@@ -29,11 +35,12 @@ export function parseRepoSlug(originUrl) {
 
 /**
  * Render an issue-list block for an obstacles/experiments marker. Returns
- * markdown lines. `cwd` should be the parent monorepo's project root so `gh`
- * resolves the correct origin; `repo` is an explicit `owner/name` slug used when
- * the origin remote is unparseable by `gh` (e.g. sandbox proxy URLs); `token`
- * is the resolved GH token (e.g. via `Config.ghToken()`). The `gh` command runs
- * through `runtime.subprocess`, and stderr warnings through `runtime.proc`.
+ * markdown lines. Set `cwd` to the parent monorepo's project root so `gh`
+ * resolves the correct origin. `repo` is an explicit `owner/name` slug. Use it
+ * when `gh` cannot parse the origin remote (e.g. sandbox proxy URLs). `token`
+ * is the resolved GH token (e.g. through `Config.ghToken()`). The `gh` command
+ * runs through `runtime.subprocess`. Stderr warnings run through
+ * `runtime.proc`.
  *
  * @param {object} options
  * @param {string} options.topic
@@ -107,12 +114,13 @@ export async function renderIssueList({
 }
 
 /**
- * Render the attributed per-agent experiments surface. Fetches open
- * issues labeled `experiment`, keeps only those also carrying an
- * `agent:{name}` label, and emits one sanitized, body-free line per issue:
- * `- #<number> [<agent>] <title> (by <author>)`. Issue bodies are never read.
- * Throws {@link TrackerQueryError} on tracker failure so the caller can keep the
- * previously materialized block; never returns `[]` on failure.
+ * Render the attributed per-agent experiments surface. Fetches open issues
+ * labeled `experiment`. Keeps only the issues that also carry an
+ * `agent:{name}` label. Emits one sanitized, body-free line per issue:
+ * `- #<number> [<agent>] <title> (by <author>)`. This function never reads
+ * issue bodies. Throws {@link TrackerQueryError} on tracker failure so the
+ * caller can keep the previously materialized block. Never returns `[]` on
+ * failure.
  *
  * @param {object} options
  * @param {string} options.cwd