@event4u/agent-config 14.10.0 → 14.11.0

package/src/scripts/lint_judge_prompt_expectation.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env tsx
+/**
+ * Warn when a captured judge prompt states an EXPECTATION of the outcome.
+ *
+ * Step 4.2 of `road-to-review-independence`, and the companion to
+ * `evidence_independence.ts`. That concern blocks a prompt carrying a pre-loaded
+ * **verdict**; this one reads the prompts that were actually sent and warns on the
+ * softer form — a statement of what the author thinks the answer will be.
+ *
+ * The distinction is not academic. *"NO-FINDINGS is expected and welcome"* names no
+ * verdict and supplies one; it steered a real review into an honest-null that a later
+ * unsteered pass refuted with five findings, one critical, already live on the trunk.
+ * `evaluator-independence.md` states the rule; this is the part a script can see.
+ *
+ * WHAT IT CANNOT SEE — stated here so the gate is not oversold, exactly as
+ * `evidence_independence.ts` states its own phrase-list limit:
+ *
+ * 1. **A paraphrase.** This is a PHRASE LIST. "no findings expected" is caught; "I'd be
+ *    surprised if anything turns up" is not. It catches recurrences of known steering
+ *    wording, never steering as such. Closing that needs a judgement, not a check.
+ * 2. **Omission.** A round that commits no `prompt.md` is not in the scanned set at all —
+ *    the same cheapest-bypass `check_review_prompt_binding` records for itself. Nothing
+ *    in the tree requires the package to exist.
+ * 3. **Substitution.** The party that writes a steered prompt also writes the file, so
+ *    swapping a clean one in passes. What changes is that steering then requires an act
+ *    of substitution rather than merely a careless sentence.
+ *
+ * WARN-ONLY, deliberately. A phrase list that can refuse a review would refuse the
+ * false positives too, and the shape it is looking for is one sentence in a long prompt.
+ * Exit is always 0; the finding is the output.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const REVIEWS_DIR = path.join('agents', 'evidence', 'reviews');
+
+/**
+ * Phrases that state an expectation of the outcome.
+ *
+ * Each is a shape observed or narrowly derived from one, and the list is deliberately
+ * short: a long list of guesses produces false positives, and a warn nobody trusts is
+ * worse than no warn. The first entry is the measured one.
+ */
+export const EXPECTATION_PHRASES: readonly RegExp[] = [
+    /no[- ]findings\s+(?:is|are)\s+(?:expected|welcome)/i,
+    /\bexpect(?:ing)?\s+(?:no|zero)\s+(?:findings|issues|problems)/i,
+    /\bshould\s+be\s+(?:clean|fine|correct|green)\b/i,
+    /\bi\s+believe\s+this\s+is\s+(?:correct|clean|right)\b/i,
+    /\bjust\s+confirm\b/i,
+    /\bplease\s+confirm\s+(?:that\s+)?(?:there\s+are\s+)?no\b/i,
+    /\bthis\s+(?:should|ought\s+to)\s+pass\b/i,
+];
+
+export interface Finding {
+    readonly file: string;
+    readonly line: number;
+    readonly phrase: string;
+    readonly text: string;
+}
+
+/** Scan one prompt's text. Returns every match, not the first — a prompt can steer twice. */
+export function scanPromptText(rel: string, text: string): Finding[] {
+    const out: Finding[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i]!;
+        for (const re of EXPECTATION_PHRASES) {
+            const m = re.exec(line);
+            if (m !== null) {
+                out.push({
+                    file: rel,
+                    line: i + 1,
+                    phrase: m[0],
+                    // Trimmed and capped: the finding names the sentence, and a prompt
+                    // line can be very long.
+                    text: line.trim().slice(0, 160),
+                });
+            }
+        }
+    }
+    return out;
+}
+
+/** Every `<slug>.review-input/prompt.md` under the reviews directory. */
+export function collectPrompts(repoRoot: string): string[] {
+    const dir = path.join(repoRoot, REVIEWS_DIR);
+    if (!fs.existsSync(dir)) return [];
+    const out: string[] = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+        a.name < b.name ? -1 : 1,
+    )) {
+        if (!entry.isDirectory() || !entry.name.endsWith('.review-input')) continue;
+        const p = path.join(dir, entry.name, 'prompt.md');
+        if (fs.existsSync(p)) out.push(p);
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] = []): number {
+    const quiet = argv.includes('--quiet');
+    const rootIdx = argv.indexOf('--repo-root');
+    const repoRoot = rootIdx >= 0 ? (argv[rootIdx + 1] ?? REPO_ROOT) : REPO_ROOT;
+
+    const prompts = collectPrompts(repoRoot);
+    const findings: Finding[] = [];
+    for (const p of prompts) {
+        findings.push(...scanPromptText(path.relative(repoRoot, p), fs.readFileSync(p, 'utf-8')));
+    }
+
+    reportScanned({
+        gate: 'lint_judge_prompt_expectation',
+        scanned: prompts.length,
+        units: 'captured judge prompt(s)',
+        roots: [REVIEWS_DIR],
+    });
+
+    if (findings.length === 0) {
+        if (!quiet) {
+            process.stdout.write(
+                '✅  lint_judge_prompt_expectation: no captured prompt states an expectation ' +
+                    'of the outcome (phrase list only — a paraphrase is not caught).\n',
+            );
+        }
+        return 0;
+    }
+    process.stdout.write(
+        `⚠️   lint_judge_prompt_expectation: ${String(findings.length)} prompt line(s) state an ` +
+            'expectation of the outcome. WARN ONLY — review them:\n',
+    );
+    for (const f of findings) {
+        process.stdout.write(`  ${f.file}:${String(f.line)} — "${f.phrase}"\n      ${f.text}\n`);
+    }
+    process.stdout.write(
+        '\n  A prompt that says what the author thinks the answer is has authored the answer, ' +
+            'whatever mood it used. See src/rules/evaluator-independence.md.\n',
+    );
+    // Always 0. See the header: a phrase list that can refuse would refuse its false
+    // positives too.
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    const invoked = process.argv[1];
+    return invoked !== undefined && path.resolve(invoked) === path.resolve(fileURLToPath(import.meta.url));
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/lint_marketplace.ts

@@ -15,6 +15,8 @@
  *   - owner must have name + email
  *   - metadata must have description + version
  *   - metadata.version must match package.json (single source of truth)
+ *   - every version field in BOTH .augment-plugin/ manifests matches
+ *     package.json too — see check_augment_manifests()
  *   - the union of plugins[].skills[] must be EXACTLY the pointer skill
  *     (./.claude-plugin/skills/install-agent-config) — a repopulated
  *     content-skill list FAILS by design
@@ -88,6 +90,87 @@ function require_key(
   return true;
 }
 
+/**
+ * Every version field in both `.augment-plugin/` manifests must equal
+ * `package.json`'s.
+ *
+ * WHY THE AUGMENT TWIN IS IN SCOPE OF THIS GATE. Both files ship in the npm
+ * tarball — `src/config/publish-surface.json` lists `.augment-plugin/` as a
+ * publish root — and both carried `version: 1.0.0` while `package.json` moved
+ * to 14.x. Nothing in the tree ever claimed `1.0.0` was an independent
+ * plugin-API version: no comment, no test, no doc, and the only reader anywhere
+ * is `src/scripts/probe_skill_registration.ts:137`. `plugin.json` had not been
+ * touched since 2026-04-17. An unclaimed constant no reader interprets is
+ * drift, not a deliberate independent version — so the Augment manifests are
+ * treated as the projection counterpart of the `.claude-plugin` twin this gate
+ * already version-syncs, and are held to the same rule.
+ *
+ * Reversible in one commit if that reading is ever wrong, which is why
+ * `docs/CLAIMS.md` records the choice rather than leaving it implicit.
+ *
+ * The nesting differs between the two files, so the fields are enumerated
+ * rather than discovered: a recursive "every key named version" walk would
+ * silently start policing a future field that is legitimately independent.
+ */
+export function check_augment_manifests(
+  pkgVersion: string,
+  errors: string[],
+  base: string = ROOT,
+): void {
+  const targets: Array<[string, string[][]]> = [
+    [path.join(base, ".augment-plugin", "plugin.json"), [["version"]]],
+    [
+      path.join(base, ".augment-plugin", "marketplace.json"),
+      [["version"], ["metadata", "version"], ["plugins", "*", "version"]],
+    ],
+  ];
+  for (const [file, paths] of targets) {
+    if (!_exists(file)) {
+      errors.push(`${file} not found (listed in publish-surface.json roots)`);
+      continue;
+    }
+    let data: JsonValue;
+    try {
+      data = JSON.parse(fs.readFileSync(file, "utf-8")) as JsonValue;
+    } catch (e) {
+      errors.push(`${file} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+      continue;
+    }
+    for (const keys of paths) {
+      for (const [label, value] of _resolveVersionField(data, keys)) {
+        if (value !== pkgVersion) {
+          errors.push(
+            `${file}: ${label} \`${String(value)}\` does not match ` +
+              `package.json version \`${pkgVersion}\``,
+          );
+        }
+      }
+    }
+  }
+}
+
+/** Resolve a key path, expanding `*` over array indices. Returns [label, value]. */
+function _resolveVersionField(
+  data: JsonValue,
+  keys: readonly string[],
+  prefix = "",
+): Array<[string, JsonValue | undefined]> {
+  if (keys.length === 0) {
+    return [[prefix.replace(/^\./, ""), data]];
+  }
+  const [head, ...rest] = keys as [string, ...string[]];
+  if (head === "*") {
+    if (!Array.isArray(data)) {
+      return [[`${prefix}[*]`.replace(/^\./, ""), undefined]];
+    }
+    return data.flatMap((item, i) => _resolveVersionField(item, rest, `${prefix}[${String(i)}]`));
+  }
+  if (!isObject(data)) {
+    return [[`${prefix}.${head}`.replace(/^\./, ""), undefined]];
+  }
+  return _resolveVersionField(data[head] ?? null, rest, `${prefix}.${head}`);
+}
+
 export function main(): number {
   // No corpus to count — the shim is exactly one manifest plus one pointer
   // skill, and every count the shape offers (plugins, skill entries, dirs under
@@ -100,6 +183,8 @@ export function main(): number {
       gate: "lint_marketplace",
       candidates: [
         ".claude-plugin/marketplace.json",
+        ".augment-plugin/plugin.json",
+        ".augment-plugin/marketplace.json",
         "package.json",
         `${POINTER_SKILL_ENTRY.replace(/^\.\//, "")}/SKILL.md`,
       ],
@@ -161,6 +246,9 @@ export function main(): number {
             `package.json version \`${String(pkgVersion)}\``,
         );
       }
+      if (typeof pkgVersion === "string") {
+        check_augment_manifests(pkgVersion, errors);
+      }
     }
   } else {
     errors.push("`metadata` must be an object");

package/src/scripts/lint_media_policy_linkage.ts

@@ -18,7 +18,13 @@
  * shallow and the referrer roots named the pre-ADR-051 container. Repaired
  * 2026-08-02; see the constants below.
  *
- * Exit codes: 0 all policies linked, 1 one or more orphan policies, 2 dead scope.
+ * SECOND PASS (skill-link-integrity Phase 3): adapter lifecycle parity. See
+ * {@link adapter_lifecycle_findings} — the nearest existing scope for a check
+ * `docs/contracts/provider-lifecycle.md` says in its own words that CI does not
+ * perform.
+ *
+ * Exit codes: 0 all policies linked and lifecycle tags agree, 1 one or more
+ * orphan policies or a lifecycle disagreement, 2 dead scope.
  */
 
 import * as fs from 'node:fs';
@@ -186,6 +192,110 @@ function referrers_for(policy: string, scanFiles: readonly string[]): string[] {
     return referrers;
 }
 
+// ── Adapter lifecycle parity ────────────────────────────────────────────────
+// `docs/contracts/provider-lifecycle.md:101` states the obligation and its own
+// gap in one sentence: "Editing an adapter and leaving its header `Lifecycle:`
+// comment out of sync with `agents/templates/.ai-video.xml.example` → violation
+// (CI does not catch this; the agent must)." This pass makes CI catch it.
+//
+// EXPECTED GREEN ON LANDING, and that is the point rather than a weakness. The
+// premise this was drafted against claimed a live contradiction between the
+// higgsfield adapter header and the contract; re-reading the tree refuted it —
+// the two surfaces the contract actually obliges to agree DO agree at `stable`,
+// and the surface reading `experimental` is § 5, a table that says in its own
+// words that it lists the tiers "on the day this contract lands". So there is
+// nothing to repair today; the check exists so the next divergence is caught.
+// Its sensitivity is proven by a fixture that must be red, not by a finding.
+//
+// § 5 IS DELIBERATELY NOT AN INPUT. A historical record must not be able to
+// fail a live check — wiring it in would make the gate demand that a
+// day-one table be edited, which would destroy the record it is.
+//
+// DRIVEN FROM THE ADAPTERS, NOT FROM THE XML. The example declares providers
+// that have no adapter at all (`allin1`, `whisperx`) and one that is a
+// documentation placeholder inside a commented example block
+// (`my-future-backend`); iterating the xml would demand adapters for all three.
+// The reverse direction is still covered: an adapter with no provider entry is
+// reported, because a shipped adapter the example never declares is exactly the
+// drift this pass is for.
+
+/** `# Lifecycle: <tier>` from an adapter header. */
+const ADAPTER_LIFECYCLE_RE = /^#\s*Lifecycle:\s*([a-z]+)/m;
+
+/** Repo-relative adapter dir and the xml example the contract pairs it with. */
+const ADAPTER_DIR = path.join(REPO, 'src', 'scripts', 'ai-video', 'adapters');
+const AI_VIDEO_EXAMPLE = path.join(REPO, 'agents', 'templates', '.ai-video.xml.example');
+
+/** `<provider id="x" …> … <lifecycle>tier</lifecycle>` pairs, xml order. */
+export function parse_example_lifecycles(xml: string): Map<string, string> {
+    const out = new Map<string, string>();
+    const re = /<provider\s+id="([^"]+)"[^>]*>([\s\S]*?)<\/provider>/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(xml)) !== null) {
+        const tier = /<lifecycle>\s*([a-z]+)\s*<\/lifecycle>/.exec(m[2] as string);
+        // First declaration wins: the example's commented "how to add one"
+        // block repeats an id shape, and a later placeholder must not overwrite
+        // a real entry.
+        if (tier && !out.has(m[1] as string)) {
+            out.set(m[1] as string, tier[1] as string);
+        }
+    }
+    return out;
+}
+
+/** Findings for adapter-vs-example lifecycle disagreement. `[]` = parity holds. */
+export function adapter_lifecycle_findings(
+    adapterDir: string = ADAPTER_DIR,
+    examplePath: string = AI_VIDEO_EXAMPLE,
+): string[] {
+    const findings: string[] = [];
+    let xml: string;
+    try {
+        xml = fs.readFileSync(examplePath, 'utf-8');
+    } catch {
+        return [`${_relToPosix(examplePath, REPO)} is unreadable — lifecycle parity cannot be checked`];
+    }
+    const declared = parse_example_lifecycles(xml);
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(adapterDir).filter((f) => f.endsWith('.sh')).sort();
+    } catch {
+        return [`${_relToPosix(adapterDir, REPO)} is unreadable — lifecycle parity cannot be checked`];
+    }
+    for (const file of entries) {
+        const id = file.replace(/\.sh$/, '');
+        const header = ADAPTER_LIFECYCLE_RE.exec(fs.readFileSync(path.join(adapterDir, file), 'utf-8'));
+        if (header === null) {
+            findings.push(`adapters/${file}: no \`# Lifecycle:\` header comment`);
+            continue;
+        }
+        const inXml = declared.get(id);
+        if (inXml === undefined) {
+            findings.push(
+                `adapters/${file}: header says \`${header[1] as string}\` but no ` +
+                    `<provider id="${id}"> exists in ${_relToPosix(examplePath, REPO)}`,
+            );
+            continue;
+        }
+        if (inXml !== header[1]) {
+            findings.push(
+                `adapters/${file}: header \`${header[1] as string}\` != ` +
+                    `<provider id="${id}"><lifecycle>${inXml}</lifecycle>`,
+            );
+        }
+    }
+    return findings;
+}
+
+/** Adapter count, for the dead-scope assertion. */
+export function count_adapters(adapterDir: string = ADAPTER_DIR): number {
+    try {
+        return fs.readdirSync(adapterDir).filter((f) => f.endsWith('.sh')).length;
+    } catch {
+        return 0;
+    }
+}
+
 function main(): number {
     // Scope assertions replace the two silent early returns this gate used to
     // take. Both are deliberately WITHOUT `allowEmpty`: "the policy directory
@@ -207,6 +317,13 @@ function main(): number {
             units: 'referrer-candidate file(s)',
             roots: SCAN_ROOTS.map((r) => _relToPosix(r, REPO)),
         });
