@nurix/etna 0.19.89 → 0.19.91

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

@@ -7,8 +7,10 @@
 
 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 { readStdin, resolveProjectDir } from "./lib/ownership.mjs";
+import { readSafe, relIfInside, git, commandRoot, backtickTokens, SOURCE_EXT } from "./lib/repo.mjs";
+import { openGatedPlans, inPlanScope } from "./lib/plans.mjs";
+import { stagedExempt } from "./lib/exempt.mjs";
 import { readQueue, countRows, askedThisSession, recordAsked } from "./lib/state.mjs";
 import { frozenStatus } from "./lib/frozen.mjs";
 import { undischargedRows } from "./lib/ledger.mjs";
@@ -16,26 +18,6 @@ import { appendEvent, unresolvedDenials, sessionLogPath, malformedEventLines } f
 import { approvedPackages, rejectedPackages } from "./lib/approved.mjs";
 import { claimActivity, releaseActivity, recentForeignTouches } from "./lib/claims.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 },
@@ -63,48 +45,16 @@ function autoResolve(projectDir, sessionId, gate, target) {
 // PreToolUse — file gates
 // ---------------------------------------------------------------------------
 
+// Re-read at most once per hook process — the list is consulted per gated path.
+let protectedCache = null;
 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;
+  if (protectedCache) return protectedCache;
+  const text = readSafe(path.join(projectDir, "docs", "operations", "protected-files.md"));
+  protectedCache = ["AGENTS.md", "docs/operations/protected-files.md", ...backtickTokens(text)];
+  return protectedCache;
 }
 
