@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/lint_override_kernel_guard.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env tsx
+/**
+ * Override audit — kernel-rule overrides, reported rather than policed.
+ *
+ * The obvious design for this file was a build-failing lint on any kernel-named
+ * file under `agents/overrides/rules/`. The council talked us out of it, and the
+ * argument holds: the override layer is resolved by the *agent reading the
+ * instructions*, not by a loader, so a consumer who wants a kernel rule relaxed
+ * has other routes — a persona file, host-level agent config, a line in the
+ * prompt. Failing the build on route one does not shrink that surface; it moves
+ * the override to a route with no visibility at all, while the red X reads as
+ * coverage. That is the exact "claims enforcement it does not have" defect this
+ * whole roadmap exists to remove, pointed at ourselves.
+ *
+ * So the default output is a REPORT. A consumer reading "0 kernel overrides" or
+ * "2 kernel overrides, both registered" learns something true.
+ *
+ * Two things do hard-fail, because on our own authoring surface the coverage
+ * claim IS true:
+ *   1. a `Mode: replace` override on a kernel / safety-floor rule — the class is
+ *      non-replaceable, and this is mechanically decidable from the header;
+ *   2. an `extend` on one with no entry in `agents/overrides/kernel-exceptions.yml`
+ *      — tightening is allowed, going unrecorded is not.
+ *
+ * Honest limit, stated in-band: an `extend` block whose prose says "ignore
+ * 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
+ *   ./scripts-run src/scripts/lint_override_kernel_guard --strict   # + hard-fails
+ *
+ * Exit codes: 0 clean · 1 violation (--strict) · 2 usage/env error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { KERNEL_RULE_IDS, is_kernel_rule } from './_lib/kernel_rules.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const OVERRIDES_RULES = path.join(REPO_ROOT, 'agents', 'overrides', 'rules');
+const REGISTRY = path.join(REPO_ROOT, 'agents', 'overrides', 'kernel-exceptions.yml');
+const RULES_DIR = path.join(REPO_ROOT, 'src', 'rules');
+
+export interface OverrideRow {
+    rule: string;
+    file: string;
+    mode: 'extend' | 'replace' | 'unknown';
+    kernel: boolean;
+    safety_floor: boolean;
+    registered: boolean;
+    cited: boolean;
+    violations: string[];
+}
+
+/** `**Mode:** \`extend\`` — the header form the override contract specifies. */
+export function parse_mode(text: string): 'extend' | 'replace' | 'unknown' {
+    const m = /^\s*\*\*Mode:\*\*\s*`?(extend|replace)`?\s*$/im.exec(text);
+    return m ? (m[1] as 'extend' | 'replace') : 'unknown';
+}
+
+/** `> Overrides: <rule> §<section> — <reason>` — the citation obligation. */
+export function has_citation(text: string): boolean {
+    return /^>\s*Overrides:\s*\S+.*—.+$/im.test(text);
+}
+
+/** Rule ids carrying `tier: safety-floor`, read from the rule sources. */
+export function safety_floor_ids(rules_dir: string): Set<string> {
+    const out = new Set<string>();
+    if (!fs.existsSync(rules_dir)) return out;
+    for (const name of fs.readdirSync(rules_dir)) {
+        if (!name.endsWith('.md')) continue;
+        const head = fs.readFileSync(path.join(rules_dir, name), 'utf-8').slice(0, 2000);
+        if (/^tier:\s*"?safety-floor"?\s*$/im.test(head)) out.add(name.replace(/\.md$/, ''));
+    }
+    return out;
+}
+
+/**
+ * Rule ids with a registered exception.
+ *
+ * Narrow reader, not a YAML dependency: the registry is a fixed two-level shape
+ * and the only fact needed is which rules appear under `exceptions:`. Anything
+ * more permissive would let a malformed registry read as coverage.
+ */
+export function registered_rules(text: string): Set<string> {
+    const out = new Set<string>();
+    let in_exceptions = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (/^exceptions:\s*$/.test(line)) { in_exceptions = true; continue; }
+        if (!in_exceptions) continue;
+        if (/^\S/.test(line)) break;
+        const rule_name = /^\s*-?\s*rule:\s*"?([a-z0-9-]+)"?\s*$/i.exec(line)?.[1];
+        if (rule_name !== undefined) out.add(rule_name);
+    }
+    return out;
+}
+
+/**
+ * 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[] = [];
+
+    if (kernel || is_floor) {
+        if (mode === 'replace') {
+            violations.push(
+                `\`replace\` on a ${kernel ? 'kernel' : 'safety-floor'} rule — this class may be tightened, never replaced`,
+            );
+        }
+        if (mode === 'unknown') {
+            violations.push(
+                'no readable `**Mode:**` header — an override on this class must declare its mode',
+            );
+        }
+        if (mode === 'extend' && !is_registered) {
+            violations.push(
+                `\`extend\` on a ${kernel ? 'kernel' : 'safety-floor'} rule with no entry in agents/overrides/kernel-exceptions.yml`,
+            );
+        }
+        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,
+            file: path.relative(REPO_ROOT, path.join(OVERRIDES_RULES, name)),
+            mode,
+            kernel,
+            safety_floor: is_floor,
+            registered: is_registered,
+            cited,
+            violations,
+        });
+    }
+    return rows;
+}
+
+function main(argv: string[]): number {
+    const as_json = argv.includes('--json');
+    const strict = argv.includes('--strict');
+    const rows = audit();
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ overrides: rows }, null, 2) + '\n');
+        return 0;
+    }
+
+    const bad = rows.filter((r) => r.violations.length > 0);
+
+    if (rows.length === 0) {
+        process.stdout.write(
+            `✅  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} 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' : 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}`);
+    }
+    lines.push('');
+    lines.push(
+        '  Limit: this audits files under agents/overrides/. A rule can also be ' +
+            'relaxed through a persona, host config, or a direct instruction — ' +
+            'those routes are not visible here and are not claimed to be covered.',
+    );
+    process.stdout.write(lines.join('\n') + '\n');
+
+    if (strict && bad.length > 0) {
+        process.stderr.write(
+            `❌  lint_override_kernel_guard: ${bad.length} override(s) violate the override contract\n`,
+        );
+        return 1;
+    }
+    return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    }
+}

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