+        // Zero adapters means the adapter root moved, not that parity holds.
+        assertScanned({
+            gate: 'lint_media_policy_linkage',
+            scanned: count_adapters(),
+            units: 'ai-video adapter(s)',
+            roots: [_relToPosix(ADAPTER_DIR, REPO)],
+        });
     } catch (exc) {
         if (!(exc instanceof DeadScopeError)) {
             throw exc;
@@ -227,6 +344,11 @@ function main(): number {
         emit(`✅  ${rel}  (${referrers.length} referrer(s))`);
     }
 
+    const lifecycle = adapter_lifecycle_findings();
+    for (const f of lifecycle) {
+        emit(`❌  LIFECYCLE  ${f}`);
+    }
+
     if (orphans.length > 0) {
         process.stderr.write(
             `\nmedia-policy-linkage: ${orphans.length} orphan policy ` +
@@ -239,10 +361,27 @@ function main(): number {
         return 1;
     }
 
+    if (lifecycle.length > 0) {
+        process.stderr.write(
+            `\nadapter-lifecycle-parity: ${lifecycle.length} disagreement(s) ` +
+                `between an adapter header and agents/templates/.ai-video.xml.example. ` +
+                `The day-one table in docs/contracts/provider-lifecycle.md § 5 is NOT ` +
+                `an input here — it is a historical record.\n`,
+        );
+        for (const f of lifecycle) {
+            process.stderr.write(`  - ${f}\n`);
+        }
+        return 1;
+    }
+
     emit(
         `media-policy-linkage: ${policies.length} policy file(s) — all ` +
             `linked (${scanFiles.length} file(s) scanned for referrers).`,
     );
+    emit(
+        `adapter-lifecycle-parity: ${count_adapters()} adapter(s) — every ` +
+            `\`# Lifecycle:\` header agrees with its <provider> entry.`,
+    );
     return 0;
 }
 

package/src/scripts/lint_one_off_age.ts

@@ -28,6 +28,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { asOf, asOfBanner } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -59,7 +60,7 @@ interface SimpleDate {
 }
 
 function _today_utc(): SimpleDate {
-    const now = new Date();
+    const now = asOf();
     return {
         y: now.getUTCFullYear(),
         m: now.getUTCMonth() + 1,
@@ -369,6 +370,10 @@ export function main(): number {
         }));
         process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
     } else {
+        // Text only: the JSON payload is consumed by tooling and must stay a
+        // bare array. A reviewer reading the text report needs to know which
+        // "now" produced these ages — see `_lib/as_of.ts`.
+        process.stdout.write(`${asOfBanner()}\n`);
         process.stdout.write(format_text(findings) + '\n');
     }
     return findings.some((f) => f.severity === 'fail') ? 1 : 0;

package/src/scripts/lint_override_kernel_guard.ts

@@ -184,21 +184,32 @@ export function classify_violations(input: {
     return violations;
 }
 
-export function audit(): OverrideRow[] {
-    if (!fs.existsSync(OVERRIDES_RULES)) return [];
+/**
+ * @param overridesDir  Directory of override files to audit. Defaults to the real
+ *   `agents/overrides/rules/`; a caller passes a fixture directory so the
+ *   reachability of the audit itself can be tested against a KNOWN pair rather
+ *   than against whatever the tree happens to contain. Added by step 1.2 of
+ *   `road-to-override-efficacy-proof`: with the path hardcoded, a test could only
+ *   assert against the one real override, so a regression that stopped
+ *   discovering files would still read clean on an empty directory.
+ *
+ *   Additive, with a default, so no existing caller changes.
+ */
+export function audit(overridesDir: string = OVERRIDES_RULES): OverrideRow[] {
+    if (!fs.existsSync(overridesDir)) return [];
     const floor = safety_floor_ids(RULES_DIR);
     const registered = fs.existsSync(REGISTRY)
         ? registered_rules(fs.readFileSync(REGISTRY, 'utf-8'))
         : new Set<string>();
 
     const rows: OverrideRow[] = [];
-    for (const name of fs.readdirSync(OVERRIDES_RULES).sort()) {
+    for (const name of fs.readdirSync(overridesDir).sort()) {
         if (!name.endsWith('.md')) continue;
         const rule = name.replace(/\.md$/, '');
         const kernel = is_kernel_rule(rule);
         const is_floor = floor.has(rule);
 
-        const text = fs.readFileSync(path.join(OVERRIDES_RULES, name), 'utf-8');
+        const text = fs.readFileSync(path.join(overridesDir, name), 'utf-8');
         const mode = parse_mode(text);
         const cited = has_citation(text);
         const is_registered = registered.has(rule);
@@ -206,7 +217,7 @@ export function audit(): OverrideRow[] {
 
         rows.push({
             rule,
-            file: path.relative(REPO_ROOT, path.join(OVERRIDES_RULES, name)),
+            file: path.relative(REPO_ROOT, path.join(overridesDir, name)),
             mode,
             kernel,
             safety_floor: is_floor,
@@ -218,9 +229,65 @@ export function audit(): OverrideRow[] {
     return rows;
 }
 
+/**
+ * Render the precedence table — step 1.4 of `road-to-override-efficacy-proof`.
+ *
+ * The audit's answer already existed as JSON nobody runs. This is the same answer
+ * in a form a reviewer reads, and it is GENERATED rather than written: regenerating
+ * it on an unchanged tree must produce no diff, so the table is a fact about the
+ * tree rather than a snapshot of when someone last looked.
+ *
+ * Rows are sorted by `rule` (the audit already reads its directory sorted), and no
+ * timestamp is emitted. A generated file carrying "last updated" changes on every
+ * run and makes `git diff --exit-code` useless as a freshness check — the check the
+ * step's verify actually performs.
+ */
+export function render_precedence_table(rows: readonly OverrideRow[]): string {
+    const L: string[] = [];
+    L.push('<!-- evidence-type: analysis -->');
+    L.push('');
+    L.push('<!-- GENERATED by `lint_override_kernel_guard --write-table`. Do not hand-edit. -->');
+    L.push('');
+    L.push('# Override precedence table');
+    L.push('');
+    L.push(
+        'Every override in the tree, with the rule it overrides and its audit state. ' +
+            'Generated from the same `audit()` the strict gate runs, so the table and the ' +
+            'gate cannot disagree.',
+    );
+    L.push('');
+    L.push(
+        '**This is a DELIVERY table, not an efficacy claim.** It says an override file ' +
+            'is discovered, resolves to a rule, and carries its citation. Whether the agent ' +
+            'then behaves differently is a separate question, and it is measured nowhere in ' +
+            'this table — see `road-to-override-efficacy-proof` Phase 2, deferred on ' +
+            'population validity.',
+    );
+    L.push('');
+    if (rows.length === 0) {
+        L.push('No override files are present. That is a real and common state, not a fault.');
+        L.push('');
+        return L.join('\n');
+    }
+    L.push('| rule | mode | kernel | safety floor | registered | cited | violations |');
+    L.push('|---|---|---|---|---|---|---|');
+    for (const r of rows) {
+        L.push(
+            `| \`${r.rule}\` | \`${r.mode}\` | ${r.kernel ? 'yes' : 'no'} | ` +
+                `${r.safety_floor ? 'yes' : 'no'} | ${r.registered ? 'yes' : 'no'} | ` +
+                `${r.cited ? 'yes' : 'no'} | ${r.violations.length === 0 ? '—' : r.violations.join('; ')} |`,
+        );
+    }
+    L.push('');
+    L.push(`${String(rows.length)} override(s).`);
+    L.push('');
+    return L.join('\n');
+}
+
 function main(argv: string[]): number {
     const as_json = argv.includes('--json');
     const strict = argv.includes('--strict');
+    const tableIdx = argv.indexOf('--write-table');
 
     // Not the override corpus: an empty `agents/overrides/rules/` is a real and
     // common state (the report says so in words). The scope that cannot be
@@ -252,6 +319,21 @@ function main(argv: string[]): number {
 
     const rows = audit();
 
+    if (tableIdx >= 0) {
+        const rel = argv[tableIdx + 1];
+        if (rel === undefined || rel.startsWith('--')) {
+            process.stderr.write('--write-table needs a path\n');
+            return 2;
+        }
+        const out = path.join(REPO_ROOT, rel);
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(out, render_precedence_table(rows), 'utf-8');
+        process.stdout.write(
+            `override precedence table: ${String(rows.length)} row(s) → ${rel}\n`,
+        );
+        return 0;
+    }
+
     if (as_json) {
         process.stdout.write(JSON.stringify({ overrides: rows }, null, 2) + '\n');
         return 0;