@forwardimpact/libwiki 0.2.13 → 0.2.15

package/bin/fit-wiki.js

@@ -16,14 +16,11 @@ const NEEDS_WIKI_SYNC = new Set(["claim", "release", "push", "pull", "init"]);
 
 async function main() {
   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 definition = createDefinition(runtime.proc.env);
+  const cli = createCli(definition, {
+    runtime,
+    packageJsonUrl: new URL("../package.json", import.meta.url),
+  });
 
   const parsed = cli.parse(runtime.proc.argv.slice(2));
   if (!parsed) return runtime.proc.exit(0); // --help / --version already printed

package/package.json

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

package/src/audit/rules.js

@@ -77,7 +77,6 @@ const columnCount = (expected) => (s) =>
 
 const exists = (s) => (s.exists ? null : {});
 const expired = (s, ctx) => (s.expires_at < ctx.today ? {} : null);
-const always = () => ({});
 
 function entryHasDecision(lines, startIdx, requiredLine, stopRe) {
   let seen = 0;
@@ -257,6 +256,7 @@ export const RULES = [
     id: "weekly-log.line-budget",
     scope: "weekly-log-main",
     severity: "fail",
+    remediation: "rotate",
     check: lineBudget(WEEKLY_LOG_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${WEEKLY_LOG_LINE_BUDGET})`,
     hint: "run `bunx fit-wiki rotate` to seal this file as a sealed part and start a fresh weekly log",
@@ -265,6 +265,7 @@ export const RULES = [
     id: "weekly-log.word-budget",
     scope: "weekly-log-main",
     severity: "fail",
+    remediation: "rotate",
     check: wordBudget(WEEKLY_LOG_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${WEEKLY_LOG_WORD_BUDGET})`,
     hint: "run `bunx fit-wiki rotate` to seal this file as a sealed part and start a fresh weekly log",
@@ -282,6 +283,7 @@ export const RULES = [
     id: "decision-block.heading-within-5",
     scope: "weekly-log-main",
     severity: "fail",
+    remediation: "flag",
     check: decisionWithin5({
       entryRe: /^## \d{4}-\d{2}-\d{2}(?:[\s(].*)?$/,
       requiredLine: DECISION_HEADING,
@@ -305,6 +307,7 @@ export const RULES = [
     id: "weekly-log-part.line-budget",
     scope: "weekly-log-part",
     severity: "fail",
+    remediation: "flag",
     check: lineBudget(WEEKLY_LOG_LINE_BUDGET),
     message: (_s, r) => `${r.value} lines (limit ${WEEKLY_LOG_LINE_BUDGET})`,
     hint: "sealed parts should already be at-or-under the cap; if not, the rotation that produced this part needs investigation",
@@ -313,6 +316,7 @@ export const RULES = [
     id: "weekly-log-part.word-budget",
     scope: "weekly-log-part",
     severity: "fail",
+    remediation: "flag",
     check: wordBudget(WEEKLY_LOG_WORD_BUDGET),
     message: (_s, r) => `${r.value} words (limit ${WEEKLY_LOG_WORD_BUDGET})`,
     hint: "sealed parts should already be at-or-under the cap; if not, the rotation that produced this part needs investigation",
@@ -487,15 +491,4 @@ export const RULES = [
   // -- STATUS.md rows (per-migration-unit sub-row schema) --
 
   ...STATUS_ROW_RULES,
-
-  // -- Stray files --
-
-  {
-    id: "wiki.stray-file",
-    scope: "stray-file",
-    severity: "fail",
-    check: always,
-    message: () => "Does not match any known scope",
-    hint: "rename to a recognized scope (summary, weekly log, weekly-log part) or remove the file",
-  },
 ];

package/src/audit/scopes.js

@@ -74,8 +74,7 @@ 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.
+  // `status-row` scope — skip the per-file classification.
   if (base === "STATUS.md") return null;
   if (NON_SUMMARY_PREFIXES.some((p) => base.startsWith(p))) return null;
   if (WEEKLY_LOG_NAME_RE.test(base)) {
@@ -85,8 +84,10 @@ function classifyFile(filePath, fs) {
     return { kind: "weekly-log-part", subject: loadFile(filePath, fs) };
   }
   const subject = loadFile(filePath, fs);
-  const kind = SUMMARY_H1_RE.test(subject.firstLine) ? "summary" : "stray";
-  return { kind, subject };
+  // Files that do not match a summary or weekly-log shape are left
+  // unclassified: stray files are not audited.
+  if (!SUMMARY_H1_RE.test(subject.firstLine)) return null;
+  return { kind: "summary", subject };
 }
 
 function loadMemory(wikiRoot, fs) {
@@ -216,7 +217,6 @@ const SCOPE_RESOLVERS = {
       ...r,
       path: ctx.status.path,
     })),
-  "stray-file": (ctx) => ctx.subjects.stray,
 };
 
 /** Resolve a scope key into the list of subjects the engine should iterate. */
@@ -236,7 +236,6 @@ export function buildContext({ wikiRoot, today, fs }) {
     summary: [],
     "weekly-log-main": [],
     "weekly-log-part": [],
-    stray: [],
   };
   for (const file of listMdFiles(wikiRoot, fs)) {
     const classified = classifyFile(file, fs);

package/src/cli-definition.js

@@ -13,16 +13,16 @@ import { runFixCommand } from "./commands/fix.js";
 /**
  * Build the `fit-wiki` libcli definition. The agent/sender defaults read the
  * injected `env` rather than the ambient `process.env` so this module carries
- * no ambient dependency; the bin shim passes `runtime.proc.env` and the
- * package version. Each subcommand carries a `handler` and (for subcommand-
- * bearing commands) `args`/`argsUsage` so `cli.dispatch` can route to the
- * per-command handler with a frozen `ctx`.
+ * no ambient dependency; the bin shim passes `runtime.proc.env`. The version is
+ * resolved by libcli's `createCli` from the bin's `packageJsonUrl`. Each
+ * subcommand carries a `handler` and (for subcommand-bearing commands)
+ * `args`/`argsUsage` so `cli.dispatch` can route to the per-command handler
+ * with a frozen `ctx`.
  *
  * @param {Record<string, string>} env - The process env (`runtime.proc.env`).
- * @param {string} version - The package version string.
  * @returns {object} The libcli definition.
  */
-export function createDefinition(env, version) {
+export function createDefinition(env) {
   const wikiRootOpt = {
     "wiki-root": {
       type: "string",
@@ -48,7 +48,6 @@ export function createDefinition(env, version) {
 
   return {
     name: "fit-wiki",
-    version,
     description: "Wiki lifecycle management for the Kata agent system",
     commands: [
       {
@@ -174,7 +173,7 @@ export function createDefinition(env, version) {
       {
         name: "fix",
         description:
-          "Auto-fix wiki audit findings using an AI agent (technical-writer, Haiku)",
+          "Auto-fix wiki audit findings: rotate weekly logs, fix the rest with an AI agent (technical-writer, Haiku), flag the unresolvable",
         handler: runFixCommand,
         options: {
           ...wikiRootOpt,

package/src/commands/fix.js

@@ -8,14 +8,25 @@ import {
 } from "@forwardimpact/libeval";
 import { RULES } from "../audit/rules.js";
 import { buildContext, resolveScope } from "../audit/scopes.js";
+import { rotateIfOverBudget, weeklyLogPath } from "../weekly-log.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 
-// The agent edits, we re-audit, and resume on whatever still fails. Cap the
-// rounds so a finding the agent cannot resolve (e.g. a budget needing
-// `fit-wiki rotate`, which it has no Bash to run) fails loudly, not forever.
+// Pipeline: audit → deterministic rotation (the one fix needing a file seal the
+// agent can't do) → re-audit → Haiku agent on the prose-judgment residual →
+// flag what neither should touch. MAX_ROUNDS still caps the agent loop so an
+// unresolvable agent-class finding fails loudly rather than spinning forever.
 const MAX_ROUNDS = 3;
 
+/**
+ * A finding's remediation class, from the declarative rule. Rules without a
+ * `remediation` field default to `"agent"`: the Haiku agent handles all
+ * prose-judgment fixes (summary trims, section order, MEMORY.md prose).
+ */
+function classOf(finding) {
+  return RULES.find((r) => r.id === finding.id)?.remediation ?? "agent";
+}
+
 /**
  * Every rule governing a scope with an open finding, as `id — hint` lines.
  * Handing the agent the full contract for the files it edits — not just the
@@ -63,6 +74,56 @@ function composeFollowup(findings, projectRoot) {
   ].join("\n");
 }
 
+/**
+ * Deterministic pre-pass: seal every over-budget current-week weekly-log main
+ * file via `rotateIfOverBudget`. The agent name comes from the audit's own
+ * subjects (keyed by path) — no filename parsing. `force: true` rotates even a
+ * word-over/line-under file.
+ *
+ * `rotateIfOverBudget` always seals the agent's *current-week* log, so we only
+ * call it when the finding IS that file. A prior-week over-budget main is left
+ * untouched (rotating it would force-seal a healthy current-week log instead);
+ * it survives the re-audit and is flagged for a human.
+ */
+function rotateOverBudgetMainLogs(
+  findings,
+  { wikiRoot, today, projectRoot, fs, out },
+) {
+  const subjects = buildContext({ wikiRoot, today, fs }).subjects[
+    "weekly-log-main"
+  ];
+  const agentByPath = new Map(subjects.map((s) => [s.path, s.agentPrefix]));
+  for (const f of findings) {
+    if (classOf(f) !== "rotate") continue;
+    const agent = agentByPath.get(f.path);
+    if (!agent) continue;
+    if (weeklyLogPath(wikiRoot, agent, today) !== f.path) continue;
+    const res = rotateIfOverBudget(
+      wikiRoot,
+      agent,
+      today,
+      0,
+      { force: true },
+      fs,
+    );
+    if (res.rotated) {
+      out(
+        `rotated ${path.relative(projectRoot, res.fromPath)} -> ` +
+          `${path.relative(projectRoot, res.toPath)}\n`,
+      );
+    }
+  }
+}
+
+/** Report findings that need human judgment — never auto-fixed. */
+function reportFlags(err, flagFindings, projectRoot) {
+  err(
+    `fit-wiki fix: ${flagFindings.length} finding(s) need human judgment ` +
+      `(not auto-fixable):\n` +
+      emitFindingsText(flagFindings, { cwd: projectRoot }),
+  );
+}
+
 /**
  * Surface a round's agent error, if any. Returns true when it is fatal: a
  * missing sessionId means the process never started (e.g. the SDK refused
@@ -80,65 +141,123 @@ function isFatalError(result, round, err) {
   return false;
 }
 
-/** Run the wiki audit and auto-fix findings via a Haiku-powered AgentRunner. */
-export async function runFixCommand(ctx) {
-  const { runtime } = ctx.deps;
-  const projectRoot = resolveProjectRoot(runtime);
-  const wikiRoot = ctx.options["wiki-root"] || path.join(projectRoot, "wiki");
-  const today = ctx.options.today || currentDayIso(runtime);
-  const out = (s) => runtime.proc.stdout.write(s);
-  const err = (s) => runtime.proc.stderr.write(s);
-
-  // The agent's edits change the result, so re-read and re-audit each round.
-  const audit = () =>
-    runRules(RULES, buildContext({ wikiRoot, today, fs: runtime.fsSync }), {
-      resolveScope,
-    });
-
-  let findings = audit();
-  if (findings.length === 0) {
-    out("nothing to fix\n");
-    return { ok: true };
-  }
-
+/** Build the Haiku technical-writer runner for prose-judgment fixes. */
+async function buildFixRunner(ctx, projectRoot, runtime) {
   const query =
     ctx.deps.query ?? (await import("@anthropic-ai/claude-agent-sdk")).query;
-  const runner = createAgentRunner({
+  return createAgentRunner({
     cwd: projectRoot,
     query,
     output: new Writable({ write: (_c, _e, cb) => cb() }),
     model: "claude-haiku-4-5-20251001",
     maxTurns: 30,
-    allowedTools: ["Read", "Write", "Edit"],
+    allowedTools: ["Read", "Glob", "Write", "Edit"],
     settingSources: ["project"],
     systemPrompt: composeProfilePrompt("technical-writer", {
       profilesDir: path.resolve(projectRoot, ".claude/agents"),
       runtime,
     }),
-    redactor: createRedactor(),
+    redactor: createRedactor({ runtime }),
   });
+}
 
-  // The audit is the verdict, not the agent's self-report: run, re-audit, and
-  // resume the session on whatever still fails until clean or out of rounds.
-  // Resuming also extends the turn budget for a trim too large for one round.
-  let task = composeTask(findings, wikiRoot, projectRoot);
+/**
+ * Run the agent on the prose-judgment findings, re-auditing each round until
+ * clean, flag-only, or MAX_ROUNDS is exhausted. The audit is the verdict, not
+ * the agent's self-report; resuming extends the turn budget for a trim too
+ * large for one round.
+ */
+async function runAgentRounds(runner, agentFindings, deps) {
+  const { wikiRoot, projectRoot, audit, partition, out, err } = deps;
+  let task = composeTask(agentFindings, wikiRoot, projectRoot);
+  let flagFindings = [];
   for (let round = 0; round < MAX_ROUNDS; round++) {
     const result =
       round === 0 ? await runner.run(task) : await runner.resume(task);
     if (result.text) out(result.text + "\n");
     if (isFatalError(result, round, err)) return { ok: false, code: 1 };
 
+    ({ agentFindings, flagFindings } = partition(audit()));
+    if (agentFindings.length === 0) {
+      if (flagFindings.length === 0) {
+        out("fixed: wiki audit is clean\n");
+        return { ok: true, code: 0 };
+      }
+      reportFlags(err, flagFindings, projectRoot);
+      return { ok: false, code: 2 };
+    }
+    task = composeFollowup(agentFindings, projectRoot);
+  }
+
+  err(
+    `fit-wiki fix: ${agentFindings.length} finding(s) remain after ` +
+      `${MAX_ROUNDS} round(s):\n` +
+      emitFindingsText(agentFindings, { cwd: projectRoot }),
+  );
+  if (flagFindings.length > 0) reportFlags(err, flagFindings, projectRoot);
+  return { ok: false, code: 1 };
+}
+
+/** Run the wiki audit and auto-fix findings: rotate, then agent, then flag. */
+export async function runFixCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const fs = runtime.fsSync;
+  const projectRoot = resolveProjectRoot(runtime);
+  const wikiRoot = ctx.options["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = ctx.options.today || currentDayIso(runtime);
+  const out = (s) => runtime.proc.stdout.write(s);
+  const err = (s) => runtime.proc.stderr.write(s);
+
+  // The agent's edits change the result, so re-read and re-audit each round.
+  const audit = () =>
+    runRules(RULES, buildContext({ wikiRoot, today, fs }), { resolveScope });
+  // The agent only ever gets prose-judgment (`agent`-class) findings. A
+  // `rotate` finding that survived the pre-pass (e.g. a prior-week log) is
+  // unfixable by the agent — and trimming append-only history to satisfy a
+  // budget would corrupt it — so it joins the flag set for a human.
+  const partition = (found) => ({
+    agentFindings: found.filter((f) => classOf(f) === "agent"),
+    flagFindings: found.filter((f) => classOf(f) !== "agent"),
+  });
+
+  let findings = audit();
+  if (findings.length === 0) {
+    out("nothing to fix\n");
+    return { ok: true };
+  }
+
+  // Deterministic layer: weekly-log rotation only.
+  if (findings.some((f) => classOf(f) === "rotate")) {
+    rotateOverBudgetMainLogs(findings, {
+      wikiRoot,
+      today,
+      projectRoot,
+      fs,
+      out,
+    });
     findings = audit();
     if (findings.length === 0) {
       out("fixed: wiki audit is clean\n");
       return { ok: true, code: 0 };
     }
-    task = composeFollowup(findings, projectRoot);
   }
 
-  err(
-    `fit-wiki fix: ${findings.length} finding(s) remain after ${MAX_ROUNDS} round(s):\n` +
-      emitFindingsText(findings, { cwd: projectRoot }),
-  );
-  return { ok: false, code: 1 };
+  // Residual: agent-class goes to the writer; everything else (flag, plus any
+  // rotate finding the deterministic pass could not handle) needs a human.
+  const { agentFindings, flagFindings } = partition(findings);
+  if (agentFindings.length === 0) {
+    reportFlags(err, flagFindings, projectRoot);
+    return { ok: false, code: 2 };
+  }
+
+  // Constructed only now, so a rotation-only or flag-only run never spawns it.
+  const runner = await buildFixRunner(ctx, projectRoot, runtime);
+  return runAgentRounds(runner, agentFindings, {
+    wikiRoot,
+    projectRoot,
+    audit,
+    partition,
+    out,
+    err,
+  });
 }

package/src/commands/refresh.js

@@ -53,6 +53,18 @@ 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.
+function readStoryboardOrNull(runtime, storyboardPath) {
+  try {
+    return runtime.fsSync.readFileSync(storyboardPath, "utf-8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    return null;
+  }
+}
+
 /** Re-render XmR chart blocks and issue-list blocks in a storyboard file. */
 export async function runRefreshCommand(ctx) {
   const { runtime, gitClient } = ctx.deps;
@@ -63,7 +75,11 @@ export async function runRefreshCommand(ctx) {
     projectRoot,
     ctx.args["storyboard-path"] || currentStoryboardRelPath(runtime),
   );
-  const text = runtime.fsSync.readFileSync(storyboardPath, "utf-8");
+  const text = readStoryboardOrNull(runtime, storyboardPath);
+  if (text === null) {
+    runtime.proc.stderr.write(`refresh: no storyboard at ${storyboardPath}\n`);
+    return { ok: true };
+  }
   const blocks = scanMarkers(text, {
     warn: (message) => runtime.proc.stderr.write(message),
   });

package/src/util/wiki-dir.js

@@ -3,7 +3,7 @@ import path from "node:path";
 /**
  * Find the project root by upward `package.json` discovery from the current
  * working directory, using the injected `runtime.finder` (the one canonical
- * Finder — SC9 keeps `new Finder(...)` inside libutil).
+ * Finder, constructed only inside libutil).
  * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
  * @returns {string}
  */