@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/lint_load_context.ts

@@ -36,9 +36,15 @@ const QUIET = process.argv.slice(2).includes('--quiet');
 // src/scripts/lint_load_context.ts → three dirs up is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
+// Retargeted 2026-07-29: the first two pointed at the ADR-051-emptied tree, so
+// this gate reported "clean (0 declarer(s))" in CI — the count was in its own
+// output the whole time. `agents/contexts` does not exist either (project-local
+// contexts live under agents/settings/contexts) and is kept only as a no-op for
+// consumer layouts that do have it.
 const SCAN_DIRS = [
-    path.join(ROOT, '.agent-src.uncondensed', 'rules'),
-    path.join(ROOT, '.agent-src.uncondensed', 'contexts'),
+    path.join(ROOT, 'src', 'rules'),
+    path.join(ROOT, 'src', 'agent-src', 'contexts'),
+    path.join(ROOT, 'agents', 'settings', 'contexts'),
     path.join(ROOT, 'agents', 'contexts'),
 ];
 
@@ -50,9 +56,10 @@ const ALLOWED_PREFIXES = [
 
 const LEGACY_PREFIX = '.agent-src.uncondensed/contexts/';
 
-const SOURCE_ROOT = path.join(ROOT, '.agent-src.uncondensed');
+// Base for resolving a logical `contexts/...` entry to a real file.
+const SOURCE_ROOT = path.join(ROOT, 'src', 'agent-src');
 
-const PUBLIC_RULE_PREFIX = '.agent-src.uncondensed/rules/';
+const PUBLIC_RULE_PREFIX = 'src/rules/';
 const PROJECT_LOCAL_PREFIX = 'agents/settings/contexts/';
 
 const HARD_FLOOR_RULES: ReadonlySet<string> = new Set([
@@ -217,7 +224,12 @@ function main(): number {
     const warnings: string[] = [];
     const graph: Record<string, string[]> = {};
 
-    for (const f of collect_files()) {
+    const _files = collect_files();
+    // Gate-coverage contract (src/config/gate-coverage.yml): count FILES INSPECTED,
+    // not declarers — "0 declarers" over 400 files is a legitimate result, "0 files"
+    // is blindness. Reporting declarers here would have hidden the dead root.
+    process.stdout.write(`scanned: ${String(_files.length)}\n`);
+    for (const f of _files) {
         const fm = parse_frontmatter(f);
         const lazyRaw = fm['load_context'];
         const eagerRaw = fm['load_context_eager'];

package/src/scripts/lint_mcp_registry_manifest.ts

@@ -33,6 +33,8 @@ const SCHEMA = path.join(ROOT, 'docs', 'contracts', 'mcp-registry-manifest.schem
 const MANIFEST = path.join(ROOT, 'dist', 'mcp', 'registry-manifest.json');
 const ROW_MD = path.join(ROOT, 'dist', 'mcp', 'awesome-mcp-servers.row.md');
 const CF_JSON = path.join(ROOT, 'dist', 'mcp', 'mcp-cloudflare-catalogue.json');
+const SERVER_JSON = path.join(ROOT, 'dist', 'mcp', 'server.json');
+const PKG_FILE = path.join(ROOT, 'package.json');
 
 function _relToRoot(p: string): string {
     return path.relative(ROOT, p);
@@ -293,7 +295,7 @@ function main(argv: readonly string[]): number {
         throw e;
     }
 
-    for (const p of [SCHEMA, MANIFEST, ROW_MD, CF_JSON]) {
+    for (const p of [SCHEMA, MANIFEST, ROW_MD, CF_JSON, SERVER_JSON]) {
         if (!fs.existsSync(p)) {
             return _fail(`missing: ${_relToRoot(p)}`);
         }
@@ -324,6 +326,29 @@ function main(argv: readonly string[]): number {
         return _fail(`mcp-cloudflare-catalogue.json: ${(e as Error).message}`);
     }
 
+    // Official-registry payload (road-to-credible-install Phase 3): valid
+    // JSON, reverse-DNS name matching package.json `mcpName`, and version
+    // equal to package.json.version (the CI version-equality gate).
+    let server_payload: JsonObject;
+    try {
+        server_payload = JSON.parse(fs.readFileSync(SERVER_JSON, 'utf-8')) as JsonObject;
+    } catch (e) {
+        return _fail(`server.json: ${(e as Error).message}`);
+    }
+    const pkg_for_gate = JSON.parse(fs.readFileSync(PKG_FILE, 'utf-8')) as JsonObject;
+    if (server_payload['version'] !== pkg_for_gate['version']) {
+        return _fail(
+            `server.json version (${String(server_payload['version'])}) != package.json version ` +
+                `(${String(pkg_for_gate['version'])}) — re-run build:mcp-manifest`,
+        );
+    }
+    if (server_payload['name'] !== pkg_for_gate['mcpName']) {
+        return _fail(
+            `server.json name (${String(server_payload['name'])}) != package.json mcpName ` +
+                `(${String(pkg_for_gate['mcpName'])})`,
+        );
+    }
+
     if (!args.quiet) {
         const registries = (manifest as JsonObject)['registries'];
         const count = Array.isArray(registries) ? registries.length : 0;

package/src/scripts/lint_memory_tripwire.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Personal-context tripwire over TRACKED memory files — invariant 3 of
+ * ADR-130 (`subject` axis, road-to-reachable-code-memory Phase 8).
+ *
+ * Hand-authored first-person / preference vocabulary (DE+EN) that indicates
+ * a `subject: user` record leaked into a tracked project artifact. On a hit
+ * it HALTS (exit 1) and NEVER rewrites — a human decides.
+ *
+ * ── Honest-null verdict (pre-registered in the roadmap, applied 2026-07-27):
+ * `--history` scanned the FULL git history of agents/memory/** at cut time —
+ * see the run record in agents/evidence/reports/spike-reachable-code-memory-s0.md.
+ * Per the pre-registration, ZERO fires across the full history means
+ * invariant 3 is UNFOUNDED: this script is retained as evidence + an
+ * on-demand tool, but it is deliberately NOT wired into CI; invariants 1–2
+ * (structural: lint_store_boundary + the memory_signal provenance gate)
+ * carry the boundary. A non-zero history result at cut time would have
+ * wired it as a vitest gate instead.
+ *
+ * Exit codes: 0 clean · 1 hits · 2 usage · 3 internal.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Tracked memory surfaces the tripwire watches. */
+export const TRACKED_GLOB_ROOT = 'agents/memory';
+
+/**
+ * Hand-authored personal-context vocabulary, DE+EN. Deliberately narrow:
+ * first-person preference/identity statements — not every "I" (change-log
+ * prose like "I/O" or quoted user feedback in an incident record must not
+ * trip). Word-boundary anchored; case-insensitive.
+ */
+export const TRIPWIRE_PATTERNS: readonly RegExp[] = [
+    // EN — first-person preference / identity
+    /\bI (?:prefer|like|dislike|hate|want|always use|never use)\b/i,
+    /\bmy (?:name|email|address|phone|password|birthday|salary)\b/i,
+    /\bcall me\b/i,
+    // DE — first-person preference / identity (Du-form package: user prose)
+    /\bich (?:bevorzuge|mag|hasse|will|möchte|nutze immer|nutze nie)\b/i,
+    /\bmein[e]? (?:name|e-?mail|adresse|telefonnummer|passwort|geburtstag|gehalt)\b/i,
+    /\bnenn mich\b/i,
+];
+
+export interface Hit {
+    file: string;
+    line: number;
+    pattern: string;
+    /** commit sha for --history hits; 'worktree' otherwise. */
+    ref: string;
+}
+
+export function scanText(text: string, file: string, ref: string): Hit[] {
+    const hits: Hit[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        for (const re of TRIPWIRE_PATTERNS) {
+            if (re.test(lines[i]!)) {
+                hits.push({ file, line: i + 1, pattern: re.source, ref });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+
+function _git(root: string, args: string[]): string {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** Scan the current worktree's tracked memory files. */
+export function scanWorktree(root: string): Hit[] {
+    const out: Hit[] = [];
+    let files: string[];
+    try {
+        files = _git(root, ['ls-files', TRACKED_GLOB_ROOT]).split('\n').filter(Boolean);
+    } catch {
+        return out;
+    }
+    for (const f of files) {
+        const p = path.join(root, f);
+        if (!fs.existsSync(p)) continue;
+        out.push(...scanText(fs.readFileSync(p, 'utf8'), f, 'worktree'));
+    }
+    return out;
+}
+
+/** Scan EVERY historical version of every tracked memory file (all commits). */
+export function scanHistory(root: string): { hits: Hit[]; commits: number; blobs: number } {
+    const shas = _git(root, ['log', '--all', '--pretty=%H', '--', TRACKED_GLOB_ROOT])
+        .split('\n')
+        .filter(Boolean);
+    const hits: Hit[] = [];
+    const seenBlobs = new Set<string>();
+    let blobs = 0;
+    for (const sha of shas) {
+        let listing: string;
+        try {
+            listing = _git(root, ['ls-tree', '-r', sha, '--', TRACKED_GLOB_ROOT]);
+        } catch {
+            continue;
+        }
+        for (const row of listing.split('\n').filter(Boolean)) {
+            // <mode> blob <hash>\t<path>
+            const m = /^\d+ blob ([0-9a-f]+)\t(.+)$/.exec(row);
+            if (!m) continue;
+            const [, blob, file] = m;
+            if (seenBlobs.has(blob!)) continue;
+            seenBlobs.add(blob!);
+            blobs++;
+            let content: string;
+            try {
+                content = _git(root, ['cat-file', 'blob', blob!]);
+            } catch {
+                continue;
+            }
+            hits.push(...scanText(content, file!, sha.slice(0, 10)));
+        }
+    }
+    return { hits, commits: shas.length, blobs };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let root = REPO_ROOT;
+    let history = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i]!;
+        if (a === '--root') root = argv[++i] ?? root;
+        else if (a.startsWith('--root=')) root = a.slice('--root='.length);
+        else if (a === '--history') history = true;
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_memory_tripwire [--root ROOT] [--history]\n');
+            return 0;
+        } else {
+            process.stderr.write(`lint_memory_tripwire: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+    try {
+        if (history) {
+            const { hits, commits, blobs } = scanHistory(root);
+            process.stdout.write(
+                `scanned ${commits} commit(s), ${blobs} unique blob(s) under ${TRACKED_GLOB_ROOT}\n`,
+            );
+            if (hits.length === 0) {
+                process.stdout.write('✅  zero tripwire fires across the full history.\n');
+                return 0;
+            }
+            for (const h of hits) {
+                process.stdout.write(`  🔴 ${h.ref} ${h.file}:${h.line}  (pattern: ${h.pattern})\n`);
+            }
+            process.stdout.write(`❌  ${hits.length} fire(s). HALT — never rewrite; a human decides.\n`);
+            return 1;
+        }
+        const hits = scanWorktree(root);
+        if (hits.length === 0) {
+            process.stdout.write('✅  tripwire clean on tracked memory files.\n');
+            return 0;
+        }
+        for (const h of hits) {
+            process.stdout.write(`  🔴 ${h.file}:${h.line}  (pattern: ${h.pattern})\n`);
+        }
+        process.stdout.write(`❌  ${hits.length} fire(s). HALT — never rewrite; a human decides.\n`);
+        return 1;
+    } catch (exc) {
+        process.stderr.write(`lint_memory_tripwire: internal error: ${String(exc)}\n`);
+        return 3;
+    }
+}
+
+const _isMain = (() => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return pathToFileURL(fs.realpathSync(path.resolve(process.argv[1]))).href === import.meta.url;
+    } catch {
+        return pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+    }
+})();
+if (_isMain) {
+    process.exit(main());
+}

package/src/scripts/lint_new_skill_gate.ts

@@ -105,9 +105,15 @@ function _skill_roots(): string[] {
             }
         }
     }
-    const legacy = path.join(ROOT, '.agent-src.uncondensed', 'skills');
-    if (roots.length === 0 && _isDir(legacy)) {
-        roots = [legacy];
+    // ADR-051 moved skill authoring to `src/skills`; a later commit deleted
+    // `packages/` entirely. Until 2026-07-29 the only fallback was the retired
+    // container, so this resolved to [] and the overlap gate silently passed
+    // every new skill.
+    if (roots.length === 0) {
+        const cand = path.join(ROOT, 'src', 'skills');
+        if (_isDir(cand)) {
+            roots = [cand];
+        }
     }
     return roots;
 }

package/src/scripts/lint_no_python_twin_rationale.ts

@@ -26,9 +26,24 @@ const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const SCOPE = path.join(ROOT, 'src', 'scripts');
 
-/** Banned rationale shapes (case-insensitive). */
+/**
+ * Banned rationale shapes (case-insensitive).
+ *
+ * `twin-of` is qualified with a Python signal on purpose. The bare `/\btwin of\b/`
+ * it replaced banned an English word rather than a claim shape, and produced 6 false
+ * positives out of 7 findings: a CLI twin of an MCP tool, a sync twin of an async
+ * probe in the same file, a debate twin of a sibling function, a SQLite twin of a
+ * JSON cache. None of those rationalise anything by fidelity to a deleted Python
+ * original — which is the only thing this gate exists to stop — and rewording correct
+ * comments to dodge a word would have been the tail wagging the dog.
+ *
+ * The narrowing does not weaken the gate: every shape it targets names Python by
+ * construction ("TypeScript twin of the Python original", "twin of the retired
+ * .py"), so the qualifier is satisfied precisely when the claim is the banned one.
+ * The other three patterns already carry their own Python signal.
+ */
 export const BANNED: ReadonlyArray<[string, RegExp]> = [
-    ['twin-of', /\btwin of\b/i],
+    ['twin-of', /\btwin of\b[^\n]*\b(?:python|py2ts|\.py)\b|\b(?:python|py2ts|\.py)\b[^\n]*\btwin of\b/i],
     ['latent-quirks', /latent (?:python )?(?:quirks|bugs) replicated/i],
     ['byte-identical-python', /byte-identical to the python/i],
     ['python-original', /\bthe python original\b/i],

package/src/scripts/lint_originality.ts

@@ -373,7 +373,7 @@ function _changed(files: string[]): { pairs: Pair[]; fails: number } {
     const seen = new Set<string>();
     const record = (a: Artifact, b: Artifact): void => {
         if (a.relpath === b.relpath) return;
-        const key = [a.relpath, b.relpath].sort().join('');
+        const key = [a.relpath, b.relpath].sort().join('\0');
         if (seen.has(key)) return;
         const o = overlap(a, b);
         if (o >= WARN) {

package/src/scripts/lint_override_kernel_guard.ts

@@ -26,6 +26,14 @@
  * everything above" passes this check. No linter reads intent. The registry
  * entry is where a human records it, and the report is what makes it reviewable.
  *
+ * The citation obligation (override-system.md § Citation obligation) binds
+ * every override file, not only kernel/safety-floor ones — until now that was
+ * doc-contract-only for ordinary overrides. This guard now also scans ordinary
+ * (non-kernel, non-safety-floor) override files and raises a `missing-citation`
+ * finding when the `> Overrides: <rule> §<section> — <reason>` line is absent.
+ * The non-overridable-class checks (replace-on-kernel, unregistered-extend)
+ * still apply only to kernel/safety-floor files, unchanged.
+ *
  * Usage:
  *   ./scripts-run src/scripts/lint_override_kernel_guard            # report
  *   ./scripts-run src/scripts/lint_override_kernel_guard --json
@@ -101,27 +109,30 @@ export function registered_rules(text: string): Set<string> {
     return out;
 }
 
-export function audit(): OverrideRow[] {
-    if (!fs.existsSync(OVERRIDES_RULES)) 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()) {
-        if (!name.endsWith('.md')) continue;
-        const rule = name.replace(/\.md$/, '');
-        const kernel = is_kernel_rule(rule);
-        const is_floor = floor.has(rule);
-        if (!kernel && !is_floor) continue; // ordinary override — not this gate's business
-
-        const text = fs.readFileSync(path.join(OVERRIDES_RULES, name), 'utf-8');
-        const mode = parse_mode(text);
-        const cited = has_citation(text);
-        const is_registered = registered.has(rule);
+/**
+ * Violations for one override file.
+ *
+ * Kernel / safety-floor files get the full non-overridable-class check
+ * (unchanged from before this file gained an ordinary-override path): a
+ * `replace` is refused, an undeclared mode is refused, and an unregistered
+ * `extend` is refused — each in addition to the citation check every override
+ * carries.
+ *
+ * An ordinary override gets only the citation check — the non-overridable
+ * class does not apply to it — surfaced as the `missing-citation` finding
+ * class per override-system.md § Citation obligation.
+ */
+export function classify_violations(input: {
+    kernel: boolean;
+    is_floor: boolean;
+    mode: 'extend' | 'replace' | 'unknown';
+    cited: boolean;
+    is_registered: boolean;
+}): string[] {
+    const { kernel, is_floor, mode, cited, is_registered } = input;
+    const violations: string[] = [];
 
-        const violations: string[] = [];
+    if (kernel || is_floor) {
         if (mode === 'replace') {
             violations.push(
                 `\`replace\` on a ${kernel ? 'kernel' : 'safety-floor'} rule — this class may be tightened, never replaced`,
@@ -140,6 +151,39 @@ export function audit(): OverrideRow[] {
         if (!cited) {
             violations.push('missing `> Overrides: <rule> §<section> — <reason>` citation');
         }
+        return violations;
+    }
+
+    // Ordinary override — not the non-overridable class, but the citation
+    // obligation binds it too (override-system.md § Citation obligation).
+    if (!cited) {
+        violations.push(
+            'missing-citation: no `> Overrides: <rule> §<section> — <reason>` line ' +
+                '(override-system.md § Citation obligation)',
+        );
+    }
+    return violations;
+}
+
+export function audit(): OverrideRow[] {
+    if (!fs.existsSync(OVERRIDES_RULES)) 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()) {
+        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 mode = parse_mode(text);
+        const cited = has_citation(text);
+        const is_registered = registered.has(rule);
+        const violations = classify_violations({ kernel, is_floor, mode, cited, is_registered });
 
         rows.push({
             rule,
@@ -161,7 +205,7 @@ function main(argv: string[]): number {
     const rows = audit();
 
     if (as_json) {
-        process.stdout.write(JSON.stringify({ kernel_overrides: rows }, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ overrides: rows }, null, 2) + '\n');
         return 0;
     }
 
@@ -169,19 +213,23 @@ function main(argv: string[]): number {
 
     if (rows.length === 0) {
         process.stdout.write(
-            `✅  override audit: 0 kernel / safety-floor overrides present ` +
+            `✅  override audit: 0 overrides present ` +
                 `(${KERNEL_RULE_IDS.length} kernel rules, none overridden)\n`,
         );
         return 0;
     }
 
+    const kernel_floor_rows = rows.filter((r) => r.kernel || r.safety_floor);
+    const ordinary_rows = rows.filter((r) => !r.kernel && !r.safety_floor);
+
     const lines: string[] = [];
     lines.push(
-        `override audit: ${rows.length} kernel / safety-floor override(s) · ` +
-            `${rows.filter((r) => r.registered).length} registered · ${bad.length} with findings`,
+        `override audit: ${rows.length} override(s) — ${kernel_floor_rows.length} kernel/safety-floor ` +
+            `(${rows.filter((r) => r.registered).length} registered), ${ordinary_rows.length} ordinary · ` +
+            `${bad.length} with findings`,
     );
     for (const r of rows) {
-        const tag = r.kernel ? 'kernel' : 'safety-floor';
+        const tag = r.kernel ? 'kernel' : r.safety_floor ? 'safety-floor' : 'ordinary';
         lines.push(`  · ${r.rule} [${tag}] mode=${r.mode} registered=${r.registered ? 'yes' : 'NO'}`);
         for (const v of r.violations) lines.push(`      ❌ ${v}`);
     }
@@ -195,7 +243,7 @@ function main(argv: string[]): number {
 
     if (strict && bad.length > 0) {
         process.stderr.write(
-            `❌  lint_override_kernel_guard: ${bad.length} override(s) violate the non-overridable class\n`,
+            `❌  lint_override_kernel_guard: ${bad.length} override(s) violate the override contract\n`,
         );
         return 1;
     }

package/src/scripts/lint_persistence.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env tsx
+/**
+ * lint_persistence — deterministic persistence-lint substrate for the
+ * scale-discipline / history-discipline packs
+ * (road-to-scale-and-history-discipline; spike verdicts:
+ * docs/spikes/scale-history-spikes.md).
+ *
+ * Adapters:
+ *   raw-sql   — R-A6 migration-safety (F6) + R-A7 growth-budget (F7)
+ *   eloquent  — R-A1 N+1 (F1), R-A2 index-parity (F2), R-A8/R-A10
+ *               offload + durable-async (F9/F11), R-B1 audit-coverage (F8,
+ *               only when an audit-scope file is present)
+ *   prisma    — R-A2 index-parity (F2) over schema.prisma + client queries
+ *
+ * "Deterministic" = deterministic pattern detection with an auditable waiver
+ * process; `advice`-tier findings never fail the run. Waivers with empty
+ * reason text are hygiene errors.
+ *
+ * Usage:
+ *   lint_persistence --dir <path> [--stack raw-sql|eloquent|prisma]...
+ *                    [--audit-scope <file.json>] [--format json|text]
+ *                    [--quiet]
+ *
+ * Exit codes: 0 no gate findings · 1 gate findings (or empty-reason waivers)
+ * · 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { Finding, WaiverRecord } from './_lib/persistence/types.js';
+import { scan_dir as scan_sql_dir } from './_lib/persistence/adapter_raw_sql.js';
+import { scan_dir as scan_n1_dir } from './_lib/persistence/detect_n1_eloquent.js';
+import { analyze as analyze_index_parity } from './_lib/persistence/detect_index_parity.js';
+import { scan_dir as scan_offload_dir } from './_lib/persistence/detect_offload.js';
+import { analyze_repo as analyze_audit } from './_lib/persistence/detect_audit_coverage.js';
+import { scan_dir as scan_bounded_dir } from './_lib/persistence/detect_bounded_reads.js';
+import { scan_dir as scan_prisma_growth_dir } from './_lib/persistence/detect_prisma_growth.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+export type StackId = 'raw-sql' | 'eloquent' | 'prisma';
+
+export interface LintReport {
+    findings: Finding[];
+    gate_count: number;
+    advice_count: number;
+    waived_count: number;
+    empty_reason_waivers: WaiverRecord[];
+    stacks: StackId[];
+}
+
+export function detect_stacks(dir: string): StackId[] {
+    const stacks = new Set<StackId>();
+    const walk = (d: string, depth: number): void => {
+        if (depth > 6) return;
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            if (e.name === 'node_modules' || e.name === 'vendor' || e.name.startsWith('.')) continue;
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) walk(p, depth + 1);
+            else if (e.name.endsWith('.sql')) stacks.add('raw-sql');
+            else if (e.name === 'schema.prisma') stacks.add('prisma');
+            else if (e.name.endsWith('.php')) stacks.add('eloquent');
+        }
+    };
+    walk(dir, 0);
+    return [...stacks];
+}
+
+export function run_lint(dir: string, stacks: StackId[], audit_scope_file?: string): LintReport {
+    const findings: Finding[] = [];
+    const empty_reason_waivers: WaiverRecord[] = [];
+
+    for (const stack of stacks) {
+        if (stack === 'raw-sql') {
+            const res = scan_sql_dir(dir);
+            findings.push(...res.findings);
+            empty_reason_waivers.push(...res.waivers.filter((w) => w.reason === ''));
+        } else if (stack === 'eloquent') {
+            findings.push(...scan_n1_dir(dir));
+            findings.push(...analyze_index_parity(dir).findings);
+            findings.push(...scan_offload_dir(dir, 'eloquent'));
+            findings.push(...scan_bounded_dir(dir));
+            const scope_file = audit_scope_file ?? path.join(dir, 'audit-scope.json');
+            if (fs.existsSync(scope_file)) {
+                const scope = JSON.parse(fs.readFileSync(scope_file, 'utf8'));
+                findings.push(...analyze_audit(dir, scope).findings);
+            }
+        } else if (stack === 'prisma') {
+            findings.push(...analyze_index_parity(dir).findings);
+            findings.push(...scan_offload_dir(dir, 'ts'));
+            findings.push(...scan_prisma_growth_dir(dir));
+        }
+    }
+
+    const active = findings.filter((f) => !f.waived);
+    return {
+        findings,
+        gate_count: active.filter((f) => f.tier === 'gate').length,
+        advice_count: active.filter((f) => f.tier === 'advice').length,
+        waived_count: findings.filter((f) => f.waived).length,
+        empty_reason_waivers,
+        stacks,
+    };
+}
+
+function format_text(report: LintReport): string {
+    const lines: string[] = [];
+    for (const f of report.findings) {
+        const mark = f.waived ? 'waived' : f.tier;
+        lines.push(`${f.file}:${f.line} [${f.rule}/${mark}] ${f.message}`);
+    }
+    for (const w of report.empty_reason_waivers) {
+        lines.push(`${w.file}:${w.line} [waiver-hygiene/gate] empty ${w.kind} waiver reason — a waiver must say why`);
+    }
+    lines.push(
+        `${report.gate_count} gate · ${report.advice_count} advice · ${report.waived_count} waived · stacks: ${report.stacks.join(', ') || 'none'}`,
+    );
+    return lines.join('\n') + '\n';
+}
+
+function main(argv: string[]): number {
+    let dir = '';
+    const stacks: StackId[] = [];
+    let audit_scope: string | undefined;
+    let format = 'text';
+    let quiet = false;
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--dir') dir = argv[++i] ?? '';
+        else if (a === '--stack') {
+            const s = argv[++i] as StackId;
+            if (!['raw-sql', 'eloquent', 'prisma'].includes(s)) {
+                process.stderr.write(`❌  unknown stack: ${s}\n`);
+                return 2;
+            }
+            stacks.push(s);
+        } else if (a === '--audit-scope') audit_scope = argv[++i];
+        else if (a === '--format') format = argv[++i] ?? 'text';
+        else if (a === '--quiet') quiet = true;
+        else {
+            process.stderr.write(`❌  unknown argument: ${a}\n`);
+            return 2;
+        }
+    }
+    if (!dir || !fs.existsSync(dir)) {
+        process.stderr.write('❌  --dir <path> is required and must exist\n');
+        return 2;
+    }
+
+    const resolved_stacks = stacks.length > 0 ? stacks : detect_stacks(dir);
+    const report = run_lint(dir, resolved_stacks, audit_scope);
+
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else if (!quiet || report.gate_count > 0 || report.empty_reason_waivers.length > 0) {
+        process.stdout.write(format_text(report));
+    }
+
+    const failed = report.gate_count > 0 || report.empty_reason_waivers.length > 0;
+    if (!failed && !quiet && format !== 'json') {
+        process.stdout.write('✅  lint_persistence: no gate findings\n');
+    }
+    return failed ? 1 : 0;
+}
+
+const isMain = process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_HERE);
+if (isMain) {
+    process.exit(main(process.argv.slice(2)));
+}