@forwardimpact/libwiki 0.3.0 → 0.3.2

package/src/audit/rules.js

@@ -56,9 +56,9 @@ import {
 import { STATUS_ROW_RULES } from "./status-row.js";
 
 // The budget predicates the post-landing pre-push gate re-runs over the
-// outgoing tree. Naming the ids here keeps the gate selecting rules by
-// membership of this set, so a future predicate change to any of these
-// rules flows through the gate with no gate-code change.
+// outgoing tree. This set names the ids, so the gate selects rules by
+// membership of the set. A future predicate change to any of these
+// rules then flows through the gate with no gate-code change.
 export const BUDGET_RULE_IDS = new Set([
   "summary.line-budget",
   "summary.word-budget",
@@ -110,7 +110,7 @@ export const RULES = [
     severity: "fail",
     check: lineBudget(SUMMARY_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${SUMMARY_LINE_BUDGET})`,
-    hint: "trim history into the weekly log; the summary holds settled state, not history",
+    hint: "trim history into the weekly log. the summary holds settled state. it does not hold history",
   },
   {
     id: "summary.word-budget",
@@ -118,7 +118,7 @@ export const RULES = [
     severity: "fail",
     check: wordBudget(SUMMARY_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${SUMMARY_WORD_BUDGET})`,
-    hint: "trim history into the weekly log; the summary holds settled state, not history",
+    hint: "trim history into the weekly log. the summary holds settled state. it does not hold history",
   },
   {
     id: "summary.h1-agent-matches-filename",
@@ -176,7 +176,7 @@ export const RULES = [
     check: headingGrammarDrift,
     message: (_s, r) =>
       `Entry heading '${r.observed}' does not match the dated grammar`,
-    hint: "weekly-log entry headings must be '## YYYY-MM-DD'; open entries with `gemba-wiki log decision/note`, which emit a conforming heading the rotation seam-finder can split",
+    hint: "weekly-log entry headings must be '## YYYY-MM-DD'. open entries with `gemba-wiki log decision/note`, which emit a heading that conforms and that the rotation seam-finder can split",
   },
   {
     id: "decision-block.heading-within-5",
@@ -189,9 +189,9 @@ export const RULES = [
     }),
     message: (_s, r) =>
       r.nearMiss
-        ? `Entry opens with '${r.nearMiss}'; the heading must be exactly '${DECISION_HEADING}' — move the suffix into the body`
+        ? `Entry opens with '${r.nearMiss}'. The heading must be exactly '${DECISION_HEADING}'. Move the suffix into the body`
         : `Entry lacks a line that is exactly '${DECISION_HEADING}'`,
-    hint: `open each '## YYYY-MM-DD' entry with \`gemba-wiki log decision\`, which emits a line containing exactly '${DECISION_HEADING}' (no suffix — the check is an exact match); put the one-line summary in the body below it, drawn from the entry's own narrative — do not invent rationale the entry does not support`,
+    hint: `open each '## YYYY-MM-DD' entry with \`gemba-wiki log decision\`. it emits a line that contains exactly '${DECISION_HEADING}' (no suffix, because the check is an exact match). put the one-line summary in the body below it, drawn from the entry's own narrative. do not invent rationale the entry does not support`,
   },
 
   // -- Weekly logs (sealed parts) --
@@ -211,7 +211,7 @@ export const RULES = [
     check: headingGrammarDrift,
     message: (_s, r) =>
       `Entry heading '${r.observed}' does not match the dated grammar`,
-    hint: "weekly-log entry headings must be '## YYYY-MM-DD'; open entries with `gemba-wiki log decision/note`, which emit a conforming heading the rotation seam-finder can split",
+    hint: "weekly-log entry headings must be '## YYYY-MM-DD'. open entries with `gemba-wiki log decision/note`, which emit a heading that conforms and that the rotation seam-finder can split",
   },
   {
     id: "weekly-log-part.line-budget",
@@ -220,7 +220,7 @@ export const RULES = [
     remediation: "rotate",
     check: lineBudget(WEEKLY_LOG_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${WEEKLY_LOG_LINE_BUDGET})`,
-    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams; only a single '### ' block that alone exceeds the budget remains for a human to shorten",
+    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams. only a single '### ' block that alone exceeds the budget remains for a human to shorten",
   },
   {
     id: "weekly-log-part.word-budget",
@@ -229,7 +229,7 @@ export const RULES = [
     remediation: "rotate",
     check: wordBudget(WEEKLY_LOG_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${WEEKLY_LOG_WORD_BUDGET})`,
-    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams; only a single '### ' block that alone exceeds the budget remains for a human to shorten",
+    hint: "`bunx gemba-wiki fix` re-bisects an over-budget part at its day-section seams and, for a lone over-cap day, at its '### ' block seams. only a single '### ' block that alone exceeds the budget remains for a human to shorten",
   },
   {
     id: "weekly-log-part.h1-agent-matches-filename",
@@ -242,10 +242,11 @@ export const RULES = [
   },
 
   // -- Carry surfaces --
-  // No `h1-shape` rule: unlike the weekly logs (classified on filename alone),
-  // the carry classifier (scopes.js) requires the Carry H1 before assigning the
-  // scope, so a malformed-H1 file is left unclassified rather than reaching an
-  // h1-shape rule. The two rules below are the reachable, failable set (SC #2).
+  // There is no `h1-shape` rule. The classifier classifies a weekly log on
+  // filename alone. The carry classifier (scopes.js) instead requires the
+  // Carry H1 before it assigns the scope. So it leaves a malformed-H1 file
+  // unclassified, and that file never reaches an h1-shape rule. The two rules
+  // below are the reachable, failable set (SC #2).
 
   {
     id: "carry-surface.h1-agent-matches-filename",
@@ -282,7 +283,7 @@ export const RULES = [
     when: memoryExists,
     check: lineBudget(MEMORY_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${MEMORY_LINE_BUDGET})`,
-    hint: "MEMORY.md holds settled cross-cutting state, not history; release settled claims, prune stale priority rows, and move event-by-event detail to the relevant ledger page or weekly log",
+    hint: "MEMORY.md holds settled cross-cutting state. it does not hold history. release settled claims, prune stale priority rows, and move event-by-event detail to the relevant ledger page or weekly log",
   },
   {
     id: "memory.word-budget",
@@ -291,7 +292,7 @@ export const RULES = [
     when: memoryExists,
     check: wordBudget(MEMORY_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${MEMORY_WORD_BUDGET})`,
-    hint: "MEMORY.md holds settled cross-cutting state, not history; release settled claims, prune stale priority rows, and move event-by-event detail to the relevant ledger page or weekly log",
+    hint: "MEMORY.md holds settled cross-cutting state. it does not hold history. release settled claims, prune stale priority rows, and move event-by-event detail to the relevant ledger page or weekly log",
   },
   {
     id: "memory.priority-heading",
@@ -400,7 +401,7 @@ export const RULES = [
     when: storyboardExists,
     check: lineBudget(STORYBOARD_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${STORYBOARD_LINE_BUDGET})`,
-    hint: "see per-section word budgets in storyboard-template.md; retire prior-session Headlines/Notes/Next-review entries to weekly logs",
+    hint: "see per-section word budgets in storyboard-template.md. retire prior-session Headlines/Notes/Next-review entries to weekly logs",
   },
   {
     id: "storyboard.word-budget",
@@ -409,7 +410,7 @@ export const RULES = [
     when: storyboardExists,
     check: wordBudget(STORYBOARD_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${STORYBOARD_WORD_BUDGET})`,
-    hint: "see per-section word budgets in storyboard-template.md; retire prior-session Headlines/Notes/Next-review entries to weekly logs",
+    hint: "see per-section word budgets in storyboard-template.md. retire prior-session Headlines/Notes/Next-review entries to weekly logs",
   },
   {
     id: "storyboard.markers-balanced.xmr",
@@ -454,8 +455,9 @@ export const RULES = [
     hint: "every '<!-- agent-experiments -->' needs a matching '<!-- /agent-experiments -->'",
   },
 
-  // -- Metrics CSVs (union merge keeps both sides on concurrent appends;
-  // exact-duplicate rows are surfaced here, never silently removed) --
+  // -- Metrics CSVs (union merge keeps both sides on concurrent appends. The
+  // audit surfaces exact-duplicate rows here. It never silently removes
+  // them) --
 
   {
     id: "metrics-csv.duplicate-row",
@@ -464,7 +466,7 @@ export const RULES = [
     check: duplicateCsvRows,
     message: (_s, r) =>
       `Duplicate metrics row at line ${r.lineNo} (exact match of an earlier row)`,
-    hint: "remove the surplus row, or differentiate a genuinely-distinct measurement by editing its run id or note so the rows are no longer identical",
+    hint: "remove the surplus row, or differentiate a genuinely-distinct measurement. edit its run id or note so the rows are no longer identical",
   },
 
   // -- STATUS.md rows (per-migration-unit sub-row schema) --
@@ -478,17 +480,18 @@ export const RULES = [
   // -- Filename admission --
 
   // The `admission` resolver yields one subject per git-tracked path the
-  // filename grammar rejects, so the check always fires. Flag-for-human: a
-  // wrong automated move or delete destroys memory, so `fix` routes this to the
-  // human report (any non-`agent` remediation class does) and never touches the
-  // file.
+  // filename grammar rejects, so the check always fires. This finding is a
+  // flag for a human. A wrong automated move or delete destroys memory, so
+  // `fix` routes it to the human report and never touches the file. Any
+  // non-`agent` remediation class does the same.
   {
     id: "admission.not-in-grammar",
     scope: "admission",
     severity: "fail",
     remediation: "flag",
     check: () => ({}),
-    message: (s) => `${s.relPath} matches no wiki filename grammar class`,
+    message: (s) =>
+      `${s.relPath} matches no class in the wiki filename grammar`,
     hint: "rename to an admitted class, or extend the Wiki Filename Grammar section in memory-protocol.md and audit/grammar.js together (the single admission path)",
   },
 ];

package/src/audit/scopes.js

@@ -39,8 +39,8 @@ function listMdFiles(wikiRoot, fs) {
 }
 
 // Recursively collect every *.csv under `<wikiRoot>/metrics/`. The real layout
-// is `metrics/<skill>/<year>.csv` (two levels), so the walk recurses rather
-// than assuming a fixed depth. Uses readdirSync + statSync (rather than
+// is `metrics/<skill>/<year>.csv` (two levels), so the walk recurses and does
+// not assume a fixed depth. The walk uses readdirSync + statSync (rather than
 // `withFileTypes` Dirents) so it runs unchanged under the in-memory mock fs.
 function listCsvFiles(wikiRoot, fs) {
   const metricsRoot = path.join(wikiRoot, "metrics");
@@ -57,7 +57,7 @@ function listCsvFiles(wikiRoot, fs) {
   return found;
 }
 
-// Load a metrics CSV as an audit subject: `rows` is the array of line strings,
+// Load a metrics CSV as an audit subject. `rows` is the array of line strings,
 // so a rule indexes `rows[i]` (a string) and `i + 1` is its line number.
 function loadCsv(filePath, fs) {
   return {
@@ -97,8 +97,8 @@ function loadFile(filePath, fs) {
 function classifyFile(filePath, fs) {
   const base = path.basename(filePath);
   if (EXCLUDED_BASES.has(base)) return null;
-  // STATUS.md is loaded separately (readOptional in buildContext) and audited
-  // via the dedicated `status-row` scope — skip the per-file classification.
+  // buildContext loads STATUS.md separately with readOptional. The dedicated
+  // `status-row` scope audits it. So skip the per-file classification.
   if (base === "STATUS.md") return null;
   if (NON_SUMMARY_PREFIXES.some((p) => base.startsWith(p))) return null;
   if (WEEKLY_LOG_NAME_RE.test(base)) {
@@ -109,23 +109,23 @@ function classifyFile(filePath, fs) {
   }
   const subject = loadFile(filePath, fs);
   // Carry surface: a `<agent>-carries.md` whose H1 matches the Carry H1 RE.
-  // Both axes must match (filename prefix and H1), mirroring the summary
-  // classifier. The two H1 REs end in distinct literals (`— Carries` vs
-  // `— Summary`) so the branches cannot cross-capture regardless of order;
-  // a name-match + H1-miss is left unclassified, like a malformed summary.
+  // Both axes must match (filename prefix and H1), like the summary
+  // classifier. The two H1 REs end in distinct literals (`— Carries` and
+  // `— Summary`) so the branches cannot cross-capture regardless of order.
+  // A name-match with an H1-miss stays unclassified, like a malformed summary.
   if (CARRY_SURFACE_NAME_RE.test(base)) {
     if (CARRY_SURFACE_H1_RE.test(subject.firstLine)) {
       return { kind: "carry-surface", subject };
     }
     return null;
   }
-  // Files that do not match a summary or weekly-log shape are left
-  // unclassified: stray files are not audited.
+  // A file that does not match a summary or weekly-log shape stays
+  // unclassified. The audit skips stray files.
   if (!SUMMARY_H1_RE.test(subject.firstLine)) return null;
   return { kind: "summary", subject };
 }
 
-// Read a file if present; an absent file yields empty text so callers audit
+// Read a file if present. An absent file yields empty text so callers audit
 // "missing" uniformly. The common { path, text, exists } shape backs the
 // MEMORY.md, STATUS.md, and storyboard context loads.
 function readOptional(filePath, fs) {
@@ -139,7 +139,8 @@ function readOptional(filePath, fs) {
 
 // MEMORY.md carries the same line/word budget rules as the prose surfaces, so
 // its subject needs the `lines`/`words` counters those check builders read.
-// Counted off the canonical budget.js pair, like every other budgeted surface.
+// The loader counts them off the canonical budget.js pair, like every other
+// budgeted surface.
 function loadMemory(filePath, fs) {
   const base = readOptional(filePath, fs);
   return {
@@ -150,11 +151,11 @@ function loadMemory(filePath, fs) {
 }
 
 /**
- * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
- * outside the ``` fence (header prose) and blank lines are skipped. Each row
- * carries a `kind` from {@link parseStatusRowId} (`"spec"`, `"experiment"`, or
- * `null` for an unrecognized id); spec-shaped rules read the positional
- * `id`/`phase`/`status` fields, experiment rules read `cells`.
+ * Parse the rows inside STATUS.md's fenced block into audit subjects. The
+ * parser skips lines outside the ``` fence (header prose) and blank lines.
+ * Each row carries a `kind` from {@link parseStatusRowId} (`"spec"`,
+ * `"experiment"`, or `null` for an unrecognized id). Spec-shaped rules read
+ * the positional `id`/`phase`/`status` fields. Experiment rules read `cells`.
  * @param {string} statusText - The full STATUS.md contents.
  * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string, kind: string|null}>}
  */
@@ -171,9 +172,9 @@ function parseStatusRows(statusText) {
     if (!inFence || line.trim() === "") continue;
     const cells = line.split("\t");
     // Classify by id prefix so a malformed `exp:` row (e.g. wrong cell count)
-    // is still routed to the experiment rules, which flag it — rather than
-    // slipping through the spec-shaped rules. parseStatusRowId returns the
-    // structured fields only for a well-formed row; the rules read `cells`.
+    // still routes to the experiment rules, which flag it. It does not slip
+    // through the spec-shaped rules. parseStatusRowId returns the structured
+    // fields only for a well-formed row. The rules read `cells`.
     const isExp = typeof cells[0] === "string" && cells[0].startsWith("exp:");
     const parsed = parseStatusRowId(cells[0], cells);
     rows.push({
@@ -276,12 +277,12 @@ const SCOPE_RESOLVERS = {
 
 // Normalize every audited surface into a uniform `{ path, text, fenceExempt }`
 // subject for the conflict-marker scan. The per-file subjects (summaries,
-// weekly logs and sealed parts, storyboard) carry `fileLines`; MEMORY.md and
+// weekly logs and sealed parts, storyboard) carry `fileLines`. MEMORY.md and
 // STATUS.md carry `text` (readOptional shape). `fenceExempt` is true for prose
-// surfaces, where a fence quotes content, and false for STATUS.md, whose fenced
-// rows are data — a marker there is never legitimate (per-surface fence
-// contract). Files absent from disk (missing MEMORY/STATUS/storyboard) yield
-// empty text and produce no findings.
+// surfaces, where a fence quotes content. It is false for STATUS.md, whose
+// fenced rows are data. A marker there is never legitimate (per-surface fence
+// contract). A file absent from disk (no MEMORY/STATUS/storyboard) yields
+// empty text and produces no findings.
 function conflictScanSubjects(ctx) {
   const subjects = [];
   const fileScopes = ["summary", "weekly-log-main", "weekly-log-part"];
@@ -320,12 +321,12 @@ export function resolveScope(scopeKey, ctx) {
 }
 
 /**
- * Build the admission slice: the tracked-file universe plus the
- * `rootSummaryAgents` set that gates `<agent>/` sidecar directories. The agent
- * set is derived first (a root-level summary-class file's stem) so the
- * `admission` scope can classify sidecar directories against it.
+ * Build the admission slice. It holds the tracked-file universe plus the
+ * `rootSummaryAgents` set that gates `<agent>/` sidecar directories. The
+ * function derives the agent set first (a root-level summary-class file's
+ * stem) so the `admission` scope can classify sidecar directories against it.
  *
- * Returns the empty universe when `subprocess` is absent — callers that only
+ * Returns the empty universe when `subprocess` is absent. Callers that only
  * read `.subjects` (the rotation pre-pass) skip the git read and the tree walk
  * entirely, and produce no `admission` findings.
  */
@@ -342,9 +343,9 @@ function buildAdmission(wikiRoot, fs, subprocess) {
 }
 
 /**
- * Build the audit context: classifies and loads every wiki file once.
+ * Build the audit context. It classifies and loads every wiki file once.
  * @param {{wikiRoot: string, today: string, fs: object, subprocess: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`); `subprocess` is
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `subprocess` is
  *   `runtime.subprocess` (its `runSync` backs the admission scope's git read).
  */
 export function buildContext({ wikiRoot, today, fs, subprocess }) {

package/src/audit/status-row.js

@@ -1,7 +1,7 @@
 import { STATUS_ID_REGEX } from "../status.js";
 
-// Validate every row inside wiki/STATUS.md's code fence. Rows are resolved by
-// the `status-row` scope in scopes.js; each subject carries
+// Validate every row inside wiki/STATUS.md's code fence. The `status-row`
+// scope in scopes.js resolves the rows. Each subject carries
 // `{ cells, id, phase, status, kind, text }`. Two row kinds share the fence:
 //
 //   spec        `{id}<TAB>{phase}<TAB>{status}` — three cells
@@ -40,7 +40,7 @@ export const STATUS_ROW_RULES = [
     when: hasThreeCells,
     check: (s) => (STATUS_ID_REGEX.test(s.id) ? null : { id: s.id }),
     message: (_s, r) => `Bad id '${r.id}' (expected ^\\d{4}(/[a-z0-9-]+)?$)`,
-    hint: "spec ids are four digits; a sub-row appends `/<unit>` (e.g. 1370/libutil)",
+    hint: "spec ids are four digits. a sub-row appends `/<unit>` (e.g. 1370/libutil)",
   },
   {
     id: "status-row.phase",
@@ -73,11 +73,10 @@ export const STATUS_ROW_RULES = [
     hint: "each experiment row is `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}`",
   },
   {
-    // An experiment-kind row is classified by its `exp:` id prefix
-    // (scopes.js), so the spec `id-format` rule is skipped for it; this rule
-    // enforces the `exp:\d+` id so a non-numeric issue (e.g. `exp:abc`) flags
-    // rather than auditing clean — keeping the audit aligned with
-    // STATUS_ID_REGEX / parseStatusRowId.
+    // scopes.js classifies an experiment-kind row by its `exp:` id prefix, so
+    // the spec `id-format` rule skips it. This rule enforces the `exp:\d+` id,
+    // so a non-numeric issue (e.g. `exp:abc`) flags and does not audit clean.
+    // That keeps the audit aligned with STATUS_ID_REGEX / parseStatusRowId.
     id: "status-row.exp-id-format",
     scope: "status-row",
     severity: "fail",
@@ -101,10 +100,10 @@ export const STATUS_ROW_RULES = [
     scope: "status-row",
     severity: "fail",
     when: hasFourCells,
-    // The pin is decidable per state, with no "ever approved" inference: a
-    // `registered` row has no pin (`-`); an `approved` row pins the 40-hex
-    // head; a `cancelled` row may carry the retained pin or `-` (it may or may
-    // not have been approved before cancellation), so both are accepted.
+    // The pin is decidable per state, with no "ever approved" inference. A
+    // `registered` row has no pin (`-`). An `approved` row pins the 40-hex
+    // head. A `cancelled` row may carry the retained pin or `-`, because it
+    // may or may not pass through `approved` first. So the check accepts both.
     check: (s) => {
       const [, state, pin] = s.cells;
       if (state === "registered") {
@@ -118,11 +117,11 @@ export const STATUS_ROW_RULES = [
           ? null
           : { state, pin, want: "`-` or a 40-hex SHA" };
       }
-      return null; // bad state already flagged by exp-state
+      return null; // exp-state already flags a bad state
     },
     message: (_s, r) =>
       `Bad pin '${r.pin}' for state '${r.state}' (expected ${r.want})`,
-    hint: "registered pins `-`; approved pins a 40-hex SHA; cancelled pins either",
+    hint: "registered pins `-`. approved pins a 40-hex SHA. cancelled pins either",
   },
   {
     id: "status-row.exp-planref",
@@ -131,6 +130,6 @@ export const STATUS_ROW_RULES = [
     when: hasFourCells,
     check: (s) => (/^#\d+$/.test(s.cells[3]) ? null : { planRef: s.cells[3] }),
     message: (_s, r) => `Bad plan-ref '${r.planRef}' (expected #NNN)`,
-    hint: "the plan-ref names the issue carrying the execution plan, e.g. #NNN",
+    hint: "the plan-ref names the issue that carries the execution plan, e.g. #NNN",
   },
 ];

package/src/block-renderer.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { analyze, renderChart, MIN_POINTS } from "@forwardimpact/libxmr";
 
-/** Error thrown when an XmR block cannot be rendered due to missing CSV or metric. */
+/** Error the renderer throws when an XmR block has no CSV or no metric. */
 export class BlockRenderError extends Error {
   /** Create a BlockRenderError with the given reason string. */
   constructor(reason) {
@@ -11,11 +11,12 @@ export class BlockRenderError extends Error {
 }
 
 /**
- * Render an XmR chart block for a metric by reading its CSV and producing
+ * Render an XmR chart block for a metric. Read its CSV and produce the
  * markdown lines.
  * @param {{metric: string, csvPath: string, projectRoot: string, fs: object, priorReadAnchor?: string|null}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`). `priorReadAnchor`,
- *   when supplied, stamps per-signal provenance surfaced in the Signals line.
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `priorReadAnchor`
+ *   stamps per-signal provenance when the caller supplies it. The Signals line
+ *   surfaces that provenance.
  */
 export function renderBlock({
   metric,

package/src/boot.js

@@ -130,10 +130,11 @@ function bulletItem(threshold, agent) {
 }
 
 // Advance the agent-section scan for one storyboard line that is NOT inside the
-// materialized block. Returns the next `inAgent` state and pushes an h3-bullet
-// item for the booting agent when one is found. An h2 ends the agent-section
-// scan (team-wide sections follow the last agent h3 — without this the scan
-// would run past the agent sections and misattribute team-wide bullets).
+// materialized block. Returns the next `inAgent` state. When the scan finds an
+// h3 bullet for the agent that boots, it pushes that item. An h2 ends the
+// agent-section scan, because team-wide sections follow the last agent h3.
+// Without this the scan would run past the agent sections and misattribute
+// team-wide bullets.
 function scanAgentLine(line, agent, inAgent, items) {
   if (/^## /.test(line)) return false;
   const h3Match = line.match(/^### (.+)$/);
@@ -152,8 +153,9 @@ function parseStoryboardItems(text, agent) {
   let inBlock = false;
   for (const line of text.split("\n")) {
     // The materialized block carries `- #N [agent] …` bullets that the agent
-    // scan must never capture; track it so the bullet loop skips inside it.
-    // (Without it the legacy scan double-counted these as the last agent's bullets.)
+    // scan must never capture. Track it so the bullet loop skips inside it.
+    // (Without it the legacy scan double-counted these as the last agent's
+    // bullets.)
     if (AGENT_EXPERIMENTS_OPEN_RE.test(line)) {
       inBlock = true;
       inAgent = false;
@@ -204,7 +206,7 @@ function countInbox(text) {
 /**
  * Remaining budget for a budgeted surface: current value, cap, and headroom for
  * both the line and word budget. An absent file (empty text) reports zero usage
- * and full headroom so a writer sees the ceiling before composing.
+ * and full headroom so a writer sees the ceiling before they compose.
  */
 function headroom(text, lineCap, wordCap) {
   const lines = countLines(text);
@@ -237,7 +239,7 @@ function mapClaim(c) {
 /**
  * Build the boot digest JSON object.
  * @param {{wikiRoot: string, agent: string, today: string, fs: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`); `today` is an ISO
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `today` is an ISO
  *   date string.
  */
 export function buildDigest({ wikiRoot, agent, today, fs }) {

package/src/budget-gate.js

@@ -1,14 +1,14 @@
 // Post-landing, pre-push budget re-validation on the size (word/line) axis.
 //
 // The wiki landing flow re-runs the audit's budget predicates over the
-// outgoing tree between landing and push, and refuses a push that introduces
+// outgoing tree between landing and push. It refuses a push that introduces
 // or deepens a per-file budget breach this writer's push would publish. The
-// gate reuses the audit's budget rules by reference: it resolves the rule
-// objects named by `BUDGET_RULE_IDS` and calls each rule's own `check` (the
-// over-cap predicate) plus the same `countWords` / `countLines` the audit
-// builds its subjects from. It never re-defines a budget, never routes through
-// the `runRules` engine (which drops the numeric value and emits nothing under
-// cap), and never edits — it refuses, keeping commits local.
+// gate reuses the audit's budget rules by reference. It resolves the rule
+// objects named by `BUDGET_RULE_IDS`. It then calls each rule's own `check`
+// (the over-cap predicate) plus the same `countWords` / `countLines` the audit
+// builds its subjects from. It never re-defines a budget. It never routes
+// through the `runRules` engine, which drops the numeric value and emits
+// nothing under cap. It never edits. It refuses, which keeps commits local.
 
 import path from "node:path";
 import { BUDGET_RULE_IDS, RULES } from "./audit/rules.js";
@@ -16,9 +16,10 @@ import { buildContext, resolveScope } from "./audit/scopes.js";
 import { countLines, countWords } from "./budget.js";
 
 /**
- * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`, tagging each with
- * the count axis its id implies. Throws if a named id is missing from `RULES`,
- * so a rule rename surfaces here rather than silently dropping a predicate.
+ * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`. Tag each one with
+ * the count axis its id implies. It throws if a named id is missing from
+ * `RULES`, so a rule rename surfaces here and does not silently drop a
+ * predicate.
  * @returns {Array<{id: string, scope: string, axis: 'words'|'lines', check: Function}>}
  */
 export function budgetRules() {
@@ -36,10 +37,10 @@ export function budgetRules() {
 }
 
 /**
- * Enumerate which wiki files are budgeted, by reusing the audit's
- * classification. Subjects carry an absolute `path`, so each is reduced to the
- * `<file>` half of `git show <ref>:<file>` relative to `wikiRoot`. No count is
- * read off the working-dir subject — only the file identity and its scope.
+ * Enumerate which wiki files are budgeted. Reuse the audit's classification.
+ * Subjects carry an absolute `path`. Reduce each one to the `<file>` half of
+ * `git show <ref>:<file>`, relative to `wikiRoot`. This function reads no count
+ * off the working-dir subject. It reads only the file identity and its scope.
  * @param {object} ctx - An audit context from `buildContext`.
  * @param {string} wikiRoot - The wiki clone directory the paths are relative to.
  * @returns {Array<{relPath: string, scope: string}>}
@@ -56,12 +57,12 @@ export function budgetedFiles(ctx, wikiRoot) {
 }
 
 /**
- * Measure the budget predicates for the tree at `ref`. Reads each budgeted
- * file's blob via the cwd-bound `showFile`, counts it once with the audit's
- * counters, then for every budget rule on that file's scope records the axis
+ * Measure the budget predicates for the tree at `ref`. Read each budgeted
+ * file's blob through the cwd-bound `showFile`. Count it once with the audit's
+ * counters. Then, for every budget rule on that file's scope, record the axis
  * value and whether the rule's own `check` flags it over cap. An absent path
- * at the ref counts as 0 (matching the audit's "missing counts as empty"
- * posture); an unreadable ref makes `showFile` throw, which propagates.
+ * at the ref counts as 0. This matches the audit's "missing counts as empty"
+ * posture. An unreadable ref makes `showFile` throw, and the throw propagates.
  * @param {(ref: string, file: string) => Promise<string|null>} showFile
  * @param {string} ref - The tree-ish to measure (e.g. "HEAD", a SHA).
  * @param {Array<{relPath: string, scope: string}>} budgeted
@@ -88,15 +89,16 @@ export async function measureRef(showFile, ref, budgeted) {
 }
 
 /**
- * Compare the outgoing tree against the two push-input baselines and return the
+ * Compare the outgoing tree against the two push-input baselines. Return the
  * per-file/per-predicate refusal delta. For each (file, rule) the baseline is
- * the worse (higher) of the session-base and origin-tip values, treating an
- * absent measurement as 0. A predicate refuses iff the outgoing value is over
- * cap AND strictly exceeds that baseline — so equal-or-better states pass, and
- * a foreign breach the writer did not worsen passes. A `summary.*` breach on a
- * file listed in `exemptSummaryFiles` is surfaced instead of refused — the
- * memo-delivery seam, where blocking a delivery into deficient headroom would
- * enforce a contradiction the memo-headroom measures exist to resolve.
+ * the worse (higher) of the session-base and origin-tip values. An absent
+ * measurement counts as 0. A predicate refuses iff the outgoing value is over
+ * cap AND strictly exceeds that baseline. So equal-or-better states pass, and
+ * a foreign breach the writer did not worsen passes. The gate surfaces a
+ * `summary.*` breach on a file listed in `exemptSummaryFiles` instead of
+ * refusing it. Those files are the memo-delivery seam. A block on a delivery
+ * into deficient headroom would enforce a contradiction. The memo-headroom
+ * measures exist to resolve that contradiction.
  *
  * @param {object} args
  * @param {Map<string, Map<string, {value: number, overCap: boolean}>>} args.outgoing
@@ -137,14 +139,14 @@ export function revalidateBudgets({
 }
 
 /**
- * Run the gate end to end over the outgoing tree. Builds the audit context,
- * enumerates the budgeted files, measures the committed `HEAD` (what publishes)
- * and the two push-input baselines through the one `measureRef` path, then
- * computes the per-file/per-predicate delta. An unreadable baseline ref makes
- * `showFile` throw, which aborts the gate WITHOUT refusing — the gate only
- * refuses a regression it can prove, so a read failure surfaces (the push
- * proceeds) rather than fabricating a value-0 baseline that would wrongly block
- * a foreign pre-existing breach.
+ * Run the gate end to end over the outgoing tree. Build the audit context.
+ * Enumerate the budgeted files. Measure the committed `HEAD` (what publishes)
+ * and the two push-input baselines through the one `measureRef` path. Then
+ * compute the per-file/per-predicate delta. An unreadable baseline ref makes
+ * `showFile` throw, which aborts the gate WITHOUT refusing. The gate only
+ * refuses a regression it can prove. So a read failure surfaces and the push
+ * proceeds. The gate does not fabricate a value-0 baseline that would wrongly
+ * block a foreign pre-existing breach.
  *
  * @param {object} args
  * @param {(ref: string, file: string) => Promise<string|null>} args.showFile
@@ -181,7 +183,8 @@ export async function runBudgetGate({
     }
     originTip = await measureRef(showFile, originRef, budgeted);
   } catch {
-    // Cannot prove a regression (unreadable ref) ⇒ do not refuse; fail-visible.
+    // Cannot prove a regression (unreadable ref) ⇒ do not refuse. This is the
+    // fail-visible posture.
     return { refusals: [], surfaced: [] };
   }
   return revalidateBudgets({

package/src/budget.js

@@ -1,9 +1,9 @@
 // Canonical line- and word-counters for the budgeted wiki surfaces. The audit
 // (`audit/scopes.js`) and the rotation primitive's bisecting seal
-// (`weekly-log.js`) both import this one pair so a part the seal calls
-// conforming cannot later be flagged by an audit counting differently.
+// (`weekly-log.js`) both import this one pair. So no audit that counts
+// differently can later flag a part the seal accepts as conforming.
 
-/** Count lines, not counting a trailing newline as an empty final line. */
+/** Count lines. Do not count a trailing newline as an empty final line. */
 export function countLines(text) {
   return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
 }