mason-context 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.11.0 — 2026-09-05
+
+Mason now keeps the original audit evidence visible while an assistant repairs documentation. A dependency warning suppressed by local edits stays unresolved, and a later documentation commit does not silently clear its review requirement.
+
+- Add `mason_repair` and `mason-audit --prepare-repair` / `--verify-repair` to retain original audit evidence through edits and the final documentation commit. Verification distinguishes resolved, unresolved, review-required, unverified, and new findings; it preserves unavailable history and missing-document diagnostics.
+- Retain suppressed dependency advisories when setup or repairs dirty context files. An advisory disappearing after a documentation commit no longer loses its evidence in a prepared repair. Ordinary audit exit codes stay unchanged; explicit repair verification reports incomplete scope separately.
+- Route authorized repairs through preparation and verification in assistant instructions and work orders. Setup alone does not authorize rewriting existing claims; advisories require a separate assessment.
+
+Upgrade to `mason-context@0.11.0`, restart the assistant, and refresh its marker-delimited Mason instructions through `mason_init` to enable the repair workflow. No decision-store migration is required. Explicit repair verification exits 2 for incomplete checks or outstanding advisory review; ordinary audit exit codes are unchanged.
+
 ## 0.10.1 — 2026-09-05
 
 Editing an accepted decision previously hid its accepted content from ordinary retrieval until the draft was reviewed. Mason now keeps the accepted constraint visible alongside the proposed replacement.

package/README.md

@@ -130,6 +130,7 @@ Mason records assertions of review; it does not authenticate reviewer identity,
 | Tool | Purpose |
 |---|---|
 | `mason_init` | Read-only audit/review findings and quickstart guide; optional `base` for review, `evidence` for local CI manifests, `mode: "map"` for an architecture build. |
+| `mason_repair` | Prepare an audit repair baseline; verify the same original findings after edits. Reports unresolved advisories and unavailable checks. |
 | `mason_complete_init` | Records assistant instruction setup; preserves prior settings on repeated calls. |
 | `generate_snapshot_batch` | Map step — returns one batch of files for the assistant to summarize. |
 | `save_partial_snapshot` | Persists the partial map for one batch. |
@@ -272,7 +273,29 @@ Issues drive the exit code; **advisories never do** — they're facts an agent c
 
 ### The context files maintain themselves
 
-Same split as the concept map: detection is deterministic and free, the fix is any agent you already run. `--fix-prompt` emits a work order scoped to exactly the flagged claims — fix only these, minimal diffs, never invent content, never touch source code. The reusable workflow runs the audit, hands the work order to your agent, verifies the audit is clean afterwards (and that the agent touched nothing but the context files), then opens a PR citing the evidence — it never commits to the audited branch, and it skips cleanly when an audit PR is already open:
+### Track a repair through verification
+
+Ask your assistant: *"Use Mason to prepare a repair, fix the documented issues within scope, and verify against the original findings."* The assistant calls `mason_repair` with `action: "prepare"`, makes grounded edits, and then calls it with `action: "verify"` and the returned `baselinePath`. Setup alone only installs assistant instructions; repairing existing claims needs to be part of your request.
+
+The CLI provides the same workflow:
+
+```bash
+mason-audit --dir . --prepare-repair --fix-prompt
+# After applying the work order, use the exact baseline path it returned:
+mason-audit --dir . --verify-repair .mason/reports/repairs/<id>.json
+```
+
+Preparation saves the full original audit under `.mason/reports/repairs/`; it does not edit documentation. Ordinary audits and verification remain read-only. Add `.mason/reports/` to your ignore rules if you want these local artifacts excluded from commits. Keep the same baseline through any final documentation commit, then verify again. Do not regenerate it to clear unresolved findings. `--json` is supported for preparation and verification; use `--checks` only during preparation to select a scope.
+
+Each original finding is **resolved** (its check no longer reports it), **unresolved**, **review-required**, or **unverified**. New findings are separate. A shifted line number does not erase the original claim, and a missing document, unavailable history, or skipped check cannot count as a fix. Inspect the edit for meaning: these deterministic checks do not establish complete documentation correctness. README files and arbitrary build commands are outside this audit's current scope.
+
+Dependency evidence suppressed by local edits is retained in `suppressedAdvisories`, including when setup has already dirtied the document. Committing that document does not prove the dependency change was reviewed: the original advisory stays in the repair report. Record your assessment separately; this workflow does not approve advisories or decisions. Baselines are validated local evidence with a checksum to detect accidental edits, not authenticated attestations.
+
+Ordinary audit exit codes remain **0** for no issues (advisories may exist), **1** for issues, and **2** for errors. Explicit `--verify-repair` uses **0** for verified scope, **1** for remaining/new issues, and **2** for incomplete verification, including advisories needing review or skipped checks. Incomplete verification takes precedence when both issues and unavailable evidence remain.
+
+### Repair pull requests in CI
+
+`--fix-prompt` emits a work order scoped to the flagged claims and the user's authorization. The reusable workflow below prepares a baseline, checks that the agent touched only context files, and verifies the original issues both before and after the documentation commit. It opens a PR only when those issues are resolved by their checks and no new issues appear. Advisories and skipped checks remain visible in the PR; their review is not a condition for proposing documentation repairs. The workflow never commits to the audited branch and skips when an audit PR is already open:
 
 ```yaml
 name: Context audit

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 },
@@ -1353,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,
@@ -1362,6 +1399,7 @@ async function computeAudit(rootDir, options = {}) {
     decisionsChecked: false,
     issues: [],
     advisories: [],
+    suppressedAdvisories: [],
     skippedChecks: [],
     clean: true
   };
@@ -1390,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>]
 
@@ -1413,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
@@ -1421,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];
@@ -1436,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") {
@@ -1446,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(
@@ -1469,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";
@@ -1496,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."
@@ -1518,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."
   );
@@ -1531,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");
 }
@@ -1560,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);
@@ -1569,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(
@@ -1585,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;
   }