mason-context 0.10.0 → 0.11.0

package/dist/mason-audit.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/audit/cli.ts
-import path16 from "path";
+import path17 from "path";
 
 // src/audit/audit.ts
 import fs9 from "fs/promises";
@@ -35,6 +35,10 @@ function normalizeRepoPath(value) {
   const normalized = path.posix.normalize(slash).replace(/\/$/, "");
   return normalized === "." ? null : normalized;
 }
+function isWithinRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
 function anchorMatches(anchor, file) {
   const a = normalizeRepoPath(anchor);
   const f = normalizeRepoPath(file);
@@ -132,6 +136,26 @@ async function readStoreJson(root, relative) {
     throw new Error(`Invalid Mason store ${relative}: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+async function writeStoreJson(root, relative, value) {
+  const payload = JSON.stringify(value, null, 2) + "\n";
+  if (Buffer.byteLength(payload) > 10 * 1024 * 1024) {
+    throw new Error(`Mason store ${relative} exceeds 10 MiB`);
+  }
+  const file = await storePath(root, relative, true);
+  const temporary = path3.join(path3.dirname(file), `.${path3.basename(file)}.${randomUUID()}.tmp`);
+  try {
+    const handle = await fs2.open(temporary, "wx", 384);
+    try {
+      await handle.writeFile(payload, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fs2.rename(temporary, file);
+  } finally {
+    await fs2.rm(temporary, { force: true });
+  }
+}
 
 // src/snapshot/snapshot.ts
 import { z } from "zod";
@@ -794,8 +818,8 @@ async function checkNewModules(ctx) {
     const absTop = path9.join(ctx.root, topDir);
     const topMentioned = isMentioned(combinedDocs, topDir);
     if (!topMentioned) {
-      const count = await countSourceFiles(absTop);
-      if (count >= 1) await flag(topDir, count);
+      const count2 = await countSourceFiles(absTop);
+      if (count2 >= 1) await flag(topDir, count2);
       continue;
     }
     const subdirs = await listSubdirs(absTop);
@@ -803,9 +827,9 @@ async function checkNewModules(ctx) {
     if (mentioned.length < ENUMERATION_THRESHOLD) continue;
     for (const sub of subdirs) {
       if (isMentioned(combinedDocs, sub)) continue;
-      const count = await countSourceFiles(path9.join(absTop, sub));
-      if (count >= SECOND_LEVEL_MIN_SOURCE_FILES) {
-        await flag(`${topDir}/${sub}`, count);
+      const count2 = await countSourceFiles(path9.join(absTop, sub));
+      if (count2 >= SECOND_LEVEL_MIN_SOURCE_FILES) {
+        await flag(`${topDir}/${sub}`, count2);
       }
     }
   }
@@ -931,7 +955,15 @@ async function checkStaleCounts(ctx) {
   for (const doc of ctx.docs) {
     for (const claim of doc.claims.counts) {
       const source = await resolveCountSource(ctx.root, claim);
-      if (source === null || source.actual === claim.count) continue;
+      if (source === null) {
+        result.skipped.push({
+          check: "stale-count",
+          doc: doc.path,
+          reason: `${doc.path}: cannot resolve a workspace manifest for "${claim.excerpt}"`
+        });
+        continue;
+      }
+      if (source.actual === claim.count) continue;
       result.issues.push({
         type: "stale-count",
         message: `says "${claim.excerpt}" but ${source.countedFrom} resolves to ${source.actual}`,
@@ -1039,10 +1071,12 @@ var MANIFEST_PATHSPECS = [
 ];
 async function checkDepsChanged(ctx) {
   const result = emptyResult();
+  result.suppressedAdvisories = [];
   for (const doc of ctx.docs) {
     if (!doc.lastCommit) {
       result.skipped.push({
         check: "deps-changed",
+        doc: doc.path,
         reason: `${doc.path} has no commit history`
       });
       continue;
@@ -1050,9 +1084,9 @@ async function checkDepsChanged(ctx) {
     if (doc.dirty) {
       result.skipped.push({
         check: "deps-changed",
+        doc: doc.path,
         reason: `${doc.path} has uncommitted edits \u2013 suppressed while in flight`
       });
-      continue;
     }
     const range = await commitsTouchingSince(
       ctx.root,
@@ -1062,13 +1096,14 @@ async function checkDepsChanged(ctx) {
     if (range === null) {
       result.skipped.push({
         check: "deps-changed",
+        doc: doc.path,
         reason: `${doc.path}: commit range unreachable (shallow clone?)`
       });
       continue;
     }
     if (range.total === 0) continue;
     const latest = range.commits[0];
-    result.advisories.push({
+    (doc.dirty ? result.suppressedAdvisories : result.advisories).push({
       type: "deps-changed",
       message: `dependency manifests touched by ${range.total} commit${range.total === 1 ? "" : "s"} since ${doc.path} was last committed (latest: ${latest.hash.slice(0, 7)} "${latest.subject}")`,
       anchor: { doc: doc.path, line: null, excerpt: null },
@@ -1200,6 +1235,23 @@ function decisionContent(record) {
 function decisionApproval(record) {
   return record.version === 1 ? "unreviewed" : record.approval;
 }
+function effectiveDecision(record) {
+  if (record.version !== 2 || record.status !== "active" || record.approval !== "proposed") return record;
+  let index = record.history.length - 1;
+  while (index >= 0 && !["accepted", "reaffirmed"].includes(record.history[index].kind)) index--;
+  if (index < 0) return record;
+  const event = record.history[index];
+  return {
+    ...record,
+    ...event.content,
+    owner: event.content.owner,
+    approval: "accepted",
+    revision: event.revision,
+    refreshedHash: event.refreshedHash,
+    updatedAt: event.at,
+    history: record.history.slice(0, index + 1)
+  };
+}
 function decisionProvenance(record, freshness = "unknown") {
   const approval = decisionApproval(record);
   const review = record.version === 2 ? [...record.history].reverse().find((e) => ["accepted", "reaffirmed"].includes(e.kind) && e.revision === record.revision) : void 0;
@@ -1246,12 +1298,8 @@ async function computeDecisionDrift(rootDir, decisions) {
   const report = { historyAvailable: true, totalDecisions: store.records.length, staleDecisions: {}, freshness: {}, diagnostics: store.diagnostics };
   const [head, workingTree] = await Promise.all([getCurrentGitHash(resolvedRoot), getWorkingTree(resolvedRoot)]);
   const changesByHash = /* @__PURE__ */ new Map();
-  for (const record of store.records) {
-    if (record.status !== "active") continue;
-    if (record.files.length === 0) {
-      report.freshness[record.id] = "unknown";
-      continue;
-    }
+  const inspect = async (record) => {
+    if (record.files.length === 0) return { freshness: "unknown", changedFiles: [] };
     let touched = changesByHash.get(record.refreshedHash);
     if (touched === void 0) {
       const changes = record.refreshedHash === head && head !== "unknown" ? [] : await getChangesWithStatus(resolvedRoot, record.refreshedHash);
@@ -1260,9 +1308,16 @@ async function computeDecisionDrift(rootDir, decisions) {
     }
     if (touched === null) report.historyAvailable = false;
     const hits = touched ? matchingPaths(record.files, touched) : [];
-    if (hits.length) report.staleDecisions[record.id] = hits;
     const localHits = matchingPaths(record.files, workingTree.changedFiles);
-    report.freshness[record.id] = touched === null || !workingTree.available ? "unknown" : hits.length || localHits.length ? "changed" : "current";
+    return { freshness: touched === null || !workingTree.available ? "unknown" : hits.length || localHits.length ? "changed" : "current", changedFiles: hits };
+  };
+  for (const record of store.records) {
+    if (record.status !== "active") continue;
+    const effective = effectiveDecision(record);
+    const state = await inspect(effective);
+    report.freshness[record.id] = state.freshness;
+    if (state.changedFiles.length) report.staleDecisions[record.id] = state.changedFiles;
+    if (effective !== record) (report.pendingProposals ??= {})[record.id] = await inspect(record);
   }
   return report;
 }
@@ -1281,11 +1336,14 @@ async function checkDecisionAnchors(ctx) {
       reason: "some decision base commits are unreachable (shallow clone?)"
     });
   }
-  const byId = new Map(records.map((r) => [r.id, r]));
-  for (const [id, changedFiles] of Object.entries(drift.staleDecisions)) {
-    const record = byId.get(id);
-    if (!record) continue;
-    const provenance = decisionProvenance(record, drift.freshness?.[id] ?? "unknown");
+  const changed = records.flatMap((record) => [
+    { record: effectiveDecision(record), changedFiles: drift.staleDecisions[record.id] ?? [], freshness: drift.freshness?.[record.id] ?? "unknown" },
+    { record, changedFiles: drift.pendingProposals?.[record.id]?.changedFiles ?? [], freshness: drift.pendingProposals?.[record.id]?.freshness ?? "unknown" }
+  ]);
+  for (const { record, changedFiles, freshness } of changed) {
+    if (!changedFiles.length) continue;
+    const id = record.id;
+    const provenance = decisionProvenance(record, freshness);
     result.advisories.push({
       type: "decision-anchor-drift",
       message: `decision "${record.title}" (${provenance.approval}) has anchor files that changed since its evidence baseline \u2013 needs human review`,
@@ -1330,6 +1388,8 @@ async function computeAudit(rootDir, options = {}) {
     version: 1,
     root: resolvedRoot,
     gitAvailable: headHash !== "unknown",
+    headHash,
+    checksRun: [],
     docs: docs.map((d) => ({
       path: d.path,
       lastCommit: d.lastCommit,
@@ -1339,6 +1399,7 @@ async function computeAudit(rootDir, options = {}) {
     decisionsChecked: false,
     issues: [],
     advisories: [],
+    suppressedAdvisories: [],
     skippedChecks: [],
     clean: true
   };
@@ -1367,15 +1428,263 @@ async function computeAudit(rootDir, options = {}) {
   const selected = options.checks ?? ALL_CHECKS;
   for (const name of ALL_CHECKS) {
     if (!selected.includes(name)) continue;
-    const { issues, advisories, skipped } = await CHECKS[name](ctx);
+    const { issues, advisories, suppressedAdvisories, skipped } = await CHECKS[name](ctx);
+    report.checksRun.push(name);
     report.issues.push(...issues);
     report.advisories.push(...advisories);
+    report.suppressedAdvisories.push(...suppressedAdvisories ?? []);
     report.skippedChecks.push(...skipped);
   }
   report.clean = report.issues.length === 0;
   return report;
 }
 
+// src/audit/repair.ts
+import fs10 from "fs/promises";
+import path16 from "path";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { z as z3 } from "zod";
+var checkSchema = z3.enum(["deleted-reference", "new-module", "stale-count", "dead-command", "deps-changed", "decision-anchor-drift"]);
+var commitSchema = z3.object({ hash: z3.string().regex(/^[a-f0-9]{40,64}$/), date: z3.string(), subject: z3.string() });
+var anchorSchema = z3.object({ doc: z3.string(), line: z3.number().int().positive().nullable(), excerpt: z3.string().nullable() });
+var count = z3.number().int().nonnegative();
+var evidenceSchema = z3.discriminatedUnion("kind", [
+  z3.object({
+    kind: z3.literal("missing-path"),
+    claimed: z3.string(),
+    renamedTo: z3.string().nullable(),
+    deletedInCommit: commitSchema.nullable(),
+    everTracked: z3.boolean(),
+    parentDirExists: z3.boolean()
+  }),
+  z3.object({
+    kind: z3.literal("unmentioned-dir"),
+    dir: z3.string(),
+    sourceFileCount: count,
+    firstCommit: commitSchema.nullable(),
+    checkedDocs: z3.array(z3.string())
+  }),
+  z3.object({
+    kind: z3.literal("count-mismatch"),
+    claimed: count,
+    actual: count,
+    unit: z3.string(),
+    countedFrom: z3.string(),
+    members: z3.array(z3.string())
+  }),
+  z3.object({
+    kind: z3.literal("missing-script"),
+    scriptName: z3.string(),
+    invocation: z3.string(),
+    manifestsChecked: z3.array(z3.string()),
+    availableScripts: z3.array(z3.string())
+  }),
+  z3.object({
+    kind: z3.literal("doc-behind-manifests"),
+    docLastCommit: commitSchema,
+    manifestCommits: z3.array(commitSchema.extend({ files: z3.array(z3.string()) })),
+    totalCommits: count
+  }),
+  z3.object({
+    kind: z3.literal("decision-anchor"),
+    decisionId: z3.string(),
+    title: z3.string(),
+    changedFiles: z3.array(z3.string()),
+    refreshedHash: z3.string(),
+    provenance: z3.object({}).passthrough().optional()
+  })
+]);
+var findingSchema = z3.object({ message: z3.string(), anchor: anchorSchema, evidence: evidenceSchema });
+var issueSchema = findingSchema.extend({
+  type: z3.enum(["deleted-reference", "new-module", "stale-count", "dead-command"]),
+  confidence: z3.enum(["certain", "likely"])
+});
+var advisorySchema = findingSchema.extend({ type: z3.enum(["deps-changed", "decision-anchor-drift"]) });
+var reportSchema = z3.object({
+  version: z3.literal(1),
+  root: z3.string(),
+  gitAvailable: z3.literal(true),
+  headHash: commitSchema.shape.hash,
+  checksRun: z3.array(checkSchema).nonempty(),
+  docs: z3.array(z3.object({
+    path: z3.enum(DOC_CANDIDATES),
+    lastCommit: commitSchema.nullable(),
+    dirty: z3.boolean(),
+    lineCount: count
+  })).nonempty(),
+  decisionsChecked: z3.boolean(),
+  clean: z3.boolean(),
+  issues: z3.array(issueSchema),
+  advisories: z3.array(advisorySchema),
+  suppressedAdvisories: z3.array(advisorySchema).optional(),
+  skippedChecks: z3.array(z3.object({ check: z3.string(), reason: z3.string(), doc: z3.string().optional() }))
+});
+var baselineSchema = z3.object({
+  kind: z3.literal("mason-audit-repair"),
+  version: z3.literal(1),
+  createdAt: z3.string().datetime(),
+  report: reportSchema,
+  digest: z3.string().regex(/^[a-f0-9]{64}$/)
+});
+var digest = (value) => createHash2("sha256").update(JSON.stringify(value)).digest("hex");
+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]);
+}
+function allFindings(report) {
+  return [...report.issues, ...report.advisories, ...report.suppressedAdvisories ?? []];
+}
+async function docState(root) {
+  const docs = [];
+  for (const doc of DOC_CANDIDATES) {
+    try {
+      const content = await readBoundedFile(await storePath(root, doc), 10 * 1024 * 1024);
+      if (content === null) throw new Error("Context file is not regular or exceeds 10 MiB: " + doc);
+      docs.push([doc, digest(content)]);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      docs.push([doc, null]);
+    }
+  }
+  return digest(docs);
+}
+async function stableAudit(root, checks) {
+  const head = await getCurrentGitHash(root);
+  const before = await docState(root);
+  const report = await computeAudit(root, { checks });
+  if (head !== await getCurrentGitHash(root) || before !== await docState(root) || report && report.headHash !== head) {
+    throw new Error("HEAD or context files changed during the audit; retry against a stable checkout.");
+  }
+  return report;
+}
+async function prepareRepair(rootDir, checks = ALL_CHECKS) {
+  const root = await fs10.realpath(rootDir);
+  const selected = z3.array(checkSchema).nonempty().parse(checks);
+  const report = await stableAudit(root, selected);
+  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.");
+  const storedReport = reportSchema.parse(report);
+  const payload = {
+    kind: "mason-audit-repair",
+    version: 1,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    report: storedReport
+  };
+  const baselinePath = ".mason/reports/repairs/" + randomUUID2() + ".json";
+  await writeStoreJson(root, baselinePath, { ...payload, digest: digest(payload) });
+  return { version: 1, action: "prepare", baselinePath, report };
+}
+async function verifyRepair(rootDir, baselinePath) {
+  const root = await fs10.realpath(rootDir);
+  const declaredRoot = path16.resolve(rootDir);
+  const relative = path16.isAbsolute(baselinePath) ? path16.relative(isWithinRoot(declaredRoot, baselinePath) ? declaredRoot : root, baselinePath) : baselinePath;
+  const 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;
+  const diagnostics = [];
+  let current = null;
+  try {
+    current = await stableAudit(root, original.checksRun);
+    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;
+      const content = await readBoundedFile(await storePath(root, doc.path), 10 * 1024 * 1024);
+      if (content === null || !content.trim()) {
+        diagnostics.push("Original context file " + doc.path + " is empty or unreadable; losing its claims does not verify a repair.");
+      }
+    }
+    if (await getChangesWithStatus(root, original.headHash) === null) {
+      diagnostics.push("The original audit commit is unavailable; repair history cannot be verified.");
+    }
+  } catch (error) {
+    diagnostics.push(error instanceof Error ? error.message : String(error));
+  }
+  const currentById = new Map((current ? allFindings(current) : []).map((f) => [findingId(f), f]));
+  const originalFindings = allFindings(original);
+  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 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) {
+      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)) {
+      return {
+        ...base,
+        status: "review-required",
+        reason: "An audit cannot establish that this advisory was reviewed. Retain its original evidence and report a separate assessment; editing or committing the doc is not approval."
+      };
+    }
+    return { ...base, status: "resolved", reason: "The original check ran and no longer reports this claim. Inspect the edit for semantic correctness." };
+  });
+  const newFindings = [...currentById].filter(([id]) => !originalIds.has(id)).map(([, f]) => f);
+  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 issuesRemain = counts.unresolved > 0 || newFindings.some((f) => "confidence" in f);
+  return {
+    version: 1,
+    action: "verify",
+    baselinePath: relative,
+    baselineHead: original.headHash,
+    currentHead: current?.gitAvailable ? current.headHash : null,
+    status: incomplete ? "incomplete" : issuesRemain ? "issues-remain" : "verified",
+    findings,
+    newFindings,
+    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."
+  };
+}
+function repairExitCode(report) {
+  return report.status === "verified" ? 0 : report.status === "issues-remain" ? 1 : 2;
+}
+function formatRepairSummary(report) {
+  return [
+    "Repair verification: " + report.status + ". Baseline: " + report.baselinePath,
+    ...report.findings.map((f) => "  [" + f.status + "] " + f.original.type + " " + f.original.anchor.doc + ": " + f.original.message + "\n    " + f.reason),
+    ...report.newFindings.map((f) => "  [new] " + f.type + " " + f.anchor.doc + ": " + f.message),
+    ...report.diagnostics.map((d) => "  [unverified] " + d),
+    ...(report.currentAudit?.skippedChecks ?? []).map((s) => "  [skipped] " + s.check + ": " + s.reason),
+    report.scope
+  ].join("\n");
+}
+
 // src/audit/cli.ts
 var USAGE = `Usage: mason-audit [--dir <path>] [--json | --fix-prompt] [--checks <list>]
 
@@ -1390,7 +1699,10 @@ Options:
   --json           Print the full audit report as JSON (additive-only schema)
   --fix-prompt     When issues exist, print a work order for ANY coding agent
                    (Claude, Codex, Gemini, ...) \u2013 pipe it to your agent CLI to
-                   close the loop. Prints the clean summary when there are none.
+                   repair the findings. Includes advisories that require review.
+  --prepare-repair Save the original audit under .mason/reports/repairs/ before edits
+  --verify-repair <path>
+                   Compare against that saved baseline, using its original checks
   --checks <list>  Comma-separated subset of checks to run (default: all):
                    ${ALL_CHECKS.join(", ")}
   --help           Show this help
@@ -1398,14 +1710,19 @@ Options:
 Exit codes:
   0  no issues (advisories may still be present)
   1  provable issues found
-  2  error (no context file, not a git repository, bad arguments)`;
+  2  error (no context file, not a git repository, bad arguments)
+
+With --verify-repair: 0 verified by the original checks; 1 issues remain;
+2 incomplete (unverified findings, skipped checks, or advisories needing review).
+Preparation writes only a baseline; verification and ordinary audits are read-only.`;
 function parseArgs(argv) {
   const parsed = {
     dir: process.cwd(),
     json: false,
     fixPrompt: false,
     help: false,
-    checks: void 0
+    checks: void 0,
+    prepareRepair: false
   };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -1413,6 +1730,12 @@ function parseArgs(argv) {
       parsed.json = true;
     } else if (arg === "--fix-prompt") {
       parsed.fixPrompt = true;
+    } else if (arg === "--prepare-repair") {
+      parsed.prepareRepair = true;
+    } else if (arg === "--verify-repair") {
+      const value = argv[++i];
+      if (!value || value.startsWith("--")) throw new Error("--verify-repair requires a baseline path");
+      parsed.baseline = value;
     } else if (arg === "--help" || arg === "-h") {
       parsed.help = true;
     } else if (arg === "--dir") {
@@ -1423,6 +1746,7 @@ function parseArgs(argv) {
       const value = argv[++i];
       if (!value) throw new Error("--checks requires a comma-separated list");
       const names = value.split(",").map((n) => n.trim()).filter(Boolean);
+      if (!names.length) throw new Error("--checks requires at least one check");
       for (const name of names) {
         if (!ALL_CHECKS.includes(name)) {
           throw new Error(
@@ -1446,6 +1770,7 @@ function issueLine(issue) {
 }
 function formatAuditSummary(report) {
   const lines = [];
+  const reviewCount = report.advisories.length + (report.suppressedAdvisories?.length ?? 0);
   for (const doc of report.docs) {
     const docIssues = report.issues.filter((i) => i.anchor.doc === doc.path);
     const committed = doc.lastCommit ? `last committed ${doc.lastCommit.date.slice(0, 10)}, ${doc.lastCommit.hash.slice(0, 7)}` : "untracked";
@@ -1473,21 +1798,25 @@ function formatAuditSummary(report) {
       lines.push(`  [skipped] ${skip.check}: ${skip.reason}`);
     }
   }
+  for (const advisory of report.suppressedAdvisories ?? []) {
+    lines.push(`  [suppressed; unresolved] ${advisory.type} ${advisory.anchor.doc}: ${advisory.message}`);
+  }
   lines.push(
-    report.clean ? `Context files are clean (${report.docs.length} doc${report.docs.length === 1 ? "" : "s"} audited).` : `${report.issues.length} issue${report.issues.length === 1 ? "" : "s"} across ${report.docs.length} doc${report.docs.length === 1 ? "" : "s"}.`
+    report.clean ? reviewCount || report.skippedChecks.length ? `No audit issues detected (${report.docs.length} docs audited); ${reviewCount} advisories remain for review, ${report.skippedChecks.length} checks skipped.` : `Context files are clean (${report.docs.length} doc${report.docs.length === 1 ? "" : "s"} audited).` : `${report.issues.length} issue${report.issues.length === 1 ? "" : "s"} across ${report.docs.length} doc${report.docs.length === 1 ? "" : "s"}.`
   );
   return lines.join("\n");
 }
-function formatFixPrompt(report) {
+function formatFixPrompt(report, baselinePath) {
   const flaggedDocs = [...new Set(report.issues.map((i) => i.anchor.doc))];
   const lines = [];
   lines.push(
-    "The AI context files in this repository contain claims that are provably out of date. Fix ONLY the flagged claims. Work autonomously; do not ask questions."
+    "Review the flagged context claims using the evidence below. Make minimal repairs within the user's authorized scope. A setup-only or audit-only request does not authorize rewriting existing documentation."
   );
   lines.push("");
   lines.push("RULES:");
+  lines.push(baselinePath ? `- Preserve the original repair baseline: ${JSON.stringify(baselinePath)}. Do not replace it after editing.` : "- Before the first edit, call mason_repair with action: prepare, or run mason-audit --prepare-repair --json with the same --dir and --checks. Keep the returned baselinePath through verification.");
   lines.push(
-    `- Edit ONLY these files: ${flaggedDocs.join(", ")}. Never modify source code, configs, or anything else \u2013 the docs must be brought to match the code, not the other way around.`
+    `- Edit ONLY these files: ${flaggedDocs.join(", ") || "none (advisory review only)"}. Bring the docs into agreement with verified source evidence; do not change source code or configs to silence findings.`
   );
   lines.push(
     "- Keep diffs minimal: change the smallest span that makes each claim true."
@@ -1495,6 +1824,7 @@ function formatFixPrompt(report) {
   lines.push(
     "- Never invent content. Every replacement must be grounded in the evidence below or in files you read from this repository."
   );
+  lines.push("- Inspect likely findings before editing: heuristic evidence may describe an intentional omission or an example.");
   lines.push(
     "- deleted-reference: if evidence shows renamedTo, update the path; otherwise remove the reference, or rephrase to past tense if the sentence is about history. Deleted paths inside directory trees: delete the tree line."
   );
@@ -1508,20 +1838,27 @@ function formatFixPrompt(report) {
     "- new-module: add a one-line factual mention of the directory where sibling modules are described; read the directory's files first and describe only what you verified."
   );
   lines.push(
-    "- Do NOT touch anything listed under ADVISORIES \u2013 list them in your summary for human review instead."
+    "- ADVISORIES require a separate assessment of the cited commits or decision evidence. Report any review you perform and what remains unknown. Their disappearance after edits or a commit does not establish review or approval."
   );
   lines.push("");
-  lines.push("AUDIT REPORT (deterministic, computed against git HEAD):");
+  lines.push("AUDIT REPORT (current context files and repository evidence, including local edits):");
   lines.push(
     JSON.stringify(
-      { issues: report.issues, advisories: report.advisories },
+      {
+        root: report.root,
+        checks: report.checksRun,
+        issues: report.issues,
+        advisories: report.advisories,
+        suppressedAdvisories: report.suppressedAdvisories,
+        skippedChecks: report.skippedChecks
+      },
       null,
       2
     )
   );
   lines.push("");
   lines.push(
-    "Finish by summarizing each edit and citing the evidence item it resolves."
+    "After edits, call mason_repair with action: verify and the original baselinePath, or mason-audit --verify-repair <baselinePath> --dir <project>. Repeat against the same baseline after any final documentation commit. Summarize resolved, unresolved, review-required, unverified, and new findings with their evidence. Do not report a suppressed or unavailable check as fixed. This audit covers the listed context files; independently discovered README or application issues need their own validation."
   );
   return lines.join("\n");
 }
@@ -1537,6 +1874,9 @@ async function runAuditCli(argv, io = {
     if (args.json && args.fixPrompt) {
       throw new Error("--json and --fix-prompt are mutually exclusive");
     }
+    if (args.baseline && (args.prepareRepair || args.checks || args.fixPrompt)) {
+      throw new Error("--verify-repair cannot be combined with --prepare-repair, --checks, or --fix-prompt; verification uses the original scope");
+    }
   } catch (error) {
     io.err(error instanceof Error ? error.message : String(error));
     io.err(USAGE);
@@ -1546,7 +1886,23 @@ async function runAuditCli(argv, io = {
     io.out(USAGE);
     return 0;
   }
-  const rootDir = path16.resolve(args.dir);
+  const rootDir = path17.resolve(args.dir);
+  if (args.baseline || args.prepareRepair) {
+    try {
+      if (args.baseline) {
+        const verification = await verifyRepair(rootDir, args.baseline);
+        io.out(args.json ? JSON.stringify(verification, null, 2) : formatRepairSummary(verification));
+        return repairExitCode(verification);
+      }
+      const prepared = await prepareRepair(rootDir, args.checks);
+      io.out(args.json ? JSON.stringify({ ...prepared, workOrder: formatFixPrompt(prepared.report, prepared.baselinePath) }, null, 2) : args.fixPrompt ? formatFixPrompt(prepared.report, prepared.baselinePath) : `Repair baseline: ${prepared.baselinePath}
+${formatAuditSummary(prepared.report)}`);
+      return prepared.report.clean ? 0 : 1;
+    } catch (error) {
+      io.err(error instanceof Error ? error.message : String(error));
+      return 2;
+    }
+  }
   const report = await computeAudit(rootDir, { checks: args.checks });
   if (!report) {
     io.err(
@@ -1562,7 +1918,7 @@ async function runAuditCli(argv, io = {
   }
   if (args.fixPrompt) {
     io.out(
-      report.clean ? formatAuditSummary(report) : formatFixPrompt(report)
+      report.clean && !report.advisories.length && !report.suppressedAdvisories?.length ? formatAuditSummary(report) : formatFixPrompt(report)
     );
     return report.clean ? 0 : 1;
   }