@forwardimpact/libwiki 0.1.3 → 0.2.0

package/bin/fit-wiki.js

@@ -7,16 +7,156 @@ 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";
 
 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 env var)",
+  },
+};
+
+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 memory-protocol contract (500-line cap; cutover 2026-W23)",
+      options: {
+        ...wikiRootOpt,
+        ...todayOpt,
+        format: {
+          type: "string",
+          description: "Output format: text (default) or json",
+        },
+        "legacy-only": {
+          type: "boolean",
+          description:
+            "Run only the checks the legacy wiki-audit.sh carried (parity mode)",
+        },
+      },
+    },
     {
       name: "memo",
       description: "Send a cross-team memo into a teammate's Message Inbox",
@@ -35,26 +175,27 @@ const definition = {
           type: "string",
           description: "Memo text",
         },
-        "wiki-root": {
-          type: "string",
-          description: "Override wiki root directory (default: auto-detected)",
-        },
+        ...wikiRootOpt,
       },
     },
     {
       name: "refresh",
       description:
-        "Regenerate XmR chart blocks inside a storyboard markdown file",
+        "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 for a Kata installation",
+      description:
+        "Bootstrap a wiki working tree, scaffold Active Claims, install audit Stop-hook",
       options: {
-        "wiki-root": {
-          type: "string",
-          description: "Override wiki root directory (default: wiki)",
-        },
+        ...wikiRootOpt,
         "skills-dir": {
           type: "string",
           description: "Override skills directory (default: .claude/skills)",
@@ -64,22 +205,12 @@ const definition = {
     {
       name: "push",
       description: "Commit and push local wiki changes to the remote",
-      options: {
-        "wiki-root": {
-          type: "string",
-          description: "Override wiki root directory (default: wiki)",
-        },
-      },
+      options: { ...wikiRootOpt },
     },
     {
       name: "pull",
       description: "Pull remote wiki changes into the local working tree",
-      options: {
-        "wiki-root": {
-          type: "string",
-          description: "Override wiki root directory (default: wiki)",
-        },
-      },
+      options: { ...wikiRootOpt },
     },
   ],
   globalOptions: {
@@ -91,10 +222,15 @@ const definition = {
     },
   },
   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-1060 --branch claude/...",
+    "fit-wiki release --agent staff-engineer --target spec-1060",
+    "fit-wiki inbox list --agent staff-engineer",
+    "fit-wiki rotate --agent staff-engineer",
+    "fit-wiki audit",
     'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
-    'fit-wiki memo --from technical-writer --to all --message "new XmR baseline"',
     "fit-wiki refresh",
-    "fit-wiki refresh wiki/storyboard-2026-M05.md",
     "fit-wiki init",
     "fit-wiki push",
     "fit-wiki pull",
@@ -118,6 +254,13 @@ const definition = {
 const cli = createCli(definition);
 
 const COMMANDS = {
+  boot: runBootCommand,
+  log: runLogCommand,
+  claim: runClaimCommand,
+  release: runReleaseCommand,
+  inbox: runInboxCommand,
+  rotate: runRotateCommand,
+  audit: runAuditCommand,
   memo: runMemoCommand,
   refresh: runRefreshCommand,
   init: runInitCommand,
@@ -125,7 +268,7 @@ const COMMANDS = {
   pull: runPullCommand,
 };
 
-function main() {
+async function main() {
   const parsed = cli.parse(process.argv.slice(2));
   if (!parsed) process.exit(0);
 
@@ -144,7 +287,7 @@ function main() {
     process.exit(2);
   }
 
-  handler(values, args, cli);
+  await handler(values, args, cli);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
+    "@forwardimpact/libconfig": "^0.1.77",
     "@forwardimpact/libutil": "^0.1.0",
     "@forwardimpact/libxmr": "^1.1.0"
   },

package/src/active-claims.js

@@ -0,0 +1,196 @@
+import {
+  ACTIVE_CLAIMS_HEADING,
+  ACTIVE_CLAIMS_TABLE_HEADER,
+  ACTIVE_CLAIMS_TABLE_SEPARATOR,
+} from "./constants.js";
+
+const HEADER_RE =
+  /^\|\s*agent\s*\|\s*target\s*\|\s*branch\s*\|\s*pr\s*\|\s*claimed_at\s*\|\s*expires_at\s*\|\s*$/;
+const SEPARATOR_RE = /^\|\s*---\s*\|/;
+const ROW_RE =
+  /^\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*([^|]*?)\s*\|\s*$/;
+
+function findSection(lines) {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === ACTIVE_CLAIMS_HEADING) return i;
+  }
+  return -1;
+}
+
+function findNextH2(lines, start) {
+  for (let i = start; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) return i;
+  }
+  return lines.length;
+}
+
+function isEmptyStateCell(cell) {
+  return cell === "*None*" || cell === "—";
+}
+
+function rowFromMatch(match) {
+  const [, agent, target, branch, pr, claimed_at, expires_at] = match;
+  if (isEmptyStateCell(agent.trim())) return null;
+  return {
+    agent: agent.trim(),
+    target: target.trim(),
+    branch: branch.trim(),
+    pr: pr.trim() === "—" || pr.trim() === "" ? null : pr.trim(),
+    claimed_at: claimed_at.trim(),
+    expires_at: expires_at.trim(),
+  };
+}
+
+function scanRowsBetween(lines, start, end) {
+  const claims = [];
+  let inTable = false;
+  let seenSeparator = false;
+  for (let i = start; i < end; i++) {
+    const line = lines[i];
+    if (HEADER_RE.test(line)) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && SEPARATOR_RE.test(line)) {
+      seenSeparator = true;
+      continue;
+    }
+    if (!(inTable && seenSeparator && line.startsWith("|"))) continue;
+    const match = line.match(ROW_RE);
+    if (!match) continue;
+    const row = rowFromMatch(match);
+    if (row) claims.push(row);
+  }
+  return claims;
+}
+
+/** Parse the `## Active Claims` table from MEMORY.md text. Returns [] if absent. */
+export function parseClaims(memoryText) {
+  if (typeof memoryText !== "string") return [];
+  const lines = memoryText.split("\n");
+  const heading = findSection(lines);
+  if (heading === -1) return [];
+  const sectionEnd = findNextH2(lines, heading + 1);
+  return scanRowsBetween(lines, heading + 1, sectionEnd);
+}
+
+function formatRow({ agent, target, branch, pr, claimed_at, expires_at }) {
+  const prCell = pr == null || pr === "" ? "—" : pr;
+  return `| ${agent} | ${target} | ${branch} | ${prCell} | ${claimed_at} | ${expires_at} |`;
+}
+
+function appendNewSection(memoryText, claim) {
+  const block = [
+    "",
+    ACTIVE_CLAIMS_HEADING,
+    "",
+    ACTIVE_CLAIMS_TABLE_HEADER,
+    ACTIVE_CLAIMS_TABLE_SEPARATOR,
+    formatRow(claim),
+    "",
+  ];
+  return memoryText.replace(/\n*$/, "") + "\n" + block.join("\n");
+}
+
+function findTableIndices(lines, heading, sectionEnd) {
+  let headerIdx = -1;
+  let separatorIdx = -1;
+  for (let i = heading + 1; i < sectionEnd; i++) {
+    if (HEADER_RE.test(lines[i])) headerIdx = i;
+    if (headerIdx !== -1 && SEPARATOR_RE.test(lines[i])) {
+      separatorIdx = i;
+      break;
+    }
+  }
+  return { headerIdx, separatorIdx };
+}
+
+function insertTableWithRow(lines, heading, sectionEnd, claim) {
+  let insertAt = heading + 1;
+  while (insertAt < sectionEnd && lines[insertAt].trim() === "") insertAt++;
+  while (insertAt < sectionEnd && lines[insertAt].trim() !== "") insertAt++;
+  const toInsert = [
+    "",
+    ACTIVE_CLAIMS_TABLE_HEADER,
+    ACTIVE_CLAIMS_TABLE_SEPARATOR,
+    formatRow(claim),
+  ];
+  lines.splice(insertAt, 0, ...toInsert);
+  return lines.join("\n");
+}
+
+function appendRowAfterTable(lines, sectionEnd, separatorIdx, claim) {
+  let lastRowIdx = separatorIdx;
+  for (let i = separatorIdx + 1; i < sectionEnd; i++) {
+    if (!lines[i].startsWith("|")) break;
+    lastRowIdx = i;
+  }
+  if (lastRowIdx > separatorIdx) {
+    const match = lines[lastRowIdx].match(ROW_RE);
+    if (match && isEmptyStateCell(match[1].trim())) {
+      lines[lastRowIdx] = formatRow(claim);
+      return lines.join("\n");
+    }
+  }
+  lines.splice(lastRowIdx + 1, 0, formatRow(claim));
+  return lines.join("\n");
+}
+
+/** Append a claim row to MEMORY.md text. Refuses if (agent, target) already present. */
+export function appendClaim(memoryText, claim, _today) {
+  const existing = parseClaims(memoryText);
+  if (
+    existing.some((c) => c.agent === claim.agent && c.target === claim.target)
+  ) {
+    return { text: memoryText, inserted: false, reason: "duplicate" };
+  }
+  const lines = memoryText.split("\n");
+  const heading = findSection(lines);
+  if (heading === -1) {
+    return { text: appendNewSection(memoryText, claim), inserted: true };
+  }
+  const sectionEnd = findNextH2(lines, heading + 1);
+  const { headerIdx, separatorIdx } = findTableIndices(
+    lines,
+    heading,
+    sectionEnd,
+  );
+  if (headerIdx === -1 || separatorIdx === -1) {
+    return {
+      text: insertTableWithRow(lines, heading, sectionEnd, claim),
+      inserted: true,
+    };
+  }
+  return {
+    text: appendRowAfterTable(lines, sectionEnd, separatorIdx, claim),
+    inserted: true,
+  };
+}
+
+/** Remove the claim row matching (agent, target). Idempotent. */
+export function removeClaim(memoryText, { agent, target }) {
+  const lines = memoryText.split("\n");
+  const heading = findSection(lines);
+  if (heading === -1) return { text: memoryText, removed: false };
+  const sectionEnd = findNextH2(lines, heading + 1);
+  for (let i = heading + 1; i < sectionEnd; i++) {
+    const match = lines[i].match(ROW_RE);
+    if (!match) continue;
+    if (match[1].trim() === agent && match[2].trim() === target) {
+      lines.splice(i, 1);
+      return { text: lines.join("\n"), removed: true };
+    }
+  }
+  return { text: memoryText, removed: false };
+}
+
+/** Split claims into active vs expired based on `expires_at >= today`. */
+export function filterExpired(claims, today) {
+  const active = [];
+  const expired = [];
+  for (const c of claims) {
+    if (!c.expires_at || c.expires_at >= today) active.push(c);
+    else expired.push(c);
+  }
+  return { active, expired };
+}

package/src/boot.js

@@ -0,0 +1,179 @@
+import { readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { parseClaims, filterExpired } from "./active-claims.js";
+import { MEMO_INBOX_MARKER, PRIORITY_INDEX_HEADING } from "./constants.js";
+
+function readIfExists(filePath) {
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, "utf-8");
+}
+
+function currentStoryboardPath(wikiRoot, date) {
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  return path.join(wikiRoot, `storyboard-${yyyy}-M${mm}.md`);
+}
+
+function extractSummary(text) {
+  if (!text) return "";
+  const lines = text.split("\n");
+  let i = 0;
+  while (i < lines.length && lines[i].startsWith("#")) i++;
+  while (i < lines.length && lines[i].trim() === "") i++;
+  const paragraph = [];
+  while (i < lines.length && lines[i].trim() !== "") {
+    paragraph.push(lines[i]);
+    i++;
+  }
+  return paragraph.join(" ").trim();
+}
+
+function parsePriorityRow(line) {
+  const cells = line
+    .split("|")
+    .slice(1, -1)
+    .map((c) => c.trim());
+  if (cells.length < 5) return null;
+  const [item, agents, owner, status, added] = cells;
+  if (item === "*None*") return null;
+  return { item, agents, owner, status, added, link: null };
+}
+
+function findHeading(lines, heading) {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === heading) return i;
+  }
+  return -1;
+}
+
+function findSectionEnd(lines, start) {
+  for (let i = start; i < lines.length; i++) {
+    if (/^## /.test(lines[i])) return i;
+  }
+  return lines.length;
+}
+
+function parsePriorityTable(text) {
+  if (!text) return [];
+  const lines = text.split("\n");
+  const start = findHeading(lines, PRIORITY_INDEX_HEADING);
+  if (start === -1) return [];
+  const end = findSectionEnd(lines, start + 1);
+  const rows = [];
+  let inTable = false;
+  let seenSep = false;
+  for (let i = start + 1; i < end; i++) {
+    const line = lines[i];
+    if (/^\|\s*Item\s*\|/.test(line)) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && /^\|\s*---/.test(line)) {
+      seenSep = true;
+      continue;
+    }
+    if (!(inTable && seenSep && line.startsWith("|"))) continue;
+    const row = parsePriorityRow(line);
+    if (row) rows.push(row);
+  }
+  return rows;
+}
+
+function splitPriorities(rows, agent) {
+  const owned = [];
+  const cross = [];
+  for (const r of rows) {
+    if (r.owner === agent) owned.push(r);
+    else cross.push(r);
+  }
+  return { owned, cross };
+}
+
+function parseStoryboardItems(text, agent) {
+  if (!text) return [];
+  const lines = text.split("\n");
+  const items = [];
+  let inAgent = false;
+  for (const line of lines) {
+    const h3Match = line.match(/^### (.+)$/);
+    if (h3Match) {
+      inAgent = h3Match[1].toLowerCase().startsWith(agent.toLowerCase());
+      continue;
+    }
+    if (!inAgent) continue;
+    const bullet = line.match(/^[-*]\s+(.+)$/);
+    if (bullet) {
+      items.push({
+        dim: agent,
+        threshold: bullet[1],
+        status: "open",
+        link: null,
+      });
+    }
+  }
+  return items;
+}
+
+function countInbox(text) {
+  if (!text) return 0;
+  const lines = text.split("\n");
+  const markerIdx = lines.findIndex((l) => l.trim() === MEMO_INBOX_MARKER);
+  if (markerIdx === -1) return 0;
+  let n = 0;
+  for (let i = markerIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    if (/^##\s/.test(line)) break;
+    if (!line.startsWith("-")) continue;
+    if (/\*No new messages\.\*/.test(line)) continue;
+    n++;
+  }
+  return n;
+}
+
+function mapPriority(r) {
+  return { item: r.item, status: r.status, added: r.added, link: r.link };
+}
+
+function mapClaim(c) {
+  return {
+    agent: c.agent,
+    target: c.target,
+    branch: c.branch,
+    pr: c.pr,
+    claimed_at: c.claimed_at,
+    expires_at: c.expires_at,
+  };
+}
+
+/** Build the boot digest JSON object. */
+export function buildDigest({ wikiRoot, agent, today, _fs, _gh }) {
+  const date = today instanceof Date ? today : new Date(today);
+  const todayStr = date.toISOString().slice(0, 10);
+
+  const summaryPath = path.join(wikiRoot, `${agent}.md`);
+  const memoryPath = path.join(wikiRoot, "MEMORY.md");
+  const storyboardPath = currentStoryboardPath(wikiRoot, date);
+
+  const summaryText = readIfExists(summaryPath);
+  const memoryText = readIfExists(memoryPath);
+  const storyboardText = readIfExists(storyboardPath);
+
+  const { active } = filterExpired(parseClaims(memoryText ?? ""), todayStr);
+  const { owned, cross } = splitPriorities(
+    parsePriorityTable(memoryText ?? ""),
+    agent,
+  );
+
+  return {
+    summary: extractSummary(summaryText),
+    owned_priorities: owned.map(mapPriority),
+    cross_cutting: cross.map(mapPriority),
+    claims: active.map(mapClaim),
+    storyboard_items: parseStoryboardItems(storyboardText ?? "", agent),
+    inbox_count: countInbox(summaryText),
+    storyboard_path: existsSync(storyboardPath)
+      ? path.relative(path.dirname(wikiRoot) || ".", storyboardPath)
+      : "",
+  };
+}