@forwardimpact/libwiki 0.2.35 → 0.3.1

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 `fit-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 \`fit-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
@@ -122,7 +125,7 @@ function sealMainLog(agent, { wikiRoot, today, projectRoot, fs, out, err }) {
       );
     }
   } catch (e) {
-    err(`fit-wiki fix: rotate failed for ${agent}: ${e.message}\n`);
+    err(`gemba-wiki fix: rotate failed for ${agent}: ${e.message}\n`);
   }
 }
 
@@ -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 {
@@ -164,22 +167,22 @@ function resealPart(partPath, { fs, projectRoot, out, err }) {
     }
   } catch (e) {
     err(
-      `fit-wiki fix: rebisect failed for ` +
+      `gemba-wiki fix: rebisect failed for ` +
         `${path.relative(projectRoot, partPath)}: ${e.message}\n`,
     );
   }
 }
 
 /**
- * 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,29 +193,29 @@ 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(
-    `fit-wiki fix: ${flagFindings.length} finding(s) need human judgment ` +
+    `gemba-wiki fix: ${flagFindings.length} finding(s) need human judgment ` +
       `(not auto-fixable):\n` +
       emitFindingsText(flagFindings, { cwd: 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;
   if (!result.sessionId) {
-    err(`fit-wiki fix: agent run failed: ${result.error.message}\n`);
+    err(`gemba-wiki fix: agent run failed: ${result.error.message}\n`);
     return true;
   }
-  err(`fit-wiki fix: round ${round} agent error: ${result.error.message}\n`);
+  err(`gemba-wiki fix: round ${round} agent error: ${result.error.message}\n`);
   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;
@@ -265,7 +268,7 @@ async function runAgentRounds(runner, agentFindings, deps) {
   }
 
   err(
-    `fit-wiki fix: ${agentFindings.length} finding(s) remain after ` +
+    `gemba-wiki fix: ${agentFindings.length} finding(s) remain after ` +
       `${MAX_ROUNDS} round(s):\n` +
       emitFindingsText(agentFindings, { cwd: projectRoot }),
   );
@@ -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

@@ -13,7 +13,7 @@ function paths(runtime, options) {
   const wikiRoot = resolveWikiRoot(runtime, options);
   const resolved = requireAgentFlag(options, {
     command: "inbox",
-    example: "fit-wiki inbox list --agent staff-engineer",
+    example: "gemba-wiki inbox list --agent staff-engineer",
   });
   if (!resolved.ok) return { error: resolved };
   const agent = resolved.agent;
@@ -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,8 +36,8 @@ function scaffoldActiveClaims(runtime, memoryPath) {
     "",
     ACTIVE_CLAIMS_HEADING,
     "",
-    "In-flight work claimed by an agent. Row present = active; row absent = settled.",
-    "Writers: `fit-wiki claim`, `fit-wiki release`. Reader: `fit-wiki boot`.",
+    "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,
     ACTIVE_CLAIMS_TABLE_SEPARATOR,
@@ -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";
@@ -181,11 +181,11 @@ async function verify(env, options) {
 const SUBS = { allocate, rebuild, verify };
 
 /**
- * `fit-wiki ledger <allocate|rebuild|verify>` — the allocation procedure that
+ * `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;