@forwardimpact/libwiki 0.2.33 → 0.2.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.33",
+  "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/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 -->
+`;
+}