@forwardimpact/libwiki 0.2.24 → 0.2.26

package/src/commands/refresh.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { scanMarkers } from "../marker-scanner.js";
 import { renderBlock, BlockRenderError } from "../block-renderer.js";
@@ -26,6 +27,7 @@ async function renderForBlock(block, projectRoot, ghContext, runtime) {
     return renderBlock({
       metric: block.metric,
       csvPath: block.csvPath,
+      priorReadAnchor: block.priorReadAnchor,
       projectRoot,
       fs: runtime.fsSync,
     });
@@ -69,6 +71,7 @@ function readStoryboardOrNull(runtime, storyboardPath) {
 export async function runRefreshCommand(ctx) {
   const { runtime, gitClient } = ctx.deps;
   const options = ctx.options;
+  const logger = createLogger("wiki", runtime);
   const projectRoot = resolveProjectRoot(runtime);
 
   const storyboardPath = path.resolve(
@@ -77,11 +80,11 @@ export async function runRefreshCommand(ctx) {
   );
   const text = readStoryboardOrNull(runtime, storyboardPath);
   if (text === null) {
-    runtime.proc.stderr.write(`refresh: no storyboard at ${storyboardPath}\n`);
+    logger.warn("refresh", `no storyboard at ${storyboardPath}`);
     return { ok: true };
   }
   const blocks = scanMarkers(text, {
-    warn: (message) => runtime.proc.stderr.write(message),
+    warn: (message) => logger.warn("refresh", message),
   });
   if (blocks.length === 0) return { ok: true };
 
@@ -122,8 +125,9 @@ export async function runRefreshCommand(ctx) {
       spliced = true;
     } catch (err) {
       if (!(err instanceof BlockRenderError)) throw err;
-      runtime.proc.stderr.write(
-        `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}\n`,
+      logger.error(
+        "refresh",
+        `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}`,
       );
     }
   }

package/src/commands/rotate.js

@@ -1,24 +1,28 @@
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { rotateIfOverBudget, weeklyLogPath } from "../weekly-log.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
-/** Force-rotate the current weekly log to a sealed part file. */
+/**
+ * Rotate the current weekly log to a sealed part file. Refuses an under-budget
+ * target (exit 2) unless `--force`; the header-only floor stays a zero-exit
+ * no-op even under `--force`; a missing target exits 2.
+ */
 export function runRotateCommand(ctx) {
   const { runtime } = ctx.deps;
+  const logger = createLogger("wiki", runtime);
   const options = ctx.options;
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    return {
-      ok: false,
-      code: 2,
-      error: "rotate requires --agent or LIBEVAL_AGENT_PROFILE",
-    };
-  }
+  const resolved = requireAgentFlag(options, {
+    command: "rotate",
+    example: "fit-wiki rotate --agent staff-engineer",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
   const wikiRoot = resolveWikiRoot(runtime, options);
   const today = options.today || currentDayIso(runtime);
   // Name the resolved target before any seal: the file follows from agent +
-  // current week, not from any audit finding, so an env-default agent can
-  // silently select a different file than the one the operator has in mind.
+  // current week, not from any audit finding.
   runtime.proc.stdout.write(
     `target → ${weeklyLogPath(wikiRoot, agent, today)}\n`,
   );
@@ -29,18 +33,37 @@ export function runRotateCommand(ctx) {
       wikiRoot,
       agent,
       today,
-      0,
-      { force: true },
+      { lines: 0, words: 0 },
+      { force: Boolean(options.force) },
       runtime.fsSync,
     );
   } catch (e) {
-    runtime.proc.stderr.write(`rotate failed: ${e.message}\n`);
+    logger.error("rotate", `rotate failed: ${e.message}`);
     return { ok: false, code: 1 };
   }
   switch (result.status) {
     case "noop":
-      runtime.proc.stdout.write(`no rotation needed for ${agent}\n`);
-      return { ok: true };
+      // The header-only floor is a benign no-op; an under-budget or missing
+      // target fails closed so a stale/typo'd invocation cannot pass silently.
+      if (result.reason === "floor") {
+        runtime.proc.stdout.write(`no rotation needed for ${agent}\n`);
+        return { ok: true };
+      }
+      if (result.reason === "missing") {
+        return {
+          ok: false,
+          code: 2,
+          error: `no weekly log for ${agent} at ${result.fromPath}`,
+        };
+      }
+      return {
+        ok: false,
+        code: 2,
+        error:
+          `${result.fromPath} is under budget ` +
+          `(${result.lines} lines, ${result.words} words); ` +
+          `pass --force to seal it early`,
+      };
     case "sealed":
       for (const part of result.parts) {
         runtime.proc.stdout.write(`sealed → ${part}\n`);
@@ -51,12 +74,13 @@ export function runRotateCommand(ctx) {
         runtime.proc.stdout.write(`sealed → ${part}\n`);
       }
       const { section, lines, words, path: residuePath } = result.residue;
-      runtime.proc.stderr.write(
-        `day-section ${section} alone exceeds the budget ` +
-          `(${lines} lines, ${words} words) and cannot be split at a day ` +
-          `seam: ${residuePath}\n` +
-          `recover it by hand — bisect the section at a finer seam ` +
-          `(see the memory protocol's manual-recovery convention)\n`,
+      logger.error(
+        "rotate",
+        `section ${section} alone exceeds the budget ` +
+          `(${lines} lines, ${words} words) and has no finer seam to split ` +
+          `at: ${residuePath}\n` +
+          `recover it by hand — shorten the section ` +
+          `(see the memory protocol's manual-recovery convention)`,
       );
       return { ok: false, code: 1 };
     }

package/src/commands/sync.js

@@ -1,35 +1,85 @@
-import { WikiPullConflict } from "../wiki-sync.js";
+import { createLogger } from "@forwardimpact/libtelemetry";
+import { refusalEnvelope } from "../secret-gate.js";
+import { AncestryRefusal, WikiPullConflict } from "../wiki-sync.js";
+import { sweepTier2, renderDetections } from "../integrity.js";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
 
-/** Commit all wiki changes and push them to the remote wiki repository. */
+/**
+ * Commit all wiki changes and push them through the secret-gated push path.
+ * A detected secret or unavailable scanner fails the command closed and names
+ * the cause on stderr without attempting the push; a clean write pushes or
+ * reports nothing to push. The post-push tier-1 integrity detections surface in
+ * the output; they never gate the push.
+ */
 export async function runPushCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   await wikiSync.inheritIdentity();
 
-  const result = await wikiSync.commitAndPush("wiki: update from session");
+  let result;
+  try {
+    result = await wikiSync.commitAndPush("wiki: update from session");
+  } catch (err) {
+    if (err instanceof AncestryRefusal) {
+      runtime.proc.stderr.write(`${err.message}\n`);
+      return { ok: false, code: 1 };
+    }
+    throw err;
+  }
+  // Fail the command closed on a secret-gate refusal (secret detected or scanner
+  // unavailable); a clean push falls through to the normal reporting below.
+  const refusal = refusalEnvelope(runtime, result);
+  if (refusal) return refusal;
   if (result.pushed) {
     runtime.proc.stdout.write("push: committed and pushed\n");
   } else {
     runtime.proc.stdout.write("push: nothing to push\n");
   }
+  if (result.detections?.length) {
+    runtime.proc.stdout.write(renderDetections(result.detections));
+  }
   return { ok: true };
 }
 
-/** Fetch and rebase the local wiki on origin/master; on rebase conflict, return a non-zero envelope with a message to resolve manually or push first. */
+/** Fetch and rebase the local wiki on origin/master; on rebase conflict, return a non-zero envelope with a message to resolve manually or push first. After a clean pull, the tier-2 lane-record sweep surfaces any previous-session content absent at the fetched tip; it never gates the boot. */
 export async function runPullCommand(ctx) {
-  const { runtime, wikiSync } = ctx.deps;
+  const { runtime, wikiSync, gitClient } = ctx.deps;
   await wikiSync.inheritIdentity();
 
   try {
     await wikiSync.pull();
     runtime.proc.stdout.write("pull: up to date\n");
-    return { ok: true };
   } catch (err) {
     if (err instanceof WikiPullConflict) {
-      runtime.proc.stderr.write(
-        "fit-wiki pull: rebase conflict — local divergence detected; resolve manually or push first\n",
+      createLogger("wiki", runtime).error(
+        "pull",
+        "rebase conflict — local divergence detected; resolve manually or push first",
       );
       return { ok: false, code: 1 };
     }
     throw err;
   }
+
+  // Tier-2 sweep on the just-rebased tree. Detection-only: any failure degrades
+  // to no detections, never throws into the flow, never changes the exit code.
+  try {
+    const wikiDir = resolveWikiRoot(runtime, ctx.options);
+    // `--today` (ISO date) overrides the wall clock for deterministic tests;
+    // a malformed value falls back to the runtime clock rather than NaN.
+    const today = ctx.options.today
+      ? Date.parse(ctx.options.today)
+      : Number.NaN;
+    const now = Number.isNaN(today) ? runtime.clock.now() : today;
+    const detections = await sweepTier2({
+      runtime,
+      gitClient,
+      wikiDir,
+      agent: ctx.options.agent,
+      now,
+    });
+    if (detections.length)
+      runtime.proc.stdout.write(renderDetections(detections));
+  } catch {
+    // Detection-only instrument: a sweep error never gates the boot flow.
+  }
+  return { ok: true };
 }

package/src/conflict-markers.js

@@ -0,0 +1,78 @@
+// Structural detector for unresolved git conflict markers, shared by the wiki
+// audit's `conflict.markers` rule (audit/conflict-markers-rule.js) and the
+// WikiSync pre-push guard (wiki-sync.js). One home so the two layers cannot
+// drift on what counts as a marker.
+//
+// Detection is line-anchored and structural, not a naive grep, so it does not
+// fire on markers legitimately quoted in prose:
+//
+// - Open (`<<<<<<<`) and close (`>>>>>>>`) marker lines fire UNCONDITIONALLY,
+//   per file. A seal rotation can sever one conflict block across two sealed
+//   files (the open in one, the separator + close in the other); a
+//   complete-in-file-block matcher would miss both, so each marker form stands
+//   alone. The single-space-or-end-of-line guard after the 7-char run admits
+//   the stash-pop label forms (`<<<<<<< Updated upstream`,
+//   `>>>>>>> Stashed changes`) and the branch/sha label forms while rejecting
+//   longer `<`/`>` runs.
+// - The separator (`=======`) fires ONLY while a conflict block is open in the
+//   same file (block-conditioned). A lone separator with no open above it is
+//   indistinguishable from a setext-heading underline and is a deliberate
+//   accepted non-detection.
+// - In a `fenceExempt` (prose) surface, occurrences inside a fenced code block
+//   are suppressed — a fence quotes content. Markers quoted in a backtick code
+//   SPAN are handled by the column-1 anchor itself: a span sits mid-line, so
+//   `^` never matches. STATUS.md and non-markdown push targets pass
+//   `fenceExempt:false`: their fenced rows are data, where a marker is never
+//   legitimate, so fence state never suppresses.
+
+const OPEN_RE = /^<{7}( |$)/;
+const CLOSE_RE = /^>{7}( |$)/;
+const SEPARATOR_RE = /^={7}\s*$/;
+// A fenced-code delimiter: three or more backticks or tildes, up to three
+// leading spaces of indentation (CommonMark). The info string after the run is
+// ignored — a delimiter line is never itself a marker.
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
+
+/**
+ * Scan `text` for unresolved git conflict markers.
+ *
+ * @param {string} text - The file (or diff-added) content to scan.
+ * @param {object} [options]
+ * @param {boolean} [options.fenceExempt=true] - When true, suppress markers
+ *   inside fenced code blocks (prose surfaces). When false, fence state never
+ *   suppresses (STATUS.md, non-markdown targets).
+ * @returns {Array<{lineNo: number, kind: "open"|"separator"|"close"}>}
+ *   One entry per detected marker line, in document order.
+ */
+export function scanConflictMarkers(text, { fenceExempt = true } = {}) {
+  const lines = text.split("\n");
+  const hits = [];
+  let insideFence = false;
+  let openDepth = 0;
+  for (let i = 0; i < lines.length; i++) {
+    // Strip a trailing CR so a CRLF checkout is matched identically to LF — a
+    // bare marker (`<<<<<<<\r`) would otherwise escape the `( |$)` anchor and
+    // a CRLF corruption block would publish undetected.
+    const line = lines[i].replace(/\r$/, "");
+    if (FENCE_RE.test(line)) {
+      insideFence = !insideFence;
+      continue;
+    }
+    if (fenceExempt && insideFence) continue;
+    const kind = classify(line, openDepth);
+    if (!kind) continue;
+    hits.push({ lineNo: i + 1, kind });
+    if (kind === "open") openDepth++;
+    else if (kind === "close" && openDepth > 0) openDepth--;
+  }
+  return hits;
+}
+
+// Classify a single line as a marker kind, or null. The separator is
+// block-conditioned: it only counts while a conflict block is open.
+function classify(line, openDepth) {
+  if (OPEN_RE.test(line)) return "open";
+  if (CLOSE_RE.test(line)) return "close";
+  if (openDepth > 0 && SEPARATOR_RE.test(line)) return "separator";
+  return null;
+}

package/src/constants.js

@@ -3,6 +3,21 @@ export const INBOX_HEADING = "## Message Inbox";
 export const BROADCAST_TARGET = "all";
 
 export const MEMORY_FILE = "MEMORY.md";
+
+// Row-structured singleton surfaces under the sync-merge discipline: when a
+// landing on one of these is contended, the resolution re-runs the row
+// operation against the fresh remote tip (rebase the operation, not the
+// lines), never a textual merge. Founding member: MEMORY.md (the Active Claims
+// table). STATUS.md phase rows join as their own re-apply operations land.
+// Metrics CSV appends take the complementary union-merge path below.
+export const SINGLETON_PATHS = new Set([MEMORY_FILE]);
+
+// The tracked `.gitattributes` declaration that makes concurrent appends to
+// metrics CSVs union-merge (keep both sides' rows) on every publish path,
+// instead of conflicting or side-picking. Carried by the wiki repo itself so
+// it governs every clone.
+export const GITATTRIBUTES_FILE = ".gitattributes";
+export const METRICS_CSV_MERGE_ATTRIBUTE = "metrics/**/*.csv merge=union";
 export const ACTIVE_CLAIMS_HEADING = "## Active Claims";
 export const ACTIVE_CLAIMS_TABLE_HEADER =
   "| agent | target | branch | pr | claimed_at | expires_at |";
@@ -53,12 +68,27 @@ export const WEEKLY_LOG_NAME_RE = /^([a-z][a-z-]*)-(\d{4})-W(\d{2})\.md$/;
 export const WEEKLY_LOG_PART_NAME_RE =
   /^([a-z][a-z-]*)-(\d{4})-W(\d{2})-part\d+\.md$/;
 
+// Day-section seam: `## YYYY-MM-DD` at line start, a trailing suffix tolerated
+// (e.g. `## 2026-05-19 (third activation)`). One home so the rotation
+// seam-finder (weekly-log.js), the `log` command's last-entry probe
+// (commands/log.js), and the audit's heading-grammar-drift rule (audit/rules.js)
+// cannot disagree on what a conforming entry heading is. Source has no flags;
+// call sites add `g`/`m` as needed via `new RegExp(WEEKLY_LOG_SEAM_RE.source, …)`.
+export const WEEKLY_LOG_SEAM_RE = /^## (\d{4}-\d{2}-\d{2})/;
+
+// Tier-2 integrity sweep idle-gap: lane-authored commits separated by more
+// than this delimit sessions in the wiki history. 30 minutes.
+export const SESSION_GAP_MS = 30 * 60 * 1000;
+
 // Storyboard marker syntax. An open or close marker tolerates optional trailing
 // text after the tag (typically an inline "Do not edit. Generated from fit-wiki
 // refresh." notice). One home so the marker scanner (marker-scanner.js) and the
 // audit's balance check (audit/rules.js) cannot drift on the syntax.
+// Capture groups: 1 metric, 2 csvPath, 3 optional prior-read anchor date. The
+// `prior=YYYY-MM-DD` token sits before the trailing-text group so the "Do not
+// edit" notice is still tolerated and does not swallow the anchor.
 export const XMR_OPEN_RE =
-  /^<!--\s*xmr:([^:\s]+):(\S+)(?:\s+[^>]*?)?\s*-->\s*$/;
+  /^<!--\s*xmr:([^:\s]+):(\S+)(?:\s+prior=(\d{4}-\d{2}-\d{2}))?(?:\s+[^>]*?)?\s*-->\s*$/;
 export const XMR_CLOSE_RE = /^<!--\s*\/xmr(?:\s+[^>]*?)?\s*-->\s*$/;
 export const ISSUE_OPEN_RE =
   /^<!--\s*(obstacles|experiments):(open|closed)(?::(\d+d))?(?:\s+[^>]*?)?\s*-->\s*$/;

package/src/gitattributes.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import {
+  GITATTRIBUTES_FILE,
+  METRICS_CSV_MERGE_ATTRIBUTE,
+} from "./constants.js";
+
+/**
+ * Ensure the wiki's tracked `.gitattributes` declares the metrics-CSV union
+ * merge attribute (`metrics/**\/*.csv merge=union`), idempotently.
+ *
+ * Present-and-correct means no write: if the exact attribute line already
+ * appears in the file, the file is left byte-unchanged and `{ changed: false }`
+ * is returned. Otherwise the line is appended (preserving any existing
+ * `.gitattributes` content) or the file is created with just that line, and
+ * `{ changed: true }` is returned.
+ *
+ * The single union declaration governs every clone because it is a tracked
+ * worktree file; per-clone config (`core.attributesFile`, `.git/info/attributes`)
+ * would not propagate to the sibling sessions that cause the loss.
+ *
+ * @param {string} wikiDir - The wiki clone directory.
+ * @param {import('node:fs')} fsSync - Synchronous filesystem surface (`runtime.fsSync`).
+ * @returns {{ changed: boolean }}
+ */
+export function ensureMetricsCsvMergeAttribute(wikiDir, fsSync) {
+  const filePath = path.join(wikiDir, GITATTRIBUTES_FILE);
+  if (fsSync.existsSync(filePath)) {
+    const text = fsSync.readFileSync(filePath, "utf-8");
+    const present = text
+      .split("\n")
+      .some((line) => line.trim() === METRICS_CSV_MERGE_ATTRIBUTE);
+    if (present) return { changed: false };
+    // Append the line, keeping existing content and ending with a newline.
+    const base = text.endsWith("\n") || text === "" ? text : `${text}\n`;
+    fsSync.writeFileSync(filePath, `${base}${METRICS_CSV_MERGE_ATTRIBUTE}\n`);
+    return { changed: true };
+  }
+  fsSync.writeFileSync(filePath, `${METRICS_CSV_MERGE_ATTRIBUTE}\n`);
+  return { changed: true };
+}

package/src/index.js

@@ -18,9 +18,10 @@ export {
   SUMMARY_WORD_BUDGET,
 } from "./constants.js";
 export { scanMarkers } from "./marker-scanner.js";
+export { scanConflictMarkers } from "./conflict-markers.js";
 export { renderBlock } from "./block-renderer.js";
 export { renderIssueList } from "./issue-list-renderer.js";
-export { WikiSync, WikiPullConflict } from "./wiki-sync.js";
+export { WikiSync, WikiPullConflict, WikiSyncRefusal } from "./wiki-sync.js";
 export { listSkills } from "./skill-roster.js";
 export {
   parseClaims,