@event4u/agent-config 8.13.0 → 9.1.0

package/src/scripts/lint_skill_scripts_readonly.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env -S node --import tsx
+/**
+ * lint_skill_scripts_readonly — read-only-by-default script convention
+ * (ecosystem-harvest skill-quality-gates, Phase 3).
+ *
+ * A script shipped inside a skill (`src/skills/<skill>/scripts/**`) is
+ * side-effect-free by default: it inspects / prints, it does not mutate. Any
+ * mutation must be gated behind an explicit flag (`--writable` / `--apply` /
+ * `--write` / `--out` / `--fix` / `--emit`) named in the skill's SKILL.md, OR
+ * the script must be allowlisted with a rationale (a generator whose declared
+ * purpose IS to write into a caller-supplied path).
+ *
+ * The linter flags a script that contains a content-mutation primitive but
+ * neither references a write-gating flag nor is allowlisted. Directory creation
+ * (`mkdirSync`) and writes under a temp dir are not content mutation and do not
+ * trip the gate.
+ *
+ * Deterministic, static-config only. Allowlist:
+ * `lint_skill_scripts_readonly_allowlist.json`, capped at 20.
+ *
+ * Exit codes: 0 = clean (or only allowlisted), 1 = ungated write, 2 = over cap / usage.
+ *
+ * Usage: ./scripts-run src/scripts/lint_skill_scripts_readonly [--quiet] [--root <dir>]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const DEFAULT_SKILLS = path.join(REPO, 'src', 'skills');
+const ALLOWLIST = path.join(path.dirname(_HERE), 'lint_skill_scripts_readonly_allowlist.json');
+const ALLOWLIST_CAP = 20;
+
+// Content-mutation primitives, language-scoped. mkdirSync is intentionally
+// excluded (dir creation is not content mutation). Shell redirection is matched
+// only in .sh files — `> "` / `=> "` is pervasive, harmless syntax in TS/JS.
+const JS_WRITE_RE =
+    /\b(writeFileSync|writeFile\s*\(|appendFileSync|appendFile\s*\(|unlinkSync|unlink\s*\(|rmSync|rmdirSync|copyFileSync|renameSync)\b/;
+const PY_WRITE_RE =
+    /\bopen\s*\([^)]*,\s*["'][wa]\+?b?["']|\bos\.(remove|unlink|rmdir)\b|\bshutil\.(rmtree|move|copy)\b|\bpathlib[^\n]*\.write_(text|bytes)\b|\.write_(text|bytes)\s*\(/;
+const SH_WRITE_RE =
+    /(^|\s|;|&&|\|)(rm|rmdir|mv|cp|dd|truncate|tee)\s|>>?\s*[^&\s]|\b(DELETE\s+FROM|DROP\s+(TABLE|DATABASE)|TRUNCATE)\b/;
+// A write-gating flag reference — mutation is behind an opt-in.
+const GATE_RE = /--writable|--apply|--write|--out|--fix\b|--emit|--generate|--dry-run|dryRun|dry_run|parsed\.output|args\.output|opts\.output/;
+const SCRIPT_EXT = new Set(['.ts', '.js', '.mjs', '.cjs', '.py', '.sh']);
+
+function hasWritePrimitive(body: string, ext: string): boolean {
+    if (ext === '.py') return PY_WRITE_RE.test(body);
+    if (ext === '.sh') return SH_WRITE_RE.test(body);
+    return JS_WRITE_RE.test(body); // .ts/.js/.mjs/.cjs
+}
+
+interface Violation {
+    rel: string;
+    detail: string;
+}
+
+function loadAllowlist(): Set<string> {
+    if (!fs.existsSync(ALLOWLIST)) return new Set();
+    const data = JSON.parse(fs.readFileSync(ALLOWLIST, 'utf-8')) as {
+        entries?: Array<{ path: string; reason: string }>;
+    };
+    const entries = Array.isArray(data.entries) ? data.entries : [];
+    if (entries.length > ALLOWLIST_CAP) {
+        process.stderr.write(
+            `❌  lint_skill_scripts_readonly: allowlist has ${entries.length} entries (> ${ALLOWLIST_CAP}). ` +
+                `Per the autonomous-execution allowlist-growth antipattern, the convention is wrong, not the content.\n`,
+        );
+        process.exit(2);
+    }
+    const bad = entries.filter((e) => !e.reason || e.reason.trim() === '');
+    if (bad.length > 0) {
+        process.stderr.write(`❌  lint_skill_scripts_readonly: allowlist entries must carry a non-empty reason: ${bad.map((b) => b.path).join(', ')}\n`);
+        process.exit(2);
+    }
+    return new Set(entries.map((e) => e.path));
+}
+
+function* scriptFiles(root: string): Generator<string> {
+    if (!fs.existsSync(root)) return;
+    for (const skill of fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!skill.isDirectory()) continue;
+        const scriptsDir = path.join(root, skill.name, 'scripts');
+        if (!fs.existsSync(scriptsDir)) continue;
+        const stack = [scriptsDir];
+        while (stack.length) {
+            const d = stack.pop() as string;
+            for (const e of fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                const full = path.join(d, e.name);
+                if (e.isDirectory()) stack.push(full);
+                else if (SCRIPT_EXT.has(path.extname(e.name))) yield full;
+            }
+        }
+    }
+}
+
+function parseArgs(argv: string[]): { quiet: boolean; root: string } {
+    const a = { quiet: false, root: DEFAULT_SKILLS };
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--quiet') a.quiet = true;
+        else if (argv[i] === '--root') a.root = argv[(i += 1)] ?? DEFAULT_SKILLS;
+        else {
+            process.stderr.write(`lint_skill_scripts_readonly: unrecognized argument: ${argv[i]}\n`);
+            process.exit(2);
+        }
+    }
+    return a;
+}
+
+function main(argv: string[]): number {
+    const args = parseArgs(argv);
+    const allow = loadAllowlist();
+    const violations: Violation[] = [];
+    let scanned = 0;
+    for (const f of scriptFiles(args.root)) {
+        scanned += 1;
+        const rel = path.relative(REPO, f);
+        // Compare against the src/skills-relative form for the allowlist key.
+        const relSkills = path.relative(args.root, f);
+        const body = fs.readFileSync(f, 'utf-8');
+        if (!hasWritePrimitive(body, path.extname(f))) continue;
+        if (GATE_RE.test(body)) continue;
+        if (allow.has(relSkills) || allow.has(rel)) continue;
+        violations.push({ rel, detail: 'contains a content-mutation primitive but no write-gating flag (--writable/--apply/--write/--out/--fix) and is not allowlisted' });
+    }
+
+    if (violations.length > 0) {
+        process.stderr.write(`❌  lint_skill_scripts_readonly: ${violations.length} ungated write(s):\n`);
+        for (const v of violations) process.stderr.write(`   ${v.rel} — ${v.detail}\n`);
+        return 1;
+    }
+    if (!args.quiet) {
+        process.stdout.write(`✅  lint_skill_scripts_readonly: ${scanned} skill script(s), all read-only or gated.\n`);
+    }
+    return 0;
+}
+
+if (path.resolve(process.argv[1] ?? '') === path.resolve(_HERE)) {
+    process.exit(main(process.argv.slice(2)));
+}
+
+export { hasWritePrimitive, GATE_RE, main };

package/src/scripts/lint_skill_scripts_readonly_allowlist.json

@@ -0,0 +1,8 @@
+{
+  "entries": [
+    {
+      "path": "corpus-grounding/scripts/decision_engine.ts",
+      "reason": "Generator whose declared purpose IS to materialize the grounded design-system MASTER.md (and optional page-override files) into a caller-supplied output_dir; the caller (ground.ts) controls the path. Writing is the feature, not a side effect."
+    }
+  ]
+}

package/src/scripts/lint_supported_tools_matrix.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env tsx
+/**
+ * lint_supported_tools_matrix.ts — CI gate: the README `## Supported tools`
+ * matrix equals the canonical adapter registry (fail on drift in either
+ * direction), and every tool-tagged generator output root is claimed by the
+ * registry (road-to-ecosystem-harvest-skill-quality-gates Phase 4, Source AA).
+ *
+ * Exit codes: 0 — in sync · 1 — drift (each line names the drifted row).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { lint_matrix } from './_lib/tool_adapter_registry.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
+
+export function run(readmePath: string): string[] {
+    const readme = fs.readFileSync(readmePath, 'utf-8');
+    return lint_matrix(readme);
+}
+
+const isMain = process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_HERE);
+if (isMain) {
+    const idx = process.argv.indexOf('--readme');
+    const readmePath = idx !== -1 ? (process.argv[idx + 1] ?? '') : path.join(REPO_ROOT, 'README.md');
+    const errors = run(readmePath);
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  ${e}\n`);
+        process.exit(1);
+    }
+    process.stdout.write('✅  Supported-tools matrix ↔ adapter registry ↔ generator roots in sync\n');
+    process.exit(0);
+}

package/src/scripts/mcp_server/tools.ts

@@ -775,9 +775,7 @@ async function _runDoctorLeg(consumerRoot: string): Promise<{
         let tagDrift: Record<string, unknown>[] = [];
         let checks: Record<string, unknown>[];
         if (manifest === null) {
-            const bridgePresent = fs.existsSync(
-                path.join(projectRoot, doctor.BRIDGE_MARKER_RELATIVE),
-            );
+            const bridgePresent = doctor._is_global_only_consumer(projectRoot);
             checks = doctor._run_checks_no_manifest(projectRoot, bridgePresent, null);
         } else {
             const [records, known] = doctor._collect_manifest_entries(projectRoot, manifest);

package/src/scripts/optimize_skill_description.ts

@@ -0,0 +1,144 @@
+/**
+ * optimize_skill_description.ts — U1 packaged description-optimizer loop
+ * (road-to-ecosystem-harvest-skill-authoring-rigor).
+ *
+ * Chains the suite's existing primitives into ONE authoring workflow:
+ * candidate descriptions × the skill's `evals/triggers.json` queries →
+ * per-candidate trigger-rate, measured on a HELD-OUT split so the winning
+ * description is picked on queries it was never tuned against (avoids
+ * overfitting to the training queries).
+ *
+ * Split: queries are partitioned deterministically (stable hash of the query
+ * text, even→train / odd→test) — reproducible without storing a seed.
+ *
+ * Judges:
+ *   default   — deterministic proxy: does the query share ≥ 2 informative
+ *               tokens (or one rare token) with the description? Free, fast,
+ *               good for iteration.
+ *   --live    — model judge (claude-haiku): "would this description fire for
+ *               this query? YES/NO" — the real signal, ~$0.001/query·candidate.
+ *
+ * Usage:
+ *   npx tsx src/scripts/optimize_skill_description.ts --skill fe-design \
+ *     [--candidate "alt description …"]... [--live] [--max-usd 1]
+ *
+ * Output: per-candidate train/test trigger-accuracy table; the pick is the
+ * best TEST accuracy. Exit 0 always (authoring tool, not a gate).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface TriggerQuery {
+    q: string;
+    trigger: boolean;
+}
+
+/** Deterministic stable split — even hash → train, odd → test. */
+export function split_queries(queries: TriggerQuery[]): { train: TriggerQuery[]; test: TriggerQuery[] } {
+    const train: TriggerQuery[] = [];
+    const test: TriggerQuery[] = [];
+    for (const query of queries) {
+        let h = 0;
+        for (const ch of query.q) h = (h * 31 + ch.codePointAt(0)!) >>> 0;
+        (h % 2 === 0 ? train : test).push(query);
+    }
+    return { train, test };
+}
+
+const STOP = new Set(['the', 'a', 'an', 'for', 'to', 'of', 'and', 'or', 'in', 'on', 'with', 'when', 'use', 'via', 'this', 'that', 'my', 'our', 'me', 'we', 'is', 'are', 'it', 'before', 'after']);
+
+export function tokens(s: string): Set<string> {
+    return new Set(
+        s.toLowerCase().split(/[^a-z0-9]+/u).filter((t) => t.length > 2 && !STOP.has(t)),
+    );
+}
+
+/** Deterministic proxy judge: informative-token overlap between query and description. */
+export function proxy_fires(description: string, query: string): boolean {
+    const d = tokens(description);
+    const q = tokens(query);
+    let overlap = 0;
+    for (const t of q) if (d.has(t)) overlap += 1;
+    return overlap >= 2;
+}
+
+export function accuracy(
+    fires: (desc: string, q: string) => boolean,
+    desc: string,
+    queries: TriggerQuery[],
+): number {
+    if (queries.length === 0) return 0;
+    let ok = 0;
+    for (const query of queries) {
+        if (fires(desc, query.q) === query.trigger) ok += 1;
+    }
+    return ok / queries.length;
+}
+
+async function live_judge_factory(maxUsd: number): Promise<(desc: string, q: string) => boolean> {
+    const c = await import('./ai_council/clients.js');
+    const client = new c.AnthropicClient({ api_key: c.load_anthropic_key(), model: 'claude-haiku-4-5-20251001' });
+    let spent = 0;
+    return (desc: string, q: string): boolean => {
+        if (spent >= maxUsd) throw new Error(`live-judge budget $${maxUsd} exhausted`);
+        const resp = client.ask(
+            'You decide whether an agent skill would activate. Answer exactly YES or NO.',
+            `Skill description: "${desc}"\nUser query: "${q}"\nWould this skill fire for this query?`,
+            8,
+        );
+        if (resp.error) throw new Error(resp.error);
+        spent += ((resp.input_tokens / 1e6) * 0.25) + ((resp.output_tokens / 1e6) * 1.25);
+        return /YES/i.test(resp.text);
+    };
+}
+
+export async function main(argv: string[]): Promise<number> {
+    const skillIdx = argv.indexOf('--skill');
+    if (skillIdx === -1) {
+        process.stderr.write('usage: --skill <id> [--candidate "…"]... [--live] [--max-usd 1]\n');
+        return 2;
+    }
+    const skill = argv[skillIdx + 1] ?? '';
+    const live = argv.includes('--live');
+    const mu = argv.indexOf('--max-usd');
+    const maxUsd = mu !== -1 ? Number(argv[mu + 1]) : 1;
+    const candidates: string[] = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--candidate') candidates.push(argv[i + 1] ?? '');
+    }
+
+    const skillMd = fs.readFileSync(path.join('src/skills', skill, 'SKILL.md'), 'utf-8');
+    const current = (skillMd.match(/^description:\s*["']?(.+?)["']?\s*$/m) ?? [])[1] ?? '';
+    const triggers = JSON.parse(
+        fs.readFileSync(path.join('src/skills', skill, 'evals', 'triggers.json'), 'utf-8'),
+    ) as { queries: TriggerQuery[] };
+    const { train, test } = split_queries(triggers.queries);
+    process.stdout.write(`skill ${skill}: ${triggers.queries.length} queries → train ${train.length} / held-out ${test.length}\n\n`);
+
+    const judge = live ? await live_judge_factory(maxUsd) : proxy_fires;
+    const all = [current, ...candidates];
+    process.stdout.write('| # | description (first 70 chars) | train | TEST (held-out) |\n|---|---|---:|---:|\n');
+    let best = 0;
+    let bestAcc = -1;
+    all.forEach((desc, i) => {
+        const tr = accuracy(judge, desc, train);
+        const te = accuracy(judge, desc, test);
+        process.stdout.write(`| ${i === 0 ? 'current' : i} | ${desc.slice(0, 70)} | ${(tr * 100).toFixed(0)}% | ${(te * 100).toFixed(0)}% |\n`);
+        if (te > bestAcc) { bestAcc = te; best = i; }
+    });
+    process.stdout.write(`\npick (best held-out): ${best === 0 ? 'current description' : `candidate ${best}`} (${(bestAcc * 100).toFixed(0)}% test)\n`);
+    return 0;
+}
+
+const isMain = process.argv[1] !== undefined
+    && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+if (isMain) {
+    main(process.argv.slice(2)).then(
+        (code) => process.exit(code),
+        (err) => {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        },
+    );
+}

package/src/scripts/orchestration_record.ts

@@ -10,7 +10,7 @@
  *   ./scripts-run src/scripts/orchestration_record \
  *     --spawn-count 1 --token-delta -72000 --provenance measured \
  *     --tier-chosen lite --tier-source inferred --task-class read-only-fanout \
- *     [--tiers sonnet,opus] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
+ *     [--tiers sonnet,opus] [--agent-combo implementer,judge] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
  *     [--first-pass-success true|false] [--escalated true|false] \
  *     [--dir <audit-dir>] [--dry-run]
  *
@@ -109,6 +109,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         token_delta: int(flags, 'token-delta') ?? NaN,
         token_delta_provenance: str(flags, 'provenance') as Provenance | undefined,
         tiers: str(flags, 'tiers')?.split(',').map((s) => s.trim()).filter(Boolean),
+        agent_combo: str(flags, 'agent-combo')?.split(',').map((s) => s.trim()).filter(Boolean),
         tier_chosen: str(flags, 'tier-chosen') as TierChosen | undefined,
         tier_source: str(flags, 'tier-source') as TierSource | undefined,
         task_class: str(flags, 'task-class'),

package/src/scripts/prelaunch_diagnostics.ts

@@ -0,0 +1,248 @@
+#!/usr/bin/env tsx
+/**
+ * prelaunch_diagnostics.ts — validate / verdict / diff for pre-launch
+ * diagnostic reports (road-to-ecosystem-harvest-prelaunch-diagnostics,
+ * Source L). Contract: docs/contracts/prelaunch-diagnostics.md.
+ *
+ * Read-only by design: reads report JSON (+ optional suppression YAML),
+ * writes nothing — the consumer-side fix loop stays approval-gated.
+ *
+ * CLI:
+ *   validate <report.json> [--suppressions <file>]
+ *   diff <baseline.json> <current.json> [--ci] [--suppressions <file>]
+ *
+ * Exit codes: 0 clean · 1 validation error / --ci gate tripped · 2 usage.
+ *
+ * NO numeric score anywhere — council-locked (contract § 9).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
+const AREAS_FILE = path.join(REPO_ROOT, 'src', 'config', 'prelaunch-areas.yml');
+
+export interface AreaDef {
+    code: string;
+    launch_gate: boolean;
+    description?: string;
+}
+
+export interface AreaState {
+    state: 'pass' | 'finding' | 'unknown' | 'not-applicable';
+    evidence?: string;
+    reason?: string;
+}
+
+export interface Finding {
+    id: string;
+    area: string;
+    severity: 'P0' | 'P1' | 'P2' | 'P3';
+    title: string;
+    evidence?: string;
+    status: 'open' | 'fixed' | 'accepted-risk' | 'deferred-with-reason' | 'suppressed-with-evidence' | 'not-applicable';
+    reason?: string;
+}
+
+export interface Report {
+    schema_version: string;
+    project: string;
+    run_at: string;
+    areas: Record<string, AreaState>;
+    findings: Finding[];
+    questions?: string[];
+}
+
+export interface Suppression {
+    id: string;
+    reason: string;
+    evidence: string;
+}
+
+const ID_RE = /^AC-([A-Z][A-Z0-9]{1,7})-([0-9]{3})$/;
+const REASON_REQUIRED = new Set(['accepted-risk', 'deferred-with-reason', 'suppressed-with-evidence', 'not-applicable']);
+
+export function load_areas(file: string = AREAS_FILE): Record<string, AreaDef> {
+    const doc = parseYaml(fs.readFileSync(file, 'utf-8')) as { areas?: Record<string, AreaDef> };
+    return doc.areas ?? {};
+}
+
+export function load_suppressions(file: string): Suppression[] {
+    if (!fs.existsSync(file)) return [];
+    const doc = parseYaml(fs.readFileSync(file, 'utf-8')) as { suppressions?: Suppression[] };
+    return doc.suppressions ?? [];
+}
+
+/**
+ * Epistemics + structure validation beyond the JSON schema shape:
+ * pass-needs-evidence, N/A-needs-reason, ID grammar + area agreement,
+ * unique IDs, status-reason coupling, suppression receipts.
+ */
+export function validate_report(
+    report: Report,
+    areas: Record<string, AreaDef>,
+    suppressions: Suppression[] = [],
+): string[] {
+    const errors: string[] = [];
+    const codeByArea = new Map(Object.entries(areas).map(([k, v]) => [k, v.code]));
+
+    for (const [areaKey, st] of Object.entries(report.areas ?? {})) {
+        if (!codeByArea.has(areaKey)) {
+            errors.push(`areas.${areaKey}: unknown area (not in prelaunch-areas.yml — the vocabulary is fixed)`);
+        }
+        if (st.state === 'pass' && !st.evidence) {
+            errors.push(`areas.${areaKey}: state 'pass' without evidence — a pass is a cited diagnosis, not an assertion`);
+        }
+        if (st.state === 'not-applicable' && !st.reason) {
+            errors.push(`areas.${areaKey}: state 'not-applicable' without a reason`);
+        }
+    }
+
+    const seen = new Set<string>();
+    const suppressionById = new Map(suppressions.map((s) => [s.id, s]));
+    for (const f of report.findings ?? []) {
+        const m = ID_RE.exec(f.id);
+        if (!m) {
+            errors.push(`${f.id}: malformed finding ID (grammar: AC-<AREA>-NNN)`);
+            continue;
+        }
+        if (seen.has(f.id)) errors.push(`${f.id}: duplicate finding ID — IDs are immutable and never re-assigned`);
+        seen.add(f.id);
+        const expected = codeByArea.get(f.area);
+        if (expected === undefined) {
+            errors.push(`${f.id}: unknown area '${f.area}'`);
+        } else if (m[1] !== expected) {
+            errors.push(`${f.id}: ID area code '${m[1]}' does not match area '${f.area}' (code ${expected})`);
+        }
+        if (REASON_REQUIRED.has(f.status) && !f.reason) {
+            errors.push(`${f.id}: status '${f.status}' requires a reason`);
+        }
+        if (f.status === 'suppressed-with-evidence') {
+            const s = suppressionById.get(f.id);
+            if (!s) errors.push(`${f.id}: suppressed-with-evidence without a matching suppression entry`);
+            else if (!s.reason || !s.evidence) errors.push(`${f.id}: suppression entry must carry both reason and evidence`);
+        }
+    }
+    return errors;
+}
+
+/**
+ * The launch verdict. READY IS THE RESIDUAL STATE, NEVER THE DEFAULT:
+ * any open P0 refuses ready regardless of every other area (suppression
+ * does not rescue a P0 — contract § 5); any open P1 or a launch-gate
+ * area not at pass/not-applicable refuses ready too.
+ */
+export function verdict(report: Report, areas: Record<string, AreaDef>): { ready: boolean; blockers: string[] } {
+    const blockers: string[] = [];
+    for (const f of report.findings ?? []) {
+        if (f.severity === 'P0' && f.status !== 'fixed' && f.status !== 'not-applicable') {
+            blockers.push(`${f.id} (P0, ${f.status}): open P0 caps the verdict regardless of every other area`);
+        } else if (f.severity === 'P1' && f.status === 'open') {
+            blockers.push(`${f.id} (P1, open): fix before general rollout`);
+        }
+    }
+    for (const [key, def] of Object.entries(areas)) {
+        if (!def.launch_gate) continue;
+        const st = report.areas?.[key]?.state ?? 'unknown';
+        if (st !== 'pass' && st !== 'not-applicable') {
+            blockers.push(`area ${key} (launch-gate): state '${st}' — Unknown is never a Pass`);
+        }
+    }
+    return { ready: blockers.length === 0, blockers };
+}
+
+export interface DiffResult {
+    new_findings: Finding[];
+    resolved: Finding[];
+    regressed_areas: string[];
+    ci_trips: string[];
+}
+
+/** Diff two reports BY ID (titles are mutable metadata, never the key). */
+export function diff_reports(
+    baseline: Report,
+    current: Report,
+    areas: Record<string, AreaDef>,
+    suppressions: Suppression[] = [],
+): DiffResult {
+    const suppressed = new Set(suppressions.map((s) => s.id));
+    const baseIds = new Set((baseline.findings ?? []).map((f) => f.id));
+    const baseById = new Map((baseline.findings ?? []).map((f) => [f.id, f]));
+
+    const new_findings = (current.findings ?? []).filter((f) => !baseIds.has(f.id));
+    const resolved = (current.findings ?? []).filter(
+        (f) => f.status === 'fixed' && baseById.get(f.id)?.status === 'open',
+    );
+
+    const regressed_areas: string[] = [];
+    for (const [key, def] of Object.entries(areas)) {
+        if (!def.launch_gate) continue;
+        const before = baseline.areas?.[key]?.state;
+        const after = current.areas?.[key]?.state ?? 'unknown';
+        if (before === 'pass' && after !== 'pass' && after !== 'not-applicable') {
+            regressed_areas.push(key);
+        }
+    }
+
+    const ci_trips: string[] = [];
+    for (const f of new_findings) {
+        if ((f.severity === 'P0' || f.severity === 'P1') && f.status === 'open' && !suppressed.has(f.id)) {
+            ci_trips.push(`new open ${f.severity}: ${f.id} — ${f.title}`);
+        }
+    }
+    for (const a of regressed_areas) {
+        ci_trips.push(`launch-gate area '${a}' regressed from pass (Pass→Finding flip)`);
+    }
+    return { new_findings, resolved, regressed_areas, ci_trips };
+}
+
+function _readReport(p: string): Report {
+    return JSON.parse(fs.readFileSync(p, 'utf-8')) as Report;
+}
+
+function _renderDiff(d: DiffResult, suppressions: Suppression[]): string {
+    const lines: string[] = [];
+    lines.push(`new: ${d.new_findings.length} · resolved: ${d.resolved.length} · regressed launch-gate areas: ${d.regressed_areas.length}`);
+    for (const f of d.new_findings) lines.push(`  + ${f.id} [${f.severity}/${f.status}] ${f.title}`);
+    for (const f of d.resolved) lines.push(`  ✓ ${f.id} resolved`);
+    for (const a of d.regressed_areas) lines.push(`  ↓ area ${a} regressed from pass`);
+    if (suppressions.length > 0) {
+        lines.push('<details><summary>suppressed findings (evidence-backed, excluded from CI triggers)</summary>');
+        for (const s of suppressions) lines.push(`  ~ ${s.id} — ${s.reason} (evidence: ${s.evidence})`);
+        lines.push('</details>');
+    }
+    return lines.join('\n');
+}
+
+const isMain = process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_HERE);
+if (isMain) {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    const sIdx = argv.indexOf('--suppressions');
+    const suppressions = sIdx !== -1 ? load_suppressions(argv[sIdx + 1] ?? '') : [];
+    const areas = load_areas();
+
+    if (cmd === 'validate' && argv[1]) {
+        const report = _readReport(argv[1]);
+        const errors = validate_report(report, areas, suppressions);
+        for (const e of errors) process.stderr.write(`❌  ${e}\n`);
+        const v = verdict(report, areas);
+        process.stdout.write(v.ready ? '✅  verdict: ready\n' : `⚠️  verdict: NOT ready (${v.blockers.length} blocker(s))\n`);
+        for (const b of v.blockers) process.stdout.write(`   - ${b}\n`);
+        process.exit(errors.length > 0 ? 1 : 0);
+    } else if (cmd === 'diff' && argv[1] && argv[2]) {
+        const d = diff_reports(_readReport(argv[1]), _readReport(argv[2]), areas, suppressions);
+        process.stdout.write(_renderDiff(d, suppressions) + '\n');
+        if (argv.includes('--ci') && d.ci_trips.length > 0) {
+            for (const t of d.ci_trips) process.stderr.write(`❌  ${t}\n`);
+            process.exit(1);
+        }
+        process.exit(0);
+    } else {
+        process.stderr.write('usage: prelaunch_diagnostics validate <report.json> | diff <baseline.json> <current.json> [--ci] [--suppressions <file>]\n');
+        process.exit(2);
+    }
+}