@nurix/etna 0.19.43 → 0.19.45

package/data/harnesses/code/hooks/compliance.mjs

@@ -0,0 +1,353 @@
+// harness/code/hooks/compliance.mjs — the gate-always-waivable hook module.
+// PreToolUse (Edit|Write|MultiEdit|Bash): deny what is never legitimate (frozen records, protected
+// files, plan-gate skips, changelog-less commits, off-catalog packages), ask where intent matters
+// (branches, live commands, test files mid-plan, off-map doc paths). Stop: block an arc that tries
+// to end with unresolved bookkeeping or an unrecorded plan completion. Every gate fails open — a
+// crash or unreadable repo allows the action; enforcement is never allowed to become an outage.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { readStdin, resolveProjectDir, frontmatter } from "./lib/ownership.mjs";
+import { readQueue, countRows, askedThisSession, recordAsked } from "./lib/state.mjs";
+import { frozenStatus } from "./lib/frozen.mjs";
+
+function readSafe(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+function relIfInside(projectDir, filePath) {
+  if (!filePath) return null;
+  const rel = path.relative(projectDir, path.resolve(projectDir, filePath));
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join("/");
+}
+
+function git(projectDir, args) {
+  const res = spawnSync("git", args, { cwd: projectDir, encoding: "utf8", timeout: 5000 });
+  return res.status === 0 ? (res.stdout || "").trim() : null;
+}
+
+function decision(permissionDecision, reason) {
+  return {
+    hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: reason },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PreToolUse — file gates
+// ---------------------------------------------------------------------------
+
+function protectedPaths(projectDir) {
+  const listFile = path.join(projectDir, "docs", "operations", "protected-files.md");
+  const paths = ["AGENTS.md", "docs/operations/protected-files.md"];
+  const text = readSafe(listFile);
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const candidate = m[1].trim();
+    if (candidate && !candidate.includes(" ")) paths.push(candidate.replace(/^\.\//, ""));
+  }
+  return paths;
+}
+
+// Open plans in the new format only (a `Gates:` line present). Plans without one are
+// legacy and pass every plan gate — otherwise every open plan bricks on harness upgrade.
+function openGatedPlans(projectDir) {
+  const dir = path.join(projectDir, "docs", "history", "plans");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch (e) {
+    return [];
+  }
+  const plans = [];
+  for (const file of entries) {
+    const text = readSafe(path.join(dir, file));
+    const status = (/^\*\*Status:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim();
+    if (!status || /Complete|Abandoned/.test(status)) continue;
+    const gates = (/^\*\*Gates:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim();
+    if (!gates) continue; // legacy tolerance
+    plans.push({ file, status, gates, hasLedger: /^##\s+Test Obligations\b/m.test(text) });
+  }
+  return plans;
+}
+
+const TEST_FILE_RE = /(^|\/)tests?\/|\.test\.|\.spec\./;
+const SOURCE_LIKE = /\.(m?[jt]sx?|py|rs|go|rb|java|kt|swift|c|h|cpp|hpp|cs|sh|sql|vue|svelte)$/;
+
+function fileGate(projectDir, rel, toolName) {
+  const frozen = frozenStatus(projectDir, rel);
+  if (frozen.frozen) {
+    return decision(
+      "deny",
+      `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}). A correction is a new dated entry that links back.`
+    );
+  }
+
+  if (protectedPaths(projectDir).includes(rel)) {
+    return decision("deny", `BLOCKED — protected file. \`${rel}\` is on the protected list.`);
+  }
+
+  const inDocs = rel.startsWith("docs/") || rel.startsWith(".claude/") || rel.endsWith(".md");
+  if (!inDocs && SOURCE_LIKE.test(rel)) {
+    for (const plan of openGatedPlans(projectDir)) {
+      if (/Boundary:\s*pending/i.test(plan.gates)) {
+        return decision(
+          "deny",
+          `BLOCKED — plan gate. \`${plan.file}\` is open but its Gates line reads 'Boundary: pending'. Run the \`boundary\` skill and record its verdict in the plan before implementation edits.`
+        );
+      }
+      if (!plan.hasLedger) {
+        return decision(
+          "deny",
+          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`test-plan\` skill; its ledger is what the verification gate discharges.`
+        );
+      }
+    }
+  }
+
+  if (toolName === "Write" && TEST_FILE_RE.test(rel)) {
+    const midPlan = openGatedPlans(projectDir).some((p) => /In Progress/i.test(p.status));
+    if (midPlan) {
+      return decision(
+        "ask",
+        "Create a test file mid-plan? Plan builds defer tests to the verification gate — proceed only if this is a bug-fix regression test (fails before the fix, passes after)."
+      );
+    }
+  }
+
+  // Doc placement is never an interruption: an off-map docs/ folder is detected silently by
+  // the awareness module (a `doc-placement` auto: row) and resolved by the bookkeeper.
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// PreToolUse — Bash gates
+// ---------------------------------------------------------------------------
+
+const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+
+// Exempt per the changelog rule's closed list, judged mechanically: lockfile-only,
+// harness-file-only (.claude/, AGENTS.md, CLAUDE.md), or changelog housekeeping.
+function stagedExempt(files) {
+  return files.every(
+    (f) =>
+      LOCKFILES.test(path.basename(f)) ||
+      f.startsWith(".claude/") ||
+      f === "AGENTS.md" ||
+      f === "CLAUDE.md" ||
+      f.startsWith("docs/history/changelog/") ||
+      f === "docs/history/CHANGELOG.md"
+  );
+}
+
+function commitGate(projectDir) {
+  const staged = (git(projectDir, ["diff", "--cached", "--name-only"]) || "")
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (staged.length > 0 && !stagedExempt(staged)) {
+    if (!staged.some((f) => f.startsWith("docs/history/changelog/"))) {
+      return decision(
+        "deny",
+        "BLOCKED — changelog. This commit stages no `docs/history/changelog/` entry. Every non-exempt commit carries its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping — state which if claiming one, then stage accordingly or re-run)."
+      );
+    }
+  }
+  const counts = countRows(readQueue(projectDir));
+  if (counts.unresolved > 0) {
+    return decision(
+      "deny",
+      `BLOCKED — bookkeeping. ${counts.unresolved} unresolved row(s) in docs/operations/bookkeeping.md. Dispatch the bookkeeper, resolve, or convert to \`waived:\` with a reason and expiry.`
+    );
+  }
+  return null;
+}
+
+// Package names approved anywhere in the rules (general.md table + testing.md's frameworks).
+function approvedPackages(projectDir) {
+  const names = new Set();
+  for (const rule of ["general.md", "testing.md"]) {
+    const text = readSafe(path.join(projectDir, ".claude", "rules", rule));
+    for (const m of text.matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) names.add(m[1]);
+  }
+  return names;
+}
+
+function packageGate(projectDir, command) {
+  const m = new RegExp(String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)\s+(.+)`).exec(command);
+  if (!m) return null;
+  const approved = approvedPackages(projectDir);
+  if (approved.size === 0) return null; // no rules file installed — nothing to enforce
+  const args = m[1].split(/\s+/).filter((a) => a && !a.startsWith("-"));
+  for (const arg of args) {
+    const pkg = arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0];
+    if (!pkg || pkg === "." || pkg.includes("/") && !pkg.startsWith("@")) continue;
+    if (!approved.has(pkg)) {
+      return decision(
+        "deny",
+        `BLOCKED — package table. \`${pkg}\` is not in the approved table (.claude/rules/general.md; test packages: .claude/rules/testing.md). The table changes only by explicit user decision.`
+      );
+    }
+  }
+  return null;
+}
+
+// The repo a Bash command acts on: an explicit `cd <dir>` in the command wins, then the
+// payload's cwd, then the session's home project — a session may operate across repos
+// (forge + consumer), and gating a commit against the wrong repo blocks or passes falsely.
+function commandRoot(projectDir, payload, command) {
+  const cdMatch = /(?:^|&&|;)\s*cd\s+"?([^"\s;&]+)"?/.exec(command || "");
+  for (const candidate of [cdMatch && cdMatch[1], payload.cwd]) {
+    if (!candidate || !path.isAbsolute(candidate)) continue;
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate;
+    } catch (e) {
+      /* fall through */
+    }
+  }
+  return projectDir;
+}
+
+// An ask class fires once per session: the first occurrence asks, later ones pass silently —
+// the user has already exercised judgment on this class this session.
+function askOnce(projectDir, sessionId, key, message) {
+  if (askedThisSession(projectDir, sessionId, key)) return null;
+  recordAsked(projectDir, sessionId, key);
+  return decision("ask", message);
+}
+
+// Command matchers anchor at statement boundaries (start, &&, ;, |) so quoted text — an
+// echoed payload, a commit message naming a command — can never trigger a gate.
+const AT_STATEMENT = String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:npx\s+(?:--yes\s+)?)?`;
+const statement = (body) => new RegExp(AT_STATEMENT + body);
+
+function bashGate(projectDir, command, sessionId) {
+  if (!command) return null;
+
+  if (statement(String.raw`git\s+commit\b`).test(command)) {
+    return commitGate(projectDir);
+  }
+
+  if (statement(String.raw`git\s+(checkout\s+-b|switch\s+-c|branch\s+\S+|worktree\s+add)\b`).test(command)) {
+    return askOnce(
+      projectDir,
+      sessionId,
+      "branch-worktree",
+      "Create a branch/worktree? Policy allows this only when you asked for a PR or branch."
+    );
+  }
+
+  if (
+    statement(String.raw`wrangler(?:@\S+)?\b.*(\bd1\s+execute\b.*--remote|\bsecret\s+(put|bulk)\b|\bdeploy\b)`).test(command) &&
+    !/--dry-run\b|--local\b/.test(command)
+  ) {
+    return askOnce(
+      projectDir,
+      sessionId,
+      "live-command",
+      "Run this live-system command (deploy / remote DB / secrets)? If it's a one-shot migration, its runbook should exist in docs/history/migrations/ first. Asked once per session."
+    );
+  }
+
+  return packageGate(projectDir, command);
+}
+
+// ---------------------------------------------------------------------------
+// Stop
+// ---------------------------------------------------------------------------
+
+// True when the transcript's recent tail shows a bookkeeper dispatch this turn — best-effort:
+// absent or unreadable transcript reads as "not dispatched".
+function bookkeeperDispatched(transcriptPath) {
+  const text = readSafe(transcriptPath || "");
+  if (!text) return false;
+  const tail = text.slice(-200000);
+  return /bookkeeper/i.test(tail) && /"(Task|Agent)"/.test(tail);
+}
+
+// Plans this session flipped to Complete: Status is Complete AND the file appears in this
+// machine's touched.tsv (written by the awareness detector as edits happen).
+function plansCompletedThisSession(projectDir) {
+  const touched = readSafe(path.join(projectDir, ".claude", "state", "touched.tsv"));
+  const touchedPlans = new Set(
+    touched
+      .split("\n")
+      .map((line) => line.split("\t")[1])
+      .filter((p) => p && p.startsWith("docs/history/plans/"))
+  );
+  const out = [];
+  for (const rel of touchedPlans) {
+    const text = readSafe(path.join(projectDir, rel));
+    if (/^\*\*Status:\*\*\s*Complete\b/m.test(text)) out.push(rel);
+  }
+  return out;
+}
+
+function stopGate(projectDir, payload) {
+  if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
+
+  const counts = countRows(readQueue(projectDir));
+  if (counts.unresolved > 0 && !bookkeeperDispatched(payload.transcript_path)) {
+    return {
+      decision: "block",
+      reason:
+        `${counts.unresolved} unresolved bookkeeping rows (${counts.auto} auto, ${counts.note} note, ${counts.needsSession} needs-session) in docs/operations/bookkeeping.md. ` +
+        "Dispatch the `bookkeeper` agent to drain them, resolve them now, or convert to `waived:` rows with reason + expiry. " +
+        "If implementation of the open plan is complete, also report it and offer the verification gate — never run it unbidden.",
+    };
+  }
+
+  const completed = plansCompletedThisSession(projectDir);
+  if (completed.length > 0) {
+    const drafts = git(projectDir, ["status", "--porcelain", "--", "docs/history/changelog/"]) || "";
+    if (!drafts.trim()) {
+      return {
+        decision: "block",
+        reason: `Plan \`${completed[0]}\` reached Status: Complete this session with no changelog entry drafted. Write the draft now (documentation skill → templates/changelog-entry.md) — the Ask quotes, rejected iterations, and skill verdicts that fill it exist only in this session and die with it.`,
+      };
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  const projectDir = resolveProjectDir(payload);
+  const event = payload.hook_event_name;
+
+  let out = null;
+  if (event === "PreToolUse") {
+    const input = payload.tool_input || {};
+    if (payload.tool_name === "Bash") {
+      out = bashGate(commandRoot(projectDir, payload, input.command), input.command, payload.session_id);
+    } else {
+      const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
+      if (rel) out = fileGate(projectDir, rel, payload.tool_name);
+    }
+  } else if (event === "Stop") {
+    out = stopGate(projectDir, payload);
+  }
+
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+
+try {
+  main();
+} catch (e) {
+  // Fail open: a broken gate must never become an outage.
+} finally {
+  process.exit(0);
+}

