@forwardimpact/libwiki 0.3.0 → 0.3.1

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

package/src/lane-files.js

@@ -4,12 +4,13 @@ import { WEEKLY_LOG_NAME_RE, WEEKLY_LOG_PART_NAME_RE } from "./constants.js";
 const METRICS_CSV_RE = /^metrics\/[^/]+\/\d{4}\.csv$/;
 
 /**
- * Whether a wiki-root-relative path is one of the lane's own files: the
- * agent's summary (`<agent>.md`), a weekly log or sealed part
- * (`<agent>-YYYY-Www.md`, `<agent>-YYYY-Www-partN.md`, matched on the captured
- * agent token), or a metrics CSV (`metrics/<skill>/<year>.csv`). Metrics CSVs
- * match by path for every agent; lane ownership of a metrics CSV is enforced by
- * the tier-2 sweep's author filter at the commit level, not here.
+ * Whether a wiki-root-relative path is one of the lane's own files. The lane's
+ * own files are the agent's summary (`<agent>.md`), a weekly log or sealed
+ * part, and a metrics CSV (`metrics/<skill>/<year>.csv`). A weekly log or
+ * sealed part is `<agent>-YYYY-Www.md` or `<agent>-YYYY-Www-partN.md`, matched
+ * on the captured agent token. Metrics CSVs match by path for every agent. The
+ * tier-2 sweep's author filter enforces lane ownership of a metrics CSV at the
+ * commit level. This function does not.
  *
  * @param {string} relPath - Path relative to the wiki root (POSIX or native).
  * @param {string} agent - Agent profile id (e.g. "staff-engineer").
@@ -27,9 +28,9 @@ export function isLaneFile(relPath, agent) {
 }
 
 /**
- * Enumerate the lane's own files present under `wikiRoot`: matching top-level
- * summary and weekly-log files, plus every `metrics/<skill>/<year>.csv`.
- * Returns wiki-root-relative POSIX paths.
+ * Enumerate the lane's own files present under `wikiRoot`. The list holds the
+ * top-level summary and weekly-log files that match, plus every
+ * `metrics/<skill>/<year>.csv`. Returns wiki-root-relative POSIX paths.
  *
  * @param {string} wikiRoot
  * @param {string} agent
@@ -45,7 +46,7 @@ export function enumerateLaneFiles(wikiRoot, agent, fsSync) {
   return out;
 }
 
-/** Wiki-root-relative `metrics/<skill>/<year>.csv` paths matching the lane. */
+/** Wiki-root-relative `metrics/<skill>/<year>.csv` paths that match the lane. */
 function enumerateMetricsCsvs(wikiRoot, agent, fsSync) {
   const metricsDir = path.join(wikiRoot, "metrics");
   if (!fsSync.existsSync(metricsDir)) return [];

package/src/ledger/anchor.js

@@ -13,11 +13,11 @@
  * ```
  * ```
  *
- * The block is parsed by structure, not by a general YAML engine, so libwiki
- * adds no parser dependency. `kind` is one of `occ`, `nm`, `fold`, `meta`;
- * `ids` is a list of display labels; `event` is the durable key (a SHA or a
- * prior anchor id); `note` is free text. The durable key is `event`; labels are
- * display only, so relabeling is lossless.
+ * The parser reads the block by structure. It does not use a general YAML
+ * engine, so libwiki adds no parser dependency. `kind` is one of `occ`, `nm`,
+ * `fold`, `meta`. `ids` is a list of display labels. `event` is the durable
+ * key (a SHA or a prior anchor id). `note` is free text. The durable key is
+ * `event`. Labels are display only, so a relabel loses nothing.
  */
 
 const FENCE_OPEN = "```yaml alloc";
@@ -59,7 +59,7 @@ export function parseAnchor(body) {
 }
 
 /**
- * Render the canonical anchor body for posting.
+ * Render the canonical anchor body to post.
  *
  * @param {{kind: string, ids: string[], event: string, note?: string}} anchor
  * @returns {string}

package/src/ledger/projection.js

@@ -1,16 +1,18 @@
 /**
- * Fold the ordered allocation-anchor sequence into id assignments and render
- * the two derived projections — the ledger page body and the MEMORY
- * cross-cutting row. The anchor record is authoritative; these projections hold
- * no sole-copy state and are rebuildable from it, so erasure of a projection is
- * a cache miss repaired by rebuild, not a loss event.
+ * Fold the ordered allocation-anchor sequence into id assignments. Then render
+ * the two derived projections: the ledger page body and the MEMORY
+ * cross-cutting row. The anchor record is authoritative. These projections
+ * hold no sole-copy state, and a rebuild recreates them from the record. So an
+ * erased projection is a cache miss that a rebuild repairs. It is not a loss
+ * event.
  *
- * Identity is the `event` key; labels are display output, so a double-allocation
- * resolves first-published-wins and the loser is re-labeled without losing any
- * record. The labeling policy is a `labelMode` parameter: `renumber` (the
- * default, matching the team's established convention) keeps the labels dense
- * and re-mints the loser at the next free index; `gapped` leaves a gap so a
- * label never moves. Both are supported; neither is forced.
+ * Identity is the `event` key. Labels are display output. So a
+ * double-allocation resolves first-published-wins. The loser takes a new
+ * label, and no record is lost. The `labelMode` parameter sets the label
+ * policy. `renumber` is the default and matches the team's established
+ * convention. It keeps the labels dense and re-mints the loser at the next
+ * free index. `gapped` leaves a gap so a label never moves. The code supports
+ * both. It forces neither.
  */
 
 /**
@@ -37,7 +39,7 @@ export function foldAnchors(anchors) {
         assignments.set(label, record);
         continue;
       }
-      // existing was published earlier (anchors are id-ordered): it wins.
+      // the existing record is older (anchors are id-ordered), so it wins.
       if (!contested.has(label)) contested.set(label, []);
       contested.get(label).push(record);
     }
@@ -51,13 +53,13 @@ export function foldAnchors(anchors) {
 }
 
 /**
- * Render the ledger page body from a fold. Entries are grouped by kind and
- * ordered by their winning anchor's id. Authored prose carried by
- * `<!-- anchor:ID -->`-cited blocks is re-emitted in anchor-id order; a cited
- * anchor that does not exist is reported in the returned `missingProse` list,
- * never silently dropped. `labelMode` selects the loser re-mint guidance for a
- * double-allocation: `renumber` (default) re-mints at the next free index,
- * `gapped` leaves the loser's index as a gap.
+ * Render the ledger page body from a fold. The renderer groups entries by kind
+ * and orders them by the id of the anchor that won. It re-emits authored prose
+ * from `<!-- anchor:ID -->`-cited blocks in anchor-id order. The returned
+ * `missingProse` list names any cited anchor that does not exist. The renderer
+ * never drops one silently. `labelMode` selects the re-mint guidance for the
+ * loser of a double-allocation. `renumber` (default) re-mints at the next free
+ * index. `gapped` leaves the loser's index as a gap.
  *
  * @param {{assignments: Map, conflicts: Array}} fold
  * @param {Array<{anchorId: number, text: string}>} [prose] - Anchor-cited prose blocks.
@@ -72,7 +74,7 @@ export function renderLedgerPage(
   const lines = [
     "# Parallel-Collision Ledger",
     "",
-    "Derived projection of the allocation-anchor record. Rebuilt by `gemba-wiki ledger rebuild`; do not hand-edit identifiers here — allocate at an anchor.",
+    "Derived projection of the allocation-anchor record. `gemba-wiki ledger rebuild` rebuilds it. Do not hand-edit identifiers here. Allocate at an anchor.",
     "",
     ...renderKindSections(fold),
     ...renderConflicts(fold, labelMode),
@@ -123,8 +125,8 @@ function renderConflicts(fold, labelMode) {
 
 /**
  * Extract `<!-- anchor:ID -->`-cited prose blocks from an existing ledger-page
- * body so a rebuild re-emits them rather than dropping them. Each block runs
- * from its citation marker to the next marker or end of input.
+ * body so a rebuild re-emits them. A rebuild does not drop them. Each block
+ * runs from its citation marker to the next marker or end of input.
  *
  * @param {string} pageBody - The current ledger-page text.
  * @returns {Array<{anchorId: number, text: string}>}
@@ -160,8 +162,8 @@ function appendProse(lines, fold, prose) {
 }
 
 /**
- * Render the MEMORY cross-cutting row counters from a fold: next-free index per
- * kind, plus the total assigned count.
+ * Render the MEMORY cross-cutting row counters from a fold. The counters are
+ * the next-free index per kind, plus the total assigned count.
  *
  * @param {{assignments: Map}} fold
  * @returns {string}
@@ -176,7 +178,7 @@ export function renderMemoryRow(fold) {
   return (
     `Parallel-collision allocation (derived from the anchor record): ` +
     `${fold.assignments.size} ids assigned; next free #${next.occ}, NM${next.nm}, ` +
-    `n=${next.fold}, M${next.meta}. Allocate at an anchor, never by editing this row.`
+    `n=${next.fold}, M${next.meta}. Allocate at an anchor. Never allocate by editing this row.`
   );
 }
 
@@ -188,11 +190,12 @@ const MEMORY_REGION_RE = new RegExp(
 
 /**
  * Write the derived MEMORY-row counters into a delimited region of a MEMORY.md
- * body, so the row is a rebuildable projection of the anchor record
- * without overwriting the surrounding authored narrative. The region is the
- * only sole-copy-free surface: its interior is fully regenerated, everything
- * outside it is preserved byte-for-byte. If the region is absent it is appended
- * under a heading; if present, only its interior is replaced.
+ * body. The row is then a rebuildable projection of the anchor record. The
+ * write does not overwrite the surrounding authored narrative. The region is
+ * the only sole-copy-free surface. This function regenerates its interior in
+ * full. It preserves everything outside the region byte-for-byte. If the
+ * region is absent, this function appends it under a heading. If the region is
+ * present, this function replaces only its interior.
  *
  * @param {string} memoryBody - Current `MEMORY.md` text.
  * @param {{assignments: Map}} fold
@@ -210,8 +213,8 @@ export function writeMemoryRowRegion(memoryBody, fold) {
 
 /**
  * Extract the derived MEMORY-row region interior from a MEMORY.md body, or
- * `null` if the region is absent. Used by `verify` to diff the projection
- * surface alone, never the surrounding narrative.
+ * `null` if the region is absent. `verify` uses this to diff the projection
+ * surface alone. It never diffs the surrounding narrative.
  *
  * @param {string} memoryBody
  * @returns {string|null}

package/src/ledger/reader.js

@@ -2,16 +2,16 @@ import { parseAnchor } from "./anchor.js";
 
 /**
  * The obstacle issue whose comment thread is the allocation-anchor surface.
- * GitHub serializes comment creation and assigns a monotonic `id`, so that `id`
+ * GitHub serializes comment creation and assigns a monotonic `id`. So the `id`
  * order is the allocation serialization no merge can erase.
  */
 export const DEFAULT_ANCHOR_ISSUE = 1564;
 
 /**
  * Read every allocation anchor from the obstacle issue's comment thread, in
- * server `id` order ascending. The lowest comment `id` claiming a given label
- * is its winner (first published wins). Comments carrying no anchor block are
- * skipped.
+ * server `id` order ascending. The lowest comment `id` that claims a given
+ * label is its winner (first published wins). This function skips comments
+ * that carry no anchor block.
  *
  * @param {object} ghClient - A GhClient (or mock) exposing `apiGetPaginated`.
  * @param {object} opts

package/src/marker-scanner.js

@@ -84,8 +84,9 @@ function matchClose(line, open) {
 
 /**
  * Scan text for paired marker blocks (xmr or issue-list). Returns positions and
- * metadata. Dangling open markers are reported through the injected `warn`
- * callback (default: discard) instead of writing to the process directly.
+ * metadata. The scanner reports dangling open markers through the injected
+ * `warn` callback (default: discard). It does not write to the process
+ * directly.
  * @param {string} text - The storyboard text to scan.
  * @param {{warn?: (message: string) => void}} [options]
  * @returns {Array<object>} The paired marker blocks.