@forwardimpact/libwiki 0.2.7 → 0.2.8

package/README.md

@@ -53,8 +53,8 @@ line budget would be exceeded.
 ### `claim` / `release` — coordinate work
 
 ```sh
-npx fit-wiki claim   --agent X --target spec-1060 --branch claude/spec-1060
-npx fit-wiki release --agent X --target spec-1060
+npx fit-wiki claim   --agent X --target spec-NNNN --branch claude/spec-NNNN
+npx fit-wiki release --agent X --target spec-NNNN
 npx fit-wiki release --agent X --expired
 ```
 

package/bin/fit-wiki.js

@@ -222,8 +222,8 @@ 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 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",

package/package.json

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

package/src/audit/rules.js

@@ -188,15 +188,16 @@ export const RULES = [
     scope: "summary",
     severity: "fail",
     check: matches(/^\*\*Last run\*\*:/m),
-    message: (s) => `sections: ${s.path} missing '**Last run**:' line`,
+    message: () => "Missing '**Last run**:' line",
+    hint: "add a '**Last run**: <date> — <one-line state>' line directly after the H1",
   },
   {
     id: "summary.first-h2-inbox",
     scope: "summary",
     severity: "fail",
     check: firstH2Is("Message Inbox"),
-    message: (s, r) =>
-      `sections: ${s.path} first H2 is '${r.observed}', expected 'Message Inbox'`,
+    message: (_s, r) => `First H2 is '${r.observed}', expected 'Message Inbox'`,
+    hint: "move '## Message Inbox' to be the first H2 in the file",
   },
   {
     id: "summary.memo-inbox-marker",
@@ -204,31 +205,32 @@ export const RULES = [
     severity: "fail",
     when: (s) => s.h2s.includes("Message Inbox"),
     check: containsLine(MEMO_INBOX_MARKER),
-    message: (s) => `sections: ${s.path} missing <!-- memo:inbox --> marker`,
+    message: () => `Missing ${MEMO_INBOX_MARKER} marker`,
+    hint: "add the marker directly below the '## Message Inbox' heading so `fit-wiki memo` can find it",
   },
   {
     id: "summary.open-blockers-last",
     scope: "summary",
     severity: "fail",
     check: nothingAfterH2("Open Blockers"),
-    message: (s, r) =>
-      `sections: ${s.path} '${r.observed}' appears after 'Open Blockers'`,
+    message: (_s, r) => `'${r.observed}' appears after 'Open Blockers'`,
+    hint: "move '## Open Blockers' to the end of the file",
   },
   {
     id: "summary.line-budget",
     scope: "summary",
     severity: "fail",
     check: lineBudget(SUMMARY_LINE_BUDGET),
-    message: (s, r) =>
-      `budget: ${s.path} has ${r.value} lines (limit ${SUMMARY_LINE_BUDGET})`,
+    message: (_s, r) => `${r.value} lines (limit ${SUMMARY_LINE_BUDGET})`,
+    hint: "trim history into the weekly log; the summary holds settled state, not history",
   },
   {
     id: "summary.word-budget",
     scope: "summary",
     severity: "fail",
     check: wordBudget(SUMMARY_WORD_BUDGET),
-    message: (s, r) =>
-      `budget: ${s.path} has ${r.value} words (limit ${SUMMARY_WORD_BUDGET})`,
+    message: (_s, r) => `${r.value} words (limit ${SUMMARY_WORD_BUDGET})`,
+    hint: "trim history into the weekly log; the summary holds settled state, not history",
   },
   {
     id: "summary.h1-agent-matches-filename",
@@ -236,7 +238,8 @@ export const RULES = [
     severity: "fail",
     check: summaryAgentMismatch,
     message: (s, r) =>
-      `sections: ${s.path} H1 title slug '${r.titleSlug}' does not match filename prefix '${s.agentPrefix}'`,
+      `H1 title slug '${r.titleSlug}' does not match filename prefix '${s.agentPrefix}'`,
+    hint: "rename either the H1 ('# <agent> — Summary') or the file so they agree",
   },
 
   // -- Weekly logs (main) --
@@ -246,23 +249,24 @@ export const RULES = [
     scope: "weekly-log-main",
     severity: "fail",
     check: firstLineMatches(WEEKLY_LOG_H1_RE),
-    message: (s) => `weekly-log: ${s.path} missing valid H1 heading`,
+    message: () => "Missing valid H1 heading",
+    hint: "set the H1 to '# <agent> — YYYY-Www'",
   },
   {
     id: "weekly-log.line-budget",
     scope: "weekly-log-main",
     severity: "fail",
     check: lineBudget(WEEKLY_LOG_LINE_BUDGET),
-    message: (s, r) =>
-      `weekly-log: ${s.path} has ${r.value} lines (limit ${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",
   },
   {
     id: "weekly-log.word-budget",
     scope: "weekly-log-main",
     severity: "fail",
     check: wordBudget(WEEKLY_LOG_WORD_BUDGET),
-    message: (s, r) =>
-      `weekly-log: ${s.path} has ${r.value} words (limit ${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",
   },
   {
     id: "weekly-log.h1-agent-matches-filename",
@@ -270,7 +274,8 @@ export const RULES = [
     severity: "fail",
     check: weeklyAgentMismatch,
     message: (s, r) =>
-      `weekly-log: ${s.path} H1 title slug '${r.titleSlug}' does not match filename prefix '${s.agentPrefix}'`,
+      `H1 title slug '${r.titleSlug}' does not match filename prefix '${s.agentPrefix}'`,
+    hint: "rename either the H1 or the file so they agree",
   },
   {
     id: "decision-block.heading-within-5",
@@ -281,8 +286,8 @@ export const RULES = [
       requiredLine: DECISION_HEADING,
       stopRe: /^##\s/,
     }),
-    message: (s, r) =>
-      `decision-block: ${s.path}:${r.lineNo} entry lacks leading '### Decision'`,
+    message: () => "Entry lacks leading '### Decision'",
+    hint: "open each '## YYYY-MM-DD' entry with a '### Decision' subheading; use `bunx fit-wiki log decision` to do this mechanically",
   },
 
   // -- Weekly logs (sealed parts) --
@@ -292,23 +297,24 @@ export const RULES = [
     scope: "weekly-log-part",
     severity: "fail",
     check: firstLineMatches(WEEKLY_LOG_H1_RE),
-    message: (s) => `weekly-log: ${s.path} missing valid H1 heading`,
+    message: () => "Missing valid H1 heading",
+    hint: "set the H1 to '# <agent> — YYYY-Www (part N of M)'",
   },
   {
     id: "weekly-log-part.line-budget",
     scope: "weekly-log-part",
     severity: "fail",
     check: lineBudget(WEEKLY_LOG_LINE_BUDGET),
-    message: (s, r) =>
-      `weekly-log: ${s.path} has ${r.value} lines (limit ${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",
   },
   {
     id: "weekly-log-part.word-budget",
     scope: "weekly-log-part",
     severity: "fail",
     check: wordBudget(WEEKLY_LOG_WORD_BUDGET),
-    message: (s, r) =>
-      `weekly-log: ${s.path} has ${r.value} words (limit ${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",
   },
   {
     id: "weekly-log-part.h1-agent-matches-filename",
@@ -316,7 +322,8 @@ export const RULES = [
     severity: "fail",
     check: weeklyAgentMismatch,
     message: (s, r) =>
-      `weekly-log: ${s.path} H1 title slug '${r.titleSlug}' does not match filename prefix '${s.agentPrefix}'`,
+      `H1 title slug '${r.titleSlug}' does not match filename prefix '${s.agentPrefix}'`,
+    hint: "rename either the H1 or the file so they agree",
   },
 
   // -- MEMORY.md --
@@ -326,7 +333,8 @@ export const RULES = [
     scope: "memory",
     severity: "fail",
     check: exists,
-    message: (s) => `memory: ${s.path} not found`,
+    message: () => "MEMORY.md not found",
+    hint: "run `bunx fit-wiki init` to scaffold the canonical sections",
   },
   {
     id: "memory.priority-heading",
@@ -334,7 +342,8 @@ export const RULES = [
     severity: "fail",
     when: memoryExists,
     check: matches(PRIORITY_INDEX_HEADING_RE),
-    message: () => `memory: missing '${PRIORITY_INDEX_HEADING}' heading`,
+    message: () => `Missing '${PRIORITY_INDEX_HEADING}' heading`,
+    hint: "add the heading before the cross-cutting priorities table",
   },
   {
     id: "memory.priority-table-header",
@@ -342,7 +351,8 @@ export const RULES = [
     severity: "fail",
     when: memoryExists,
     check: matches(PRIORITY_HEADER_RE),
-    message: () => "memory: missing priority table header row",
+    message: () => "Missing priority table header row",
+    hint: "add '| Item | Agents | Owner | Status | Added |' under the priority heading",
   },
   {
     id: "memory.priority-separator-row",
@@ -350,8 +360,8 @@ export const RULES = [
     severity: "fail",
     when: memoryHasPriorityHeader,
     check: matches(PRIORITY_SEPARATOR_RE),
-    message: () =>
-      "memory: missing priority table separator row (| --- | --- | --- | --- | --- |)",
+    message: () => "Missing priority table separator row",
+    hint: "add '| --- | --- | --- | --- | --- |' directly below the header row",
   },
   {
     id: "memory.active-claims-table-header",
@@ -359,8 +369,8 @@ export const RULES = [
     severity: "fail",
     when: memoryHasClaimsHeading,
     check: matches(CLAIMS_HEADER_RE),
-    message: () =>
-      `active-claims: header mismatch (expected ${ACTIVE_CLAIMS_TABLE_HEADER})`,
+    message: () => `Active claims header mismatch`,
+    hint: `expected header row: '${ACTIVE_CLAIMS_TABLE_HEADER}'`,
   },
   {
     id: "memory.active-claims-separator-row",
@@ -368,8 +378,8 @@ export const RULES = [
     severity: "fail",
     when: memoryHasClaimsHeader,
     check: matches(CLAIMS_SEPARATOR_RE),
-    message: () =>
-      "active-claims: missing separator row (| --- | --- | --- | --- | --- | --- |)",
+    message: () => "Missing active-claims separator row",
+    hint: "add '| --- | --- | --- | --- | --- | --- |' directly below the claims header",
   },
 
   // -- Table rows --
@@ -379,32 +389,32 @@ export const RULES = [
     scope: "priority-row",
     severity: "fail",
     check: columnCount(5),
-    message: (s, r) =>
-      `priority-row: row at line ${s.lineNo} has ${r.actual} cells (expected ${r.expected})`,
+    message: (_s, r) => `${r.actual} cells (expected ${r.expected})`,
+    hint: "every priority row needs 5 cells: Item, Agents, Owner, Status, Added",
   },
   {
     id: "claims-row.claimed-at-format",
     scope: "claims-row",
     severity: "fail",
     check: fieldMatches("claimed_at", ISO_DATE_RE),
-    message: (s, r) =>
-      `active-claims: bad claimed_at '${r.value}' for ${s.agent}/${s.target}`,
+    message: (s, r) => `Bad claimed_at '${r.value}' for ${s.agent}/${s.target}`,
+    hint: "claimed_at must be ISO YYYY-MM-DD",
   },
   {
     id: "claims-row.expires-at-format",
     scope: "claims-row",
     severity: "fail",
     check: fieldMatches("expires_at", ISO_DATE_RE),
-    message: (s, r) =>
-      `active-claims: bad expires_at '${r.value}' for ${s.agent}/${s.target}`,
+    message: (s, r) => `Bad expires_at '${r.value}' for ${s.agent}/${s.target}`,
+    hint: "expires_at must be ISO YYYY-MM-DD",
   },
   {
     id: "expired-claim",
     scope: "claims-row",
     severity: "warn",
     check: expired,
-    message: (s) =>
-      `expired-claim: ${s.agent}/${s.target} expired ${s.expires_at}`,
+    message: (s) => `${s.agent}/${s.target} expired ${s.expires_at}`,
+    hint: "run `bunx fit-wiki release --expired` to clear expired claims",
   },
 
   // -- Storyboards --
@@ -414,8 +424,8 @@ export const RULES = [
     scope: "storyboard",
     severity: "fail",
     check: exists,
-    message: (s) =>
-      `storyboard: ${s.path} (current month ${s.yearMonth}) not found`,
+    message: (s) => `Current-month storyboard (${s.yearMonth}) not found`,
+    hint: "create it from `.claude/skills/kata-session/references/storyboard-template.md`",
   },
   {
     id: "storyboard.agent-h3-required",
@@ -423,7 +433,8 @@ export const RULES = [
     severity: "fail",
     when: storyboardExists,
     check: allRequiredLines(AGENT_H3_REQUIREMENTS),
-    message: (s, r) => `storyboard: ${s.path} missing '### ${r.label}' H3`,
+    message: (_s, r) => `Missing '### ${r.label}' H3`,
+    hint: "every domain agent gets an H3 under '## Current Condition'",
   },
   {
     id: "storyboard.line-budget",
@@ -431,8 +442,8 @@ export const RULES = [
     severity: "fail",
     when: storyboardExists,
     check: lineBudget(STORYBOARD_LINE_BUDGET),
-    message: (s, r) =>
-      `storyboard: ${s.path} has ${r.value} lines (limit ${STORYBOARD_LINE_BUDGET})`,
+    message: (_s, r) => `${r.value} lines (limit ${STORYBOARD_LINE_BUDGET})`,
+    hint: "see per-section word budgets in storyboard-template.md; retire prior-session Headlines/Notes/Next-review entries to weekly logs",
   },
   {
     id: "storyboard.word-budget",
@@ -440,8 +451,8 @@ export const RULES = [
     severity: "fail",
     when: storyboardExists,
     check: wordBudget(STORYBOARD_WORD_BUDGET),
-    message: (s, r) =>
-      `storyboard: ${s.path} has ${r.value} words (limit ${STORYBOARD_WORD_BUDGET})`,
+    message: (_s, r) => `${r.value} words (limit ${STORYBOARD_WORD_BUDGET})`,
+    hint: "see per-section word budgets in storyboard-template.md; retire prior-session Headlines/Notes/Next-review entries to weekly logs",
   },
   {
     id: "storyboard.markers-balanced.xmr",
@@ -453,8 +464,9 @@ export const RULES = [
       closeRe: XMR_CLOSE_RE,
       label: "xmr",
     }),
-    message: (s, r) =>
-      `storyboard: ${s.path}:${r.lineNo} ${r.reason} xmr marker${r.label ? ` (${r.label})` : ""}`,
+    message: (_s, r) =>
+      `${r.reason} xmr marker${r.label ? ` (${r.label})` : ""}`,
+    hint: "every '<!-- xmr:metric:csv -->' needs a matching '<!-- /xmr -->'",
   },
   {
     id: "storyboard.markers-balanced.issues",
@@ -466,8 +478,9 @@ export const RULES = [
       closeRe: ISSUE_CLOSE_RE,
       label: "issue-list",
     }),
-    message: (s, r) =>
-      `storyboard: ${s.path}:${r.lineNo} ${r.reason} issue-list marker${r.label ? ` (${r.label})` : ""}`,
+    message: (_s, r) =>
+      `${r.reason} issue-list marker${r.label ? ` (${r.label})` : ""}`,
+    hint: "every '<!-- obstacles:* -->' or '<!-- experiments:* -->' needs a matching close marker",
   },
 
   // -- Stray files --
@@ -477,7 +490,7 @@ export const RULES = [
     scope: "stray-file",
     severity: "fail",
     check: always,
-    message: (s) =>
-      `stray-file: ${s.path} does not match any known scope (summary, weekly log, or excluded prefix)`,
+    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

@@ -161,8 +161,12 @@ const SCOPE_RESOLVERS = {
   "weekly-log-part": (ctx) => ctx.subjects["weekly-log-part"],
   memory: (ctx) => [ctx.memory],
   "claims-row": (ctx) =>
-    parseClaims(ctx.memory.text).map((c) => ({ path: null, ...c })),
-  "priority-row": (ctx) => parsePriorityRows(ctx.memory.text),
+    parseClaims(ctx.memory.text).map((c) => ({ ...c, path: ctx.memory.path })),
+  "priority-row": (ctx) =>
+    parsePriorityRows(ctx.memory.text).map((r) => ({
+      ...r,
+      path: ctx.memory.path,
+    })),
   storyboard: (ctx) => [ctx.storyboard],
   "stray-file": (ctx) => ctx.subjects.stray,
 };

package/src/commands/audit.js

@@ -1,10 +1,13 @@
 import fsAsync from "node:fs/promises";
 import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
-import { runAudit } from "../audit/engine.js";
+import {
+  Finder,
+  emitFindingsJson,
+  emitFindingsText,
+  runRules,
+} from "@forwardimpact/libutil";
 import { RULES } from "../audit/rules.js";
-import { buildContext } from "../audit/scopes.js";
-import { emitJson, emitText } from "../audit/format.js";
+import { buildContext, resolveScope } from "../audit/scopes.js";
 
 /** Run the wiki audit and emit findings. JSON via --format json. */
 export function runAuditCommand(values, _args, _cli) {
@@ -14,10 +17,15 @@ export function runAuditCommand(values, _args, _cli) {
   const today = values.today || new Date().toISOString().slice(0, 10);
 
   const ctx = buildContext({ wikiRoot, today });
-  const findings = runAudit(RULES, ctx);
+  const findings = runRules(RULES, ctx, { resolveScope });
 
   process.stdout.write(
-    values.format === "json" ? emitJson(findings) : emitText(findings),
+    values.format === "json"
+      ? emitFindingsJson(findings)
+      : emitFindingsText(findings, {
+          cwd: projectRoot,
+          passMessage: "wiki audit passed",
+        }),
   );
 
   if (findings.some((f) => f.level === "fail")) process.exit(1);

package/src/index.js

@@ -35,5 +35,5 @@ export {
   appendEntry,
 } from "./weekly-log.js";
 export { buildDigest } from "./boot.js";
-export { runAudit } from "./audit/engine.js";
 export { RULES } from "./audit/rules.js";
+export { resolveScope as resolveAuditScope } from "./audit/scopes.js";

package/src/audit/engine.js

@@ -1,36 +0,0 @@
-import { resolveScope } from "./scopes.js";
-
-function groupByScope(rules) {
-  const groups = new Map();
-  for (const rule of rules) {
-    if (!groups.has(rule.scope)) groups.set(rule.scope, []);
-    groups.get(rule.scope).push(rule);
-  }
-  return groups;
-}
-
-function applyRule(rule, subject, ctx) {
-  if (rule.when && !rule.when(subject, ctx)) return [];
-  const result = rule.check(subject, ctx);
-  if (result == null) return [];
-  const items = Array.isArray(result) ? result : [result];
-  return items.map((item) => ({
-    id: rule.id,
-    level: rule.severity,
-    path: subject.path ?? null,
-    message: rule.message(subject, item, ctx),
-  }));
-}
-
-/** Apply the declarative rule catalogue to the wiki context. */
-export function runAudit(rules, ctx) {
-  const findings = [];
-  for (const [scopeKey, scopeRules] of groupByScope(rules)) {
-    for (const subject of resolveScope(scopeKey, ctx)) {
-      for (const rule of scopeRules) {
-        findings.push(...applyRule(rule, subject, ctx));
-      }
-    }
-  }
-  return findings;
-}

package/src/audit/format.js

@@ -1,39 +0,0 @@
-function partition(findings) {
-  const failures = [];
-  const warnings = [];
-  for (const f of findings) {
-    if (f.level === "warn") warnings.push(f);
-    else failures.push(f);
-  }
-  return { failures, warnings };
-}
-
-/** Render findings as `WARN`/`FAIL` lines followed by a `RESULT:` trailer. */
-export function emitText(findings) {
-  const { failures, warnings } = partition(findings);
-  const lines = [];
-  for (const w of warnings) lines.push(`WARN ${w.message}`);
-  for (const f of failures) lines.push(`FAIL ${f.message}`);
-  lines.push(
-    failures.length === 0
-      ? "RESULT: pass"
-      : `RESULT: fail (${failures.length} checks failed)`,
-  );
-  return lines.join("\n") + "\n";
-}
-
-/** Render findings as a JSON document. */
-export function emitJson(findings) {
-  const { failures, warnings } = partition(findings);
-  return (
-    JSON.stringify(
-      {
-        result: failures.length === 0 ? "pass" : "fail",
-        failures,
-        warnings,
-      },
-      null,
-      2,
-    ) + "\n"
-  );
-}