-// 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),
-      hasDocLedger: /^##\s+Doc Obligations\b/m.test(text),
-    });
-  }
-  return plans;
-}
-
-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, sessionId) {
+function fileGate(projectDir, rel, sessionId) {
   const frozen = frozenStatus(projectDir, rel);
   if (frozen.frozen) {
     return deny(
@@ -141,8 +91,11 @@ function fileGate(projectDir, rel, toolName, sessionId) {
   }
 
   const inDocs = rel.startsWith("docs/") || rel.startsWith(".claude/") || rel.endsWith(".md");
-  if (!inDocs && SOURCE_LIKE.test(rel)) {
+  if (!inDocs && SOURCE_EXT.test(rel)) {
     for (const plan of openGatedPlans(projectDir)) {
+      // The gate binds the plan's own paths, so disjoint plans run in parallel.
+      // A scopeless plan stays repo-wide — fail closed.
+      if (plan.scope.length && !inPlanScope(rel, plan.scope)) continue;
       if (/Boundary:\s*pending/i.test(plan.gates)) {
         return deny(
           projectDir,
@@ -183,8 +136,8 @@ function fileGate(projectDir, rel, toolName, sessionId) {
   // a file appears adds no guarantee those two do not, and it fires hardest at the gate itself,
   // where the ledger's tests are precisely what should be getting written.
 
-  // 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.
+  // Doc placement is never an interruption: docs/structure.md is the authority a session
+  // consults; no hook polices it.
   return null;
 }
 
@@ -192,32 +145,6 @@ function fileGate(projectDir, rel, toolName, sessionId) {
 // 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.
-const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
-const HARNESS_FILES = [
-  "AGENTS.md",
-  "CLAUDE.md",
-  ".mcp.json",
-  ".vscode/settings.json",
-  ".prettierignore",
-  ".prettierrc.json",
-];
-
-function stagedExempt(files) {
-  return files.every(
-    (f) =>
-      LOCKFILES.test(path.basename(f)) ||
-      HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
-      HARNESS_FILES.includes(f) ||
-      f.startsWith("docs/history/changelog/") ||
-      f.includes(".bkp.") ||
-      f === "docs/history/CHANGELOG.md"
-  );
-}
-
 function commitGate(projectDir, sessionId) {
   const staged = (git(projectDir, ["diff", "--cached", "--name-only"]) || "")
     .split("\n")
@@ -271,7 +198,7 @@ const PKG_SPEC = /^(@[a-z0-9~-][\w.-]*\/)?[a-z0-9~-][\w.-]*(@[\w.^~*<>=|x-]+)?$/
 
 function packageGate(projectDir, command, sessionId) {
   const m = new RegExp(
-    String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)(?=\s|$)([^&;|]*)`
+    String.raw`(?:^|\n|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)(?=\s|$)([^&;|\n]*)`
   ).exec(command);
   if (!m) return null;
   const approved = approvedPackages(projectDir);
@@ -288,9 +215,11 @@ function packageGate(projectDir, command, sessionId) {
     [...approved].filter((n) => n.startsWith("@")).map((n) => n.split("/")[0])
   );
   approvedScopes.add("@types");
-  const args = raw.split(/\s+/).filter((a) => a && !a.startsWith("-") && PKG_SPEC.test(a));
-  for (const arg of args) {
-    const pkg = arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0];
+  const pkgs = raw
+    .split(/\s+/)
+    .filter((a) => a && !a.startsWith("-") && PKG_SPEC.test(a))
+    .map((arg) => (arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0]));
+  for (const pkg of pkgs) {
     if (approved.has(pkg)) continue;
     if (isDev && pkg.startsWith("@") && approvedScopes.has(pkg.split("/")[0])) continue;
     // Approved wins over rejected: `jest` is banned for web and Express and prescribed for Expo,
@@ -311,33 +240,11 @@ function packageGate(projectDir, command, sessionId) {
     // No decision exists for this package — not approved, not rejected. Allowed, and harvested
     // centrally by the fleet package census rather than blocked here.
   }
-  // Every named package is approved — a package-table denial for one of them is a successful retry.
-  for (const arg of args) {
-    const pkg = arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0];
-    autoResolve(projectDir, sessionId, "package-table", pkg);
-  }
+  // Every named package passed — a package-table denial for one of them is a successful retry.
+  for (const pkg of pkgs) autoResolve(projectDir, sessionId, "package-table", pkg);
   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.
-// A candidate is normalized to its git toplevel: a cwd inside the repo (packages/studio)
-// still gates — and writes the session log — against the repo root, not the subdirectory.
-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()) continue;
-    } catch (e) {
-      continue;
-    }
-    return git(candidate, ["rev-parse", "--show-toplevel"]) || candidate;
-  }
-  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) {
@@ -346,9 +253,11 @@ function askOnce(projectDir, sessionId, key, message) {
   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+)?)?`;
+// Command matchers anchor at statement boundaries (start, newline, &&, ;, |) so quoted text — an
+// echoed payload, a commit message naming a command — can never trigger a gate, while a command
+// on its own line cannot slip past one. (Heredoc bodies still look like statements; that false
+// positive is accepted over the false negative.)
+const AT_STATEMENT = String.raw`(?:^|\n|&&|;|\|)\s*(?:sudo\s+)?(?:npx\s+(?:--yes\s+)?)?`;
 const statement = (body) => new RegExp(AT_STATEMENT + body);
 
 function bashGate(projectDir, command, sessionId) {
@@ -460,13 +369,13 @@ function bashWriteScreen(projectDir, command, sessionId) {
 // Stop
 // ---------------------------------------------------------------------------
 
-// True when the transcript's recent tail shows a bookkeeper dispatch this turn — best-effort:
-// absent or unreadable transcript reads as "not dispatched".
+// True when the transcript's recent tail shows a REAL bookkeeper dispatch — a tool record naming
+// the agent type, not the word appearing in prose (policy text quoting "bookkeeper" rides in most
+// transcripts, and a prose match silently suppressed this wall). 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);
+  const tail = readSafe(transcriptPath || "").slice(-200000);
+  return /"subagent_type"\s*:\s*"bookkeeper"/.test(tail);
 }
 
 // Plans this session flipped to Complete: Status is Complete AND the file appears in this
@@ -493,19 +402,12 @@ function plansCompletedThisSession(projectDir, sessionId) {
   return out;
 }
 
-// Whether some changelog entry already accounts for this plan.
-//
-// COMMITTED COUNTS. The test used to be `git status --porcelain docs/history/changelog/` — i.e. "is
-// there a DIRTY file there" — which a properly committed entry can never satisfy: committing cleans
-// the tree, so the gate re-fired immediately after the one action that discharged it, and the only
-// way to silence it was to leave an uncommitted file lying in the changelog directory.
-//
-// An entry names its plan by slug (the template links `../plans/<slug>.md`), so the slug is what is
-// searched for. A dirty file still counts too: a draft being written this moment has not necessarily
-// named its plan yet, and that was the original check's one real job.
+// Whether some changelog entry already accounts for this plan. An entry names its plan by slug
+// (the template links `../plans/<slug>.md`), so the slug is what is searched for — over every
+// entry on disk, committed or draft. A dirty-but-unrelated file in the changelog directory does
+// NOT count: that shortcut made the wall satisfiable by `touch docs/history/changelog/x.md`,
+// for every plan at once.
 function planHasChangelogEntry(projectDir, planRel) {
-  if ((git(projectDir, ["status", "--porcelain", "--", "docs/history/changelog/"]) || "").trim()) return true;
-
   const slug = path.basename(planRel, ".md");
   const dir = path.join(projectDir, "docs", "history", "changelog");
   let names = [];
@@ -517,43 +419,6 @@ function planHasChangelogEntry(projectDir, planRel) {
   return names.some((name) => name.endsWith(".md") && readSafe(path.join(dir, name)).includes(slug));
 }
 
-// Approximate the context the next turn will re-read, from the transcript's last recorded usage.
-// Best-effort: an absent or unparseable transcript reports nothing.
-function sessionContextTokens(transcriptPath) {
-  const text = readSafe(transcriptPath || "");
-  if (!text) return 0;
-  const lines = text.slice(-400000).split("\n");
-  for (let i = lines.length - 1; i >= 0; i--) {
-    if (!lines[i].includes('"usage"')) continue;
-    try {
-      const u = JSON.parse(lines[i]).message.usage;
-      return (
-        (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0)
-      );
-    } catch (e) {
-      // the slice cut this line in half — keep scanning upward
-    }
-  }
-  return 0;
-}
-
-// Context re-reads in full on every turn, so its size IS the standing per-turn floor — the one
-// number that argues for ending a session rather than carrying it into unrelated work. The agent
-// cannot act on this (it can neither end a session nor start one), so it is addressed to the user
-// as a systemMessage and never blocks. Kept out of the model's context deliberately: a running
-// token count in-context produces context anxiety, not shorter sessions.
-const CONTEXT_ADVISORY_TOKENS = 250000;
-
-function sessionSizeNote(payload) {
-  const tokens = sessionContextTokens(payload.transcript_path);
-  if (tokens < CONTEXT_ADVISORY_TOKENS) return null;
-  return (
-    `Session context is roughly ${Math.round(tokens / 1000)}K tokens, and every turn re-reads all of it — ` +
-    "that is the per-turn floor before anything new is produced. A fresh session starts near zero; " +
-    "worth ending this one if the next task is unrelated."
-  );
-}
-
 function stopGate(projectDir, payload) {
   if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
 
@@ -567,8 +432,11 @@ function stopGate(projectDir, payload) {
     return {
       decision: "block",
       reason:
-        `${counts.unresolved} unresolved bookkeeping rows from this session (${counts.auto} auto, ${counts.note} note, ${counts.needsSession} needs-session) in docs/operations/bookkeeping.md. ` +
+        `${counts.unresolved} unresolved bookkeeping rows from this session (${counts.auto} auto, ${counts.note} note, ${counts.needsSession} needs-session, ${counts.expiredWaived} expired-waived) in docs/operations/bookkeeping.md. ` +
         "Dispatch the `bookkeeper` agent to drain them, resolve them now, or convert to `waived:` rows with reason + expiry. " +
+        (counts.expiredWaived > 0
+          ? "An expired waiver is a deferral that ran out — re-judge whether its reason still holds rather than re-waiving by default. "
+          : "") +
         "If implementation of the open plan is complete, also report it and offer the verification gate — never run it unbidden.",
     };
   }
@@ -648,16 +516,11 @@ function main() {
     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, payload.session_id);
+      const rel = relIfInside(projectDir, input.file_path);
+      if (rel) out = fileGate(projectDir, rel, payload.session_id);
     }
   } else if (event === "Stop") {
     out = stopGate(projectDir, payload);
-    // Advisory rides alongside a block rather than replacing it — both are true at once.
-    if (!payload.stop_hook_active) {
-      const note = sessionSizeNote(payload);
-      if (note) out = { ...(out || {}), systemMessage: note };
-    }
   }
 
   if (out) process.stdout.write(JSON.stringify(out));

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

@@ -2,16 +2,8 @@
 // PreToolUse install gate (compliance) and the PostToolUse outcome detector (awareness), so
 // "blocked at install" and "flagged in the manifest" can never disagree about the table.
 
-import fs from "node:fs";
 import path from "node:path";
-
-function readSafe(file) {
-  try {
-    return fs.readFileSync(file, "utf8");
-  } catch (e) {
-    return "";
-  }
-}
+import { readSafe } from "./repo.mjs";
 
 // A rule names its rejected alternatives in backticks — instruction-style § Negative space requires
 // it — so harvesting every backticked token adds the ban list to the approved set. Two shapes carry

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

@@ -12,15 +12,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { stateDir, withFileLock, atomicWrite } from "./state.mjs";
+import { sid8 } from "./repo.mjs";
 
 const LIVE_WINDOW_MIN = 30; // transcript modified within this window ⇒ the session is live
 const CLAIM_TTL_MIN = 20; // an activity claim older than this is stale even if the holder lives
 const RETENTION_DAYS = 14; // registry + touched.tsv rows older than this are pruned
 
-function sid8(sessionId) {
-  return String(sessionId || "unknown").replace(/[^a-zA-Z0-9-]/g, "").slice(0, 8) || "unknown";
-}
-
 function minutesSince(iso) {
   const t = Date.parse(iso);
   return Number.isFinite(t) ? (Date.now() - t) / 60000 : Infinity;

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

@@ -0,0 +1,32 @@
+// harness/code/hooks/lib/exempt.mjs — the changelog rule's closed exemption list, judged
+// mechanically. One predicate shared by the commit gate and the CI backstop: two private
+// copies once drifted (`.bkp.` exempt at the gate, not in CI) and could disagree about
+// whether the same commit owed an entry.
+
+import path from "node:path";
+
+const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+const HARNESS_PREFIXES = [".claude/", ".agents/", ".codex/"];
+const HARNESS_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".mcp.json",
+  ".vscode/settings.json",
+  ".prettierignore",
+  ".prettierrc.json",
+];
+
+export function changelogExemptFile(f) {
+  return (
+    LOCKFILES.test(path.basename(f)) ||
+    HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
+    HARNESS_FILES.includes(f) ||
+    f.startsWith("docs/history/changelog/") ||
+    f.includes(".bkp.") ||
+    f === "docs/history/CHANGELOG.md"
+  );
+}
+
+export function stagedExempt(files) {
+  return files.every(changelogExemptFile);
+}

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

@@ -29,10 +29,10 @@ function readSafe(projectDir, filePath) {
 
 // The predicate. Returns { frozen: boolean, reason?: string }.
 export function frozenStatus(projectDir, filePath) {
+  const rel = relPosix(projectDir, filePath);
   // *.bkp.* siblings are install-time backups, not records — the maintenance fold edits and
   // deletes them, which a frozen verdict would forbid.
-  if (relPosix(projectDir, filePath).includes(".bkp.")) return { frozen: false };
-  const rel = relPosix(projectDir, filePath);
+  if (rel.includes(".bkp.")) return { frozen: false };
   if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
     if (isCommitted(projectDir, rel)) {
       return { frozen: true, reason: "committed changelog entry — immutability begins at commit" };
@@ -56,6 +56,26 @@ export function frozenStatus(projectDir, filePath) {
   return { frozen: false };
 }
 
-export function isFrozen(projectDir, filePath) {
-  return frozenStatus(projectDir, filePath).frozen;
+// Frozen as of HEAD — the copy git holds, not the working tree. This is the outcome detector's
+// predicate: a record frozen only in the worktree is a freeze born in the current edit (a plan
+// legitimately flipping to Complete), and flagging it walls the completion ceremony itself.
+// Only an edit to something HEAD already froze is an evasion.
+export function frozenStatusAtHead(projectDir, filePath) {
+  const rel = relPosix(projectDir, filePath);
+  if (rel.includes(".bkp.")) return { frozen: false };
+  if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
+    return frozenStatus(projectDir, filePath); // already keyed on isCommitted
+  }
+  const inRepo = spawnSync("git", ["rev-parse", "--git-dir"], { cwd: projectDir, stdio: "ignore", timeout: 5000 });
+  if (inRepo.status !== 0) return frozenStatus(projectDir, filePath); // gitless — the worktree is all there is
+  const res = spawnSync("git", ["show", `HEAD:${rel}`], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
+  const headText = res.status === 0 ? res.stdout || "" : "";
+  if (!headText) return { frozen: false }; // never committed — a freeze born in this worktree is a ceremony, not an evasion
+  if (rel.startsWith("docs/history/plans/") && /^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(headText)) {
+    return { frozen: true, reason: "plan committed with Status: Complete or Abandoned" };
+  }
+  if (rel.startsWith("docs/history/migrations/") && /^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(headText)) {
+    return { frozen: true, reason: "outcome-stamped migration runbook" };
+  }
+  return { frozen: false };
 }

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

@@ -194,10 +194,10 @@ export function globToRegExp(glob) {
 }
 
 // Feature docs owning the given repo-relative path (deprecated docs excluded).
-export function owningDocs(projectDir, relPath) {
+export function owningDocs(projectDir, relPath, docs) {
   const rel = relPath.split(path.sep).join("/");
   const out = [];
-  for (const entry of scanFeatureDocs(projectDir)) {
+  for (const entry of docs || scanFeatureDocs(projectDir)) {
     if (entry.status === "deprecated") continue;
     if (entry.owns.some((g) => globToRegExp(g).test(rel))) out.push(entry);
   }
@@ -229,11 +229,11 @@ export function listRepoFiles(projectDir) {
 }
 
 // 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) {
+// Returns [{ glob, doc }]; pass precomputed file/doc lists to amortize the walks.
+export function deadGlobs(projectDir, repoFiles, docs) {
   const files = repoFiles || listRepoFiles(projectDir);
   const dead = [];
-  for (const entry of scanFeatureDocs(projectDir)) {
+  for (const entry of docs || scanFeatureDocs(projectDir)) {
     if (entry.status === "deprecated") continue;
     for (const glob of entry.owns) {
       const re = globToRegExp(glob);
@@ -258,43 +258,39 @@ export function specificity(glob) {
   return { literal, wildcard };
 }
 
-// Two globs are equally specific when both tuple components match.
-export function sameSpecificity(a, b) {
-  return a.literal === b.literal && a.wildcard === b.wildcard;
-}
-
 // Cross-doc equal-specificity ownership conflicts: two globs from DIFFERENT feature docs that
 // match a common file at the same specificity, so "most specific wins" cannot pick an owner and
-// the path is doubly owned. Returns [{ a: {doc, glob}, b: {doc, glob}, example }].
+// the path is doubly owned. Returns [{ a: {doc, glob}, b: {doc, glob}, example }] — one pass
+// over the files, owners grouped per file, instead of a quadratic glob-pair scan.
 //
 // This is the mechanical half of a rule the harness has always stated and never checked — the
 // `documentation` skill's frontmatter reference calls an equal-specificity overlap "an ownership
 // conflict to resolve", and the `maintenance` agent is told to flag one. Without this, both had
 // to be enforced by eye.
-export function overlaps(projectDir, repoFiles) {
+export function overlaps(projectDir, repoFiles, docs) {
   const files = repoFiles || listRepoFiles(projectDir);
   const owners = [];
-  for (const entry of scanFeatureDocs(projectDir)) {
+  for (const entry of docs || scanFeatureDocs(projectDir)) {
     if (entry.status === "deprecated") continue;
     for (const glob of entry.owns) {
-      const re = globToRegExp(glob);
-      owners.push({ doc: entry.doc, glob, spec: specificity(glob), files: files.filter((f) => re.test(f)) });
+      const s = specificity(glob);
+      owners.push({ doc: entry.doc, glob, key: `${s.literal}/${s.wildcard}`, re: globToRegExp(glob) });
     }
   }
-  return pairOverlaps(owners);
-}
-
-// The pure core of `overlaps()`, split out so tests can feed synthetic owners without a repo tree.
-export function pairOverlaps(owners) {
   const found = [];
-  for (let i = 0; i < owners.length; i++) {
-    for (let j = i + 1; j < owners.length; j++) {
-      const a = owners[i];
-      const b = owners[j];
-      if (a.doc === b.doc) continue;
-      if (!sameSpecificity(a.spec, b.spec)) continue;
-      const example = a.files.find((f) => b.files.includes(f));
-      if (example) found.push({ a: { doc: a.doc, glob: a.glob }, b: { doc: b.doc, glob: b.glob }, example });
+  const seen = new Set(); // one example per glob pair
+  for (const file of files) {
+    const here = owners.filter((o) => o.re.test(file));
+    for (let i = 0; i < here.length; i++) {
+      for (let j = i + 1; j < here.length; j++) {
+        const a = here[i];
+        const b = here[j];
+        if (a.doc === b.doc || a.key !== b.key) continue;
+        const pair = `${a.doc}·${a.glob}·${b.doc}·${b.glob}`;
+        if (seen.has(pair)) continue;
+        seen.add(pair);
+        found.push({ a: { doc: a.doc, glob: a.glob }, b: { doc: b.doc, glob: b.glob }, example: file });
+      }
     }
   }
   return found;

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

@@ -0,0 +1,63 @@
+// harness/code/hooks/lib/plans.mjs — the one reader of docs/history/plans/. The gate, the
+// SessionStart banner, and the CI completion check all consume this parse; three private
+// regex triplets once disagreed about what a plan's Status line was.
+
+import fs from "node:fs";
+import path from "node:path";
+import { readSafe, backtickTokens } from "./repo.mjs";
+import { globToRegExp } from "./ownership.mjs";
+
+// A plan's scope: path-shaped backticked tokens in its `## Proposed Changes` section.
+// Empty ⇒ unparseable ⇒ the caller treats the plan as repo-wide (fail closed — the
+// pressure lands on the scopeless plan, not its neighbors).
+export function planScopePaths(text) {
+  const section = /^##\s+Proposed Changes\s*$([\s\S]*?)(?=^##\s|(?![\s\S]))/m.exec(text);
+  if (!section) return [];
+  return backtickTokens(section[1]).filter((t) => t.includes("/"));
+}
+
+// True when `rel` falls inside a scope entry. Wildcarded entries compile through the same glob
+// engine the ownership index uses — a mid-pattern glob (`tests/*.test.mjs`) once fell through
+// the trailing-`/**` special case and silently matched nothing, narrowing the gate. A bare
+// directory entry covers its subtree; a bare file matches exactly.
+export function inPlanScope(rel, scope) {
+  return scope.some((entry) => {
+    if (entry.includes("*")) return globToRegExp(entry).test(rel);
+    if (entry.endsWith("/")) return rel === entry.slice(0, -1) || rel.startsWith(entry);
+    return rel === entry || rel.startsWith(entry + "/");
+  });
+}
+
+// Every plan in the folder, parsed once: { file, status, gates, scope, hasLedger,
+// hasDocLedger, ledgerRows }. `gates` is null on legacy plans (pre-Gates format).
+export function listPlans(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() || null;
+    if (!status) continue;
+    plans.push({
+      file,
+      status,
+      gates: (/^\*\*Gates:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim() || null,
+      scope: planScopePaths(text),
+      hasLedger: /^##\s+Test Obligations\b/m.test(text),
+      hasDocLedger: /^##\s+Doc Obligations\b/m.test(text),
+      ledgerRows: (text.match(/^\|\s*\d+\s*\|/gm) || []).length,
+    });
+  }
+  return plans;
+}
+
+// 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.
+export function openGatedPlans(projectDir) {
+  return listPlans(projectDir).filter((p) => !/Complete|Abandoned/.test(p.status) && p.gates);
+}