@forwardimpact/libwiki 0.2.11 → 0.2.13

package/bin/fit-wiki.js

@@ -2,303 +2,66 @@
 
 import "@forwardimpact/libpreflight/node22";
 
-import { readFileSync } from "node:fs";
+import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
+import { GitClient } from "@forwardimpact/libutil/git-client";
+import { createScriptConfig } from "@forwardimpact/libconfig";
 import { createCli } from "@forwardimpact/libcli";
+import { WikiSync } from "../src/wiki-sync.js";
+import { resolveProjectRoot, resolveWikiRoot } from "../src/util/wiki-dir.js";
+import { createDefinition } from "../src/cli-definition.js";
 
-import { runMemoCommand } from "../src/commands/memo.js";
-import { runRefreshCommand } from "../src/commands/refresh.js";
-import { runInitCommand } from "../src/commands/init.js";
-import { runPushCommand, runPullCommand } from "../src/commands/sync.js";
-import { runBootCommand } from "../src/commands/boot.js";
-import { runLogCommand } from "../src/commands/log.js";
-import { runClaimCommand, runReleaseCommand } from "../src/commands/claim.js";
-import { runInboxCommand } from "../src/commands/inbox.js";
-import { runRotateCommand } from "../src/commands/rotate.js";
-import { runAuditCommand } from "../src/commands/audit.js";
-import { runFixCommand } from "../src/commands/fix.js";
-
-const { version: VERSION } = JSON.parse(
-  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-);
-
-const wikiRootOpt = {
-  "wiki-root": {
-    type: "string",
-    description: "Override wiki root directory (default: wiki)",
-  },
-};
-
-const agentOpt = {
-  agent: {
-    type: "string",
-    description:
-      "Agent name (falls back to LIBEVAL_AGENT_PROFILE, then staff-engineer)",
-    default: process.env.LIBEVAL_AGENT_PROFILE || "staff-engineer",
-  },
-};
-
-const todayOpt = {
-  today: {
-    type: "string",
-    description: "Override today's ISO date (testing)",
-  },
-};
-
-const definition = {
-  name: "fit-wiki",
-  version: VERSION,
-  description: "Wiki lifecycle management for the Kata agent system",
-  commands: [
-    {
-      name: "boot",
-      description:
-        "Print on-boot digest (priorities, claims, storyboard items) as JSON",
-      options: {
-        ...agentOpt,
-        ...wikiRootOpt,
-        ...todayOpt,
-        format: {
-          type: "string",
-          description: "Output format: json (default) or markdown",
-        },
-      },
-    },
-    {
-      name: "log",
-      description:
-        "Append a decision/note/done entry to the current weekly log",
-      args: "[subcommand]",
-      options: {
-        ...agentOpt,
-        ...wikiRootOpt,
-        ...todayOpt,
-        surveyed: {
-          type: "string",
-          description: "Decision: routing levels surveyed",
-        },
-        chosen: { type: "string", description: "Decision: chosen action" },
-        rationale: { type: "string", description: "Decision: rationale" },
-        alternatives: { type: "string", description: "Decision: alternatives" },
-        field: { type: "string", description: "Note: field heading" },
-        body: { type: "string", description: "Note: field body" },
-      },
-    },
-    {
-      name: "claim",
-      description:
-        "Claim a target in MEMORY.md ## Active Claims (refuses duplicates)",
-      options: {
-        ...agentOpt,
-        ...wikiRootOpt,
-        ...todayOpt,
-        target: {
-          type: "string",
-          description: "What is being claimed (spec id, PR id, etc.)",
-        },
-        branch: { type: "string", description: "Branch carrying the work" },
-        pr: { type: "string", description: "Optional PR id" },
-        "expires-at": {
-          type: "string",
-          description: "Override expiry ISO date (default claim+7d)",
-        },
-      },
-    },
-    {
-      name: "release",
-      description: "Release a claim (or all expired claims with --expired)",
-      options: {
-        ...agentOpt,
-        ...wikiRootOpt,
-        ...todayOpt,
-        target: { type: "string", description: "Target to release" },
-        expired: {
-          type: "boolean",
-          description: "Release every row past expires_at",
-        },
-      },
-    },
-    {
-      name: "inbox",
-      description: "Triage the agent's Message Inbox (list/ack/promote/drop)",
-      args: "[subcommand]",
-      options: {
-        ...agentOpt,
-        ...wikiRootOpt,
-        ...todayOpt,
-        index: {
-          type: "string",
-          description: "Bullet index (0-based) for ack/promote/drop",
-        },
-        owner: {
-          type: "string",
-          description: "Owner field when promoting (default: --agent)",
-        },
-      },
-    },
-    {
-      name: "rotate",
-      description: "Force-rotate the current weekly log to a sealed part",
-      options: {
-        ...agentOpt,
-        ...wikiRootOpt,
-        ...todayOpt,
-      },
-    },
-    {
-      name: "audit",
-      description:
-        "Audit the wiki against the declarative rule catalogue (line and word budgets, headings, decision blocks, storyboards, claims)",
-      options: {
-        ...wikiRootOpt,
-        ...todayOpt,
-        format: {
-          type: "string",
-          description: "Output format: text (default) or json",
-        },
-      },
-    },
-    {
-      name: "fix",
-      description:
-        "Auto-fix wiki audit findings using an AI agent (technical-writer, Haiku)",
-      options: {
-        ...wikiRootOpt,
-        ...todayOpt,
-      },
-    },
-    {
-      name: "memo",
-      description: "Send a cross-team memo into a teammate's Message Inbox",
-      options: {
-        from: {
-          type: "string",
-          description:
-            "Sender agent name (falls back to LIBEVAL_AGENT_PROFILE env var)",
-          default: process.env.LIBEVAL_AGENT_PROFILE,
-        },
-        to: {
-          type: "string",
-          description:
-            'Target agent name, or "all" to broadcast (sender is skipped)',
-        },
-        message: {
-          type: "string",
-          description: "Memo text",
-        },
-        ...wikiRootOpt,
-      },
-    },
-    {
-      name: "refresh",
-      description:
-        "Regenerate XmR and obstacle/experiment marker blocks in a storyboard",
-      args: "[storyboard-path]",
-      options: {
-        format: {
-          type: "string",
-          description: "Output format: (default off) or json",
-        },
-      },
-    },
-    {
-      name: "init",
-      description: "Bootstrap a wiki working tree and scaffold Active Claims",
-      options: {
-        ...wikiRootOpt,
-        "skills-dir": {
-          type: "string",
-          description: "Override skills directory (default: .claude/skills)",
-        },
-      },
-    },
-    {
-      name: "push",
-      description: "Commit and push local wiki changes to the remote",
-      options: { ...wikiRootOpt },
-    },
-    {
-      name: "pull",
-      description: "Pull remote wiki changes into the local working tree",
-      options: { ...wikiRootOpt },
-    },
-  ],
-  globalOptions: {
-    help: { type: "boolean", short: "h", description: "Show this help" },
-    version: { type: "boolean", description: "Show version" },
-    json: {
-      type: "boolean",
-      description: "Render --help output as JSON",
-    },
-  },
-  examples: [
-    "fit-wiki boot --agent staff-engineer",
-    'fit-wiki log decision --agent staff-engineer --surveyed "..." --chosen "..." --rationale "..."',
-    "fit-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
-    "fit-wiki release --agent staff-engineer --target spec-NNNN",
-    "fit-wiki inbox list --agent staff-engineer",
-    "fit-wiki rotate --agent staff-engineer",
-    "fit-wiki audit",
-    "fit-wiki fix",
-    'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
-    "fit-wiki refresh",
-    "fit-wiki init",
-    "fit-wiki push",
-    "fit-wiki pull",
-  ],
-  documentation: [
-    {
-      title: "Operate a Predictable Agent Team",
-      url: "https://www.forwardimpact.team/docs/libraries/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",
-      description:
-        "Send cross-team memos, refresh storyboard charts, and sync the wiki.",
-    },
-  ],
-};
-
-const cli = createCli(definition);
-
-const COMMANDS = {
-  boot: runBootCommand,
-  log: runLogCommand,
-  claim: runClaimCommand,
-  release: runReleaseCommand,
-  inbox: runInboxCommand,
-  rotate: runRotateCommand,
-  audit: runAuditCommand,
-  fix: runFixCommand,
-  memo: runMemoCommand,
-  refresh: runRefreshCommand,
-  init: runInitCommand,
-  push: runPushCommand,
-  pull: runPullCommand,
-};
+// Commands that mutate or sync the remote wiki need a constructed WikiSync
+// (and its config-backed token resolver); the rest run against the local tree.
+const NEEDS_WIKI_SYNC = new Set(["claim", "release", "push", "pull", "init"]);
 
 async function main() {
-  const parsed = cli.parse(process.argv.slice(2));
-  if (!parsed) process.exit(0);
-
-  const { values, positionals } = parsed;
-
+  const runtime = createDefaultRuntime();
+  const { version } = JSON.parse(
+    runtime.fsSync.readFileSync(
+      new URL("../package.json", import.meta.url),
+      "utf8",
+    ),
+  );
+  const definition = createDefinition(runtime.proc.env, version);
+  const cli = createCli(definition, { runtime });
+
+  const parsed = cli.parse(runtime.proc.argv.slice(2));
+  if (!parsed) return runtime.proc.exit(0); // --help / --version already printed
+
+  const { positionals } = parsed;
   if (positionals.length === 0) {
     cli.showHelp();
-    process.exit(0);
+    return runtime.proc.exit(0);
   }
 
-  const [command, ...args] = positionals;
-  const handler = COMMANDS[command];
-
-  if (!handler) {
+  const command = positionals[0];
+  if (!definition.commands.some((c) => c.name === command)) {
     cli.usageError(`unknown command "${command}"`);
-    process.exit(2);
+    return runtime.proc.exit(2);
   }
 
-  await handler(values, args, cli);
+  const gitClient = new GitClient({ runtime });
+  let wikiSync;
+  if (NEEDS_WIKI_SYNC.has(command)) {
+    const projectRoot = resolveProjectRoot(runtime);
+    const wikiDir = resolveWikiRoot(runtime, parsed.values);
+    const config = await createScriptConfig("wiki");
+    wikiSync = new WikiSync({
+      runtime,
+      gitClient,
+      wikiDir,
+      parentDir: projectRoot,
+      resolveToken: () => config.ghToken(),
+    });
+  }
+
+  const result = await cli.dispatch(parsed, {
+    deps: { runtime, wikiSync, gitClient },
+  });
+
+  const envelope = result ?? { ok: true };
+  if (!envelope.ok && envelope.error) cli.usageError(envelope.error);
+  runtime.proc.exit(envelope.ok ? 0 : (envelope.code ?? 1));
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",

package/src/agent-roster.js

@@ -1,12 +1,13 @@
-import { readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { BROADCAST_TARGET } from "./constants.js";
 
-/** List all agent markdown files in the agents directory, returning agent names and summary paths. */
-export function listAgents(
-  { agentsDir, wikiRoot },
-  fs = { readdirSync, statSync },
-) {
+/**
+ * List all agent markdown files in the agents directory, returning agent names
+ * and summary paths.
+ * @param {{agentsDir: string, wikiRoot: string}} dirs
+ * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
+ */
+export function listAgents({ agentsDir, wikiRoot }, fs) {
   const entries = fs.readdirSync(agentsDir);
   const agents = [];
 

package/src/audit/rules.js

@@ -12,6 +12,7 @@ import {
   WEEKLY_LOG_WORD_BUDGET,
 } from "../constants.js";
 import { PRIORITY_HEADER_RE, WEEKLY_LOG_H1_RE } from "./scopes.js";
+import { STATUS_ROW_RULES } from "./status-row.js";
 
 const PRIORITY_INDEX_HEADING_RE = new RegExp(
   `^${PRIORITY_INDEX_HEADING}$`,
@@ -483,6 +484,10 @@ export const RULES = [
     hint: "every '<!-- obstacles:* -->' or '<!-- experiments:* -->' needs a matching close marker",
   },
 
+  // -- STATUS.md rows (per-migration-unit sub-row schema) --
+
+  ...STATUS_ROW_RULES,
+
   // -- Stray files --
 
   {

package/src/audit/scopes.js

@@ -1,5 +1,5 @@
-import { readFileSync, existsSync, readdirSync } from "node:fs";
 import path from "node:path";
+import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims } from "../active-claims.js";
 import { PRIORITY_INDEX_HEADING } from "../constants.js";
 
@@ -11,7 +11,7 @@ export const WEEKLY_LOG_H1_RE =
 export const PRIORITY_HEADER_RE =
   /^\|\s*Item\s*\|\s*Agents\s*\|\s*Owner\s*\|\s*Status\s*\|\s*Added\s*\|/m;
 
-const EXCLUDED_BASES = new Set(["MEMORY.md", "Home.md", "STATUS.md"]);
+const EXCLUDED_BASES = new Set(["MEMORY.md", "Home.md"]);
 const NON_SUMMARY_PREFIXES = [
   "storyboard-",
   "downstream-",
@@ -20,9 +20,10 @@ const NON_SUMMARY_PREFIXES = [
   "fit-trace-",
 ];
 
-function listMdFiles(wikiRoot) {
-  if (!existsSync(wikiRoot)) return [];
-  return readdirSync(wikiRoot)
+function listMdFiles(wikiRoot, fs) {
+  if (!fs.existsSync(wikiRoot)) return [];
+  return fs
+    .readdirSync(wikiRoot)
     .filter((e) => e.endsWith(".md"))
     .map((e) => path.join(wikiRoot, e));
 }
@@ -46,8 +47,8 @@ function countWords(text) {
   return count;
 }
 
-function loadFile(filePath) {
-  const text = readFileSync(filePath, "utf-8");
+function loadFile(filePath, fs) {
+  const text = fs.readFileSync(filePath, "utf-8");
   const fileLines = text.split("\n");
   const h2s = [];
   for (const line of fileLines) {
@@ -69,44 +70,86 @@ function loadFile(filePath) {
   };
 }
 
-function classifyFile(filePath) {
+function classifyFile(filePath, fs) {
   const base = path.basename(filePath);
   if (EXCLUDED_BASES.has(base)) return null;
+  // STATUS.md is loaded separately (loadStatus) and audited via the dedicated
+  // `status-row` scope — skip the per-file classification so it is not treated
+  // as a stray file.
+  if (base === "STATUS.md") return null;
   if (NON_SUMMARY_PREFIXES.some((p) => base.startsWith(p))) return null;
   if (WEEKLY_LOG_NAME_RE.test(base)) {
-    return { kind: "weekly-log-main", subject: loadFile(filePath) };
+    return { kind: "weekly-log-main", subject: loadFile(filePath, fs) };
   }
   if (WEEKLY_LOG_PART_NAME_RE.test(base)) {
-    return { kind: "weekly-log-part", subject: loadFile(filePath) };
+    return { kind: "weekly-log-part", subject: loadFile(filePath, fs) };
   }
-  const subject = loadFile(filePath);
+  const subject = loadFile(filePath, fs);
   const kind = SUMMARY_H1_RE.test(subject.firstLine) ? "summary" : "stray";
   return { kind, subject };
 }
 
-function loadMemory(wikiRoot) {
+function loadMemory(wikiRoot, fs) {
   const filePath = path.join(wikiRoot, "MEMORY.md");
-  const exists = existsSync(filePath);
+  const exists = fs.existsSync(filePath);
   return {
     path: filePath,
-    text: exists ? readFileSync(filePath, "utf-8") : "",
+    text: exists ? fs.readFileSync(filePath, "utf-8") : "",
     exists,
   };
 }
 
-function loadStoryboard(wikiRoot, today) {
-  const date = new Date(today);
-  const yyyy = date.getUTCFullYear();
-  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
-  const filePath = path.join(wikiRoot, `storyboard-${yyyy}-M${mm}.md`);
-  const exists = existsSync(filePath);
-  const text = exists ? readFileSync(filePath, "utf-8") : "";
+function loadStatus(wikiRoot, fs) {
+  const filePath = path.join(wikiRoot, "STATUS.md");
+  const exists = fs.existsSync(filePath);
+  return {
+    path: filePath,
+    text: exists ? fs.readFileSync(filePath, "utf-8") : "",
+    exists,
+  };
+}
+
+/**
+ * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
+ * outside the ``` fence (header prose) and blank lines are skipped.
+ * @param {string} statusText - The full STATUS.md contents.
+ * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string}>}
+ */
+function parseStatusRows(statusText) {
+  const lines = statusText.split("\n");
+  const rows = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trimStart().startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence || line.trim() === "") continue;
+    const cells = line.split("\t");
+    rows.push({
+      lineNo: i + 1,
+      text: line,
+      cells,
+      id: cells[0],
+      phase: cells[1],
+      status: cells[2],
+    });
+  }
+  return rows;
+}
+
+function loadStoryboard(wikiRoot, today, fs) {
+  const ym = yearMonth(today);
+  const filePath = path.join(wikiRoot, `storyboard-${ym}.md`);
+  const exists = fs.existsSync(filePath);
+  const text = exists ? fs.readFileSync(filePath, "utf-8") : "";
   return {
     path: filePath,
     text,
     fileLines: text.split("\n"),
     exists,
-    yearMonth: `${yyyy}-M${mm}`,
+    yearMonth: ym,
     lines: countLines(text),
     words: countWords(text),
   };
@@ -168,6 +211,11 @@ const SCOPE_RESOLVERS = {
       path: ctx.memory.path,
     })),
   storyboard: (ctx) => [ctx.storyboard],
+  "status-row": (ctx) =>
+    parseStatusRows(ctx.status.text).map((r) => ({
+      ...r,
+      path: ctx.status.path,
+    })),
   "stray-file": (ctx) => ctx.subjects.stray,
 };
 
@@ -178,23 +226,28 @@ export function resolveScope(scopeKey, ctx) {
   return resolver(ctx);
 }
 
-/** Build the audit context: classifies and loads every wiki file once. */
-export function buildContext({ wikiRoot, today }) {
+/**
+ * Build the audit context: classifies and loads every wiki file once.
+ * @param {{wikiRoot: string, today: string, fs: object}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`).
+ */
+export function buildContext({ wikiRoot, today, fs }) {
   const subjects = {
     summary: [],
     "weekly-log-main": [],
     "weekly-log-part": [],
     stray: [],
   };
-  for (const file of listMdFiles(wikiRoot)) {
-    const classified = classifyFile(file);
+  for (const file of listMdFiles(wikiRoot, fs)) {
+    const classified = classifyFile(file, fs);
     if (classified) subjects[classified.kind].push(classified.subject);
   }
   return {
     wikiRoot,
     today,
     subjects,
-    memory: loadMemory(wikiRoot),
-    storyboard: loadStoryboard(wikiRoot, today),
+    memory: loadMemory(wikiRoot, fs),
+    status: loadStatus(wikiRoot, fs),
+    storyboard: loadStoryboard(wikiRoot, today, fs),
   };
 }

package/src/audit/status-row.js

@@ -0,0 +1,51 @@
+import { STATUS_ID_REGEX } from "../status.js";
+
+// Validate every row inside wiki/STATUS.md's code fence against the
+// `{id}<TAB>{phase}<TAB>{status}` shape. Rows are resolved by the `status-row`
+// scope in scopes.js; each subject carries `{ cells, id, phase, status, text }`.
+
+const PHASES = new Set(["spec", "design", "plan"]);
+const STATUSES = new Set(["draft", "approved", "implemented", "cancelled"]);
+
+const hasThreeCells = (s) => s.cells.length === 3;
+
+export const STATUS_ROW_RULES = [
+  {
+    id: "status-row.shape",
+    scope: "status-row",
+    severity: "fail",
+    check: (s) =>
+      hasThreeCells(s) ? null : { actual: s.cells.length, text: s.text },
+    message: (_s, r) =>
+      `${r.actual} tab-separated field(s), expected 3: "${r.text}"`,
+    hint: "each STATUS row is `{id}<TAB>{phase}<TAB>{status}`",
+  },
+  {
+    id: "status-row.id-format",
+    scope: "status-row",
+    severity: "fail",
+    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)",
+  },
+  {
+    id: "status-row.phase",
+    scope: "status-row",
+    severity: "fail",
+    when: hasThreeCells,
+    check: (s) => (PHASES.has(s.phase) ? null : { phase: s.phase }),
+    message: (_s, r) => `Bad phase '${r.phase}' (expected spec|design|plan)`,
+    hint: "phase is one of spec, design, plan",
+  },
+  {
+    id: "status-row.status",
+    scope: "status-row",
+    severity: "fail",
+    when: hasThreeCells,
+    check: (s) => (STATUSES.has(s.status) ? null : { status: s.status }),
+    message: (_s, r) =>
+      `Bad status '${r.status}' (expected draft|approved|implemented|cancelled)`,
+    hint: "status is one of draft, approved, implemented, cancelled",
+  },
+];

package/src/block-renderer.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import path from "node:path";
 import { analyze, renderChart, MIN_POINTS } from "@forwardimpact/libxmr";
 
@@ -11,13 +10,13 @@ export class BlockRenderError extends Error {
   }
 }
 
-/** Render an XmR chart block for a metric by reading its CSV and producing markdown lines. */
-export function renderBlock({
-  metric,
-  csvPath,
-  projectRoot,
-  fs = { readFileSync },
-}) {
+/**
+ * Render an XmR chart block for a metric by reading its CSV and producing
+ * markdown lines.
+ * @param {{metric: string, csvPath: string, projectRoot: string, fs: object}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`).
+ */
+export function renderBlock({ metric, csvPath, projectRoot, fs }) {
   const fullPath = path.resolve(projectRoot, csvPath);
   let csvText;
   try {