@event4u/agent-config 9.3.0 → 9.5.0

package/src/scripts/bench_defect_finding.ts

@@ -0,0 +1,348 @@
+#!/usr/bin/env tsx
+/**
+ * Defect-finding benchmark runner (road-to-team-mode Phase 5, Steps 2-4).
+ *
+ * Three arms over the pre-registered corpus (internal/bench/corpora/defect-finding.yaml):
+ *   (a) self-review  — single strong model (Anthropic) + the adversarial-review frame
+ *   (b) team         — codex exec (subscription; reviewer pinned via --codex-model)
+ *   (c) council      — the neutral breadth arm: Anthropic + OpenAI independent reviews, union
+ *
+ * Every arm gets the SAME strict output contract so scoring is fair + objective:
+ * a review must end with `VERDICT: <n>` and one `DEFECT: <file>:<line> — <why>`
+ * line per defect. Recall + false-positives are then scored DETERMINISTICALLY
+ * against the corpus ground truth (no LLM judge for the PRIMARY metric — the
+ * blind rubric judge is the SECONDARY metric and is deferred this pass).
+ *
+ * Spend: arm (a) + arm (c) are billable API calls; arm (b) is the ChatGPT
+ * subscription (non-billable through this process). `--max-usd` is a HARD cap:
+ * the run aborts before a call that would cross it. `--dry-run` makes zero calls.
+ *
+ * Exit 0 ok · 1 aborted-on-cap / error · 2 usage.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { load as yamlLoad } from 'js-yaml';
+
+import {
+    AnthropicClient,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+} from './ai_council/clients.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '..', '..');
+const CORPUS = path.join(ROOT, 'internal', 'bench', 'corpora', 'defect-finding.yaml');
+const OUT_JSON = path.join(ROOT, 'internal', 'bench', 'reports', 'defect-finding.json');
+const OUT_MD = path.join(ROOT, 'internal', 'bench', 'reports', 'defect-finding.md');
+
+const OUTPUT_CONTRACT =
+    '\n\nReport STRICTLY in this format, nothing after it:\n' +
+    'DEFECT: <file>:<line> — <one-line why>   (one line per real defect; omit if none)\n' +
+    'VERDICT: <integer count of defects>';
+
+interface Fixture {
+    id: string;
+    defect_class: string;
+    prompt: string;
+    ground_truth: string;
+    rubric: string;
+    negative_control?: boolean;
+}
+
+type ArmId = 'self-review' | 'team' | 'council';
+
+interface ArmResult {
+    arm: ArmId;
+    text: string;
+    calls: number;
+    input_tokens: number;
+    output_tokens: number;
+    usd: number;
+    ms: number;
+    error: string | null;
+}
+
+/** Ground-truth FILENAME for a fixture, or null for a control. Each planted
+ * fixture touches exactly ONE unique file, so "a DEFECT line names this file"
+ * is the honest, line-number-robust recall signal (diff line numbering is
+ * ambiguous and models cite lines inconsistently — matching the exact
+ * file:line token systematically under-counts real finds). */
+function groundTruthFile(gt: string): string | null {
+    if (/^\s*NONE\b/i.test(gt)) return null;
+    const head = gt.split('—')[0] ?? gt;
+    const m = /([\w./-]+\.\w+):[\d,]+/.exec(head);
+    return m ? (m[1] as string) : null;
+}
+/** Basename of a path token (find.ts from src/search/find.ts). */
+function basename(p: string): string { return p.split('/').pop() ?? p; }
+
+/** Parse the DEFECT lines an arm emitted (file:line tokens it claims). */
+function parseClaimedDefects(text: string): { count: number; files: string[] } {
+    const files: string[] = [];
+    for (const line of text.split('\n')) {
+        // DEFECT: <file>[:line] — ... ; capture the file token (line optional).
+        const m = /^\s*DEFECT:\s*([\w./-]+\.\w+)/.exec(line);
+        if (m) files.push(m[1] as string);
+    }
+    const vm = /VERDICT:\s*(\d+)/i.exec(text);
+    const count = vm ? Number(vm[1]) : files.length;
+    return { count, files };
+}
+
+/** Deterministic recall/FP for one arm on one fixture. */
+function score(
+    fx: Fixture,
+    arm: ArmResult,
+): { recall_hit: boolean; false_positive: boolean; claimed: number } {
+    const gtFile = groundTruthFile(fx.ground_truth);
+    const claimed = parseClaimedDefects(arm.text);
+    if (gtFile === null || fx.negative_control === true) {
+        // Control: any claimed defect is a false positive.
+        return { recall_hit: false, false_positive: claimed.count > 0, claimed: claimed.count };
+    }
+    // Recall: a DEFECT line names the planted file (by basename — robust to the
+    // model prefixing or omitting the dir). Line-agnostic on purpose.
+    const target = basename(gtFile);
+    const hit = claimed.files.some((f) => basename(f) === target) || arm.text.includes(target);
+    return { recall_hit: hit, false_positive: false, claimed: claimed.count };
+}
+
+function usd(inTok: number, outTok: number, inRate: number, outRate: number): number {
+    return (inTok / 1_000_000) * inRate + (outTok / 1_000_000) * outRate;
+}
+
+// Conservative published-tier rates (per 1M tokens) for the estimate + tally.
+const RATES = {
+    anthropic: { in: 3, out: 15 }, // claude-sonnet class
+    openai: { in: 2.5, out: 10 }, // gpt-4o class
+};
+
+interface Budget {
+    cap: number;
+    spent: number;
+}
+
+function guard(b: Budget, next: number): void {
+    if (b.cap > 0 && b.spent + next > b.cap) {
+        throw new Error(`hard cap $${b.cap} would be crossed (spent $${b.spent.toFixed(4)}, next ~$${next.toFixed(4)})`);
+    }
+}
+
+function armSelfReview(fx: Fixture, key: string, b: Budget): ArmResult {
+    const t0 = Date.now();
+    guard(b, 0.05);
+    const client = new AnthropicClient({ api_key: key });
+    const sys =
+        'You are a single-model adversarial code reviewer (Attack-Defend-Revise). ' +
+        'Find real defects in the diff; do not invent problems in correct code.';
+    const r = client.ask(sys, fx.prompt + OUTPUT_CONTRACT, 1024);
+    const cost = usd(r.input_tokens, r.output_tokens, RATES.anthropic.in, RATES.anthropic.out);
+    b.spent += cost;
+    return {
+        arm: 'self-review', text: r.text, calls: 1,
+        input_tokens: r.input_tokens, output_tokens: r.output_tokens,
+        usd: cost, ms: Date.now() - t0, error: r.error,
+    };
+}
+
+function armTeam(fx: Fixture, model: string, _b: Budget): ArmResult {
+    const t0 = Date.now();
+    // codex = ChatGPT subscription: non-billable through this process. `--json`
+    // streams events; the review is the LAST agent_message item's text (the
+    // interactive mode without --json blocks/hangs — must use --json here).
+    let text = '';
+    let error: string | null = null;
+    try {
+        const raw = execFileSync('codex', ['exec', '--json', '-m', model, fx.prompt + OUTPUT_CONTRACT], {
+            encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout: 180_000,
+        });
+        for (const line of raw.split('\n')) {
+            const s = line.trim();
+            if (!s.startsWith('{')) continue;
+            try {
+                const ev = JSON.parse(s) as { item?: { type?: string; text?: string } };
+                if (ev.item?.type === 'agent_message' && typeof ev.item.text === 'string') {
+                    text = ev.item.text; // keep the last agent_message
+                }
+            } catch { /* skip non-JSON / partial lines */ }
+        }
+        if (!text) error = 'no agent_message in codex --json stream';
+    } catch (e) {
+        error = e instanceof Error ? e.message.slice(0, 300) : String(e);
+    }
+    return { arm: 'team', text, calls: 1, input_tokens: 0, output_tokens: 0, usd: 0, ms: Date.now() - t0, error };
+}
+
+function armCouncil(fx: Fixture, aKey: string, oKey: string, b: Budget): ArmResult {
+    const t0 = Date.now();
+    const sys =
+        'You are a neutral code reviewer. Review ONLY the supplied diff for real ' +
+        'defects; never invent problems in correct code.';
+    guard(b, 0.05);
+    const a = new AnthropicClient({ api_key: aKey }).ask(sys, fx.prompt + OUTPUT_CONTRACT, 1024);
+    let cost = usd(a.input_tokens, a.output_tokens, RATES.anthropic.in, RATES.anthropic.out);
+    b.spent += cost;
+    guard(b, 0.05);
+    const o = new OpenAIClient({ api_key: oKey }).ask(sys, fx.prompt + OUTPUT_CONTRACT, 1024);
+    const oc = usd(o.input_tokens, o.output_tokens, RATES.openai.in, RATES.openai.out);
+    b.spent += oc;
+    cost += oc;
+    // Council = breadth: union the two independent reviews.
+    const text = `# reviewer A\n${a.text}\n\n# reviewer B\n${o.text}`;
+    return {
+        arm: 'council', text, calls: 2,
+        input_tokens: a.input_tokens + o.input_tokens,
+        output_tokens: a.output_tokens + o.output_tokens,
+        usd: cost, ms: Date.now() - t0, error: a.error ?? o.error,
+    };
+}
+
+const CORRECTNESS = new Set(['logic-bug', 'off-by-one', 'race']);
+const DESIGN = new Set(['missing-empty-state', 'security-smell']);
+
+export function main(argv: string[]): 0 | 1 | 2 {
+    const dryRun = argv.includes('--dry-run');
+    const capIdx = argv.indexOf('--max-usd');
+    const cap = capIdx >= 0 ? Number(argv[capIdx + 1]) : 1.2;
+    const modelIdx = argv.indexOf('--codex-model');
+    const codexModel = (modelIdx >= 0 ? argv[modelIdx + 1] : undefined) ?? 'gpt-5.5';
+
+    const doc = yamlLoad(fs.readFileSync(CORPUS, 'utf8')) as { fixtures: Fixture[] };
+    const fixtures = doc.fixtures;
+
+    if (dryRun) {
+        const planted = fixtures.filter((f) => !f.negative_control).length;
+        process.stdout.write(
+            `defect-finding (dry-run — no calls):\n` +
+                `  fixtures: ${fixtures.length} (${planted} planted, ${fixtures.length - planted} control)\n` +
+                `  arms: self-review (anthropic, ${fixtures.length} calls) · team (codex ${codexModel}, ${fixtures.length} calls, subscription) · council (anthropic+openai, ${fixtures.length * 2} calls)\n` +
+                `  billable estimate: arm a ~$${(fixtures.length * 0.02).toFixed(2)} + arm c ~$${(fixtures.length * 0.04).toFixed(2)} ≈ $${(fixtures.length * 0.06).toFixed(2)} (hard cap $${cap})\n` +
+                `  arm b (codex): 0 billable (ChatGPT subscription quota)\n`,
+        );
+        return 0;
+    }
+
+    const aKey = load_anthropic_key();
+    const oKey = load_openai_key();
+    const budget: Budget = { cap, spent: 0 };
+    const rows: Array<{ fx: Fixture; arms: Record<ArmId, ArmResult> }> = [];
+
+    try {
+        for (const fx of fixtures) {
+            process.stdout.write(`· ${fx.id} (${fx.defect_class})\n`);
+            const arms = {
+                'self-review': armSelfReview(fx, aKey, budget),
+                team: armTeam(fx, codexModel, budget),
+                council: armCouncil(fx, aKey, oKey, budget),
+            } as Record<ArmId, ArmResult>;
+            rows.push({ fx, arms });
+        }
+    } catch (e) {
+        process.stderr.write(`ABORTED: ${e instanceof Error ? e.message : String(e)}\n`);
+        // fall through to write a partial report
+    }
+
+    // ── aggregate ──
+    const ARMS: ArmId[] = ['self-review', 'team', 'council'];
+    const agg: Record<string, unknown> = {};
+    const perArm: Record<ArmId, { recall: number; planted: number; fp: number; usd: number; ms: number; calls: number; byClass: Record<string, { hit: number; n: number }> }> =
+        Object.fromEntries(ARMS.map((a) => [a, { recall: 0, planted: 0, fp: 0, usd: 0, ms: 0, calls: 0, byClass: {} }])) as never;
+
+    const detail: unknown[] = [];
+    for (const { fx, arms } of rows) {
+        const d: Record<string, unknown> = { id: fx.id, defect_class: fx.defect_class, control: !!fx.negative_control };
+        for (const a of ARMS) {
+            const ar = arms[a];
+            const sc = score(fx, ar);
+            const pa = perArm[a];
+            pa.usd += ar.usd; pa.ms += ar.ms; pa.calls += ar.calls;
+            if (!fx.negative_control) {
+                pa.planted += 1;
+                if (sc.recall_hit) pa.recall += 1;
+                const c = (pa.byClass[fx.defect_class] ??= { hit: 0, n: 0 });
+                c.n += 1; if (sc.recall_hit) c.hit += 1;
+            } else if (sc.false_positive) {
+                pa.fp += 1;
+            }
+            d[a] = { recall_hit: sc.recall_hit, false_positive: sc.false_positive, claimed: sc.claimed, usd: Number(ar.usd.toFixed(4)), ms: ar.ms, error: ar.error, review: ar.text.slice(0, 1200) };
+        }
+        detail.push(d);
+    }
+
+    const recallRate = (a: ArmId): number => (perArm[a].planted ? perArm[a].recall / perArm[a].planted : 0);
+    const classRecall = (a: ArmId, classes: Set<string>): { hit: number; n: number } => {
+        let hit = 0, n = 0;
+        for (const [cls, c] of Object.entries(perArm[a].byClass)) if (classes.has(cls)) { hit += c.hit; n += c.n; }
+        return { hit, n };
+    };
+    const rr = (x: { hit: number; n: number }): number => (x.n ? x.hit / x.n : 0);
+
+    // Hypotheses (pre-registered thresholds).
+    const aCorr = classRecall('self-review', CORRECTNESS), bCorr = classRecall('team', CORRECTNESS);
+    const bDes = classRecall('team', DESIGN), cDes = classRecall('council', DESIGN);
+    const h1 = rr(bCorr) - rr(aCorr); // team - self on correctness; predict >= +0.20
+    const h2 = Math.abs(rr(cDes) - rr(bDes)); // council vs team on design; predict within 0.10
+    const h3ok = ARMS.every((a) => perArm[a].fp <= 1);
+
+    agg['preregistered'] = {
+        roadmap: 'road-to-team-mode Phase 5', authored: '2026-07-20',
+        primary: ['recall', 'false_positives', 'cost/time/calls'],
+        secondary: 'blind rubric judge — DEFERRED this pass (primary recall is deterministic)',
+        hypotheses: { H1: 'team>self on correctness, Δrecall>=+0.20', H2: 'council≈team on design, within 0.10', H3: 'FP<=1/arm on controls' },
+        codex_model: codexModel, models_cache_fetched: '2026-07-20T12:21Z',
+    };
+    agg['arms'] = Object.fromEntries(ARMS.map((a) => [a, {
+        recall_rate: Number(recallRate(a).toFixed(3)), recall: perArm[a].recall, planted: perArm[a].planted,
+        false_positives: perArm[a].fp, usd: Number(perArm[a].usd.toFixed(4)), ms: perArm[a].ms, calls: perArm[a].calls,
+        correctness_recall: Number(rr(classRecall(a, CORRECTNESS)).toFixed(3)),
+        design_recall: Number(rr(classRecall(a, DESIGN)).toFixed(3)),
+    }]));
+    const nullish = Math.abs(h1) <= 0.1 && h2 <= 0.1;
+    agg['verdict'] = {
+        H1_team_minus_self_correctness: Number(h1.toFixed(3)), H1_met: h1 >= 0.2,
+        H2_council_vs_team_design_absdelta: Number(h2.toFixed(3)), H2_met: h2 <= 0.1,
+        H3_fp_within_bound: h3ok,
+        honest_null: nullish,
+        disposition: nullish
+            ? 'HONEST NULL — arms indistinguishable within pre-registered thresholds; no lift claim binds.'
+            : h1 >= 0.2
+                ? 'LIFT on correctness-class — H1 met; a team-lift CLAIM may bind (maintainer decision).'
+                : 'MIXED — see per-class rates; no blanket lift claim.',
+    };
+    agg['total_billable_usd'] = Number((perArm['self-review'].usd + perArm.council.usd).toFixed(4));
+    agg['detail'] = detail;
+
+    fs.mkdirSync(path.dirname(OUT_JSON), { recursive: true });
+    fs.writeFileSync(OUT_JSON, JSON.stringify(agg, null, 2) + '\n');
+
+    const v = agg['verdict'] as Record<string, unknown>;
+    const md = [
+        '# Defect-finding benchmark — results (road-to-team-mode Phase 5)',
+        '', `> Run 2026-07-20. Codex reviewer: \`${codexModel}\`. Primary metric = deterministic`,
+        '> recall against corpus ground truth; blind rubric judge (secondary) deferred.',
+        '', '## Per-arm', '', '| arm | recall | correctness | design | false-pos | calls | $ |', '|---|--:|--:|--:|--:|--:|--:|',
+        ...ARMS.map((a) => {
+            const x = (agg['arms'] as Record<string, Record<string, number>>)[a] as Record<string, number>;
+            return `| ${a} | ${x.recall_rate} | ${x.correctness_recall} | ${x.design_recall} | ${x.false_positives} | ${x.calls} | ${x.usd} |`;
+        }),
+        '', '## Verdict', '',
+        `- H1 (team − self, correctness recall Δ): **${v.H1_team_minus_self_correctness}** — met: ${v.H1_met}`,
+        `- H2 (council vs team, design recall |Δ|): **${v.H2_council_vs_team_design_absdelta}** — met: ${v.H2_met}`,
+        `- H3 (false positives ≤ 1/arm): ${v.H3_fp_within_bound}`,
+        '', `**Disposition:** ${v.disposition}`,
+        '', `Total billable: $${agg['total_billable_usd']} (arm b codex = subscription, $0 billable).`,
+        '',
+    ].join('\n');
+    fs.writeFileSync(OUT_MD, md);
+    process.stdout.write(`\nwrote ${path.relative(ROOT, OUT_JSON)} + ${path.relative(ROOT, OUT_MD)}\n`);
+    process.stdout.write(`spent ~$${budget.spent.toFixed(4)} (cap $${cap})\n`);
+    return 0;
+}
+
+if (fs.existsSync(process.argv[1] ?? '') && import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/build_catalog_index.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+/**
+ * Build the lazy-catalog index — `dist/catalog-index-v1.json`.
+ *
+ * A queryable metadata index over every skill, persona, and domain command:
+ * `{ id, cls, name, description, tags, path }` — **metadata only, no bodies**.
+ * Bodies load lazily from disk at `catalog_load` time (the stdio server has the
+ * repo underneath it, unlike the upstream Hermes plugin which embeds bodies).
+ *
+ * Feeds the `catalog_search / _inspect / _load` MCP tools (built as discovery
+ * stubs; activation deferred behind a quality A/B — see
+ * road-to-persona-library-harvest.md Phase 2). Deterministic output (entries
+ * sorted by (cls, id), stable keys) so the artifact diffs cleanly. `--check`
+ * fails on drift instead of writing (CI mode), mirroring the
+ * build_mcp_registry_manifest convention.
+ */
+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);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+// The `-v1` namespace tracks `schema_version` below (per lint_versioned_cache):
+// bump both together on a shape change so any stale cached copy self-invalidates
+// by name rather than being read as the new shape.
+export const OUT = path.join(ROOT, 'dist', 'catalog-index-v1.json');
+
+export type CatalogClass = 'skill' | 'persona' | 'command';
+
+export interface CatalogIndexEntry {
+    /** Globally unique handle: `<cls>:<slug>`. */
+    id: string;
+    cls: CatalogClass;
+    name: string;
+    description: string;
+    /** Domain / packs / tier — for filtering and search-text weighting. */
+    tags: string[];
+    /** Repo-relative path to the body (resolved by catalog_load). */
+    path: string;
+}
+
+const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
+const PERSONAS_DIR = path.join(ROOT, 'src', 'agent-src', 'personas');
+const DOMAINS_DIR = path.join(ROOT, 'src', 'domains');
+
+function _isDir(p: string): boolean {
+    try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function _isFile(p: string): boolean {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+function _rel(abs: string): string {
+    return path.relative(ROOT, abs).split(path.sep).join('/');
+}
+
+function _frontmatter(abs: string): Record<string, unknown> {
+    const text = fs.readFileSync(abs, 'utf-8');
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (!m || m.index !== 0) return {};
+    try {
+        const fm = parseYaml(m[1] as string, { version: '1.1' });
+        return fm !== null && typeof fm === 'object' && !Array.isArray(fm) ? (fm as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+function _str(v: unknown): string {
+    return typeof v === 'string' ? v.trim() : v == null ? '' : String(v);
+}
+function _list(v: unknown): string[] {
+    if (Array.isArray(v)) return v.map((x) => _str(x)).filter((s) => s.length > 0);
+    const s = _str(v);
+    return s ? [s] : [];
+}
+
+function _walkLeaf(dir: string, leaf: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+        const full = path.join(dir, ent.name);
+        if (ent.isDirectory() || (ent.isSymbolicLink() && _isDir(full))) _walkLeaf(full, leaf, out);
+        else if (ent.name === leaf) out.push(full);
+    }
+}
+
+export function buildEntries(): CatalogIndexEntry[] {
+    const out: CatalogIndexEntry[] = [];
+
+    // Skills
+    if (_isDir(SKILLS_DIR)) {
+        for (const slug of fs.readdirSync(SKILLS_DIR).sort()) {
+            const abs = path.join(SKILLS_DIR, slug, 'SKILL.md');
+            if (!_isFile(abs)) continue;
+            const fm = _frontmatter(abs);
+            out.push({
+                id: `skill:${slug}`,
+                cls: 'skill',
+                name: _str(fm['name']) || slug,
+                description: _str(fm['description']),
+                tags: [_str(fm['domain']), ..._list(fm['packs'])].filter((s) => s.length > 0),
+                path: _rel(abs),
+            });
+        }
+    }
+
+    // Personas (top-level *.md, skip _template/advisors and underscore-prefixed)
+    if (_isDir(PERSONAS_DIR)) {
+        for (const name of fs.readdirSync(PERSONAS_DIR).sort()) {
+            if (!name.endsWith('.md') || name.startsWith('_')) continue;
+            const abs = path.join(PERSONAS_DIR, name);
+            if (!_isFile(abs)) continue;
+            const fm = _frontmatter(abs);
+            const id = _str(fm['id']) || name.replace(/\.md$/, '');
+            out.push({
+                id: `persona:${id}`,
+                cls: 'persona',
+                name: _str(fm['role']) || id,
+                description: _str(fm['description']),
+                tags: [_str(fm['tier']), _str(fm['mode'])].filter((s) => s.length > 0),
+                path: _rel(abs),
+            });
+        }
+    }
+
+    // Domain commands
+    const cmds: string[] = [];
+    _walkLeaf(DOMAINS_DIR, 'command.md', cmds);
+    for (const abs of cmds.sort()) {
+        const fm = _frontmatter(abs);
+        // logical id = <pack>/<subpath> under src/domains, without /command.md
+        const relFromDomains = path.relative(DOMAINS_DIR, path.dirname(abs)).split(path.sep).join('/');
+        const name = _str(fm['name']) || relFromDomains.split('/').pop() || relFromDomains;
+        out.push({
+            id: `command:${relFromDomains}`,
+            cls: 'command',
+            name,
+            description: _str(fm['description']) || _str(fm['intent']),
+            tags: [_str(fm['pack']), _str(fm['tier']), _str(fm['visibility'])].filter((s) => s.length > 0),
+            path: _rel(abs),
+        });
+    }
+
+    // Deterministic order: (cls, id).
+    out.sort((a, b) => (a.cls < b.cls ? -1 : a.cls > b.cls ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return out;
+}
+
+export function serialize(entries: CatalogIndexEntry[]): string {
+    return JSON.stringify({ schema_version: 1, count: entries.length, entries }, null, 2) + '\n';
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const check = args.includes('--check');
+    const quiet = args.includes('--quiet');
+    const entries = buildEntries();
+    const rendered = serialize(entries);
+
+    if (check) {
+        const current = _isFile(OUT) ? fs.readFileSync(OUT, 'utf-8') : '';
+        if (current !== rendered) {
+            process.stderr.write(`build_catalog_index: DRIFT — ${_rel(OUT)} is stale; run build_catalog_index to regenerate.\n`);
+            return 1;
+        }
+        if (!quiet) process.stdout.write(`build_catalog_index: OK — ${entries.length} entries, index up to date.\n`);
+        return 0;
+    }
+
+    fs.mkdirSync(path.dirname(OUT), { recursive: true });
+    fs.writeFileSync(OUT, rendered, 'utf-8');
+    if (!quiet) process.stdout.write(`build_catalog_index: wrote ${entries.length} entries → ${_rel(OUT)}\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch { return false; }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/council_cli.ts

@@ -98,7 +98,9 @@ import {
 } from './ai_council/orchestrator.js';
 import {
     type PriceTable,
+    downgrade_coupling,
     estimate_cost,
+    estimate_input_tokens,
     load_prices,
     prices_file_for,
 } from './ai_council/pricing.js';
@@ -1605,7 +1607,8 @@ function _necessity_gate(opts: {
 function _resolve_model_downgrade(ai_cfg: Dict, lens: string): [boolean, boolean] {
     const md_block = (ai_cfg['model_downgrade'] as Dict) || {};
     let enabled = md_block['enabled'] === undefined ? true : Boolean(_pyBool(md_block['enabled']));
-    let auto_apply = md_block['auto_apply'] === undefined ? false : Boolean(_pyBool(md_block['auto_apply']));
+    // A3: auto-downgrade is the default; `auto_apply: false` is the opt-out.
+    let auto_apply = md_block['auto_apply'] === undefined ? true : Boolean(_pyBool(md_block['auto_apply']));
     const overrides = ((ai_cfg['lens_overrides'] as Dict) || {})['model_downgrade'] || {};
     const lens_override = _isDict(overrides) ? (overrides as Dict)[lens] : null;
     if (_isDict(lens_override)) {
@@ -1622,6 +1625,10 @@ function _size_fit_gate(opts: {
     members: ExternalAIClient[];
     ai_cfg: Dict;
     stdout?: ((s: string) => void) | null;
+    /** Planned rounds for the run; expected same-model cache reads = rounds − 1. */
+    rounds?: number;
+    /** Price table for the A1↔A3 cache-coupling gate; null → coupling skipped. */
+    price_table?: PriceTable | null;
 }): Array<[string, SizeFitVerdict, boolean]> {
     const out = opts.stdout ?? _stdout;
     const [enabled, auto_apply] = _resolve_model_downgrade(opts.ai_cfg, opts.lens);
@@ -1629,8 +1636,25 @@ function _size_fit_gate(opts: {
     if (!enabled) {
         return decisions;
     }
+    const md_block = (opts.ai_cfg['model_downgrade'] as Dict) || {};
+    const tier_override = (md_block['model_tier_override'] as Dict) || {};
+    const cache_enabled = opts.ai_cfg['prompt_cache'] !== false;
+    const expected_reads = Math.max(0, (opts.rounds ?? 1) - 1);
     const members_cfg = (opts.ai_cfg['members'] as Dict) || {};
     for (const member of opts.members) {
+        // Per-run escape hatch: a member pinned in model_tier_override gets
+        // exactly that model — classifier and coupling both skipped.
+        const pinned = tier_override[member.name];
+        if (typeof pinned === 'string' && pinned.length > 0) {
+            if (pinned !== member.model) {
+                out(
+                    `council:size-fit · ${member.name} · model_tier_override ` +
+                        `\`${member.model}\` → \`${pinned}\` (operator pin)\n`,
+                );
+                member.model = pinned;
+            }
+            continue;
+        }
         const member_cfg = (members_cfg[member.name] as Dict) || {};
         const ladder = (member_cfg['model_ladder'] as string[]) || [];
         if (ladder.length === 0) {
@@ -1639,6 +1663,35 @@ function _size_fit_gate(opts: {
         const verdict = classify_size_fit(opts.prompt, member.model, ladder, opts.lens);
         let applied = false;
         if (!verdict.fit && verdict.suggested_model) {
+            // A1↔A3 coupling: a downgraded member misses the model-scoped
+            // prompt cache — downgrade only when the model saving beats the
+            // forfeited cache reads. No price table → conservative skip is
+            // wrong for the cost goal, so coupling only gates when computable.
+            if (opts.price_table) {
+                const prefix_tokens = estimate_input_tokens(opts.prompt);
+                const coupling = downgrade_coupling(
+                    member.name,
+                    member.model,
+                    verdict.suggested_model,
+                    prefix_tokens,
+                    4096,
+                    {
+                        enabled: cache_enabled,
+                        cacheable_prefix_tokens: prefix_tokens,
+                        expected_reads,
+                    },
+                    opts.price_table,
+                );
+                if (!coupling.net_positive) {
+                    out(
+                        `council:size-fit · ${member.name} · downgrade skipped — ` +
+                            `lost cache savings $${coupling.lost_cache_savings_usd.toFixed(4)} ` +
+                            `≥ model savings $${coupling.downgrade_savings_usd.toFixed(4)}\n`,
+                    );
+                    decisions.push([member.name, verdict, false]);
+                    continue;
+                }
+            }
             if (auto_apply) {
                 out(
                     `council:size-fit · ${member.name} · auto-downgrade ` +
@@ -1845,6 +1898,8 @@ function cmd_run(
         lens: question.mode,
         members,
         ai_cfg,
+        rounds: _getattr(args, 'rounds', 1) as number,
+        price_table: table,
     });
     const project = detect_project_context(REPO_ROOT);
     const billable = members.filter((m) => _getattr(m, 'billable', true));

package/src/scripts/generate_index.ts

@@ -232,7 +232,10 @@ export function _collect_skills(): Entry[] {
                 kind: 'skill',
                 name,
                 description: _truncate(fm['description'] ?? ''),
-                extra: '',
+                // Provenance: `official` unless the skill declares
+                // `provenance: community` (external contribution — credited in
+                // CREDITS.md; the catalog column makes the credit visible).
+                extra: fm['provenance'] ?? 'official',
                 path: _relativeToPosix(skillMd, ROOT),
             });
         }
@@ -372,7 +375,7 @@ export function _render_index(
         '',
         `## Skills (${skills.length})`,
         '',
-        _render_table(skills, ['kind', 'name', 'extra', 'description'], '../'),
+        _render_table(skills, ['kind', 'name', 'source', 'description'], '../'),
         '',
         `## Rules (${rules.length})`,
         '',
@@ -428,7 +431,7 @@ export function _render_catalog(
         '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
         '> floor bounds liability, not correctness — see [the proof page](proof.md).',
         '',
-        _render_table(skills, ['kind', 'name', 'extra', 'description'], '../', _to_shipped_path),
+        _render_table(skills, ['kind', 'name', 'source', 'description'], '../', _to_shipped_path),
         '',
         `## Rules (${publicRules.length})`,
         '',