@forwardimpact/libwiki 0.3.0 → 0.3.2

package/src/commands/fix.js

@@ -18,15 +18,15 @@ import { resolveProjectRoot } from "../util/wiki-dir.js";
 import { FAST_MODEL } from "@forwardimpact/libutil/models";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
-// Pipeline: audit → deterministic rotation (the one fix needing a file seal the
-// agent can't do) → re-audit → Haiku agent on the prose-judgment residual →
-// flag what neither should touch. MAX_ROUNDS still caps the agent loop so an
-// unresolvable agent-class finding fails loudly rather than spinning forever.
+// Pipeline: audit → deterministic rotation (the one fix that needs a file seal
+// the agent cannot do) → re-audit → Haiku agent on the prose-judgment residual
+// → flag what neither should touch. MAX_ROUNDS still caps the agent loop. An
+// unresolvable agent-class finding fails loudly and does not loop forever.
 const MAX_ROUNDS = 3;
 
 /**
  * A finding's remediation class, from the declarative rule. Rules without a
- * `remediation` field default to `"agent"`: the Haiku agent handles all
+ * `remediation` field default to `"agent"`. The Haiku agent handles all
  * prose-judgment fixes (summary trims, section order, MEMORY.md prose).
  */
 function classOf(finding) {
@@ -34,14 +34,16 @@ function classOf(finding) {
 }
 
 /**
- * Every rule governing a scope with an open finding, as `id — hint` lines.
- * Handing the agent the full contract for the files it edits — not just the
- * failing rules — stops it fixing one finding by breaking another (dropping
- * the `**Last run**:` line, appending a section after `## Open Blockers`, …).
+ * Every rule that governs a scope with an open finding, as `id — hint` lines.
+ * The agent gets the full contract for the files it edits. The contract covers
+ * more than the rules that fail. It stops the agent from breaking one
+ * invariant while it fixes another finding (a dropped `**Last run**:` line, a
+ * section appended after `## Open Blockers`, …).
  *
- * Only static-string hints are listed: a function hint is a per-finding
- * resolved command (a `rotate` remediation the agent never performs), not a
- * file invariant, so listing it would leak its source text into the prompt.
+ * This lists only static-string hints. A function hint is a per-finding
+ * resolved command (a `rotate` remediation the agent never performs). A
+ * function hint is not a file invariant, so an entry for it would leak its
+ * source text into the prompt.
  */
 function invariantContract(findings) {
   const scopes = new Set(
@@ -53,52 +55,53 @@ function invariantContract(findings) {
 }
 
 /**
- * The opening task: the findings, the invariant contract, and the things the
- * rule hints don't cover — where trimmed history goes (only existing
- * weekly-log files; rotation owns minting new ones), and to prefer a single
- * Write.
+ * The opening task. It carries the findings, the invariant contract, and the
+ * things the rule hints do not cover. It says where trimmed history goes (only
+ * existing weekly-log files, because rotation mints the new ones). It also
+ * says to prefer a single Write.
  */
 function composeTask(findings, wikiRoot, projectRoot) {
   return [
-    `Fix these wiki audit findings by editing files under ${wikiRoot}.`,
+    `Fix these wiki audit findings. Edit files under ${wikiRoot}.`,
     ``,
     emitFindingsText(findings, { cwd: projectRoot }),
     ``,
-    `All of these invariants must hold when you finish — never fix one finding`,
-    `by breaking another:`,
+    `All of these invariants must hold when you finish. Never fix one finding`,
+    `and break another:`,
     ...invariantContract(findings),
     ``,
     `Move history out of an over-budget summary into the agent's existing`,
-    `weekly-log file or its current part (wiki/<agent>-YYYY-Www[-partN].md) —`,
-    `never a new summary section, and never a new file: rotation tooling owns`,
-    `when part files are created, so do not mint filenames yourself. If the`,
-    `trimmed narrative already exists in the weekly log, replace it in the`,
-    `summary with a pointer to that file instead of copying it anywhere.`,
+    `weekly-log file or its current part (wiki/<agent>-YYYY-Www[-partN].md).`,
+    `Never write a new summary section, and never a new file. The rotation`,
+    `tool owns when it creates part files, so do not mint filenames yourself.`,
+    `If the trimmed narrative already exists in the weekly log, replace it in`,
+    `the summary with a pointer to that file instead of copying it anywhere.`,
     `Prefer a single Write over many Edits.`,
   ].join("\n");
 }
 
-/** The resume task: the findings that survived the last edit. */
+/** The resume task. It carries the findings that survived the last edit. */
 function composeFollowup(findings, projectRoot) {
   return [
-    `The wiki still fails the audit. Remaining findings:`,
+    `The wiki still fails the audit. The findings that remain:`,
     ``,
     emitFindingsText(findings, { cwd: projectRoot }),
     ``,
-    `Fix every one without breaking any invariant listed earlier.`,
+    `Fix every one. Do not break any invariant listed earlier.`,
   ].join("\n");
 }
 
 /**
- * Deterministic pre-pass: seal every over-budget current-week weekly-log main
- * file via `rotateIfOverBudget`. The agent name comes from the audit's own
- * subjects (keyed by path) — no filename parsing. `force: true` rotates even a
- * word-over/line-under file.
+ * Deterministic pre-pass. It seals every over-budget current-week main log
+ * with `rotateIfOverBudget`. The agent name comes from the audit's own
+ * subjects (keyed by path), so nothing parses the filename. `force: true`
+ * rotates even a word-over/line-under file.
  *
- * `rotateIfOverBudget` always seals the agent's *current-week* log, so we only
- * call it when the finding IS that file. A prior-week over-budget main is left
- * untouched (rotating it would force-seal a healthy current-week log instead);
- * it survives the re-audit and is flagged for a human.
+ * `rotateIfOverBudget` always seals the agent's *current-week* log, so we call
+ * it only when the finding IS that file. A prior-week over-budget main log
+ * stays untouched. A rotation would force-seal a healthy current-week log
+ * instead. The over-budget main survives the re-audit, and the run flags it
+ * for a human.
  */
 /**
  * Seal one over-budget current-week main log. A failed seal leaves the source
@@ -133,8 +136,8 @@ function rotateOverBudgetMainLogs(findings, deps) {
   ];
   const agentByPath = new Map(subjects.map((s) => [s.path, s.agentPrefix]));
   // A log over BOTH budgets yields two `rotate` findings with the same path
-  // (different rule ids); seal each path once, or the second force call would
-  // bisect the freshly-written fresh-main into a spurious near-empty part.
+  // (different rule ids). Seal each path once. A second force call would
+  // bisect the newly written main file into a spurious near-empty part.
   const sealed = new Set();
   for (const f of findings) {
     if (classOf(f) !== "rotate") continue;
@@ -147,9 +150,9 @@ function rotateOverBudgetMainLogs(findings, deps) {
 }
 
 /**
- * Re-bisect one over-budget sealed part, logging each new sibling slot it
- * produces (the reused source slot is not a new file). A failed reseal leaves
- * the source intact (the writer rolled back), so the re-audit re-flags it.
+ * Re-bisect one over-budget sealed part. Log each new sibling slot it produces
+ * (the reused source slot is not a new file). A failed reseal leaves the
+ * source intact (the writer rolled back), so the re-audit re-flags it.
  */
 function resealPart(partPath, { fs, projectRoot, out, err }) {
   try {
@@ -171,15 +174,15 @@ function resealPart(partPath, { fs, projectRoot, out, err }) {
 }
 
 /**
- * Deterministic pass for over-budget sealed parts: re-bisect each at its
- * day-section seams. A part with no splittable seam is left byte-identical (the
- * re-audit re-flags it for a human). Agent and week come from the part filename,
- * so no subject lookup is needed. Part findings are disjoint from the main-log
- * findings `rotateOverBudgetMainLogs` handles.
+ * Deterministic pass for over-budget sealed parts. It re-bisects each part at
+ * its day-section seams. A part with no splittable seam stays byte-identical
+ * (the re-audit re-flags it for a human). Agent and week come from the part
+ * filename, so the pass needs no subject lookup. Part findings are disjoint
+ * from the main-log findings `rotateOverBudgetMainLogs` handles.
  */
 function rebisectOverBudgetParts(findings, deps) {
-  // A part over both budgets yields two findings with the same path; re-bisect
-  // each path once.
+  // A part over both budgets yields two findings with the same path.
+  // Re-bisect each path once.
   const done = new Set();
   for (const f of findings) {
     if (classOf(f) !== "rotate") continue;
@@ -190,7 +193,7 @@ function rebisectOverBudgetParts(findings, deps) {
   }
 }
 
-/** Report findings that need human judgment — never auto-fixed. */
+/** Report findings that need human judgment. Nothing auto-fixes them. */
 function reportFlags(err, flagFindings, projectRoot) {
   err(
     `gemba-wiki fix: ${flagFindings.length} finding(s) need human judgment ` +
@@ -200,11 +203,11 @@ function reportFlags(err, flagFindings, projectRoot) {
 }
 
 /**
- * Surface a round's agent error, if any. Returns true when it is fatal: a
- * missing sessionId means the process never started (e.g. the SDK refused
+ * Surface a round's agent error, if any. Returns true when the error is fatal.
+ * A missing sessionId means the process never started (e.g. the SDK refused
  * bypass-permissions as root), so there is nothing to resume. A turn-limit or
- * transient error keeps its session and may have made partial progress, so it
- * is noted but not fatal — the re-audit decides.
+ * transient error keeps its session and can make partial progress. The
+ * function notes it and does not treat it as fatal. The re-audit decides.
  */
 function isFatalError(result, round, err) {
   if (!result.error) return false;
@@ -237,10 +240,10 @@ async function buildFixRunner(ctx, projectRoot, runtime) {
 }
 
 /**
- * Run the agent on the prose-judgment findings, re-auditing each round until
- * clean, flag-only, or MAX_ROUNDS is exhausted. The audit is the verdict, not
- * the agent's self-report; resuming extends the turn budget for a trim too
- * large for one round.
+ * Run the agent on the prose-judgment findings. Re-audit each round until the
+ * wiki is clean, until only flags remain, or until MAX_ROUNDS is exhausted.
+ * The audit gives the verdict. The agent's self-report does not. A resume
+ * extends the turn budget for a trim too large for one round.
  */
 async function runAgentRounds(runner, agentFindings, deps) {
   const { wikiRoot, projectRoot, audit, partition, out, err } = deps;
@@ -291,10 +294,10 @@ export async function runFixCommand(ctx) {
       buildContext({ wikiRoot, today, fs, subprocess: runtime.subprocess }),
       { resolveScope },
     );
-  // The agent only ever gets prose-judgment (`agent`-class) findings. A
-  // `rotate` finding that survived the pre-pass (e.g. a prior-week log) is
-  // unfixable by the agent — and trimming append-only history to satisfy a
-  // budget would corrupt it — so it joins the flag set for a human.
+  // The agent only ever gets prose-judgment (`agent`-class) findings. The
+  // agent cannot fix a `rotate` finding that survived the pre-pass (e.g. a
+  // prior-week log). A trim of append-only history to satisfy a budget would
+  // corrupt the history. So the finding joins the flag set for a human.
   const partition = (found) => ({
     agentFindings: found.filter((f) => classOf(f) === "agent"),
     flagFindings: found.filter((f) => classOf(f) !== "agent"),
@@ -307,7 +310,7 @@ export async function runFixCommand(ctx) {
   }
 
   // Deterministic layer: seal over-budget main logs, then re-bisect over-budget
-  // sealed parts. Both are content-preserving — no agent, no history rewrite.
+  // sealed parts. Both preserve content, with no agent and no history rewrite.
   if (findings.some((f) => classOf(f) === "rotate")) {
     const rotateDeps = { wikiRoot, today, projectRoot, fs, out, err };
     rotateOverBudgetMainLogs(findings, rotateDeps);
@@ -319,15 +322,16 @@ export async function runFixCommand(ctx) {
     }
   }
 
-  // Residual: agent-class goes to the writer; everything else (flag, plus any
-  // rotate finding the deterministic pass could not handle) needs a human.
+  // Residual: agent-class goes to the writer. Everything else needs a human
+  // (flag, plus any rotate finding the deterministic pass could not handle).
   const { agentFindings, flagFindings } = partition(findings);
   if (agentFindings.length === 0) {
     reportFlags(err, flagFindings, projectRoot);
     return { ok: false, code: 2 };
   }
 
-  // Constructed only now, so a rotation-only or flag-only run never spawns it.
+  // Build the runner only now, so a rotation-only or flag-only run never
+  // spawns it.
   const runner = await buildFixRunner(ctx, projectRoot, runtime);
   return runAgentRounds(runner, agentFindings, {
     wikiRoot,

package/src/commands/inbox.js

@@ -104,7 +104,7 @@ function appendPriorityRow(memoryText, { item, agents, owner, status, added }) {
     ];
     return memoryText.replace(/\n*$/, "") + "\n" + block.join("\n");
   }
-  // Find last data row.
+  // Find the last data row.
   let sepIdx = -1;
   for (let i = headingIdx + 1; i < lines.length; i++) {
     if (/^\|\s*---/.test(lines[i])) {

package/src/commands/init.js

@@ -9,7 +9,12 @@ import {
   ACTIVE_CLAIMS_TABLE_SEPARATOR,
 } from "../constants.js";
 
-/** Resolve the wiki clone URL. Honors the FIT_WIKI_URL env var as an explicit override (for sandboxed environments where `origin` is rewritten to a local proxy that does not serve wiki repos); otherwise derives the URL by appending `.wiki.git` to the parent repo's `origin` remote. */
+/**
+ * Resolve the wiki clone URL. The FIT_WIKI_URL env var is an explicit
+ * override. Use it in a sandboxed environment where a local proxy replaces
+ * `origin` and does not serve wiki repos. Without that override, the function
+ * appends `.wiki.git` to the parent repo's `origin` remote.
+ */
 export async function deriveWikiUrl(gitClient, parentDir, env) {
   if (env.FIT_WIKI_URL) return env.FIT_WIKI_URL;
   try {
@@ -31,7 +36,7 @@ function scaffoldActiveClaims(runtime, memoryPath) {
     "",
     ACTIVE_CLAIMS_HEADING,
     "",
-    "In-flight work claimed by an agent. Row present = active; row absent = settled.",
+    "In-flight work claimed by an agent. Row present = active. Row absent = settled.",
     "Writers: `gemba-wiki claim`, `gemba-wiki release`. Reader: `gemba-wiki boot`.",
     "",
     ACTIVE_CLAIMS_TABLE_HEADER,
@@ -65,14 +70,14 @@ async function maybeCloneWiki(wikiSync, gitClient, projectRoot, runtime) {
   if (cloneResult.cloned) {
     await wikiSync.inheritIdentity();
   } else {
-    logger.warn(
-      "init",
-      "could not clone wiki, continuing with local-only steps",
-    );
+    logger.warn("init", "could not clone wiki, so only the local steps run");
   }
 }
 
-/** Clone the wiki if not already present, scaffold Active Claims in MEMORY.md, and create per-skill metric directories. */
+/**
+ * Clone the wiki if it is absent. Scaffold Active Claims in MEMORY.md. Create
+ * a metric directory for each skill.
+ */
 export async function runInitCommand(ctx) {
   const { runtime, wikiSync, gitClient } = ctx.deps;
   const options = ctx.options;

package/src/commands/ledger.js

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

package/src/commands/log.js

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

package/src/commands/memo.js

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

package/src/commands/product-mix.js

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

package/src/commands/refresh.js

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