@forwardimpact/libwiki 0.3.0 → 0.3.2

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.

package/src/sanitize.js

@@ -3,9 +3,10 @@ const ELLIPSIS = "…";
 const ZERO_WIDTH_SPACE = "\u200b";
 
 // Replace every newline, control character, or whitespace code point with a
-// single space, then collapse runs. Done by code-point inspection rather than a
-// character-class range so no literal hyphen is ever folded into a range and
-// hyphenated identifiers ("staff-engineer", "dick-olsson") survive intact.
+// single space. Then collapse runs. This function inspects each code point and
+// does not use a character-class range. So it never folds a literal hyphen
+// into a range, and hyphenated identifiers ("staff-engineer", "dick-olsson")
+// survive intact.
 function flattenWhitespace(input) {
   let out = "";
   for (const ch of input) {
@@ -19,11 +20,11 @@ function flattenWhitespace(input) {
 
 /**
  * Neutralize an anyone-editable issue-tracker field before it crosses into a
- * boot-readable wiki surface. Flattens newlines / control characters /
- * whitespace to single spaces (a multi-line value is what would let a field
- * inject a heading or block marker and move section boundaries), escapes a
- * leading protocol sigil ("[" or "<") so "[ask#N]" / "<tag>" / HTML-comment
- * lookalikes render inert, and length-caps the result.
+ * boot-readable wiki surface. Flattens newlines, control characters, and
+ * whitespace to single spaces. A multi-line value would let a field inject a
+ * heading or block marker and move section boundaries. Escapes a leading
+ * protocol sigil ("[" or "<") so "[ask#N]", "<tag>", and HTML-comment
+ * lookalikes render inert. Length-caps the result.
  * @param {string|null|undefined} value
  * @param {number} [maxLen]
  * @returns {string}
@@ -38,9 +39,9 @@ export function sanitizeCrossingField(value, maxLen = FIELD_CAP) {
 
 /**
  * Sanitize a materialized item title. Beyond {@link sanitizeCrossingField}, it
- * defuses the literal author-suffix token " (by " by inserting a zero-width
- * space after "(by", so a title can never be mistaken for the trailing
- * "(by <author>)" provenance suffix when the line is parsed back at boot.
+ * defuses the literal author-suffix token " (by ". It inserts a zero-width
+ * space after "(by". A title then never looks like the trailing
+ * "(by <author>)" provenance suffix when the boot parse reads the line back.
  * @param {string|null|undefined} value
  * @param {number} [maxLen]
  * @returns {string}

package/src/secret-gate.js

@@ -1,32 +1,33 @@
 /**
- * Fail-closed secret gate for the wiki push path. Runs gitleaks over the
- * commit range a push introduces and reports a clean / finding /
- * scanner-absent verdict. The wiki has no destination-side secret control (a
- * GitHub Wiki repo runs no Actions and is excluded from GitHub
- * secret-scanning), so this is the only place a content backstop can live.
+ * Fail-closed secret gate for the wiki push path. The gate runs gitleaks over
+ * the commit range a push introduces. It reports a clean, finding, or
+ * scanner-absent verdict. The wiki has no destination-side secret control. A
+ * GitHub Wiki repo runs no Actions, and GitHub secret-scanning excludes it. So
+ * this is the only place a content backstop can live.
  *
- * The module never throws on a scanner result: a missing or erroring scanner
- * resolves to `scanner-absent` so the caller fails closed rather than treating
- * an error as clean. Findings carry only a location (`file:line:rule`) — never
- * the matched secret value, so an audit record built from them cannot itself
- * leak.
+ * The module never throws on a scanner result. A missing scanner resolves to
+ * `scanner-absent`. A scanner that errors resolves the same way. The caller
+ * then fails closed and never reports an error as clean. Findings carry only a
+ * location (`file:line:rule`). They never carry the matched secret value, so an
+ * audit record built from them cannot itself leak.
  */
 
 import { isoTimestamp } from "@forwardimpact/libutil";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
-/** The gitleaks binary name resolved on PATH; provisioning is an operator concern (see wiki-operations guide). */
+/** The gitleaks binary name resolved on PATH. An operator provisions it (see the wiki-operations guide). */
 const GITLEAKS = "gitleaks";
 
 /**
- * Scan the commit range a push introduces for secrets, fail closed.
+ * Scan the commit range a push introduces for secrets. Fail closed.
  *
- * Probes `gitleaks version` first; an unresolvable binary short-circuits to
- * `scanner-absent`. Then runs `gitleaks detect` over `range` expressed as
- * `git log` options, reading the JSON report from stdout. Exit codes follow
- * gitleaks' documented contract: `0` clean, `1` leaks found, any other
- * non-zero an invocation error (treated as `scanner-absent` — fail closed, an
- * error is never reported as clean).
+ * The scan probes `gitleaks version` first. An unresolvable binary
+ * short-circuits to `scanner-absent`. The scan then runs `gitleaks detect` over
+ * `range` expressed as `git log` options, and reads the JSON report from
+ * stdout. Exit codes follow gitleaks' documented contract: `0` clean, `1` leaks
+ * found, any other non-zero an invocation error. The scan treats an invocation
+ * error as `scanner-absent` and fails closed. It never reports an error as
+ * clean.
  *
  * @param {object} args
  * @param {import('@forwardimpact/libutil/runtime').Runtime} args.runtime - Provides `subprocess.run`.
@@ -60,16 +61,16 @@ export async function scanPushWindow({ runtime, wikiDir, range }) {
   if (scan.exitCode === 1) {
     return { status: "finding", findings: parseFindings(scan.stdout) };
   }
-  // Any other non-zero is an invocation/usage error, not a leak verdict:
-  // fail closed rather than risk reporting a broken scan as clean.
+  // Any other non-zero is an invocation or usage error. It is not a leak
+  // verdict. Fail closed. Do not report a broken scan as clean.
   return { status: "scanner-absent" };
 }
 
 /**
- * Parse a gitleaks JSON report into location-only findings. Reads only the
- * file, line, and rule of each entry — never the matched secret value — so a
- * record built from the result is secret-free by construction. A malformed or
- * empty report yields an empty list.
+ * Parse a gitleaks JSON report into location-only findings. The parser reads
+ * only the file, line, and rule of each entry. It never reads the matched
+ * secret value, so a record built from the result is secret-free by
+ * construction. A malformed or empty report yields an empty list.
  *
  * @param {string} stdout - The gitleaks JSON report.
  * @returns {Array<{file: string, line: number, rule: string}>}
@@ -93,10 +94,10 @@ function parseFindings(stdout) {
  * Append one secret-free line to the wiki tree's `secret-overrides.log` and
  * stage it (path-scoped) so it lands in the same push as the overridden
  * content. The line records the override as a durable, inspectable audit
- * trail: an ISO timestamp, the asserted operator identity (`git config
- * user.email` — attribution of intent, NOT an authenticated identity), the
- * override class, the reason, and for a finding its location. It never carries
- * a matched secret value.
+ * trail. It holds an ISO timestamp, the asserted operator identity (`git
+ * config user.email`), the override class, the reason, and for a finding its
+ * location. That identity asserts intent. It is NOT an authenticated identity.
+ * The line never carries a matched secret value.
  *
  * @param {object} args
  * @param {import('@forwardimpact/libutil/runtime').Runtime} args.runtime - Provides `fs` and `clock`.
@@ -123,8 +124,8 @@ export async function appendOverrideRecord({
         "unspecified"
       : "scanner-absent";
   const ts = isoTimestamp(runtime.clock.now());
-  // Tab-separated, single line; the reason is collapsed so the record stays
-  // one inspectable row per override.
+  // Tab-separated, single line. The replace call collapses the reason so the
+  // record stays one inspectable row per override.
   const line = `${ts}\t${email}\t${klass}\t${reason.replace(/\s+/g, " ").trim()}\t${where}\n`;
   const logPath = `${wikiDir}/${OVERRIDE_LOG}`;
   await runtime.fs.appendFile(logPath, line);
@@ -140,12 +141,12 @@ export async function appendOverrideRecord({
 export const OVERRIDE_LOG = "secret-overrides.log";
 
 /**
- * Translate a `commitAndPush` security refusal into a command envelope,
- * logging the cause and its break-glass procedure at error level (always
- * surfaced, regardless of LOG_LEVEL). Returns `null` for any non-refusal
- * result (clean / pushed / network "saved locally"), so a caller can fall
- * through to its normal success handling. Shared by every command surface so
- * the refusal message and exit code live in one place.
+ * Translate a `commitAndPush` security refusal into a command envelope. Log the
+ * cause and its break-glass procedure at error level. The logger always
+ * surfaces them, regardless of LOG_LEVEL. Returns `null` for any
+ * non-refusal result (clean, pushed, or network "saved locally"), so a caller
+ * can fall through to its normal success path. Every command surface shares
+ * this function, so the refusal message and exit code live in one place.
  *
  * @param {object} runtime - The runtime bag (the logger writes to `proc.stderr`).
  * @param {{reason?: string, findings?: Array<{file: string, line: number, rule: string}>}} result - A `commitAndPush` result.
@@ -158,8 +159,8 @@ export function refusalEnvelope(runtime, result) {
       .join(", ");
     createLogger("wiki", runtime).error(
       "push",
-      `push blocked: secret detected in wiki content${where ? ` (${where})` : ""}; ` +
-        "the push was not attempted. After confirming a false positive, set " +
+      `push blocked: secret detected in wiki content${where ? ` (${where})` : ""}. ` +
+        "The push did not run. Confirm a false positive first. Then set " +
         "FIT_WIKI_SECRET_OVERRIDE to a reason to override (audited).",
     );
     return { ok: false, code: 1 };
@@ -167,8 +168,8 @@ export function refusalEnvelope(runtime, result) {
   if (result.reason === "scanner-unavailable") {
     createLogger("wiki", runtime).error(
       "push",
-      "push blocked: the secret scanner (gitleaks) is unavailable; the push " +
-        "was not attempted. Install gitleaks, or set FIT_WIKI_SCANNER_ABSENT_OK " +
+      "push blocked: the secret scanner (gitleaks) is unavailable. The push " +
+        "did not run. Install gitleaks, or set FIT_WIKI_SCANNER_ABSENT_OK " +
         "to a reason to override (audited).",
     );
     return { ok: false, code: 1 };

package/src/status.js

@@ -1,20 +1,21 @@
 // STATUS.md rows come in two kinds. A spec row's id is four digits with an
-// optional `/<unit>` suffix denoting a per-migration-unit sub-row of a master
-// spec (`1370/libutil`, …); the master `NNNN` row advances only when every
-// sub-row reads `plan implemented`. An experiment row's id is `exp:<issue>`
-// and the row carries four tab cells — `exp:<issue><TAB><state><TAB><pin>
-// <TAB><plan-ref>` — keying the merge-gate approval path for a spec-less
-// experiment PR. The `exp:` namespace cannot match the spec id's `^\d{4}`
-// anchor, so the two kinds never collide for any issue-number width.
+// optional `/<unit>` suffix. The suffix denotes a per-migration-unit sub-row
+// of a master spec (`1370/libutil`, …). The master `NNNN` row advances only
+// when every sub-row reads `plan implemented`. An experiment row's id is
+// `exp:<issue>`. That row carries four tab cells:
+// `exp:<issue><TAB><state><TAB><pin><TAB><plan-ref>`. The cells key the
+// merge-gate approval path for a spec-less experiment PR. The `exp:` namespace
+// cannot match the spec id's `^\d{4}` anchor, so the two kinds never collide
+// for any issue-number width.
 
 /** Matches a status-row id: a four-digit spec id (optional `/<unit>`) or `exp:<issue>`. */
 export const STATUS_ID_REGEX = /^(\d{4}(\/[a-z0-9-]+)?|exp:\d+)$/;
 
 /**
- * Classify a status-row id into its kind and parts. Experiment rows are
- * identified by an `exp:` id together with a four-cell row; the optional
- * `cells` array supplies that count (a bare `exp:` id without four cells is
- * not a valid row and yields null).
+ * Classify a status-row id into its kind and parts. An `exp:` id together with
+ * a four-cell row identifies an experiment row. The optional `cells` array
+ * supplies that count. A bare `exp:` id without four cells is not a valid row
+ * and yields null.
  * @param {string} id - The id field (cell 0) of a STATUS.md row.
  * @param {string[]} [cells] - The full tab-separated cells of the row, when
  *   available. Required to classify an experiment row.

package/src/storyboard-skeleton.js

@@ -1,16 +1,17 @@
 /**
- * Storyboard skeleton — the minimal, valid storyboard file `gemba-wiki refresh`
- * writes when the current-month board does not yet exist. It carries only the
- * structural surface libwiki owns: the five Toyota Kata sections and the
- * generic `obstacles`/`experiments` issue-list marker blocks that refresh
- * renders from tracker state.
+ * The storyboard skeleton is the minimal, valid storyboard file that
+ * `gemba-wiki refresh` writes when the current-month board does not yet exist.
+ * It carries only the structural surface libwiki owns: the five Toyota Kata
+ * sections and the generic `obstacles`/`experiments` issue-list marker blocks.
+ * Refresh renders those blocks from tracker state.
  *
- * Deliberately *not* here: the per-agent `#### {metric}` XmR blocks. Their
- * agent→metric grouping is per-installation curation libwiki cannot infer, so a
- * participant seeds each missing marker pair (see the kata-session skill) and a
- * later refresh renders it. Section budgets and authoring prose ("write the
- * challenge here") stay in the skill's `storyboard-template.md`, the L4
- * authoring layer — this skeleton is content-free scaffolding.
+ * This skeleton deliberately omits the per-agent `#### {metric}` XmR blocks.
+ * Each installation curates which metric belongs to which agent, so libwiki
+ * cannot infer the pairs. A participant seeds each missing marker pair (see the
+ * kata-session skill). A later refresh renders it. Section budgets and prose
+ * for authors ("write the challenge here") stay in the skill's
+ * `storyboard-template.md`, the L4 authoring layer. The skeleton itself carries
+ * no content.
  */
 
 const MONTH_NAMES = [
@@ -36,9 +37,9 @@ function isLeapYear(year) {
 }
 
 /**
- * Last calendar day of the month containing `todayIso` (ISO `YYYY-MM-DD`).
- * Pure integer/calendar math — no `Date`, so the module stays free of ambient
- * time deps.
+ * Return the last calendar day of the month that holds `todayIso` (ISO
+ * `YYYY-MM-DD`). The function uses pure integer and calendar math. It uses no
+ * `Date`, so the module stays free of ambient time deps.
  */
 function endOfMonthIso(todayIso) {
   const [year, month] = todayIso.split("-").map(Number);
@@ -48,10 +49,11 @@ function endOfMonthIso(todayIso) {
 }
 
 /**
- * Render the minimal storyboard skeleton for the month containing `todayIso`.
- * Pure — takes the day as an ISO string and returns markdown. The heading reads
- * `# Storyboard — {YYYY} {Month}`; the marker blocks match the syntax the
- * scanner (`marker-scanner.js`) and renderer (`commands/refresh.js`) expect.
+ * Render the minimal storyboard skeleton for the month that holds `todayIso`.
+ * The function is pure. It takes the day as an ISO string and returns
+ * markdown. The heading reads `# Storyboard — {YYYY} {Month}`. The marker
+ * blocks match the syntax the scanner (`marker-scanner.js`) and renderer
+ * (`commands/refresh.js`) expect.
  *
  * @param {string} todayIso - ISO date string (`YYYY-MM-DD`).
  * @returns {string} The skeleton markdown, newline-terminated.

package/src/util/agent-flag.js

@@ -1,16 +1,16 @@
 /**
- * Resolve the required agent flag from frozen CLI options. Pure — reads no
- * filesystem and no environment, so it runs before any state change. Returns
- * `{ ok: true, agent }` when the flag is present, or
- * `{ ok: false, code: 2, error }` when it is missing, where `error` names the
- * missing flag and shows a corrected example invocation. The error never
- * mentions an environment variable: `libwiki` carries no ambient agent
+ * Resolve the required agent flag from frozen CLI options. The function is
+ * pure. It reads no filesystem and no environment, so it runs before any state
+ * change. It returns `{ ok: true, agent }` when the flag is present. It returns
+ * `{ ok: false, code: 2, error }` when the flag is missing. The `error` names
+ * the missing flag and shows a corrected example invocation. The error never
+ * mentions an environment variable. `libwiki` carries no ambient agent
  * identity, so there is no fallback to offer.
  *
  * @param {Record<string, unknown>} options - The frozen `ctx.options`.
  * @param {{ command: string, flag?: string, example: string }} spec
- *   `command` names the failing subcommand; `flag` is the option key prefix
- *   (`--agent` by default, `--from` for `memo`); `example` is a correct
+ *   `command` names the subcommand that failed. `flag` is the option key prefix
+ *   (`--agent` by default, `--from` for `memo`). `example` is a correct
  *   invocation shown verbatim in the error.
  * @returns {{ ok: true, agent: string } | { ok: false, code: 2, error: string }}
  */

package/src/util/clock.js

@@ -1,7 +1,7 @@
 import { isoDate } from "@forwardimpact/libutil";
 
 /**
- * Today's ISO calendar date (`YYYY-MM-DD`) read from the injected clock.
+ * Return today's ISO calendar date (`YYYY-MM-DD`) from the injected clock.
  * Commands that previously inlined `new Date().toISOString().slice(0, 10)` (or
  * libwiki's `io.today()`) call this instead so the wall-clock read flows
  * through `runtime.clock`.

package/src/util/wiki-dir.js

@@ -1,9 +1,9 @@
 import path from "node:path";
 
 /**
- * Find the project root by upward `package.json` discovery from the current
- * working directory, using the injected `runtime.finder` (the one canonical
- * Finder, constructed only inside libutil).
+ * Find the project root. The search looks upward for a `package.json` from the
+ * current working directory. It uses the injected `runtime.finder` (the one
+ * canonical Finder, which libutil alone constructs).
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @returns {string}
  */
@@ -12,9 +12,9 @@ export function resolveProjectRoot(runtime) {
 }
 
 /**
- * Resolve the wiki root, preserving the pre-1370 order: the `--wiki-root`
- * option when given, else `<projectRoot>/wiki`. The finder is consulted only
- * when no explicit `--wiki-root` is supplied.
+ * Resolve the wiki root and keep the pre-1370 order: the `--wiki-root` option
+ * when the caller gives one, else `<projectRoot>/wiki`. The function consults
+ * the finder only when the caller supplies no explicit `--wiki-root`.
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @param {Record<string, unknown>} [options] - Parsed CLI options (`ctx.options`).
  * @returns {string}
@@ -26,7 +26,7 @@ export function resolveWikiRoot(runtime, options = {}) {
 /**
  * Report whether the resolved wiki root exists on disk. Commands that read or
  * sync an existing wiki use this to degrade gracefully (warn and exit 0) when
- * the tree was never bootstrapped — e.g. a fresh worktree where
+ * nobody bootstrapped the tree. One example is a fresh worktree where
  * `scripts/bootstrap.sh` did not run.
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @param {string} wikiDir - The resolved wiki root.