@event4u/agent-config 9.16.0 → 9.18.0

package/src/scripts/lint_profile_personas.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env tsx
+/**
+ * Profile → persona id resolution gate.
+ *
+ * ## The defect this catches
+ *
+ * Every seed profile under `src/agent-src/profiles/*.yml` pre-selects persona
+ * ids in `defaults.personas`. Persona ids are the filenames under
+ * `src/agent-src/personas/` (plus `personas/advisors/`), and nothing else
+ * historically checked the join — all six seed profiles shipped ids
+ * (`reviewer`, `security`, `editor`, …) that resolved to no persona file at
+ * all, so the pre-selection was silently dead. This gate makes a broken id a
+ * CI failure with a nearest-match hint.
+ *
+ * Contract (src/config/gate-coverage.yml): emits exactly one `scanned: <N>`
+ * line, N = profiles scanned.
+ *
+ * Exit: 0 clean · 1 usage/IO error · 2 findings.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export interface Finding {
+    file: string;
+    id: string;
+    hint: string;
+}
+
+/** Persona ids = `.md` basenames under personas/ and personas/advisors/. */
+export function known_persona_ids(repoRoot: string): Set<string> {
+    const ids = new Set<string>();
+    const roots = [
+        path.join(repoRoot, 'src', 'agent-src', 'personas'),
+        path.join(repoRoot, 'src', 'agent-src', 'personas', 'advisors'),
+    ];
+    for (const dir of roots) {
+        if (!fs.existsSync(dir)) continue;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+            if (entry.name === 'README.md') continue;
+            ids.add(entry.name.slice(0, -'.md'.length));
+        }
+    }
+    return ids;
+}
+
+function levenshtein(a: string, b: string): number {
+    const prev: number[] = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0]!;
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cur = prev[j]!;
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            prev[j] = Math.min(cur + 1, prev[j - 1]! + 1, diag + cost);
+            diag = cur;
+        }
+    }
+    return prev[b.length]!;
+}
+
+/** Closest known id by substring containment first, edit distance second. */
+export function nearest_match(id: string, known: ReadonlySet<string>): string {
+    let best = '';
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const candidate of known) {
+        const contains = candidate.includes(id) || id.includes(candidate);
+        const score = levenshtein(id, candidate) - (contains ? 100 : 0);
+        if (score < bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best;
+}
+
+/**
+ * Scan every `profiles/*.yml` under `repoRoot`'s profile dir and resolve
+ * `defaults.personas` against the known persona ids.
+ */
+export function scan_profiles(repoRoot: string): { findings: Finding[]; scanned: number } {
+    const profileDir = path.join(repoRoot, 'src', 'agent-src', 'profiles');
+    if (!fs.existsSync(profileDir)) {
+        throw new Error(`profile directory not found: ${profileDir}`);
+    }
+    const known = known_persona_ids(repoRoot);
+    const findings: Finding[] = [];
+    let scanned = 0;
+    const files = fs
+        .readdirSync(profileDir)
+        .filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))
+        .sort();
+    for (const file of files) {
+        const full = path.join(profileDir, file);
+        const rel = path.relative(repoRoot, full);
+        const parsed = parseYaml(fs.readFileSync(full, 'utf-8')) as Record<string, unknown> | null;
+        scanned += 1;
+        const profile = (parsed?.['profile'] ?? {}) as Record<string, unknown>;
+        const defaults = (profile['defaults'] ?? {}) as Record<string, unknown>;
+        const personas = defaults['personas'];
+        if (!Array.isArray(personas)) continue;
+        for (const raw of personas) {
+            const id = String(raw);
+            if (known.has(id)) continue;
+            const hint = known.size > 0 ? `did you mean \`${nearest_match(id, known)}\`?` : 'no personas found';
+            findings.push({ file: rel, id, hint });
+        }
+    }
+    return { findings, scanned };
+}
+
+export function main(argv?: readonly string[]): number {
+    let quiet = false;
+    for (const arg of argv ?? process.argv.slice(2)) {
+        if (arg === '--quiet') {
+            quiet = true;
+        } else {
+            process.stderr.write(`usage: lint_profile_personas [--quiet]\n`);
+            return 1;
+        }
+    }
+
+    let result: { findings: Finding[]; scanned: number };
+    try {
+        result = scan_profiles(REPO_ROOT);
+    } catch (e) {
+        process.stderr.write(`error: ${String(e)}\n`);
+        return 1;
+    }
+
+    for (const f of result.findings) {
+        process.stdout.write(
+            `❌  ${f.file}  defaults.personas id \`${f.id}\` resolves to no file under src/agent-src/personas/ — ${f.hint}\n`,
+        );
+    }
+    if (result.findings.length === 0 && !quiet) {
+        process.stdout.write(
+            `✅  profile personas: every defaults.personas id resolves to a persona file\n`,
+        );
+    }
+    // gate-coverage contract (src/config/gate-coverage.yml): profiles inspected.
+    process.stdout.write(`scanned: ${String(result.scanned)}\n`);
+    return result.findings.length > 0 ? 2 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/lint_token_budget_discipline.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env tsx
+/**
+ * Token-budget-discipline gate (src/rules/token-budget-discipline.md).
+ *
+ * The rule names this linter as its CI enforcer for two obligations on
+ * `token_budget_class: rich` skills:
+ *
+ * 1. CAP — at most 15 % of the suite's skills may claim `rich`. Exceeding
+ *    the ratio is a hard fail (both numbers are printed).
+ * 2. JUSTIFICATION — every `rich`-tagged skill carries a
+ *    `## Why this skill is rich` section explaining the irreducible
+ *    complexity.
+ *
+ * Additionally, any `token_budget_class` value outside
+ * `lean | standard | rich` is a finding (schema drift).
+ *
+ * Exit: 0 clean · 1 usage/IO error · 2 findings.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const SKILLS_ROOT = 'src/skills';
+
+/** The rule's cap: rich-tagged skills / total skills must stay <= 15 %. */
+export const RICH_RATIO_CAP = 0.15;
+
+export const VALID_CLASSES = ['lean', 'standard', 'rich'] as const;
+
+export const RICH_SECTION_HEADING = '## Why this skill is rich';
+
+export interface Finding {
+    /** repo-relative path */
+    file: string;
+    message: string;
+}
+
+export interface ScanResult {
+    findings: Finding[];
+    /** SKILL.md files scanned. */
+    scanned: number;
+    /** Skills declaring token_budget_class: rich. */
+    richCount: number;
+}
+
+/** `token_budget_class` value from a SKILL.md's YAML frontmatter, or null. */
+export function frontmatter_class(content: string): string | null {
+    if (!content.startsWith('---')) {
+        return null;
+    }
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) {
+        return null;
+    }
+    const frontmatter = content.slice(0, end);
+    const m = /^token_budget_class:\s*['"]?([^'"\s#]+)/m.exec(frontmatter);
+    return m ? m[1]! : null;
+}
+
+/** Scan one skills root (directory of `<skill>/SKILL.md`). */
+export function scan_skills(skillsRoot: string): ScanResult {
+    const findings: Finding[] = [];
+    let scanned = 0;
+    let richCount = 0;
+    const entries = fs
+        .readdirSync(skillsRoot, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    for (const name of entries) {
+        const skillFile = path.join(skillsRoot, name, 'SKILL.md');
+        if (!fs.existsSync(skillFile)) {
+            continue;
+        }
+        scanned += 1;
+        const rel = path.relative(REPO_ROOT, skillFile).split(path.sep).join('/');
+        const content = fs.readFileSync(skillFile, 'utf-8');
+        const cls = frontmatter_class(content);
+        if (cls === null) {
+            continue; // no key = lean by default (rule § the three classes)
+        }
+        if (!(VALID_CLASSES as readonly string[]).includes(cls)) {
+            findings.push({
+                file: rel,
+                message: `invalid token_budget_class '${cls}' — must be one of ${VALID_CLASSES.join(' | ')}`,
+            });
+            continue;
+        }
+        if (cls === 'rich') {
+            richCount += 1;
+            if (!content.includes(RICH_SECTION_HEADING)) {
+                findings.push({
+                    file: rel,
+                    message: `rich-tagged skill missing the '${RICH_SECTION_HEADING}' justification section`,
+                });
+            }
+        }
+    }
+    if (scanned > 0 && richCount > scanned * RICH_RATIO_CAP) {
+        findings.push({
+            file: SKILLS_ROOT,
+            message:
+                `rich-skill cap exceeded: ${String(richCount)} rich of ${String(scanned)} skills ` +
+                `(${((richCount / scanned) * 100).toFixed(1)} % > ${String(RICH_RATIO_CAP * 100)} % cap, ` +
+                `max ${String(Math.floor(scanned * RICH_RATIO_CAP))})`,
+        });
+    }
+    return { findings, scanned, richCount };
+}
+
+export function main(argv?: readonly string[]): number {
+    let quiet = false;
+    for (const arg of argv ?? process.argv.slice(2)) {
+        if (arg === '--quiet') {
+            quiet = true;
+        } else {
+            process.stderr.write('usage: lint_token_budget_discipline [--quiet]\n');
+            return 1;
+        }
+    }
+
+    let result: ScanResult;
+    try {
+        result = scan_skills(path.join(REPO_ROOT, SKILLS_ROOT));
+    } catch (e) {
+        process.stderr.write(`error: ${String(e)}\n`);
+        return 1;
+    }
+
+    for (const f of result.findings) {
+        process.stdout.write(`❌  ${f.file}  ${f.message}\n`);
+    }
+    if (result.findings.length === 0 && !quiet) {
+        process.stdout.write(
+            `✅  token-budget discipline: ${String(result.richCount)} rich of ${String(result.scanned)} skills within the ${String(RICH_RATIO_CAP * 100)} % cap; every rich skill justifies itself\n`,
+        );
+    }
+    // gate-coverage contract (src/config/gate-coverage.yml): files inspected.
+    process.stdout.write(`scanned: ${String(result.scanned)}\n`);
+    return result.findings.length > 0 ? 2 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}

package/src/scripts/lint_trigger_collisions.ts

@@ -0,0 +1,257 @@
+#!/usr/bin/env tsx
+/**
+ * lint_trigger_collisions — every shared trigger carries a written-down
+ * disposition, or the build is red.
+ *
+ * Defect measured: a trigger string shared by ≥2 routed rules makes both fire
+ * on the same prompt. Many collisions are correct (`refactor` firing both the
+ * analyze-first and the diff-shape floor is complementary), but before this
+ * gate nothing forced that argument to be WRITTEN DOWN — so accidental
+ * co-firing (the brand pair, secret/password, valuation/DCF) accumulated
+ * silently. This gate makes every collision either dispositioned or an error.
+ *
+ * Why this gate shape: the existing `tests/scripts/rule_trigger_collisions.test.ts`
+ * is a pair-level Jaccard SIMILARITY ratchet (near-duplicate trigger sets);
+ * it is kept untouched. This lint is per-trigger-VALUE disposition coverage —
+ * a different axis: one shared value between otherwise-different rules never
+ * moves Jaccard past 0.4, but still needs an argument.
+ *
+ * Disposition, in the sharing rule's frontmatter (both optional keys are in
+ * `schemas/rule.schema.json`):
+ *
+ *   collision_ok:
+ *     "refactor": "one-line reason why this rule also firing here is correct"
+ *   precedence:
+ *     "refactor": 1        # all sharers declare pairwise-distinct integers
+ *
+ * A collision is clean when EVERY sharer has `collision_ok[<value>]`, OR all
+ * sharers carry pairwise-distinct `precedence[<value>]` integers.
+ *
+ * Scope: `src/rules/*.md`, `type: manual` excluded (reference-only, no router
+ * emission — ADR-004), rules without `triggers:` excluded (kernel).
+ * Same-value-different-kind never collides (a `keyword` and a `path_prefix`
+ * match different surfaces).
+ *
+ * Modes: default lint (exit 0 clean, 2 findings/dead-scope, 1 internal error;
+ * emits one machine-readable `scanned: <N>` line for gate-coverage), plus
+ * `--report <path>` writing the collision-census markdown, `--json`, `--quiet`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const RULES_ROOT = 'src/rules';
+const TRIGGER_KINDS = ['keyword', 'phrase', 'command', 'path_prefix', 'file_pattern'] as const;
+
+export interface RuleTriggers {
+    id: string;
+    type: string;
+    triggers: { kind: string; value: string }[];
+    collision_ok: Record<string, string>;
+    precedence: Record<string, number>;
+}
+
+export interface Collision {
+    kind: string;
+    value: string; // case-folded
+    sharers: string[]; // rule ids, sorted
+    undispositioned: string[]; // rule ids missing a valid disposition
+}
+
+function _parse_frontmatter(text: string): Record<string, unknown> {
+    if (!text.startsWith('---\n')) return {};
+    const end = text.indexOf('\n---', 4);
+    if (end < 0) return {};
+    const data = parseYaml(text.slice(4, end), { version: '1.1' }) ?? {};
+    return data !== null && typeof data === 'object' && !Array.isArray(data)
+        ? (data as Record<string, unknown>)
+        : {};
+}
+
+function _as_string_map(v: unknown): Record<string, string> {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) return {};
+    const out: Record<string, string> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+        out[k.toLowerCase()] = String(val);
+    }
+    return out;
+}
+
+function _as_int_map(v: unknown): Record<string, number> {
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) return {};
+    const out: Record<string, number> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+        const n = Number(val);
+        if (Number.isInteger(n)) out[k.toLowerCase()] = n;
+    }
+    return out;
+}
+
+export function load_rules(rules_dir: string): RuleTriggers[] {
+    const out: RuleTriggers[] = [];
+    let files: string[] = [];
+    try {
+        files = fs.readdirSync(rules_dir).filter((f) => f.endsWith('.md')).sort();
+    } catch {
+        return [];
+    }
+    for (const f of files) {
+        const fm = _parse_frontmatter(fs.readFileSync(path.join(rules_dir, f), 'utf-8'));
+        if (Object.keys(fm).length === 0) continue;
+        const type = String(fm['type'] ?? 'auto');
+        const rawTriggers = Array.isArray(fm['triggers']) ? (fm['triggers'] as unknown[]) : [];
+        const triggers: { kind: string; value: string }[] = [];
+        for (const t of rawTriggers) {
+            if (t === null || typeof t !== 'object' || Array.isArray(t)) continue;
+            for (const kind of TRIGGER_KINDS) {
+                if (kind in (t as Record<string, unknown>)) {
+                    triggers.push({ kind, value: String((t as Record<string, unknown>)[kind]).toLowerCase() });
+                    break;
+                }
+            }
+        }
+        out.push({
+            id: f.replace(/\.md$/, ''),
+            type,
+            triggers,
+            collision_ok: _as_string_map(fm['collision_ok']),
+            precedence: _as_int_map(fm['precedence']),
+        });
+    }
+    return out;
+}
+
+export function find_collisions(rules: RuleTriggers[]): Collision[] {
+    const routed = rules.filter((r) => r.type !== 'manual' && r.triggers.length > 0);
+    const byKey = new Map<string, Set<string>>();
+    const ruleById = new Map(routed.map((r) => [r.id, r]));
+    for (const r of routed) {
+        for (const t of r.triggers) {
+            const key = `${t.kind}\u0000${t.value}`;
+            const set = byKey.get(key) ?? new Set<string>();
+            set.add(r.id);
+            byKey.set(key, set);
+        }
+    }
+    const collisions: Collision[] = [];
+    for (const [key, sharerSet] of byKey) {
+        if (sharerSet.size < 2) continue;
+        const [kind, value] = key.split('\u0000') as [string, string];
+        const sharers = [...sharerSet].sort();
+        const withOk = sharers.filter((id) => value in (ruleById.get(id)?.collision_ok ?? {}));
+        const precedences = sharers
+            .map((id) => (ruleById.get(id)?.precedence ?? {})[value])
+            .filter((n): n is number => n !== undefined);
+        const precedence_ok =
+            precedences.length === sharers.length && new Set(precedences).size === sharers.length;
+        const undispositioned = precedence_ok ? [] : sharers.filter((id) => !withOk.includes(id));
+        collisions.push({ kind, value, sharers, undispositioned });
+    }
+    collisions.sort(
+        (a, b) => b.sharers.length - a.sharers.length || (a.value < b.value ? -1 : a.value > b.value ? 1 : 0),
+    );
+    return collisions;
+}
+
+export function render_report(rules: RuleTriggers[], collisions: Collision[], sha: string): string {
+    const routed = rules.filter((r) => r.type !== 'manual' && r.triggers.length > 0);
+    const totalTriggers = routed.reduce((s, r) => s + r.triggers.length, 0);
+    const distinct = new Set(routed.flatMap((r) => r.triggers.map((t) => `${t.kind}\u0000${t.value}`))).size;
+    const undisp = collisions.filter((c) => c.undispositioned.length > 0);
+    const lines: string[] = [
+        '# Trigger-collision census',
+        '',
+        `> Generated by \`./scripts-run src/scripts/lint_trigger_collisions --report agents/evidence/reports/trigger-collision-census.md\` on 2026-08-04 at ${sha}.`,
+        '> Do not hand-edit — re-run the command.',
+        '',
+        `- Routed rules with triggers: ${routed.length} (of ${rules.length} rule files; \`type: manual\` and trigger-less kernel rules excluded)`,
+        `- Trigger entries: ${totalTriggers} · distinct (kind, value) pairs: ${distinct}`,
+        `- Colliding values (shared by ≥2 rules): ${collisions.length}`,
+        `- Undispositioned collisions: ${undisp.length} (the lint is red unless this is 0)`,
+        '',
+        '| # | Kind | Trigger | Rules | Disposition |',
+        '|---|------|---------|-------|-------------|',
+    ];
+    collisions.forEach((c, i) => {
+        const status = c.undispositioned.length === 0 ? 'dispositioned' : `MISSING: ${c.undispositioned.join(', ')}`;
+        lines.push(`| ${i + 1} | ${c.kind} | \`${c.value}\` | ${c.sharers.join(', ')} | ${status} |`);
+    });
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function main(argv: string[]): number {
+    const quiet = argv.includes('--quiet');
+    const as_json = argv.includes('--json');
+    let reportPath: string | null = null;
+    const ri = argv.indexOf('--report');
+    if (ri >= 0) reportPath = argv[ri + 1] ?? null;
+
+    const rulesDir = path.join(REPO_ROOT, RULES_ROOT);
+    const rules = load_rules(rulesDir);
+    try {
+        assertScanned({
+            gate: 'lint_trigger_collisions',
+            scanned: rules.length,
+            units: 'rule file(s)',
+            roots: [RULES_ROOT],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) throw exc;
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
+    process.stdout.write(`scanned: ${rules.length}\n`);
+
+    const collisions = find_collisions(rules);
+    const findings = collisions.filter((c) => c.undispositioned.length > 0);
+
+    if (reportPath) {
+        let sha = 'HEAD';
+        try {
+            sha = fs.readFileSync(path.join(REPO_ROOT, '.git', 'HEAD'), 'utf-8').trim().slice(0, 9);
+        } catch {
+            // detached info unavailable — keep the placeholder
+        }
+        const target = path.isAbsolute(reportPath) ? reportPath : path.join(REPO_ROOT, reportPath);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, render_report(rules, collisions, sha));
+        if (!quiet) process.stdout.write(`report → ${reportPath}\n`);
+    }
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ collisions, findings: findings.length }, null, 2) + '\n');
+    }
+
+    if (findings.length > 0) {
+        process.stderr.write(
+            `❌  ${findings.length} trigger collision(s) without a written disposition:\n`,
+        );
+        for (const c of findings) {
+            process.stderr.write(
+                `    ${c.kind} "${c.value}" shared by [${c.sharers.join(', ')}] — missing collision_ok/precedence on: ${c.undispositioned.join(', ')}\n`,
+            );
+        }
+        process.stderr.write(
+            '    Remedy: add `collision_ok: {"<value>": "<one-line reason>"}` (or pairwise-distinct\n' +
+                '    `precedence: {"<value>": <int>}`) to EVERY sharer’s frontmatter, or disjoin the trigger sets.\n',
+        );
+        return 2;
+    }
+    if (!quiet) {
+        process.stdout.write(
+            `✅  ${collisions.length} trigger collision(s), all dispositioned (${rules.length} rules scanned)\n`,
+        );
+    }
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+if (process.argv[1] && (import.meta.url === pathToFileURL(process.argv[1]).href || path.resolve(process.argv[1]) === _HERE)) {
+    process.exitCode = main(process.argv.slice(2));
+}