@forwardimpact/libwiki 0.3.0 → 0.3.2

package/src/cli-definition.js

@@ -14,13 +14,13 @@ import { runFixCommand } from "./commands/fix.js";
 import { runLedgerCommand } from "./commands/ledger.js";
 
 /**
- * Build the `gemba-wiki` libcli definition. Agent identity is never resolved from
- * the environment: agent-scoped subcommands require an explicit `--agent`
- * (`--from` for `memo`) and fail closed without it, so this module carries no
- * ambient agent identity. The version is resolved by libcli's `createCli` from
- * the bin's `packageJsonUrl`. Each subcommand carries a `handler` and (for
- * subcommand-bearing commands) `args`/`argsUsage` so `cli.dispatch` can route to
- * the per-command handler with a frozen `ctx`.
+ * Build the `gemba-wiki` libcli definition. This module never resolves agent
+ * identity from the environment. Agent-scoped subcommands require an explicit
+ * `--agent` (`--from` for `memo`). They fail closed without it, so this module
+ * carries no ambient agent identity. libcli's `createCli` resolves the version
+ * from the bin's `packageJsonUrl`. Each subcommand carries a `handler`. A
+ * command that takes subcommands also carries `args`/`argsUsage`, so
+ * `cli.dispatch` can route to the per-command handler with a frozen `ctx`.
  *
  * @returns {object} The libcli definition.
  */
@@ -48,12 +48,12 @@ export function createDefinition() {
 
   return {
     name: "gemba-wiki",
-    description: "Wiki lifecycle management for the Kata agent system",
+    description: "Manage the wiki lifecycle for the Kata agent system",
     commands: [
       {
         name: "boot",
         description:
-          "Print on-boot digest (priorities, claims, storyboard items) as JSON",
+          "Print the on-boot digest (priorities, claims, storyboard items) as JSON",
         handler: runBootCommand,
         options: {
           ...agentOpt,
@@ -101,9 +101,12 @@ export function createDefinition() {
           ...todayOpt,
           target: {
             type: "string",
-            description: "What is being claimed (spec id, PR id, etc.)",
+            description: "Target to claim (spec id, PR id, etc.)",
+          },
+          branch: {
+            type: "string",
+            description: "Branch that carries the work",
           },
-          branch: { type: "string", description: "Branch carrying the work" },
           pr: { type: "string", description: "Optional PR id" },
           "expires-at": {
             type: "string",
@@ -142,7 +145,7 @@ export function createDefinition() {
           },
           owner: {
             type: "string",
-            description: "Owner field when promoting (default: --agent)",
+            description: "Owner field for promote (default: --agent)",
           },
         },
       },
@@ -190,7 +193,7 @@ export function createDefinition() {
           "dry-run": {
             type: "boolean",
             description:
-              "Print the issue body and intended action without calling gh",
+              "Print the issue body and intended action. Do not call gh",
           },
         },
       },
@@ -217,7 +220,7 @@ export function createDefinition() {
           to: {
             type: "string",
             description:
-              'Target agent name, or "all" to broadcast (sender is skipped)',
+              'Target agent name, or "all" to broadcast (skips the sender)',
           },
           message: {
             type: "string",
@@ -287,7 +290,7 @@ export function createDefinition() {
             type: "string",
             multiple: true,
             description:
-              "Pathspec(s) limiting the write-set; omit to land the session's dirty set",
+              "Pathspec(s) that limit the write-set. Omit to land the session's dirty set",
           },
         },
       },
@@ -330,7 +333,7 @@ export function createDefinition() {
           gapped: {
             type: "boolean",
             description:
-              "Render double-allocation losers as a gap, not a renumber",
+              "Render double-allocation losers as a gap instead of a renumber",
           },
           issue: {
             type: "string",
@@ -367,25 +370,25 @@ export function createDefinition() {
     documentation: [
       {
         title: "Operate a Predictable Agent Team",
-        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/index.md",
+        url: "https://www.gemba.team/docs/predictable-team/index.md",
         description:
           "End-to-end guide to wiki memory, XmR charts, and team coordination.",
       },
       {
         title: "Send a Memo or Update a Storyboard",
-        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-operations/index.md",
+        url: "https://www.gemba.team/docs/predictable-team/wiki-operations/index.md",
         description:
           "Send cross-team memos, refresh storyboard charts, sync the wiki, and record the product-mix metric.",
       },
       {
         title: "Audit and Auto-Fix the Wiki",
-        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-integrity/index.md",
+        url: "https://www.gemba.team/docs/predictable-team/wiki-integrity/index.md",
         description:
           "Check the wiki against the rule catalogue, auto-fix what is safe, and flag the rest for a human.",
       },
       {
         title: "Allocate Collision-Ledger Entries for Parallel Work",
-        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/collision-ledger/index.md",
+        url: "https://www.gemba.team/docs/predictable-team/collision-ledger/index.md",
         description:
           "Assign stable, collision-free ids to parallel work and rebuild the ledger projections.",
       },

package/src/commands/audit.js

@@ -11,8 +11,8 @@ import { resolveProjectRoot } from "../util/wiki-dir.js";
 
 /**
  * Run the wiki audit and return its findings plus the resolved project root.
- * Shared by `runAuditCommand` (emits them) and `runCurateCommand` (routes
- * them to an issue) so the two cannot drift.
+ * `runAuditCommand` emits the findings. `runCurateCommand` routes them to an
+ * issue. Both share this function, so the two cannot drift.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {{ findings: object[], projectRoot: string }}
  */
@@ -32,7 +32,7 @@ export function auditWiki(ctx) {
   return { findings: runRules(RULES, auditCtx, { resolveScope }), projectRoot };
 }
 
-/** Run the wiki audit and emit findings. JSON via --format json. */
+/** Run the wiki audit and emit findings. Use --format json for JSON. */
 export function runAuditCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;

package/src/commands/boot.js

@@ -40,7 +40,7 @@ function renderMarkdown(digest) {
   return lines.join("\n");
 }
 
-/** Print the on-boot digest for the calling agent. JSON by default; --format markdown renders prose. */
+/** Print the on-boot digest for the agent that runs it. JSON by default. --format markdown renders prose. */
 export function runBootCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;

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 };
   }