@forwardimpact/libwiki 0.2.32 → 0.2.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "description": "Wiki lifecycle for agent teams — persistent memory, declarative integrity audits, and a collision ledger so coordination survives across sessions and parallel work.",
   "keywords": [
     "wiki",

package/src/commands/curate.js

@@ -16,24 +16,62 @@ const LABEL = {
 };
 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`.
+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.
  * @param {string} findingsJson
+ * @param {{shown?: number, total?: number}} [trunc]
  * @returns {string}
  */
-function buildBody(findingsJson) {
-  return [
+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).",
     "",
-    "```json",
-    findingsJson,
-    "```",
-    "",
-  ].join("\n");
+  ];
+  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.`,
+      "",
+    );
+  }
+  lines.push("```json", findingsJson, "```", "");
+  return lines.join("\n");
+}
+
+/**
+ * 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.
+ * @param {{level: string}[]} findings
+ * @returns {string}
+ */
+function fitBody(findings) {
+  const total = findings.filter((f) => f.level === "fail").length;
+  const full = buildBody(emitFindingsJson(findings), { shown: total, total });
+  if (full.length <= MAX_BODY) return full;
+
+  const failures = findings.filter((f) => f.level === "fail");
+  let shown = failures.length;
+  while (shown > 0) {
+    const body = buildBody(emitFindingsJson(failures.slice(0, shown)), {
+      shown,
+      total,
+    });
+    if (body.length <= MAX_BODY) return body;
+    const next = Math.floor((shown * MAX_BODY) / body.length);
+    shown = next < shown ? next : shown - 1;
+  }
+  return buildBody(emitFindingsJson([]), { shown: 0, total });
 }
 
 // Resolve the monorepo's `owner/repo` slug the way refresh.js/product-mix.js
@@ -60,35 +98,49 @@ async function resolveToken() {
 }
 
 /**
- * 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.
- *
+ * 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).
+ * @param {import("@forwardimpact/libcli").InvocationContext["deps"]["runtime"]} runtime
+ * @param {string[]} repoArgs
+ * @param {{cwd: string, env: object}} opts
+ * @returns {Promise<number|null>}
+ */
+async function findOpenIssue(runtime, repoArgs, opts) {
+  const list = await runtime.subprocess.run(
+    "gh",
+    [
+      "issue",
+      "list",
+      "--search",
+      `${TITLE} in:title`,
+      "--state",
+      "open",
+      "--json",
+      "number",
+      ...repoArgs,
+    ],
+    opts,
+  );
+  try {
+    return JSON.parse(list.stdout || "[]")[0]?.number ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @param {string} body
+ * @param {ReturnType<typeof createLogger>} logger
  * @returns {Promise<{ok: boolean}>}
  */
-export async function runCurateCommand(ctx) {
+async function routeFindings(ctx, body, logger) {
   const { runtime, gitClient } = ctx.deps;
-  const logger = createLogger("wiki", runtime);
-  const { findings } = auditWiki(ctx);
-
-  if (!findings.some((f) => f.level === "fail")) {
-    runtime.proc.stdout.write("wiki audit clean — no curation issue routed\n");
-    return { ok: true };
-  }
-
-  const body = buildBody(emitFindingsJson(findings));
-
-  if (ctx.options["dry-run"]) {
-    runtime.proc.stdout.write(
-      `[dry-run] would route findings to issue "${TITLE}":\n\n${body}`,
-    );
-    return { ok: true };
-  }
-
   const cwd = resolveProjectRoot(runtime);
   const repo =
     ctx.options.repo || (await deriveRepo(gitClient, cwd, runtime.proc.env));
@@ -115,27 +167,7 @@ export async function runCurateCommand(ctx) {
     { cwd, env },
   );
 
-  const list = await runtime.subprocess.run(
-    "gh",
-    [
-      "issue",
-      "list",
-      "--search",
-      `${TITLE} in:title`,
-      "--state",
-      "open",
-      "--json",
-      "number",
-      ...repoArgs,
-    ],
-    { cwd, env },
-  );
-  let number = null;
-  try {
-    number = JSON.parse(list.stdout || "[]")[0]?.number ?? null;
-  } catch {
-    number = null;
-  }
+  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.
@@ -143,37 +175,28 @@ export async function runCurateCommand(ctx) {
   const bodyFile = path.join(tmp, "wiki-curation-body.md");
   runtime.fsSync.writeFileSync(bodyFile, body);
 
-  const result = number
-    ? await runtime.subprocess.run(
-        "gh",
-        [
-          "issue",
-          "comment",
-          String(number),
-          "--body-file",
-          bodyFile,
-          ...repoArgs,
-        ],
-        { cwd, env },
-      )
-    : await runtime.subprocess.run(
-        "gh",
-        [
-          "issue",
-          "create",
-          "--title",
-          TITLE,
-          "--body-file",
-          bodyFile,
-          "--label",
-          LABEL.name,
-          ...repoArgs,
-        ],
-        { cwd, env },
-      );
+  const args = number
+    ? ["issue", "comment", String(number), "--body-file", bodyFile, ...repoArgs]
+    : [
+        "issue",
+        "create",
+        "--title",
+        TITLE,
+        "--body-file",
+        bodyFile,
+        "--label",
+        LABEL.name,
+        ...repoArgs,
+      ];
+  const result = await runtime.subprocess.run("gh", args, { cwd, env });
 
   if (result.exitCode !== 0) {
-    logger.warn("curate", `gh issue ${number ? "comment" : "create"} failed`);
+    const detail = (result.stderr || result.stdout || "").trim();
+    const action = number ? "comment" : "create";
+    logger.warn(
+      "curate",
+      `gh issue ${action} failed${detail ? `: ${detail}` : ""}`,
+    );
     return { ok: false };
   }
   runtime.proc.stdout.write(
@@ -183,3 +206,36 @@ export async function runCurateCommand(ctx) {
   );
   return { ok: true };
 }
+
+/**
+ * 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.
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean}>}
+ */
+export async function runCurateCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const logger = createLogger("wiki", runtime);
+  const { findings } = auditWiki(ctx);
+
+  if (!findings.some((f) => f.level === "fail")) {
+    runtime.proc.stdout.write("wiki audit clean — no curation issue routed\n");
+    return { ok: true };
+  }
+
+  const body = fitBody(findings);
+
+  if (ctx.options["dry-run"]) {
+    runtime.proc.stdout.write(
+      `[dry-run] would route findings to issue "${TITLE}":\n\n${body}`,
+    );
+    return { ok: true };
+  }
+
+  return routeFindings(ctx, body, logger);
+}

package/src/commands/refresh.js

@@ -11,6 +11,7 @@ import {
   parseRepoSlug,
 } from "../issue-list-renderer.js";
 import { parseClaims, filterExpired, removeClaim } from "../active-claims.js";
+import { renderStoryboardSkeleton } from "../storyboard-skeleton.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot, resolveWikiRoot } from "../util/wiki-dir.js";
 
@@ -90,9 +91,8 @@ function spliceBlock(lines, block, rendered) {
   );
 }
 
-// A missing current-month storyboard (e.g. a coaching run early in the month,
-// before the storyboard meeting created it) is non-fatal: return null so the
-// deterministic refresh step exits cleanly instead of failing the job.
+// A missing current-month storyboard is non-fatal: return null so the caller
+// can create it (see createStoryboardSkeleton) rather than fail the job.
 function readStoryboardOrNull(runtime, storyboardPath) {
   try {
     return runtime.fsSync.readFileSync(storyboardPath, "utf-8");
@@ -102,6 +102,20 @@ function readStoryboardOrNull(runtime, storyboardPath) {
   }
 }
 
+// Create the current-month storyboard from the minimal skeleton when it does
+// not exist. Refresh is the deterministic "freshen the wiki" step and runs
+// before the session (kata-agent pre-run), so creating here guarantees the file
+// is on disk before participants look for it — without any lead having a write
+// tool. The skeleton carries the section structure and the generic issue-list
+// markers; the render pass below fills them and participants seed metric blocks.
+function createStoryboardSkeleton(runtime, storyboardPath, logger) {
+  const skeleton = renderStoryboardSkeleton(currentDayIso(runtime));
+  runtime.fsSync.mkdirSync(path.dirname(storyboardPath), { recursive: true });
+  runtime.fsSync.writeFileSync(storyboardPath, skeleton);
+  logger.info("refresh", `created storyboard at ${storyboardPath}`);
+  return skeleton;
+}
+
 // Drop every MEMORY.md `## Active Claims` row past its `expires_at`, writing the
 // trimmed table back in place. Refresh is the deterministic "freshen the wiki"
 // step, so clearing lapsed claims belongs here alongside the storyboard render;
