mason-context 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.12.0 — 2026-09-06
+
+Mason can now run documentation checks automatically through Claude Code and Codex hooks. It preserves findings before edits can hide them, resumes retained evidence across sessions, and verifies repairs against the final commit. Hook installation is opt-in.
+
+- Add a shared documentation automation runtime with Claude Code and Codex lifecycle adapters, `mason-auto` installation/status/check commands, and the `mason_automation` MCP tool. Retain original and newly discovered findings across sessions, isolate branch/worktree state, verify after the final commit, and distinguish configured hooks from observed runtime events.
+- Cache audit checks by their evidence dependencies, retry skipped checks, serialize concurrent captures, and keep full reports accessible behind concise notifications. Request at most one task-relevant continuation per session; never infer advisory approval or expand repair authorization.
+- Add ordinary-request automation evaluations for module renames and unrelated edits, with baseline, instructions, and hooks arms. Offline lifecycle replay is separate from live agent performance evidence.
+
+Upgrade with `npm install -D mason-context@0.12.0` in each project that will use the default hook command. Run `npx mason-auto install --host claude` or `npx mason-auto install --host codex`, then start a new assistant session; Codex also requires review/trust through `/hooks`. Keep the host configuration and `.mason/automation.json` together in version control, and ignore `.mason/reports/`. Update any separately pinned MCP server command, restart it, and refresh the Mason instructions through `mason_init`. No decision-store migration is required.
+
+Validation includes 414 automated tests, live rename/control smoke tests in both hosts, and a Codex trial in an existing Kotlin Multiplatform/iOS project. These trials observed capture and final-commit verification without requiring forced continuation. The controlled live forced-repair continuation test remains deferred; broader mistake-rate, false-positive, and large-repository performance claims remain unproven. See the [recorded smoke results](https://github.com/adrianczuczka/mason/blob/v0.12.0/bench/harness/automation/SMOKE_RESULTS.md).
+
 ## 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.

package/README.md

@@ -8,6 +8,8 @@
 
 ### Give coding assistants the lessons your team already learned, the changes they might miss, and evidence of what is still current.
 
+Project direction and remaining evidence gaps are recorded in [the roadmap](ROADMAP.md).
+
 Start with useful checks in an existing Git repository — no setup, map build, or model calls:
 
 ```bash
@@ -131,6 +133,7 @@ Mason records assertions of review; it does not authenticate reviewer identity,
 |---|---|
 | `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_automation` | Inspect configured hooks and observed events, or capture/resume and verify retained repair evidence across sessions. |
 | `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. |
@@ -314,6 +317,41 @@ jobs:
 
 Omit `agent-command` for detect-only mode: no agent, no credentials — the job fails when the context files have drifted, which is a reasonable default for repos that want the signal before the automation. Two GitHub notes: the repo setting **"Allow GitHub Actions to create and approve pull requests"** (Settings → Actions → General) must be enabled for the PR step, and PRs created with the default `GITHUB_TOKEN` don't trigger the repo's own CI — run your agent with PAT-backed auth if you need that.
 
+## Automatic documentation checks (mason-auto)
+
+Mason can preserve documentation audit evidence and resume unfinished repairs through Claude Code or Codex lifecycle hooks. A shared engine owns the evidence, verification, and cache; each host adapter handles its event format. No concept map or model call is required for the checks.
+
+Available from 0.12.0. Install or upgrade the package in each project where you want automatic checks:
+
+```bash
+npm install -D mason-context@0.12.0
+npx mason-auto install --host claude   # Claude Code
+npx mason-auto install --host codex    # Codex; review/trust the hooks using /hooks
+npx mason-auto status
+```
+
+Install only the adapters you use. Installation merges the project's `.claude/settings.json` or `.codex/hooks.json`, preserves other hooks/settings, and records its own handler in `.mason/automation.json`. Repeating installation updates only those handlers. Keep the host configuration and `.mason/automation.json` together in version control; if you ignore all of `.mason/`, allow the installation record explicitly. Add `.mason/reports/` to your ignore rules. Start a new assistant session after installation. The default handler uses the locally installed package with `npx --no-install`; `--command` accepts an executable prefix for an existing installation.
+
+When upgrading an existing MCP setup, update any separately pinned server command to `mason-context@0.12.0`, restart the server, and refresh the Mason instruction block through `mason_init`. Existing decisions and repair baselines need no migration. Upgrading the package alone does not install hooks.
+
+`status` distinguishes configuration from observed events. Host versions, project trust, policy, and specialized tool paths can prevent hooks from running. Configuration alone is not evidence of automatic use. Codex requires review/trust of new or changed non-managed hooks. See the [Claude Code hook reference](https://code.claude.com/docs/en/hooks) and [Codex hook reference](https://learn.chatgpt.com/docs/hooks).
+
+On session start, Mason recovers the current branch/worktree's evidence. Before and after tools, it checks for changed audit inputs and retains newly observed findings before another documentation edit can hide them. Shell and unknown tool calls are included because edits can happen outside a file-edit tool. At turn completion it verifies the retained findings. A relevant unresolved issue can request **one continuation per session**; advisories and unavailable checks never create a repair loop. Fixes remain the assistant's responsibility within the user's task scope.
+
+Checks reuse cached results only when their dependencies match. Documentation and history, file inventory, manifests, and decision evidence have separate invalidation keys. Changes to a dirty manifest invalidate its checks even when Git's status text is unchanged. Skipped checks are retried. Cache corruption causes recomputation; invalid original baselines or active state remain errors. Concurrent events serialize writes, and interrupted local writers' locks are recovered only when their process is gone. New reports are written atomically. Unchanged tool events reuse the existing full report.
+
+```bash
+npx mason-auto check --json   # Capture/resume the active evidence and verify it
+# After any final documentation commit:
+npx mason-auto check
+```
+
+The equivalent MCP operation is `mason_automation(action: "check")`. Its response is concise and links the full local report. `status` is read-only; `check` writes evidence. Exit codes are 0 for verified checks, 1 for unresolved issues, and 2 for incomplete/unavailable checks. Original `mason_repair` baselines remain separately verifiable by their paths. Hook errors are visible and advisory; the existing `mason-hook` decision injector keeps its previous behavior.
+
+Evidence is local to the worktree and branch. Switching assistants in that worktree resumes the same repair; another worktree or branch has separate state. Detached-HEAD commits retain evidence; moving that checkout to a different history requires inspection. Hooks follow the Git worktree of the event's working directory. Reports are not automatically transferred to CI. CI can call `mason-auto check` on retained local artifacts, or `mason-audit --verify-repair <baseline>` after restoring the original artifacts at their recorded root. A fresh checkout cannot reconstruct missing pre-edit evidence. Audited instruction files remain limited to `AGENTS.md`, `CLAUDE.md`, and `.claude/CLAUDE.md`. Automation bounds inventory at 100,000 paths and retained baselines at 128; exceeding a bound reports unavailable evidence without evicting unresolved findings. Symbolic links in the inspected inventory require an explicit audit instead of cached automation. This is not proof of arbitrary repository scale or universal tool interception.
+
+The [automation evaluation](bench/harness/automation/README.md) compares ordinary module-renaming requests and unrelated edits across hosts, with baseline, instructions, and hooks arms. Deterministic replay verifies the mechanism; live sessions measure actual activation.
+
 ## Decision injection (mason-hook)
 
 Recorded knowledge only helps if it shows up. Retrieval tools depend on the model deciding to call them — and it often doesn't. `mason-hook` removes the gamble: it's a Claude Code `PostToolUse` hook that fires when a session reads or edits a file, looks up the decision records anchored to that file (exact path or directory prefix), and injects them into the model's context. Deterministic lookup, no LLM call, ~100ms, silent when nothing matches. Each decision is injected at most once per session, and records whose anchors drifted since verification carry a verify-before-relying marker.
@@ -508,7 +546,7 @@ If you used Mason before v0.4.0, the standalone `mason <command>` CLI has been r
 | `mason impact File.kt` | Ask your assistant: *"what would changing File.kt affect?"* — it calls `get_impact`. |
 | `mason snapshot --install-hook` | Removed. The map auto-refreshes when the assistant detects stale state. |
 
-The package provides `mason-mcp`, `mason-drift`, `mason-audit`, `mason-hook`, and `mason-review`. Running `mason` directly prints a migration message and exits.
+The package provides `mason-mcp`, `mason-drift`, `mason-audit`, `mason-auto`, `mason-hook`, and `mason-review`. Running `mason` directly prints a migration message and exits.
 
 ## License
 

package/dist/mason-audit.js

@@ -1428,7 +1428,7 @@ 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, suppressedAdvisories, skipped } = await CHECKS[name](ctx);
+    const { issues, advisories, suppressedAdvisories, skipped } = await (options.runCheck ? options.runCheck(name, ctx) : CHECKS[name](ctx));
     report.checksRun.push(name);
     report.issues.push(...issues);
     report.advisories.push(...advisories);
@@ -1500,6 +1500,12 @@ var issueSchema = findingSchema.extend({
   confidence: z3.enum(["certain", "likely"])
 });
 var advisorySchema = findingSchema.extend({ type: z3.enum(["deps-changed", "decision-anchor-drift"]) });
+var checkResultSchema = z3.object({
+  issues: z3.array(issueSchema),
+  advisories: z3.array(advisorySchema),
+  suppressedAdvisories: z3.array(advisorySchema).optional(),
+  skipped: z3.array(z3.object({ check: z3.string(), reason: z3.string(), doc: z3.string().optional() }))
+});
 var reportSchema = z3.object({
   version: z3.literal(1),
   root: z3.string(),
@@ -1569,19 +1575,19 @@ async function docState(root) {
   }
   return digest(docs);
 }
-async function stableAudit(root, checks) {
+async function stableAudit(root, checks, options = {}) {
   const head = await getCurrentGitHash(root);
   const before = await docState(root);
-  const report = await computeAudit(root, { checks });
+  const report = await computeAudit(root, { ...options, 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) {
+async function prepareRepair(rootDir, checks = ALL_CHECKS, options = {}) {
   const root = await fs10.realpath(rootDir);
   const selected = z3.array(checkSchema).nonempty().parse(checks);
-  const report = await stableAudit(root, selected);
+  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.");
   const storedReport = reportSchema.parse(report);
@@ -1595,7 +1601,7 @@ async function prepareRepair(rootDir, checks = ALL_CHECKS) {
   await writeStoreJson(root, baselinePath, { ...payload, digest: digest(payload) });
   return { version: 1, action: "prepare", baselinePath, report };
 }
-async function verifyRepair(rootDir, baselinePath) {
+async function verifyRepair(rootDir, baselinePath, options = {}) {
   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;
@@ -1607,7 +1613,7 @@ async function verifyRepair(rootDir, baselinePath) {
   const diagnostics = [];
   let current = null;
   try {
-    current = await stableAudit(root, original.checksRun);
+    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) {