@forwardimpact/libwiki 0.1.3 → 0.2.0

package/src/commands/init.js

@@ -1,12 +1,21 @@
-import { mkdirSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import fsAsync from "node:fs/promises";
 import { Finder } from "@forwardimpact/libutil";
+import { createScriptConfig } from "@forwardimpact/libconfig";
 import { WikiRepo } from "../wiki-repo.js";
 import { listSkills } from "../skill-roster.js";
+import {
+  ACTIVE_CLAIMS_HEADING,
+  ACTIVE_CLAIMS_TABLE_HEADER,
+  ACTIVE_CLAIMS_TABLE_SEPARATOR,
+} from "../constants.js";
+
+/** Resolve the wiki clone URL. Honors the FIT_WIKI_URL env var as an explicit override (for sandboxed environments where `origin` is rewritten to a local proxy that does not serve wiki repos); otherwise derives the URL by appending `.wiki.git` to the parent repo's `origin` remote. */
+export function deriveWikiUrl(parentDir) {
+  if (process.env.FIT_WIKI_URL) return process.env.FIT_WIKI_URL;
 
-function deriveWikiUrl(parentDir) {
   const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
     encoding: "utf-8",
     stdio: "pipe",
@@ -17,18 +26,96 @@ function deriveWikiUrl(parentDir) {
   return base + ".wiki.git";
 }
 
-/** Clone the wiki if not already present (URL derived from origin remote), copy git identity from the parent repo, and create metric directories for each kata skill. */
-export function runInitCommand(values, _args, cli) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
+function scaffoldActiveClaims(memoryPath) {
+  if (!existsSync(memoryPath)) return false;
+  const text = readFileSync(memoryPath, "utf-8");
+  if (new RegExp(`^${ACTIVE_CLAIMS_HEADING}$`, "m").test(text)) return false;
 
-  const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
-  const skillsDir = path.resolve(
-    projectRoot,
-    values["skills-dir"] ?? path.join(".claude", "skills"),
-  );
+  const block = [
+    "",
+    ACTIVE_CLAIMS_HEADING,
+    "",
+    "In-flight work claimed by an agent. Row present = active; row absent = settled.",
+    "Writers: `fit-wiki claim`, `fit-wiki release`. Reader: `fit-wiki boot`.",
+    "",
+    ACTIVE_CLAIMS_TABLE_HEADER,
+    ACTIVE_CLAIMS_TABLE_SEPARATOR,
+    "| *None* | — | — | — | — | — |",
+    "",
+  ].join("\n");
+
+  const lines = text.split("\n");
+  const storyboardIdx = lines.findIndex((l) => l.trim() === "## Storyboard");
+  if (storyboardIdx === -1) {
+    writeFileSync(memoryPath, text.replace(/\n*$/, "") + "\n" + block + "\n");
+    return true;
+  }
+  lines.splice(storyboardIdx, 0, ...block.split("\n"), "");
+  writeFileSync(memoryPath, lines.join("\n"));
+  return true;
+}
+
+const AUDIT_HOOK_COMMAND = "bunx fit-wiki audit";
 
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  try {
+    return JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch {
+    process.stderr.write(
+      `init: ${settingsPath} is not valid JSON; skipping stop-hook install\n`,
+    );
+    return null;
+  }
+}
+
+function hasAuditHook(settings) {
+  if (!settings.hooks || !Array.isArray(settings.hooks.Stop)) return false;
+  for (const group of settings.hooks.Stop) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    if (
+      group.hooks.some(
+        (h) =>
+          h &&
+          typeof h.command === "string" &&
+          h.command.includes("fit-wiki audit"),
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function addAuditHook(settings) {
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+  if (settings.hooks.Stop.length === 0) {
+    settings.hooks.Stop.push({
+      hooks: [{ type: "command", command: AUDIT_HOOK_COMMAND }],
+    });
+    return;
+  }
+  if (!Array.isArray(settings.hooks.Stop[0].hooks)) {
+    settings.hooks.Stop[0].hooks = [];
+  }
+  settings.hooks.Stop[0].hooks.push({
+    type: "command",
+    command: AUDIT_HOOK_COMMAND,
+  });
+}
+
+function installStopHook(settingsPath) {
+  const settings = readSettings(settingsPath);
+  if (settings === null) return false;
+  if (hasAuditHook(settings)) return false;
+  addAuditHook(settings);
+  mkdirSync(path.dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return true;
+}
+
+async function maybeCloneWiki(projectRoot, wikiDir) {
   const wikiUrl = deriveWikiUrl(projectRoot);
   if (!wikiUrl) {
     process.stderr.write(
@@ -36,20 +123,56 @@ export function runInitCommand(values, _args, cli) {
     );
     return;
   }
+  const config = await createScriptConfig("wiki");
+  const repo = new WikiRepo({
+    wikiDir,
+    parentDir: projectRoot,
+    resolveToken: () => config.ghToken(),
+  });
+  const cloneResult = repo.ensureCloned(wikiUrl);
+  if (cloneResult.cloned) {
+    repo.inheritIdentity();
+  } else {
+    process.stderr.write(
+      "init: could not clone wiki, continuing with local-only steps\n",
+    );
+  }
+}
+
+/** Clone the wiki if not already present, scaffold Active Claims in MEMORY.md, install the audit Stop-hook, and create per-skill metric directories. */
+export async function runInitCommand(values, _args, _cli) {
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  const projectRoot = finder.findProjectRoot(process.cwd());
+
+  const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
+  const skillsDir = path.resolve(
+    projectRoot,
+    values["skills-dir"] ?? path.join(".claude", "skills"),
+  );
+  const settingsPath = path.resolve(projectRoot, ".claude", "settings.json");
 
-  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+  await maybeCloneWiki(projectRoot, wikiDir);
 
-  const cloneResult = repo.ensureCloned(wikiUrl);
-  if (!cloneResult.cloned) {
-    process.stderr.write("init: could not clone wiki, skipping\n");
-    return;
+  if (existsSync(skillsDir)) {
+    for (const slug of listSkills({ skillsDir })) {
+      mkdirSync(path.join(wikiDir, "metrics", slug), { recursive: true });
+    }
   }
 
-  repo.inheritIdentity();
+  if (existsSync(wikiDir)) {
+    const memoryPath = path.join(wikiDir, "MEMORY.md");
+    if (scaffoldActiveClaims(memoryPath)) {
+      process.stdout.write(
+        `init: scaffolded ${ACTIVE_CLAIMS_HEADING} in ${memoryPath}\n`,
+      );
+    }
+  }
 
-  const skills = listSkills({ skillsDir });
-  for (const slug of skills) {
-    mkdirSync(path.join(wikiDir, "metrics", slug), { recursive: true });
+  if (installStopHook(settingsPath)) {
+    process.stdout.write(
+      `init: installed Stop-hook audit entry in ${settingsPath}\n`,
+    );
   }
 
   process.stdout.write(`init: wiki ready at ${wikiDir}\n`);

package/src/commands/log.js

@@ -0,0 +1,102 @@
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Finder } from "@forwardimpact/libutil";
+import {
+  weeklyLogPath,
+  rotateIfOverBudget,
+  appendEntry,
+} from "../weekly-log.js";
+import { DECISION_HEADING } from "../constants.js";
+
+function projectRootForCommand() {
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  return finder.findProjectRoot(process.cwd());
+}
+
+function commonContext(values) {
+  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  if (!agent) {
+    process.stderr.write(
+      "log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n",
+    );
+    process.exit(2);
+  }
+  const projectRoot = projectRootForCommand();
+  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = values.today || new Date().toISOString().slice(0, 10);
+  return { agent, wikiRoot, today };
+}
+
+function ensureDateHeading(body, today) {
+  const heading = `## ${today}`;
+  if (body.startsWith(heading) || body.startsWith("## ")) return body;
+  return `${heading}\n\n${body}`;
+}
+
+function runDecision(values) {
+  const { agent, wikiRoot, today } = commonContext(values);
+  const surveyed = values.surveyed || "—";
+  const chosen = values.chosen || "—";
+  const rationale = values.rationale || "—";
+  const alternatives = values.alternatives || "—";
+  const body = [
+    `## ${today}`,
+    "",
+    DECISION_HEADING,
+    "",
+    `**Surveyed:** ${surveyed}`,
+    "",
+    `**Alternatives:** ${alternatives}`,
+    "",
+    `**Chosen:** ${chosen}`,
+    "",
+    `**Rationale:** ${rationale}`,
+    "",
+  ].join("\n");
+  const lineCount = body.split("\n").length;
+  rotateIfOverBudget(wikiRoot, agent, today, lineCount);
+  const target = weeklyLogPath(wikiRoot, agent, today);
+  appendEntry(target, body, agent, today);
+  process.stdout.write(`logged decision to ${target}\n`);
+}
+
+function runNote(values) {
+  const { agent, wikiRoot, today } = commonContext(values);
+  if (!values.field || !values.body) {
+    process.stderr.write("log note requires --field and --body\n");
+    process.exit(2);
+  }
+  const body = ensureDateHeading(
+    `### ${values.field}\n\n${values.body}\n`,
+    today,
+  );
+  const lineCount = body.split("\n").length;
+  rotateIfOverBudget(wikiRoot, agent, today, lineCount);
+  const target = weeklyLogPath(wikiRoot, agent, today);
+  appendEntry(target, body, agent, today);
+  process.stdout.write(`logged note to ${target}\n`);
+}
+
+function runDone(values) {
+  const { agent, wikiRoot, today } = commonContext(values);
+  const body = `### Closed\n\nRun closed ${today}.\n`;
+  const lineCount = body.split("\n").length;
+  rotateIfOverBudget(wikiRoot, agent, today, lineCount);
+  const target = weeklyLogPath(wikiRoot, agent, today);
+  appendEntry(target, body, agent, today);
+  process.stdout.write(`closed entry in ${target}\n`);
+}
+
+const SUBS = { decision: runDecision, note: runNote, done: runDone };
+
+/** Dispatch `log {decision|note|done}` to the matching sub-handler. */
+export function runLogCommand(values, args, cli) {
+  const sub = args[0];
+  const handler = SUBS[sub];
+  if (!handler) {
+    cli.usageError("log requires subcommand: decision | note | done");
+    process.exit(2);
+  }
+  handler(values);
+}

package/src/commands/refresh.js

@@ -4,6 +4,7 @@ import fsAsync from "node:fs/promises";
 import { Finder } from "@forwardimpact/libutil";
 import { scanMarkers } from "../marker-scanner.js";
 import { renderBlock, BlockRenderError } from "../block-renderer.js";
+import { renderIssueList } from "../issue-list-renderer.js";
 
 function currentStoryboardPath() {
   const now = new Date();
@@ -12,8 +13,34 @@ function currentStoryboardPath() {
   return `wiki/storyboard-${yyyy}-M${mm}.md`;
 }
 
-/** Re-render all XmR chart blocks in a storyboard file by scanning markers and splicing updated content. */
-export function runRefreshCommand(values, args, cli) {
+function renderForBlock(block, projectRoot) {
+  if (block.kind === "xmr") {
+    return renderBlock({
+      metric: block.metric,
+      csvPath: block.csvPath,
+      projectRoot,
+    });
+  }
+  if (block.kind === "issue-list") {
+    return renderIssueList({
+      topic: block.topic,
+      state: block.state,
+      window: block.window,
+    });
+  }
+  return null;
+}
+
+function spliceBlock(lines, block, rendered) {
+  lines.splice(
+    block.openLine + 1,
+    block.closeLine - block.openLine - 1,
+    ...rendered,
+  );
+}
+
+/** Re-render XmR chart blocks and issue-list blocks in a storyboard file. */
+export function runRefreshCommand(values, args, _cli) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);
   const projectRoot = finder.findProjectRoot(process.cwd());
@@ -24,7 +51,6 @@ export function runRefreshCommand(values, args, cli) {
   );
   const text = readFileSync(storyboardPath, "utf-8");
   const blocks = scanMarkers(text);
-
   if (blocks.length === 0) return;
 
   const lines = text.split("\n");
@@ -33,16 +59,9 @@ export function runRefreshCommand(values, args, cli) {
   for (let i = blocks.length - 1; i >= 0; i--) {
     const block = blocks[i];
     try {
-      const rendered = renderBlock({
-        metric: block.metric,
-        csvPath: block.csvPath,
-        projectRoot,
-      });
-      lines.splice(
-        block.openLine + 1,
-        block.closeLine - block.openLine - 1,
-        ...rendered,
-      );
+      const rendered = renderForBlock(block, projectRoot);
+      if (!rendered) continue;
+      spliceBlock(lines, block, rendered);
       spliced = true;
     } catch (err) {
       if (!(err instanceof BlockRenderError)) throw err;
@@ -53,4 +72,9 @@ export function runRefreshCommand(values, args, cli) {
   }
 
   if (spliced) writeFileSync(storyboardPath, lines.join("\n"));
+  if (values && values.format === "json") {
+    process.stdout.write(
+      JSON.stringify({ blocks: blocks.length, spliced }) + "\n",
+    );
+  }
 }

package/src/commands/rotate.js

@@ -0,0 +1,25 @@
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Finder } from "@forwardimpact/libutil";
+import { rotateIfOverBudget } from "../weekly-log.js";
+
+/** Force-rotate the current weekly log to a sealed part file. */
+export function runRotateCommand(values, _args, cli) {
+  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  if (!agent) {
+    cli.usageError("rotate requires --agent or LIBEVAL_AGENT_PROFILE");
+    process.exit(2);
+  }
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  const projectRoot = finder.findProjectRoot(process.cwd());
+  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = values.today || new Date().toISOString().slice(0, 10);
+
+  const result = rotateIfOverBudget(wikiRoot, agent, today, 0, { force: true });
+  if (result.rotated) {
+    process.stdout.write(`rotated ${result.fromPath} → ${result.toPath}\n`);
+  } else {
+    process.stdout.write(`no rotation needed for ${agent}\n`);
+  }
+}

package/src/commands/sync.js

@@ -1,16 +1,26 @@
 import path from "node:path";
 import fsAsync from "node:fs/promises";
 import { Finder } from "@forwardimpact/libutil";
+import { createScriptConfig } from "@forwardimpact/libconfig";
 import { WikiRepo, WikiPullConflict } from "../wiki-repo.js";
 
-/** Commit all wiki changes and push them to the remote wiki repository. */
-export function runPushCommand(values, _args, cli) {
+async function buildRepo(values) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);
   const projectRoot = finder.findProjectRoot(process.cwd());
   const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
 
-  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+  const config = await createScriptConfig("wiki");
+  return new WikiRepo({
+    wikiDir,
+    parentDir: projectRoot,
+    resolveToken: () => config.ghToken(),
+  });
+}
+
+/** Commit all wiki changes and push them to the remote wiki repository. */
+export async function runPushCommand(values, _args, cli) {
+  const repo = await buildRepo(values);
   repo.inheritIdentity();
 
   const result = repo.commitAndPush("wiki: update from session");
@@ -22,13 +32,8 @@ export function runPushCommand(values, _args, cli) {
 }
 
 /** Fetch and rebase the local wiki on origin/master; on rebase conflict, exit the process with code 1 and a message to resolve manually or push first. */
-export function runPullCommand(values, _args, cli) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
-  const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
-
-  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+export async function runPullCommand(values, _args, cli) {
+  const repo = await buildRepo(values);
   repo.inheritIdentity();
 
   try {

package/src/constants.js

@@ -1,3 +1,21 @@
 export const MEMO_INBOX_MARKER = "<!-- memo:inbox -->";
 export const INBOX_HEADING = "## Message Inbox";
 export const BROADCAST_TARGET = "all";
+
+export const MEMORY_FILE = "MEMORY.md";
+export const ACTIVE_CLAIMS_HEADING = "## Active Claims";
+export const ACTIVE_CLAIMS_TABLE_HEADER =
+  "| agent | target | branch | pr | claimed_at | expires_at |";
+export const ACTIVE_CLAIMS_TABLE_SEPARATOR =
+  "| --- | --- | --- | --- | --- | --- |";
+export const PRIORITY_INDEX_HEADING = "## Cross-Cutting Priorities";
+export const PRIORITY_INDEX_TABLE_HEADER =
+  "| Item | Agents | Owner | Status | Added |";
+export const DECISION_HEADING = "### Decision";
+
+// Cap derivation: ≤2.5% of a 1M-token context window = 25k tokens;
+// ≈42 tokens/line empirical proxy → ~500 lines. See spec 1060
+// design-a.md § Decision area 2 for the full anchor.
+export const WEEKLY_LOG_LINE_BUDGET = 500;
+export const SUMMARY_LINE_BUDGET = 80;
+export const CUTOVER_ISO_WEEK = "2026-W23";

package/src/index.js

@@ -5,8 +5,32 @@ export {
   MEMO_INBOX_MARKER,
   INBOX_HEADING,
   BROADCAST_TARGET,
+  MEMORY_FILE,
+  ACTIVE_CLAIMS_HEADING,
+  ACTIVE_CLAIMS_TABLE_HEADER,
+  ACTIVE_CLAIMS_TABLE_SEPARATOR,
+  PRIORITY_INDEX_HEADING,
+  PRIORITY_INDEX_TABLE_HEADER,
+  DECISION_HEADING,
+  WEEKLY_LOG_LINE_BUDGET,
+  SUMMARY_LINE_BUDGET,
+  CUTOVER_ISO_WEEK,
 } from "./constants.js";
 export { scanMarkers } from "./marker-scanner.js";
 export { renderBlock } from "./block-renderer.js";
+export { renderIssueList } from "./issue-list-renderer.js";
 export { WikiRepo } from "./wiki-repo.js";
 export { listSkills } from "./skill-roster.js";
+export {
+  parseClaims,
+  appendClaim,
+  removeClaim,
+  filterExpired,
+} from "./active-claims.js";
+export {
+  isoWeek,
+  weeklyLogPath,
+  rotateIfOverBudget,
+  appendEntry,
+} from "./weekly-log.js";
+export { buildDigest } from "./boot.js";

package/src/issue-list-renderer.js

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+
+function defaultGh(args) {
+  return spawnSync("gh", args, {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function daysAgo(today, n) {
+  const d = today instanceof Date ? new Date(today.getTime()) : new Date(today);
+  d.setUTCDate(d.getUTCDate() - n);
+  return d.toISOString().slice(0, 10);
+}
+
+/** Render an issue-list block for an obstacles/experiments marker. Returns markdown lines. */
+export function renderIssueList({
+  topic,
+  state,
+  window,
+  today = new Date(),
+  gh = defaultGh,
+}) {
+  const ghState = state === "closed" ? "closed" : "open";
+  const result = gh([
+    "issue",
+    "list",
+    "--label",
+    topic.replace(/s$/, ""),
+    "--state",
+    ghState,
+    "--json",
+    "number,title,labels,closedAt",
+    "--limit",
+    "100",
+  ]);
+  if (result.status !== 0) {
+    process.stderr.write(
+      `refresh: gh issue list failed for ${topic}:${state}\n`,
+    );
+    return [];
+  }
+  let issues;
+  try {
+    issues = JSON.parse(result.stdout || "[]");
+  } catch {
+    process.stderr.write(
+      `refresh: gh issue list JSON parse failed for ${topic}:${state}\n`,
+    );
+    return [];
+  }
+
+  if (state === "closed") {
+    const windowDays = window
+      ? Number.parseInt(window.replace("d", ""), 10)
+      : 7;
+    const cutoff = daysAgo(today, windowDays);
+    issues = issues.filter(
+      (i) => i.closedAt && i.closedAt.slice(0, 10) >= cutoff,
+    );
+  }
+
+  const lines = [];
+  for (const issue of issues) {
+    const tag = topic === "experiments" ? "Exp" : "Obs";
+    lines.push(`- **${tag} #${issue.number} — ${issue.title}**`);
+  }
+  return lines;
+}