@forwardimpact/libwiki 0.3.0 → 0.3.1

package/src/commands/claim.js

@@ -24,9 +24,9 @@ const NOT_PUBLISHED = {
 };
 
 // Failure reasons that, on the claim/release surfaces, are an unsafe-state
-// refusal (D7/D9 family) rather than a saved-locally success (D1): the refusal
-// fires before the local write is publishable, or leaves the tree unsafe for a
-// later whole-tree sweep, so the surface must exit non-zero.
+// refusal (D7/D9 family) rather than a saved-locally success (D1). The refusal
+// fires before the local write is publishable. Or it leaves the tree unsafe
+// for a later whole-tree sweep. So the surface must exit non-zero.
 const UNSAFE_STATE_REASONS = new Set([
   PUSH_REASONS.PRECONDITION,
   PUSH_REASONS.RESIDUE_CONFLICT,
@@ -37,7 +37,7 @@ const UNSAFE_STATE_REASONS = new Set([
 function notPublishedMessage(err) {
   return (
     `${err.message}\n` +
-    "The row was written to MEMORY.md but is NOT published — it remains an " +
+    "The row is in MEMORY.md but is NOT published. It remains an " +
     "uncommitted working-tree change.\n"
   );
 }
@@ -52,23 +52,25 @@ function memoryPath(runtime, options) {
 }
 
 /**
- * Push the claim/release MEMORY.md change and translate the honest outcome
- * (the honest-CLI contract) into a command envelope, composed with the singleton merge
- * discipline (the singleton merge discipline) and the secret/ancestry guards:
- * - landed (grounded or re-applied) ⇒ `{ ok: true }`, success message printed;
+ * Push the claim/release MEMORY.md change. Translate the honest outcome (the
+ * honest-CLI contract) into a command envelope. Compose it with the singleton
+ * merge discipline (the singleton merge discipline) and the secret/ancestry
+ * guards:
+ * - landed (grounded or re-applied) ⇒ `{ ok: true }` with a printed success
+ *   message;
  * - `rejected`/`transport` ⇒ `{ ok: true }` with a saved-locally warning (the
- *   landed-locally row is complete; the session-end push is its retry);
+ *   landed-locally row is complete, and the session-end push is its retry);
  * - `precondition`/`residue-conflict`/`conservation` ⇒ `{ ok: false, code: 1 }`
- *   (D7/D9 unsafe-state family — the row is not published and the tree may be
- *   left unsafe for a later whole-tree sweep);
+ *   (the D7/D9 unsafe-state family, where the row is not published and the
+ *   tree may be left unsafe for a later whole-tree sweep);
  * - a secret-gate refusal ⇒ `{ ok: false, code: 1 }` ({@link refusalEnvelope});
- * - an {@link AncestryRefusal} is rethrown so `pushRowOrRefuse` maps it to the
- *   not-published non-zero envelope;
+ * - this function rethrows an {@link AncestryRefusal} so `pushRowOrRefuse`
+ *   maps it to the not-published non-zero envelope;
  * - any other thrown error is a network/credential failure that degrades to
  *   "saved locally" (`{ ok: true }`).
  *
  * The `reapply` closure re-derives this row against the fresh tip if the
- * landing contends, so a parallel writer's row is never erased.
+ * landing contends, so this command never erases a parallel writer's row.
  *
  * @param {object} wikiSync - The WikiSync collaborator (may be absent in tests).
  * @param {object} runtime - The runtime bag (for stdout/stderr).
@@ -82,37 +84,38 @@ async function pushWiki(wikiSync, runtime, message, reapply) {
   let result;
   try {
     await wikiSync.inheritIdentity();
-    // claim/release contract is a 1-line MEMORY.md change; the pathspec keeps
-    // foreign uncommitted files from parallel writers out of the commit. The
-    // `reapply` closure re-derives this row against the fresh tip if the landing
-    // contends (the singleton merge discipline), so a parallel writer's row is never erased.
+    // The claim/release contract is a 1-line MEMORY.md change. The pathspec
+    // keeps foreign uncommitted files from parallel writers out of the commit.
+    // The `reapply` closure re-derives this row against the fresh tip if the
+    // landing contends (the singleton merge discipline), so this command never
+    // erases a parallel writer's row.
     result = await wikiSync.commitAndPush(message, ["MEMORY.md"], { reapply });
   } catch (err) {
-    // An ancestry-guard refusal pierces the saved-locally degradation: rethrow
-    // so pushRowOrRefuse maps it to the not-published non-zero envelope.
+    // An ancestry-guard refusal pierces the saved-locally degradation. Rethrow
+    // it so pushRowOrRefuse maps it to the not-published non-zero envelope.
     if (err instanceof AncestryRefusal) throw err;
     if (err instanceof WikiPushFailure) {
-      // D7/D9 unsafe-state family: the row is not published and the tree may be
-      // left unsafe for a later sweep — fail the command closed (non-zero).
+      // D7/D9 unsafe-state family. The row is not published, and the tree may
+      // be left unsafe for a later sweep. Fail the command closed (non-zero).
       if (UNSAFE_STATE_REASONS.has(err.reason)) {
         runtime.proc.stderr.write(`${err.message}\n`);
         return { ok: false, code: 1 };
       }
-      // rejected / transport: the local row landed; warn and keep zero exit.
+      // rejected / transport: the local row landed. Warn and keep zero exit.
       runtime.proc.stderr.write(
-        `saved locally — not yet visible to parallel sessions (${err.reason}): ${err.message}\n`,
+        `saved locally, not yet visible to parallel sessions (${err.reason}): ${err.message}\n`,
       );
       return { ok: true };
     }
-    // Any other failure: preserve fire-and-forget "saved locally" — the change
-    // is on disk and the command still succeeds.
+    // Any other failure: preserve fire-and-forget "saved locally". The change
+    // is on disk, and the command still succeeds.
     createLogger("wiki", runtime).warn(
       "claim",
       `push failed (saved locally): ${err.message}`,
     );
     return { ok: true };
   }
-  // A secret-gate refusal fails the command closed; a grounded-landed or a
+  // A secret-gate refusal fails the command closed. A grounded-landed or a
   // re-applied push reports success.
   const refusal = refusalEnvelope(runtime, result);
   if (refusal) return refusal;
@@ -123,16 +126,17 @@ async function pushWiki(wikiSync, runtime, message, reapply) {
 }
 
 /**
- * Push a written claim/release row, mapping an ancestry-guard refusal to the
- * not-published non-zero envelope and any other outcome to `pushWiki`'s
- * envelope. The row is already written to MEMORY.md; on refusal it stays as an
+ * Push a written claim/release row. Map an ancestry-guard refusal to the
+ * not-published non-zero envelope. Map any other outcome to `pushWiki`'s
+ * envelope. The row is already in MEMORY.md. On a refusal it stays as an
  * uncommitted working-tree change. The `reapply` closure re-derives the same
  * row against the fresh tip when the landing contends.
  */
 async function pushRowOrRefuse(wikiSync, runtime, message, reapply) {
   try {
     // Propagate pushWiki's envelope so a secret-gate or unsafe-state refusal
-    // ({ ok: false }) fails the command closed; a clean push returns { ok: true }.
+    // ({ ok: false }) fails the command closed. A clean push returns
+    // { ok: true }.
     return await pushWiki(wikiSync, runtime, message, reapply);
   } catch (err) {
     if (err instanceof AncestryRefusal) {
@@ -143,7 +147,7 @@ async function pushRowOrRefuse(wikiSync, runtime, message, reapply) {
   }
 }
 
-/** Insert a row into MEMORY.md `## Active Claims`. Refuses if (agent, target) already present. */
+/** Insert a row into MEMORY.md `## Active Claims`. It refuses if (agent, target) is already present. */
 export async function runClaimCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   const options = ctx.options;
@@ -162,8 +166,9 @@ export async function runClaimCommand(ctx) {
     };
   }
   const today = options.today || currentDayIso(runtime);
-  // Default expiry is claim+1 day: a claim is a short-lived "actively shipping
-  // this now" assertion, not a long lease. A run that outlives one day re-claims.
+  // Default expiry is claim+1 day. A claim is a short-lived "actively shipping
+  // this now" assertion. It is not a long lease. A run that outlives one day
+  // re-claims.
   const expires = options["expires-at"] || addDays(today, 1);
   const memPath = memoryPath(runtime, options);
   const text = readMemory(runtime, memPath);
@@ -220,8 +225,8 @@ export async function runReleaseCommand(ctx) {
     }
     runtime.fsSync.writeFileSync(memPath, current);
     runtime.proc.stdout.write(`released ${count} expired claim(s)\n`);
-    // Re-derive expiry against the fresh tip so a renewal landed since the stale
-    // read survives; only still-expired rows are removed.
+    // Re-derive expiry against the fresh tip so a renewal landed since the
+    // stale read survives. Remove only the rows that are still expired.
     const reapply = (fresh) => {
       const freshExpired = filterExpired(parseClaims(fresh), today).expired;
       let next = fresh;
@@ -265,8 +270,9 @@ export async function runReleaseCommand(ctx) {
     return { ok: true };
   }
   runtime.proc.stdout.write(`released ${options.target}\n`);
-  // Re-apply the same removal against the fresh tip if the landing contends;
-  // re-removing an absent row is a no-op, so a re-release never resurrects it.
+  // Re-apply the same removal against the fresh tip if the landing contends.
+  // A second removal of an absent row is a no-op, so a re-release never
+  // resurrects it.
   const reapply = (fresh) => {
     const r = removeClaim(fresh, { agent, target: options.target });
     return r.removed ? r.text : null;

package/src/commands/curate.js

@@ -7,8 +7,8 @@ import { resolveProjectRoot } from "../util/wiki-dir.js";
 import { auditWiki } from "./audit.js";
 
 // The routing contract: a single open issue, addressed to the technical-writer,
-// holding the audit findings. The title is matched verbatim on every run so a
-// dirty wiki appends to one issue rather than opening a new one each day.
+// that holds the audit findings. Every run matches the title verbatim, so a
+// dirty wiki appends to one issue and does not open a new one each day.
 const LABEL = {
   name: "wiki-curation",
   color: "BFD4F2",
@@ -19,13 +19,14 @@ const TITLE = "Wiki curation: shared-state audit findings";
 // GitHub rejects an issue or comment body over 65536 characters. Keep the whole
 // body under a margin below that so the preamble, JSON fence, and truncation
 // notice always fit. When the findings overflow, the body carries the first N
-// that fit plus a count; the full list stays reproducible via `gemba-wiki audit`.
+// that fit plus a count. `gemba-wiki audit` still reproduces the full list.
 const MAX_BODY = 65000;
 
 /**
  * Compose the issue body from the audit's JSON findings. The findings ride a
- * fenced ```json block; the body is passed to `gh` via `--body-file` (a temp
- * file), never argv, so untrusted finding text cannot be misread as a flag.
+ * fenced ```json block. The caller passes the body to `gh` through
+ * `--body-file` (a temp file) and never through argv. So `gh` cannot misread
+ * untrusted finding text as a flag.
  * @param {string} findingsJson
  * @param {{shown?: number, total?: number}} [trunc]
  * @returns {string}
@@ -34,12 +35,12 @@ function buildBody(findingsJson, { shown, total } = {}) {
   const lines = [
     "Scheduled `curate-wiki` audit found shared-wiki violations.",
     "",
-    "Owner: **technical-writer** (service these via the curation shift; the per-PR `wiki` gate no longer reads shared wiki state).",
+    "Owner: **technical-writer**. Service these through the curation shift. The per-PR `wiki` gate no longer reads shared wiki state.",
     "",
   ];
   if (total != null && shown != null && shown < total) {
     lines.push(
-      `Showing ${shown} of ${total} findings — the body was truncated to fit GitHub's comment limit. Run \`gemba-wiki audit\` for the full list.`,
+      `Showing ${shown} of ${total} findings. The body is truncated to fit GitHub's comment limit. Run \`gemba-wiki audit\` for the full list.`,
       "",
     );
   }
@@ -49,9 +50,10 @@ function buildBody(findingsJson, { shown, total } = {}) {
 
 /**
  * Build the largest postable body for the audit findings. The full findings
- * usually fit; when they don't, keep the first N `fail` findings that stay
- * under GitHub's body limit and label the body as truncated. The shrink steps
- * down proportionally to the overflow, so it converges in a couple of passes.
+ * usually fit. When they do not fit, keep the first N `fail` findings that
+ * stay under GitHub's body limit. Label the body as truncated. The shrink
+ * steps down proportionally to the overflow, so it converges in a couple of
+ * passes.
  * @param {{level: string}[]} findings
  * @returns {string}
  */
@@ -76,8 +78,8 @@ function fitBody(findings) {
 
 // Resolve the monorepo's `owner/repo` slug the way refresh.js/product-mix.js
 // do: an explicit FIT_GH_REPO override (sandbox proxy URLs), else the origin
-// remote parsed via the injected git client. Null lets `gh` fall back to its
-// own cwd resolution.
+// remote parsed through the injected git client. Null lets `gh` fall 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;
@@ -88,7 +90,7 @@ async function deriveRepo(gitClient, cwd, env) {
   }
 }
 
-// A missing token is non-fatal: `gh` may still resolve ambient auth.
+// A missing token is non-fatal. `gh` may still resolve ambient auth.
 async function resolveToken() {
   try {
     return (await createScriptConfig("wiki")).ghToken();
@@ -98,8 +100,9 @@ async function resolveToken() {
 }
 
 /**
- * Find the open `wiki-curation` issue by its verbatim title, or null. Any
- * parse failure or empty result is treated as "no issue" (create path).
+ * Find the open `wiki-curation` issue by its verbatim title, or null. This
+ * function treats any parse failure or empty result as "no issue" (create
+ * path).
  * @param {import("@forwardimpact/libcli").InvocationContext["deps"]["runtime"]} runtime
  * @param {string[]} repoArgs
  * @param {{cwd: string, env: object}} opts
@@ -129,11 +132,11 @@ async function findOpenIssue(runtime, repoArgs, opts) {
 }
 
 /**
- * Route the composed body to the single `wiki-curation` issue: ensure the
- * label, find the open issue by title, then comment on it or create it. The
- * body goes through a temp file (never argv) so untrusted finding text cannot
- * be read as a flag. On a `gh` failure the reason is logged and `ok:false`
- * returned so the caller exits non-zero.
+ * Route the composed body to the single `wiki-curation` issue: make sure the
+ * label exists, find the open issue by title, then comment on it or create it.
+ * The body goes through a temp file and never through argv. So `gh` cannot
+ * read untrusted finding text as a flag. On a `gh` failure this function logs
+ * the reason and returns `ok:false`, so the caller exits non-zero.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @param {string} body
  * @param {ReturnType<typeof createLogger>} logger
@@ -150,8 +153,8 @@ async function routeFindings(ctx, body, logger) {
     : runtime.proc.env;
   const repoArgs = repo ? ["--repo", repo] : [];
 
-  // Ensure the label exists; a re-create on an existing label exits non-zero,
-  // which is expected and ignored.
+  // Make sure the label exists. A re-create on an existing label exits
+  // non-zero. That is expected, and the code ignores it.
   await runtime.subprocess.run(
     "gh",
     [
@@ -169,8 +172,8 @@ async function routeFindings(ctx, body, logger) {
 
   const number = await findOpenIssue(runtime, repoArgs, { cwd, env });
 
-  // Pass the body through a temp file, not argv — robust to length and immune
-  // to finding text being read as a flag.
+  // Pass the body through a temp file instead of argv. A temp file is robust
+  // to length, and `gh` cannot read finding text as a flag.
   const tmp = runtime.proc.env.RUNNER_TEMP || runtime.proc.env.TMPDIR || "/tmp";
   const bodyFile = path.join(tmp, "wiki-curation-body.md");
   runtime.fsSync.writeFileSync(bodyFile, body);
@@ -208,12 +211,12 @@ async function routeFindings(ctx, body, logger) {
 }
 
 /**
- * Audit the shared wiki and, when it is dirty, route the findings to the
- * single `wiki-curation` issue (create or comment) addressed to the
- * technical-writer. This is the SOLE home of the shared-wiki audit verdict; the
- * per-PR `wiki` gate no longer reads live wiki state. A clean wiki routes
- * nothing. The label/search/create-or-comment logic lives here, not in the
- * workflow, so the curation step is one CLI call.
+ * Audit the shared wiki. When it is dirty, route the findings to the single
+ * `wiki-curation` issue (create or comment) addressed to the technical-writer.
+ * This is the SOLE home of the shared-wiki audit verdict. The per-PR `wiki`
+ * gate no longer reads live wiki state. A clean wiki routes nothing. The
+ * label/search/create-or-comment logic lives here and not in the workflow, so
+ * the curation step is one CLI call.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: boolean}>}
@@ -224,7 +227,7 @@ export async function runCurateCommand(ctx) {
   const { findings } = auditWiki(ctx);
 
   if (!findings.some((f) => f.level === "fail")) {
-    runtime.proc.stdout.write("wiki audit clean — no curation issue routed\n");
+    runtime.proc.stdout.write("wiki audit clean, no curation issue routed\n");
     return { ok: true };
   }
 

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;