@forwardimpact/libwiki 0.2.25 → 0.2.27

package/src/audit/scopes.js

@@ -2,11 +2,14 @@ import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims } from "../active-claims.js";
 import { countLines, countWords } from "../budget.js";
+import { parseStatusRowId } from "../status.js";
 import {
   PRIORITY_INDEX_HEADING,
   WEEKLY_LOG_NAME_RE,
   WEEKLY_LOG_PART_NAME_RE,
 } from "../constants.js";
+import { listAdmissionPaths } from "./admission.js";
+import { classifyPath, rootSummaryStem } from "./grammar.js";
 
 // Capture the agent-title group so the same regex both classifies a file
 // (`.test`) and yields the title for the agent-prefix audit (`.match[1]`).
@@ -33,6 +36,34 @@ function listMdFiles(wikiRoot, fs) {
     .map((e) => path.join(wikiRoot, e));
 }
 
+// Recursively collect every *.csv under `<wikiRoot>/metrics/`. The real layout
+// is `metrics/<skill>/<year>.csv` (two levels), so the walk recurses rather
+// than assuming a fixed depth. Uses readdirSync + statSync (rather than
+// `withFileTypes` Dirents) so it runs unchanged under the in-memory mock fs.
+function listCsvFiles(wikiRoot, fs) {
+  const metricsRoot = path.join(wikiRoot, "metrics");
+  if (!fs.existsSync(metricsRoot)) return [];
+  const found = [];
+  const walk = (dir) => {
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      if (fs.statSync(full).isDirectory()) walk(full);
+      else if (name.endsWith(".csv")) found.push(full);
+    }
+  };
+  walk(metricsRoot);
+  return found;
+}
+
+// Load a metrics CSV as an audit subject: `rows` is the array of line strings,
+// so a rule indexes `rows[i]` (a string) and `i + 1` is its line number.
+function loadCsv(filePath, fs) {
+  return {
+    path: filePath,
+    rows: fs.readFileSync(filePath, "utf-8").split("\n"),
+  };
+}
+
 function loadFile(filePath, fs) {
   const text = fs.readFileSync(filePath, "utf-8");
   const fileLines = text.split("\n");
@@ -90,9 +121,12 @@ function readOptional(filePath, fs) {
 
 /**
  * Parse the rows inside STATUS.md's fenced block into audit subjects. Lines
- * outside the ``` fence (header prose) and blank lines are skipped.
+ * outside the ``` fence (header prose) and blank lines are skipped. Each row
+ * carries a `kind` from {@link parseStatusRowId} (`"spec"`, `"experiment"`, or
+ * `null` for an unrecognized id); spec-shaped rules read the positional
+ * `id`/`phase`/`status` fields, experiment rules read `cells`.
  * @param {string} statusText - The full STATUS.md contents.
- * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string}>}
+ * @returns {Array<{lineNo: number, text: string, cells: string[], id: string, phase: string, status: string, kind: string|null}>}
  */
 function parseStatusRows(statusText) {
   const lines = statusText.split("\n");
@@ -106,6 +140,12 @@ function parseStatusRows(statusText) {
     }
     if (!inFence || line.trim() === "") continue;
     const cells = line.split("\t");
+    // Classify by id prefix so a malformed `exp:` row (e.g. wrong cell count)
+    // is still routed to the experiment rules, which flag it — rather than
+    // slipping through the spec-shaped rules. parseStatusRowId returns the
+    // structured fields only for a well-formed row; the rules read `cells`.
+    const isExp = typeof cells[0] === "string" && cells[0].startsWith("exp:");
+    const parsed = parseStatusRowId(cells[0], cells);
     rows.push({
       lineNo: i + 1,
       text: line,
@@ -113,6 +153,7 @@ function parseStatusRows(statusText) {
       id: cells[0],
       phase: cells[1],
       status: cells[2],
+      kind: isExp ? "experiment" : parsed ? parsed.kind : null,
     });
   }
   return rows;
@@ -177,6 +218,7 @@ const SCOPE_RESOLVERS = {
   summary: (ctx) => ctx.subjects.summary,
   "weekly-log-main": (ctx) => ctx.subjects["weekly-log-main"],
   "weekly-log-part": (ctx) => ctx.subjects["weekly-log-part"],
+  "metrics-csv": (ctx) => ctx.subjects["metrics-csv"],
   memory: (ctx) => [ctx.memory],
   "claims-row": (ctx) =>
     parseClaims(ctx.memory.text).map((c) => ({ ...c, path: ctx.memory.path })),
@@ -191,8 +233,54 @@ const SCOPE_RESOLVERS = {
       ...r,
       path: ctx.status.path,
     })),
+  "conflict-scan": (ctx) => conflictScanSubjects(ctx),
+  admission: (ctx) =>
+    ctx.admission.paths
+      .filter((p) => classifyPath(p, ctx.admission) === "rejected")
+      .map((relPath) => ({
+        path: path.join(ctx.wikiRoot, relPath),
+        relPath,
+      })),
 };
 
+// Normalize every audited surface into a uniform `{ path, text, fenceExempt }`
+// subject for the conflict-marker scan. The per-file subjects (summaries,
+// weekly logs and sealed parts, storyboard) carry `fileLines`; MEMORY.md and
+// STATUS.md carry `text` (readOptional shape). `fenceExempt` is true for prose
+// surfaces, where a fence quotes content, and false for STATUS.md, whose fenced
+// rows are data — a marker there is never legitimate (per-surface fence
+// contract). Files absent from disk (missing MEMORY/STATUS/storyboard) yield
+// empty text and produce no findings.
+function conflictScanSubjects(ctx) {
+  const subjects = [];
+  const fileScopes = ["summary", "weekly-log-main", "weekly-log-part"];
+  for (const scope of fileScopes) {
+    for (const s of ctx.subjects[scope]) {
+      subjects.push({
+        path: s.path,
+        text: s.fileLines.join("\n"),
+        fenceExempt: true,
+      });
+    }
+  }
+  subjects.push({
+    path: ctx.storyboard.path,
+    text: ctx.storyboard.text,
+    fenceExempt: true,
+  });
+  subjects.push({
+    path: ctx.memory.path,
+    text: ctx.memory.text,
+    fenceExempt: true,
+  });
+  subjects.push({
+    path: ctx.status.path,
+    text: ctx.status.text,
+    fenceExempt: false,
+  });
+  return subjects;
+}
+
 /** Resolve a scope key into the list of subjects the engine should iterate. */
 export function resolveScope(scopeKey, ctx) {
   const resolver = SCOPE_RESOLVERS[scopeKey];
@@ -200,21 +288,48 @@ export function resolveScope(scopeKey, ctx) {
   return resolver(ctx);
 }
 
+/**
+ * Build the admission slice: the tracked-file universe plus the
+ * `rootSummaryAgents` set that gates `<agent>/` sidecar directories. The agent
+ * set is derived first (a root-level summary-class file's stem) so the
+ * `admission` scope can classify sidecar directories against it.
+ *
+ * Returns the empty universe when `subprocess` is absent — callers that only
+ * read `.subjects` (the rotation pre-pass) skip the git read and the tree walk
+ * entirely, and produce no `admission` findings.
+ */
+function buildAdmission(wikiRoot, fs, subprocess) {
+  if (!subprocess) return { paths: [], rootSummaryAgents: new Set() };
+  const paths = listAdmissionPaths({ wikiRoot, fs, subprocess });
+  const rootSummaryAgents = new Set();
+  for (const p of paths) {
+    if (p.includes("/")) continue; // root-level files only
+    const stem = rootSummaryStem(p);
+    if (stem) rootSummaryAgents.add(stem);
+  }
+  return { paths, rootSummaryAgents };
+}
+
 /**
  * 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`).
+ * @param {{wikiRoot: string, today: string, fs: object, subprocess: object}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`); `subprocess` is
+ *   `runtime.subprocess` (its `runSync` backs the admission scope's git read).
  */
-export function buildContext({ wikiRoot, today, fs }) {
+export function buildContext({ wikiRoot, today, fs, subprocess }) {
   const subjects = {
     summary: [],
     "weekly-log-main": [],
     "weekly-log-part": [],
+    "metrics-csv": [],
   };
   for (const file of listMdFiles(wikiRoot, fs)) {
     const classified = classifyFile(file, fs);
     if (classified) subjects[classified.kind].push(classified.subject);
   }
+  for (const file of listCsvFiles(wikiRoot, fs)) {
+    subjects["metrics-csv"].push(loadCsv(file, fs));
+  }
   return {
     wikiRoot,
     today,
@@ -222,5 +337,6 @@ export function buildContext({ wikiRoot, today, fs }) {
     memory: readOptional(path.join(wikiRoot, "MEMORY.md"), fs),
     status: readOptional(path.join(wikiRoot, "STATUS.md"), fs),
     storyboard: loadStoryboard(wikiRoot, today, fs),
+    admission: buildAdmission(wikiRoot, fs, subprocess),
   };
 }

package/src/audit/status-row.js

@@ -1,24 +1,37 @@
 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 }`.
+// Validate every row inside wiki/STATUS.md's code fence. Rows are resolved by
+// the `status-row` scope in scopes.js; each subject carries
+// `{ cells, id, phase, status, kind, text }`. Two row kinds share the fence:
+//
+//   spec        `{id}<TAB>{phase}<TAB>{status}` — three cells
+//   experiment  `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}` — four cells
+//
+// Spec-shaped rules run for every non-experiment row (`kind !== "experiment"`,
+// which includes an unrecognized id so a malformed id still flags). Experiment
+// rules run only for `kind === "experiment"`.
 
 const PHASES = new Set(["spec", "design", "plan"]);
 const STATUSES = new Set(["draft", "approved", "implemented", "cancelled"]);
+const EXP_STATES = new Set(["registered", "approved", "cancelled"]);
+const PIN_RE = /^[0-9a-f]{40}$/;
 
-const hasThreeCells = (s) => s.cells.length === 3;
+const isSpecShaped = (s) => s.kind !== "experiment";
+const isExperiment = (s) => s.kind === "experiment";
+const hasThreeCells = (s) => isSpecShaped(s) && s.cells.length === 3;
+const hasFourCells = (s) => isExperiment(s) && s.cells.length === 4;
 
 export const STATUS_ROW_RULES = [
   {
     id: "status-row.shape",
     scope: "status-row",
     severity: "fail",
+    when: isSpecShaped,
     check: (s) =>
-      hasThreeCells(s) ? null : { actual: s.cells.length, text: s.text },
+      s.cells.length === 3 ? 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}`",
+    hint: "each spec STATUS row is `{id}<TAB>{phase}<TAB>{status}`",
   },
   {
     id: "status-row.id-format",
@@ -48,4 +61,76 @@ export const STATUS_ROW_RULES = [
       `Bad status '${r.status}' (expected draft|approved|implemented|cancelled)`,
     hint: "status is one of draft, approved, implemented, cancelled",
   },
+  {
+    id: "status-row.exp-shape",
+    scope: "status-row",
+    severity: "fail",
+    when: isExperiment,
+    check: (s) =>
+      s.cells.length === 4 ? null : { actual: s.cells.length, text: s.text },
+    message: (_s, r) =>
+      `${r.actual} tab-separated field(s), expected 4: "${r.text}"`,
+    hint: "each experiment row is `exp:{issue}<TAB>{state}<TAB>{pin}<TAB>{plan-ref}`",
+  },
+  {
+    // An experiment-kind row is classified by its `exp:` id prefix
+    // (scopes.js), so the spec `id-format` rule is skipped for it; this rule
+    // enforces the `exp:\d+` id so a non-numeric issue (e.g. `exp:abc`) flags
+    // rather than auditing clean — keeping the audit aligned with
+    // STATUS_ID_REGEX / parseStatusRowId.
+    id: "status-row.exp-id-format",
+    scope: "status-row",
+    severity: "fail",
+    when: isExperiment,
+    check: (s) => (/^exp:\d+$/.test(s.id) ? null : { id: s.id }),
+    message: (_s, r) => `Bad experiment id '${r.id}' (expected exp:NNN)`,
+    hint: "an experiment id is `exp:` followed by the issue number",
+  },
+  {
+    id: "status-row.exp-state",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    check: (s) => (EXP_STATES.has(s.cells[1]) ? null : { state: s.cells[1] }),
+    message: (_s, r) =>
+      `Bad experiment state '${r.state}' (expected registered|approved|cancelled)`,
+    hint: "experiment state is one of registered, approved, cancelled",
+  },
+  {
+    id: "status-row.exp-pin",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    // The pin is decidable per state, with no "ever approved" inference: a
+    // `registered` row has no pin (`-`); an `approved` row pins the 40-hex
+    // head; a `cancelled` row may carry the retained pin or `-` (it may or may
+    // not have been approved before cancellation), so both are accepted.
+    check: (s) => {
+      const [, state, pin] = s.cells;
+      if (state === "registered") {
+        return pin === "-" ? null : { state, pin, want: "-" };
+      }
+      if (state === "approved") {
+        return PIN_RE.test(pin) ? null : { state, pin, want: "a 40-hex SHA" };
+      }
+      if (state === "cancelled") {
+        return pin === "-" || PIN_RE.test(pin)
+          ? null
+          : { state, pin, want: "`-` or a 40-hex SHA" };
+      }
+      return null; // bad state already flagged by exp-state
+    },
+    message: (_s, r) =>
+      `Bad pin '${r.pin}' for state '${r.state}' (expected ${r.want})`,
+    hint: "registered pins `-`; approved pins a 40-hex SHA; cancelled pins either",
+  },
+  {
+    id: "status-row.exp-planref",
+    scope: "status-row",
+    severity: "fail",
+    when: hasFourCells,
+    check: (s) => (/^#\d+$/.test(s.cells[3]) ? null : { planRef: s.cells[3] }),
+    message: (_s, r) => `Bad plan-ref '${r.planRef}' (expected #NNN)`,
+    hint: "the plan-ref names the issue carrying the execution plan, e.g. #NNN",
+  },
 ];

package/src/block-renderer.js

@@ -13,10 +13,17 @@ export class BlockRenderError extends Error {
 /**
  * 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`).
+ * @param {{metric: string, csvPath: string, projectRoot: string, fs: object, priorReadAnchor?: string|null}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`). `priorReadAnchor`,
+ *   when supplied, stamps per-signal provenance surfaced in the Signals line.
  */
-export function renderBlock({ metric, csvPath, projectRoot, fs }) {
+export function renderBlock({
+  metric,
+  csvPath,
+  projectRoot,
+  fs,
+  priorReadAnchor,
+}) {
   const fullPath = path.resolve(projectRoot, csvPath);
   let csvText;
   try {
@@ -24,7 +31,7 @@ export function renderBlock({ metric, csvPath, projectRoot, fs }) {
   } catch {
     throw new BlockRenderError(`csv-not-found: ${csvPath}`);
   }
-  const report = analyze(csvText);
+  const report = analyze(csvText, { priorReadAnchor });
 
   const m = report.metrics.find((entry) => entry.metric === metric);
   if (!m) {
@@ -50,11 +57,18 @@ export function renderBlock({ metric, csvPath, projectRoot, fs }) {
   ];
 }
 
+// Annotate each fired rule with its records' provenance when present, so a
+// storyboard reader distinguishes recomputation-revealed signals from
+// new-point signals at the cell. Without a prior-read anchor, provenance is
+// absent and the line renders bare rule names exactly as before.
 function formatSignals(signals) {
   if (!signals) return "—";
   const fired = [];
   for (const rule of ["xRule1", "xRule2", "xRule3", "mrRule1"]) {
-    if (signals[rule]?.length > 0) fired.push(rule);
+    const recs = signals[rule];
+    if (!recs?.length) continue;
+    const tags = [...new Set(recs.map((r) => r.provenance).filter(Boolean))];
+    fired.push(tags.length ? `${rule} (${tags.join(", ")})` : rule);
   }
   return fired.length > 0 ? fired.join(", ") : "—";
 }

package/src/boot.js

@@ -1,7 +1,16 @@
 import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims, filterExpired } from "./active-claims.js";
-import { MEMO_INBOX_MARKER, PRIORITY_INDEX_HEADING } from "./constants.js";
+import { countLines, countWords } from "./budget.js";
+import {
+  MEMO_INBOX_MARKER,
+  PRIORITY_INDEX_HEADING,
+  SUMMARY_LINE_BUDGET,
+  SUMMARY_WORD_BUDGET,
+  WEEKLY_LOG_LINE_BUDGET,
+  WEEKLY_LOG_WORD_BUDGET,
+} from "./constants.js";
+import { weeklyLogPath } from "./weekly-log.js";
 
 function readIfExists(fs, filePath) {
   if (!fs.existsSync(filePath)) return null;
@@ -133,6 +142,24 @@ function countInbox(text) {
   return n;
 }
 
+/**
+ * Remaining budget for a budgeted surface: current value, cap, and headroom for
+ * both the line and word budget. An absent file (empty text) reports zero usage
+ * and full headroom so a writer sees the ceiling before composing.
+ */
+function headroom(text, lineCap, wordCap) {
+  const lines = countLines(text);
+  const words = countWords(text);
+  return {
+    words,
+    lines,
+    word_cap: wordCap,
+    line_cap: lineCap,
+    words_remaining: wordCap - words,
+    lines_remaining: lineCap - lines,
+  };
+}
+
 function mapPriority(r) {
   return { item: r.item, status: r.status, added: r.added, link: r.link };
 }
@@ -162,6 +189,7 @@ export function buildDigest({ wikiRoot, agent, today, fs }) {
   const summaryText = readIfExists(fs, summaryPath);
   const memoryText = readIfExists(fs, memoryPath);
   const storyboardText = readIfExists(fs, storyboardPath);
+  const weeklyLogText = readIfExists(fs, weeklyLogPath(wikiRoot, agent, today));
 
   const { active } = filterExpired(parseClaims(memoryText ?? ""), today);
   const { owned, cross } = splitPriorities(
@@ -176,6 +204,16 @@ export function buildDigest({ wikiRoot, agent, today, fs }) {
     claims: active.map(mapClaim),
     storyboard_items: parseStoryboardItems(storyboardText ?? "", agent),
     inbox_count: countInbox(summaryText),
+    summary_headroom: headroom(
+      summaryText ?? "",
+      SUMMARY_LINE_BUDGET,
+      SUMMARY_WORD_BUDGET,
+    ),
+    weekly_log_headroom: headroom(
+      weeklyLogText ?? "",
+      WEEKLY_LOG_LINE_BUDGET,
+      WEEKLY_LOG_WORD_BUDGET,
+    ),
     storyboard_path: fs.existsSync(storyboardPath)
       ? path.relative(path.dirname(wikiRoot) || ".", storyboardPath)
       : "",

package/src/cli-definition.js

@@ -11,18 +11,17 @@ import { runAuditCommand } from "./commands/audit.js";
 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`. 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`.
+ * Build the `fit-wiki` libcli definition. Agent identity is never resolved from
+ * the environment: agent-scoped subcommands require an explicit `--agent`
+ * (`--from` for `memo`) and fail closed without it, so this module carries no
+ * ambient agent identity. 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`).
  * @returns {object} The libcli definition.
  */
-export function createDefinition(env) {
+export function createDefinition() {
   const wikiRootOpt = {
     "wiki-root": {
       type: "string",
@@ -33,9 +32,7 @@ export function createDefinition(env) {
   const agentOpt = {
     agent: {
       type: "string",
-      description:
-        "Agent name (falls back to LIBEVAL_AGENT_PROFILE, then staff-engineer)",
-      default: env.LIBEVAL_AGENT_PROFILE || "staff-engineer",
+      description: "Agent name (required; no environment fallback)",
     },
   };
 
@@ -148,12 +145,17 @@ export function createDefinition(env) {
       },
       {
         name: "rotate",
-        description: "Force-rotate the current weekly log to a sealed part",
+        description: "Rotate the current weekly log to a sealed part",
         handler: runRotateCommand,
         options: {
           ...agentOpt,
           ...wikiRootOpt,
           ...todayOpt,
+          force: {
+            type: "boolean",
+            description:
+              "Seal even an under-budget log (the header-only floor still holds)",
+          },
         },
       },
       {
@@ -188,8 +190,7 @@ export function createDefinition(env) {
           from: {
             type: "string",
             description:
-              "Sender agent name (falls back to LIBEVAL_AGENT_PROFILE env var)",
-            default: env.LIBEVAL_AGENT_PROFILE,
+              "Sender agent name (required; no environment fallback)",
           },
           to: {
             type: "string",
@@ -239,7 +240,7 @@ export function createDefinition(env) {
         name: "pull",
         description: "Pull remote wiki changes into the local working tree",
         handler: runPullCommand,
-        options: { ...wikiRootOpt },
+        options: { ...agentOpt, ...wikiRootOpt, ...todayOpt },
       },
     ],
     globalOptions: {

package/src/commands/audit.js

@@ -17,7 +17,12 @@ export function runAuditCommand(ctx) {
   const wikiRoot = options["wiki-root"] || path.join(projectRoot, "wiki");
   const today = options.today || currentDayIso(runtime);
 
-  const auditCtx = buildContext({ wikiRoot, today, fs: runtime.fsSync });
+  const auditCtx = buildContext({
+    wikiRoot,
+    today,
+    fs: runtime.fsSync,
+    subprocess: runtime.subprocess,
+  });
   const findings = runRules(RULES, auditCtx, { resolveScope });
 
   runtime.proc.stdout.write(

package/src/commands/boot.js

@@ -1,5 +1,6 @@
 import { buildDigest } from "../boot.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 function renderMarkdown(digest) {
@@ -43,8 +44,12 @@ function renderMarkdown(digest) {
 export function runBootCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;
-  const agent =
-    options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE || "staff-engineer";
+  const resolved = requireAgentFlag(options, {
+    command: "boot",
+    example: "fit-wiki boot --agent staff-engineer",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
 
   const wikiRoot = resolveWikiRoot(runtime, options);
   const today = options.today || currentDayIso(runtime);