package/data/harnesses/code/hooks/hooks.json

@@ -1,16 +1,22 @@
 {
+  "permissions": {
+    "allow": [
+      "Edit(docs/**)",
+      "Write(docs/**)"
+    ]
+  },
   "hooks": {
     "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/generate-ownership-index.mjs\"",
-            "timeout": 10
-          }
-        ]
-      }
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/awareness.mjs\"", "timeout": 10 } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|Write|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/awareness.mjs\"", "timeout": 10 } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/compliance.mjs\"", "timeout": 10 } ] }
+    ],
+    "Stop": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/compliance.mjs\"", "timeout": 15 } ] }
     ]
   }
 }

package/data/harnesses/code/hooks/lib/frozen.mjs

@@ -0,0 +1,58 @@
+// harness/code/hooks/lib/frozen.mjs — the frozen-record predicate, shared by the compliance gate
+// and CI. Frozen: a committed docs/history/changelog/ entry, a plan whose Status is Complete or
+// Abandoned, an outcome-stamped migration runbook. Immutability begins at commit for changelog
+// entries (a draft in the working tree is meant to be edited), at the status flip for plans, and
+// at the Executed stamp for runbooks. Every check fails open: no git, unreadable file ⇒ not frozen.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function relPosix(projectDir, filePath) {
+  return path.relative(projectDir, path.resolve(projectDir, filePath)).split(path.sep).join("/");
+}
+
+// True when git tracks the file at HEAD (i.e. it has been committed at least once).
+export function isCommitted(projectDir, filePath) {
+  const rel = relPosix(projectDir, filePath);
+  const res = spawnSync("git", ["cat-file", "-e", `HEAD:${rel}`], { cwd: projectDir, stdio: "ignore" });
+  return res.status === 0;
+}
+
+function readSafe(projectDir, filePath) {
+  try {
+    return fs.readFileSync(path.resolve(projectDir, filePath), "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// The predicate. Returns { frozen: boolean, reason?: string }.
+export function frozenStatus(projectDir, filePath) {
+  const rel = relPosix(projectDir, filePath);
+  if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
+    if (isCommitted(projectDir, rel)) {
+      return { frozen: true, reason: "committed changelog entry — immutability begins at commit" };
+    }
+    return { frozen: false };
+  }
+  if (rel.startsWith("docs/history/plans/") && rel.endsWith(".md")) {
+    const text = readSafe(projectDir, rel);
+    if (/^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(text)) {
+      return { frozen: true, reason: "plan with Status: Complete or Abandoned" };
+    }
+    return { frozen: false };
+  }
+  if (rel.startsWith("docs/history/migrations/") && rel.endsWith(".md")) {
+    const text = readSafe(projectDir, rel);
+    if (/^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(text)) {
+      return { frozen: true, reason: "outcome-stamped migration runbook" };
+    }
+    return { frozen: false };
+  }
+  return { frozen: false };
+}
+
+export function isFrozen(projectDir, filePath) {
+  return frozenStatus(projectDir, filePath).frozen;
+}

package/data/harnesses/code/hooks/lib/ownership.mjs

@@ -0,0 +1,223 @@
+// harness/code/hooks/lib/ownership.mjs — frontmatter scan + owns:-glob resolution, shared by the
+// hook entrypoints (awareness, compliance) and the CI checks so gates and pipeline cannot disagree.
+// Everything here is read-only over docs/features/ and the source tree; no network, no deps.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+export function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+export function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Recursively collect every .md file under dir (returns [] if the dir is absent).
+export function listMarkdown(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+// Pull the leading `--- … ---` frontmatter block; "" if the file has none.
+export function frontmatter(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  return m ? m[1] : "";
+}
+
+// Trim surrounding whitespace, then strip one layer of matching quotes.
+export function unquote(s) {
+  return String(s).trim().replace(/^["']|["']$/g, "").trim();
+}
+
+// One YAML list/array item → clean value: a quoted item ends at its closing quote
+// (anything after — trailing comments — drops); an unquoted item ends at ` #`.
+export function cleanItem(s) {
+  const t = String(s).trim();
+  const q = t[0];
+  if (q === '"' || q === "'") {
+    const end = t.indexOf(q, 1);
+    if (end > 0) return t.slice(1, end).trim();
+  }
+  const hash = t.search(/\s#/);
+  return unquote(hash >= 0 ? t.slice(0, hash) : t);
+}
+
+// `[a, b] # comment` → items; content ends at the closing bracket, not the line end.
+function parseInlineArray(raw) {
+  const end = raw.indexOf("]");
+  const body = (end >= 0 ? raw.slice(0, end) : raw).replace(/^\[/, "");
+  return body.split(",").map((s) => cleanItem(s)).filter(Boolean);
+}
+
+// Read one frontmatter key: scalar (`k: v`), inline array (`k: [a, b]`), or a following `- item` block.
+// Returns a string for scalars, an array for lists, or undefined when the key is absent.
+export function field(block, key) {
+  const lines = block.split(/\r?\n/);
+  const head = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = head.exec(lines[i]);
+    if (!m) continue;
+    const raw = m[1].trim();
+    if (raw === "") {
+      // A bare key may continue as an indented inline array on the next line, or a `- item` block.
+      const next = (lines[i + 1] || "").trim();
+      if (next.startsWith("[")) {
+        return parseInlineArray(next);
+      }
+      const items = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const li = /^\s*-\s+(.*)$/.exec(lines[j]);
+        if (!li) break;
+        items.push(cleanItem(li[1]));
+      }
+      return items;
+    }
+    if (raw.startsWith("[")) {
+      return parseInlineArray(raw);
+    }
+    return unquote(raw);
+  }
+  return undefined;
+}
+
+// Coerce a field that may be scalar/array/undefined into a clean string array.
+export function asList(v) {
+  if (v == null) return [];
+  return (Array.isArray(v) ? v : [v]).map((s) => String(s).trim()).filter(Boolean);
+}
+
+// Scan docs/features/**/*.md and return one entry per feature doc that declares owns:.
+// Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
+export function scanFeatureDocs(projectDir) {
+  const featuresDir = path.join(projectDir, "docs", "features");
+  const files = listMarkdown(featuresDir);
+  const docs = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      continue;
+    }
+    const block = frontmatter(text);
+    if (!block) continue;
+    const owns = asList(field(block, "owns"));
+    if (owns.length === 0) continue;
+    docs.push({
+      doc: path.relative(projectDir, file).split(path.sep).join("/"),
+      owns,
+      module: (field(block, "module") || "—").toString(),
+      keywords: asList(field(block, "keywords")),
+      status: (field(block, "status") || "active").toString().toLowerCase(),
+    });
+  }
+  return docs;
+}
+
+// Build the ownership index text from every feature doc's frontmatter.
+export function buildIndex(projectDir) {
+  const docs = scanFeatureDocs(projectDir);
+  const lines = [];
+  let deprecated = 0;
+  for (const entry of docs) {
+    if (entry.status === "deprecated") {
+      deprecated += 1;
+      continue; // keep deprecated docs out of the routing lines
+    }
+    const kw = entry.keywords.length ? `[${entry.keywords.join(", ")}]` : "[]";
+    for (const glob of entry.owns) {
+      lines.push(`${glob} → ${entry.doc} · ${entry.module} · ${kw} · ${entry.status}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  lines.sort();
+  const header =
+    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
+  const footer = deprecated > 0 ? `\n# (${deprecated} deprecated feature doc(s) omitted)` : "";
+  return header + lines.join("\n") + footer;
+}
+
+// Compile one owns:-style glob (`**` any depth, `*` within a segment) to a RegExp
+// over /-separated repo-relative paths. `a/**` also matches `a` itself.
+export function globToRegExp(glob) {
+  const g = glob.replace(/\\/g, "/").replace(/\/+$/, "");
+  const escaped = g.replace(/[\\^$.|?+()[\]{}]/g, "\\$&");
+  const re = escaped
+    .replace(/\/\*\*$/, "\0TAIL\0") // `x/**` → x plus optionally anything below it
+    .replace(/\*\*\//g, "\0LEAD\0") // `**/x` → any (possibly empty) directory prefix
+    .replace(/\*\*/g, "\0ANY\0")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\0TAIL\0/g, "(?:/.*)?")
+    .replace(/\0LEAD\0/g, "(?:.*/)?")
+    .replace(/\0ANY\0/g, ".*");
+  return new RegExp(`^${re}$`);
+}
+
+// Feature docs owning the given repo-relative path (deprecated docs excluded).
+export function owningDocs(projectDir, relPath) {
+  const rel = relPath.split(path.sep).join("/");
+  const out = [];
+  for (const entry of scanFeatureDocs(projectDir)) {
+    if (entry.status === "deprecated") continue;
+    if (entry.owns.some((g) => globToRegExp(g).test(rel))) out.push(entry);
+  }
+  return out;
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".claude", ".codex"]);
+
+// Walk the repo once and return every tracked-ish file path (repo-relative, /-separated).
+// Used to detect dead globs; heavy dirs are skipped, depth is bounded by the tree itself.
+export function listRepoFiles(projectDir) {
+  const out = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(path.relative(projectDir, full).split(path.sep).join("/"));
+    }
+  }
+  walk(projectDir);
+  return out;
+}
+
+// Globs across all feature docs that match zero files on disk.
+// Returns [{ glob, doc }]; pass a precomputed file list to amortize the walk.
+export function deadGlobs(projectDir, repoFiles) {
+  const files = repoFiles || listRepoFiles(projectDir);
+  const dead = [];
+  for (const entry of scanFeatureDocs(projectDir)) {
+    if (entry.status === "deprecated") continue;
+    for (const glob of entry.owns) {
+      const re = globToRegExp(glob);
+      if (!files.some((f) => re.test(f))) dead.push({ glob, doc: entry.doc });
+    }
+  }
+  return dead;
+}