@forwardimpact/libwiki 0.3.0 → 0.3.1

package/src/audit/scopes.js

@@ -39,8 +39,8 @@ function listMdFiles(wikiRoot, fs) {
 }
 
 // Recursively collect every *.csv under `<wikiRoot>/metrics/`. The real layout
-// is `metrics/<skill>/<year>.csv` (two levels), so the walk recurses rather
-// than assuming a fixed depth. Uses readdirSync + statSync (rather than
+// is `metrics/<skill>/<year>.csv` (two levels), so the walk recurses and does
+// not assume a fixed depth. The walk uses readdirSync + statSync (rather than
 // `withFileTypes` Dirents) so it runs unchanged under the in-memory mock fs.
 function listCsvFiles(wikiRoot, fs) {
   const metricsRoot = path.join(wikiRoot, "metrics");
@@ -57,7 +57,7 @@ function listCsvFiles(wikiRoot, fs) {
   return found;
 }
 
-// Load a metrics CSV as an audit subject: `rows` is the array of line strings,
+// Load a metrics CSV as an audit subject. `rows` is the array of line strings,
 // so a rule indexes `rows[i]` (a string) and `i + 1` is its line number.
 function loadCsv(filePath, fs) {
   return {
@@ -97,8 +97,8 @@ function loadFile(filePath, fs) {
 function classifyFile(filePath, fs) {
   const base = path.basename(filePath);
   if (EXCLUDED_BASES.has(base)) return null;
-  // STATUS.md is loaded separately (readOptional in buildContext) and audited
-  // via the dedicated `status-row` scope — skip the per-file classification.
+  // buildContext loads STATUS.md separately with readOptional. The dedicated
+  // `status-row` scope audits it. So skip the per-file classification.
   if (base === "STATUS.md") return null;
   if (NON_SUMMARY_PREFIXES.some((p) => base.startsWith(p))) return null;
   if (WEEKLY_LOG_NAME_RE.test(base)) {
@@ -109,23 +109,23 @@ function classifyFile(filePath, fs) {
   }
   const subject = loadFile(filePath, fs);
   // Carry surface: a `<agent>-carries.md` whose H1 matches the Carry H1 RE.
-  // Both axes must match (filename prefix and H1), mirroring the summary
-  // classifier. The two H1 REs end in distinct literals (`— Carries` vs
-  // `— Summary`) so the branches cannot cross-capture regardless of order;
-  // a name-match + H1-miss is left unclassified, like a malformed summary.
+  // Both axes must match (filename prefix and H1), like the summary
+  // classifier. The two H1 REs end in distinct literals (`— Carries` and
+  // `— Summary`) so the branches cannot cross-capture regardless of order.
+  // A name-match with an H1-miss stays unclassified, like a malformed summary.
   if (CARRY_SURFACE_NAME_RE.test(base)) {
     if (CARRY_SURFACE_H1_RE.test(subject.firstLine)) {
       return { kind: "carry-surface", subject };
     }
     return null;
   }
-  // Files that do not match a summary or weekly-log shape are left
-  // unclassified: stray files are not audited.
+  // A file that does not match a summary or weekly-log shape stays
+  // unclassified. The audit skips stray files.
   if (!SUMMARY_H1_RE.test(subject.firstLine)) return null;
   return { kind: "summary", subject };
 }
 
-// Read a file if present; an absent file yields empty text so callers audit
+// Read a file if present. An absent file yields empty text so callers audit
 // "missing" uniformly. The common { path, text, exists } shape backs the
 // MEMORY.md, STATUS.md, and storyboard context loads.
 function readOptional(filePath, fs) {
@@ -139,7 +139,8 @@ function readOptional(filePath, fs) {
 
 // MEMORY.md carries the same line/word budget rules as the prose surfaces, so
 // its subject needs the `lines`/`words` counters those check builders read.
-// Counted off the canonical budget.js pair, like every other budgeted surface.
+// The loader counts them off the canonical budget.js pair, like every other
+// budgeted surface.
 function loadMemory(filePath, fs) {
   const base = readOptional(filePath, fs);
   return {
@@ -150,11 +151,11 @@ function loadMemory(filePath, fs) {
 }
 
 /**
- * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
- * outside the ``` fence (header prose) and blank lines are skipped. Each row
- * carries a `kind` from {@link parseStatusRowId} (`"spec"`, `"experiment"`, or
- * `null` for an unrecognized id); spec-shaped rules read the positional
- * `id`/`phase`/`status` fields, experiment rules read `cells`.
+ * Parse the rows inside STATUS.md's fenced block into audit subjects. The
+ * parser skips lines outside the ``` fence (header prose) and blank lines.
+ * Each row carries a `kind` from {@link parseStatusRowId} (`"spec"`,
+ * `"experiment"`, or `null` for an unrecognized id). Spec-shaped rules read
+ * the positional `id`/`phase`/`status` fields. Experiment rules read `cells`.
  * @param {string} statusText - The full STATUS.md contents.
  * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string, kind: string|null}>}
  */
@@ -171,9 +172,9 @@ function parseStatusRows(statusText) {
     if (!inFence || line.trim() === "") continue;
     const cells = line.split("\t");
     // Classify by id prefix so a malformed `exp:` row (e.g. wrong cell count)
-    // is still routed to the experiment rules, which flag it — rather than
-    // slipping through the spec-shaped rules. parseStatusRowId returns the
-    // structured fields only for a well-formed row; the rules read `cells`.
+    // still routes to the experiment rules, which flag it. It does not slip
+    // through the spec-shaped rules. parseStatusRowId returns the structured
+    // fields only for a well-formed row. The rules read `cells`.
     const isExp = typeof cells[0] === "string" && cells[0].startsWith("exp:");
     const parsed = parseStatusRowId(cells[0], cells);
     rows.push({
@@ -276,12 +277,12 @@ const SCOPE_RESOLVERS = {
 
 // Normalize every audited surface into a uniform `{ path, text, fenceExempt }`
 // subject for the conflict-marker scan. The per-file subjects (summaries,
-// weekly logs and sealed parts, storyboard) carry `fileLines`; MEMORY.md and
+// weekly logs and sealed parts, storyboard) carry `fileLines`. MEMORY.md and
 // STATUS.md carry `text` (readOptional shape). `fenceExempt` is true for prose
-// surfaces, where a fence quotes content, and false for STATUS.md, whose fenced
-// rows are data — a marker there is never legitimate (per-surface fence
-// contract). Files absent from disk (missing MEMORY/STATUS/storyboard) yield
-// empty text and produce no findings.
+// surfaces, where a fence quotes content. It is false for STATUS.md, whose
+// fenced rows are data. A marker there is never legitimate (per-surface fence
+// contract). A file absent from disk (no MEMORY/STATUS/storyboard) yields
+// empty text and produces no findings.
 function conflictScanSubjects(ctx) {
   const subjects = [];
   const fileScopes = ["summary", "weekly-log-main", "weekly-log-part"];
@@ -320,12 +321,12 @@ export function resolveScope(scopeKey, ctx) {
 }
 
 /**
- * Build the admission slice: the tracked-file universe plus the
- * `rootSummaryAgents` set that gates `<agent>/` sidecar directories. The agent
- * set is derived first (a root-level summary-class file's stem) so the
- * `admission` scope can classify sidecar directories against it.
+ * Build the admission slice. It holds the tracked-file universe plus the
+ * `rootSummaryAgents` set that gates `<agent>/` sidecar directories. The
+ * function derives the agent set first (a root-level summary-class file's
+ * stem) so the `admission` scope can classify sidecar directories against it.
  *
- * Returns the empty universe when `subprocess` is absent — callers that only
+ * Returns the empty universe when `subprocess` is absent. Callers that only
  * read `.subjects` (the rotation pre-pass) skip the git read and the tree walk
  * entirely, and produce no `admission` findings.
  */
@@ -342,9 +343,9 @@ function buildAdmission(wikiRoot, fs, subprocess) {
 }
 
 /**
- * Build the audit context: classifies and loads every wiki file once.
+ * Build the audit context. It classifies and loads every wiki file once.
  * @param {{wikiRoot: string, today: string, fs: object, subprocess: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`); `subprocess` is
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `subprocess` is
  *   `runtime.subprocess` (its `runSync` backs the admission scope's git read).
  */
 export function buildContext({ wikiRoot, today, fs, subprocess }) {

package/src/audit/status-row.js

@@ -1,7 +1,7 @@
 import { STATUS_ID_REGEX } from "../status.js";
 
-// Validate every row inside wiki/STATUS.md's code fence. Rows are resolved by
-// the `status-row` scope in scopes.js; each subject carries
+// Validate every row inside wiki/STATUS.md's code fence. The `status-row`
+// scope in scopes.js resolves the rows. Each subject carries
 // `{ cells, id, phase, status, kind, text }`. Two row kinds share the fence:
 //
 //   spec        `{id}<TAB>{phase}<TAB>{status}` — three cells
@@ -40,7 +40,7 @@ export const STATUS_ROW_RULES = [
     when: hasThreeCells,
     check: (s) => (STATUS_ID_REGEX.test(s.id) ? null : { id: s.id }),
     message: (_s, r) => `Bad id '${r.id}' (expected ^\\d{4}(/[a-z0-9-]+)?$)`,
-    hint: "spec ids are four digits; a sub-row appends `/<unit>` (e.g. 1370/libutil)",
+    hint: "spec ids are four digits. a sub-row appends `/<unit>` (e.g. 1370/libutil)",
   },
   {
     id: "status-row.phase",
@@ -73,11 +73,10 @@ export const STATUS_ROW_RULES = [
     hint: "each experiment row is `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}`",
   },
   {
-    // An experiment-kind row is classified by its `exp:` id prefix
-    // (scopes.js), so the spec `id-format` rule is skipped for it; this rule
-    // enforces the `exp:\d+` id so a non-numeric issue (e.g. `exp:abc`) flags
-    // rather than auditing clean — keeping the audit aligned with
-    // STATUS_ID_REGEX / parseStatusRowId.
+    // scopes.js classifies an experiment-kind row by its `exp:` id prefix, so
+    // the spec `id-format` rule skips it. This rule enforces the `exp:\d+` id,
+    // so a non-numeric issue (e.g. `exp:abc`) flags and does not audit clean.
+    // That keeps the audit aligned with STATUS_ID_REGEX / parseStatusRowId.
     id: "status-row.exp-id-format",
     scope: "status-row",
     severity: "fail",
@@ -101,10 +100,10 @@ export const STATUS_ROW_RULES = [
     scope: "status-row",
     severity: "fail",
     when: hasFourCells,
-    // The pin is decidable per state, with no "ever approved" inference: a
-    // `registered` row has no pin (`-`); an `approved` row pins the 40-hex
-    // head; a `cancelled` row may carry the retained pin or `-` (it may or may
-    // not have been approved before cancellation), so both are accepted.
+    // The pin is decidable per state, with no "ever approved" inference. A
+    // `registered` row has no pin (`-`). An `approved` row pins the 40-hex
+    // head. A `cancelled` row may carry the retained pin or `-`, because it
+    // may or may not pass through `approved` first. So the check accepts both.
     check: (s) => {
       const [, state, pin] = s.cells;
       if (state === "registered") {
@@ -118,11 +117,11 @@ export const STATUS_ROW_RULES = [
           ? null
           : { state, pin, want: "`-` or a 40-hex SHA" };
       }
-      return null; // bad state already flagged by exp-state
+      return null; // exp-state already flags a bad state
     },
     message: (_s, r) =>
       `Bad pin '${r.pin}' for state '${r.state}' (expected ${r.want})`,
-    hint: "registered pins `-`; approved pins a 40-hex SHA; cancelled pins either",
+    hint: "registered pins `-`. approved pins a 40-hex SHA. cancelled pins either",
   },
   {
     id: "status-row.exp-planref",
@@ -131,6 +130,6 @@ export const STATUS_ROW_RULES = [
     when: hasFourCells,
     check: (s) => (/^#\d+$/.test(s.cells[3]) ? null : { planRef: s.cells[3] }),
     message: (_s, r) => `Bad plan-ref '${r.planRef}' (expected #NNN)`,
-    hint: "the plan-ref names the issue carrying the execution plan, e.g. #NNN",
+    hint: "the plan-ref names the issue that carries the execution plan, e.g. #NNN",
   },
 ];

package/src/block-renderer.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { analyze, renderChart, MIN_POINTS } from "@forwardimpact/libxmr";
 
-/** Error thrown when an XmR block cannot be rendered due to missing CSV or metric. */
+/** Error the renderer throws when an XmR block has no CSV or no metric. */
 export class BlockRenderError extends Error {
   /** Create a BlockRenderError with the given reason string. */
   constructor(reason) {
@@ -11,11 +11,12 @@ export class BlockRenderError extends Error {
 }
 
 /**
- * Render an XmR chart block for a metric by reading its CSV and producing
+ * Render an XmR chart block for a metric. Read its CSV and produce the
  * markdown lines.
  * @param {{metric: string, csvPath: string, projectRoot: string, fs: object, priorReadAnchor?: string|null}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`). `priorReadAnchor`,
- *   when supplied, stamps per-signal provenance surfaced in the Signals line.
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `priorReadAnchor`
+ *   stamps per-signal provenance when the caller supplies it. The Signals line
+ *   surfaces that provenance.
  */
 export function renderBlock({
   metric,

package/src/boot.js

@@ -130,10 +130,11 @@ function bulletItem(threshold, agent) {
 }
 
 // Advance the agent-section scan for one storyboard line that is NOT inside the
-// materialized block. Returns the next `inAgent` state and pushes an h3-bullet
-// item for the booting agent when one is found. An h2 ends the agent-section
-// scan (team-wide sections follow the last agent h3 — without this the scan
-// would run past the agent sections and misattribute team-wide bullets).
+// materialized block. Returns the next `inAgent` state. When the scan finds an
+// h3 bullet for the agent that boots, it pushes that item. An h2 ends the
+// agent-section scan, because team-wide sections follow the last agent h3.
+// Without this the scan would run past the agent sections and misattribute
+// team-wide bullets.
 function scanAgentLine(line, agent, inAgent, items) {
   if (/^## /.test(line)) return false;
   const h3Match = line.match(/^### (.+)$/);
@@ -152,8 +153,9 @@ function parseStoryboardItems(text, agent) {
   let inBlock = false;
   for (const line of text.split("\n")) {
     // The materialized block carries `- #N [agent] …` bullets that the agent
-    // scan must never capture; track it so the bullet loop skips inside it.
-    // (Without it the legacy scan double-counted these as the last agent's bullets.)
+    // scan must never capture. Track it so the bullet loop skips inside it.
+    // (Without it the legacy scan double-counted these as the last agent's
+    // bullets.)
     if (AGENT_EXPERIMENTS_OPEN_RE.test(line)) {
       inBlock = true;
       inAgent = false;
@@ -204,7 +206,7 @@ function countInbox(text) {
 /**
  * Remaining budget for a budgeted surface: current value, cap, and headroom for
  * both the line and word budget. An absent file (empty text) reports zero usage
- * and full headroom so a writer sees the ceiling before composing.
+ * and full headroom so a writer sees the ceiling before they compose.
  */
 function headroom(text, lineCap, wordCap) {
   const lines = countLines(text);
@@ -237,7 +239,7 @@ function mapClaim(c) {
 /**
  * Build the boot digest JSON object.
  * @param {{wikiRoot: string, agent: string, today: string, fs: object}} options
- *   `fs` is the sync filesystem surface (`runtime.fsSync`); `today` is an ISO
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `today` is an ISO
  *   date string.
  */
 export function buildDigest({ wikiRoot, agent, today, fs }) {

package/src/budget-gate.js

@@ -1,14 +1,14 @@
 // Post-landing, pre-push budget re-validation on the size (word/line) axis.
 //
 // The wiki landing flow re-runs the audit's budget predicates over the
-// outgoing tree between landing and push, and refuses a push that introduces
+// outgoing tree between landing and push. It refuses a push that introduces
 // or deepens a per-file budget breach this writer's push would publish. The
-// gate reuses the audit's budget rules by reference: it resolves the rule
-// objects named by `BUDGET_RULE_IDS` and calls each rule's own `check` (the
-// over-cap predicate) plus the same `countWords` / `countLines` the audit
-// builds its subjects from. It never re-defines a budget, never routes through
-// the `runRules` engine (which drops the numeric value and emits nothing under
-// cap), and never edits — it refuses, keeping commits local.
+// gate reuses the audit's budget rules by reference. It resolves the rule
+// objects named by `BUDGET_RULE_IDS`. It then calls each rule's own `check`
+// (the over-cap predicate) plus the same `countWords` / `countLines` the audit
+// builds its subjects from. It never re-defines a budget. It never routes
+// through the `runRules` engine, which drops the numeric value and emits
+// nothing under cap. It never edits. It refuses, which keeps commits local.
 
 import path from "node:path";
 import { BUDGET_RULE_IDS, RULES } from "./audit/rules.js";
@@ -16,9 +16,10 @@ import { buildContext, resolveScope } from "./audit/scopes.js";
 import { countLines, countWords } from "./budget.js";
 
 /**
- * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`, tagging each with
- * the count axis its id implies. Throws if a named id is missing from `RULES`,
- * so a rule rename surfaces here rather than silently dropping a predicate.
+ * Resolve `BUDGET_RULE_IDS` to their rule objects in `RULES`. Tag each one with
+ * the count axis its id implies. It throws if a named id is missing from
+ * `RULES`, so a rule rename surfaces here and does not silently drop a
+ * predicate.
  * @returns {Array<{id: string, scope: string, axis: 'words'|'lines', check: Function}>}
  */
 export function budgetRules() {
@@ -36,10 +37,10 @@ export function budgetRules() {
 }
 
 /**
- * Enumerate which wiki files are budgeted, by reusing the audit's
- * classification. Subjects carry an absolute `path`, so each is reduced to the
- * `<file>` half of `git show <ref>:<file>` relative to `wikiRoot`. No count is
- * read off the working-dir subject — only the file identity and its scope.
+ * Enumerate which wiki files are budgeted. Reuse the audit's classification.
+ * Subjects carry an absolute `path`. Reduce each one to the `<file>` half of
+ * `git show <ref>:<file>`, relative to `wikiRoot`. This function reads no count
+ * off the working-dir subject. It reads only the file identity and its scope.
  * @param {object} ctx - An audit context from `buildContext`.
  * @param {string} wikiRoot - The wiki clone directory the paths are relative to.
  * @returns {Array<{relPath: string, scope: string}>}
@@ -56,12 +57,12 @@ export function budgetedFiles(ctx, wikiRoot) {
 }
 
 /**
- * Measure the budget predicates for the tree at `ref`. Reads each budgeted
- * file's blob via the cwd-bound `showFile`, counts it once with the audit's
- * counters, then for every budget rule on that file's scope records the axis
+ * Measure the budget predicates for the tree at `ref`. Read each budgeted
+ * file's blob through the cwd-bound `showFile`. Count it once with the audit's
+ * counters. Then, for every budget rule on that file's scope, record the axis
  * value and whether the rule's own `check` flags it over cap. An absent path
- * at the ref counts as 0 (matching the audit's "missing counts as empty"
- * posture); an unreadable ref makes `showFile` throw, which propagates.
+ * at the ref counts as 0. This matches the audit's "missing counts as empty"
+ * posture. An unreadable ref makes `showFile` throw, and the throw propagates.
  * @param {(ref: string, file: string) => Promise<string|null>} showFile
  * @param {string} ref - The tree-ish to measure (e.g. "HEAD", a SHA).
  * @param {Array<{relPath: string, scope: string}>} budgeted
@@ -88,15 +89,16 @@ export async function measureRef(showFile, ref, budgeted) {
 }
 
 /**
- * Compare the outgoing tree against the two push-input baselines and return the
+ * Compare the outgoing tree against the two push-input baselines. Return the
  * per-file/per-predicate refusal delta. For each (file, rule) the baseline is
- * the worse (higher) of the session-base and origin-tip values, treating an
- * absent measurement as 0. A predicate refuses iff the outgoing value is over
- * cap AND strictly exceeds that baseline — so equal-or-better states pass, and
- * a foreign breach the writer did not worsen passes. A `summary.*` breach on a
- * file listed in `exemptSummaryFiles` is surfaced instead of refused — the
- * memo-delivery seam, where blocking a delivery into deficient headroom would
- * enforce a contradiction the memo-headroom measures exist to resolve.
+ * the worse (higher) of the session-base and origin-tip values. An absent
+ * measurement counts as 0. A predicate refuses iff the outgoing value is over
+ * cap AND strictly exceeds that baseline. So equal-or-better states pass, and
+ * a foreign breach the writer did not worsen passes. The gate surfaces a
+ * `summary.*` breach on a file listed in `exemptSummaryFiles` instead of
+ * refusing it. Those files are the memo-delivery seam. A block on a delivery
+ * into deficient headroom would enforce a contradiction. The memo-headroom
+ * measures exist to resolve that contradiction.
  *
  * @param {object} args
  * @param {Map<string, Map<string, {value: number, overCap: boolean}>>} args.outgoing
@@ -137,14 +139,14 @@ export function revalidateBudgets({
 }
 
 /**
- * Run the gate end to end over the outgoing tree. Builds the audit context,
- * enumerates the budgeted files, measures the committed `HEAD` (what publishes)
- * and the two push-input baselines through the one `measureRef` path, then
- * computes the per-file/per-predicate delta. An unreadable baseline ref makes
- * `showFile` throw, which aborts the gate WITHOUT refusing — the gate only
- * refuses a regression it can prove, so a read failure surfaces (the push
- * proceeds) rather than fabricating a value-0 baseline that would wrongly block
- * a foreign pre-existing breach.
+ * Run the gate end to end over the outgoing tree. Build the audit context.
+ * Enumerate the budgeted files. Measure the committed `HEAD` (what publishes)
+ * and the two push-input baselines through the one `measureRef` path. Then
+ * compute the per-file/per-predicate delta. An unreadable baseline ref makes
+ * `showFile` throw, which aborts the gate WITHOUT refusing. The gate only
+ * refuses a regression it can prove. So a read failure surfaces and the push
+ * proceeds. The gate does not fabricate a value-0 baseline that would wrongly
+ * block a foreign pre-existing breach.
  *
  * @param {object} args
  * @param {(ref: string, file: string) => Promise<string|null>} args.showFile
@@ -181,7 +183,8 @@ export async function runBudgetGate({
     }
     originTip = await measureRef(showFile, originRef, budgeted);
   } catch {
-    // Cannot prove a regression (unreadable ref) ⇒ do not refuse; fail-visible.
+    // Cannot prove a regression (unreadable ref) ⇒ do not refuse. This is the
+    // fail-visible posture.
     return { refusals: [], surfaced: [] };
   }
   return revalidateBudgets({

package/src/budget.js

@@ -1,9 +1,9 @@
 // Canonical line- and word-counters for the budgeted wiki surfaces. The audit
 // (`audit/scopes.js`) and the rotation primitive's bisecting seal
-// (`weekly-log.js`) both import this one pair so a part the seal calls
-// conforming cannot later be flagged by an audit counting differently.
+// (`weekly-log.js`) both import this one pair. So no audit that counts
+// differently can later flag a part the seal accepts as conforming.
 
-/** Count lines, not counting a trailing newline as an empty final line. */
+/** Count lines. Do not count a trailing newline as an empty final line. */
 export function countLines(text) {
   return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
 }

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",

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;