mason-context 0.16.2 → 0.17.0

package/dist/mason-audit.js

@@ -1,30 +1,13 @@
 #!/usr/bin/env node
-
-// src/audit/cli.ts
-import path17 from "path";
-
-// src/audit/audit.ts
-import fs9 from "fs/promises";
-import path15 from "path";
-
-// src/drift/drift.ts
-import fs3 from "fs/promises";
-import path6 from "path";
-import { execFile as execFile3 } from "child_process";
-import { promisify as promisify3 } from "util";
-
-// src/snapshot/snapshot.ts
-import path5 from "path";
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-
-// src/utils/files.ts
-import fs from "fs/promises";
-import { constants } from "fs";
-import path2 from "path";
-import { execFile } from "child_process";
-import { promisify } from "util";
-import fg from "fast-glob";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/utils/paths.ts
 import path from "path";
@@ -47,35 +30,19 @@ function anchorMatches(anchor, file) {
 function matchingPaths(anchors, files) {
   return [...new Set(files)].filter((file) => anchors.some((anchor) => anchorMatches(anchor, file)));
 }
+var init_paths = __esm({
+  "src/utils/paths.ts"() {
+    "use strict";
+  }
+});
 
 // src/utils/files.ts
-var exec = promisify(execFile);
-var SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mts", "cts", "mjs", "cjs", "vue", "svelte", "kt", "kts", "java", "py", "go", "rs", "swift", "rb", "cs", "cpp", "c", "h", "hpp", "dart", "php"];
-var SOURCE_GLOB = `**/*.{${SOURCE_EXTENSIONS.join(",")}}`;
-var SOURCE_IGNORE = [
-  "**/node_modules/**",
-  "**/dist/**",
-  "**/build/**",
-  "**/.gradle/**",
-  "**/target/**",
-  "**/.git/**",
-  "**/.mason/**",
-  "**/vendor/**",
-  "**/__pycache__/**",
-  "**/venv/**",
-  "**/.venv/**",
-  "**/*.min.*",
-  "**/*.map",
-  "**/*.lock",
-  "**/generated/**",
-  "**/*.generated.*",
-  "**/R.java",
-  "**/BuildConfig.java",
-  "**/package-lock.json",
-  "**/yarn.lock",
-  "**/pnpm-lock.yaml"
-];
-var MAX_SOURCE_BYTES = 1024 * 1024;
+import fs from "fs/promises";
+import { constants } from "fs";
+import path2 from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import fg from "fast-glob";
 async function readBoundedFile(file, maxBytes) {
   const handle = await fs.open(file, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
   try {
@@ -116,6 +83,40 @@ async function loadProjectConfig(root) {
     throw new Error(`Cannot apply project file policy: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+var exec, SOURCE_EXTENSIONS, SOURCE_GLOB, SOURCE_IGNORE, MAX_SOURCE_BYTES;
+var init_files = __esm({
+  "src/utils/files.ts"() {
+    "use strict";
+    init_paths();
+    exec = promisify(execFile);
+    SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mts", "cts", "mjs", "cjs", "vue", "svelte", "kt", "kts", "java", "py", "go", "rs", "swift", "rb", "cs", "cpp", "c", "h", "hpp", "dart", "php"];
+    SOURCE_GLOB = `**/*.{${SOURCE_EXTENSIONS.join(",")}}`;
+    SOURCE_IGNORE = [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/.gradle/**",
+      "**/target/**",
+      "**/.git/**",
+      "**/.mason/**",
+      "**/vendor/**",
+      "**/__pycache__/**",
+      "**/venv/**",
+      "**/.venv/**",
+      "**/*.min.*",
+      "**/*.map",
+      "**/*.lock",
+      "**/generated/**",
+      "**/*.generated.*",
+      "**/R.java",
+      "**/BuildConfig.java",
+      "**/package-lock.json",
+      "**/yarn.lock",
+      "**/pnpm-lock.yaml"
+    ];
+    MAX_SOURCE_BYTES = 1024 * 1024;
+  }
+});
 
 // src/utils/storage.ts
 import fs2 from "fs/promises";
@@ -179,39 +180,28 @@ async function writeStoreJson(root, relative, value) {
     await fs2.rm(temporary, { force: true });
   }
 }
-
-// src/snapshot/snapshot.ts
-import { z } from "zod";
+var init_storage = __esm({
+  "src/utils/storage.ts"() {
+    "use strict";
+    init_paths();
+    init_files();
+  }
+});
 
 // src/test-map.ts
 import path4 from "path";
+var init_test_map = __esm({
+  "src/test-map.ts"() {
+    "use strict";
+    init_files();
+  }
+});
 
 // src/snapshot/snapshot.ts
-var exec2 = promisify2(execFile2);
-var repoPath = z.string().refine((value) => normalizeRepoPath(value) !== null, "Expected a relative repository path");
-var verificationFields = {
-  refreshedHash: z.string().optional(),
-  verifiedAt: z.string().optional(),
-  verifiedHash: z.string().optional(),
-  verificationFailed: z.boolean().optional(),
-  verificationNote: z.string().optional()
-};
-var featureSchema = z.object({
-  description: z.string(),
-  files: z.array(repoPath),
-  tests: z.array(repoPath).optional(),
-  type: z.enum(["capability", "infrastructure"]).optional(),
-  ...verificationFields
-}).passthrough();
-var flowSchema = z.object({ description: z.string(), chain: z.array(repoPath), ...verificationFields }).passthrough();
-var snapshotSchema = z.object({
-  version: z.literal(2),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-  gitHash: z.string(),
-  features: z.record(featureSchema),
-  flows: z.record(flowSchema)
-}).passthrough();
+import path5 from "path";
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+import { z } from "zod";
 async function getCurrentGitHash(rootDir) {
   try {
     const { stdout } = await exec2("git", ["rev-parse", "HEAD"], {
@@ -222,9 +212,48 @@ async function getCurrentGitHash(rootDir) {
     return "unknown";
   }
 }
+var exec2, repoPath, verificationFields, featureSchema, flowSchema, snapshotSchema;
+var init_snapshot = __esm({
+  "src/snapshot/snapshot.ts"() {
+    "use strict";
+    init_files();
+    init_files();
+    init_storage();
+    init_paths();
+    init_test_map();
+    exec2 = promisify2(execFile2);
+    repoPath = z.string().refine((value) => normalizeRepoPath(value) !== null, "Expected a relative repository path");
+    verificationFields = {
+      refreshedHash: z.string().optional(),
+      verifiedAt: z.string().optional(),
+      verifiedHash: z.string().optional(),
+      verificationFailed: z.boolean().optional(),
+      verificationNote: z.string().optional()
+    };
+    featureSchema = z.object({
+      description: z.string(),
+      files: z.array(repoPath),
+      tests: z.array(repoPath).optional(),
+      type: z.enum(["capability", "infrastructure"]).optional(),
+      ...verificationFields
+    }).passthrough();
+    flowSchema = z.object({ description: z.string(), chain: z.array(repoPath), ...verificationFields }).passthrough();
+    snapshotSchema = z.object({
+      version: z.literal(2),
+      createdAt: z.string(),
+      updatedAt: z.string(),
+      gitHash: z.string(),
+      features: z.record(featureSchema),
+      flows: z.record(flowSchema)
+    }).passthrough();
+  }
+});
 
 // src/drift/drift.ts
-var exec3 = promisify3(execFile3);
+import fs3 from "fs/promises";
+import path6 from "path";
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
 function parseChanges(output) {
   const fields = output.split("\0");
   const changes = [];
@@ -263,16 +292,100 @@ async function getWorkingTree(resolvedRoot) {
     return { available: false, changedFiles: [], untrackedFiles: [] };
   }
 }
+var exec3;
+var init_drift = __esm({
+  "src/drift/drift.ts"() {
+    "use strict";
+    init_snapshot();
+    init_paths();
+    exec3 = promisify3(execFile3);
+  }
+});
 
-// src/audit/docs.ts
-import fs4 from "fs/promises";
+// src/audit/commands.ts
 import path7 from "path";
-import { execFile as execFile5 } from "child_process";
-import { promisify as promisify5 } from "util";
+function splitCommands(line) {
+  const parts = [];
+  let quote = "", start = 0;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = "";
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+    if (char === ";" || line.slice(i, i + 2) === "&&") {
+      parts.push(line.slice(start, i));
+      if (char === "&") i++;
+      start = i + 1;
+    }
+  }
+  parts.push(line.slice(start));
+  return parts;
+}
+function commandClaims(line, lineNo, cwd, shell = false) {
+  const claims = [];
+  const segments = splitCommands(line);
+  for (const segment of segments) {
+    const text2 = segment.trim().replace(/^\$\s+/, "");
+    if (text2.startsWith("#") || /^(?:echo|printf)\b/.test(text2)) continue;
+    const cd = text2.match(/^cd\s+(.+)$/);
+    if (cd) {
+      const directory = literal(cd[1]);
+      cwd = directory === null || cwd === null || /\s/.test(directory) && !/^["']/.test(cd[1]) ? null : path7.posix.join(cwd ?? ".", directory);
+      continue;
+    }
+    for (const match of text2.matchAll(COMMAND)) {
+      const flags = match[2].trim();
+      const selector = flags.match(/^(?:--prefix|--dir|-C)(?:\s+|=)(.+)$/);
+      let directory = cwd;
+      let scopeUnknown;
+      if (shell && match.index !== 0 || match[3].startsWith("-")) scopeUnknown = "Unsupported shell wrapper or options before the script.";
+      if (selector) {
+        const selected = literal(selector[1]);
+        directory = selected === null || cwd === null ? null : path7.posix.join(cwd ?? ".", selected);
+      } else if (flags) scopeUnknown = "Unsupported package-manager options before run: " + flags;
+      const tail = text2.slice(match.index + match[0].length).split(/\s--(?:\s|$)/)[0];
+      if (/(?:^|\s)(?:--workspace(?:s)?|-w|--filter|-F|--prefix|--dir|-C|--if-present)(?:\s|=|$)/.test(tail)) {
+        scopeUnknown = "Package selection or conditional options after the script need review.";
+      }
+      if (/[|()]/.test(text2) || /\b(?:pushd|popd|if|for|while)\b/.test(text2) || directory === null) {
+        scopeUnknown = "The command's working directory or shell control flow could not be resolved.";
+      }
+      claims.push({
+        scriptName: match[3],
+        invocation: match[0],
+        excerpt: match[0],
+        line: lineNo,
+        ...directory !== void 0 && directory !== null ? { directory } : {},
+        ...scopeUnknown ? { scopeUnknown } : {}
+      });
+    }
+    if (/\b(?:cd|pushd|popd)\b/.test(text2)) cwd = null;
+  }
+  return { claims, cwd };
+}
+var TOKEN, COMMAND, literal;
+var init_commands = __esm({
+  "src/audit/commands.ts"() {
+    "use strict";
+    TOKEN = `(?:"[^"\\n]*"|'[^'\\n]*'|[^\\s\`;&|]+)`;
+    COMMAND = new RegExp(`\\b(npm|pnpm|yarn)((?:[ \\t]+${TOKEN})*?)[ \\t]+run[ \\t]+([A-Za-z0-9:_.-]+)`, "g");
+    literal = (value) => {
+      const unquoted = value.replace(/^(["'])(.*)\1$/, "$2");
+      return /[$`*?\[\]{}~\\\x00-\x1f]/.test(unquoted) || path7.posix.isAbsolute(unquoted) ? null : unquoted;
+    };
+  }
+});
 
 // src/audit/tree.ts
-var MIN_GLYPH_LINES = 3;
-var GLYPHS = ["\u251C\u2500\u2500", "\u2514\u2500\u2500"];
 function glyphIndex(line) {
   for (const glyph of GLYPHS) {
     const idx = line.indexOf(glyph);
@@ -341,46 +454,17 @@ function extractTreeClaims(blockLines, blockStartLine) {
   }
   return claims;
 }
+var MIN_GLYPH_LINES, GLYPHS;
+var init_tree = __esm({
+  "src/audit/tree.ts"() {
+    "use strict";
+    MIN_GLYPH_LINES = 3;
+    GLYPHS = ["\u251C\u2500\u2500", "\u2514\u2500\u2500"];
+  }
+});
 
 // src/audit/claims.ts
-var ROOT_FILE_NAMES = /* @__PURE__ */ new Set([
-  "package.json",
-  "package-lock.json",
-  "pnpm-workspace.yaml",
-  "tsconfig.json",
-  "tsup.config.ts",
-  "vitest.config.ts",
-  "Makefile",
-  "Dockerfile",
-  "docker-compose.yml",
-  "Cargo.toml",
-  "go.mod",
-  "go.sum",
-  "pyproject.toml",
-  "requirements.txt",
-  "Gemfile",
-  "composer.json",
-  "settings.gradle.kts",
-  "settings.gradle",
-  "build.gradle.kts",
-  "build.gradle",
-  "manifest.json",
-  "server.json",
-  "README.md",
-  "CHANGELOG.md",
-  "LICENSE",
-  "CLAUDE.md",
-  "AGENTS.md",
-  ".gitignore",
-  ".env.example"
-]);
-var SHELL_FENCE_INFOS = /* @__PURE__ */ new Set(["", "bash", "sh", "shell", "console", "zsh"]);
-var COMMAND_RE = /\b(npm|pnpm|yarn)\s+run\s+([A-Za-z0-9:_.-]+)/g;
-var COUNT_RE = /(\d+)\s+(modules?|packages?|workspaces?|crates?)\b/gi;
-var COUNT_DENYLIST_RE = /^\s*(manager|registr|lock|json)/i;
-var IGNORE_LINE = "<!-- mason:ignore -->";
-var IGNORE_START = "<!-- mason:ignore-start -->";
-var IGNORE_END = "<!-- mason:ignore-end -->";
+import MarkdownIt from "markdown-it";
 function normalizePathToken(token) {
   let t = token.trim();
   if (!t) return null;
@@ -444,11 +528,34 @@ function extractClaims(content) {
   const counts = [];
   const commands = /* @__PURE__ */ new Map();
   const addPath = (claim) => {
-    if (!paths.has(claim.path)) paths.set(claim.path, claim);
+    const key = [claim.relativeTo ?? "scope", claim.path].join(":");
+    if (!paths.has(key)) paths.set(key, claim);
   };
   const addCommand = (claim) => {
-    if (!commands.has(claim.scriptName)) commands.set(claim.scriptName, claim);
+    const key = JSON.stringify([claim.scriptName, claim.directory, claim.scopeUnknown]);
+    if (!commands.has(key)) commands.set(key, claim);
   };
+  const parsed = markdown.parse(lines.map((line, i) => ignored[i] ? "" : line).join("\n"), {});
+  for (const token of parsed) {
+    if (token.type !== "inline" || !token.map) continue;
+    let line = token.map[0] + 1;
+    for (const child of token.children ?? []) {
+      const target = child.type === "link_open" ? child.attrGet("href") : child.type === "image" ? child.attrGet("src") : null;
+      if (target && !/^(?:[a-z][a-z0-9+.-]*:|[\/#~])/i.test(target)) {
+        let pathname = null;
+        try {
+          pathname = decodeURIComponent(target.split(/[?#]/)[0]);
+        } catch {
+        }
+        if (pathname && !/[$*?{}<>\\\x00-\x1f]/.test(pathname)) {
+          addPath({ path: pathname, line, excerpt: target, relativeTo: "document" });
+        }
+      }
+      if (child.type === "softbreak" || child.type === "hardbreak") line++;
+      else line += child.content.split("\n").length - 1;
+    }
+  }
+  let shellCwd;
   let inFence = false;
   let fenceInfo = "";
   let fenceMarker = "";
@@ -479,6 +586,7 @@ function extractClaims(content) {
         fenceMarker = fenceMatch[1][0];
         fenceInfo = fenceMatch[2].trim().toLowerCase();
         blockLines = [];
+        shellCwd = void 0;
         blockStartLine = lineNo + 1;
       } else if (fenceMatch[1][0] === fenceMarker) {
         inFence = false;
@@ -489,14 +597,9 @@ function extractClaims(content) {
     if (inFence) {
       blockLines.push(ignored[i] ? "" : line);
       if (!ignored[i] && SHELL_FENCE_INFOS.has(fenceInfo)) {
-        for (const m of line.matchAll(COMMAND_RE)) {
-          addCommand({
-            scriptName: m[2],
-            invocation: m[0],
-            line: lineNo,
-            excerpt: m[0]
-          });
-        }
+        const scanned = commandClaims(line, lineNo, shellCwd, true);
+        shellCwd = scanned.cwd;
+        for (const claim of scanned.claims) addCommand(claim);
       }
       continue;
     }
@@ -523,14 +626,10 @@ function extractClaims(content) {
         excerpt: m[0]
       });
     }
-    for (const m of line.matchAll(COMMAND_RE)) {
-      addCommand({
-        scriptName: m[2],
-        invocation: m[0],
-        line: lineNo,
-        excerpt: m[0]
-      });
+    for (const match of line.matchAll(/`([^`]+)`/g)) {
+      for (const claim of commandClaims(match[1], lineNo, void 0, true).claims) addCommand(claim);
     }
+    for (const claim of commandClaims(line.replace(/`[^`]+`/g, ""), lineNo).claims) addCommand(claim);
   }
   if (inFence) processBlock();
   return {
@@ -539,12 +638,56 @@ function extractClaims(content) {
     commands: [...commands.values()]
   };
 }
+var ROOT_FILE_NAMES, SHELL_FENCE_INFOS, markdown, COUNT_RE, COUNT_DENYLIST_RE, IGNORE_LINE, IGNORE_START, IGNORE_END;
+var init_claims = __esm({
+  "src/audit/claims.ts"() {
+    "use strict";
+    init_commands();
+    init_tree();
+    ROOT_FILE_NAMES = /* @__PURE__ */ new Set([
+      "package.json",
+      "package-lock.json",
+      "pnpm-workspace.yaml",
+      "tsconfig.json",
+      "tsup.config.ts",
+      "vitest.config.ts",
+      "Makefile",
+      "Dockerfile",
+      "docker-compose.yml",
+      "Cargo.toml",
+      "go.mod",
+      "go.sum",
+      "pyproject.toml",
+      "requirements.txt",
+      "Gemfile",
+      "composer.json",
+      "settings.gradle.kts",
+      "settings.gradle",
+      "build.gradle.kts",
+      "build.gradle",
+      "manifest.json",
+      "server.json",
+      "README.md",
+      "CHANGELOG.md",
+      "LICENSE",
+      "CLAUDE.md",
+      "AGENTS.md",
+      ".gitignore",
+      ".env.example"
+    ]);
+    SHELL_FENCE_INFOS = /* @__PURE__ */ new Set(["", "bash", "sh", "shell", "console", "zsh"]);
+    markdown = new MarkdownIt("commonmark", { html: false });
+    COUNT_RE = /(\d+)\s+(modules?|packages?|workspaces?|crates?)\b/gi;
+    COUNT_DENYLIST_RE = /^\s*(manager|registr|lock|json)/i;
+    IGNORE_LINE = "<!-- mason:ignore -->";
+    IGNORE_START = "<!-- mason:ignore-start -->";
+    IGNORE_END = "<!-- mason:ignore-end -->";
+  }
+});
 
 // src/audit/git.ts
 import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
-var exec4 = promisify4(execFile4);
-var COMMIT_FORMAT = "%H%x09%cI%x09%s";
 function parseCommitLine(line) {
   const parts = line.split("	");
   if (parts.length < 3 || !parts[0]) return null;
@@ -554,7 +697,7 @@ async function lastCommitOf(resolvedRoot, relPath) {
   try {
     const { stdout } = await exec4(
       "git",
-      ["log", "-1", `--format=${COMMIT_FORMAT}`, "--", relPath],
+      ["log", "-1", `--format=${COMMIT_FORMAT}`, "--", `:(literal)${relPath}`],
       { cwd: resolvedRoot }
     );
     const line = stdout.trim().split("\n")[0];
@@ -573,7 +716,7 @@ async function deletingCommitOf(resolvedRoot, relPath) {
         "--diff-filter=D",
         `--format=${COMMIT_FORMAT}`,
         "--",
-        relPath
+        `:(literal)${relPath}`
       ],
       { cwd: resolvedRoot }
     );
@@ -587,7 +730,7 @@ async function firstCommitOf(resolvedRoot, relPath) {
   try {
     const { stdout } = await exec4(
       "git",
-      ["log", "--reverse", `--format=${COMMIT_FORMAT}`, "--", relPath],
+      ["log", "--reverse", `--format=${COMMIT_FORMAT}`, "--", `:(literal)${relPath}`],
       { cwd: resolvedRoot, maxBuffer: 10 * 1024 * 1024 }
     );
     const line = stdout.trim().split("\n")[0];
@@ -624,164 +767,24 @@ async function commitsTouchingSince(resolvedRoot, fromHash, pathspecs) {
     return null;
   }
 }
-
-// src/audit/docs.ts
-var exec5 = promisify5(execFile5);
-var DOC_CANDIDATES = [
-  "AGENTS.md",
-  "CLAUDE.md",
-  ".claude/CLAUDE.md"
-];
-async function isDirty(resolvedRoot, relPath) {
-  try {
-    const { stdout } = await exec5(
-      "git",
-      ["status", "--porcelain", "--", relPath],
-      { cwd: resolvedRoot }
-    );
-    return stdout.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-async function discoverDocs(resolvedRoot) {
-  const docs = await Promise.all(DOC_CANDIDATES.map(async (candidate) => {
-    let content;
-    try {
-      content = await fs4.readFile(path7.join(resolvedRoot, candidate), "utf-8");
-    } catch {
-      return null;
-    }
-    const [lastCommit, dirty] = await Promise.all([lastCommitOf(resolvedRoot, candidate), isDirty(resolvedRoot, candidate)]);
-    return {
-      path: candidate,
-      content,
-      lineCount: content.split("\n").length,
-      lastCommit,
-      dirty,
-      claims: extractClaims(content)
-    };
-  }));
-  return docs.filter((doc) => doc !== null);
-}
-
-// src/audit/types.ts
-var ALL_CHECKS = [
-  "deleted-reference",
-  "new-module",
-  "stale-count",
-  "dead-command",
-  "deps-changed",
-  "decision-anchor-drift"
-];
-
-// src/audit/checks/deleted-reference.ts
-import fs5 from "fs/promises";
-import path8 from "path";
-async function exists(absPath) {
-  try {
-    await fs5.access(absPath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function checkDeletedReferences(ctx) {
-  const result = emptyResult();
-  for (const doc of ctx.docs) {
-    const changes = ctx.changesSinceDoc.get(doc.path);
-    const renames = /* @__PURE__ */ new Map();
-    for (const change of changes ?? []) {
-      if (change.status === "renamed" && change.previousPath) {
-        renames.set(change.previousPath, change.path);
-      }
-    }
-    for (const claim of doc.claims.paths) {
-      if (claim.path === ".mason" || claim.path.startsWith(".mason/")) {
-        continue;
-      }
-      if (await exists(path8.join(ctx.root, claim.path))) continue;
-      const anchor = { doc: doc.path, line: claim.line, excerpt: claim.excerpt };
-      const renamedTo = renames.get(claim.path) ?? null;
-      if (renamedTo) {
-        result.issues.push({
-          type: "deleted-reference",
-          message: `\`${claim.path}\` was renamed to \`${renamedTo}\``,
-          anchor,
-          confidence: "certain",
-          evidence: {
-            kind: "missing-path",
-            claimed: claim.path,
-            renamedTo,
-            deletedInCommit: null,
-            everTracked: true,
-            parentDirExists: true
-          }
-        });
-        continue;
-      }
-      const tracked = await lastCommitOf(ctx.root, claim.path);
-      if (tracked) {
-        const deleted = await deletingCommitOf(ctx.root, claim.path);
-        const detail = deleted ? ` \u2013 deleted in ${deleted.hash.slice(0, 7)} "${deleted.subject}" (${deleted.date.slice(0, 10)})` : "";
-        result.issues.push({
-          type: "deleted-reference",
-          message: `\`${claim.path}\` no longer exists${detail}`,
-          anchor,
-          confidence: "certain",
-          evidence: {
-            kind: "missing-path",
-            claimed: claim.path,
-            renamedTo: null,
-            deletedInCommit: deleted,
-            everTracked: true,
-            parentDirExists: await exists(
-              path8.join(ctx.root, path8.dirname(claim.path))
-            )
-          }
-        });
-        continue;
-      }
-      const parentDirExists = await exists(
-        path8.join(ctx.root, path8.dirname(claim.path))
-      );
-      if (!parentDirExists) continue;
-      const issue = {
-        type: "deleted-reference",
-        message: `\`${claim.path}\` does not exist (never tracked in git \u2013 possible typo or invented path)`,
-        anchor,
-        confidence: "likely",
-        evidence: {
-          kind: "missing-path",
-          claimed: claim.path,
-          renamedTo: null,
-          deletedInCommit: null,
-          everTracked: false,
-          parentDirExists: true
-        }
-      };
-      result.issues.push(issue);
-    }
+var exec4, COMMIT_FORMAT;
+var init_git = __esm({
+  "src/audit/git.ts"() {
+    "use strict";
+    exec4 = promisify4(execFile4);
+    COMMIT_FORMAT = "%H%x09%cI%x09%s";
   }
-  return result;
-}
-
-// src/audit/checks/new-module.ts
-import fg3 from "fast-glob";
-import fs7 from "fs/promises";
-import path10 from "path";
+});
 
 // src/audit/inputs.ts
-import fs6 from "fs/promises";
+import fs4 from "fs/promises";
 import * as nativeFs from "fs";
-import path9 from "path";
-import { execFile as execFile6 } from "child_process";
-import { promisify as promisify6 } from "util";
+import path8 from "path";
+import { execFile as execFile5 } from "child_process";
+import { promisify as promisify5 } from "util";
 import fg2 from "fast-glob";
-var execute = promisify6(execFile6);
-var MAX_INPUTS = 1e5;
 async function auditInputPath(root, file) {
-  if (file === ".") return fs6.realpath(root);
+  if (file === ".") return fs4.realpath(root);
   try {
     return await storePath(root, file);
   } catch (error) {
@@ -805,7 +808,7 @@ async function auditGlob(root, patterns, options) {
   if (Array.isArray(patterns) && !patterns.length) return [];
   const directories = /* @__PURE__ */ new Set();
   const readdir2 = ((directory, opts, callback) => {
-    const relative = path9.relative(root, directory).split(path9.sep).join("/") || ".";
+    const relative = path8.relative(root, directory).split(path8.sep).join("/") || ".";
     directories.add(relative);
     if (directories.size > MAX_INPUTS) {
       callback(new Error(`${options.label} exceeds ${MAX_INPUTS.toLocaleString("en-US")} directories while inspecting ${relative}. Narrow this check's inputs.`));
@@ -816,7 +819,7 @@ async function auditGlob(root, patterns, options) {
     }, callback);
   });
   const lstat2 = ((file, callback) => {
-    const relative = path9.relative(root, file).split(path9.sep).join("/") || ".";
+    const relative = path8.relative(root, file).split(path8.sep).join("/") || ".";
     auditInputPath(root, relative).then(() => nativeFs.lstat(file, callback), callback);
   });
   const stream = fg2.stream(patterns, {
@@ -844,7 +847,7 @@ async function auditGlob(root, patterns, options) {
           counts.set(dir, (counts.get(dir) ?? 0) + 1);
           return counts;
         }, /* @__PURE__ */ new Map())].sort((a, b) => b[1] - a[1]).slice(0, 3);
-        throw new Error(`${options.label} exceeds ${MAX_INPUTS.toLocaleString("en-US")} relevant paths. Largest directories: ${largest.map(([dir, count2]) => `${dir} (${count2})`).join(", ")}. Narrow this check's inputs.`);
+        throw new Error(`${options.label} exceeds ${MAX_INPUTS.toLocaleString("en-US")} relevant paths. Largest directories: ${largest.map(([dir, count3]) => `${dir} (${count3})`).join(", ")}. Narrow this check's inputs.`);
       }
     }
   } finally {
@@ -885,100 +888,341 @@ async function gitIgnoredPaths(root, files) {
     throw error;
   }
 }
+var execute, MAX_INPUTS;
+var init_inputs = __esm({
+  "src/audit/inputs.ts"() {
+    "use strict";
+    init_files();
+    init_storage();
+    execute = promisify5(execFile5);
+    MAX_INPUTS = 1e5;
+  }
+});
 
-// src/audit/checks/new-module.ts
-var DIR_DENYLIST = /* @__PURE__ */ new Set([
-  "node_modules",
-  "dist",
-  "build",
-  "out",
-  "coverage",
-  "target",
-  "vendor",
-  "__pycache__",
-  "venv",
-  ".venv",
-  ".git",
-  ".gradle",
-  ".mason",
-  ".claude",
-  ".github",
-  ".vscode",
-  ".idea"
-]);
-var SECOND_LEVEL_MIN_SOURCE_FILES = 2;
-var ENUMERATION_THRESHOLD = 2;
-function escapeRegExp(text2) {
-  return text2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function isMentioned(combinedDocs, name) {
-  const re = new RegExp(
-    `(^|[^A-Za-z0-9_-])${escapeRegExp(name)}(/|[^A-Za-z0-9_-]|$)`,
-    "im"
-  );
-  return re.test(combinedDocs);
+// src/audit/docs.ts
+import fs5 from "fs/promises";
+import path9 from "path";
+import { execFile as execFile6 } from "child_process";
+import { promisify as promisify6 } from "util";
+import fg3 from "fast-glob";
+async function isDirty(resolvedRoot, relPath) {
+  try {
+    const { stdout } = await exec5(
+      "git",
+      ["status", "--porcelain", "--", `:(literal)${relPath}`],
+      { cwd: resolvedRoot }
+    );
+    return stdout.trim().length > 0;
+  } catch {
+    return true;
+  }
 }
-async function checkNewModules(ctx) {
-  const result = emptyResult();
-  if (ctx.docs.length === 0) return result;
-  const combinedDocs = ctx.docs.map((d) => d.content).join("\n");
-  const primaryDoc = ctx.docs[0].path;
-  const checkedDocs = ctx.docs.map((d) => d.path);
-  const flag = async (dir, sourceFileCount) => {
-    result.issues.push({
-      type: "new-module",
-      message: `directory \`${dir}/\` contains ${sourceFileCount} source file${sourceFileCount === 1 ? "" : "s"} but is not mentioned in any context file`,
-      anchor: { doc: primaryDoc, line: null, excerpt: dir },
-      confidence: "likely",
-      evidence: {
-        kind: "unmentioned-dir",
-        dir,
-        sourceFileCount,
-        firstCommit: await firstCommitOf(ctx.root, dir),
-        checkedDocs
-      }
-    });
+async function discoverDocPaths(root) {
+  let candidates = [];
+  try {
+    const { stdout } = await exec5(
+      "git",
+      [
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--",
+        ":(icase,glob)**/readme.md",
+        ":(icase,glob)**/agents.md",
+        ":(icase,glob)**/claude.md"
+      ],
+      { cwd: root, maxBuffer: 16 * 1024 * 1024, timeout: 1e4 }
+    );
+    candidates = stdout.split("\0").filter(Boolean);
+  } catch (error) {
+    try {
+      await exec5("git", ["rev-parse", "--git-dir"], { cwd: root });
+    } catch {
+      return localDocPaths(root);
+    }
+    throw error;
+  }
+  candidates.push(...await localDocPaths(root));
+  const config = await loadProjectConfig(root);
+  const excluded = [
+    "**/node_modules/**",
+    "**/vendor/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/target/**",
+    "**/.git/**",
+    "**/.venv/**",
+    "**/venv/**",
+    ".mason/**",
+    ...config.ignore ?? []
+  ];
+  const paths = [];
+  const unique = [...new Set(candidates)].sort();
+  for (let offset = 0; offset < unique.length; offset += 256) {
+    paths.push(...await auditGlob(root, unique.slice(offset, offset + 256).map((p) => fg3.escapePath(p)), {
+      ignore: excluded,
+      followSymbolicLinks: false,
+      label: "Documentation discovery"
+    }));
+    if (paths.length > 1e4) throw new Error("Documentation discovery exceeds 10,000 relevant files; narrow .mason/config.json ignore patterns.");
+  }
+  const priority = (file) => {
+    const index = DOC_CANDIDATES.findIndex((p) => p.toLowerCase() === file.toLowerCase());
+    return index < 0 ? DOC_CANDIDATES.length : index;
   };
-  for (const candidate of await moduleCandidates(ctx.root, combinedDocs)) {
-    await flag(candidate.dir, candidate.sourceFileCount);
+  return paths.sort((a, b) => priority(a) - priority(b) || a.localeCompare(b));
+}
+async function localDocPaths(root) {
+  const paths = [];
+  for (const dir of [".", ".claude"]) {
+    let entries;
+    try {
+      entries = await fs5.readdir(await auditInputPath(root, dir), { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    for (const entry of entries) if (/^(?:agents|claude|readme)\.md$/i.test(entry.name)) {
+      paths.push(path9.posix.join(dir, entry.name));
+    }
   }
-  return result;
+  return paths;
 }
-async function moduleCandidates(root, combinedDocs) {
-  const [config, sourcePaths] = await Promise.all([loadProjectConfig(root), gitSourcePaths(root)]);
-  const ignore = [...SOURCE_IGNORE, ...config.ignore ?? []];
-  const sources = sourcePaths.filter((file) => !file.split("/").some((part) => part.startsWith(".")));
-  const listSubdirs = async (dir) => {
-    const entries = await fs7.readdir(await auditInputPath(root, dir), { withFileTypes: true });
-    const dirs = entries.filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && !entry.name.startsWith(".") && !DIR_DENYLIST.has(entry.name)).map((entry) => path10.posix.join(dir, entry.name));
-    const ignored = await gitIgnoredPaths(root, dirs);
-    const visible = new Set(dirs.filter((dir2) => !ignored.has(dir2) || sources.some((file) => file.startsWith(dir2 + "/"))));
-    return (await auditGlob(root, dir === "." ? "*" : `${fg3.escapePath(dir)}/*`, {
-      ignore,
-      onlyDirectories: true,
-      label: "Module directory discovery",
-      select: (file) => visible.has(file)
-    })).map((file) => path10.posix.basename(file));
+function documentScope(file) {
+  const parent = path9.posix.dirname(file);
+  return path9.posix.basename(parent).toLowerCase() === ".claude" ? path9.posix.dirname(parent) : parent;
+}
+async function discoverDocs(resolvedRoot) {
+  const docs = [];
+  for (const candidate of await discoverDocPaths(resolvedRoot)) {
+    const content = await readAuditInput(resolvedRoot, candidate);
+    if (content === null) throw new Error("Document disappeared during discovery: " + candidate);
+    const [lastCommit, dirty] = await Promise.all([lastCommitOf(resolvedRoot, candidate), isDirty(resolvedRoot, candidate)]);
+    docs.push({
+      path: candidate,
+      content,
+      scope: documentScope(candidate),
+      kind: /^readme\.md$/i.test(path9.posix.basename(candidate)) ? "readme" : "instructions",
+      lineCount: content.split("\n").length,
+      lastCommit,
+      dirty,
+      claims: extractClaims(content)
+    });
+  }
+  return docs;
+}
+var exec5, DOC_CANDIDATES;
+var init_docs = __esm({
+  "src/audit/docs.ts"() {
+    "use strict";
+    init_claims();
+    init_git();
+    init_inputs();
+    init_files();
+    exec5 = promisify6(execFile6);
+    DOC_CANDIDATES = [
+      "AGENTS.md",
+      "CLAUDE.md",
+      ".claude/CLAUDE.md"
+    ];
+  }
+});
+
+// src/audit/types.ts
+var ALL_CHECKS;
+var init_types = __esm({
+  "src/audit/types.ts"() {
+    "use strict";
+    ALL_CHECKS = [
+      "deleted-reference",
+      "new-module",
+      "stale-count",
+      "dead-command",
+      "deps-changed",
+      "decision-anchor-drift"
+    ];
+  }
+});
+
+// src/audit/scope.ts
+import fs6 from "fs/promises";
+import path10 from "path";
+function scopedPath(directory, value) {
+  if (path10.posix.isAbsolute(value) || value.includes("\\") || /[\x00-\x1f]/.test(value)) return null;
+  const resolved = path10.posix.normalize(path10.posix.join(directory, value));
+  return resolved === ".." || resolved.startsWith("../") ? null : resolved;
+}
+function pathClaimScope(doc, claim) {
+  const directory = claim.relativeTo === "document" ? path10.posix.dirname(doc) : documentScope(doc);
+  const local = scopedPath(directory, claim.path);
+  if (!local) return null;
+  const candidates = claim.relativeTo === "document" || directory === "." ? [local] : [...new Set([local, scopedPath(".", claim.path)].filter((p) => p !== null))];
+  return {
+    basis: claim.relativeTo === "document" ? "document-link" : directory === "." ? "repository" : "document",
+    directory,
+    candidates
+  };
+}
+async function pathExists(root, file) {
+  const absolute = await auditInputPath(root, file);
+  try {
+    await fs6.access(absolute);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function optionalMasonPath(file) {
+  return file.split("/").includes(".mason");
+}
+var init_scope = __esm({
+  "src/audit/scope.ts"() {
+    "use strict";
+    init_inputs();
+    init_docs();
+  }
+});
+
+// src/audit/checks/deleted-reference.ts
+import path11 from "path";
+async function checkDeletedReferences(ctx) {
+  const result = emptyResult();
+  for (const doc of ctx.docs) {
+    const changes = ctx.changesSinceDoc.get(doc.path);
+    const renames = new Map((changes ?? []).filter((c) => c.status === "renamed" && c.previousPath).map((c) => [c.previousPath, c.path]));
+    for (const claim of doc.claims.paths) {
+      const scope = pathClaimScope(doc.path, claim);
+      if (!scope) {
+        result.skipped.push({
+          check: "deleted-reference",
+          doc: doc.path,
+          reason: `Reference ${claim.excerpt} is outside the repository or has an unsupported path.`
+        });
+        continue;
+      }
+      if (scope.candidates.some(optionalMasonPath)) continue;
+      if ((await Promise.all(scope.candidates.map((file) => pathExists(ctx.root, file)))).some(Boolean)) continue;
+      const candidates = await Promise.all(scope.candidates.map(async (file) => ({
+        file,
+        tracked: await lastCommitOf(ctx.root, file),
+        parent: await pathExists(ctx.root, path11.posix.dirname(file))
+      })));
+      const candidate = candidates.find((c) => c.tracked || renames.has(c.file)) ?? candidates.find((c) => c.parent);
+      if (!candidate && claim.relativeTo !== "document") continue;
+      const resolvedPath = candidate?.file ?? scope.candidates[0];
+      const renamedTo = renames.get(resolvedPath) ?? null;
+      const deletedInCommit = candidate?.tracked && !renamedTo ? await deletingCommitOf(ctx.root, resolvedPath) : null;
+      const evidence = {
+        kind: "missing-path",
+        claimed: claim.path,
+        resolvedPath,
+        scope,
+        renamedTo,
+        deletedInCommit,
+        everTracked: !!candidate?.tracked || !!renamedTo,
+        parentDirExists: candidate?.parent ?? false
+      };
+      const anchor = { doc: doc.path, line: claim.line, excerpt: claim.excerpt };
+      const message = renamedTo ? `\`${resolvedPath}\` was renamed to \`${renamedTo}\`` : `\`${resolvedPath}\` does not exist` + (deletedInCommit ? ` \u2013 deleted in ${deletedInCommit.hash.slice(0, 7)} "${deletedInCommit.subject}" (${deletedInCommit.date.slice(0, 10)})` : "");
+      if (scope.basis !== "document" && (renamedTo || candidate?.tracked)) {
+        result.issues.push({ type: "deleted-reference", message, anchor, confidence: "certain", evidence });
+      } else {
+        result.advisories.push({ resolution: "recheck", type: "deleted-reference", message: message + (scope.basis === "document" ? "; the bare path's document/repository scope needs review." : "; no tracked history establishes it as a required file. Review for a typo, generated output, or example."), anchor, evidence });
+      }
+    }
+  }
+  return result;
+}
+var init_deleted_reference = __esm({
+  "src/audit/checks/deleted-reference.ts"() {
+    "use strict";
+    init_git();
+    init_scope();
+    init_checks();
+  }
+});
+
+// src/audit/checks/new-module.ts
+import fg4 from "fast-glob";
+import fs7 from "fs/promises";
+import path12 from "path";
+function escapeRegExp(text2) {
+  return text2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isMentioned(combinedDocs, name) {
+  const re = new RegExp(
+    `(^|[^A-Za-z0-9_-])${escapeRegExp(name)}(/|[^A-Za-z0-9_-]|$)`,
+    "im"
+  );
+  return re.test(combinedDocs);
+}
+async function checkNewModules(ctx) {
+  const result = emptyResult();
+  if (ctx.docs.length === 0) return result;
+  const combinedDocs = moduleDocumentation(ctx.docs);
+  const primaryDoc = ctx.docs[0].path;
+  const checkedDocs = ctx.docs.map((d) => d.path);
+  const flag = async (dir, sourceFileCount) => {
+    result.advisories.push({
+      resolution: "recheck",
+      type: "new-module",
+      message: `directory \`${dir}/\` contains ${sourceFileCount} source file${sourceFileCount === 1 ? "" : "s"} but is not mentioned in the discovered documentation; review whether it needs documenting`,
+      anchor: { doc: primaryDoc, line: null, excerpt: dir },
+      evidence: {
+        kind: "unmentioned-dir",
+        dir,
+        sourceFileCount,
+        firstCommit: await firstCommitOf(ctx.root, dir),
+        checkedDocs
+      }
+    });
+  };
+  for (const candidate of await moduleCandidates(ctx.root, combinedDocs)) {
+    await flag(candidate.dir, candidate.sourceFileCount);
+  }
+  return result;
+}
+function moduleDocumentation(docs) {
+  return docs.map((doc) => doc.content + "\n" + (path12.posix.dirname(doc.path) === "." ? "" : path12.posix.dirname(doc.path) + "/")).join("\n");
+}
+async function moduleCandidates(root, combinedDocs) {
+  const [config, sourcePaths] = await Promise.all([loadProjectConfig(root), gitSourcePaths(root)]);
+  const ignore = [...SOURCE_IGNORE, ...config.ignore ?? []];
+  const sources = sourcePaths.filter((file) => !file.split("/").some((part) => part.startsWith(".")));
+  const listSubdirs = async (dir) => {
+    const entries = await fs7.readdir(await auditInputPath(root, dir), { withFileTypes: true });
+    const dirs = entries.filter((entry) => (entry.isDirectory() || entry.isSymbolicLink() && sources.some((file) => file.startsWith(path12.posix.join(dir, entry.name) + "/"))) && !entry.name.startsWith(".") && !DIR_DENYLIST.has(entry.name)).map((entry) => path12.posix.join(dir, entry.name));
+    const ignored = await gitIgnoredPaths(root, dirs);
+    const visible = new Set(dirs.filter((dir2) => !ignored.has(dir2) || sources.some((file) => file.startsWith(dir2 + "/"))));
+    return (await auditGlob(root, dir === "." ? "*" : `${fg4.escapePath(dir)}/*`, {
+      ignore,
+      onlyDirectories: true,
+      label: "Module directory discovery",
+      select: (file) => visible.has(file)
+    })).map((file) => path12.posix.basename(file));
   };
   const countSourceFiles = async (dir) => {
     const files = sources.filter((file) => file.startsWith(dir + "/"));
-    let count2 = 0;
+    let count3 = 0;
     for (let offset = 0; offset < files.length; offset += 256) {
-      count2 += (await auditGlob(root, files.slice(offset, offset + 256).map((file) => fg3.escapePath(file)), {
+      count3 += (await auditGlob(root, files.slice(offset, offset + 256).map((file) => fg4.escapePath(file)), {
         ignore,
         followSymbolicLinks: false,
         label: `Source discovery in ${dir}`
       })).length;
-      if (count2 > 1e5) throw new Error(`Source discovery in ${dir} exceeds 100,000 relevant files. Exclude generated source with .mason/config.json ignore patterns or narrow this audit's checks.`);
+      if (count3 > 1e5) throw new Error(`Source discovery in ${dir} exceeds 100,000 relevant files. Exclude generated source with .mason/config.json ignore patterns or narrow this audit's checks.`);
     }
-    return count2;
+    return count3;
   };
   const candidates = [];
   for (const topDir of await listSubdirs(".")) {
     const topMentioned = isMentioned(combinedDocs, topDir);
     if (!topMentioned) {
-      const count2 = await countSourceFiles(topDir);
-      if (count2 >= 1) candidates.push({ dir: topDir, sourceFileCount: count2 });
+      const count3 = await countSourceFiles(topDir);
+      if (count3 >= 1) candidates.push({ dir: topDir, sourceFileCount: count3 });
       continue;
     }
     const subdirs = await listSubdirs(topDir);
@@ -986,18 +1230,48 @@ async function moduleCandidates(root, combinedDocs) {
     if (mentioned.length < ENUMERATION_THRESHOLD) continue;
     for (const sub of subdirs) {
       if (isMentioned(combinedDocs, sub)) continue;
-      const count2 = await countSourceFiles(`${topDir}/${sub}`);
-      if (count2 >= SECOND_LEVEL_MIN_SOURCE_FILES) {
-        candidates.push({ dir: `${topDir}/${sub}`, sourceFileCount: count2 });
+      const count3 = await countSourceFiles(`${topDir}/${sub}`);
+      if (count3 >= SECOND_LEVEL_MIN_SOURCE_FILES) {
+        candidates.push({ dir: `${topDir}/${sub}`, sourceFileCount: count3 });
       }
     }
   }
   return candidates;
 }
+var DIR_DENYLIST, SECOND_LEVEL_MIN_SOURCE_FILES, ENUMERATION_THRESHOLD;
+var init_new_module = __esm({
+  "src/audit/checks/new-module.ts"() {
+    "use strict";
+    init_files();
+    init_inputs();
+    init_git();
+    init_checks();
+    DIR_DENYLIST = /* @__PURE__ */ new Set([
+      "node_modules",
+      "dist",
+      "build",
+      "out",
+      "coverage",
+      "target",
+      "vendor",
+      "__pycache__",
+      "venv",
+      ".venv",
+      ".git",
+      ".gradle",
+      ".mason",
+      ".claude",
+      ".github",
+      ".vscode",
+      ".idea"
+    ]);
+    SECOND_LEVEL_MIN_SOURCE_FILES = 2;
+    ENUMERATION_THRESHOLD = 2;
+  }
+});
 
 // src/audit/checks/stale-count.ts
-import path11 from "path";
-var MEMBERS_CAP = 50;
+import path13 from "path";
 async function countGradleModules(root) {
   for (const name of ["settings.gradle.kts", "settings.gradle"]) {
     const content = await readAuditInput(root, name);
@@ -1031,7 +1305,7 @@ async function countNpmWorkspaces(root) {
       return {
         actual: matched.length,
         countedFrom: "package.json workspaces",
-        members: matched.map((m) => path11.dirname(m)).sort()
+        members: matched.map((m) => path13.dirname(m)).sort()
       };
     }
   }
@@ -1062,7 +1336,7 @@ async function countNpmWorkspaces(root) {
       return {
         actual: matched.length,
         countedFrom: "pnpm-workspace.yaml",
-        members: matched.map((m) => path11.dirname(m)).sort()
+        members: matched.map((m) => path13.dirname(m)).sort()
       };
     }
   }
@@ -1084,8 +1358,8 @@ async function countCargoCrates(root) {
         ignore: ["**/target/**"],
         label: "Cargo workspace discovery"
       });
-      for (const m of matched) members.add(path11.dirname(m));
-    } else if (await readAuditInput(root, path11.posix.join(entry, "Cargo.toml")) !== null) {
+      for (const m of matched) members.add(path13.dirname(m));
+    } else if (await readAuditInput(root, path13.posix.join(entry, "Cargo.toml")) !== null) {
       members.add(entry);
     }
   }
@@ -1103,11 +1377,21 @@ async function resolveCountSource(root, claim) {
   if (unit === "crate") return countCargoCrates(root);
   return await countNpmWorkspaces(root) ?? await countCargoCrates(root) ?? await countGradleModules(root);
 }
+async function resolveDocCountSource(root, doc, claim) {
+  const scope = documentScope(doc);
+  const source = await resolveCountSource(path13.join(root, scope), claim);
+  if (!source || scope === ".") return source;
+  return {
+    ...source,
+    countedFrom: scope + "/" + source.countedFrom,
+    members: source.members.map((member) => scope + "/" + member)
+  };
+}
 async function checkStaleCounts(ctx) {
   const result = emptyResult();
   for (const doc of ctx.docs) {
     for (const claim of doc.claims.counts) {
-      const source = await resolveCountSource(ctx.root, claim);
+      const source = await resolveDocCountSource(ctx.root, doc.path, claim);
       if (source === null) {
         result.skipped.push({
           check: "stale-count",
@@ -1135,64 +1419,106 @@ async function checkStaleCounts(ctx) {
   }
   return result;
 }
+var MEMBERS_CAP;
+var init_stale_count = __esm({
+  "src/audit/checks/stale-count.ts"() {
+    "use strict";
+    init_docs();
+    init_inputs();
+    init_checks();
+    MEMBERS_CAP = 50;
+  }
+});
 
 // src/audit/checks/dead-command.ts
-var AVAILABLE_SCRIPTS_CAP = 30;
-async function scriptsOf(root, manifest) {
-  const raw = await readAuditInput(root, manifest);
-  if (raw === null) return null;
+import path14 from "path";
+function scriptsOf(raw) {
   try {
     const pkg = JSON.parse(raw);
-    return pkg && typeof pkg.scripts === "object" && pkg.scripts !== null ? Object.keys(pkg.scripts) : [];
+    if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return null;
+    if (pkg.scripts === void 0) return [];
+    return pkg.scripts && typeof pkg.scripts === "object" && !Array.isArray(pkg.scripts) && Object.values(pkg.scripts).every((value) => typeof value === "string") ? Object.keys(pkg.scripts) : null;
   } catch {
     return null;
   }
 }
-async function checkDeadCommands(ctx) {
-  const result = emptyResult();
-  const commandClaims = ctx.docs.flatMap(
-    (doc) => doc.claims.commands.map((claim) => ({ doc, claim }))
-  );
-  if (commandClaims.length === 0) return result;
-  const rootScripts = await scriptsOf(ctx.root, "package.json");
-  if (rootScripts === null) {
-    result.skipped.push({
-      check: "dead-command",
-      reason: "no package.json at the repo root"
-    });
-    return result;
-  }
-  const rootSet = new Set(rootScripts);
-  let workspaceScripts = null;
-  let manifestsChecked = ["package.json"];
-  const loadWorkspaceScripts = async () => {
-    if (workspaceScripts !== null) return workspaceScripts;
-    workspaceScripts = /* @__PURE__ */ new Set();
-    const manifests = await commandManifests(ctx.root);
-    manifestsChecked = ["package.json", ...manifests.sort()];
-    for (const manifest of manifests) {
-      const scripts = await scriptsOf(ctx.root, manifest);
-      for (const name of scripts ?? []) workspaceScripts.add(name);
-    }
-    return workspaceScripts;
+async function commandInputs(root, docs) {
+  const contents = /* @__PURE__ */ new Map();
+  const read = async (file) => {
+    if (!contents.has(file)) contents.set(file, await readAuditInput(root, file));
+    return contents.get(file);
   };
-  for (const { doc, claim } of commandClaims) {
-    if (rootSet.has(claim.scriptName)) continue;
-    const elsewhere = await loadWorkspaceScripts();
-    if (elsewhere.has(claim.scriptName)) continue;
-    result.issues.push({
-      type: "dead-command",
-      message: `\`${claim.invocation}\` refers to script "${claim.scriptName}", which exists in no package.json`,
-      anchor: { doc: doc.path, line: claim.line, excerpt: claim.excerpt },
-      confidence: "certain",
-      evidence: {
-        kind: "missing-script",
-        scriptName: claim.scriptName,
-        invocation: claim.invocation,
-        manifestsChecked,
-        availableScripts: rootScripts.slice(0, AVAILABLE_SCRIPTS_CAP)
+  await read("package.json");
+  let inventory;
+  const resolutions = [];
+  for (const doc of docs) for (const claim of doc.claims.commands) {
+    const base = documentScope(doc.path);
+    const directory = scopedPath(base, claim.directory ?? ".");
+    const scope = {
+      basis: claim.directory === void 0 ? "document" : "explicit",
+      directory: directory ?? base,
+      candidates: []
+    };
+    const resolution = { doc: doc.path, claim, scope, manifest: null, scripts: [], elsewhere: [] };
+    resolutions.push(resolution);
+    if (claim.scopeUnknown || directory === null) {
+      resolution.problem = claim.scopeUnknown ?? "The command's directory leaves the repository.";
+      continue;
+    }
+    let cursor = directory;
+    while (true) {
+      const manifest = path14.posix.join(cursor, "package.json");
+      scope.candidates.push(manifest);
+      const raw = await read(manifest);
+      if (raw !== null) {
+        resolution.manifest = manifest;
+        const scripts = scriptsOf(raw);
+        if (scripts === null) resolution.problem = "Invalid package manifest: " + manifest;
+        else resolution.scripts = scripts;
+        break;
       }
-    });
+      if (claim.directory !== void 0 || cursor === ".") break;
+      cursor = path14.posix.dirname(cursor);
+    }
+    if (!resolution.manifest && !resolution.problem) {
+      resolution.problem = `No package.json for the command's scope (${directory}).`;
+    }
+    if (resolution.problem || resolution.scripts.includes(claim.scriptName) || claim.directory !== void 0) continue;
+    inventory ??= await commandManifests(root);
+    for (const manifest of [.../* @__PURE__ */ new Set(["package.json", ...inventory])].sort()) {
+      if (scope.candidates.includes(manifest)) continue;
+      scope.candidates.push(manifest);
+      const raw = await read(manifest);
+      if (raw === null) continue;
+      const scripts = scriptsOf(raw);
+      if (scripts === null) resolution.problem = "Cannot establish script availability: invalid manifest " + manifest;
+      else if (scripts.includes(claim.scriptName)) resolution.elsewhere.push(manifest);
+    }
+  }
+  return { manifests: [...contents].sort(([a], [b]) => a.localeCompare(b)), resolutions };
+}
+async function checkDeadCommands(ctx) {
+  const result = emptyResult();
+  const { resolutions } = await commandInputs(ctx.root, ctx.docs);
+  for (const { doc, claim, scope, scripts, elsewhere, problem, manifest } of resolutions) {
+    if (problem) {
+      result.skipped.push({ check: "dead-command", doc, reason: problem });
+      continue;
+    }
+    if (scripts.includes(claim.scriptName)) continue;
+    const evidence = {
+      kind: "missing-script",
+      scriptName: claim.scriptName,
+      invocation: claim.invocation,
+      manifestsChecked: scope.candidates,
+      availableScripts: scripts.slice(0, AVAILABLE_SCRIPTS_CAP),
+      scope
+    };
+    const anchor = { doc, line: claim.line, excerpt: claim.excerpt };
+    const message = `\`${claim.invocation}\` names script "${claim.scriptName}", which is absent from ${manifest}`;
+    const certain = documentScope(doc) === "." && (scope.basis === "explicit" || !elsewhere.length);
+    if (certain) result.issues.push({ type: "dead-command", message, anchor, confidence: "certain", evidence });
+    else result.advisories.push({ resolution: "recheck", type: "dead-command", message: message + (elsewhere.length ? `; it exists in ${elsewhere.join(", ")}. Clarify the intended working directory.` : "; the intended working directory needs review."), anchor, evidence });
   }
   return result;
 }
@@ -1202,23 +1528,33 @@ function commandManifests(root) {
     label: "Command manifest discovery"
   });
 }
+var AVAILABLE_SCRIPTS_CAP;
+var init_dead_command = __esm({
+  "src/audit/checks/dead-command.ts"() {
+    "use strict";
+    init_inputs();
+    init_docs();
+    init_scope();
+    init_checks();
+    AVAILABLE_SCRIPTS_CAP = 30;
+  }
+});
 
 // src/audit/release-metadata.ts
 import { execFile as execFile7 } from "child_process";
 import { promisify as promisify7 } from "util";
-var exec6 = promisify7(execFile7);
 async function git(root, args) {
   return (await exec6("git", args, { cwd: root, timeout: 1e4, maxBuffer: 2 * 1024 * 1024 })).stdout;
 }
 function withoutAndroidReleaseValues(text2) {
   if (/\/\*|"""|'''/.test(text2) || !/id\s*\(?\s*["']com\.android\.(application|library)["']/.test(text2)) return null;
-  const scopes = [];
+  const scopes2 = [];
   const normalized = [];
   let assignments = 0;
   for (const line of text2.split("\n")) {
     const code = line.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\/\/.*$/g, (token) => token.startsWith("//") ? "" : '""');
     const assignment = line.match(/^(\s*)(versionName|versionCode)(\s*(?:=\s*|\s+))("[A-Za-z0-9._+-]+"|'[A-Za-z0-9._+-]+'|\d+)(\s*)$/);
-    if (assignment && scopes.join("/") === "android/defaultConfig" && (assignment[2] === "versionCode" ? /^\d+$/.test(assignment[4]) : /^["']/.test(assignment[4]))) {
+    if (assignment && scopes2.join("/") === "android/defaultConfig" && (assignment[2] === "versionCode" ? /^\d+$/.test(assignment[4]) : /^["']/.test(assignment[4]))) {
       normalized.push(assignment[1] + assignment[2] + assignment[3] + "<release-value>" + assignment[5]);
       assignments++;
     } else {
@@ -1227,12 +1563,12 @@ function withoutAndroidReleaseValues(text2) {
     }
     const named = code.match(/^\s*(android|defaultConfig)\s*\{\s*$/)?.[1];
     for (const brace of code.matchAll(/[{}]/g)) {
-      if (brace[0] === "{") scopes.push(named ?? "unknown");
-      else if (!scopes.length) return null;
-      else scopes.pop();
+      if (brace[0] === "{") scopes2.push(named ?? "unknown");
+      else if (!scopes2.length) return null;
+      else scopes2.pop();
     }
   }
-  return assignments && !scopes.length ? normalized.join("\n") : null;
+  return assignments && !scopes2.length ? normalized.join("\n") : null;
 }
 async function releaseMetadataOnly(root, commit) {
   if (!commit.files.length || !commit.files.every((file) => /(^|\/)build\.gradle(?:\.kts)?$/.test(file))) return false;
@@ -1254,23 +1590,21 @@ async function releaseMetadataOnly(root, commit) {
     return false;
   }
 }
+var exec6;
+var init_release_metadata = __esm({
+  "src/audit/release-metadata.ts"() {
+    "use strict";
+    exec6 = promisify7(execFile7);
+  }
+});
 
 // src/audit/checks/deps-changed.ts
-var MANIFEST_COMMITS_CAP = 10;
-var MANIFEST_PATHSPECS = [
-  ":(glob)**/package.json",
-  ":(glob)**/build.gradle.kts",
-  ":(glob)**/build.gradle",
-  "settings.gradle.kts",
-  "settings.gradle",
-  "gradle/libs.versions.toml",
-  ":(glob)**/Cargo.toml",
-  "go.mod",
-  "pyproject.toml",
-  "requirements.txt",
-  "Gemfile",
-  "composer.json"
-];
+function manifestPathspecs(doc) {
+  const scope = documentScope(doc);
+  if (scope === ".") return MANIFEST_PATHSPECS;
+  const escaped = scope.replace(/[\\*?\[\]]/g, "\\$&");
+  return MANIFEST_PATHSPECS.map((spec) => spec.startsWith(":(glob)") ? ":(glob)" + escaped + "/" + spec.slice(":(glob)".length) : ":(literal)" + scope + "/" + spec);
+}
 async function checkDepsChanged(ctx) {
   const result = emptyResult();
   result.suppressedAdvisories = [];
@@ -1294,7 +1628,7 @@ async function checkDepsChanged(ctx) {
     const range = await commitsTouchingSince(
       ctx.root,
       doc.lastCommit.hash,
-      MANIFEST_PATHSPECS
+      manifestPathspecs(doc.path)
     );
     if (range === null) {
       result.skipped.push({
@@ -1329,111 +1663,49 @@ async function checkDepsChanged(ctx) {
   }
   return result;
 }
-
-// src/decisions/drift.ts
-import path14 from "path";
-
-// src/decisions/decisions.ts
-import fs8 from "fs/promises";
-import path13 from "path";
-import { createHash } from "crypto";
+var MANIFEST_COMMITS_CAP, MANIFEST_PATHSPECS;
+var init_deps_changed = __esm({
+  "src/audit/checks/deps-changed.ts"() {
+    "use strict";
+    init_docs();
+    init_release_metadata();
+    init_git();
+    init_checks();
+    MANIFEST_COMMITS_CAP = 10;
+    MANIFEST_PATHSPECS = [
+      ":(glob)**/package.json",
+      ":(glob)**/build.gradle.kts",
+      ":(glob)**/build.gradle",
+      "settings.gradle.kts",
+      "settings.gradle",
+      "gradle/libs.versions.toml",
+      ":(glob)**/Cargo.toml",
+      "go.mod",
+      "pyproject.toml",
+      "requirements.txt",
+      "Gemfile",
+      "composer.json"
+    ];
+  }
+});
 
 // src/context/lexical.ts
-import path12 from "path";
+import path15 from "path";
+var init_lexical = __esm({
+  "src/context/lexical.ts"() {
+    "use strict";
+  }
+});
+
+// src/context/trust.ts
+var init_trust = __esm({
+  "src/context/trust.ts"() {
+    "use strict";
+  }
+});
 
 // src/decisions/provenance.ts
 import { z as z2 } from "zod";
-var text = (max) => z2.string().trim().min(1).max(max);
-var decisionSourceSchema = z2.object({
-  kind: z2.enum(["pull_request", "issue", "incident", "discussion", "document", "other"]),
-  reference: text(1e3),
-  note: text(500).optional()
-}).strict();
-var attributionSchema = z2.object({
-  owner: text(200).nullable().optional(),
-  sources: z2.array(decisionSourceSchema).max(20).optional(),
-  actor: text(200).optional()
-});
-var contentSchema = z2.object({
-  title: z2.string().min(1),
-  body: z2.string().min(1),
-  category: z2.enum(["decision", "gotcha", "deprecation", "convention"]),
-  files: z2.array(z2.string().refine((f) => normalizeRepoPath(f) !== null)),
-  owner: text(200).optional(),
-  sources: z2.array(decisionSourceSchema).max(20)
-});
-var approvalSchema = z2.enum(["unreviewed", "proposed", "accepted"]);
-var statusSchema = z2.enum(["active", "superseded", "retired"]);
-var reviewEvidenceSchema = z2.object({
-  baseHash: z2.string(),
-  headHash: z2.string(),
-  historyAvailable: z2.boolean(),
-  changedFiles: z2.array(z2.string()),
-  localChanges: z2.array(z2.string())
-});
-var eventSchema = z2.object({
-  kind: z2.enum(["imported", "created", "revised", "accepted", "reaffirmed", "retired", "superseded"]),
-  at: z2.string().datetime(),
-  actor: text(200).optional(),
-  note: text(1500).optional(),
-  revision: z2.number().int().positive(),
-  content: contentSchema,
-  approval: approvalSchema,
-  status: statusSchema,
-  refreshedHash: z2.string(),
-  evidence: reviewEvidenceSchema.optional()
-});
-var legacySchema = z2.object({
-  version: z2.literal(1),
-  id: z2.string().regex(/^[a-zA-Z0-9_-]+$/),
-  title: z2.string().min(1),
-  body: z2.string().min(1),
-  category: contentSchema.shape.category,
-  files: contentSchema.shape.files,
-  createdAt: z2.string(),
-  updatedAt: z2.string(),
-  refreshedHash: z2.string(),
-  status: z2.enum(["active", "superseded"]),
-  supersededBy: z2.string().optional()
-}).passthrough();
-var currentSchema = legacySchema.extend({
-  version: z2.literal(2),
-  status: statusSchema,
-  approval: approvalSchema,
-  revision: z2.number().int().positive(),
-  owner: text(200).optional(),
-  sources: z2.array(decisionSourceSchema).max(20),
-  history: z2.array(eventSchema).min(1)
-}).superRefine((record, ctx) => {
-  const invalid = (message) => ctx.addIssue({ code: "custom", message });
-  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-  let previous;
-  for (const event of record.history) {
-    if (!previous) {
-      if (!["created", "imported"].includes(event.kind) || event.revision !== 1) invalid("History must begin with creation or legacy import at revision 1");
-      if (event.approval !== (event.kind === "created" ? "proposed" : "unreviewed")) invalid("Initial records cannot claim acceptance");
-    } else {
-      if (["created", "imported"].includes(event.kind)) invalid("History cannot restart");
-      if (previous.status !== "active") invalid("Archived decisions cannot be changed");
-      if (event.revision !== previous.revision + (event.kind === "revised" ? 1 : 0)) invalid("Invalid revision sequence");
-      if (event.kind !== "revised" && !same(event.content, previous.content)) invalid("A review cannot silently revise decision content");
-      if (event.kind === "reaffirmed" && previous.approval !== "accepted") invalid("Only accepted decisions can be reaffirmed");
-      if (event.kind === "accepted" && previous.approval === "accepted") invalid("Use reaffirmation for an accepted decision");
-      const approval = event.kind === "revised" ? "proposed" : ["accepted", "reaffirmed"].includes(event.kind) ? "accepted" : previous.approval;
-      if (event.approval !== approval) invalid("Approval disagrees with review history");
-      if (!["accepted", "reaffirmed"].includes(event.kind) && event.refreshedHash !== previous.refreshedHash) invalid("Only a review can refresh the evidence baseline");
-    }
-    if (event.kind !== "imported" && event.status !== (event.kind === "retired" ? "retired" : event.kind === "superseded" ? "superseded" : "active")) invalid("Lifecycle disagrees with history");
-    if (["accepted", "reaffirmed", "retired"].includes(event.kind) && (!event.actor || !event.note || !event.evidence)) invalid("Reviews require a named reviewer, reason, and code evidence");
-    if (["accepted", "reaffirmed"].includes(event.kind)) {
-      if (!event.content.owner || !event.content.sources.length) invalid("Accepted decisions require an owner and source");
-      if (!event.evidence || !/^[a-f0-9]{40,64}$/.test(event.evidence.headHash) || event.refreshedHash !== event.evidence.headHash || event.evidence.localChanges.length) invalid("Acceptance requires a committed evidence baseline");
-    }
-    previous = event;
-  }
-  if (!previous || !same(previous.content, decisionContent(record)) || previous.approval !== record.approval || previous.status !== record.status || previous.revision !== record.revision || previous.refreshedHash !== record.refreshedHash) invalid("Decision does not match the final history event");
-});
-var decisionSchema = z2.union([legacySchema, currentSchema]);
 function decisionContent(record) {
   return {
     title: record.title,
@@ -1477,8 +1749,111 @@ function decisionProvenance(record, freshness = "unknown") {
     lastReview: review ? { reviewer: review.actor, at: review.at, note: review.note, gitHash: review.refreshedHash } : null
   };
 }
+var text, decisionSourceSchema, attributionSchema, contentSchema, approvalSchema, statusSchema, reviewEvidenceSchema, eventSchema, legacySchema, currentSchema, decisionSchema;
+var init_provenance = __esm({
+  "src/decisions/provenance.ts"() {
+    "use strict";
+    init_paths();
+    init_trust();
+    text = (max) => z2.string().trim().min(1).max(max);
+    decisionSourceSchema = z2.object({
+      kind: z2.enum(["pull_request", "issue", "incident", "discussion", "document", "other"]),
+      reference: text(1e3),
+      note: text(500).optional()
+    }).strict();
+    attributionSchema = z2.object({
+      owner: text(200).nullable().optional(),
+      sources: z2.array(decisionSourceSchema).max(20).optional(),
+      actor: text(200).optional()
+    });
+    contentSchema = z2.object({
+      title: z2.string().min(1),
+      body: z2.string().min(1),
+      category: z2.enum(["decision", "gotcha", "deprecation", "convention"]),
+      files: z2.array(z2.string().refine((f) => normalizeRepoPath(f) !== null)),
+      owner: text(200).optional(),
+      sources: z2.array(decisionSourceSchema).max(20)
+    });
+    approvalSchema = z2.enum(["unreviewed", "proposed", "accepted"]);
+    statusSchema = z2.enum(["active", "superseded", "retired"]);
+    reviewEvidenceSchema = z2.object({
+      baseHash: z2.string(),
+      headHash: z2.string(),
+      historyAvailable: z2.boolean(),
+      changedFiles: z2.array(z2.string()),
+      localChanges: z2.array(z2.string())
+    });
+    eventSchema = z2.object({
+      kind: z2.enum(["imported", "created", "revised", "accepted", "reaffirmed", "retired", "superseded"]),
+      at: z2.string().datetime(),
+      actor: text(200).optional(),
+      note: text(1500).optional(),
+      revision: z2.number().int().positive(),
+      content: contentSchema,
+      approval: approvalSchema,
+      status: statusSchema,
+      refreshedHash: z2.string(),
+      evidence: reviewEvidenceSchema.optional()
+    });
+    legacySchema = z2.object({
+      version: z2.literal(1),
+      id: z2.string().regex(/^[a-zA-Z0-9_-]+$/),
+      title: z2.string().min(1),
+      body: z2.string().min(1),
+      category: contentSchema.shape.category,
+      files: contentSchema.shape.files,
+      createdAt: z2.string(),
+      updatedAt: z2.string(),
+      refreshedHash: z2.string(),
+      status: z2.enum(["active", "superseded"]),
+      supersededBy: z2.string().optional()
+    }).passthrough();
+    currentSchema = legacySchema.extend({
+      version: z2.literal(2),
+      status: statusSchema,
+      approval: approvalSchema,
+      revision: z2.number().int().positive(),
+      owner: text(200).optional(),
+      sources: z2.array(decisionSourceSchema).max(20),
+      history: z2.array(eventSchema).min(1)
+    }).superRefine((record, ctx) => {
+      const invalid = (message) => ctx.addIssue({ code: "custom", message });
+      const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+      let previous;
+      for (const event of record.history) {
+        if (!previous) {
+          if (!["created", "imported"].includes(event.kind) || event.revision !== 1) invalid("History must begin with creation or legacy import at revision 1");
+          if (event.approval !== (event.kind === "created" ? "proposed" : "unreviewed")) invalid("Initial records cannot claim acceptance");
+        } else {
+          if (["created", "imported"].includes(event.kind)) invalid("History cannot restart");
+          if (previous.status !== "active") invalid("Archived decisions cannot be changed");
+          if (event.revision !== previous.revision + (event.kind === "revised" ? 1 : 0)) invalid("Invalid revision sequence");
+          if (event.kind !== "revised" && !same(event.content, previous.content)) invalid("A review cannot silently revise decision content");
+          if (event.kind === "reaffirmed" && previous.approval !== "accepted") invalid("Only accepted decisions can be reaffirmed");
+          if (event.kind === "accepted" && previous.approval === "accepted") invalid("Use reaffirmation for an accepted decision");
+          const approval = event.kind === "revised" ? "proposed" : ["accepted", "reaffirmed"].includes(event.kind) ? "accepted" : previous.approval;
+          if (event.approval !== approval) invalid("Approval disagrees with review history");
+          if (!["accepted", "reaffirmed"].includes(event.kind) && event.refreshedHash !== previous.refreshedHash) invalid("Only a review can refresh the evidence baseline");
+        }
+        if (event.kind !== "imported" && event.status !== (event.kind === "retired" ? "retired" : event.kind === "superseded" ? "superseded" : "active")) invalid("Lifecycle disagrees with history");
+        if (["accepted", "reaffirmed", "retired"].includes(event.kind) && (!event.actor || !event.note || !event.evidence)) invalid("Reviews require a named reviewer, reason, and code evidence");
+        if (["accepted", "reaffirmed"].includes(event.kind)) {
+          if (!event.content.owner || !event.content.sources.length) invalid("Accepted decisions require an owner and source");
+          if (!event.evidence || !/^[a-f0-9]{40,64}$/.test(event.evidence.headHash) || event.refreshedHash !== event.evidence.headHash || event.evidence.localChanges.length) invalid("Acceptance requires a committed evidence baseline");
+        }
+        previous = event;
+      }
+      if (!previous || !same(previous.content, decisionContent(record)) || previous.approval !== record.approval || previous.status !== record.status || previous.revision !== record.revision || previous.refreshedHash !== record.refreshedHash) invalid("Decision does not match the final history event");
+    });
+    decisionSchema = z2.union([legacySchema, currentSchema]);
+  }
+});
 
 // src/decisions/decisions.ts
+import fs8 from "fs/promises";
+import path16 from "path";
+import { createHash } from "crypto";
+import { z as z3 } from "zod";
 async function loadDecisionStore(rootDir) {
   const records = [];
   const diagnostics = [];
@@ -1502,10 +1877,34 @@ async function loadDecisionStore(rootDir) {
   }
   return { records, diagnostics };
 }
+var TITLE_MAX_CHARS, BODY_RECOMMENDED_CHARS, BODY_MAX_CHARS, boundedText, decisionTitleSchema, decisionBodySchema;
+var init_decisions = __esm({
+  "src/decisions/decisions.ts"() {
+    "use strict";
+    init_storage();
+    init_paths();
+    init_snapshot();
+    init_lexical();
+    init_provenance();
+    TITLE_MAX_CHARS = 80;
+    BODY_RECOMMENDED_CHARS = 1500;
+    BODY_MAX_CHARS = 2500;
+    boundedText = (field, max, hint) => z3.string({
+      errorMap: (issue, ctx) => ({ message: issue.code === "too_big" ? `${field} has ${ctx.data.length} characters; maximum is ${max} (${ctx.data.length - max} over). ${hint}` : ctx.defaultError })
+    }).trim().min(1, `${field} must be non-empty`).max(max);
+    decisionTitleSchema = boundedText("title", TITLE_MAX_CHARS, "Tighten it to a specific headline.");
+    decisionBodySchema = boundedText(
+      "body",
+      BODY_MAX_CHARS,
+      `Aim for ${BODY_RECOMMENDED_CHARS} characters or fewer. Preserve the rule, reason, and exceptions; put supporting references in sources.`
+    );
+  }
+});
 
 // src/decisions/drift.ts
+import path17 from "path";
 async function computeDecisionDrift(rootDir, decisions) {
-  const resolvedRoot = path14.resolve(rootDir);
+  const resolvedRoot = path17.resolve(rootDir);
   const store = decisions ? { records: decisions, diagnostics: [] } : await loadDecisionStore(resolvedRoot);
   const report = { historyAvailable: true, totalDecisions: store.records.length, staleDecisions: {}, freshness: {}, diagnostics: store.diagnostics };
   const [head, workingTree] = await Promise.all([getCurrentGitHash(resolvedRoot), getWorkingTree(resolvedRoot)]);
@@ -1533,6 +1932,16 @@ async function computeDecisionDrift(rootDir, decisions) {
   }
   return report;
 }
+var init_drift2 = __esm({
+  "src/decisions/drift.ts"() {
+    "use strict";
+    init_drift();
+    init_paths();
+    init_snapshot();
+    init_decisions();
+    init_provenance();
+  }
+});
 
 // src/audit/checks/decision-anchor.ts
 async function checkDecisionAnchors(ctx) {
@@ -1576,180 +1985,50 @@ async function checkDecisionAnchors(ctx) {
   }
   return result;
 }
+var init_decision_anchor = __esm({
+  "src/audit/checks/decision-anchor.ts"() {
+    "use strict";
+    init_drift2();
+    init_decisions();
+    init_provenance();
+    init_checks();
+  }
+});
 
 // src/audit/checks/index.ts
-var CHECKS = {
-  "deleted-reference": checkDeletedReferences,
-  "new-module": checkNewModules,
-  "stale-count": checkStaleCounts,
-  "dead-command": checkDeadCommands,
-  "deps-changed": checkDepsChanged,
-  "decision-anchor-drift": checkDecisionAnchors
-};
 function emptyResult() {
   return { issues: [], advisories: [], skipped: [] };
 }
-
-// src/audit/audit.ts
-async function computeAudit(rootDir, options = {}) {
-  const resolvedRoot = path15.resolve(rootDir);
-  const [docs, headHash] = await Promise.all([discoverDocs(resolvedRoot), getCurrentGitHash(resolvedRoot)]);
-  if (docs.length === 0) return null;
-  const report = {
-    version: 1,
-    root: resolvedRoot,
-    gitAvailable: headHash !== "unknown",
-    headHash,
-    checksRun: [],
-    docs: docs.map((d) => ({
-      path: d.path,
-      lastCommit: d.lastCommit,
-      dirty: d.dirty,
-      lineCount: d.lineCount
-    })),
-    decisionsChecked: false,
-    issues: [],
-    advisories: [],
-    suppressedAdvisories: [],
-    skippedChecks: [],
-    clean: true
-  };
-  if (!report.gitAvailable) return report;
-  const changesSinceDoc = /* @__PURE__ */ new Map();
-  for (const doc of docs) {
-    changesSinceDoc.set(
-      doc.path,
-      doc.lastCommit ? await getChangesWithStatus(resolvedRoot, doc.lastCommit.hash) : null
-    );
-  }
-  let decisionsPresent = false;
-  try {
-    await fs9.access(path15.join(resolvedRoot, ".mason", "decisions"));
-    decisionsPresent = true;
-  } catch {
-  }
-  report.decisionsChecked = decisionsPresent;
-  const ctx = {
-    root: resolvedRoot,
-    docs,
-    headHash,
-    changesSinceDoc,
-    decisionsPresent
-  };
-  const selected = options.checks ?? ALL_CHECKS;
-  for (const name of ALL_CHECKS) {
-    if (!selected.includes(name)) continue;
-    const { issues, advisories, suppressedAdvisories, skipped } = await (options.runCheck ? options.runCheck(name, ctx) : CHECKS[name](ctx));
-    report.checksRun.push(name);
-    report.issues.push(...issues);
-    report.advisories.push(...advisories);
-    report.suppressedAdvisories.push(...suppressedAdvisories ?? []);
-    report.skippedChecks.push(...skipped);
+var CHECKS;
+var init_checks = __esm({
+  "src/audit/checks/index.ts"() {
+    "use strict";
+    init_deleted_reference();
+    init_new_module();
+    init_stale_count();
+    init_dead_command();
+    init_deps_changed();
+    init_decision_anchor();
+    CHECKS = {
+      "deleted-reference": checkDeletedReferences,
+      "new-module": checkNewModules,
+      "stale-count": checkStaleCounts,
+      "dead-command": checkDeadCommands,
+      "deps-changed": checkDepsChanged,
+      "decision-anchor-drift": checkDecisionAnchors
+    };
   }
-  report.clean = report.issues.length === 0;
-  return report;
-}
-
-// src/audit/repair.ts
-import fs10 from "fs/promises";
-import path16 from "path";
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
-import { z as z3 } from "zod";
-var checkSchema = z3.enum(["deleted-reference", "new-module", "stale-count", "dead-command", "deps-changed", "decision-anchor-drift"]);
-var commitSchema = z3.object({ hash: z3.string().regex(/^[a-f0-9]{40,64}$/), date: z3.string(), subject: z3.string() });
-var anchorSchema = z3.object({ doc: z3.string(), line: z3.number().int().positive().nullable(), excerpt: z3.string().nullable() });
-var count = z3.number().int().nonnegative();
-var evidenceSchema = z3.discriminatedUnion("kind", [
-  z3.object({
-    kind: z3.literal("missing-path"),
-    claimed: z3.string(),
-    renamedTo: z3.string().nullable(),
-    deletedInCommit: commitSchema.nullable(),
-    everTracked: z3.boolean(),
-    parentDirExists: z3.boolean()
-  }),
-  z3.object({
-    kind: z3.literal("unmentioned-dir"),
-    dir: z3.string(),
-    sourceFileCount: count,
-    firstCommit: commitSchema.nullable(),
-    checkedDocs: z3.array(z3.string())
-  }),
-  z3.object({
-    kind: z3.literal("count-mismatch"),
-    claimed: count,
-    actual: count,
-    unit: z3.string(),
-    countedFrom: z3.string(),
-    members: z3.array(z3.string())
-  }),
-  z3.object({
-    kind: z3.literal("missing-script"),
-    scriptName: z3.string(),
-    invocation: z3.string(),
-    manifestsChecked: z3.array(z3.string()),
-    availableScripts: z3.array(z3.string())
-  }),
-  z3.object({
-    kind: z3.literal("doc-behind-manifests"),
-    docLastCommit: commitSchema,
-    manifestCommits: z3.array(commitSchema.extend({ files: z3.array(z3.string()) })),
-    totalCommits: count
-  }),
-  z3.object({
-    kind: z3.literal("decision-anchor"),
-    decisionId: z3.string(),
-    title: z3.string(),
-    changedFiles: z3.array(z3.string()),
-    refreshedHash: z3.string(),
-    provenance: z3.object({}).passthrough().optional()
-  })
-]);
-var findingSchema = z3.object({ message: z3.string(), anchor: anchorSchema, evidence: evidenceSchema });
-var issueSchema = findingSchema.extend({
-  type: z3.enum(["deleted-reference", "new-module", "stale-count", "dead-command"]),
-  confidence: z3.enum(["certain", "likely"])
-});
-var advisorySchema = findingSchema.extend({ type: z3.enum(["deps-changed", "decision-anchor-drift"]) });
-var checkResultSchema = z3.object({
-  issues: z3.array(issueSchema),
-  advisories: z3.array(advisorySchema),
-  suppressedAdvisories: z3.array(advisorySchema).optional(),
-  skipped: z3.array(z3.object({ check: z3.string(), reason: z3.string(), doc: z3.string().optional() }))
 });
-var reportSchema = z3.object({
-  version: z3.literal(1),
-  root: z3.string(),
-  gitAvailable: z3.literal(true),
-  headHash: commitSchema.shape.hash,
-  checksRun: z3.array(checkSchema).nonempty(),
-  docs: z3.array(z3.object({
-    path: z3.enum(DOC_CANDIDATES),
-    lastCommit: commitSchema.nullable(),
-    dirty: z3.boolean(),
-    lineCount: count
-  })).nonempty(),
-  decisionsChecked: z3.boolean(),
-  clean: z3.boolean(),
-  issues: z3.array(issueSchema),
-  advisories: z3.array(advisorySchema),
-  suppressedAdvisories: z3.array(advisorySchema).optional(),
-  skippedChecks: z3.array(z3.object({ check: z3.string(), reason: z3.string(), doc: z3.string().optional() }))
-});
-var baselineSchema = z3.object({
-  kind: z3.literal("mason-audit-repair"),
-  version: z3.literal(1),
-  createdAt: z3.string().datetime(),
-  report: reportSchema,
-  digest: z3.string().regex(/^[a-f0-9]{64}$/)
-});
-var digest = (value) => createHash2("sha256").update(JSON.stringify(value)).digest("hex");
+
+// src/audit/findings.ts
+import { createHash as createHash2 } from "crypto";
+import { z as z4 } from "zod";
 function findingId(finding) {
   const e = finding.evidence;
   let key;
   switch (e.kind) {
     case "missing-path":
-      key = e.claimed;
+      key = e.resolvedPath && e.resolvedPath !== e.claimed ? [e.claimed, e.resolvedPath] : e.claimed;
       break;
     case "unmentioned-dir":
       key = e.dir;
@@ -1758,7 +2037,7 @@ function findingId(finding) {
       key = [e.unit.replace(/s$/, ""), e.countedFrom];
       break;
     case "missing-script":
-      key = e.scriptName;
+      key = e.scope && e.scope.directory !== "." ? [e.scriptName, e.scope.directory] : e.scriptName;
       break;
     case "doc-behind-manifests":
       key = null;
@@ -1769,12 +2048,199 @@ function findingId(finding) {
   }
   return digest([finding.type, finding.anchor.doc, key]);
 }
+var digest, checkSchema, commitSchema, anchorSchema, count, scopeSchema, evidenceSchema, findingSchema, issueSchema, advisorySchema, checkResultSchema;
+var init_findings = __esm({
+  "src/audit/findings.ts"() {
+    "use strict";
+    digest = (value) => createHash2("sha256").update(JSON.stringify(value)).digest("hex");
+    checkSchema = z4.enum(["deleted-reference", "new-module", "stale-count", "dead-command", "deps-changed", "decision-anchor-drift"]);
+    commitSchema = z4.object({ hash: z4.string().regex(/^[a-f0-9]{40,64}$/), date: z4.string(), subject: z4.string() });
+    anchorSchema = z4.object({ doc: z4.string(), line: z4.number().int().positive().nullable(), excerpt: z4.string().nullable() });
+    count = z4.number().int().nonnegative();
+    scopeSchema = z4.object({
+      basis: z4.enum(["repository", "document", "document-link", "explicit"]),
+      directory: z4.string(),
+      candidates: z4.array(z4.string())
+    });
+    evidenceSchema = z4.discriminatedUnion("kind", [
+      z4.object({
+        kind: z4.literal("missing-path"),
+        claimed: z4.string(),
+        renamedTo: z4.string().nullable(),
+        deletedInCommit: commitSchema.nullable(),
+        everTracked: z4.boolean(),
+        parentDirExists: z4.boolean(),
+        resolvedPath: z4.string().optional(),
+        scope: scopeSchema.optional()
+      }),
+      z4.object({
+        kind: z4.literal("unmentioned-dir"),
+        dir: z4.string(),
+        sourceFileCount: count,
+        firstCommit: commitSchema.nullable(),
+        checkedDocs: z4.array(z4.string())
+      }),
+      z4.object({
+        kind: z4.literal("count-mismatch"),
+        claimed: count,
+        actual: count,
+        unit: z4.string(),
+        countedFrom: z4.string(),
+        members: z4.array(z4.string())
+      }),
+      z4.object({
+        kind: z4.literal("missing-script"),
+        scriptName: z4.string(),
+        invocation: z4.string(),
+        manifestsChecked: z4.array(z4.string()),
+        availableScripts: z4.array(z4.string()),
+        scope: scopeSchema.optional()
+      }),
+      z4.object({
+        kind: z4.literal("doc-behind-manifests"),
+        docLastCommit: commitSchema,
+        manifestCommits: z4.array(commitSchema.extend({ files: z4.array(z4.string()) })),
+        totalCommits: count
+      }),
+      z4.object({
+        kind: z4.literal("decision-anchor"),
+        decisionId: z4.string(),
+        title: z4.string(),
+        changedFiles: z4.array(z4.string()),
+        refreshedHash: z4.string(),
+        provenance: z4.object({}).passthrough().optional()
+      })
+    ]);
+    findingSchema = z4.object({ message: z4.string(), anchor: anchorSchema, evidence: evidenceSchema });
+    issueSchema = findingSchema.extend({
+      type: z4.enum(["deleted-reference", "new-module", "stale-count", "dead-command"]),
+      confidence: z4.enum(["certain", "likely"])
+    });
+    advisorySchema = findingSchema.extend({ type: checkSchema, resolution: z4.literal("recheck").optional() });
+    checkResultSchema = z4.object({
+      issues: z4.array(issueSchema),
+      advisories: z4.array(advisorySchema),
+      suppressedAdvisories: z4.array(advisorySchema).optional(),
+      skipped: z4.array(z4.object({ check: z4.string(), reason: z4.string(), doc: z4.string().optional() }))
+    });
+  }
+});
+
+// src/automation/store.ts
+import fs9 from "fs/promises";
+import os from "os";
+import { z as z5 } from "zod";
+async function withLock(root, directory, run, waitMs = 5e3) {
+  const file = await storePath(root, directory + "/lock", true);
+  const deadline = Date.now() + waitMs;
+  let handle;
+  while (!handle) {
+    try {
+      handle = await fs9.open(file, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify({ pid: process.pid, host: os.hostname() }));
+      } catch (error) {
+        await handle.close().catch(() => {
+        });
+        handle = void 0;
+        await fs9.rm(file, { force: true }).catch(() => {
+        });
+        throw error;
+      }
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        const owner = JSON.parse(await fs9.readFile(file, "utf8"));
+        if (owner.host === os.hostname() && Number.isInteger(owner.pid) && owner.pid > 0) {
+          try {
+            process.kill(owner.pid, 0);
+          } catch (probe) {
+            if (probe.code === "ESRCH") {
+              const reclaim = file + ".reclaim";
+              let guard;
+              try {
+                guard = await fs9.open(reclaim, "wx", 384);
+                const current = JSON.parse(await fs9.readFile(file, "utf8"));
+                if (current.pid === owner.pid && current.host === owner.host) await fs9.unlink(file);
+              } finally {
+                if (guard) {
+                  await guard.close();
+                  await fs9.rm(reclaim, { force: true });
+                }
+              }
+            }
+          }
+        }
+      } catch {
+      }
+      if (Date.now() >= deadline) throw new Error("Automation is busy or its lock needs inspection: " + file);
+      await new Promise((resolve) => setTimeout(resolve, 40));
+    }
+  }
+  try {
+    return await run();
+  } finally {
+    await handle.close();
+    await fs9.unlink(file);
+  }
+}
+var hostSchema, stateSchema;
+var init_store = __esm({
+  "src/automation/store.ts"() {
+    "use strict";
+    init_storage();
+    hostSchema = z5.enum(["claude", "codex"]);
+    stateSchema = z5.object({
+      version: z5.literal(1),
+      root: z5.string(),
+      gitDir: z5.string(),
+      branch: z5.string(),
+      baselines: z5.array(z5.object({ path: z5.string(), at: z5.string(), event: z5.string(), fingerprint: z5.string() })).max(128),
+      sessions: z5.record(z5.object({
+        host: hostSchema,
+        seen: z5.string().nullable(),
+        continued: z5.boolean(),
+        initialIssues: z5.array(z5.string()),
+        initialDocs: z5.record(z5.string().nullable()),
+        lastUsed: z5.string(),
+        mutationObserved: z5.boolean(),
+        pending: z5.record(z5.string()),
+        coverageGaps: z5.array(z5.string()),
+        events: z5.record(z5.object({ at: z5.string(), count: z5.number().int().positive() }))
+      })),
+      updatedAt: z5.string(),
+      fingerprint: z5.string().nullable(),
+      latest: z5.string().nullable(),
+      analysis: z5.object({ id: z5.string(), fingerprint: z5.string(), completedAt: z5.number(), path: z5.string() }).optional()
+    });
+  }
+});
+
+// src/audit/repair.ts
+var repair_exports = {};
+__export(repair_exports, {
+  checkResultSchema: () => checkResultSchema,
+  findingId: () => findingId,
+  formatRepairSummary: () => formatRepairSummary,
+  loadRepairBaseline: () => loadRepairBaseline,
+  prepareRepair: () => prepareRepair,
+  repairExitCode: () => repairExitCode,
+  repairFindingSchema: () => repairFindingSchema,
+  verifyRepair: () => verifyRepair
+});
+import fs10 from "fs/promises";
+import path18 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import { z as z6 } from "zod";
+function recheckable(finding) {
+  return !("confidence" in finding) && finding.resolution === "recheck" && ["deleted-reference", "dead-command", "new-module"].includes(finding.type) && ["missing-path", "missing-script", "unmentioned-dir"].includes(finding.evidence.kind);
+}
 function allFindings(report) {
   return [...report.issues, ...report.advisories, ...report.suppressedAdvisories ?? []];
 }
 async function docState(root) {
   const docs = [];
-  for (const doc of DOC_CANDIDATES) {
+  for (const doc of await discoverDocPaths(root)) {
     try {
       const content = await readBoundedFile(await storePath(root, doc), 10 * 1024 * 1024);
       if (content === null) throw new Error("Context file is not regular or exceeds 10 MiB: " + doc);
@@ -1797,7 +2263,7 @@ async function stableAudit(root, checks, options = {}) {
 }
 async function prepareRepair(rootDir, checks = ALL_CHECKS, options = {}) {
   const root = await fs10.realpath(rootDir);
-  const selected = z3.array(checkSchema).nonempty().parse(checks);
+  const selected = z6.array(checkSchema).nonempty().parse(checks);
   const report = await stableAudit(root, selected, options);
   if (!report) throw new Error("No context files found to prepare a repair.");
   if (!report.gitAvailable) throw new Error("Readable Git history is required to prepare a repair.");
@@ -1812,23 +2278,29 @@ async function prepareRepair(rootDir, checks = ALL_CHECKS, options = {}) {
   await writeStoreJson(root, baselinePath, { ...payload, digest: digest(payload) });
   return { version: 1, action: "prepare", baselinePath, report };
 }
-async function verifyRepair(rootDir, baselinePath, options = {}) {
+async function loadRepairBaseline(rootDir, baselinePath) {
   const root = await fs10.realpath(rootDir);
-  const declaredRoot = path16.resolve(rootDir);
-  const relative = path16.isAbsolute(baselinePath) ? path16.relative(isWithinRoot(declaredRoot, baselinePath) ? declaredRoot : root, baselinePath) : baselinePath;
+  const declaredRoot = path18.resolve(rootDir);
+  const relative = path18.isAbsolute(baselinePath) ? path18.relative(isWithinRoot(declaredRoot, baselinePath) ? declaredRoot : root, baselinePath) : baselinePath;
   const stored = baselineSchema.parse(await readStoreJson(root, relative));
   const { digest: savedDigest, ...payload } = stored;
   if (digest(payload) !== savedDigest) throw new Error("Repair baseline was modified; use the original baseline.");
   if (stored.report.root !== root) throw new Error("Repair baseline belongs to a different repository.");
   const original = stored.report;
+  return { root, relative, original };
+}
+async function verifyRepair(rootDir, baselinePath, options = {}) {
+  const { root, relative, original } = await loadRepairBaseline(rootDir, baselinePath);
   const diagnostics = [];
+  let reviewDigest;
   let current = null;
   try {
+    reviewDigest = digest(await advisoryReviewInventory(root));
     current = await stableAudit(root, original.checksRun, options);
     if (!current) diagnostics.push("No context files remain available to audit.");
     else if (!current.gitAvailable) diagnostics.push("Git history is unavailable.");
     for (const doc of original.docs) {
-      if (!original.issues.some((f) => f.anchor.doc === doc.path) || !current?.docs.some((d) => d.path === doc.path)) continue;
+      if (!allFindings(original).some((f) => f.anchor.doc === doc.path) || !current?.docs.some((d) => d.path === doc.path)) continue;
       const content = await readBoundedFile(await storePath(root, doc.path), 10 * 1024 * 1024);
       if (content === null || !content.trim()) {
         diagnostics.push("Original context file " + doc.path + " is empty or unreadable; losing its claims does not verify a repair.");
@@ -1845,21 +2317,27 @@ async function verifyRepair(rootDir, baselinePath, options = {}) {
   const originalIds = new Set(originalFindings.map(findingId));
   const missingDocs = original.docs.filter((doc) => !current?.docs.some((d) => d.path === doc.path));
   for (const doc of missingDocs) diagnostics.push("Original context file " + doc.path + " is unavailable; removing it does not verify a repair.");
-  const findings = originalFindings.map((finding) => {
+  const findings = await Promise.all(originalFindings.map(async (finding) => {
     const id = findingId(finding);
     const now = currentById.get(id);
     const base = { id, original: finding, ...now ? { current: now } : {} };
     if (diagnostics.length || !current) {
       return { ...base, status: "unverified", reason: "The original audit scope could not be verified. See diagnostics." };
     }
-    if ("confidence" in finding && now) {
+    if (now && ("confidence" in finding || "confidence" in now)) {
       return { ...base, status: "unresolved", reason: "The original check still reports this claim." };
     }
     const skipped = current.skippedChecks.filter((s) => s.check === finding.type && (!s.doc || s.doc === finding.anchor.doc));
     if (!current.checksRun?.includes(finding.type) || skipped.length) {
       return { ...base, status: "unverified", reason: skipped.map((s) => s.reason).join("; ") || "The original check did not run." };
     }
-    if (!("confidence" in finding)) {
+    const review = await assessAdvisory(root, now ?? finding, original.headHash);
+    if (review) {
+      if (review.status === "unverified") return { ...base, review, status: "unverified", reason: review.reason };
+      if (review.status === "current") return { ...base, review, status: "resolved", reason: review.reason };
+      return { ...base, review, status: "review-required", reason: review.reason };
+    }
+    if (!("confidence" in finding) && (!recheckable(finding) || now)) {
       return {
         ...base,
         status: "review-required",
@@ -1867,11 +2345,27 @@ async function verifyRepair(rootDir, baselinePath, options = {}) {
       };
     }
     return { ...base, status: "resolved", reason: "The original check ran and no longer reports this claim. Inspect the edit for semantic correctness." };
-  });
+  }));
+  try {
+    if (reviewDigest !== digest(await advisoryReviewInventory(root)) || current?.headHash !== await getCurrentGitHash(root)) {
+      diagnostics.push("HEAD or advisory review records changed during verification; repeat against stable evidence.");
+      for (const finding of findings) {
+        finding.status = "unverified";
+        finding.reason = diagnostics.at(-1);
+      }
+    }
+  } catch (error) {
+    diagnostics.push(String(error));
+    for (const finding of findings) {
+      finding.status = "unverified";
+      finding.reason = "Advisory review evidence became unavailable during verification.";
+    }
+  }
   const newFindings = [...currentById].filter(([id]) => !originalIds.has(id)).map(([, f]) => f);
+  const reviewedIds = new Set(current?.advisoryReviews?.filter((review) => review.status === "current").map((review) => review.id));
   const counts = { resolved: 0, unresolved: 0, "review-required": 0, unverified: 0 };
   for (const f of findings) counts[f.status]++;
-  const incomplete = diagnostics.length > 0 || counts.unverified > 0 || counts["review-required"] > 0 || (current?.skippedChecks.length ?? 0) > 0 || newFindings.some((f) => !("confidence" in f));
+  const incomplete = diagnostics.length > 0 || counts.unverified > 0 || counts["review-required"] > 0 || (current?.skippedChecks.length ?? 0) > 0 || newFindings.some((f) => !("confidence" in f) && !reviewedIds.has(findingId(f)));
   const issuesRemain = counts.unresolved > 0 || newFindings.some((f) => "confidence" in f);
   return {
     version: 1,
@@ -1885,7 +2379,7 @@ async function verifyRepair(rootDir, baselinePath, options = {}) {
     diagnostics,
     currentAudit: current,
     counts,
-    scope: "Original audit checks over current context files and repository evidence. Resolved means no longer detected by that check. Advisories require separate review; this is not a certification of documentation or application correctness."
+    scope: "Original audit checks over current context files and repository evidence. Resolved means no longer detected by the check or covered by an explicit assessment of current evidence; inspect each finding's reason and review. This is not a certification of documentation or application correctness."
   };
 }
 function repairExitCode(report) {
@@ -1894,18 +2388,482 @@ function repairExitCode(report) {
 function formatRepairSummary(report) {
   return [
     "Repair verification: " + report.status + ". Baseline: " + report.baselinePath,
-    ...report.findings.map((f) => "  [" + f.status + "] " + f.original.type + " " + f.original.anchor.doc + ": " + f.original.message + "\n    " + f.reason),
+    ...report.findings.map((f) => "  [" + f.status + "] " + f.original.type + " " + f.original.anchor.doc + ": " + f.original.message + "\n    " + f.reason + "\n    findingId: " + f.id),
     ...report.newFindings.map((f) => "  [new] " + f.type + " " + f.anchor.doc + ": " + f.message),
     ...report.diagnostics.map((d) => "  [unverified] " + d),
     ...(report.currentAudit?.skippedChecks ?? []).map((s) => "  [skipped] " + s.check + ": " + s.reason),
     report.scope
   ].join("\n");
 }
+var count2, reportSchema, baselineSchema, repairFindingSchema;
+var init_repair = __esm({
+  "src/audit/repair.ts"() {
+    "use strict";
+    init_audit();
+    init_docs();
+    init_snapshot();
+    init_drift();
+    init_storage();
+    init_files();
+    init_paths();
+    init_types();
+    init_findings();
+    init_advisory_review();
+    init_findings();
+    count2 = z6.number().int().nonnegative();
+    reportSchema = z6.object({
+      version: z6.literal(1),
+      root: z6.string(),
+      gitAvailable: z6.literal(true),
+      headHash: commitSchema.shape.hash,
+      checksRun: z6.array(checkSchema).nonempty(),
+      docs: z6.array(z6.object({
+        path: z6.string().refine((value) => normalizeRepoPath(value) === value),
+        scope: z6.string().optional(),
+        kind: z6.enum(["instructions", "readme"]).optional(),
+        lastCommit: commitSchema.nullable(),
+        dirty: z6.boolean(),
+        lineCount: count2
+      })).nonempty(),
+      decisionsChecked: z6.boolean(),
+      clean: z6.boolean(),
+      issues: z6.array(issueSchema),
+      advisories: z6.array(advisorySchema),
+      suppressedAdvisories: z6.array(advisorySchema).optional(),
+      skippedChecks: z6.array(z6.object({ check: z6.string(), reason: z6.string(), doc: z6.string().optional() }))
+    });
+    baselineSchema = z6.object({
+      kind: z6.literal("mason-audit-repair"),
+      version: z6.literal(1),
+      createdAt: z6.string().datetime(),
+      report: reportSchema,
+      digest: z6.string().regex(/^[a-f0-9]{64}$/)
+    });
+    repairFindingSchema = z6.object({
+      id: z6.string(),
+      original: z6.union([issueSchema, advisorySchema]),
+      status: z6.enum(["resolved", "unresolved", "review-required", "unverified"]),
+      reason: z6.string(),
+      current: z6.union([issueSchema, advisorySchema]).optional(),
+      review: reviewSummarySchema.optional()
+    });
+  }
+});
+
+// src/audit/advisory-review.ts
+import fs11 from "fs/promises";
+import { execFile as execFile8 } from "child_process";
+import { promisify as promisify8 } from "util";
+import { z as z7 } from "zod";
+async function readRecord(root, id) {
+  const raw = await readStoreJson(root, recordPath(id));
+  if (raw === null) return null;
+  const record = recordSchema.parse(raw);
+  const { digest: stored, ...payload } = record;
+  if (record.id !== id || digest(payload) !== stored || record.events.some((event) => findingId(event.finding) !== id || event.evidence.fingerprint !== digest([event.evidence.scope, event.evidence.tree, event.evidence.lastScopeCommit, event.evidence.paths]))) {
+    throw new Error("Advisory review record is inconsistent or modified; inspect its history.");
+  }
+  return record;
+}
+function scopes(finding) {
+  const files = [finding.anchor.doc], e = finding.evidence;
+  if (e.kind === "decision-anchor") throw new Error("Use review_decision for decision acceptance, reaffirmation or retirement.");
+  if (e.kind === "doc-behind-manifests") return [`:(literal)${finding.anchor.doc}`, ...manifestPathspecs(finding.anchor.doc)];
+  if (e.kind === "missing-path") files.push(...e.scope?.candidates ?? [e.resolvedPath ?? e.claimed]);
+  else if (e.kind === "missing-script") files.push(...e.manifestsChecked, ...e.scope?.candidates ?? []);
+  else if (e.kind === "unmentioned-dir") files.push(e.dir, ...e.checkedDocs);
+  else throw new Error("This advisory has no supported review scope.");
+  return [...new Set(files)].map((file) => {
+    if (normalizeRepoPath(file) !== file) throw new Error("Advisory contains an invalid scoped path: " + file);
+    return `:(literal)${file}`;
+  }).sort();
+}
+async function reviewEvidence(root, finding) {
+  if (normalizeRepoPath(finding.anchor.doc) !== finding.anchor.doc) throw new Error("Invalid advisory document path.");
+  const scope = scopes(finding);
+  const head = (await git2(root, "rev-parse", "HEAD")).trim();
+  const tracked = (await git2(root, "ls-files", "--cached", "-z", "--", ...scope)).split("\0").filter(Boolean);
+  if (tracked.length > 2e4) throw new Error("Advisory scope exceeds 20,000 tracked files.");
+  const [tree, status, lastScopeCommit, document] = await Promise.all([
+    tracked.length ? git2(root, "ls-tree", "-r", "-z", "HEAD", "--", ...tracked.map((file) => `:(literal)${file}`)) : "",
+    git2(root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ...scope),
+    git2(root, "log", "-1", "--format=%H", "HEAD", "--", ...scope).then((value) => value.trim()),
+    readAuditInput(root, finding.anchor.doc)
+  ]);
+  if (!document?.trim()) throw new Error("Original advisory document is missing, empty or unreadable.");
+  if (tree.length > 2 * 1024 * 1024 || tree.split("\0").length > 2e4) throw new Error("Advisory scope is too large for a complete review; narrow the documentation scope.");
+  for (const entry of tree.split("\0").filter(Boolean)) {
+    const tab = entry.indexOf("	"), file = entry.slice(tab + 1);
+    if (entry.startsWith("120000 ") || entry.startsWith("160000 ")) throw new Error("Symlink or submodule in advisory review scope: " + file);
+    await storePath(root, file);
+  }
+  const paths = finding.evidence.kind === "missing-path" ? await Promise.all(
+    (finding.evidence.scope?.candidates ?? [finding.evidence.resolvedPath ?? finding.evidence.claimed]).map(async (file) => ({ path: file, exists: await pathExists(root, file) }))
+  ) : [];
+  let dirty = status.length > 0;
+  if (finding.evidence.kind === "missing-script") {
+    for (const file of [...finding.evidence.manifestsChecked, ...finding.evidence.scope?.candidates ?? []]) {
+      if (!tracked.includes(file) && await pathExists(root, file)) dirty = true;
+    }
+  }
+  const fingerprint = digest([scope, tree, lastScopeCommit, paths]);
+  if ((await git2(root, "rev-parse", "HEAD")).trim() !== head) throw new Error("HEAD changed while collecting review evidence.");
+  return {
+    ...evidenceSchema2.parse({ head, scope, tree, lastScopeCommit, paths, fingerprint }),
+    dirty,
+    documentDigest: digest(document)
+  };
+}
+async function decisionAssessment(root, finding, baselineHead) {
+  const evidence = finding.evidence;
+  if (evidence.kind !== "decision-anchor") return null;
+  const id = findingId(finding);
+  const store = await loadDecisionStore(root);
+  if (store.diagnostics.length) throw new Error("Decision records have unavailable or malformed evidence; review cannot be confirmed.");
+  const record = store.records.find((record2) => record2.id === evidence.decisionId);
+  if (!record || record.version !== 2) return null;
+  const events = record.history.filter((event2) => ["accepted", "reaffirmed", "retired"].includes(event2.kind));
+  const event = events.at(-1);
+  if (!event?.evidence || !event.actor || !event.note || !event.evidence.historyAvailable || event.evidence.localChanges.length) return null;
+  try {
+    await git2(root, "merge-base", "--is-ancestor", baselineHead, event.evidence.headHash);
+  } catch {
+    return null;
+  }
+  const drift = await computeDecisionDrift(root, [record]);
+  if (!drift.historyAvailable) throw new Error("Decision review history is unavailable.");
+  const retired = record.status === "retired" && event.kind === "retired";
+  const current = retired || record.status === "active" && record.approval === "accepted" && drift.freshness?.[record.id] === "current" && !drift.pendingProposals?.[record.id];
+  return {
+    id,
+    status: current ? "current" : "reopened",
+    outcome: event.kind,
+    reviewer: event.actor,
+    note: event.note,
+    reviewedHead: event.evidence.headHash,
+    recordPath: `.mason/decisions/${record.id}.json`,
+    reason: current ? "The existing decision review records acceptance, reaffirmation or retirement covering the original finding." : "Decision content or anchor evidence changed after its review; review the decision again."
+  };
+}
+async function assessAdvisory(root, finding, baselineHead) {
+  if ("confidence" in finding) return null;
+  const id = findingId(finding);
+  try {
+    if (finding.evidence.kind === "decision-anchor") return await decisionAssessment(root, finding, baselineHead);
+    const record = await readRecord(root, id);
+    if (!record) return null;
+    const event = record.events.at(-1);
+    const current = await reviewEvidence(root, event.finding);
+    await git2(root, "merge-base", "--is-ancestor", event.evidence.head, current.head);
+    const base = {
+      id,
+      recordPath: recordPath(id),
+      reviewer: event.reviewer,
+      note: event.note,
+      outcome: event.outcome,
+      reviewedHead: event.evidence.head
+    };
+    if (current.dirty || current.fingerprint !== event.evidence.fingerprint || digest(scopes(finding)) !== digest(event.evidence.scope)) return { ...base, status: "reopened", reason: "Relevant document or repository evidence changed after the assessment; prepare a new review." };
+    return { ...base, status: event.outcome === "deferred" ? "deferred" : "current", reason: event.outcome === "deferred" ? "The review was deferred and remains outstanding." : "An explicit assessment covers the current committed scope. This does not approve an engineering decision or certify correctness." };
+  } catch (error) {
+    return { id, status: "unverified", reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function advisoryReviewInventory(root) {
+  let names;
+  try {
+    names = await fs11.readdir(await storePath(root, ".mason/reviews/advisories"));
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  if (names.length > 5e3) throw new Error("Advisory review inventory exceeds 5,000 records.");
+  return Promise.all(names.filter((name) => name.endsWith(".json")).sort().map(async (name) => [name, await readAuditInput(root, ".mason/reviews/advisories/" + name)]));
+}
+async function reviewAdvisory(rootDir, input) {
+  const root = await fs11.realpath(rootDir), request = advisoryReviewRequest.parse(input);
+  const { loadRepairBaseline: loadRepairBaseline2 } = await Promise.resolve().then(() => (init_repair(), repair_exports));
+  const baseline = await loadRepairBaseline2(root, request.baselinePath);
+  const finding = [...baseline.original.advisories, ...baseline.original.suppressedAdvisories ?? []].find((f) => findingId(f) === request.findingId);
+  if (!finding) throw new Error("No advisory with this findingId in the original baseline. Provable issues must be repaired and rechecked.");
+  if (finding.evidence.kind === "decision-anchor") return {
+    status: "decision-review-required",
+    decisionId: finding.evidence.decisionId,
+    hint: "Use review_decision to prepare evidence and record authorized acceptance, reaffirmation or retirement, then verify this original repair baseline. An advisory assessment cannot approve a decision."
+  };
+  const prepare = async () => {
+    const record = await readRecord(root, request.findingId);
+    const evidence = await reviewEvidence(root, finding);
+    await git2(root, "merge-base", "--is-ancestor", baseline.original.headHash, evidence.head);
+    const token = digest({ baseline: baseline.original, finding, evidence, record });
+    return { record, evidence, token };
+  };
+  if (request.action === "prepare") {
+    const state = await prepare();
+    let diff = null, diffNote;
+    const from = finding.evidence.kind === "doc-behind-manifests" ? finding.evidence.docLastCommit.hash : baseline.original.headHash;
+    try {
+      const full = await git2(root, "diff", "--no-ext-diff", "--no-textconv", "--no-color", "--no-renames", "-U3", from, state.evidence.head, "--", ...state.evidence.scope);
+      diff = full.slice(0, 16e3);
+      if (full.length > diff.length) diffNote = "Diff preview truncated; inspect the full scoped diff before reviewing.";
+    } catch {
+      diffNote = "Diff preview unavailable; inspect the original cited evidence directly before reviewing.";
+    }
+    if ((await prepare()).token !== state.token) throw new Error("Review evidence changed during preparation; retry.");
+    return {
+      status: "prepared",
+      findingId: request.findingId,
+      finding,
+      evidence: state.evidence,
+      history: state.record?.events ?? [],
+      reviewToken: state.token,
+      diff,
+      diffNote,
+      hint: "Inspect the original finding, scoped document and relevant code changes. Record addressed, inapplicable or deferred only when the user or cited project review authorizes that assessment. Supply the actual reviewer, reason in note and reviewToken. Relevant edits must be committed first. Deferral remains outstanding. Review identities are recorded assertions, not authenticated approvals."
+    };
+  }
+  if (!request.reviewer || !request.note || !request.reviewToken) throw new Error("Prepare first; recording an assessment requires reviewToken, reviewer and note.");
+  return withLock(root, ".mason/reports/advisory-review-locks/" + request.findingId, async () => {
+    const state = await prepare();
+    if (state.token !== request.reviewToken) throw new Error("Review conflict: evidence or review history changed since preparation. Prepare and inspect a new review.");
+    if (state.evidence.dirty) throw new Error("Commit relevant document and repository edits before recording the assessment. Unrelated local work may remain.");
+    if ((state.record?.events.length ?? 0) >= 200) throw new Error("Review history limit reached; existing events were retained.");
+    const { dirty, documentDigest, ...evidence } = state.evidence;
+    const event = eventSchema2.parse({
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      reviewer: request.reviewer,
+      note: request.note,
+      outcome: request.action,
+      finding,
+      evidence
+    });
+    const payload = { version: 1, id: request.findingId, events: [...state.record?.events ?? [], event] };
+    if ((await prepare()).token !== state.token) throw new Error("Review conflict: evidence changed while recording the assessment.");
+    await writeStoreJson(root, recordPath(request.findingId), { ...payload, digest: digest(payload) });
+    return {
+      status: "recorded",
+      recordPath: recordPath(request.findingId),
+      event,
+      hint: "Review and commit this assessment record through the normal project workflow, then verify the original repair baseline. Relevant changes reopen the assessment; deferral remains outstanding."
+    };
+  });
+}
+var execute2, git2, hashSchema, commitSchema2, evidenceSchema2, eventSchema2, recordSchema, reviewSummarySchema, advisoryReviewRequest, recordPath;
+var init_advisory_review = __esm({
+  "src/audit/advisory-review.ts"() {
+    "use strict";
+    init_findings();
+    init_deps_changed();
+    init_inputs();
+    init_scope();
+    init_storage();
+    init_paths();
+    init_store();
+    init_decisions();
+    init_drift2();
+    execute2 = promisify8(execFile8);
+    git2 = async (root, ...args) => (await execute2("git", args, { cwd: root, timeout: 1e4, maxBuffer: 8 * 1024 * 1024 })).stdout;
+    hashSchema = z7.string().regex(/^[a-f0-9]{64}$/);
+    commitSchema2 = z7.string().regex(/^[a-f0-9]{40,64}$/);
+    evidenceSchema2 = z7.object({
+      head: commitSchema2,
+      fingerprint: hashSchema,
+      scope: z7.array(z7.string()).min(1).max(1e3),
+      tree: z7.string().max(2 * 1024 * 1024),
+      lastScopeCommit: commitSchema2,
+      paths: z7.array(z7.object({ path: z7.string(), exists: z7.boolean() })).max(1e3)
+    });
+    eventSchema2 = z7.object({
+      at: z7.string().datetime(),
+      reviewer: z7.string().trim().min(1).max(200),
+      note: z7.string().trim().min(1).max(2500),
+      outcome: z7.enum(["addressed", "inapplicable", "deferred"]),
+      finding: advisorySchema.refine((finding) => finding.evidence.kind !== "decision-anchor", "Decision findings use decision reviews"),
+      evidence: evidenceSchema2
+    });
+    recordSchema = z7.object({ version: z7.literal(1), id: hashSchema, events: z7.array(eventSchema2).min(1).max(200), digest: hashSchema });
+    reviewSummarySchema = z7.object({
+      id: hashSchema,
+      status: z7.enum(["current", "reopened", "deferred", "unverified"]),
+      reason: z7.string(),
+      recordPath: z7.string().optional(),
+      reviewer: z7.string().optional(),
+      note: z7.string().optional(),
+      outcome: z7.enum(["addressed", "inapplicable", "deferred", "accepted", "reaffirmed", "retired"]).optional(),
+      reviewedHead: z7.string().optional()
+    });
+    advisoryReviewRequest = z7.object({
+      baselinePath: z7.string().min(1),
+      findingId: hashSchema,
+      action: z7.enum(["prepare", "addressed", "inapplicable", "deferred"]).default("prepare"),
+      reviewer: eventSchema2.shape.reviewer.optional(),
+      note: eventSchema2.shape.note.optional(),
+      reviewToken: hashSchema.optional()
+    });
+    recordPath = (id) => `.mason/reviews/advisories/${hashSchema.parse(id)}.json`;
+  }
+});
+
+// src/audit/audit.ts
+import fs12 from "fs/promises";
+import path19 from "path";
+async function computeAudit(rootDir, options = {}) {
+  const resolvedRoot = path19.resolve(rootDir);
+  const [docs, headHash] = await Promise.all([discoverDocs(resolvedRoot), getCurrentGitHash(resolvedRoot)]);
+  if (docs.length === 0) return null;
+  const report = {
+    version: 1,
+    root: resolvedRoot,
+    gitAvailable: headHash !== "unknown",
+    headHash,
+    checksRun: [],
+    docs: docs.map((d) => ({
+      path: d.path,
+      scope: d.scope,
+      kind: d.kind,
+      lastCommit: d.lastCommit,
+      dirty: d.dirty,
+      lineCount: d.lineCount
+    })),
+    decisionsChecked: false,
+    issues: [],
+    advisories: [],
+    suppressedAdvisories: [],
+    skippedChecks: [],
+    clean: true
+  };
+  if (!report.gitAvailable) return report;
+  const changesSinceDoc = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    changesSinceDoc.set(
+      doc.path,
+      doc.lastCommit ? await getChangesWithStatus(resolvedRoot, doc.lastCommit.hash) : null
+    );
+  }
+  let decisionsPresent = false;
+  try {
+    await fs12.access(path19.join(resolvedRoot, ".mason", "decisions"));
+    decisionsPresent = true;
+  } catch {
+  }
+  report.decisionsChecked = decisionsPresent;
+  const ctx = {
+    root: resolvedRoot,
+    docs,
+    headHash,
+    changesSinceDoc,
+    decisionsPresent
+  };
+  const selected = options.checks ?? ALL_CHECKS;
+  for (const name of ALL_CHECKS) {
+    if (!selected.includes(name)) continue;
+    const { issues, advisories, suppressedAdvisories, skipped } = await (options.runCheck ? options.runCheck(name, ctx) : CHECKS[name](ctx));
+    report.checksRun.push(name);
+    report.issues.push(...issues);
+    report.advisories.push(...advisories);
+    report.suppressedAdvisories.push(...suppressedAdvisories ?? []);
+    report.skippedChecks.push(...skipped);
+  }
+  report.clean = report.issues.length === 0;
+  const reviews = (await Promise.all([...report.advisories, ...report.suppressedAdvisories].map((finding) => assessAdvisory(resolvedRoot, finding, headHash)))).filter((review) => review !== null);
+  if (reviews.length) report.advisoryReviews = reviews;
+  return report;
+}
+var init_audit = __esm({
+  "src/audit/audit.ts"() {
+    "use strict";
+    init_drift();
+    init_snapshot();
+    init_docs();
+    init_types();
+    init_checks();
+    init_advisory_review();
+  }
+});
+
+// src/audit/cli.ts
+init_audit();
+init_types();
+init_repair();
+init_findings();
+import path21 from "path";
+
+// src/audit/advisory-cli.ts
+init_advisory_review();
+import path20 from "path";
+import { stripVTControlCharacters } from "util";
+var USAGE = `Usage: mason audit review --baseline <path> --finding <id> [options]
+
+Prepare an advisory assessment against retained evidence (read-only by default).
+  --dir <path>       Repository root (default: current directory)
+  --baseline <path>  Original repair baseline
+  --finding <id>     findingId from repair verification or automation
+  --outcome <value>  Record addressed, inapplicable, or deferred
+  --reviewer <name>  Actual authorized reviewer
+  --note <reason>    Assessment reason
+  --token <token>    reviewToken returned by preparation
+  --json            Full evidence and review history
+
+Recording requires prior preparation and committed relevant edits. Review records
+belong in Git under .mason/reviews/advisories/. Deferral remains outstanding.
+Decision findings use review_decision; this command never approves decisions.
+Exit 0: prepared/recorded; 2: unavailable, conflict, or decision review required.`;
+async function runAdvisoryCli(args, io = { out: (text2) => console.log(text2), err: (text2) => console.error(text2) }) {
+  if (args.includes("--help") || args.includes("-h")) {
+    io.out(USAGE);
+    return 0;
+  }
+  try {
+    const flags = {};
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--json") {
+        json = true;
+        continue;
+      }
+      if (!["--dir", "--baseline", "--finding", "--outcome", "--reviewer", "--note", "--token"].includes(flag) || flags[flag]) throw new Error("Unexpected or repeated argument: " + flag);
+      const value = args[++i];
+      if (!value || value.startsWith("--")) throw new Error(flag + " requires a value.");
+      flags[flag] = value;
+    }
+    if (!flags["--outcome"] && ["--reviewer", "--note", "--token"].some((key) => flags[key])) throw new Error("Use --outcome to record an assessment.");
+    const input = {
+      baselinePath: flags["--baseline"],
+      findingId: flags["--finding"],
+      action: flags["--outcome"] ?? "prepare",
+      reviewer: flags["--reviewer"],
+      note: flags["--note"],
+      reviewToken: flags["--token"]
+    };
+    const result = await reviewAdvisory(path20.resolve(flags["--dir"] ?? process.cwd()), input);
+    if (json) io.out(JSON.stringify(result, null, 2));
+    else {
+      const lines = [`Advisory review: ${result.status}.`];
+      if ("finding" in result && result.finding && result.evidence) lines.push(
+        `[${result.finding.type}] ${result.finding.anchor.doc}: ${result.finding.message}`,
+        `Finding: ${result.findingId}`,
+        `Prepared against commit ${result.evidence.head.slice(0, 12)}.`,
+        result.evidence.dirty ? "Relevant files have uncommitted edits; commit them and prepare again before recording." : "Relevant files are committed.",
+        `Review token: ${result.reviewToken}`,
+        ...result.diff ? ["Scoped changes:", result.diff] : [],
+        ...result.diffNote ? [result.diffNote] : []
+      );
+      if ("event" in result) lines.push(`${result.event.outcome} \u2014 ${result.event.reviewer}: ${result.event.note}`, `Record: ${result.recordPath}`);
+      lines.push(result.hint);
+      io.out(stripVTControlCharacters(lines.join("\n")));
+    }
+    return result.status === "decision-review-required" ? 2 : 0;
+  } catch (error) {
+    io.err(stripVTControlCharacters(error instanceof Error ? error.message : String(error)));
+    return 2;
+  }
+}
 
 // src/audit/cli.ts
-var USAGE = `Usage: mason-audit [--dir <path>] [--json | --fix-prompt] [--checks <list>]
+var USAGE2 = `Usage: mason-audit [--dir <path>] [--json | --fix-prompt] [--checks <list>]
 
-Audits the repo's AI context files (CLAUDE.md, .claude/CLAUDE.md, AGENTS.md)
+Audits README.md and agent instruction files at any depth, preserving filename case
 against repo reality: referenced paths that no longer exist, undocumented
 modules, stale counts, dead npm scripts, and manifests newer than the doc.
 Deterministic: no LLM call, no network \u2013 safe for CI. Works on any repo with
@@ -1924,6 +2882,8 @@ Options:
                    ${ALL_CHECKS.join(", ")}
   --help           Show this help
 
+Use mason audit review --help to prepare and record an authorized advisory assessment.
+
 Exit codes:
   0  no issues (advisories may still be present)
   1  provable issues found
@@ -1987,7 +2947,10 @@ function issueLine(issue) {
 }
 function formatAuditSummary(report) {
   const lines = [];
-  const reviewCount = report.advisories.length + (report.suppressedAdvisories?.length ?? 0);
+  const reviewed = new Set(report.advisoryReviews?.filter((review) => review.status === "current").map((review) => review.id));
+  const open = report.advisories.filter((finding) => !reviewed.has(findingId(finding)));
+  const suppressed = (report.suppressedAdvisories ?? []).filter((finding) => !reviewed.has(findingId(finding)));
+  const reviewCount = open.length + suppressed.length;
   for (const doc of report.docs) {
     const docIssues = report.issues.filter((i) => i.anchor.doc === doc.path);
     const committed = doc.lastCommit ? `last committed ${doc.lastCommit.date.slice(0, 10)}, ${doc.lastCommit.hash.slice(0, 7)}` : "untracked";
@@ -2004,9 +2967,9 @@ function formatAuditSummary(report) {
   for (const issue of report.issues) {
     if (!docPaths.has(issue.anchor.doc)) lines.push(issueLine(issue));
   }
-  if (report.advisories.length > 0) {
+  if (open.length > 0) {
     lines.push("Advisories (do not affect the exit code):");
-    for (const advisory of report.advisories) {
+    for (const advisory of open) {
       lines.push(`  [${advisory.type}] ${advisory.anchor.doc}: ${advisory.message}`);
     }
   }
@@ -2015,7 +2978,9 @@ function formatAuditSummary(report) {
       lines.push(`  [skipped] ${skip.check}: ${skip.reason}`);
     }
   }
-  for (const advisory of report.suppressedAdvisories ?? []) {
+  if (reviewed.size) lines.push(`${reviewed.size} advisories have recorded assessments covering current evidence (see --json).`);
+  for (const review of report.advisoryReviews ?? []) if (review.status !== "current") lines.push(`  [${review.status}] ${review.reason}`);
+  for (const advisory of suppressed) {
     lines.push(`  [suppressed; unresolved] ${advisory.type} ${advisory.anchor.doc}: ${advisory.message}`);
   }
   lines.push(
@@ -2052,10 +3017,10 @@ function formatFixPrompt(report, baselinePath) {
     "- dead-command: replace with the correct script from availableScripts if an obvious rename exists; otherwise remove the command mention."
   );
   lines.push(
-    "- new-module: add a one-line factual mention of the directory where sibling modules are described; read the directory's files first and describe only what you verified."
+    "- new-module: review whether the directory needs documenting; an omission alone does not establish a defect. Preserve scope and describe only what you verified."
   );
   lines.push(
-    "- ADVISORIES require a separate assessment of the cited commits or decision evidence. Report any review you perform and what remains unknown. Their disappearance after edits or a commit does not establish review or approval."
+    "- Historical ADVISORIES require a separate authorized assessment using review_advisory with the baselinePath and findingId from verification. Prepare and inspect evidence first; record addressed, inapplicable or deferred with the actual reviewer, note and reviewToken. Decision findings use review_decision. Candidates marked resolution: recheck can be rerun to see whether the condition remains; this does not establish semantic approval. Report what remains unknown."
   );
   lines.push("");
   lines.push("AUDIT REPORT (current context files and repository evidence, including local edits):");
@@ -2075,7 +3040,7 @@ function formatFixPrompt(report, baselinePath) {
   );
   lines.push("");
   lines.push(
-    "After edits, call mason_repair with action: verify and the original baselinePath, or mason-audit --verify-repair <baselinePath> --dir <project>. Repeat against the same baseline after any final documentation commit. Summarize resolved, unresolved, review-required, unverified, and new findings with their evidence. Do not report a suppressed or unavailable check as fixed. This audit covers the listed context files; independently discovered README or application issues need their own validation."
+    "After edits, call mason_repair with action: verify and the original baselinePath, or mason-audit --verify-repair <baselinePath> --dir <project>. Repeat against the same baseline after any final documentation commit. Summarize resolved, unresolved, review-required, unverified, and new findings with their evidence. Do not report a suppressed or unavailable check as fixed. This audit covers the listed documents and supported claims; application behavior and code examples need their own validation."
   );
   return lines.join("\n");
 }
@@ -2085,6 +3050,7 @@ async function runAuditCli(argv, io = {
   err: (line) => process.stderr.write(`${line}
 `)
 }) {
+  if (argv[0] === "review") return runAdvisoryCli(argv.slice(1), io);
   let args;
   try {
     args = parseArgs(argv);
@@ -2096,14 +3062,14 @@ async function runAuditCli(argv, io = {
     }
   } catch (error) {
     io.err(error instanceof Error ? error.message : String(error));
-    io.err(USAGE);
+    io.err(USAGE2);
     return 2;
   }
   if (args.help) {
-    io.out(USAGE);
+    io.out(USAGE2);
     return 0;
   }
-  const rootDir = path17.resolve(args.dir);
+  const rootDir = path21.resolve(args.dir);
   if (args.baseline || args.prepareRepair) {
     try {
       if (args.baseline) {
@@ -2123,7 +3089,7 @@ ${formatAuditSummary(prepared.report)}`);
   const report = await computeAudit(rootDir, { checks: args.checks });
   if (!report) {
     io.err(
-      `No CLAUDE.md, .claude/CLAUDE.md, or AGENTS.md found in ${rootDir}.`
+      `No README.md or agent instruction files found in ${rootDir}.`
     );
     return 2;
   }
@@ -2149,11 +3115,13 @@ ${formatAuditSummary(prepared.report)}`);
 
 // bin/mason-audit.ts
 runAuditCli(process.argv.slice(2)).then(
-  (code) => process.exit(code),
+  (code) => {
+    process.exitCode = code;
+  },
   (err) => {
     process.stderr.write(`mason-audit error: ${err}
 `);
-    process.exit(2);
+    process.exitCode = 2;
   }
 );
 //# sourceMappingURL=mason-audit.js.map