mason-context 0.16.3 → 0.17.1

package/dist/mason-auto.js

@@ -346,6 +346,89 @@ var init_store = __esm({
   }
 });
 
+// src/audit/commands.ts
+import path4 from "path";
+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 : path4.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 : path4.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) || path4.posix.isAbsolute(unquoted) ? null : unquoted;
+    };
+  }
+});
+
 // src/audit/tree.ts
 function glyphIndex(line) {
   for (const glyph of GLYPHS) {
@@ -425,6 +508,7 @@ var init_tree = __esm({
 });
 
 // src/audit/claims.ts
+import MarkdownIt from "markdown-it";
 function normalizePathToken(token) {
   let t = token.trim();
   if (!t) return null;
@@ -488,11 +572,34 @@ function extractClaims(content2) {
   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 = "";
@@ -523,6 +630,7 @@ function extractClaims(content2) {
         fenceMarker = fenceMatch[1][0];
         fenceInfo = fenceMatch[2].trim().toLowerCase();
         blockLines = [];
+        shellCwd = void 0;
         blockStartLine = lineNo + 1;
       } else if (fenceMatch[1][0] === fenceMarker) {
         inFence = false;
@@ -533,14 +641,9 @@ function extractClaims(content2) {
     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;
     }
@@ -567,14 +670,10 @@ function extractClaims(content2) {
         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 {
@@ -583,10 +682,11 @@ function extractClaims(content2) {
     commands: [...commands.values()]
   };
 }
-var ROOT_FILE_NAMES, SHELL_FENCE_INFOS, COMMAND_RE, COUNT_RE, COUNT_DENYLIST_RE, IGNORE_LINE, IGNORE_START, IGNORE_END;
+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",
@@ -620,7 +720,7 @@ var init_claims = __esm({
       ".env.example"
     ]);
     SHELL_FENCE_INFOS = /* @__PURE__ */ new Set(["", "bash", "sh", "shell", "console", "zsh"]);
-    COMMAND_RE = /\b(npm|pnpm|yarn)\s+run\s+([A-Za-z0-9:_.-]+)/g;
+    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 -->";
@@ -641,7 +741,7 @@ async function lastCommitOf(resolvedRoot, relPath) {
   try {
     const { stdout } = await exec2(
       "git",
-      ["log", "-1", `--format=${COMMIT_FORMAT}`, "--", relPath],
+      ["log", "-1", `--format=${COMMIT_FORMAT}`, "--", `:(literal)${relPath}`],
       { cwd: resolvedRoot }
     );
     const line = stdout.trim().split("\n")[0];
@@ -660,7 +760,7 @@ async function deletingCommitOf(resolvedRoot, relPath) {
         "--diff-filter=D",
         `--format=${COMMIT_FORMAT}`,
         "--",
-        relPath
+        `:(literal)${relPath}`
       ],
       { cwd: resolvedRoot }
     );
@@ -674,7 +774,7 @@ async function firstCommitOf(resolvedRoot, relPath) {
   try {
     const { stdout } = await exec2(
       "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];
@@ -720,42 +820,242 @@ var init_git = __esm({
   }
 });
 
-// src/audit/docs.ts
+// src/audit/inputs.ts
 import fs4 from "fs/promises";
-import path4 from "path";
+import * as nativeFs from "fs";
+import path5 from "path";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify3 } from "util";
+import fg2 from "fast-glob";
+async function auditInputPath(root, file) {
+  if (file === ".") return fs4.realpath(root);
+  try {
+    return await storePath(root, file);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Symlink")) {
+      throw new Error(`Audit input contains a symbolic link: ${file}. Its evidence could not be verified.`, { cause: error });
+    }
+    throw error;
+  }
+}
+async function readAuditInput(root, file) {
+  try {
+    const value = await readBoundedFile(await auditInputPath(root, file), 10 * 1024 * 1024);
+    if (value === null) throw new Error(`Unreadable or oversized audit input: ${file}`);
+    return value;
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) return null;
+    throw error;
+  }
+}
+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 = path5.relative(root, directory).split(path5.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.`));
+      return;
+    }
+    auditInputPath(root, relative).then(() => {
+      nativeFs.readdir(directory, opts, callback);
+    }, callback);
+  });
+  const lstat2 = ((file, callback) => {
+    const relative = path5.relative(root, file).split(path5.sep).join("/") || ".";
+    auditInputPath(root, relative).then(() => nativeFs.lstat(file, callback), callback);
+  });
+  const stream = fg2.stream(patterns, {
+    cwd: root,
+    ignore: options.ignore,
+    onlyFiles: false,
+    onlyDirectories: options.onlyDirectories,
+    objectMode: true,
+    followSymbolicLinks: options.followSymbolicLinks ?? true,
+    fs: { readdir: readdir2, lstat: lstat2 },
+    concurrency: 16
+  });
+  const matches = [];
+  try {
+    for await (const value of stream) {
+      const entry = value;
+      const file = entry.path;
+      if (options.select && !options.select(file)) continue;
+      await auditInputPath(root, file);
+      if (!options.onlyDirectories && !entry.dirent.isFile()) continue;
+      matches.push(file);
+      if (matches.length > MAX_INPUTS) {
+        const largest = [...matches.reduce((counts, item) => {
+          const dir = item.split("/")[0];
+          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, count4]) => `${dir} (${count4})`).join(", ")}. Narrow this check's inputs.`);
+      }
+    }
+  } finally {
+    stream.destroy();
+  }
+  return matches.sort();
+}
+async function gitSourcePaths(root) {
+  const { stdout } = await execute(
+    "git",
+    [
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "--",
+      ...SOURCE_EXTENSIONS.map((extension) => `:(glob)**/*.${extension}`)
+    ],
+    { cwd: root, maxBuffer: 32 * 1024 * 1024, timeout: 1e4 }
+  );
+  return [...new Set(stdout.split("\0").filter(Boolean))].sort();
+}
+async function gitIgnoredPaths(root, files) {
+  if (!files.length) return /* @__PURE__ */ new Set();
+  const operation = execute(
+    "git",
+    ["check-ignore", "-z", "--stdin"],
+    { cwd: root, maxBuffer: 4 * 1024 * 1024, timeout: 1e4 }
+  );
+  operation.child.stdin.on("error", () => {
+  });
+  operation.child.stdin.end(files.join("\0") + "\0");
+  try {
+    return new Set((await operation).stdout.split("\0").filter(Boolean));
+  } catch (error) {
+    if (error.code === 1) return /* @__PURE__ */ new Set();
+    throw error;
+  }
+}
+var execute, MAX_INPUTS;
+var init_inputs = __esm({
+  "src/audit/inputs.ts"() {
+    "use strict";
+    init_files();
+    init_storage();
+    execute = promisify3(execFile3);
+    MAX_INPUTS = 1e5;
+  }
+});
+
+// src/audit/docs.ts
+import fs5 from "fs/promises";
+import path6 from "path";
+import { execFile as execFile4 } from "child_process";
+import { promisify as promisify4 } from "util";
+import fg3 from "fast-glob";
 async function isDirty(resolvedRoot, relPath) {
   try {
     const { stdout } = await exec3(
       "git",
-      ["status", "--porcelain", "--", relPath],
+      ["status", "--porcelain", "--", `:(literal)${relPath}`],
       { cwd: resolvedRoot }
     );
     return stdout.trim().length > 0;
   } catch {
-    return false;
+    return true;
   }
 }
-async function discoverDocs(resolvedRoot) {
-  const docs = await Promise.all(DOC_CANDIDATES.map(async (candidate) => {
-    let content2;
+async function discoverDocPaths(root) {
+  let candidates = [];
+  try {
+    const { stdout } = await exec3(
+      "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 {
-      content2 = await fs4.readFile(path4.join(resolvedRoot, candidate), "utf-8");
+      await exec3("git", ["rev-parse", "--git-dir"], { cwd: root });
     } catch {
-      return null;
+      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 priority2 = (file) => {
+    const index2 = DOC_CANDIDATES.findIndex((p) => p.toLowerCase() === file.toLowerCase());
+    return index2 < 0 ? DOC_CANDIDATES.length : index2;
+  };
+  return paths.sort((a, b) => priority2(a) - priority2(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(path6.posix.join(dir, entry.name));
+    }
+  }
+  return paths;
+}
+function documentScope(file) {
+  const parent = path6.posix.dirname(file);
+  return path6.posix.basename(parent).toLowerCase() === ".claude" ? path6.posix.dirname(parent) : parent;
+}
+async function discoverDocs(resolvedRoot) {
+  const docs = [];
+  for (const candidate of await discoverDocPaths(resolvedRoot)) {
+    const content2 = await readAuditInput(resolvedRoot, candidate);
+    if (content2 === null) throw new Error("Document disappeared during discovery: " + candidate);
     const [lastCommit, dirty] = await Promise.all([lastCommitOf(resolvedRoot, candidate), isDirty(resolvedRoot, candidate)]);
-    return {
+    docs.push({
       path: candidate,
       content: content2,
+      scope: documentScope(candidate),
+      kind: /^readme\.md$/i.test(path6.posix.basename(candidate)) ? "readme" : "instructions",
       lineCount: content2.split("\n").length,
       lastCommit,
       dirty,
       claims: extractClaims(content2)
-    };
-  }));
-  return docs.filter((doc) => doc !== null);
+    });
+  }
+  return docs;
 }
 var exec3, DOC_CANDIDATES;
 var init_docs = __esm({
@@ -763,7 +1063,9 @@ var init_docs = __esm({
     "use strict";
     init_claims();
     init_git();
-    exec3 = promisify3(execFile3);
+    init_inputs();
+    init_files();
+    exec3 = promisify4(execFile4);
     DOC_CANDIDATES = [
       "AGENTS.md",
       "CLAUDE.md",
@@ -772,10 +1074,52 @@ var init_docs = __esm({
   }
 });
 
+// src/audit/scope.ts
+import fs6 from "fs/promises";
+import path7 from "path";
+function scopedPath(directory, value) {
+  if (path7.posix.isAbsolute(value) || value.includes("\\") || /[\x00-\x1f]/.test(value)) return null;
+  const resolved = path7.posix.normalize(path7.posix.join(directory, value));
+  return resolved === ".." || resolved.startsWith("../") ? null : resolved;
+}
+function pathClaimScope(doc, claim) {
+  const directory = claim.relativeTo === "document" ? path7.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) {
+  try {
+    await fs6.access(await auditInputPath(root, file));
+    return true;
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) return false;
+    throw error;
+  }
+}
+function gitMetadataPath(file) {
+  return file.split("/").includes(".git");
+}
+function optionalMasonPath(file) {
+  return file.split("/").includes(".mason");
+}
+var init_scope = __esm({
+  "src/audit/scope.ts"() {
+    "use strict";
+    init_inputs();
+    init_docs();
+  }
+});
+
 // src/test-map.ts
-import path5 from "path";
+import path8 from "path";
 async function buildTestMap(dir) {
-  const rootDir = path5.resolve(dir);
+  const rootDir = path8.resolve(dir);
   const access = await createFileAccess(rootDir);
   const testPatterns = [
     "**/*.test.*",
@@ -796,7 +1140,7 @@ async function buildTestMap(dir) {
   const sourceByBaseName = /* @__PURE__ */ new Map();
   for (const file of sourceFiles) {
     if (testFiles.includes(file)) continue;
-    const baseName = path5.basename(file).replace(/\.[^.]+$/, "");
+    const baseName = path8.basename(file).replace(/\.[^.]+$/, "");
     const existing = sourceByBaseName.get(baseName) ?? [];
     existing.push(file);
     sourceByBaseName.set(baseName, existing);
@@ -804,7 +1148,7 @@ async function buildTestMap(dir) {
   const paired = [];
   const unmatched = [];
   for (const testFile of testFiles) {
-    const testBaseName = path5.basename(testFile).replace(/\.[^.]+$/, "");
+    const testBaseName = path8.basename(testFile).replace(/\.[^.]+$/, "");
     const sourceName = testBaseName.replace(/Test$|Tests$|Spec$|\.test$|\.spec$/, "").replace(/^test_|_test$/, "");
     if (!sourceName) {
       unmatched.push(testFile);
@@ -812,10 +1156,10 @@ async function buildTestMap(dir) {
     }
     const candidates = sourceByBaseName.get(sourceName);
     if (candidates && candidates.length > 0) {
-      const testDir = path5.dirname(testFile);
+      const testDir = path8.dirname(testFile);
       const bestMatch = candidates.reduce((best, candidate) => {
-        const candidateDir = path5.dirname(candidate);
-        const bestDir = path5.dirname(best);
+        const candidateDir = path8.dirname(candidate);
+        const bestDir = path8.dirname(best);
         const candidateOverlap = commonSegments(testDir, candidateDir);
         const bestOverlap = commonSegments(testDir, bestDir);
         return candidateOverlap > bestOverlap ? candidate : best;
@@ -834,12 +1178,12 @@ async function buildTestMap(dir) {
 function commonSegments(pathA, pathB) {
   const segsA = pathA.split("/");
   const segsB = pathB.split("/");
-  let count3 = 0;
+  let count4 = 0;
   for (let i = 0; i < Math.min(segsA.length, segsB.length); i++) {
-    if (segsA[i] === segsB[i]) count3++;
+    if (segsA[i] === segsB[i]) count4++;
     else break;
   }
-  return count3;
+  return count4;
 }
 var init_test_map = __esm({
   "src/test-map.ts"() {
@@ -849,9 +1193,9 @@ var init_test_map = __esm({
 });
 
 // src/snapshot/snapshot.ts
-import path6 from "path";
-import { execFile as execFile4 } from "child_process";
-import { promisify as promisify4 } from "util";
+import path9 from "path";
+import { execFile as execFile5 } from "child_process";
+import { promisify as promisify5 } from "util";
 import { z as z2 } from "zod";
 async function inspectSnapshot(rootDir) {
   try {
@@ -884,7 +1228,7 @@ var init_snapshot = __esm({
     init_storage();
     init_paths();
     init_test_map();
-    exec4 = promisify4(execFile4);
+    exec4 = promisify5(execFile5);
     repoPath = z2.string().refine((value) => normalizeRepoPath(value) !== null, "Expected a relative repository path");
     verificationFields = {
       refreshedHash: z2.string().optional(),
@@ -913,10 +1257,10 @@ var init_snapshot = __esm({
 });
 
 // src/drift/drift.ts
-import fs5 from "fs/promises";
-import path7 from "path";
-import { execFile as execFile5 } from "child_process";
-import { promisify as promisify5 } from "util";
+import fs7 from "fs/promises";
+import path10 from "path";
+import { execFile as execFile6 } from "child_process";
+import { promisify as promisify6 } from "util";
 function parseChanges(output) {
   const fields = output.split("\0");
   const changes = [];
@@ -961,7 +1305,7 @@ var init_drift = __esm({
     "use strict";
     init_snapshot();
     init_paths();
-    exec5 = promisify5(execFile5);
+    exec5 = promisify6(execFile6);
   }
 });
 
@@ -982,230 +1326,76 @@ var init_types = __esm({
 });
 
 // src/audit/checks/deleted-reference.ts
-import fs6 from "fs/promises";
-import path8 from "path";
-async function exists(absPath) {
-  try {
-    await fs6.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);
-    }
-  }
-  return result;
-}
-var init_deleted_reference = __esm({
-  "src/audit/checks/deleted-reference.ts"() {
-    "use strict";
-    init_git();
-    init_checks();
-  }
-});
-
-// src/audit/inputs.ts
-import fs7 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 fg2 from "fast-glob";
-async function auditInputPath(root, file) {
-  if (file === ".") return fs7.realpath(root);
-  try {
-    return await storePath(root, file);
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith("Symlink")) {
-      throw new Error(`Audit input contains a symbolic link: ${file}. Its evidence could not be verified.`, { cause: error });
-    }
-    throw error;
-  }
-}
-async function readAuditInput(root, file) {
-  try {
-    const value = await readBoundedFile(await auditInputPath(root, file), 10 * 1024 * 1024);
-    if (value === null) throw new Error(`Unreadable or oversized audit input: ${file}`);
-    return value;
-  } catch (error) {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  }
-}
-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("/") || ".";
-    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.`));
-      return;
-    }
-    auditInputPath(root, relative).then(() => {
-      nativeFs.readdir(directory, opts, callback);
-    }, callback);
-  });
-  const lstat2 = ((file, callback) => {
-    const relative = path9.relative(root, file).split(path9.sep).join("/") || ".";
-    auditInputPath(root, relative).then(() => nativeFs.lstat(file, callback), callback);
-  });
-  const stream = fg2.stream(patterns, {
-    cwd: root,
-    ignore: options.ignore,
-    onlyFiles: false,
-    onlyDirectories: options.onlyDirectories,
-    objectMode: true,
-    followSymbolicLinks: options.followSymbolicLinks ?? true,
-    fs: { readdir: readdir2, lstat: lstat2 },
-    concurrency: 16
-  });
-  const matches = [];
-  try {
-    for await (const value of stream) {
-      const entry = value;
-      const file = entry.path;
-      if (options.select && !options.select(file)) continue;
-      await auditInputPath(root, file);
-      if (!options.onlyDirectories && !entry.dirent.isFile()) continue;
-      matches.push(file);
-      if (matches.length > MAX_INPUTS) {
-        const largest = [...matches.reduce((counts, item) => {
-          const dir = item.split("/")[0];
-          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, count3]) => `${dir} (${count3})`).join(", ")}. Narrow this check's inputs.`);
+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 (scope.candidates.some(gitMetadataPath)) {
+        result.skipped.push({
+          check: "deleted-reference",
+          doc: doc.path,
+          reason: `Reference ${claim.path} names Git metadata, whose layout varies between checkouts; it was not verified as a repository file.`
+        });
+        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 message2 = 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: message2, anchor, confidence: "certain", evidence });
+      } else {
+        result.advisories.push({ resolution: "recheck", type: "deleted-reference", message: message2 + (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 });
       }
     }
-  } finally {
-    stream.destroy();
-  }
-  return matches.sort();
-}
-async function gitSourcePaths(root) {
-  const { stdout } = await execute(
-    "git",
-    [
-      "ls-files",
-      "-z",
-      "--cached",
-      "--others",
-      "--exclude-standard",
-      "--",
-      ...SOURCE_EXTENSIONS.map((extension) => `:(glob)**/*.${extension}`)
-    ],
-    { cwd: root, maxBuffer: 32 * 1024 * 1024, timeout: 1e4 }
-  );
-  return [...new Set(stdout.split("\0").filter(Boolean))].sort();
-}
-async function gitIgnoredPaths(root, files) {
-  if (!files.length) return /* @__PURE__ */ new Set();
-  const operation = execute(
-    "git",
-    ["check-ignore", "-z", "--stdin"],
-    { cwd: root, maxBuffer: 4 * 1024 * 1024, timeout: 1e4 }
-  );
-  operation.child.stdin.on("error", () => {
-  });
-  operation.child.stdin.end(files.join("\0") + "\0");
-  try {
-    return new Set((await operation).stdout.split("\0").filter(Boolean));
-  } catch (error) {
-    if (error.code === 1) return /* @__PURE__ */ new Set();
-    throw error;
   }
+  return result;
 }
-var execute, MAX_INPUTS;
-var init_inputs = __esm({
-  "src/audit/inputs.ts"() {
+var init_deleted_reference = __esm({
+  "src/audit/checks/deleted-reference.ts"() {
     "use strict";
-    init_files();
-    init_storage();
-    execute = promisify6(execFile6);
-    MAX_INPUTS = 1e5;
+    init_git();
+    init_scope();
+    init_checks();
   }
 });
 
 // src/audit/checks/new-module.ts
-import fg3 from "fast-glob";
+import fg4 from "fast-glob";
 import fs8 from "fs/promises";
-import path10 from "path";
+import path12 from "path";
 function escapeRegExp(text2) {
   return text2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -1219,15 +1409,15 @@ function isMentioned(combinedDocs, name) {
 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 combinedDocs = moduleDocumentation(ctx.docs);
   const primaryDoc = ctx.docs[0].path;
   const checkedDocs = ctx.docs.map((d) => d.path);
   const flag = async (dir, sourceFileCount) => {
-    result.issues.push({
+    result.advisories.push({
+      resolution: "recheck",
       type: "new-module",
-      message: `directory \`${dir}/\` contains ${sourceFileCount} source file${sourceFileCount === 1 ? "" : "s"} but is not mentioned in any context file`,
+      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 },
-      confidence: "likely",
       evidence: {
         kind: "unmentioned-dir",
         dir,
@@ -1242,41 +1432,44 @@ async function checkNewModules(ctx) {
   }
   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 fs8.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 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 === "." ? "*" : `${fg3.escapePath(dir)}/*`, {
+    return (await auditGlob(root, dir === "." ? "*" : `${fg4.escapePath(dir)}/*`, {
       ignore,
       onlyDirectories: true,
       label: "Module directory discovery",
       select: (file) => visible.has(file)
-    })).map((file) => path10.posix.basename(file));
+    })).map((file) => path12.posix.basename(file));
   };
   const countSourceFiles = async (dir) => {
     const files = sources.filter((file) => file.startsWith(dir + "/"));
-    let count3 = 0;
+    let count4 = 0;
     for (let offset = 0; offset < files.length; offset += 256) {
-      count3 += (await auditGlob(root, files.slice(offset, offset + 256).map((file) => fg3.escapePath(file)), {
+      count4 += (await auditGlob(root, files.slice(offset, offset + 256).map((file) => fg4.escapePath(file)), {
         ignore,
         followSymbolicLinks: false,
         label: `Source discovery in ${dir}`
       })).length;
-      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.`);
+      if (count4 > 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 count3;
+    return count4;
   };
   const candidates = [];
   for (const topDir of await listSubdirs(".")) {
     const topMentioned = isMentioned(combinedDocs, topDir);
     if (!topMentioned) {
-      const count3 = await countSourceFiles(topDir);
-      if (count3 >= 1) candidates.push({ dir: topDir, sourceFileCount: count3 });
+      const count4 = await countSourceFiles(topDir);
+      if (count4 >= 1) candidates.push({ dir: topDir, sourceFileCount: count4 });
       continue;
     }
     const subdirs = await listSubdirs(topDir);
@@ -1284,9 +1477,9 @@ async function moduleCandidates(root, combinedDocs) {
     if (mentioned.length < ENUMERATION_THRESHOLD) continue;
     for (const sub of subdirs) {
       if (isMentioned(combinedDocs, sub)) continue;
-      const count3 = await countSourceFiles(`${topDir}/${sub}`);
-      if (count3 >= SECOND_LEVEL_MIN_SOURCE_FILES) {
-        candidates.push({ dir: `${topDir}/${sub}`, sourceFileCount: count3 });
+      const count4 = await countSourceFiles(`${topDir}/${sub}`);
+      if (count4 >= SECOND_LEVEL_MIN_SOURCE_FILES) {
+        candidates.push({ dir: `${topDir}/${sub}`, sourceFileCount: count4 });
       }
     }
   }
@@ -1325,7 +1518,7 @@ var init_new_module = __esm({
 });
 
 // src/audit/checks/stale-count.ts
-import path11 from "path";
+import path13 from "path";
 async function countGradleModules(root) {
   for (const name of ["settings.gradle.kts", "settings.gradle"]) {
     const content2 = await readAuditInput(root, name);
@@ -1359,7 +1552,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()
       };
     }
   }
@@ -1390,7 +1583,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()
       };
     }
   }
@@ -1412,8 +1605,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);
     }
   }
@@ -1431,11 +1624,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",
@@ -1467,6 +1670,7 @@ 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;
@@ -1474,61 +1678,94 @@ var init_stale_count = __esm({
 });
 
 // src/audit/checks/dead-command.ts
-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 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);
+  };
+  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 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);
+  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;
     }
-    return workspaceScripts;
-  };
-  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)
-      }
-    });
+    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 message2 = `\`${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: message2, anchor, confidence: "certain", evidence });
+    else result.advisories.push({ resolution: "recheck", type: "dead-command", message: message2 + (elsewhere.length ? `; it exists in ${elsewhere.join(", ")}. Clarify the intended working directory.` : "; the intended working directory needs review."), anchor, evidence });
   }
   return result;
 }
@@ -1543,6 +1780,8 @@ 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;
   }
@@ -1556,13 +1795,13 @@ async function git(root, args) {
 }
 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 {
@@ -1571,12 +1810,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;
@@ -1607,6 +1846,12 @@ var init_release_metadata = __esm({
 });
 
 // src/audit/checks/deps-changed.ts
+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 = [];
@@ -1630,7 +1875,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({
@@ -1669,6 +1914,7 @@ 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();
@@ -1691,7 +1937,7 @@ var init_deps_changed = __esm({
 });
 
 // src/context/lexical.ts
-import path12 from "path";
+import path15 from "path";
 var init_lexical = __esm({
   "src/context/lexical.ts"() {
     "use strict";
@@ -1875,7 +2121,7 @@ var init_provenance = __esm({
 
 // src/decisions/decisions.ts
 import fs9 from "fs/promises";
-import path13 from "path";
+import path16 from "path";
 import { createHash } from "crypto";
 import { z as z4 } from "zod";
 async function loadDecisionStore(rootDir) {
@@ -1926,9 +2172,9 @@ var init_decisions = __esm({
 });
 
 // src/decisions/drift.ts
-import path14 from "path";
+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)]);
@@ -2017,38 +2263,330 @@ var init_decision_anchor = __esm({
     init_provenance();
     init_checks();
   }
-});
-
-// src/audit/checks/index.ts
-function emptyResult() {
-  return { issues: [], advisories: [], skipped: [] };
+});
+
+// src/audit/checks/index.ts
+function emptyResult() {
+  return { issues: [], advisories: [], 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
+    };
+  }
+});
+
+// src/audit/findings.ts
+import { createHash as createHash2 } from "crypto";
+import { z as z5 } from "zod";
+function findingId(finding) {
+  const e = finding.evidence;
+  let key;
+  switch (e.kind) {
+    case "missing-path":
+      key = e.resolvedPath && e.resolvedPath !== e.claimed ? [e.claimed, e.resolvedPath] : e.claimed;
+      break;
+    case "unmentioned-dir":
+      key = e.dir;
+      break;
+    case "count-mismatch":
+      key = [e.unit.replace(/s$/, ""), e.countedFrom];
+      break;
+    case "missing-script":
+      key = e.scope && e.scope.directory !== "." ? [e.scriptName, e.scope.directory] : e.scriptName;
+      break;
+    case "doc-behind-manifests":
+      key = null;
+      break;
+    case "decision-anchor":
+      key = [e.decisionId, e.provenance?.revision, e.provenance?.approval];
+      break;
+  }
+  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 = z5.enum(["deleted-reference", "new-module", "stale-count", "dead-command", "deps-changed", "decision-anchor-drift"]);
+    commitSchema = z5.object({ hash: z5.string().regex(/^[a-f0-9]{40,64}$/), date: z5.string(), subject: z5.string() });
+    anchorSchema = z5.object({ doc: z5.string(), line: z5.number().int().positive().nullable(), excerpt: z5.string().nullable() });
+    count = z5.number().int().nonnegative();
+    scopeSchema = z5.object({
+      basis: z5.enum(["repository", "document", "document-link", "explicit"]),
+      directory: z5.string(),
+      candidates: z5.array(z5.string())
+    });
+    evidenceSchema = z5.discriminatedUnion("kind", [
+      z5.object({
+        kind: z5.literal("missing-path"),
+        claimed: z5.string(),
+        renamedTo: z5.string().nullable(),
+        deletedInCommit: commitSchema.nullable(),
+        everTracked: z5.boolean(),
+        parentDirExists: z5.boolean(),
+        resolvedPath: z5.string().optional(),
+        scope: scopeSchema.optional()
+      }),
+      z5.object({
+        kind: z5.literal("unmentioned-dir"),
+        dir: z5.string(),
+        sourceFileCount: count,
+        firstCommit: commitSchema.nullable(),
+        checkedDocs: z5.array(z5.string())
+      }),
+      z5.object({
+        kind: z5.literal("count-mismatch"),
+        claimed: count,
+        actual: count,
+        unit: z5.string(),
+        countedFrom: z5.string(),
+        members: z5.array(z5.string())
+      }),
+      z5.object({
+        kind: z5.literal("missing-script"),
+        scriptName: z5.string(),
+        invocation: z5.string(),
+        manifestsChecked: z5.array(z5.string()),
+        availableScripts: z5.array(z5.string()),
+        scope: scopeSchema.optional()
+      }),
+      z5.object({
+        kind: z5.literal("doc-behind-manifests"),
+        docLastCommit: commitSchema,
+        manifestCommits: z5.array(commitSchema.extend({ files: z5.array(z5.string()) })),
+        totalCommits: count
+      }),
+      z5.object({
+        kind: z5.literal("decision-anchor"),
+        decisionId: z5.string(),
+        title: z5.string(),
+        changedFiles: z5.array(z5.string()),
+        refreshedHash: z5.string(),
+        provenance: z5.object({}).passthrough().optional()
+      })
+    ]);
+    findingSchema = z5.object({ message: z5.string(), anchor: anchorSchema, evidence: evidenceSchema });
+    issueSchema = findingSchema.extend({
+      type: z5.enum(["deleted-reference", "new-module", "stale-count", "dead-command"]),
+      confidence: z5.enum(["certain", "likely"])
+    });
+    advisorySchema = findingSchema.extend({ type: checkSchema, resolution: z5.literal("recheck").optional() });
+    checkResultSchema = z5.object({
+      issues: z5.array(issueSchema),
+      advisories: z5.array(advisorySchema),
+      suppressedAdvisories: z5.array(advisorySchema).optional(),
+      skipped: z5.array(z5.object({ check: z5.string(), reason: z5.string(), doc: z5.string().optional() }))
+    });
+  }
+});
+
+// src/audit/advisory-review.ts
+import fs10 from "fs/promises";
+import { execFile as execFile8 } from "child_process";
+import { promisify as promisify8 } from "util";
+import { z as z6 } 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 events2 = record.history.filter((event2) => ["accepted", "reaffirmed", "retired"].includes(event2.kind));
+  const event = events2.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) };
+  }
 }
-var CHECKS;
-var init_checks = __esm({
-  "src/audit/checks/index.ts"() {
+async function advisoryReviewInventory(root) {
+  let names;
+  try {
+    names = await fs10.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)]));
+}
+var execute2, git2, hashSchema, commitSchema2, evidenceSchema2, eventSchema2, recordSchema, reviewSummarySchema, advisoryReviewRequest, recordPath;
+var init_advisory_review = __esm({
+  "src/audit/advisory-review.ts"() {
     "use strict";
-    init_deleted_reference();
-    init_new_module();
-    init_stale_count();
-    init_dead_command();
+    init_findings();
     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
-    };
+    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 = z6.string().regex(/^[a-f0-9]{64}$/);
+    commitSchema2 = z6.string().regex(/^[a-f0-9]{40,64}$/);
+    evidenceSchema2 = z6.object({
+      head: commitSchema2,
+      fingerprint: hashSchema,
+      scope: z6.array(z6.string()).min(1).max(1e3),
+      tree: z6.string().max(2 * 1024 * 1024),
+      lastScopeCommit: commitSchema2,
+      paths: z6.array(z6.object({ path: z6.string(), exists: z6.boolean() })).max(1e3)
+    });
+    eventSchema2 = z6.object({
+      at: z6.string().datetime(),
+      reviewer: z6.string().trim().min(1).max(200),
+      note: z6.string().trim().min(1).max(2500),
+      outcome: z6.enum(["addressed", "inapplicable", "deferred"]),
+      finding: advisorySchema.refine((finding) => finding.evidence.kind !== "decision-anchor", "Decision findings use decision reviews"),
+      evidence: evidenceSchema2
+    });
+    recordSchema = z6.object({ version: z6.literal(1), id: hashSchema, events: z6.array(eventSchema2).min(1).max(200), digest: hashSchema });
+    reviewSummarySchema = z6.object({
+      id: hashSchema,
+      status: z6.enum(["current", "reopened", "deferred", "unverified"]),
+      reason: z6.string(),
+      recordPath: z6.string().optional(),
+      reviewer: z6.string().optional(),
+      note: z6.string().optional(),
+      outcome: z6.enum(["addressed", "inapplicable", "deferred", "accepted", "reaffirmed", "retired"]).optional(),
+      reviewedHead: z6.string().optional()
+    });
+    advisoryReviewRequest = z6.object({
+      baselinePath: z6.string().min(1),
+      findingId: hashSchema,
+      action: z6.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 fs10 from "fs/promises";
-import path15 from "path";
+import fs11 from "fs/promises";
+import path18 from "path";
 async function computeAudit(rootDir, options = {}) {
-  const resolvedRoot = path15.resolve(rootDir);
+  const resolvedRoot = path18.resolve(rootDir);
   const [docs, headHash] = await Promise.all([discoverDocs(resolvedRoot), getCurrentGitHash(resolvedRoot)]);
   if (docs.length === 0) return null;
   const report = {
@@ -2059,6 +2597,8 @@ async function computeAudit(rootDir, options = {}) {
     checksRun: [],
     docs: docs.map((d) => ({
       path: d.path,
+      scope: d.scope,
+      kind: d.kind,
       lastCommit: d.lastCommit,
       dirty: d.dirty,
       lineCount: d.lineCount
@@ -2080,7 +2620,7 @@ async function computeAudit(rootDir, options = {}) {
   }
   let decisionsPresent = false;
   try {
-    await fs10.access(path15.join(resolvedRoot, ".mason", "decisions"));
+    await fs11.access(path18.join(resolvedRoot, ".mason", "decisions"));
     decisionsPresent = true;
   } catch {
   }
@@ -2103,6 +2643,8 @@ async function computeAudit(rootDir, options = {}) {
     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({
@@ -2113,45 +2655,24 @@ var init_audit = __esm({
     init_docs();
     init_types();
     init_checks();
+    init_advisory_review();
   }
 });
 
 // src/audit/repair.ts
-import fs11 from "fs/promises";
-import path16 from "path";
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
-import { z as z5 } from "zod";
-function findingId(finding) {
-  const e = finding.evidence;
-  let key;
-  switch (e.kind) {
-    case "missing-path":
-      key = e.claimed;
-      break;
-    case "unmentioned-dir":
-      key = e.dir;
-      break;
-    case "count-mismatch":
-      key = [e.unit.replace(/s$/, ""), e.countedFrom];
-      break;
-    case "missing-script":
-      key = e.scriptName;
-      break;
-    case "doc-behind-manifests":
-      key = null;
-      break;
-    case "decision-anchor":
-      key = [e.decisionId, e.provenance?.revision, e.provenance?.approval];
-      break;
-  }
-  return digest([finding.type, finding.anchor.doc, key]);
+import fs12 from "fs/promises";
+import path19 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import { z as z7 } 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 content2 = await readBoundedFile(await storePath(root, doc), 10 * 1024 * 1024);
       if (content2 === null) throw new Error("Context file is not regular or exceeds 10 MiB: " + doc);
@@ -2173,8 +2694,8 @@ async function stableAudit(root, checks, options = {}) {
   return report;
 }
 async function prepareRepair(rootDir, checks = ALL_CHECKS, options = {}) {
-  const root = await fs11.realpath(rootDir);
-  const selected = z5.array(checkSchema).nonempty().parse(checks);
+  const root = await fs12.realpath(rootDir);
+  const selected = z7.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.");
@@ -2189,23 +2710,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 = {}) {
-  const root = await fs11.realpath(rootDir);
-  const declaredRoot = path16.resolve(rootDir);
-  const relative = path16.isAbsolute(baselinePath) ? path16.relative(isWithinRoot(declaredRoot, baselinePath) ? declaredRoot : root, baselinePath) : baselinePath;
+async function loadRepairBaseline(rootDir, baselinePath) {
+  const root = await fs12.realpath(rootDir);
+  const declaredRoot = path19.resolve(rootDir);
+  const relative = path19.isAbsolute(baselinePath) ? path19.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 content2 = await readBoundedFile(await storePath(root, doc.path), 10 * 1024 * 1024);
       if (content2 === null || !content2.trim()) {
         diagnostics.push("Original context file " + doc.path + " is empty or unreadable; losing its claims does not verify a repair.");
@@ -2222,21 +2749,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",
@@ -2244,11 +2777,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,
@@ -2262,10 +2811,10 @@ 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."
   };
 }
-var checkSchema, commitSchema, anchorSchema, count, evidenceSchema, findingSchema, issueSchema, advisorySchema, checkResultSchema, reportSchema, baselineSchema, digest, repairFindingSchema;
+var count2, reportSchema, baselineSchema, repairFindingSchema;
 var init_repair = __esm({
   "src/audit/repair.ts"() {
     "use strict";
@@ -2277,205 +2826,134 @@ var init_repair = __esm({
     init_files();
     init_paths();
     init_types();
-    checkSchema = z5.enum(["deleted-reference", "new-module", "stale-count", "dead-command", "deps-changed", "decision-anchor-drift"]);
-    commitSchema = z5.object({ hash: z5.string().regex(/^[a-f0-9]{40,64}$/), date: z5.string(), subject: z5.string() });
-    anchorSchema = z5.object({ doc: z5.string(), line: z5.number().int().positive().nullable(), excerpt: z5.string().nullable() });
-    count = z5.number().int().nonnegative();
-    evidenceSchema = z5.discriminatedUnion("kind", [
-      z5.object({
-        kind: z5.literal("missing-path"),
-        claimed: z5.string(),
-        renamedTo: z5.string().nullable(),
-        deletedInCommit: commitSchema.nullable(),
-        everTracked: z5.boolean(),
-        parentDirExists: z5.boolean()
-      }),
-      z5.object({
-        kind: z5.literal("unmentioned-dir"),
-        dir: z5.string(),
-        sourceFileCount: count,
-        firstCommit: commitSchema.nullable(),
-        checkedDocs: z5.array(z5.string())
-      }),
-      z5.object({
-        kind: z5.literal("count-mismatch"),
-        claimed: count,
-        actual: count,
-        unit: z5.string(),
-        countedFrom: z5.string(),
-        members: z5.array(z5.string())
-      }),
-      z5.object({
-        kind: z5.literal("missing-script"),
-        scriptName: z5.string(),
-        invocation: z5.string(),
-        manifestsChecked: z5.array(z5.string()),
-        availableScripts: z5.array(z5.string())
-      }),
-      z5.object({
-        kind: z5.literal("doc-behind-manifests"),
-        docLastCommit: commitSchema,
-        manifestCommits: z5.array(commitSchema.extend({ files: z5.array(z5.string()) })),
-        totalCommits: count
-      }),
-      z5.object({
-        kind: z5.literal("decision-anchor"),
-        decisionId: z5.string(),
-        title: z5.string(),
-        changedFiles: z5.array(z5.string()),
-        refreshedHash: z5.string(),
-        provenance: z5.object({}).passthrough().optional()
-      })
-    ]);
-    findingSchema = z5.object({ message: z5.string(), anchor: anchorSchema, evidence: evidenceSchema });
-    issueSchema = findingSchema.extend({
-      type: z5.enum(["deleted-reference", "new-module", "stale-count", "dead-command"]),
-      confidence: z5.enum(["certain", "likely"])
-    });
-    advisorySchema = findingSchema.extend({ type: z5.enum(["deps-changed", "decision-anchor-drift"]) });
-    checkResultSchema = z5.object({
-      issues: z5.array(issueSchema),
-      advisories: z5.array(advisorySchema),
-      suppressedAdvisories: z5.array(advisorySchema).optional(),
-      skipped: z5.array(z5.object({ check: z5.string(), reason: z5.string(), doc: z5.string().optional() }))
-    });
-    reportSchema = z5.object({
-      version: z5.literal(1),
-      root: z5.string(),
-      gitAvailable: z5.literal(true),
+    init_findings();
+    init_advisory_review();
+    init_findings();
+    count2 = z7.number().int().nonnegative();
+    reportSchema = z7.object({
+      version: z7.literal(1),
+      root: z7.string(),
+      gitAvailable: z7.literal(true),
       headHash: commitSchema.shape.hash,
-      checksRun: z5.array(checkSchema).nonempty(),
-      docs: z5.array(z5.object({
-        path: z5.enum(DOC_CANDIDATES),
+      checksRun: z7.array(checkSchema).nonempty(),
+      docs: z7.array(z7.object({
+        path: z7.string().refine((value) => normalizeRepoPath(value) === value),
+        scope: z7.string().optional(),
+        kind: z7.enum(["instructions", "readme"]).optional(),
         lastCommit: commitSchema.nullable(),
-        dirty: z5.boolean(),
-        lineCount: count
+        dirty: z7.boolean(),
+        lineCount: count2
       })).nonempty(),
-      decisionsChecked: z5.boolean(),
-      clean: z5.boolean(),
-      issues: z5.array(issueSchema),
-      advisories: z5.array(advisorySchema),
-      suppressedAdvisories: z5.array(advisorySchema).optional(),
-      skippedChecks: z5.array(z5.object({ check: z5.string(), reason: z5.string(), doc: z5.string().optional() }))
+      decisionsChecked: z7.boolean(),
+      clean: z7.boolean(),
+      issues: z7.array(issueSchema),
+      advisories: z7.array(advisorySchema),
+      suppressedAdvisories: z7.array(advisorySchema).optional(),
+      skippedChecks: z7.array(z7.object({ check: z7.string(), reason: z7.string(), doc: z7.string().optional() }))
     });
-    baselineSchema = z5.object({
-      kind: z5.literal("mason-audit-repair"),
-      version: z5.literal(1),
-      createdAt: z5.string().datetime(),
+    baselineSchema = z7.object({
+      kind: z7.literal("mason-audit-repair"),
+      version: z7.literal(1),
+      createdAt: z7.string().datetime(),
       report: reportSchema,
-      digest: z5.string().regex(/^[a-f0-9]{64}$/)
+      digest: z7.string().regex(/^[a-f0-9]{64}$/)
     });
-    digest = (value) => createHash2("sha256").update(JSON.stringify(value)).digest("hex");
-    repairFindingSchema = z5.object({
-      id: z5.string(),
-      original: z5.union([issueSchema, advisorySchema]),
-      status: z5.enum(["resolved", "unresolved", "review-required", "unverified"]),
-      reason: z5.string(),
-      current: z5.union([issueSchema, advisorySchema]).optional()
+    repairFindingSchema = z7.object({
+      id: z7.string(),
+      original: z7.union([issueSchema, advisorySchema]),
+      status: z7.enum(["resolved", "unresolved", "review-required", "unverified"]),
+      reason: z7.string(),
+      current: z7.union([issueSchema, advisorySchema]).optional(),
+      review: reviewSummarySchema.optional()
     });
   }
 });
 
 // src/automation/evidence.ts
-var evidence_exports = {};
-__export(evidence_exports, {
-  checkCache: () => checkCache,
-  git: () => git2,
-  hash: () => hash,
-  readInputs: () => readInputs,
-  workspace: () => workspace
-});
-import fs12 from "fs/promises";
-import path17 from "path";
+import fs13 from "fs/promises";
+import path20 from "path";
 import { createHash as createHash3 } from "crypto";
-import { execFile as execFile8 } from "child_process";
-import { promisify as promisify8 } from "util";
-import fg4 from "fast-glob";
-import { z as z6 } from "zod";
-async function git2(root, ...args) {
+import { execFile as execFile9 } from "child_process";
+import { promisify as promisify9 } from "util";
+import fg5 from "fast-glob";
+import { z as z8 } from "zod";
+async function git3(root, ...args) {
   return (await exec7("git", args, { cwd: root, maxBuffer: 16 * 1024 * 1024, timeout: 1e4 })).stdout;
 }
 async function workspace(dir) {
-  const root = await fs12.realpath((await git2(dir, "rev-parse", "--show-toplevel")).trim());
-  const gitDir = await fs12.realpath((await git2(root, "rev-parse", "--absolute-git-dir")).trim());
+  const root = await fs13.realpath((await git3(dir, "rev-parse", "--show-toplevel")).trim());
+  const gitDir = await fs13.realpath((await git3(root, "rev-parse", "--absolute-git-dir")).trim());
   let branch;
   try {
-    branch = (await git2(root, "symbolic-ref", "--quiet", "HEAD")).trim();
+    branch = (await git3(root, "symbolic-ref", "--quiet", "HEAD")).trim();
   } catch {
     branch = "detached";
   }
   return { root, gitDir, branch, directory: ".mason/reports/automation/" + hash([root, gitDir, branch]).slice(0, 24) };
 }
 async function readInputs(root) {
+  const docPaths = await discoverDocPaths(root);
   const [headText, docStatus, shallowPath, replacements] = await Promise.all([
-    git2(root, "rev-parse", "HEAD"),
-    git2(root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ...DOC_CANDIDATES),
-    git2(root, "rev-parse", "--git-path", "shallow"),
-    git2(root, "for-each-ref", "--format=%(refname) %(objectname)", "refs/replace")
+    git3(root, "rev-parse", "HEAD"),
+    docPaths.length ? git3(root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ...docPaths.map((p) => `:(literal)${p}`)) : "",
+    git3(root, "rev-parse", "--git-path", "shallow"),
+    git3(root, "for-each-ref", "--format=%(refname) %(objectname)", "refs/replace")
   ]);
   const head = headText.trim();
   let shallow = null;
   try {
-    shallow = await fs12.readFile(path17.resolve(root, shallowPath.trim()), "utf8");
+    shallow = await fs13.readFile(path20.resolve(root, shallowPath.trim()), "utf8");
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
   const docs = {};
   const docContents = [];
   const claims = [];
-  for (const file of DOC_CANDIDATES) {
+  for (const file of docPaths) {
     const text2 = await content(root, file);
     docs[file] = text2 === null ? null : hash(text2);
     docContents.push([file, text2]);
     for (const claim of text2 ? extractClaims(text2).paths : []) {
-      if (internal(claim.path) || claim.path.startsWith(".mason/")) continue;
-      const exists2 = async (p) => fs12.access(path17.resolve(root, p)).then(() => true, () => false);
-      claims.push([claim.path, await exists2(claim.path), await exists2(path17.dirname(claim.path))]);
-    }
-  }
-  const combinedDocs = docContents.map(([, text2]) => text2 ?? "").join("\n");
-  const countClaims = docContents.flatMap(([, text2]) => text2 ? extractClaims(text2).counts : []);
-  const commandClaims = docContents.flatMap(([, text2]) => text2 ? extractClaims(text2).commands : []);
-  const rootPackage = await content(root, "package.json");
-  let rootScripts = null;
-  if (rootPackage !== null) {
-    try {
-      const pkg = JSON.parse(rootPackage);
-      rootScripts = pkg?.scripts && typeof pkg.scripts === "object" ? Object.keys(pkg.scripts) : [];
-    } catch {
+      const scope = pathClaimScope(file, claim);
+      if (scope?.candidates.some(gitMetadataPath)) continue;
+      for (const candidate of scope?.candidates ?? []) {
+        if (optionalMasonPath(candidate)) continue;
+        claims.push([candidate, await pathExists(root, candidate), await pathExists(root, path20.posix.dirname(candidate))]);
+      }
     }
   }
-  const needsWorkspaceScripts = rootScripts !== null && commandClaims.some((claim) => !rootScripts.includes(claim.scriptName));
+  const parsedDocs = docContents.map(([file, text2]) => ({ path: file, content: text2 ?? "", claims: extractClaims(text2 ?? "") }));
+  const combinedDocs = moduleDocumentation(parsedDocs);
+  const countClaims = parsedDocs.flatMap((doc) => doc.claims.counts.map((claim) => ({ doc: doc.path, claim })));
   const decisionDirectory = await storePath(root, ".mason/decisions");
-  const decisionPresence = await fs12.lstat(decisionDirectory).then((stat) => stat.isDirectory() ? "directory" : "file", (error) => {
+  const decisionPresence = await fs13.lstat(decisionDirectory).then((stat) => stat.isDirectory() ? "directory" : "file", (error) => {
     if (error.code === "ENOENT") return "absent";
     throw error;
   });
-  const [modules, counts, manifests, decisionFiles] = await Promise.all([
+  const [modules, counts, commands, decisionFiles] = await Promise.all([
     combinedDocs ? moduleCandidates(root, combinedDocs) : [],
-    Promise.all(countClaims.map((claim) => resolveCountSource(root, claim))),
-    needsWorkspaceScripts ? commandManifests(root) : [],
-    fg4(".mason/decisions/*.json", { cwd: root, dot: true, onlyFiles: false, followSymbolicLinks: false })
+    Promise.all(countClaims.map(({ doc, claim }) => resolveDocCountSource(root, doc, claim))),
+    commandInputs(root, parsedDocs),
+    fg5(".mason/decisions/*.json", { cwd: root, dot: true, onlyFiles: false, followSymbolicLinks: false })
   ]);
-  const packages = [["package.json", rootPackage], ...await Promise.all(manifests.sort().map(async (file) => [file, await content(root, file)]))];
   const decisions = await Promise.all(decisionFiles.sort().map(async (file) => {
     await storePath(root, file);
     return [file, await content(root, file)];
   }));
   const [status, index2] = decisions.length ? await Promise.all([
-    git2(root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ".", ":(exclude).mason/reports"),
-    git2(root, "ls-files", "--stage", "-z", "--", ".", ":(exclude).mason/reports")
+    git3(root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ".", ":(exclude).mason/reports"),
+    git3(root, "ls-files", "--stage", "-z", "--", ".", ":(exclude).mason/reports")
   ]) : ["", ""];
-  const common = [3, engineVersion, head, shallow, replacements, docContents];
+  const common = [4, engineVersion, head, shallow, replacements, docContents];
   const keys = {
     "deleted-reference": hash([common, claims, docStatus]),
     "new-module": hash([common, modules]),
     "stale-count": hash([common, counts]),
-    "dead-command": hash([common, packages]),
+    "dead-command": hash([common, commands]),
     "deps-changed": hash([common, docStatus]),
     "decision-anchor-drift": hash([common, decisionPresence, decisions, status, index2])
   };
-  return { fingerprint: hash(keys), head, docs, keys };
+  return { fingerprint: hash([keys, await advisoryReviewInventory(root)]), head, docs, keys };
 }
 function checkCache(raw, inputs) {
   let entries = {};
@@ -2502,11 +2980,12 @@ function checkCache(raw, inputs) {
     return { version: 1, entries: canonical, digest: hash(canonical) };
   } };
 }
-var exec7, engineVersion, hash, content, internal, cacheSchema;
+var exec7, engineVersion, hash, content, cacheSchema;
 var init_evidence = __esm({
   "src/automation/evidence.ts"() {
     "use strict";
     init_docs();
+    init_scope();
     init_claims();
     init_repair();
     init_checks();
@@ -2515,20 +2994,20 @@ var init_evidence = __esm({
     init_stale_count();
     init_dead_command();
     init_storage();
-    exec7 = promisify8(execFile8);
-    engineVersion = true ? "0.16.3" : "development";
+    init_advisory_review();
+    exec7 = promisify9(execFile9);
+    engineVersion = true ? "0.17.1" : "development";
     hash = (value) => createHash3("sha256").update(JSON.stringify(value)).digest("hex");
     content = readAuditInput;
-    internal = (file) => file === ".mason" || file === ".mason/reports" || file.startsWith(".mason/reports/");
-    cacheSchema = z6.object({ version: z6.literal(1), entries: z6.record(z6.object({ key: z6.string(), result: checkResultSchema })), digest: z6.string() });
+    cacheSchema = z8.object({ version: z8.literal(1), entries: z8.record(z8.object({ key: z8.string(), result: checkResultSchema })), digest: z8.string() });
   }
 });
 
 // src/automation/execution.ts
 import os2 from "os";
-import fs13 from "fs/promises";
+import fs14 from "fs/promises";
 import { randomUUID as randomUUID3 } from "crypto";
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 function parseExecution(raw) {
   try {
     return executionSchema.parse(raw);
@@ -2546,7 +3025,7 @@ function automationFailure(error) {
     codes.add(String(cause.code));
     cause = cause.cause;
   }
-  const code = codes.has("ENOSPC") || codes.has("EDQUOT") ? "storage-full" : /changed during|changed while|changed between/.test(message2) ? "inputs-changed" : /Automation is busy/.test(message2) ? "busy" : /not a git repository|unknown revision|bad revision|different history|unreachable/.test(message2) ? "history-unavailable" : error instanceof z7.ZodError || error instanceof SyntaxError || /Hook input|Expected one command|Unknown automation command|--host/.test(message2) ? "invalid-input" : /store|baseline|modified|symbolic link|Symlink|automation state|state belongs/.test(message2) ? "invalid-evidence" : [...codes].some((c) => /^E[A-Z]+$/.test(c)) ? "io-error" : "internal";
+  const code = codes.has("ENOSPC") || codes.has("EDQUOT") ? "storage-full" : /changed during|changed while|changed between/.test(message2) ? "inputs-changed" : /Automation is busy/.test(message2) ? "busy" : /not a git repository|unknown revision|bad revision|different history|unreachable/.test(message2) ? "history-unavailable" : error instanceof z9.ZodError || error instanceof SyntaxError || /Hook input|Expected one command|Unknown automation command|--host/.test(message2) ? "invalid-input" : /store|baseline|modified|symbolic link|Symlink|automation state|state belongs/.test(message2) ? "invalid-evidence" : [...codes].some((c) => /^E[A-Z]+$/.test(c)) ? "io-error" : "internal";
   return { code, message: message2, retryable: ["inputs-changed", "storage-full", "busy", "io-error"].includes(code), receiptRecorded: false };
 }
 function failureMessage(error) {
@@ -2654,7 +3133,7 @@ async function recordExecution(root, directory, event, run) {
       throw Object.assign(new Error(failure.message, { cause: error }), { failure });
     }
   } finally {
-    await fs13.rm(await storePath(root, owner), { force: true }).catch(() => {
+    await fs14.rm(await storePath(root, owner), { force: true }).catch(() => {
     });
   }
 }
@@ -2675,33 +3154,33 @@ var init_execution = __esm({
     init_store();
     init_evidence();
     init_storage();
-    failureSchema = z7.object({
-      code: z7.enum(["inputs-changed", "storage-full", "busy", "invalid-input", "history-unavailable", "invalid-evidence", "io-error", "internal"]),
-      message: z7.string(),
-      retryable: z7.boolean(),
-      receiptRecorded: z7.boolean()
+    failureSchema = z9.object({
+      code: z9.enum(["inputs-changed", "storage-full", "busy", "invalid-input", "history-unavailable", "invalid-evidence", "io-error", "internal"]),
+      message: z9.string(),
+      retryable: z9.boolean(),
+      receiptRecorded: z9.boolean()
     });
-    attemptSchema = z7.object({
-      id: z7.string().regex(/^[a-zA-Z0-9_-]+$/),
-      lease: z7.literal(true).optional(),
-      event: z7.string(),
-      startedAt: z7.string(),
-      finishedAt: z7.string().optional(),
-      durationMs: z7.number().nonnegative().optional(),
-      pid: z7.number().int().positive(),
-      host: z7.string(),
-      status: z7.enum(["running", "completed", "failed", "unknown"]),
-      verificationStatus: z7.string().optional(),
-      reportPath: z7.string().optional(),
+    attemptSchema = z9.object({
+      id: z9.string().regex(/^[a-zA-Z0-9_-]+$/),
+      lease: z9.literal(true).optional(),
+      event: z9.string(),
+      startedAt: z9.string(),
+      finishedAt: z9.string().optional(),
+      durationMs: z9.number().nonnegative().optional(),
+      pid: z9.number().int().positive(),
+      host: z9.string(),
+      status: z9.enum(["running", "completed", "failed", "unknown"]),
+      verificationStatus: z9.string().optional(),
+      reportPath: z9.string().optional(),
       failure: failureSchema.optional()
     });
-    executionSchema = z7.object({ version: z7.literal(1), attempts: z7.array(attemptSchema).max(160), discardedAttempts: z7.number().int().nonnegative().default(0) });
-    notificationsSchema = z7.object({ version: z7.literal(1), sessions: z7.record(z7.object({
-      signature: z7.string(),
+    executionSchema = z9.object({ version: z9.literal(1), attempts: z9.array(attemptSchema).max(160), discardedAttempts: z9.number().int().nonnegative().default(0) });
+    notificationsSchema = z9.object({ version: z9.literal(1), sessions: z9.record(z9.object({
+      signature: z9.string(),
       code: failureSchema.shape.code,
-      message: z7.string(),
-      count: z7.number().int().positive(),
-      lastAt: z7.string()
+      message: z9.string(),
+      count: z9.number().int().positive(),
+      lastAt: z9.string()
     })) });
     leasePath = (directory, id) => `${directory}/executions/${id}.json`;
   }
@@ -2709,7 +3188,7 @@ var init_execution = __esm({
 
 // src/automation/runtime.ts
 import { randomUUID as randomUUID4 } from "crypto";
-import { z as z8 } from "zod";
+import { z as z10 } from "zod";
 async function observeReadOnlyTool(dir, event) {
   const ws = await workspace(dir);
   await withLock(ws.root, ws.directory, async () => {
@@ -2787,7 +3266,7 @@ async function computeAnalysis(ws, state, inputs, event) {
     baselinePaths: [],
     reportPath: "",
     findings: [],
-    diagnostics: ["No AGENTS.md, CLAUDE.md, or .claude/CLAUDE.md exists. Documentation capture is unavailable; other Mason tools remain usable."],
+    diagnostics: ["No README.md or agent instruction files were discovered. Documentation capture is unavailable; other Mason tools remain usable."],
     checks: { ran: [], reused: [], skipped: [] },
     counts: { resolved: 0, unresolved: 0, "review-required": 0, unverified: 0 },
     capture: "unknown",
@@ -2798,7 +3277,7 @@ async function computeAnalysis(ws, state, inputs, event) {
     const previous = await readStoreJson(ws.root, state.latest);
     if (!previous?.head || !/^[a-f0-9]{40,64}$/.test(previous.head)) throw new Error("The previous detached checkout evidence is unavailable.");
     try {
-      await git2(ws.root, "merge-base", "--is-ancestor", previous.head, inputs.head);
+      await git3(ws.root, "merge-base", "--is-ancestor", previous.head, inputs.head);
     } catch {
       throw new Error("Detached checkout moved to a different history; original repair evidence was retained. Inspect that baseline explicitly.");
     }
@@ -3003,43 +3482,76 @@ var init_runtime = __esm({
     init_storage();
     init_evidence();
     init_store();
-    SCOPE = "Documentation audit evidence only. Hook receipts show observed events, not complete interception. Resolved claims no longer fail their checks; advisories need separate review. Repair only within the user's task authorization.";
+    SCOPE = "Documentation audit evidence only. Hook receipts show observed events, not complete interception. Resolved findings no longer fail their checks or have a recorded assessment covering current evidence. Repair and review only within the user's task authorization.";
     priority = { resolved: 0, "review-required": 1, unresolved: 2, unverified: 3 };
     cleanText = (text2) => text2.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 250);
-    analysisSchema = z8.object({
-      id: z8.string(),
-      fingerprint: z8.string(),
-      completedAt: z8.number(),
-      baselineDigest: z8.string(),
-      report: z8.object({
-        version: z8.literal(1),
-        status: z8.enum(["verified", "issues-remain", "incomplete", "unavailable"]),
-        root: z8.string(),
-        branch: z8.string(),
-        head: z8.string(),
-        baselinePaths: z8.array(z8.string()),
-        reportPath: z8.string(),
-        findings: z8.array(repairFindingSchema),
-        diagnostics: z8.array(z8.string()),
-        checks: z8.object({
-          ran: z8.array(z8.string()),
-          reused: z8.array(z8.string()),
-          skipped: z8.array(z8.object({ check: z8.string(), reason: z8.string(), doc: z8.string().optional() }))
+    analysisSchema = z10.object({
+      id: z10.string(),
+      fingerprint: z10.string(),
+      completedAt: z10.number(),
+      baselineDigest: z10.string(),
+      report: z10.object({
+        version: z10.literal(1),
+        status: z10.enum(["verified", "issues-remain", "incomplete", "unavailable"]),
+        root: z10.string(),
+        branch: z10.string(),
+        head: z10.string(),
+        baselinePaths: z10.array(z10.string()),
+        reportPath: z10.string(),
+        findings: z10.array(repairFindingSchema),
+        diagnostics: z10.array(z10.string()),
+        checks: z10.object({
+          ran: z10.array(z10.string()),
+          reused: z10.array(z10.string()),
+          skipped: z10.array(z10.object({ check: z10.string(), reason: z10.string(), doc: z10.string().optional() }))
         }),
-        counts: z8.object({ resolved: z8.number(), unresolved: z8.number(), "review-required": z8.number(), unverified: z8.number() }),
-        capture: z8.enum(["observed", "unknown"]),
-        scope: z8.string()
+        counts: z10.object({ resolved: z10.number(), unresolved: z10.number(), "review-required": z10.number(), unverified: z10.number() }),
+        capture: z10.enum(["observed", "unknown"]),
+        scope: z10.string()
       })
     });
-    sharedSchema = z8.object({ analysis: analysisSchema, digest: z8.string() });
+    sharedSchema = z10.object({ analysis: analysisSchema, digest: z10.string() });
     baselineDigest = async (ws, state) => hash(await Promise.all(
       state.baselines.map(async (b) => [b.path, await readStoreJson(ws.root, b.path)])
     ));
   }
 });
 
+// src/automation/hook-root.ts
+import fs15 from "fs/promises";
+import path21 from "path";
+async function repositoryRoot(dir) {
+  if (!path21.isAbsolute(dir)) throw new Error("Hook input working directory must be absolute.");
+  try {
+    return await fs15.realpath((await git3(dir, "rev-parse", "--show-toplevel")).trim());
+  } catch (error) {
+    if (error.code === "ENOENT" || /not a git repository/.test(String(error.stderr))) return null;
+    throw error;
+  }
+}
+async function resolveHookRoot(host, cwd, options = {}) {
+  const current = await repositoryRoot(cwd);
+  if (current) return current;
+  const projectDir = options.projectDir ?? (host === "claude" ? process.env.CLAUDE_PROJECT_DIR : void 0);
+  const projectRoot = projectDir ? await repositoryRoot(projectDir) : null;
+  if (projectDir && !projectRoot) throw new Error("Hook input is outside Git and the host project is no longer a Git repository. Restore its history before running mason check.");
+  const launchRoot = await repositoryRoot(options.launchCwd ?? process.cwd());
+  const roots = [...new Set([launchRoot, projectRoot].filter((root) => root !== null))];
+  if (!roots.length) throw new Error("Hook input is outside a Git repository and no project root is available. Return to the project and run mason check.");
+  if (roots.length > 1) throw new Error("Hook input is outside a Git repository and project roots disagree. Return to the intended checkout and run mason check; verification was not established.");
+  const worktrees = (await git3(roots[0], "worktree", "list", "--porcelain", "-z")).split("\0").filter((field) => field.startsWith("worktree "));
+  if (worktrees.length !== 1) throw new Error("Hook input is outside a Git repository with multiple worktrees. Return to the intended worktree and run mason check; the active checkout is unknown.");
+  return roots[0];
+}
+var init_hook_root = __esm({
+  "src/automation/hook-root.ts"() {
+    "use strict";
+    init_evidence();
+  }
+});
+
 // src/setup/model.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 async function loadSetup(root) {
   const raw = await readStoreJson(root, SETUP_PATH);
   if (raw === null) return null;
@@ -3057,42 +3569,52 @@ var init_model = __esm({
   "src/setup/model.ts"() {
     "use strict";
     init_storage();
-    setupHostSchema = z9.object({
-      configuredVersion: z9.string(),
-      revision: z9.string().uuid(),
-      fingerprint: z9.string(),
-      mcpFingerprint: z9.string(),
-      instructions: z9.array(z9.string())
+    setupHostSchema = z11.object({
+      configuredVersion: z11.string(),
+      revision: z11.string().uuid(),
+      fingerprint: z11.string(),
+      mcpFingerprint: z11.string(),
+      instructions: z11.array(z11.string())
     });
-    setupSchema = z9.object({ version: z9.literal(2), hosts: z9.object({
+    setupSchema = z11.object({ version: z11.literal(2), hosts: z11.object({
       codex: setupHostSchema.optional(),
       claude: setupHostSchema.optional()
     }) });
     SETUP_PATH = ".mason/local/setup.json";
-    receiptSchema = z9.object({
-      version: z9.literal(1),
-      host: z9.enum(["codex", "claude"]),
-      status: z9.enum(["installing", "configured"]),
-      initialReportPath: z9.string(),
-      initialBaselinePaths: z9.array(z9.string()),
-      root: z9.string(),
-      revision: z9.string().uuid(),
-      configuredAt: z9.string().optional()
+    receiptSchema = z11.object({
+      version: z11.literal(1),
+      host: z11.enum(["codex", "claude"]),
+      status: z11.enum(["installing", "configured"]),
+      initialReportPath: z11.string(),
+      initialBaselinePaths: z11.array(z11.string()),
+      root: z11.string(),
+      revision: z11.string().uuid(),
+      configuredAt: z11.string().optional()
     });
   }
 });
 
 // src/setup/launcher.ts
-import { execFile as execFile9 } from "child_process";
-import { promisify as promisify9 } from "util";
-import fs14 from "fs/promises";
+var launcher_exports = {};
+__export(launcher_exports, {
+  executingVersion: () => executingVersion,
+  globalCommand: () => globalCommand,
+  hookCommand: () => hookCommand,
+  inactiveSetupMessage: () => inactiveSetupMessage,
+  installedCommand: () => installedCommand,
+  mcpCommand: () => mcpCommand,
+  prepareLaunch: () => prepareLaunch
+});
+import { execFile as execFile10 } from "child_process";
+import { promisify as promisify10 } from "util";
+import fs16 from "fs/promises";
 function globalCommand(args, platform = process.platform) {
   return platform === "win32" ? { command: "cmd.exe", args: ["/d", "/s", "/c", "mason", ...args] } : { command: "mason", args };
 }
 async function installedCommand() {
   const invocation = globalCommand(["internal-integration-version"]);
   try {
-    const { stdout } = await promisify9(execFile9)(
+    const { stdout } = await promisify10(execFile10)(
       invocation.command,
       invocation.args,
       { timeout: 5e3, maxBuffer: 8192, windowsHide: true }
@@ -3104,13 +3626,31 @@ async function installedCommand() {
     return { available: false, version: null, message: "An up-to-date mason command is not available on this process's PATH. Install or upgrade Mason, then reopen your terminal or desktop assistant and rerun mason setup." };
   }
 }
+async function prepareLaunch(host, options = {}) {
+  const root = await fs16.realpath((await git3(options.dir ?? process.cwd(), "rev-parse", "--show-toplevel")).trim());
+  const entry = (await loadSetup(root))?.hosts[host];
+  process.env.MASON_SETUP_ROOT = root;
+  process.env.MASON_SETUP_HOST = host;
+  delete process.env.MASON_SETUP_REVISION;
+  if (!entry) {
+    if (options.allowInactive) return false;
+    throw new Error(`Mason is not configured locally for ${host}. Run mason setup --host ${host} in this checkout.`);
+  }
+  process.env.MASON_SETUP_REVISION = entry.revision;
+  return true;
+}
+function inactiveSetupMessage() {
+  const host = process.env.MASON_SETUP_HOST;
+  if (!process.env.MASON_SETUP_ROOT || process.env.MASON_SETUP_REVISION || host !== "claude" && host !== "codex") return null;
+  return `Mason MCP is available, but automatic hooks are inactive in ${process.env.MASON_SETUP_ROOT}. Run mason setup --host ${host} in that checkout, review the host configuration, then restart the assistant. Setup has not been performed automatically.`;
+}
 var executingVersion, mcpCommand, hookCommand;
 var init_launcher = __esm({
   "src/setup/launcher.ts"() {
     "use strict";
     init_evidence();
     init_model();
-    executingVersion = () => true ? "0.16.3" : "development";
+    executingVersion = () => true ? "0.17.1" : "development";
     mcpCommand = (host) => globalCommand(["--setup-host", host, "mcp"]);
     hookCommand = (host) => `mason --setup-host ${host} auto`;
   }
@@ -3123,8 +3663,8 @@ __export(observations_exports, {
   observeActivation: () => observeActivation,
   readObservation: () => readObservation
 });
-import fs15 from "fs/promises";
-import { z as z10 } from "zod";
+import fs17 from "fs/promises";
+import { z as z12 } from "zod";
 function observationPath(directory, host, revision, version = executingVersion()) {
   return `${directory}/activation/${host}-${revision}-${hash(version).slice(0, 12)}.json`;
 }
@@ -3137,11 +3677,17 @@ async function readObservation(root, directory, host, revision, version = execut
 }
 async function observeActivation(dir, event, options = {}) {
   const host = process.env.MASON_SETUP_HOST, revision = process.env.MASON_SETUP_REVISION;
-  if (host !== "codex" && host !== "claude" || !revision || !process.env.MASON_SETUP_ROOT) return null;
+  if (host !== "codex" && host !== "claude" || !process.env.MASON_SETUP_ROOT) return null;
   try {
+    if (!revision) {
+      if ((await loadSetup(process.env.MASON_SETUP_ROOT))?.hosts[host]) {
+        return "Mason setup is now present. Restart the assistant to connect this MCP session to the configured integration; activation has not been established by this session.";
+      }
+      return inactiveSetupMessage();
+    }
     const capturedDirectory = options.directory?.match(/^\.mason\/reports\/automation\/[a-f0-9]{24}$/)?.[0] ?? options.reportPath?.match(/^(\.mason\/reports\/automation\/[a-f0-9]{24})\/checks\//)?.[1];
-    const ws = capturedDirectory ? { root: await fs15.realpath(dir), directory: capturedDirectory } : await workspace(dir);
-    if (ws.root !== await fs15.realpath(process.env.MASON_SETUP_ROOT)) return null;
+    const ws = capturedDirectory ? { root: await fs17.realpath(dir), directory: capturedDirectory } : await workspace(dir);
+    if (ws.root !== await fs17.realpath(process.env.MASON_SETUP_ROOT)) return null;
     const setup = await loadSetup(ws.root);
     if (setup?.hosts[host]?.revision !== revision) return "Mason setup changed; restart the assistant to observe the current integration.";
     const directory = ws.directory + "/activation";
@@ -3189,26 +3735,26 @@ var init_observations = __esm({
     init_storage();
     init_model();
     init_launcher();
-    observationSchema = z10.object({
-      version: z10.literal(1),
-      masonVersion: z10.string(),
-      root: z10.string(),
-      revision: z10.string(),
-      host: z10.enum(["codex", "claude"]),
-      contextCalls: z10.number().int().nonnegative(),
-      lastContextAt: z10.string().optional(),
-      sessions: z10.record(z10.object({
-        events: z10.array(z10.enum(events)),
-        at: z10.string(),
-        verificationStatus: z10.string().optional(),
-        reportPath: z10.string().optional()
+    observationSchema = z12.object({
+      version: z12.literal(1),
+      masonVersion: z12.string(),
+      root: z12.string(),
+      revision: z12.string(),
+      host: z12.enum(["codex", "claude"]),
+      contextCalls: z12.number().int().nonnegative(),
+      lastContextAt: z12.string().optional(),
+      sessions: z12.record(z12.object({
+        events: z12.array(z12.enum(events)),
+        at: z12.string(),
+        verificationStatus: z12.string().optional(),
+        reportPath: z12.string().optional()
       }))
     });
   }
 });
 
 // src/automation/adapters.ts
-import { z as z11 } from "zod";
+import { z as z13 } from "zod";
 function normalizeHook(host, raw) {
   hostSchema.parse(host);
   const input2 = inputSchema.parse(raw);
@@ -3222,7 +3768,7 @@ function normalizeHook(host, raw) {
     stopHookActive: input2.stop_hook_active || input2.permission_mode === "plan"
   } };
 }
-async function runAutomationHook(host, stdin) {
+async function runAutomationHook(host, stdin, options = {}) {
   let name = "";
   let hook;
   try {
@@ -3236,6 +3782,11 @@ async function runAutomationHook(host, stdin) {
     const input2 = normalizeHook(host, raw);
     hook = input2;
     name = input2.name;
+    if (options.managed) {
+      input2.cwd = await resolveHookRoot(host, input2.cwd);
+      const { prepareLaunch: prepareLaunch2 } = await Promise.resolve().then(() => (init_launcher(), launcher_exports));
+      if (!await prepareLaunch2(host, { dir: input2.cwd, allowInactive: true })) return null;
+    }
     if (["before_tool", "after_tool"].includes(input2.event.event) && input2.readOnly) {
       const observed = await observeReadOnlyTool(input2.cwd, input2.event);
       const { observeActivation: observeActivation3 } = await Promise.resolve().then(() => (init_observations(), observations_exports));
@@ -3268,6 +3819,9 @@ function managedHookCommand(host, platform = process.platform) {
 function knownManagedHookCommands(host) {
   return [managedHookCommand(host, "linux"), managedHookCommand(host, "win32"), `mason --setup-host ${host} auto hook --host ${host}`];
 }
+function compatibleManagedHookCommands(host, platform = process.platform) {
+  return [managedHookCommand(host, platform), `mason --setup-host ${host} auto hook --host ${host}`];
+}
 function hookConfig(host, command = "npx --no-install --package mason-context mason-auto") {
   const handler = { type: "command", command: command === `mason --setup-host ${host} auto` ? managedHookCommand(host) : command + " hook --host " + host, timeout: 30 };
   return { hooks: Object.fromEntries(HOOK_EVENTS.map((name) => [
@@ -3282,15 +3836,16 @@ var init_adapters = __esm({
     init_execution();
     init_runtime();
     init_store();
-    inputSchema = z11.object({
-      cwd: z11.string().min(1),
-      session_id: z11.string().min(1).max(500),
-      hook_event_name: z11.enum(["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"]),
-      tool_name: z11.string().optional(),
-      tool_use_id: z11.string().max(500).optional(),
-      tool_input: z11.unknown().optional(),
-      stop_hook_active: z11.boolean().optional(),
-      permission_mode: z11.string().optional()
+    init_hook_root();
+    inputSchema = z13.object({
+      cwd: z13.string().min(1),
+      session_id: z13.string().min(1).max(500),
+      hook_event_name: z13.enum(["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"]),
+      tool_name: z13.string().optional(),
+      tool_use_id: z13.string().max(500).optional(),
+      tool_input: z13.unknown().optional(),
+      stop_hook_active: z13.boolean().optional(),
+      permission_mode: z13.string().optional()
     });
     lifecycle = {
       SessionStart: "session_start",
@@ -3310,8 +3865,8 @@ __export(files_exports, {
   managedBlock: () => managedBlock,
   readText: () => readText
 });
-import fs16 from "fs/promises";
-import path18 from "path";
+import fs18 from "fs/promises";
+import path22 from "path";
 import { randomUUID as randomUUID5 } from "crypto";
 async function readText(root, file) {
   try {
@@ -3340,14 +3895,14 @@ async function applyEdit(root, edit) {
   if (edit.after === null) {
     const file2 = await storePath(root, edit.path);
     if (await readText(root, edit.path) !== edit.before) throw new Error("Input changed during removal: " + edit.path);
-    await fs16.unlink(file2);
+    await fs18.unlink(file2);
     return true;
   }
   const file = await storePath(root, edit.path, true);
-  const temporary = path18.join(path18.dirname(file), ".mason-setup-" + randomUUID5() + ".tmp");
+  const temporary = path22.join(path22.dirname(file), ".mason-setup-" + randomUUID5() + ".tmp");
   try {
-    const mode = await fs16.stat(file).then((s) => s.mode & 511, () => 384);
-    const handle = await fs16.open(temporary, "wx", mode);
+    const mode = await fs18.stat(file).then((s) => s.mode & 511, () => 384);
+    const handle = await fs18.open(temporary, "wx", mode);
     try {
       await handle.writeFile(edit.after, "utf8");
       await handle.sync();
@@ -3355,10 +3910,10 @@ async function applyEdit(root, edit) {
       await handle.close();
     }
     if (await readText(root, edit.path) !== edit.before) throw new Error("Integration input changed during update: " + edit.path);
-    await fs16.rename(temporary, file);
+    await fs18.rename(temporary, file);
     return true;
   } finally {
-    await fs16.rm(temporary, { force: true });
+    await fs18.rm(temporary, { force: true });
   }
 }
 var init_files2 = __esm({
@@ -3379,7 +3934,7 @@ __export(ownership_exports, {
   ownershipEdit: () => ownershipEdit,
   ownershipSchema: () => ownershipSchema
 });
-import { z as z12 } from "zod";
+import { z as z14 } from "zod";
 import { parse } from "smol-toml";
 function blockSpan(text2, start, end) {
   const starts = text2.split(start).length - 1, ends = text2.split(end).length - 1;
@@ -3430,30 +3985,30 @@ var init_ownership = __esm({
       ["<!-- mason:agents:start -->", "<!-- mason:agents:end -->"],
       ["# mason:mcp:start", "# mason:mcp:end"]
     ];
-    fileSchema = z12.object({
-      created: z12.boolean(),
-      initialHash: z12.string(),
-      blocks: z12.record(z12.string()),
-      mcpHash: z12.string().optional(),
-      hookCommands: z12.array(z12.string()).optional(),
-      hooks: z12.record(z12.array(z12.string())).optional()
+    fileSchema = z14.object({
+      created: z14.boolean(),
+      initialHash: z14.string(),
+      blocks: z14.record(z14.string()),
+      mcpHash: z14.string().optional(),
+      hookCommands: z14.array(z14.string()).optional(),
+      hooks: z14.record(z14.array(z14.string())).optional()
     });
-    ownershipSchema = z12.object({ version: z12.literal(1), files: z12.record(fileSchema) });
+    ownershipSchema = z14.object({ version: z14.literal(1), files: z14.record(fileSchema) });
   }
 });
 
 // src/mcp/init.ts
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 var markerSchema, CLAUDE_MD_SECTION, ASSISTANT_SETUP, QUICKSTART_PLAYBOOK, MAP_PLAYBOOK;
 var init_init = __esm({
   "src/mcp/init.ts"() {
     "use strict";
     init_storage();
     init_files2();
-    markerSchema = z13.object({
-      version: z13.literal(1),
-      initializedAt: z13.string(),
-      features: z13.object({ confluence: z13.boolean().optional() }).passthrough().optional()
+    markerSchema = z15.object({
+      version: z15.literal(1),
+      initializedAt: z15.string(),
+      features: z15.object({ confluence: z15.boolean().optional() }).passthrough().optional()
     }).passthrough();
     CLAUDE_MD_SECTION = `<!-- mason:start -->
 ## Mason project knowledge
@@ -3463,12 +4018,14 @@ Mason provides recorded decisions and file impact over MCP. A concept map is opt
 - Task, bug, change request, or investigation of why the project works this way \u2192 \`get_context\` with the task text and known files: matching decisions, related tests, impact, and any available map entries.
 - Before editing a file \u2192 \`get_impact\` to check references, tests, and historical change partners.
 - Investigation or correction reveals a reusable project lesson \u2192 \`save_decision\` before finishing. Capture only the lasting constraint and reason, with anchors and known sources, owner, and recorder. This creates a proposal; never infer approval. Preserve uncertain causes and unknown attribution. Route project lessons here; keep personal preferences in agent memory. Skip code summaries, current checkout status, temporary task permissions, session trivia, and secrets. No qualifying lesson means no record.
+- Before saving, compare the lesson with matching \`get_context\` records and any pending proposal. If new evidence changes the same lesson's assumptions, scope, or recommended action, revise it with \`save_decision(id: existingId)\`, including when it is accepted. Preserve supported rationale and sources, replace obsolete instructions, and add the new evidence. Create a separate record for a genuinely distinct lesson; skip unchanged restatements. Revision preserves history and leaves the accepted version operative until authorized review.
 - Consult trust metadata before relying on entries: unknown or changed freshness requires inspection, and failed verification means the description must be corrected. Check approval too: proposals are suggestions, legacy records are unreviewed, and accepted decisions are recorded constraints subject to freshness checks. An accepted revision remains operative while a pending proposal is reviewed; keep both versions and their freshness distinct.
 - Asked to review or re-verify a decision \u2192 \`review_decision\` first to inspect content, sources, history, and code changes. Record acceptance, reaffirmation, or retirement only when authorized by the user or a cited team review, with the actual reviewer and reason. Never infer approval from unchanged code. Review and commit the local record through the normal project workflow.
 - For an architectural overview, use \`get_snapshot\` if a map is available. If \`map.status\` is missing or invalid, use available decisions and source evidence; do not start building a map unless requested.
 - \`mason_init\` returns documentation audit and committed-diff review results, plus a short setup guide. Pass \`evidence\` with local CI manifest paths to include test and analysis results; the CLI equivalent is \`mason-review --evidence <manifest>\`. State skipped, unavailable, stale, or unknown checks explicitly. Related accepted decisions identify review context, not proven violations.
 
 - When documentation repair is authorized, use \`mason_repair(action: "prepare")\` before edits, keep its baselinePath, and use \`mason_repair(action: "verify", baselinePath)\` after edits and any final doc commit. Report every original finding's outcome and any new findings. Suppressed advisories remain unresolved; editing a doc does not approve it.
+- When advisory assessment is authorized, use \`review_advisory(action: "prepare", baselinePath, findingId)\` to inspect original evidence and history. Record \`addressed\`, \`inapplicable\`, or \`deferred\` with the actual reviewer, reason in note, and returned reviewToken only after relevant edits are committed. Commit the assessment and verify the same baseline again. Relevant evidence changes reopen it; deferral stays outstanding. Decision findings use \`review_decision\`; advisory closure never approves a decision.
 
 - When Mason automation is installed, use \`mason_automation(action: "status")\` to inspect configured hooks and observed events, and \`mason_automation(action: "check")\` to resume its retained repair evidence. CLI fallback: \`mason-auto status\` / \`mason-auto check\`. Preserve existing baselines across sessions. Automatic checks do not authorize unrelated repairs or approve advisories.
 
@@ -3484,7 +4041,7 @@ ${CLAUDE_MD_SECTION}`;
 
 1. Explain the actionable findings with their source evidence. Separate audit issues, advisories, and skipped checks. The review covers committed changes from the merge base to HEAD; workingTree paths are not included in that review. An unavailable or empty check is not proof that the project is correct. Use the CLI for full output if a summary is truncated.
 2. Address findings within the user's requested scope. Setup alone authorizes Mason host configuration, hooks, instructions, and ignore rules; rewriting existing project claims requires repair scope. If repair is authorized, call \`mason_repair(dir, action: "prepare")\` before editing; it saves the full original findings even when this summary is truncated. Inspect relevant source, make grounded edits, then call \`mason_repair(dir, action: "verify", baselinePath)\` with that same baseline, including after any final doc commit. Report resolved, unresolved, review-required, unverified, and new findings. Keep suppressed advisories visible even when setup has already dirtied a doc. Do not invent a decision just to populate the store.
-3. When the task reveals a real lesson or constraint, call \`save_decision\` with title, body, category, anchors, and known owner/source/actor information. Missing attribution can be added later. The tool writes a local proposal; editing it preserves revision history and requires a new acceptance, while any earlier accepted revision remains operative. An unchanged save never refreshes its evidence. When decision review is requested, \`review_decision\` prepares the record and code evidence before any authorized verdict. Review and commit records through the normal workflow. Retrieve it on the next relevant task with \`get_context(dir, task, files)\`.
+3. When the task reveals a real lesson or constraint, compare matching \`get_context\` records first. If its assumptions, scope, or recommended action changed, revise that record using \`save_decision(id: existingId)\`; create a separate record for a genuinely distinct lesson and skip unchanged restatements. Include title, body, category, anchors, and known owner/source/actor information. Preserve supported rationale and sources, replace obsolete instructions, and add new evidence. Missing attribution can be added later. The tool writes a local proposal; editing it preserves revision history and requires a new acceptance, while any earlier accepted revision remains operative. An unchanged save never refreshes its evidence. When decision review is requested, \`review_decision\` prepares the record and code evidence before any authorized verdict. Review and commit records through the normal workflow. Retrieve it on the next relevant task with \`get_context(dir, task, files)\`.
 
 ${ASSISTANT_SETUP}
 
@@ -3525,29 +4082,6 @@ If a build is interrupted, its partials remain in \`.mason/partial-snapshots/\`.
   }
 });
 
-// src/utils/git.ts
-var git_exports = {};
-__export(git_exports, {
-  isGitRepo: () => isGitRepo
-});
-import { execFile as execFile10 } from "child_process";
-import { promisify as promisify10 } from "util";
-async function isGitRepo(dir) {
-  try {
-    await exec8("git", ["rev-parse", "--git-dir"], { cwd: dir });
-    return true;
-  } catch {
-    return false;
-  }
-}
-var exec8;
-var init_git2 = __esm({
-  "src/utils/git.ts"() {
-    "use strict";
-    exec8 = promisify10(execFile10);
-  }
-});
-
 // src/setup/config.ts
 var config_exports = {};
 __export(config_exports, {
@@ -3560,7 +4094,7 @@ __export(config_exports, {
 });
 import { isDeepStrictEqual } from "util";
 import { parse as parse2, stringify } from "smol-toml";
-import { z as z14 } from "zod";
+import { z as z16 } from "zod";
 async function instructionEdits(root, host) {
   const found = await Promise.all(DOC_CANDIDATES.map(async (file) => ({ path: file, text: await readText(root, file) })));
   const existing = found.find((f) => f.text !== null);
@@ -3592,7 +4126,7 @@ async function instructionEdits(root, host) {
 function managedMcp(previous, host) {
   const options = previous === void 0 ? {} : object.parse(previous);
   for (const key of ["command", "args", "url", "type", "headers", "http_headers", "env_http_headers", "bearer_token_env_var"]) delete options[key];
-  return { ...options, ...mcpCommand(host) };
+  return { ...options, ...host === "claude" ? { type: "stdio" } : {}, ...mcpCommand(host) };
 }
 async function mcpEdit(root, host) {
   const file = mcpPath(host), before = await readText(root, file);
@@ -3629,19 +4163,13 @@ async function hookEdits(root, host) {
 }
 async function ancillaryEdits(root) {
   const ignore = await readText(root, ".gitignore");
-  const { git: git3 } = await Promise.resolve().then(() => (init_evidence(), evidence_exports));
-  const { isGitRepo: isGitRepo2 } = await Promise.resolve().then(() => (init_git2(), git_exports));
-  let parentIgnored = false;
-  try {
-    if (await isGitRepo2(root)) parentIgnored = !!(await git3(root, "check-ignore", "--no-index", ".mason")).trim();
-  } catch (error) {
-    if (error.code !== 1) throw error;
-  }
-  const retainParentRule = parentIgnored || !!ignore?.replace(/\r\n/g, "\n").includes("# mason:ignore:start\n!/.mason/\n/.mason/*");
   const rules = [
-    ...retainParentRule ? ["!/.mason/", "/.mason/*"] : [],
+    "!/.mason/",
+    "/.mason/*",
     "!/.mason/decisions/",
     "!/.mason/decisions/**",
+    "!/.mason/reviews/",
+    "!/.mason/reviews/**",
     "!/.mason/config.json",
     "!/.mason/snapshot.json",
     "/.mason/local/",
@@ -3655,13 +4183,14 @@ async function inspectHostConfig(root, host, plannedMcp) {
   const servers = host === "codex" ? config.mcp_servers : config.mcpServers;
   const hooks = automationConfigSchema.parse(JSON.parse(await readText(root, configPath(host)) ?? "{}"));
   const expected = hookConfig(host, hookCommand(host));
+  const compatible = compatibleManagedHookCommands(host);
   const mcp = servers?.mason === void 0 ? null : object.parse(servers.mason);
   return {
     mcp,
     mcpDisabled: mcp?.enabled === false,
     hooks: Object.fromEntries(Object.keys(expected.hooks).map((event) => [
       event,
-      (hooks.hooks?.[event] ?? []).flatMap((group) => group.hooks.filter((handler) => handler.command === expected.hooks.SessionStart[0].hooks[0].command).map((handler) => ({ ...group, hooks: [handler] })) ?? [])
+      (hooks.hooks?.[event] ?? []).flatMap((group) => group.hooks.filter((handler) => compatible.includes(handler.command ?? "")).map((handler) => ({ ...group, hooks: [handler] })) ?? [])
     ])),
     disabled: hooks.disableAllHooks === true || config.features?.hooks === false || config.features?.codex_hooks === false
   };
@@ -3676,7 +4205,7 @@ var init_config = __esm({
     init_install();
     init_files2();
     init_launcher();
-    object = z14.record(z14.unknown());
+    object = z16.record(z16.unknown());
     mcpPath = (host) => host === "codex" ? ".codex/config.toml" : ".mcp.json";
     TOML_START = "# mason:mcp:start";
     TOML_END = "# mason:mcp:end";
@@ -3694,11 +4223,11 @@ __export(install_exports, {
   installAutomation: () => installAutomation,
   installedAutomation: () => installedAutomation,
   planAutomationInstall: () => planAutomationInstall,
-  recordSchema: () => recordSchema
+  recordSchema: () => recordSchema2
 });
-import { z as z15 } from "zod";
+import { z as z17 } from "zod";
 async function installationRecord(root) {
-  return recordSchema.parse(await readStoreJson(root, AUTOMATION_PATH) ?? { version: 1, hosts: {} });
+  return recordSchema2.parse(await readStoreJson(root, AUTOMATION_PATH) ?? { version: 1, hosts: {} });
 }
 async function installAutomation(dir, host, command) {
   const ws = await workspace(dir);
@@ -3767,7 +4296,7 @@ async function installedAutomation(dir) {
   }
   return result;
 }
-var groupSchema, automationConfigSchema, recordSchema, AUTOMATION_PATH, configPath;
+var groupSchema, automationConfigSchema, recordSchema2, AUTOMATION_PATH, configPath;
 var init_install = __esm({
   "src/automation/install.ts"() {
     "use strict";
@@ -3777,9 +4306,9 @@ var init_install = __esm({
     init_store();
     init_files2();
     init_ownership();
-    groupSchema = z15.object({ hooks: z15.array(z15.object({ type: z15.string(), command: z15.string().optional() }).passthrough()) }).passthrough();
-    automationConfigSchema = z15.object({ hooks: z15.record(z15.array(groupSchema)).optional() }).passthrough();
-    recordSchema = z15.object({ version: z15.literal(1), hosts: z15.record(z15.object({ command: z15.string() })) });
+    groupSchema = z17.object({ hooks: z17.array(z17.object({ type: z17.string(), command: z17.string().optional() }).passthrough()) }).passthrough();
+    automationConfigSchema = z17.object({ hooks: z17.record(z17.array(groupSchema)).optional() }).passthrough();
+    recordSchema2 = z17.object({ version: z17.literal(1), hosts: z17.record(z17.object({ command: z17.string() })) });
     AUTOMATION_PATH = ".mason/local/automation.json";
     configPath = (host) => host === "claude" ? ".claude/settings.json" : ".codex/hooks.json";
   }
@@ -3793,8 +4322,8 @@ __export(teardown_exports, {
 });
 import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
 import { parse as parse3, stringify as stringify2 } from "smol-toml";
-import fg5 from "fast-glob";
-import { z as z16 } from "zod";
+import fg6 from "fast-glob";
+import { z as z18 } from "zod";
 async function planTeardown(root, selected) {
   const edits = [], diagnostics = [];
   const inputs = /* @__PURE__ */ new Map();
@@ -3814,7 +4343,7 @@ async function planTeardown(root, selected) {
   const setupBefore = await read(SETUP_PATH);
   const setup = setupBefore === null ? null : setupSchema.parse(JSON.parse(setupBefore));
   const automationBefore = await read(AUTOMATION_PATH);
-  const automation = automationBefore === null ? null : recordSchema.parse(JSON.parse(automationBefore));
+  const automation = automationBefore === null ? null : recordSchema2.parse(JSON.parse(automationBefore));
   const commands = (host) => new Set([
     automation?.hosts[host]?.command,
     ...ownership.files[configPath(host)]?.hookCommands ?? [],
@@ -3851,8 +4380,12 @@ async function planTeardown(root, selected) {
         if (host === "codex" && BLOCKS[2].some((marker) => before.includes(marker))) throw new Error("The marked Mason MCP entry was removed or renamed; inspect the retained block manually.");
         return;
       }
-      const expected = ownership.files[mcpFile]?.mcpHash ?? hash(mcpCommand(host));
-      if (hash(servers.mason) !== expected) throw new Error("The Mason MCP entry was edited or its ownership is uncertain; retained for manual cleanup.");
+      const ownedHash = ownership.files[mcpFile]?.mcpHash;
+      const expected = ownedHash ? [ownedHash] : [
+        hash(mcpCommand(host)),
+        ...host === "claude" ? [hash({ type: "stdio", ...mcpCommand(host) })] : []
+      ];
+      if (!expected.includes(hash(servers.mason))) throw new Error("The Mason MCP entry was edited or its ownership is uncertain; retained for manual cleanup.");
       delete servers.mason;
       const desired = { ...config, [key]: servers };
       if (!Object.keys(servers).length) delete desired[key];
@@ -3928,7 +4461,7 @@ async function planTeardown(root, selected) {
   if (diagnostics.length) edits.splice(instructionEditStart);
   if (!diagnostics.length) {
     const cleanup = [];
-    const receiptFiles = await fg5(
+    const receiptFiles = await fg6(
       selected.map((host) => ".mason/reports/automation/*/setup-" + host + ".json"),
       { cwd: root, dot: true, onlyFiles: false, followSymbolicLinks: false }
     );
@@ -3941,7 +4474,7 @@ async function planTeardown(root, selected) {
     if (!remainingHost) await attempt(".mason/local/project.json", async () => {
       const before = await read(".mason/local/project.json");
       if (before === null) return;
-      z16.object({ version: z16.literal(1), initializedAt: z16.string() }).strict().parse(JSON.parse(before));
+      z18.object({ version: z18.literal(1), initializedAt: z18.string() }).strict().parse(JSON.parse(before));
       cleanup.push({ path: ".mason/local/project.json", before, after: null });
     });
     if (!diagnostics.length) {
@@ -4013,7 +4546,7 @@ var init_teardown = __esm({
     init_model();
     init_ownership();
     hosts = ["codex", "claude"];
-    object2 = z16.record(z16.unknown());
+    object2 = z18.record(z18.unknown());
     json = (value) => JSON.stringify(value, null, 2) + "\n";
   }
 });
@@ -4023,9 +4556,9 @@ import { execFile as execFile11 } from "child_process";
 import { promisify as promisify11 } from "util";
 async function buildMatrix(resolvedRoot) {
   try {
-    const { stdout: shallow } = await exec9("git", ["rev-parse", "--is-shallow-repository"], { cwd: resolvedRoot });
+    const { stdout: shallow } = await exec8("git", ["rev-parse", "--is-shallow-repository"], { cwd: resolvedRoot });
     if (shallow.trim() === "true") return null;
-    const { stdout } = await exec9(
+    const { stdout } = await exec8(
       "git",
       ["log", `-n${HISTORY_COMMITS}`, "--format=%x01", "--name-only", "-M"],
       { cwd: resolvedRoot, maxBuffer: 100 * 1024 * 1024 }
@@ -4081,11 +4614,11 @@ async function findMissingPartners(resolvedRoot, changedFiles, existsOnDisk, all
   findings.sort((a, b) => b.rate - a.rate || b.sharedCommits - a.sharedCommits);
   return findings;
 }
-var exec9, HISTORY_COMMITS, MIN_FILE_COMMITS, MIN_SHARED_COMMITS, MIN_COCHANGE_RATE, MAX_COMMIT_FILES;
+var exec8, HISTORY_COMMITS, MIN_FILE_COMMITS, MIN_SHARED_COMMITS, MIN_COCHANGE_RATE, MAX_COMMIT_FILES;
 var init_cochange = __esm({
   "src/review/cochange.ts"() {
     "use strict";
-    exec9 = promisify11(execFile11);
+    exec8 = promisify11(execFile11);
     HISTORY_COMMITS = 1500;
     MIN_FILE_COMMITS = 5;
     MIN_SHARED_COMMITS = 4;
@@ -4140,7 +4673,7 @@ var init_types2 = __esm({
 });
 
 // src/review/evidence/vitest.ts
-import { z as z17 } from "zod";
+import { z as z19 } from "zod";
 function parseVitest(raw, sourceRoot) {
   const report = schema.parse(raw);
   const findings = [], diagnostics = [];
@@ -4183,30 +4716,30 @@ function parseVitest(raw, sourceRoot) {
     diagnostics
   };
 }
-var count2, schema;
+var count3, schema;
 var init_vitest = __esm({
   "src/review/evidence/vitest.ts"() {
     "use strict";
     init_paths2();
     init_types2();
-    count2 = z17.number().int().nonnegative();
-    schema = z17.object({
-      success: z17.boolean(),
-      numTotalTests: count2,
-      numPassedTests: count2,
-      numFailedTests: count2,
-      numPendingTests: count2,
-      numTodoTests: count2,
-      numFailedTestSuites: count2,
-      testResults: z17.array(z17.object({
-        name: z17.string().min(1),
-        status: z17.enum(["passed", "failed"]),
-        message: z17.string().optional(),
-        assertionResults: z17.array(z17.object({
-          fullName: z17.string(),
-          status: z17.enum(["passed", "failed", "pending", "skipped", "todo", "disabled"]),
-          failureMessages: z17.array(z17.string()).nullable().optional(),
-          location: z17.object({ line: count2, column: count2 }).nullable().optional()
+    count3 = z19.number().int().nonnegative();
+    schema = z19.object({
+      success: z19.boolean(),
+      numTotalTests: count3,
+      numPassedTests: count3,
+      numFailedTests: count3,
+      numPendingTests: count3,
+      numTodoTests: count3,
+      numFailedTestSuites: count3,
+      testResults: z19.array(z19.object({
+        name: z19.string().min(1),
+        status: z19.enum(["passed", "failed"]),
+        message: z19.string().optional(),
+        assertionResults: z19.array(z19.object({
+          fullName: z19.string(),
+          status: z19.enum(["passed", "failed", "pending", "skipped", "todo", "disabled"]),
+          failureMessages: z19.array(z19.string()).nullable().optional(),
+          location: z19.object({ line: count3, column: count3 }).nullable().optional()
         }))
       }))
     });
@@ -4214,7 +4747,7 @@ var init_vitest = __esm({
 });
 
 // src/review/evidence/sarif.ts
-import { z as z18 } from "zod";
+import { z as z20 } from "zod";
 function parseSarif(raw, sourceRoot) {
   const report = schema2.parse(raw), findings = [], diagnostics = [];
   let active = 0, suppressed = 0, absent = 0, unresolved = 0;
@@ -4305,40 +4838,98 @@ var init_sarif = __esm({
     "use strict";
     init_paths2();
     init_types2();
-    index = z18.number().int().nonnegative();
-    artifact = z18.object({ uri: z18.string().optional(), uriBaseId: z18.string().optional(), index: index.optional() });
-    message = z18.object({ text: z18.string().optional(), markdown: z18.string().optional(), id: z18.string().optional(), arguments: z18.array(z18.string()).optional() });
-    level = z18.enum(["error", "warning", "note", "none"]);
-    location = z18.object({ physicalLocation: z18.object({ artifactLocation: artifact.optional(), region: z18.object({ startLine: index.optional(), startColumn: index.optional() }).optional() }).optional() });
-    schema2 = z18.object({
-      version: z18.literal("2.1.0"),
-      runs: z18.array(z18.object({
-        tool: z18.object({ driver: z18.object({ name: z18.string().min(1), rules: z18.array(z18.object({ id: z18.string(), defaultConfiguration: z18.object({ level: level.optional() }).optional(), messageStrings: z18.record(message).optional() })).optional(), globalMessageStrings: z18.record(message).optional() }) }),
-        invocations: z18.array(z18.object({ executionSuccessful: z18.boolean(), commandLine: z18.string().optional(), toolExecutionNotifications: z18.array(z18.object({ level: level.optional(), message })).optional() })).optional(),
-        versionControlProvenance: z18.array(z18.object({ revisionId: z18.string().optional() })).optional(),
-        originalUriBaseIds: z18.record(artifact).optional(),
-        artifacts: z18.array(z18.object({ location: artifact.optional() })).optional(),
-        results: z18.array(z18.object({
-          ruleId: z18.string().optional(),
+    index = z20.number().int().nonnegative();
+    artifact = z20.object({ uri: z20.string().optional(), uriBaseId: z20.string().optional(), index: index.optional() });
+    message = z20.object({ text: z20.string().optional(), markdown: z20.string().optional(), id: z20.string().optional(), arguments: z20.array(z20.string()).optional() });
+    level = z20.enum(["error", "warning", "note", "none"]);
+    location = z20.object({ physicalLocation: z20.object({ artifactLocation: artifact.optional(), region: z20.object({ startLine: index.optional(), startColumn: index.optional() }).optional() }).optional() });
+    schema2 = z20.object({
+      version: z20.literal("2.1.0"),
+      runs: z20.array(z20.object({
+        tool: z20.object({ driver: z20.object({ name: z20.string().min(1), rules: z20.array(z20.object({ id: z20.string(), defaultConfiguration: z20.object({ level: level.optional() }).optional(), messageStrings: z20.record(message).optional() })).optional(), globalMessageStrings: z20.record(message).optional() }) }),
+        invocations: z20.array(z20.object({ executionSuccessful: z20.boolean(), commandLine: z20.string().optional(), toolExecutionNotifications: z20.array(z20.object({ level: level.optional(), message })).optional() })).optional(),
+        versionControlProvenance: z20.array(z20.object({ revisionId: z20.string().optional() })).optional(),
+        originalUriBaseIds: z20.record(artifact).optional(),
+        artifacts: z20.array(z20.object({ location: artifact.optional() })).optional(),
+        results: z20.array(z20.object({
+          ruleId: z20.string().optional(),
           ruleIndex: index.optional(),
           message,
           level: level.optional(),
-          kind: z18.enum(["fail", "pass", "open", "informational", "notApplicable", "review"]).optional(),
-          baselineState: z18.enum(["new", "unchanged", "updated", "absent"]).optional(),
-          suppressions: z18.array(z18.object({ kind: z18.enum(["inSource", "external"]), status: z18.enum(["accepted", "underReview", "rejected"]).optional() })).nullable().optional(),
-          locations: z18.array(location).optional(),
-          relatedLocations: z18.array(location).optional()
+          kind: z20.enum(["fail", "pass", "open", "informational", "notApplicable", "review"]).optional(),
+          baselineState: z20.enum(["new", "unchanged", "updated", "absent"]).optional(),
+          suppressions: z20.array(z20.object({ kind: z20.enum(["inSource", "external"]), status: z20.enum(["accepted", "underReview", "rejected"]).optional() })).nullable().optional(),
+          locations: z20.array(location).optional(),
+          relatedLocations: z20.array(location).optional()
         })).optional()
       }))
     });
   }
 });
 
+// src/review/evidence/check.ts
+import { z as z21 } from "zod";
+function parseCheck(raw, sourceRoot) {
+  const report = schema3.parse(raw);
+  const diagnostics = [], findings = [];
+  const counts = { total: report.results.length, passed: 0, failed: 0, skipped: 0 };
+  for (const [index2, result] of report.results.entries()) {
+    counts[result.status]++;
+    const locations = result.locations.flatMap((location2) => {
+      const file = evidencePath(location2.file, sourceRoot);
+      if (!file) {
+        diagnostics.push(`Check location is outside the declared checkout or invalid: ${location2.file}`);
+        return [];
+      }
+      return [{ ...location2, file }];
+    });
+    if (result.status === "failed") findings.push({
+      id: String(index2),
+      ...messagePreview([result.name, result.message].filter(Boolean).join("\n")),
+      severity: "error",
+      state: "active",
+      locations
+    });
+  }
+  if (!counts.total) diagnostics.push("No check results were recorded; an empty report is not passing evidence.");
+  if (counts.skipped) diagnostics.push(`${counts.skipped} checks were skipped; verification is incomplete.`);
+  return {
+    outcome: counts.failed ? "failed" : !counts.total ? "unavailable" : !counts.passed ? "skipped" : "passed",
+    counts,
+    findings,
+    incomplete: diagnostics.length > 0,
+    diagnostics,
+    ...report.commit ? { reportedCommits: [report.commit] } : {}
+  };
+}
+var schema3;
+var init_check = __esm({
+  "src/review/evidence/check.ts"() {
+    "use strict";
+    init_paths2();
+    init_types2();
+    schema3 = z21.object({
+      version: z21.literal(1),
+      commit: z21.string().regex(/^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/).optional(),
+      results: z21.array(z21.object({
+        name: z21.string().min(1).max(1e3),
+        status: z21.enum(["passed", "failed", "skipped"]),
+        message: z21.string().max(1e5).optional(),
+        locations: z21.array(z21.object({
+          file: z21.string().min(1).max(4e3),
+          line: z21.number().int().positive().optional(),
+          column: z21.number().int().positive().optional()
+        })).max(100).default([])
+      })).max(1e5)
+    });
+  }
+});
+
 // src/review/evidence.ts
-import path19 from "path";
-import { z as z19 } from "zod";
+import path23 from "path";
+import { z as z22 } from "zod";
 function relativeArtifact(root, file) {
-  const relative = path19.isAbsolute(file) ? path19.relative(root, file) : file;
+  const relative = path23.isAbsolute(file) ? path23.relative(root, file) : file;
   const normalized = normalizeRepoPath(relative);
   if (!normalized) throw new Error(`Evidence artifact must be inside the repository: ${file}`);
   return normalized;
@@ -4377,7 +4968,7 @@ async function collectReviewEvidence(root, manifests, changedFiles, decisions, d
     let manifest, raw;
     try {
       manifest = relativeArtifact(root, supplied);
-      raw = z19.object({ version: z19.literal(1), checks: z19.array(z19.unknown()) }).parse(await readStoreJson(root, manifest));
+      raw = z22.object({ version: z22.literal(1), checks: z22.array(z22.unknown()) }).parse(await readStoreJson(root, manifest));
     } catch (error) {
       output.diagnostics.push(`${supplied}: ${String(error)}`);
       continue;
@@ -4416,7 +5007,8 @@ async function collectReviewEvidence(root, manifests, changedFiles, decisions, d
         counts: {},
         incomplete: false,
         diagnostics: [],
-        truncated: false
+        truncated: false,
+        ...check.environment ? { environment: check.environment } : {}
       };
       output.checks.push(result);
       if (check.workingTreeClean !== true) result.diagnostics.push("The check's working tree was dirty or not recorded; its results cannot be attributed to the claimed commit alone.");
@@ -4429,13 +5021,13 @@ async function collectReviewEvidence(root, manifests, changedFiles, decisions, d
       }
       try {
         if (!check.report) throw new Error("Completed check has no report artifact.");
-        if (check.kind === "tests" !== (check.report.format === "vitest-json")) throw new Error("Test checks require vitest-json; analysis checks require sarif.");
+        if (check.report.format !== "mason-check-json" && check.kind === "tests" !== (check.report.format === "vitest-json")) throw new Error("Test checks require vitest-json or mason-check-json; analysis checks require sarif or mason-check-json.");
         const file = relativeArtifact(root, check.report.path);
         const report = await readStoreJson(root, file);
         if (report === null) throw new Error(`Report artifact is missing: ${file}`);
         const sourceRoot = check.sourceRoot ?? root;
-        if (!path19.posix.isAbsolute(sourceRoot) && !/^[A-Za-z]:[\\/]/.test(sourceRoot)) throw new Error("sourceRoot must identify the absolute checkout root on the check runner.");
-        const parsed = check.report.format === "vitest-json" ? parseVitest(report, sourceRoot) : parseSarif(report, sourceRoot);
+        if (!path23.posix.isAbsolute(sourceRoot) && !/^[A-Za-z]:[\\/]/.test(sourceRoot)) throw new Error("sourceRoot must identify the absolute checkout root on the check runner.");
+        const parsed = check.report.format === "vitest-json" ? parseVitest(report, sourceRoot) : check.report.format === "mason-check-json" ? parseCheck(report, sourceRoot) : parseSarif(report, sourceRoot);
         result.outcome = parsed.outcome;
         result.counts = parsed.counts;
         result.incomplete = parsed.incomplete;
@@ -4455,7 +5047,7 @@ async function collectReviewEvidence(root, manifests, changedFiles, decisions, d
           result.outcome = "failed";
           result.diagnostics.push(`Check command exited ${check.exitCode} despite a report with no active failures.`);
         }
-        if (check.report.format === "vitest-json" && pairs === void 0) {
+        if (check.kind === "tests" && pairs === void 0) {
           try {
             pairs = (await buildTestMap(root)).paired;
           } catch (error) {
@@ -4529,32 +5121,39 @@ var init_evidence2 = __esm({
     init_provenance();
     init_vitest();
     init_sarif();
+    init_check();
     init_types2();
-    checkSchema2 = z19.object({
-      id: z19.string().min(1).max(100),
-      kind: z19.enum(["tests", "static-analysis", "security", "complexity", "duplication"]),
-      tool: z19.string().min(1).max(200),
-      command: z19.string().min(1).max(2e3),
-      commit: z19.string().regex(/^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/).nullable().optional(),
-      workingTreeClean: z19.boolean().optional(),
-      source: z19.string().max(2e3).optional(),
-      sourceRoot: z19.string().min(1).max(4e3).optional(),
-      status: z19.enum(["completed", "skipped", "unavailable"]).default("completed"),
-      reason: z19.string().min(1).max(2e3).optional(),
-      exitCode: z19.number().int().nullable().optional(),
-      report: z19.object({ format: z19.enum(["vitest-json", "sarif"]), path: z19.string().min(1).max(4e3) }).optional()
+    checkSchema2 = z22.object({
+      id: z22.string().min(1).max(100),
+      kind: z22.enum(["tests", "static-analysis", "security", "complexity", "duplication", "documentation"]),
+      tool: z22.string().min(1).max(200),
+      command: z22.string().min(1).max(2e3),
+      commit: z22.string().regex(/^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/).nullable().optional(),
+      workingTreeClean: z22.boolean().optional(),
+      source: z22.string().max(2e3).optional(),
+      sourceRoot: z22.string().min(1).max(4e3).optional(),
+      status: z22.enum(["completed", "skipped", "unavailable"]).default("completed"),
+      reason: z22.string().min(1).max(2e3).optional(),
+      exitCode: z22.number().int().nullable().optional(),
+      environment: z22.object({
+        toolVersion: z22.string().min(1).max(200),
+        runtime: z22.string().min(1).max(200).optional(),
+        platform: z22.string().min(1).max(200).optional(),
+        configuration: z22.array(z22.string().min(1).max(4e3)).max(100).optional()
+      }).optional(),
+      report: z22.object({ format: z22.enum(["vitest-json", "sarif", "mason-check-json"]), path: z22.string().min(1).max(4e3) }).optional()
     });
   }
 });
 
 // src/review/review.ts
-import fs17 from "fs/promises";
-import path20 from "path";
+import fs19 from "fs/promises";
+import path24 from "path";
 import { execFile as execFile12 } from "child_process";
 import { promisify as promisify12 } from "util";
 async function resolveMergeBase(resolvedRoot, base, head) {
   try {
-    const { stdout } = await exec10("git", ["merge-base", base, head], {
+    const { stdout } = await exec9("git", ["merge-base", base, head], {
       cwd: resolvedRoot
     });
     return stdout.trim() || null;
@@ -4565,7 +5164,7 @@ async function resolveMergeBase(resolvedRoot, base, head) {
 async function defaultBase(resolvedRoot) {
   for (const ref of ["origin/HEAD", "origin/main", "origin/master", "main"]) {
     try {
-      await exec10("git", ["rev-parse", "--verify", "--quiet", ref], {
+      await exec9("git", ["rev-parse", "--verify", "--quiet", ref], {
         cwd: resolvedRoot
       });
       return ref;
@@ -4578,7 +5177,7 @@ function anchorsTouched(record, changedFiles) {
   return matchingPaths(record.files, changedFiles);
 }
 async function computeReview(rootDir, base, options = {}) {
-  const resolvedRoot = path20.resolve(rootDir);
+  const resolvedRoot = path24.resolve(rootDir);
   const head = await getCurrentGitHash(resolvedRoot);
   if (head === "unknown") return null;
   const mergeBase = await resolveMergeBase(resolvedRoot, base, head);
@@ -4628,7 +5227,7 @@ async function computeReview(rootDir, base, options = {}) {
     analyzed,
     async (relPath) => {
       try {
-        await fs17.access(path20.join(resolvedRoot, relPath));
+        await fs19.access(path24.join(resolvedRoot, relPath));
         return true;
       } catch {
         return false;
@@ -4661,7 +5260,7 @@ async function computeReview(rootDir, base, options = {}) {
   }
   return finalize();
 }
-var exec10, MAX_ANALYZED_FILES;
+var exec9, MAX_ANALYZED_FILES;
 var init_review = __esm({
   "src/review/review.ts"() {
     "use strict";
@@ -4673,7 +5272,7 @@ var init_review = __esm({
     init_cochange();
     init_evidence2();
     init_snapshot();
-    exec10 = promisify12(execFile12);
+    exec9 = promisify12(execFile12);
     MAX_ANALYZED_FILES = 50;
   }
 });
@@ -4682,7 +5281,7 @@ var init_review = __esm({
 async function auditSummary(root) {
   try {
     const report = await computeAudit(root);
-    if (!report) return { status: "no-context-files", reason: "No AGENTS.md, CLAUDE.md, or .claude/CLAUDE.md found to audit." };
+    if (!report) return { status: "no-context-files", reason: "No README.md or agent instruction files found to audit." };
     if (!report.gitAvailable) return { status: "unavailable", reason: "Audit needs readable Git history to verify documentation claims.", docs: report.docs };
     return {
       ...report,
@@ -4795,7 +5394,16 @@ async function setupStatus(dir) {
     const instructionsCurrent = instructions.every((edit) => edit.before === edit.after);
     const config = await inspectHostConfig(ws.root, host, void 0);
     const mcp = !config.mcpDisabled && hash(config.mcp) === entry.mcpFingerprint && isDeepStrictEqual3({ command: config.mcp?.command, args: config.mcp?.args }, mcpCommand(host));
-    const hooks = isDeepStrictEqual3(config.hooks, hookConfig(host, hookCommand(host)).hooks) && !config.disabled;
+    const expectedHooks = hookConfig(host, hookCommand(host)).hooks;
+    const currentHooks = isDeepStrictEqual3(config.hooks, expectedHooks);
+    const compatibleHooks = Object.fromEntries(Object.entries(config.hooks).map(([event, groups]) => [
+      event,
+      groups.map((group) => ({ ...group, hooks: group.hooks.map((handler) => ({
+        ...handler,
+        command: expectedHooks.SessionStart[0].hooks[0].command
+      })) }))
+    ]));
+    const hooks = isDeepStrictEqual3(compatibleHooks, expectedHooks) && !config.disabled;
     const local = await loadSetupReceipt(ws.root, ws.directory, host);
     const configured = local?.status === "configured" && local.root === ws.root && local.revision === entry.revision;
     const observation = await readObservation(ws.root, ws.directory, host, entry.revision, installed.version ?? "unavailable");
@@ -4814,11 +5422,12 @@ async function setupStatus(dir) {
       runtime: installed.available ? "global (" + installed.version + ")" : "unavailable-on-path",
       mcp: mcp ? "configured" : "changed",
       instructions: instructionsCurrent ? "current" : "changed",
-      hookConfiguration: hooks ? "configured" : "disabled-or-changed",
+      hookConfiguration: hooks ? currentHooks ? "configured" : "compatible" : "disabled-or-changed",
       observedEvents,
       contextCalls: observation?.contextCalls ?? 0,
       verificationStatus: automation.status === "current" ? automation.verificationStatus ?? "unavailable" : "unavailable",
-      pending
+      pending,
+      updates: hooks && !currentHooks ? ["A newer hook template is available. Run mason setup --host " + host + " to update it when convenient; review and commit the configuration changes."] : []
     };
   }
   const statuses = Object.values(hosts2).map((host) => host.status);
@@ -4843,6 +5452,7 @@ function summarizeActivation(status) {
       `  Task context requests: ${state.contextCalls}; verification: ${state.verificationStatus}.`,
       ...state.pending.map((message2) => "  Next: " + message2)
     );
+    lines.push(...state.updates.map((message2) => "  Optional: " + message2));
   }
   if ("decisionRecords" in status) lines.push(`Decision records: ${status.decisionRecords}.`);
   if (status.next) lines.push(status.next);
@@ -5048,7 +5658,7 @@ function isHookCommand(argv2) {
 async function runAutomationCli(argv2, stdin = "", io = {
   out: (s) => process.stdout.write(s + "\n"),
   err: (s) => process.stderr.write(s + "\n")
-}) {
+}, options = {}) {
   let action = "";
   try {
     const { values, positionals } = parseCli(argv2);
@@ -5068,7 +5678,9 @@ async function runAutomationCli(argv2, stdin = "", io = {
       return result.status === "complete" ? 0 : 2;
     }
     if (action === "hook") {
-      const output = await runAutomationHook(hostSchema.parse(values.host), stdin);
+      const host = hostSchema.parse(values.host);
+      if (options.managedHost && options.managedHost !== host) throw new Error("Managed hook --host does not match its launcher.");
+      const output = await runAutomationHook(host, stdin, { managed: !!options.managedHost });
       if (output) io.out(JSON.stringify(output));
       return 0;
     }