@nac3/forge-cli 0.2.0-alpha.4 → 0.2.0-alpha.59z.118

package/dist/office/word.js

@@ -0,0 +1,243 @@
+/**
+ * F106 office.word verbs -- cross-platform Word read/write.
+ *
+ * Read: uses `mammoth` (already in deps for the document-reader
+ * pipeline) to extract text + a heading outline from a .docx file.
+ * Write: builds a minimal .docx file by hand (Office Open XML
+ * minimal subset) -- no extra deps. Covers headings + paragraphs.
+ *
+ * This sticks to plain content. Tables / images / styles are out of
+ * scope for the first cut. Adopters that need rich docs can drop
+ * to lower-level docx libs themselves.
+ *
+ * ASCII-only source. The .docx output IS binary (ZIP).
+ */
+import { readFile, writeFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { deflateRawSync } from 'node:zlib';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import mammoth from 'mammoth';
+const MAX_BYTES_READ = 16 * 1024 * 1024; /* 16 MB */
+const MAX_SECTIONS_WRITE = 50_000;
+const MAX_SECTION_TEXT = 100_000;
+function resolveSafePath(p, projectRoot) {
+    return path.isAbsolute(p) ? p : path.join(projectRoot, p);
+}
+export async function readWord(req, projectRoot = process.cwd()) {
+    if (!req.path || typeof req.path !== 'string') {
+        return { ok: false, error: 'invalid_args', detail: 'path is required' };
+    }
+    const abs = resolveSafePath(req.path, projectRoot);
+    let buf;
+    try {
+        const s = await stat(abs);
+        if (!s.isFile())
+            return { ok: false, error: 'not_a_file', detail: abs };
+        if (s.size > MAX_BYTES_READ) {
+            return { ok: false, error: 'file_too_large', detail: s.size + ' > ' + MAX_BYTES_READ };
+        }
+        buf = await readFile(abs);
+    }
+    catch (err) {
+        return { ok: false, error: 'read_failed', detail: err instanceof Error ? err.message : String(err) };
+    }
+    let extracted;
+    try {
+        extracted = await mammoth.extractRawText({ buffer: buf });
+    }
+    catch (err) {
+        return { ok: false, error: 'parse_failed', detail: err instanceof Error ? err.message : String(err) };
+    }
+    const text = extracted.value || '';
+    const warnings = (extracted.messages || []).map((m) => m.type + ': ' + m.message);
+    const outline = [];
+    if (req.include_outline !== false) {
+        /* mammoth extractRawText loses heading metadata; we re-run with
+         *  HTML conversion for outline detection. Best-effort. */
+        try {
+            const html = await mammoth.convertToHtml({ buffer: buf });
+            const re = /<h([1-6])[^>]*>(.*?)<\/h\1>/gi;
+            let m;
+            while ((m = re.exec(html.value)) !== null) {
+                const level = parseInt(m[1] || '1', 10);
+                const t = (m[2] || '').replace(/<[^>]+>/g, '').trim();
+                if (t)
+                    outline.push({ level, text: t });
+            }
+        }
+        catch { /* outline is best-effort; ignore */ }
+    }
+    return { ok: true, text, outline, warnings, byte_size: buf.length };
+}
+/* ===========================================================
+ * Minimal .docx builder
+ * .docx is a ZIP archive with a specific XML layout. We build
+ * the minimum viable file with [Content_Types].xml + _rels +
+ * word/document.xml. No styles xml -- Word renders our
+ * paragraphs / headings with built-in styles.
+ * =========================================================== */
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let j = 0; j < 8; j++) {
+            c = c & 1 ? 0xEDB88320 ^ (c >>> 1) : c >>> 1;
+        }
+        t[i] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xFFFFFFFF;
+    for (let i = 0; i < buf.length; i++) {
+        c = CRC32_TABLE[(c ^ buf[i]) & 0xFF] ^ (c >>> 8);
+    }
+    return (c ^ 0xFFFFFFFF) >>> 0;
+}
+function buildZip(entries) {
+    const localParts = [];
+    const centralParts = [];
+    let offset = 0;
+    for (const e of entries) {
+        const nameBuf = Buffer.from(e.name, 'utf-8');
+        const uncompressed = e.data;
+        const compressed = deflateRawSync(uncompressed);
+        const crc = crc32(uncompressed);
+        const compMethod = 8; /* deflate */
+        const local = Buffer.alloc(30 + nameBuf.length);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4); /* version needed */
+        local.writeUInt16LE(0, 6); /* general purpose */
+        local.writeUInt16LE(compMethod, 8);
+        local.writeUInt16LE(0, 10); /* mtime */
+        local.writeUInt16LE(0, 12); /* mdate */
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(uncompressed.length, 22);
+        local.writeUInt16LE(nameBuf.length, 26);
+        local.writeUInt16LE(0, 28); /* extra len */
+        nameBuf.copy(local, 30);
+        const localBlock = Buffer.concat([local, compressed]);
+        localParts.push(localBlock);
+        const central = Buffer.alloc(46 + nameBuf.length);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4); /* version made by */
+        central.writeUInt16LE(20, 6); /* version needed */
+        central.writeUInt16LE(0, 8); /* general purpose */
+        central.writeUInt16LE(compMethod, 10);
+        central.writeUInt16LE(0, 12); /* mtime */
+        central.writeUInt16LE(0, 14); /* mdate */
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(compressed.length, 20);
+        central.writeUInt32LE(uncompressed.length, 24);
+        central.writeUInt16LE(nameBuf.length, 28);
+        central.writeUInt16LE(0, 30); /* extra len */
+        central.writeUInt16LE(0, 32); /* comment len */
+        central.writeUInt16LE(0, 34); /* disk number */
+        central.writeUInt16LE(0, 36); /* internal attr */
+        central.writeUInt32LE(0, 38); /* external attr */
+        central.writeUInt32LE(offset, 42); /* relative offset */
+        nameBuf.copy(central, 46);
+        centralParts.push(central);
+        offset += localBlock.length;
+    }
+    const centralDir = Buffer.concat(centralParts);
+    const localBuf = Buffer.concat(localParts);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(0, 4); /* disk */
+    eocd.writeUInt16LE(0, 6); /* central dir disk */
+    eocd.writeUInt16LE(entries.length, 8);
+    eocd.writeUInt16LE(entries.length, 10);
+    eocd.writeUInt32LE(centralDir.length, 12);
+    eocd.writeUInt32LE(localBuf.length, 16); /* central dir offset */
+    eocd.writeUInt16LE(0, 20); /* comment len */
+    return Buffer.concat([localBuf, centralDir, eocd]);
+}
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function buildDocumentXml(sections) {
+    const parts = [];
+    parts.push('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>');
+    parts.push('<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">');
+    parts.push('<w:body>');
+    for (const sec of sections) {
+        const text = xmlEscape(sec.text || '');
+        if (sec.kind === 'heading') {
+            const level = sec.level && sec.level >= 1 && sec.level <= 6 ? sec.level : 1;
+            parts.push('<w:p><w:pPr><w:pStyle w:val="Heading' + level + '"/></w:pPr>'
+                + '<w:r><w:t xml:space="preserve">' + text + '</w:t></w:r></w:p>');
+        }
+        else {
+            parts.push('<w:p><w:r><w:t xml:space="preserve">' + text + '</w:t></w:r></w:p>');
+        }
+    }
+    parts.push('</w:body></w:document>');
+    return parts.join('');
+}
+const CONTENT_TYPES_XML = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    + '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+    + '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+    + '<Default Extension="xml" ContentType="application/xml"/>'
+    + '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
+    + '</Types>';
+const RELS_XML = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    + '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    + '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>'
+    + '</Relationships>';
+export async function writeWord(req, projectRoot = process.cwd()) {
+    if (!req.path || typeof req.path !== 'string') {
+        return { ok: false, error: 'invalid_args', detail: 'path is required' };
+    }
+    if (!Array.isArray(req.sections)) {
+        return { ok: false, error: 'invalid_args', detail: 'sections must be an array' };
+    }
+    if (req.sections.length > MAX_SECTIONS_WRITE) {
+        return { ok: false, error: 'too_many_sections', detail: req.sections.length + ' > ' + MAX_SECTIONS_WRITE };
+    }
+    for (const s of req.sections) {
+        if (!s || typeof s !== 'object') {
+            return { ok: false, error: 'invalid_section', detail: 'each section must be an object' };
+        }
+        if (s.kind !== 'heading' && s.kind !== 'paragraph') {
+            return { ok: false, error: 'invalid_section', detail: 'kind must be heading or paragraph' };
+        }
+        if (typeof s.text !== 'string') {
+            return { ok: false, error: 'invalid_section', detail: 'text must be a string' };
+        }
+        if (s.text.length > MAX_SECTION_TEXT) {
+            return { ok: false, error: 'section_too_long', detail: s.text.length + ' > ' + MAX_SECTION_TEXT };
+        }
+    }
+    if (!req.path.toLowerCase().endsWith('.docx')) {
+        return { ok: false, error: 'unsupported_extension', detail: 'only .docx output is supported' };
+    }
+    const abs = resolveSafePath(req.path, projectRoot);
+    if (!req.overwrite) {
+        try {
+            await stat(abs);
+            return { ok: false, error: 'file_exists', detail: 'pass overwrite=true to replace' };
+        }
+        catch { /* missing is expected good path */ }
+    }
+    const docXml = buildDocumentXml(req.sections);
+    const zip = buildZip([
+        { name: '[Content_Types].xml', data: Buffer.from(CONTENT_TYPES_XML, 'utf-8') },
+        { name: '_rels/.rels', data: Buffer.from(RELS_XML, 'utf-8') },
+        { name: 'word/document.xml', data: Buffer.from(docXml, 'utf-8') },
+    ]);
+    try {
+        await writeFile(abs, zip);
+    }
+    catch (err) {
+        return { ok: false, error: 'fs_write_failed', detail: err instanceof Error ? err.message : String(err) };
+    }
+    return { ok: true, path: abs, bytes_written: zip.length, section_count: req.sections.length };
+}
+//# sourceMappingURL=word.js.map