@@ -142,11 +156,11 @@ export async function runRefreshCommand(ctx) {
     projectRoot,
     ctx.args["storyboard-path"] || currentStoryboardRelPath(runtime),
   );
-  const text = readStoryboardOrNull(runtime, storyboardPath);
-  if (text === null) {
-    logger.warn("refresh", `no storyboard at ${storyboardPath}`);
-    return { ok: true };
-  }
+  const existing = readStoryboardOrNull(runtime, storyboardPath);
+  const created = existing === null;
+  const text = created
+    ? createStoryboardSkeleton(runtime, storyboardPath, logger)
+    : existing;
   const blocks = scanMarkers(text, {
     warn: (message) => logger.warn("refresh", message),
   });
@@ -200,7 +214,7 @@ export async function runRefreshCommand(ctx) {
   if (spliced) runtime.fsSync.writeFileSync(storyboardPath, lines.join("\n"));
   if (options.format === "json") {
     runtime.proc.stdout.write(
-      JSON.stringify({ blocks: blocks.length, spliced }) + "\n",
+      JSON.stringify({ blocks: blocks.length, spliced, created }) + "\n",
     );
   }
   return { ok: true };

package/src/storyboard-skeleton.js

@@ -0,0 +1,106 @@
+/**
+ * Storyboard skeleton — the minimal, valid storyboard file `fit-wiki refresh`
+ * writes when the current-month board does not yet exist. It carries only the
+ * structural surface libwiki owns: the five Toyota Kata sections and the
+ * generic `obstacles`/`experiments` issue-list marker blocks that refresh
+ * renders from tracker state.
+ *
+ * Deliberately *not* here: the per-agent `#### {metric}` XmR blocks. Their
+ * agent→metric grouping is per-installation curation libwiki cannot infer, so a
+ * participant seeds each missing marker pair (see the kata-session skill) and a
+ * later refresh renders it. Section budgets and authoring prose ("write the
+ * challenge here") stay in the skill's `storyboard-template.md`, the L4
+ * authoring layer — this skeleton is content-free scaffolding.
+ */
+
+const MONTH_NAMES = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+/** Whether `year` is a leap year under the Gregorian rule. */
+function isLeapYear(year) {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+/**
+ * Last calendar day of the month containing `todayIso` (ISO `YYYY-MM-DD`).
+ * Pure integer/calendar math — no `Date`, so the module stays free of ambient
+ * time deps.
+ */
+function endOfMonthIso(todayIso) {
+  const [year, month] = todayIso.split("-").map(Number);
+  const lastDay =
+    month === 2 && isLeapYear(year) ? 29 : DAYS_IN_MONTH[month - 1];
+  return `${year}-${String(month).padStart(2, "0")}-${String(lastDay).padStart(2, "0")}`;
+}
+
+/**
+ * Render the minimal storyboard skeleton for the month containing `todayIso`.
+ * Pure — takes the day as an ISO string and returns markdown. The heading reads
+ * `# Storyboard — {YYYY} {Month}`; the marker blocks match the syntax the
+ * scanner (`marker-scanner.js`) and renderer (`commands/refresh.js`) expect.
+ *
+ * @param {string} todayIso - ISO date string (`YYYY-MM-DD`).
+ * @returns {string} The skeleton markdown, newline-terminated.
+ */
+export function renderStoryboardSkeleton(todayIso) {
+  const [year, month] = todayIso.split("-").map(Number);
+  const monthName = MONTH_NAMES[month - 1];
+  return `# Storyboard — ${year} ${monthName}
+
+## Challenge
+
+> [product-manager sets this in the planning meeting.]
+
+## Target Condition
+
+**Due:** ${endOfMonthIso(todayIso)}
+
+> [product-manager sets this in the planning meeting.]
+
+## Current Condition
+
+**Last updated:** ${todayIso}
+
+### Headlines
+
+None.
+
+## Obstacles
+
+### Active
+
+<!-- obstacles:open Do not edit. Auto-generated. -->
+<!-- /obstacles -->
+
+### Concluded (last 7 days)
+
+<!-- obstacles:closed Do not edit. Auto-generated. -->
+<!-- /obstacles -->
+
+## Experiments
+
+### Active
+
+<!-- experiments:open Do not edit. Auto-generated. -->
+<!-- /experiments -->
+
+### Concluded (last 7 days)
+
+<!-- experiments:closed Do not edit. Auto-generated. -->
+<!-- /experiments -->
+`;
+}