@event4u/agent-config 9.8.0 → 9.9.0

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)));
+}

package/src/scripts/lint_pre_migration_refs.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env tsx
+/**
+ * lint_pre_migration_refs — no pre-migration install hints in shipped files.
+ *
+ * road-to-credible-install Phase 0 (doc-rot sweep): the 9.8.0 external review
+ * found live docs still instructing consumers to run the retired Python
+ * installer (`scripts/install.py`, deleted in ADR-200) and to
+ * `pip install agent-config[mcp]`. This lint pins the count at zero and
+ * keeps it there.
+ *
+ * Scope: every git-tracked file covered by the package.json `files`
+ * whitelist (the published surface), because that is exactly what an
+ * external evaluator reads.
+ *
+ * Patterns (instructional hints only — NOT every mention of the string;
+ * legacy-install *detection/cleanup* code legitimately names old artifacts):
+ *   - `pip install agent-config`            (any variant)
+ *   - `python[3] ... install.py`            (a runnable command)
+ *   - backtick-quoted `scripts/install.py`  (presented as a current path)
+ *   - `python -m scripts.mcp_server`        (retired Python MCP entry)
+ *
+ * Carve-outs (historical records, allowed to name retired things):
+ *   - CHANGELOG.md, MIGRATION.md
+ *   - this lint itself
+ *
+ * Exit codes: 0 clean · 1 findings · 2 internal error.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+
+const PATTERNS: readonly { re: RegExp; label: string }[] = [
+    { re: /pip install agent-config/, label: 'pip install hint (Python package retired, ADR-200)' },
+    { re: /python3?\s+\S*install\.py\b/, label: 'python install.py invocation (retired, ADR-200)' },
+    { re: /`scripts\/install\.py`/, label: 'scripts/install.py cited as a current path (retired, ADR-200)' },
+    { re: /python3?\s+-m\s+scripts\.mcp_server/, label: 'python -m scripts.mcp_server (retired MCP entry, ADR-200)' },
+];
+
+const CARVE_OUTS = new Set(['CHANGELOG.md', 'MIGRATION.md', 'src/scripts/lint_pre_migration_refs.ts']);
+
+/** Binary-ish extensions we never scan. */
+const SKIP_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.wasm', '.zip', '.gz', '.pdf']);
+
+function shippedTrackedFiles(): string[] {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf-8')) as {
+        files?: string[];
+    };
+    const files = pkg.files ?? [];
+    const prefixes = files.filter((f) => f.endsWith('/')).map((f) => f.replace(/\/+$/, '') + '/');
+    const exact = new Set(files.filter((f) => !f.endsWith('/')));
+    const tracked = execFileSync('git', ['ls-files'], { cwd: REPO_ROOT, encoding: 'utf-8' })
+        .split('\n')
+        .filter(Boolean);
+    return tracked.filter((t) => exact.has(t) || prefixes.some((p) => t.startsWith(p)));
+}
+
+export function scanText(relPath: string, text: string): string[] {
+    const findings: string[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        for (const { re, label } of PATTERNS) {
+            if (re.test(lines[i] as string)) {
+                findings.push(`${relPath}:${i + 1}: ${label}`);
+            }
+        }
+    }
+    return findings;
+}
+
+export function main(): number {
+    const findings: string[] = [];
+    for (const rel of shippedTrackedFiles()) {
+        if (CARVE_OUTS.has(rel)) continue;
+        if (SKIP_EXT.has(path.extname(rel))) continue;
+        const abs = path.join(REPO_ROOT, rel);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+        let text: string;
+        try {
+            text = fs.readFileSync(abs, 'utf-8');
+        } catch {
+            continue;
+        }
+        findings.push(...scanText(rel, text));
+    }
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  pre-migration reference: ${f}\n`);
+        }
+        process.stderr.write(
+            `\n${findings.length} pre-migration reference(s) in shipped files. ` +
+                'The Python installer / pip package is retired (ADR-200) — update the hint ' +
+                'to the TypeScript path (scripts/install.ts, `npx -y @event4u/agent-config …`).\n',
+        );
+        return 1;
+    }
+    process.stdout.write('✅  no pre-migration install hints in shipped files\n');
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}