package/dist/office/word.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"word.js","sourceRoot":"","sources":["../../src/office/word.ts"],"names":[],"mappings":"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"}

package/dist/qa/brain_matrix/ab_runner.d.ts

@@ -0,0 +1,44 @@
+import type { Scenario, BrainConfig, ScenarioReport } from './types.js';
+import type { FakeResponse } from './fake_brain.js';
+export interface ABResult {
+    scenario_id: string;
+    brain_id: string;
+    a: ScenarioReport;
+    b: ScenarioReport;
+    /** Invariant pass count diff: b - a. Negative = regression. */
+    invariants_delta: number;
+    /** Token spend ratio: b / a. >1.25 considered too expensive. */
+    token_ratio: number;
+    /** True iff B is at least as good as A by all measures. */
+    promote_ok: boolean;
+    /** Human-readable reason (one short line). */
+    verdict: string;
+}
+interface ABScenarioExtension {
+    ab_test?: {
+        /** Override scenario.fake_responses for the A side. */
+        mode_a_responses?: FakeResponse[];
+        /** Override scenario.fake_responses for the B side. */
+        mode_b_responses?: FakeResponse[];
+        /** Optional: extra invariants only checked in mode B (e.g.
+         *  "must call doctrine.discover before reasoning"). */
+        extra_invariants_b?: Scenario['invariants'];
+        /** Override the default token ratio cap (1.25). Use for
+         *  "worst-case discovery" scenarios where B is expected to
+         *  spend 2-3x in tokens but the population average is still
+         *  a win because most turns do not trigger discovery. The
+         *  promotion decision aggregates across all scenarios. */
+        token_ratio_cap?: number;
+    };
+}
+export declare function runAB(scenario: Scenario & ABScenarioExtension, brain: BrainConfig): Promise<ABResult | null>;
+export interface ABMatrixResult {
+    generated_at: string;
+    results: ABResult[];
+    /** True iff every cell promote_ok=true. Gates promotion. */
+    promote_ok: boolean;
+}
+export declare function runABMatrix(scenarios: Array<Scenario & ABScenarioExtension>, brains: BrainConfig[]): Promise<ABMatrixResult>;
+export declare function renderABReport(matrix: ABMatrixResult): string;
+export {};
+//# sourceMappingURL=ab_runner.d.ts.map

