@forwardimpact/libwiki 0.2.25 → 0.2.27

package/src/commands/sync.js

@@ -1,29 +1,53 @@
 import { createLogger } from "@forwardimpact/libtelemetry";
-import { WikiPullConflict } from "../wiki-sync.js";
+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) {
       createLogger("wiki", runtime).error(
@@ -34,4 +58,28 @@ export async function runPullCommand(ctx) {
     }
     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,

package/src/integrity.js

@@ -0,0 +1,288 @@
+import { isoTimestamp } from "@forwardimpact/libutil";
+import { SESSION_GAP_MS } from "./constants.js";
+import { isLaneFile, enumerateLaneFiles } from "./lane-files.js";
+
+/**
+ * Normalize a content line for content-keyed presence: strip a trailing CR and
+ * trailing whitespace. Blank lines normalize to "" and are dropped by callers.
+ * @param {string} line
+ * @returns {string}
+ */
+export function normLine(line) {
+  return line.replace(/\r$/, "").replace(/\s+$/, "");
+}
+
+/**
+ * Parse `git diff --unified=0` text into per-file change records, attributing
+ * each `+`/`-` line to the file named by the most recent `+++ b/<path>` header.
+ * The `+++`/`---`/`@@` framing lines are not content. `/dev/null` targets
+ * (pure deletions) are kept as the home for their removed lines.
+ * @param {string} diffText
+ * @returns {Array<{home: string, added: string[], removed: string[]}>}
+ */
+export function parseDiff(diffText) {
+  const byHome = new Map();
+  let home = null;
+  for (const raw of diffText.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      home = stripDiffTarget(raw.slice(4));
+      continue;
+    }
+    if (home === null || isDiffFraming(raw)) continue;
+    const rec = byHome.get(home) ?? { home, added: [], removed: [] };
+    if (raw.startsWith("+")) rec.added.push(raw.slice(1));
+    else if (raw.startsWith("-")) rec.removed.push(raw.slice(1));
+    else continue;
+    byHome.set(home, rec);
+  }
+  return [...byHome.values()];
+}
+
+/** Whether a diff line is framing (`---`, `@@`, `diff`, `index`) rather than content. */
+function isDiffFraming(raw) {
+  return (
+    raw.startsWith("--- ") ||
+    raw.startsWith("@@") ||
+    raw.startsWith("diff ") ||
+    raw.startsWith("index ")
+  );
+}
+
+/** Strip a diff target's `a/`/`b/` prefix; `/dev/null` stays as-is. */
+function stripDiffTarget(target) {
+  const t = target.trim();
+  if (t === "/dev/null") return t;
+  return t.replace(/^[ab]\//, "");
+}
+
+/**
+ * Compose a window of change records (oldest→newest) into the surviving
+ * addition assertions, then return those absent from the tip. Content-keyed on
+ * `norm(line)`: a later own-lane deletion of an earlier-added line cancels its
+ * assertion (additions-only, own-deletions cancel). A surviving assertion is
+ * present iff its normalized line appears anywhere in `tipText`.
+ *
+ * @param {Array<{home: string, added: string[], removed: string[]}>} changes
+ *   Window changes, oldest→newest.
+ * @param {string} tipText - Concatenated text of the tip's in-scope files.
+ * @param {(line: string) => string} norm - Line normalizer.
+ * @returns {Array<{contentId: string, pushHome: string}>} Absent assertions.
+ */
+export function findAbsent(changes, tipText, norm) {
+  const asserted = composeAssertions(changes, norm);
+  const present = normalizedKeySet(tipText, norm);
+  const absent = [];
+  for (const [key, a] of asserted) {
+    if (!present.has(key)) absent.push(a);
+  }
+  return absent;
+}
+
+/** Compose window changes into surviving additions; a later removal cancels its key. */
+function composeAssertions(changes, norm) {
+  const asserted = new Map(); // norm(line) -> { contentId, pushHome }
+  for (const change of changes) {
+    for (const line of change.added) {
+      const key = norm(line);
+      if (key !== "" && !asserted.has(key)) {
+        asserted.set(key, { contentId: key, pushHome: change.home });
+      }
+    }
+    for (const line of change.removed) {
+      const key = norm(line);
+      if (key !== "") asserted.delete(key);
+    }
+  }
+  return asserted;
+}
+
+/** The set of non-blank normalized lines in `text`. */
+function normalizedKeySet(text, norm) {
+  const set = new Set();
+  for (const line of text.split("\n")) {
+    const key = norm(line);
+    if (key !== "") set.add(key);
+  }
+  return set;
+}
+
+/**
+ * Resolve the previous-session push set from lane-authored commits (newest
+ * first) by idle-gap. Tier 2 runs at boot before the current session has
+ * pushed, so the most recent contiguous run is the previous session. Vacuous
+ * only for empty history; the degenerate (content-unresolvable) case is raised
+ * by {@link sweepTier2}, not here.
+ *
+ * @param {Array<{sha: string, when: number}>} commits - Newest first.
+ * @param {number} gapMs - Idle-gap threshold (ms).
+ * @returns {{kind: "vacuous"} | {kind: "window", commits: Array<{sha: string, when: number}>}}
+ */
+export function previousSessionWindow(commits, gapMs) {
+  if (commits.length === 0) return { kind: "vacuous" };
+  const tipRun = [commits[0]];
+  for (let i = 1; i < commits.length; i++) {
+    // commits are newest-first; `when` is seconds, gap threshold is ms.
+    const gap = (commits[i - 1].when - commits[i].when) * 1000;
+    if (gap > gapMs) break;
+    tipRun.push(commits[i]);
+  }
+  return { kind: "window", commits: tipRun };
+}
+
+/**
+ * Build a detection record. `detectedAt` is the binding wall-clock stamp (ISO);
+ * an exposure figure derived from commit timestamps carries the labeled
+ * `commit-timestamp` fallback basis.
+ *
+ * @param {object} d
+ * @param {1|2} d.tier
+ * @param {string} d.contentId - The absent content's identity (normalized line).
+ * @param {string} d.pushHome - The content's push-time home path.
+ * @param {number|Date} d.now - Wall-clock (e.g. `runtime.clock.now()` ms).
+ * @param {number} [d.exposureSeconds] - Commit-timestamp-derived exposure.
+ * @returns {object}
+ */
+export function makeDetection({
+  tier,
+  contentId,
+  pushHome,
+  now,
+  exposureSeconds,
+}) {
+  const detection = {
+    tier,
+    contentId,
+    pushHome,
+    detectedAt: isoTimestamp(now),
+  };
+  if (exposureSeconds != null) {
+    detection.exposure = {
+      seconds: exposureSeconds,
+      basis: "commit-timestamp",
+    };
+  }
+  return detection;
+}
+
+/**
+ * Render detections to flow output text. Empty input renders the empty string
+ * (clean-path silence). One line per detection naming tier, push-time home, and
+ * content identity; exposure (when present) is labeled with its fallback basis.
+ * @param {object[]} detections
+ * @returns {string}
+ */
+export function renderDetections(detections) {
+  if (detections.length === 0) return "";
+  return (
+    detections
+      .map((d) => {
+        const exposure = d.exposure
+          ? ` exposure=${d.exposure.seconds}s (basis: ${d.exposure.basis})`
+          : "";
+        return `integrity[tier ${d.tier}]: absent content in ${d.pushHome} — "${d.contentId}" detected ${d.detectedAt}${exposure}`;
+      })
+      .join("\n") + "\n"
+  );
+}
+
+/**
+ * Tier-2 boot sweep: verify the lane's previous-session push set is still
+ * content-present at the fetched (rebased) origin tip, returning detections for
+ * any absence. Reads git and lane files from `wikiDir` (the rebased tree).
+ * Never writes, never throws into the flow (the caller wraps it).
+ *
+ * @param {object} ctx
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} ctx.runtime
+ * @param {import('@forwardimpact/libutil').GitClient} ctx.gitClient
+ * @param {string} ctx.wikiDir - The wiki clone dir (git cwd and fs read-root).
+ * @param {string} ctx.agent - Lane agent id.
+ * @param {number} ctx.now - Wall-clock (ms).
+ * @returns {Promise<object[]>} Detections (possibly empty).
+ */
+export async function sweepTier2({ runtime, gitClient, wikiDir, agent, now }) {
+  const email = await gitClient.configGet("user.email", { cwd: wikiDir });
+  if (!email) {
+    // Lane identity unresolvable — never a silent vacuous pass.
+    return [
+      makeDetection({
+        tier: 2,
+        contentId: "<unresolvable: no author identity>",
+        pushHome: "-",
+        now,
+      }),
+    ];
+  }
+  const commits = await gitClient.logByAuthor(email, {
+    cwd: wikiDir,
+    ref: "HEAD",
+  });
+  const window = previousSessionWindow(commits, SESSION_GAP_MS);
+  if (window.kind === "vacuous") return [];
+
+  const detections = [];
+  const changes = [];
+  // Oldest→newest so own-deletion cancellation composes in commit order.
+  const ordered = [...window.commits].reverse();
+  for (const commit of ordered) {
+    const diff = await gitClient.diffRange(`${commit.sha}~1 ${commit.sha}`, {
+      cwd: wikiDir,
+    });
+    if (diff === null) {
+      detections.push(
+        makeDetection({
+          tier: 2,
+          contentId: `<unresolvable content: ${commit.sha}>`,
+          pushHome: "-",
+          now,
+        }),
+      );
+      continue;
+    }
+    for (const rec of parseDiff(diff)) {
+      if (isLaneFile(rec.home, agent))
+        changes.push({ ...rec, when: commit.when });
+    }
+  }
+
+  const tipText = enumerateLaneFiles(wikiDir, agent, runtime.fsSync)
+    .map((rel) => readFileOrEmpty(runtime.fsSync, wikiDir, rel))
+    .join("\n");
+
+  for (const absent of findAbsent(changes, tipText, normLine)) {
+    // Exposure runs from the LAST window commit that added this exact line
+    // (its most recent assertion at origin), not merely a same-home commit.
+    const when = lastAssertionTime(changes, absent.contentId);
+    const exposureSeconds =
+      when != null ? Math.round(now / 1000 - when) : undefined;
+    detections.push(
+      makeDetection({
+        tier: 2,
+        contentId: absent.contentId,
+        pushHome: absent.pushHome,
+        now,
+        exposureSeconds,
+      }),
+    );
+  }
+  return detections;
+}
+
+/** The `when` of the latest window change whose normalized additions include `contentId`. */
+function lastAssertionTime(changes, contentId) {
+  let when;
+  for (const change of changes) {
+    if (change.added.some((line) => normLine(line) === contentId)) {
+      when = change.when;
+    }
+  }
+  return when;
+}
+
+function readFileOrEmpty(fsSync, wikiDir, rel) {
+  const abs = `${wikiDir}/${rel}`;
+  try {
+    return fsSync.readFileSync(abs, "utf-8");
+  } catch {
+    return "";
+  }
+}

package/src/lane-files.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { WEEKLY_LOG_NAME_RE, WEEKLY_LOG_PART_NAME_RE } from "./constants.js";
+
+const METRICS_CSV_RE = /^metrics\/[^/]+\/\d{4}\.csv$/;
+
+/**
+ * Whether a wiki-root-relative path is one of the lane's own files: the
+ * agent's summary (`<agent>.md`), a weekly log or sealed part
+ * (`<agent>-YYYY-Www.md`, `<agent>-YYYY-Www-partN.md`, matched on the captured
+ * agent token), or a metrics CSV (`metrics/<skill>/<year>.csv`). Metrics CSVs
+ * match by path for every agent; lane ownership of a metrics CSV is enforced by
+ * the tier-2 sweep's author filter at the commit level, not here.
+ *
+ * @param {string} relPath - Path relative to the wiki root (POSIX or native).
+ * @param {string} agent - Agent profile id (e.g. "staff-engineer").
+ * @returns {boolean}
+ */
+export function isLaneFile(relPath, agent) {
+  const rel = relPath.replace(/\\/g, "/");
+  const base = path.posix.basename(rel);
+  if (base === `${agent}.md`) return true;
+  for (const re of [WEEKLY_LOG_NAME_RE, WEEKLY_LOG_PART_NAME_RE]) {
+    const m = base.match(re);
+    if (m && m[1] === agent) return true;
+  }
+  return METRICS_CSV_RE.test(rel);
+}
+
+/**
+ * Enumerate the lane's own files present under `wikiRoot`: matching top-level
+ * summary and weekly-log files, plus every `metrics/<skill>/<year>.csv`.
+ * Returns wiki-root-relative POSIX paths.
+ *
+ * @param {string} wikiRoot
+ * @param {string} agent
+ * @param {object} fsSync - Sync filesystem surface (`runtime.fsSync`).
+ * @returns {string[]} Relative paths, in directory-read order.
+ */
+export function enumerateLaneFiles(wikiRoot, agent, fsSync) {
+  const out = [];
+  for (const entry of fsSync.readdirSync(wikiRoot)) {
+    if (entry !== "metrics" && isLaneFile(entry, agent)) out.push(entry);
+  }
+  out.push(...enumerateMetricsCsvs(wikiRoot, agent, fsSync));
+  return out;
+}
+
+/** Wiki-root-relative `metrics/<skill>/<year>.csv` paths matching the lane. */
+function enumerateMetricsCsvs(wikiRoot, agent, fsSync) {
+  const metricsDir = path.join(wikiRoot, "metrics");
+  if (!fsSync.existsSync(metricsDir)) return [];
+  const found = [];
+  for (const skill of fsSync.readdirSync(metricsDir)) {
+    const skillDir = path.join(metricsDir, skill);
+    if (!fsSync.statSync(skillDir).isDirectory()) continue;
+    for (const file of fsSync.readdirSync(skillDir)) {
+      const rel = `metrics/${skill}/${file}`;
+      if (isLaneFile(rel, agent)) found.push(rel);
+    }
+  }
+  return found;
+}

package/src/marker-scanner.js

@@ -20,6 +20,7 @@ function tryOpen(line, i) {
       kind: "xmr",
       metric: xmrMatch[1],
       csvPath: xmrMatch[2],
+      priorReadAnchor: xmrMatch[3] || null,
       openLine: i,
     };
   }
@@ -42,6 +43,7 @@ function closePair(open, i) {
       kind: "xmr",
       metric: open.metric,
       csvPath: open.csvPath,
+      priorReadAnchor: open.priorReadAnchor,
       openLine: open.openLine,
       closeLine: i,
     };