package/dist/qa/brain_matrix/ab_runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab_runner.d.ts","sourceRoot":"","sources":["../../../src/qa/brain_matrix/ab_runner.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EACV,QAAQ,EAAE,WAAW,EAAE,cAAc,EACtC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,EAAE,cAAc,CAAC;IAClB,CAAC,EAAE,cAAc,CAAC;IAClB,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,mBAAmB;IAC3B,OAAO,CAAC,EAAE;QACR,uDAAuD;QACvD,gBAAgB,CAAC,EAAE,YAAY,EAAE,CAAC;QAClC,uDAAuD;QACvD,gBAAgB,CAAC,EAAE,YAAY,EAAE,CAAC;QAClC;+DACuD;QACvD,kBAAkB,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;QAC5C;;;;kEAI0D;QAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAQD,wBAAsB,KAAK,CACzB,QAAQ,EAAE,QAAQ,GAAG,mBAAmB,EACxC,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA2E1B;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,KAAK,CAAC,QAAQ,GAAG,mBAAmB,CAAC,EAChD,MAAM,EAAE,WAAW,EAAE,GACpB,OAAO,CAAC,cAAc,CAAC,CAczB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAiB7D"}

package/dist/qa/brain_matrix/ab_runner.js

@@ -0,0 +1,144 @@
+/**
+ * A/B runner (alpha.59z.0).
+ *
+ * Each "promotion candidate" alpha removes a block from the
+ * system prompt and exposes its content via yujin.doctrine.discover
+ * or a new verb. The risk: the LLM might regress (forget the rule,
+ * hallucinate a verb, redundant-confirm, etc) because it cannot
+ * "see" the block until it asks for it.
+ *
+ * The A/B harness validates that mode B (NAC3-on-demand) is at
+ * least as good as mode A (block in prompt) for every scenario.
+ *
+ * Rule:
+ *  - Mode A: original prompt + scenario.fake_responses for mode A
+ *  - Mode B: trimmed prompt + scenario.fake_responses for mode B
+ *  - Both runs evaluated against the SAME invariants.
+ *  - PASS iff invariantsPassA <= invariantsPassB (B at least equal).
+ *  - PASS also iff tokens_B <= tokens_A * 1.25 (B not absurdly more
+ *    expensive even if invariants equal).
+ *  - FAIL otherwise -> caller must rollback.
+ *
+ * Scenario shape: an existing fixture can declare an optional
+ * `ab_test` object with `mode_a_responses` and `mode_b_responses`
+ * (overrides fake_responses for each side). When absent the A/B
+ * is skipped (only relevant for promotion candidates).
+ *
+ * ASCII-only.
+ */
+import { runScenarioOnBrain, } from './runner.js';
+const DEFAULT_TOKEN_CAP = 1.25;
+function countPass(invariants) {
+    return invariants.filter((i) => i.pass).length;
+}
+export async function runAB(scenario, brain) {
+    if (!scenario.ab_test)
+        return null;
+    const baseFake = scenario.fake_responses || [];
+    /* Build the A and B scenario copies with overridden fake_responses. */
+    const scenA = {
+        ...scenario,
+        fake_responses: scenario.ab_test.mode_a_responses ?? baseFake,
+    };
+    const scenB = {
+        ...scenario,
+        fake_responses: scenario.ab_test.mode_b_responses ?? baseFake,
+        invariants: [
+            ...scenario.invariants,
+            ...(scenario.ab_test.extra_invariants_b ?? []),
+        ],
+    };
+    const a = await runScenarioOnBrain(scenA, brain);
+    const b = await runScenarioOnBrain(scenB, brain);
+    /* B has the common invariants PLUS extras. The first
+     *  scenario.invariants.length entries are common; the rest are
+     *  the extras. Score them separately so an extra failing in B
+     *  counts as regression even though A never had that bar. */
+    const commonCount = scenario.invariants.length;
+    const commonPassA = countPass(a.invariants.slice(0, commonCount));
+    const commonPassB = countPass(b.invariants.slice(0, commonCount));
+    const extraInvariantsB = b.invariants.slice(commonCount);
+    const extraPassB = countPass(extraInvariantsB);
+    const extraTotalB = extraInvariantsB.length;
+    const passA = countPass(a.invariants);
+    const passB = countPass(b.invariants);
+    const totA = a.invariants.length;
+    const totB = b.invariants.length;
+    const invariants_delta = passB - passA;
+    /* If either side had zero tokens (no LLM call), set ratio to 1. */
+    const tA = a.run.total_tokens_out + a.run.total_tokens_in;
+    const tB = b.run.total_tokens_out + b.run.total_tokens_in;
+    const token_ratio = tA > 0 ? tB / tA : 1;
+    let promote_ok = true;
+    let verdict = 'B at least equal to A';
+    if (a.run.error || b.run.error) {
+        promote_ok = false;
+        verdict = 'run error: a=' + (a.run.error || 'ok') + ' / b=' + (b.run.error || 'ok');
+    }
+    else if (commonPassB < commonPassA) {
+        promote_ok = false;
+        verdict = 'common invariant regression: a=' + commonPassA + '/' + commonCount
+            + ', b=' + commonPassB + '/' + commonCount;
+    }
+    else if (extraTotalB > 0 && extraPassB < extraTotalB) {
+        promote_ok = false;
+        verdict = 'extra-B invariant regression: ' + extraPassB + '/' + extraTotalB
+            + ' B-only invariants passed';
+    }
+    else if (token_ratio > (scenario.ab_test?.token_ratio_cap ?? DEFAULT_TOKEN_CAP)) {
+        promote_ok = false;
+        const cap = scenario.ab_test?.token_ratio_cap ?? DEFAULT_TOKEN_CAP;
+        verdict = 'token spend regressed: b/a=' + token_ratio.toFixed(2) + ' (cap ' + cap.toFixed(2) + ')';
+    }
+    else if (passB === passA && extraTotalB === 0) {
+        verdict = 'equivalent (a=' + passA + '/' + totA + ', b=' + passB + '/' + totB + ')';
+    }
+    else {
+        verdict = 'B improved (a=' + passA + '/' + totA + ', b=' + passB + '/' + totB + ')';
+    }
+    return {
+        scenario_id: scenario.id,
+        brain_id: brain.id,
+        a, b,
+        invariants_delta,
+        token_ratio,
+        promote_ok,
+        verdict,
+    };
+}
+export async function runABMatrix(scenarios, brains) {
+    const results = [];
+    for (const s of scenarios) {
+        if (!s.ab_test)
+            continue;
+        for (const b of brains) {
+            const r = await runAB(s, b);
+            if (r)
+                results.push(r);
+        }
+    }
+    return {
+        generated_at: new Date().toISOString(),
+        results,
+        promote_ok: results.every((r) => r.promote_ok),
+    };
+}
+export function renderABReport(matrix) {
+    const lines = [];
+    lines.push('# A/B promotion report');
+    lines.push('');
+    lines.push('Generated: ' + matrix.generated_at);
+    lines.push('Cells:     ' + matrix.results.length);
+    lines.push('Promote:   ' + (matrix.promote_ok ? 'OK -- all cells passed' : 'FAIL -- one or more cells regressed'));
+    lines.push('');
+    lines.push('| Scenario | Brain | Inv A | Inv B | Tok ratio | Verdict |');
+    lines.push('|---|---|---|---|---|---|');
+    for (const r of matrix.results) {
+        const aP = countPass(r.a.invariants) + '/' + r.a.invariants.length;
+        const bP = countPass(r.b.invariants) + '/' + r.b.invariants.length;
+        lines.push('| ' + r.scenario_id + ' | ' + r.brain_id + ' | ' + aP + ' | ' + bP
+            + ' | ' + r.token_ratio.toFixed(2) + ' | ' + r.verdict + ' |');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=ab_runner.js.map

package/dist/qa/brain_matrix/ab_runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab_runner.js","sourceRoot":"","sources":["../../../src/qa/brain_matrix/ab_runner.ts"],"names":[],"mappings":"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"}

package/dist/qa/brain_matrix/brains.json

@@ -0,0 +1,80 @@
+{
+  "_doc": "Brain matrix QA -- providers/models to test against. ASCII only. Edit to add/remove brains. The harness skips brains whose vault_slot is empty (no API key configured). `fake` is the dry-run brain used in CI; it never makes network calls.",
+  "brains": [
+    {
+      "id": "fake-scripted",
+      "provider": "fake",
+      "model": "scripted",
+      "tier": "eco",
+      "vault_slot": "",
+      "notes": "Dry-run fake brain. Tests the harness itself without spending money. Reads scripted responses from the scenario fixture's `fake_responses` field."
+    },
+    {
+      "id": "gemini-flash-lite",
+      "provider": "google_ai",
+      "model": "gemini-2.5-flash-lite",
+      "tier": "eco",
+      "vault_slot": "GEMINI_API_KEY",
+      "notes": "Eco. ~$0.10/1M in, ~$0.40/1M out. Fast, smallest context handling."
+    },
+    {
+      "id": "haiku-4-5",
+      "provider": "anthropic",
+      "model": "claude-haiku-4-5-20251001",
+      "tier": "eco",
+      "vault_slot": "CLAUDE_API_KEY",
+      "notes": "Eco. ~$1/1M in, ~$5/1M out. Anthropic small model."
+    },
+    {
+      "id": "sonnet-4-6",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4-6",
+      "tier": "frontier",
+      "vault_slot": "CLAUDE_API_KEY",
+      "notes": "Frontier mid. ~$3/1M in, ~$15/1M out. Default Forge brain."
+    },
+    {
+      "id": "opus-4-7",
+      "provider": "anthropic",
+      "model": "claude-opus-4-7",
+      "tier": "frontier",
+      "vault_slot": "CLAUDE_API_KEY",
+      "notes": "Frontier top. ~$15/1M in, ~$75/1M out. Skip default to save $$.",
+      "skip_default": true
+    },
+    {
+      "id": "opus-4-8",
+      "provider": "anthropic",
+      "model": "claude-opus-4-8",
+      "tier": "frontier",
+      "vault_slot": "CLAUDE_API_KEY",
+      "notes": "Frontier top, released after 4-7. Incorporates effort indicator (low/medium/high/extra/max) and complex reasoning. Skip default to save $$ (manual invoke via --brains opus-4-8).",
+      "skip_default": true
+    },
+    {
+      "id": "deepseek-v3",
+      "provider": "deepseek",
+      "model": "deepseek-chat",
+      "tier": "eco",
+      "vault_slot": "DEEPSEEK_API_KEY",
+      "notes": "Eco. Cheap multilingual."
+    },
+    {
+      "id": "gpt-4o-mini",
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "tier": "eco",
+      "vault_slot": "OPENAI_API_KEY",
+      "notes": "Eco. ~$0.15/1M in, ~$0.60/1M out."
+    },
+    {
+      "id": "gpt-4o",
+      "provider": "openai",
+      "model": "gpt-4o",
+      "tier": "frontier",
+      "vault_slot": "OPENAI_API_KEY",
+      "notes": "Frontier alt. Skip default to save $$.",
+      "skip_default": true
+    }
+  ]
+}

package/dist/qa/brain_matrix/compare.d.ts

@@ -0,0 +1,27 @@
+import type { MatrixReport } from './types.js';
+export type Outcome = 'PASS' | 'FAIL' | 'ERR' | 'MISSING';
+export interface CompareCell {
+    scenario: string;
+    brain: string;
+    base: Outcome;
+    head: Outcome;
+    /** 'regression' (PASS->FAIL/ERR), 'improvement' (FAIL/ERR->PASS),
+     *  'unchanged' (same outcome), 'flake' (FAIL<->ERR), 'new'
+     *  (only present in head), 'removed' (only in base). */
+    kind: 'regression' | 'improvement' | 'unchanged' | 'flake' | 'new' | 'removed';
+}
+export interface CompareSummary {
+    base_version: string;
+    head_version: string;
+    cells: CompareCell[];
+    regressions: CompareCell[];
+    improvements: CompareCell[];
+    flakes: CompareCell[];
+    new_cells: CompareCell[];
+    removed_cells: CompareCell[];
+    unchanged_count: number;
+}
+export declare function compareMatrices(base: MatrixReport, head: MatrixReport): CompareSummary;
+export declare function loadMatrixReport(p: string): Promise<MatrixReport>;
+export declare function renderCompareSummary(c: CompareSummary): string;
+//# sourceMappingURL=compare.d.ts.map

package/dist/qa/brain_matrix/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/qa/brain_matrix/compare.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAK,MAAM,CAAC;IACpB,KAAK,EAAQ,MAAM,CAAC;IACpB,IAAI,EAAS,OAAO,CAAC;IACrB,IAAI,EAAS,OAAO,CAAC;IACrB;;4DAEwD;IACxD,IAAI,EAAS,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;CACvF;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAK,MAAM,CAAC;IACxB,YAAY,EAAK,MAAM,CAAC;IACxB,KAAK,EAAY,WAAW,EAAE,CAAC;IAC/B,WAAW,EAAM,WAAW,EAAE,CAAC;IAC/B,YAAY,EAAK,WAAW,EAAE,CAAC;IAC/B,MAAM,EAAW,WAAW,EAAE,CAAC;IAC/B,SAAS,EAAQ,WAAW,EAAE,CAAC;IAC/B,aAAa,EAAI,WAAW,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAUD,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,cAAc,CAmCtF;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAGvE;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAuD9D"}