@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/snapshot_agent_outputs.ts

@@ -0,0 +1,375 @@
+#!/usr/bin/env tsx
+/**
+ * Snapshot the agent-config build outputs for byte-identity verification.
+ *
+ * TypeScript twin of `src/scripts/snapshot_agent_outputs.py` (ADR-200,
+ * Phase 8 / Wave 8b). Mirrors the CLI contract EXACTLY — the `--out` flag,
+ * exit codes, the stdout/stderr split, byte-identical stdout AND the
+ * byte-identical written snapshot JSON (`json.dumps(indent=2,
+ * sort_keys=True, ensure_ascii=False) + "\n"`).
+ *
+ * Used by monorepo Phase 4 (physical layout move) to assert that the
+ * pre-move and post-move `task sync` + `task build-discovery` outputs
+ * match byte-for-byte except for `artefacts[].path` values.
+ *
+ * Captures sha256 of every file under:
+ *   - dist/agent-src/
+ *   - .augment/
+ *   - dist/discovery/discovery-manifest.json (also stores parsed copy
+ *     with paths stripped so the post-move diff is path-only)
+ *
+ * Also exported (the Python `_build_snapshot`, `_logical_path`, `_SKIP_DIRS`,
+ * `_SKIP_NAMES`) for `verify_physical_move.ts`, mirroring the Python
+ * `from snapshot_agent_outputs import (...)`.
+ *
+ * No behaviour changes — latent Python quirks replicated.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+// src/scripts/snapshot_agent_outputs.ts → parents[2] of the .py file is repo root.
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const DEFAULT_OUT = path.join(ROOT, 'dist', 'migration', 'pre-move-snapshot.json');
+
+const TARGETS: readonly string[] = [
+    path.join(ROOT, 'dist/agent-src'),
+    path.join(ROOT, '.augment'),
+];
+const MANIFEST = path.join(ROOT, 'dist', 'discovery', 'discovery-manifest.json');
+
+// Runtime artefacts that never participate in byte-identity verification.
+// Eval last-run.json + pytest caches are gitignored; including them just
+// adds noise when the worktree is clean.
+export const _SKIP_NAMES: ReadonlySet<string> = new Set(['last-run.json']);
+export const _SKIP_DIRS: ReadonlySet<string> = new Set([
+    '.pytest_cache',
+    '__pycache__',
+    '.mypy_cache',
+    '.ruff_cache',
+    'node_modules',
+    '.DS_Store',
+]);
+
+// JSON values mirroring the parsed manifest content.
+type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function _sha256(p: string): string {
+    const h = crypto.createHash('sha256');
+    h.update(fs.readFileSync(p));
+    return h.digest('hex');
+}
+
+/** POSIX relative path of `child` under `ROOT`. */
+function _relToRootPosix(child: string): string {
+    return path.relative(ROOT, child).split(path.sep).join('/');
+}
+
+/**
+ * Mirror Python `Path(child).relative_to(ROOT)` — throws when `child` is not
+ * under ROOT (the print site replicates the Python ValueError → exit 1; the
+ * traceback prose itself is Python-version-dependent and not matched).
+ */
+function _pyRelativeTo(child: string): string {
+    const rel = path.relative(ROOT, child);
+    if (rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) {
+        throw new Error(`'${child}' is not in the subpath of '${ROOT}'`);
+    }
+    return rel.split(path.sep).join('/');
+}
+
+/** `sorted(root.rglob("*"))` — every descendant path, pathlib-sorted. */
+function _rglobSorted(root: string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            out.push(full);
+            if (e.isDirectory() && !e.isSymbolicLink()) {
+                walk(full);
+            }
+        }
+    };
+    walk(root);
+    // Mirror pathlib's sorted() — component-wise lexicographic comparison.
+    out.sort(_pathCompare);
+    return out;
+}
+
+/** Mirror Python `sorted(Path…)` — component-wise comparison on POSIX parts. */
+function _pathCompare(a: string, b: string): number {
+    const pa = a.split(path.sep);
+    const pb = b.split(path.sep);
+    const n = Math.min(pa.length, pb.length);
+    for (let i = 0; i < n; i += 1) {
+        const x = pa[i] as string;
+        const y = pb[i] as string;
+        if (x < y) return -1;
+        if (x > y) return 1;
+    }
+    return pa.length - pb.length;
+}
+
+function _hash_tree(root: string): Record<string, string> {
+    if (!_exists(root)) {
+        return {};
+    }
+    const hashes: Record<string, string> = {};
+    for (const p of _rglobSorted(root)) {
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(p);
+        } catch {
+            continue;
+        }
+        if (!st.isFile()) {
+            continue;
+        }
+        const name = path.basename(p);
+        if (_SKIP_NAMES.has(name)) {
+            continue;
+        }
+        const parts = _relToRootPosix(p).split('/');
+        if (parts.some((part) => _SKIP_DIRS.has(part))) {
+            continue;
+        }
+        hashes[_relToRootPosix(p)] = _sha256(p);
+    }
+    return hashes;
+}
+
+/**
+ * Strip any source-root prefix (legacy or packages/*) so the diff
+ * compares the artefact's logical identity, not its physical location.
+ * Non-source paths are returned unchanged.
+ */
+export function _logical_path(rel: string): string {
+    const posix = rel.replace(/\\/g, '/');
+    if (posix.startsWith('.agent-src.uncondensed/')) {
+        return posix.slice('.agent-src.uncondensed/'.length);
+    }
+    if (posix.startsWith('packages/')) {
+        const marker = '/.agent-src.uncondensed/';
+        const idx = posix.indexOf(marker);
+        if (idx !== -1) {
+            return posix.slice(idx + marker.length);
+        }
+    }
+    return posix;
+}
+
+function _asObj(v: Json | undefined): { [k: string]: Json } | null {
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+        return v;
+    }
+    return null;
+}
+
+function _strField(v: Json | undefined): string {
+    return typeof v === 'string' ? v : '';
+}
+
+/** Mirror Python tuple-comparison sort key `(a, b)` on two string keys. */
+function _tupleCompare(a: [string, string], b: [string, string]): number {
+    if (a[0] < b[0]) return -1;
+    if (a[0] > b[0]) return 1;
+    if (a[1] < b[1]) return -1;
+    if (a[1] > b[1]) return 1;
+    return 0;
+}
+
+function _manifest_path_stripped(manifestPath: string): { [k: string]: Json } | null {
+    if (!_exists(manifestPath)) {
+        return null;
+    }
+    const data = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as { [k: string]: Json };
+    // Strip `path` from every artefact so the diff is path-only, then
+    // re-sort by (category, checksum) so the list order is content-stable.
+    const artefactsRaw = data['artefacts'];
+    const artefacts = Array.isArray(artefactsRaw) ? artefactsRaw : [];
+    for (const a of artefacts) {
+        const o = _asObj(a);
+        if (o) {
+            delete o['path'];
+        }
+    }
+    artefacts.sort((a, b) => {
+        const oa = _asObj(a);
+        const ob = _asObj(b);
+        return _tupleCompare(
+            [oa ? _strField(oa['category']) : '', oa ? _strField(oa['checksum']) : ''],
+            [ob ? _strField(ob['category']) : '', ob ? _strField(ob['checksum']) : ''],
+        );
+    });
+    data['artefacts'] = artefacts;
+    // Normalise unassigned / documented_unassigned to logical paths and
+    // re-sort so the post-move diff is content-only.
+    for (const key of ['unassigned', 'documented_unassigned']) {
+        const entriesRaw = data[key];
+        const entries = Array.isArray(entriesRaw) ? entriesRaw : [];
+        for (const e of entries) {
+            const o = _asObj(e);
+            if (o && 'path' in o) {
+                o['path'] = _logical_path(_strField(o['path']));
+            }
+        }
+        entries.sort((a, b) => {
+            const oa = _asObj(a);
+            const ob = _asObj(b);
+            return _tupleCompare(
+                [oa ? _strField(oa['path']) : '', oa ? _strField(oa['category']) : ''],
+                [ob ? _strField(ob['path']) : '', ob ? _strField(ob['category']) : ''],
+            );
+        });
+        data[key] = entries;
+    }
+    // Drop volatile fields.
+    delete data['generated_at'];
+    delete data['checksum'];
+    delete data['scanner_version'];
+    return data;
+}
+
+export interface Snapshot {
+    schema_version: string;
+    trees: Record<string, Record<string, string>>;
+    manifest_sha256: string | null;
+    manifest_path_stripped: { [k: string]: Json } | null;
+}
+
+export function _build_snapshot(): Snapshot {
+    const trees: Record<string, Record<string, string>> = {};
+    for (const tgt of TARGETS) {
+        const key = _relToRootPosix(tgt);
+        trees[key] = _hash_tree(tgt);
+    }
+    return {
+        schema_version: '1',
+        trees,
+        manifest_sha256: _exists(MANIFEST) ? _sha256(MANIFEST) : null,
+        manifest_path_stripped: _manifest_path_stripped(MANIFEST),
+    };
+}
+
+// --- json.dumps(indent=2, sort_keys=True, ensure_ascii=False) replica -------
+
+function _jsonDumps(obj: unknown): string {
+    const pad = '  ';
+    const enc = (value: unknown, depth: number): string => {
+        if (value === null || value === undefined) return 'null';
+        if (typeof value === 'boolean') return value ? 'true' : 'false';
+        if (typeof value === 'number') return String(value);
+        if (typeof value === 'string') return encStr(value);
+        if (Array.isArray(value)) {
+            if (value.length === 0) return '[]';
+            const inner = value.map((v) => pad.repeat(depth + 1) + enc(v, depth + 1));
+            return '[\n' + inner.join(',\n') + '\n' + pad.repeat(depth) + ']';
+        }
+        const o = value as Record<string, unknown>;
+        const keys = Object.keys(o).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        if (keys.length === 0) return '{}';
+        const inner = keys.map(
+            (k) => pad.repeat(depth + 1) + encStr(k) + ': ' + enc(o[k], depth + 1),
+        );
+        return '{\n' + inner.join(',\n') + '\n' + pad.repeat(depth) + '}';
+    };
+    const encStr = (s: string): string => {
+        // ensure_ascii=False — only escape the JSON-mandated control chars.
+        let out = '"';
+        for (const ch of s) {
+            const cp = ch.codePointAt(0) as number;
+            if (ch === '"') out += '\\"';
+            else if (ch === '\\') out += '\\\\';
+            else if (ch === '\n') out += '\\n';
+            else if (ch === '\r') out += '\\r';
+            else if (ch === '\t') out += '\\t';
+            else if (ch === '\b') out += '\\b';
+            else if (ch === '\f') out += '\\f';
+            else if (cp < 0x20) out += '\\u' + cp.toString(16).padStart(4, '0');
+            else out += ch;
+        }
+        return out + '"';
+    };
+    return enc(obj, 0);
+}
+
+interface ParsedArgs {
+    out: string;
+}
+
+function parse_args(argv: string[]): ParsedArgs {
+    const out: ParsedArgs = { out: DEFAULT_OUT };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--out' || a.startsWith('--out=')) {
+            const eq = a.indexOf('=');
+            if (eq !== -1) {
+                out.out = a.slice(eq + 1);
+            } else {
+                const next = argv[i + 1];
+                if (next === undefined) {
+                    process.stderr.write(
+                        'snapshot_agent_outputs: error: argument --out: expected one argument\n',
+                    );
+                    process.exit(2);
+                }
+                out.out = next;
+                i += 1;
+            }
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: snapshot_agent_outputs [-h] [--out OUT]\n');
+            process.exit(0);
+        }
+    }
+    return out;
+}
+
+export function main(argv: string[] | null = null): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    const snap = _build_snapshot();
+    fs.mkdirSync(path.dirname(args.out), { recursive: true });
+    fs.writeFileSync(args.out, _jsonDumps(snap) + '\n', 'utf-8');
+    let nFiles = 0;
+    for (const t of Object.values(snap.trees)) {
+        nFiles += Object.keys(t).length;
+    }
+    process.stdout.write(`Snapshot: ${_pyRelativeTo(path.resolve(args.out))}\n`);
+    process.stdout.write(`  files hashed     : ${nFiles}\n`);
+    process.stdout.write(`  trees            : ${_pyListRepr(Object.keys(snap.trees))}\n`);
+    const manifestSha = snap.manifest_sha256
+        ? snap.manifest_sha256.slice(0, 16)
+        : 'MISSING';
+    process.stdout.write(`  manifest sha256  : ${manifestSha}\n`);
+    return 0;
+}
+
+/** Mirror Python `str(list(...))` for a list of strings: `['a', 'b']`. */
+function _pyListRepr(items: string[]): string {
+    return '[' + items.map((s) => `'${s}'`).join(', ') + ']';
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/spotcheck_thin_root.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env tsx
+/** Phase 6.6 platform spot-check via AI council.
+ *
+ * TypeScript twin of `src/scripts/spotcheck_thin_root.py` (ADR-200, Phase 8 /
+ * Wave 8h). Mirrors the Python contract — no flags, exit 0, the two
+ * `Running … / ✅  Wrote …` stderr lines, and byte-identical written
+ * `thin-root-platform-spotcheck.md` / `.json`. No behaviour changes.
+ *
+ * Sends the refactored package-root AGENTS.md and the consumer template
+ * to Sonnet 4.5 + gpt-4o, asks each member to answer five questions
+ * that simulate a fresh agent landing on the file. Records qualitative
+ * verdicts in agents/runtime/reports/thin-root-platform-spotcheck.md.
+ *
+ * The live council step imports the `ai_council` TS twins directly in-process
+ * (`clients` — AnthropicClient / OpenAIClient / load_anthropic_key /
+ * load_openai_key; `orchestrator` — CostBudget / CouncilQuestion / consult;
+ * `pricing` — load_prices). The artefact assembly and report writing are
+ * deterministic. The script is non-deterministic by construction (live LLM
+ * latency / token counts), so it has no golden-parity path.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    AnthropicClient,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+} from './ai_council/clients.js';
+import { CostBudget, CouncilQuestion, consult } from './ai_council/orchestrator.js';
+import { load_prices } from './ai_council/pricing.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+// Python: ROOT = Path(__file__).resolve().parent.parent.parent
+const ROOT = path.resolve(_HERE, '..', '..', '..');
+
+const QUESTIONS = `
+You are evaluating whether the AGENTS.md file below is a sufficient
+entry point for an AI coding agent landing on this repository for
+the first time. You see only the AGENTS.md content; you do NOT have
+file-system access. Answer the following five questions in JSON
+shape \`{"q1": {...}, ..., "q5": {...}}\` where each value is
+\`{"answer": <string>, "confidence": "high"|"medium"|"low",
+"pointer_used": <one of the linked paths from AGENTS.md, or null>}\`.
+
+Q1. Where do I edit content in this repo / project? (a path)
+Q2. What command do I run to verify everything is green before opening a PR?
+Q3. Where would I find the always-active behavioural rules?
+Q4. If only this file is reachable, what five things must I assume to be true to act safely? (cite the emergency-triage block)
+Q5. What outboard target document would I open to learn the package-self-orientation / the consumer-fill-out guide? (a path)
+
+After the JSON, add a short prose verdict (≤ 5 sentences) on:
+- Whether the pointer-following worked (could you cite a path for Q1, Q3, Q5?)
+- Whether the emergency-triage block answered Q4 unambiguously.
+- One concrete improvement you'd make to the AGENTS.md.
+
+Do not invent file paths. If a question cannot be answered from the
+file alone, set \`"pointer_used": null\` and lower confidence.
+`.trim();
+
+interface ResponseRow {
+    provider: string;
+    model: string;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    latency_ms: number | null;
+    error: string | null;
+    text: string | null;
+}
+
+/**
+ * Run the live council in-process via the `ai_council` TS twins. Returns the
+ * council responses as plain rows. Mirrors the Python original's
+ * `consult(members, question, budget, table=table, rounds=1)` call exactly
+ * (same members, prompt, max_tokens, budget). `table` + `rounds` ride in the
+ * twin's `opts` argument.
+ */
+function _consultViaCouncil(artefact: string): ResponseRow[] {
+    const members = [
+        new AnthropicClient({ model: 'claude-sonnet-4-5', api_key: load_anthropic_key() }),
+        new OpenAIClient({ model: 'gpt-4o', api_key: load_openai_key() }),
+    ];
+    const question = new CouncilQuestion({ mode: 'files', user_prompt: artefact, max_tokens: 1500 });
+    const budget = new CostBudget({ max_total_usd: 2.0, max_calls: 4 });
+    const table = load_prices();
+    process.stderr.write('Running spot-check council …\n');
+    const responses = consult(members, question, budget, { table, rounds: 1 });
+    return responses.map((r) => ({
+        provider: r.provider,
+        model: r.model,
+        input_tokens: r.input_tokens,
+        output_tokens: r.output_tokens,
+        latency_ms: r.latency_ms,
+        error: r.error,
+        text: r.text,
+    }));
+}
+
+/** Python `json.dumps(raw, indent=2)` parity (ensure_ascii=True, no sort_keys). */
+function _pyJsonStr(s: string): string {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        if (ch === '"') {
+            out += '\\"';
+        } else if (ch === '\\') {
+            out += '\\\\';
+        } else if (ch === '\n') {
+            out += '\\n';
+        } else if (ch === '\r') {
+            out += '\\r';
+        } else if (ch === '\t') {
+            out += '\\t';
+        } else if (ch === '\b') {
+            out += '\\b';
+        } else if (ch === '\f') {
+            out += '\\f';
+        } else if (code < 0x20) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        } else if (code < 0x7f) {
+            out += ch;
+        } else if (code <= 0xffff) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        } else {
+            const c = code - 0x10000;
+            const hi = 0xd800 + (c >> 10);
+            const lo = 0xdc00 + (c & 0x3ff);
+            out += `\\u${hi.toString(16).padStart(4, '0')}\\u${lo.toString(16).padStart(4, '0')}`;
+        }
+    }
+    return out + '"';
+}
+
+type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+function pyJsonDumpsIndent2(obj: Json, level = 0): string {
+    if (obj === null || obj === undefined) {
+        return 'null';
+    }
+    if (typeof obj === 'number') {
+        return String(obj);
+    }
+    if (typeof obj === 'string') {
+        return _pyJsonStr(obj);
+    }
+    if (obj === true) {
+        return 'true';
+    }
+    if (obj === false) {
+        return 'false';
+    }
+    if (Array.isArray(obj)) {
+        if (obj.length === 0) {
+            return '[]';
+        }
+        const pad = ' '.repeat(2 * (level + 1));
+        const closePad = ' '.repeat(2 * level);
+        return `[\n${obj.map((v) => pad + pyJsonDumpsIndent2(v, level + 1)).join(',\n')}\n${closePad}]`;
+    }
+    const keys = Object.keys(obj as Record<string, Json>);
+    if (keys.length === 0) {
+        return '{}';
+    }
+    const pad = ' '.repeat(2 * (level + 1));
+    const closePad = ' '.repeat(2 * level);
+    const parts = keys.map(
+        (k) => `${pad}${_pyJsonStr(k)}: ${pyJsonDumpsIndent2((obj as Record<string, Json>)[k] as Json, level + 1)}`,
+    );
+    return `{\n${parts.join(',\n')}\n${closePad}}`;
+}
+
+export function main(): number {
+    const packageRoot = fs.readFileSync(path.join(ROOT, 'AGENTS.md'), 'utf-8');
+    const consumerTemplate = fs.readFileSync(
+        path.join(ROOT, '.agent-src.uncondensed', 'templates', 'AGENTS.md'),
+        'utf-8',
+    );
+
+    const artefact =
+        '## Artefact A — package-root AGENTS.md\n\n' +
+        `\`\`\`markdown\n${packageRoot}\n\`\`\`\n\n` +
+        '## Artefact B — consumer-template AGENTS.md\n\n' +
+        `\`\`\`markdown\n${consumerTemplate}\n\`\`\`\n\n` +
+        `${QUESTIONS}\n`;
+
+    const responses = _consultViaCouncil(artefact);
+
+    const outDir = path.join(ROOT, 'agents', 'reports');
+    fs.mkdirSync(outDir, { recursive: true });
+    const mdPath = path.join(outDir, 'thin-root-platform-spotcheck.md');
+    const jsonPath = path.join(outDir, 'thin-root-platform-spotcheck.json');
+
+    const mdLines: string[] = [
+        '# Thin-Root platform spot-check (Phase 6.6)',
+        '',
+        '> AI-council proxy for the manual platform spot-check. Two',
+        '> external reviewers (Sonnet 4.5, gpt-4o) simulate a fresh',
+        '> agent landing on the refactored AGENTS.md and answer five',
+        '> orientation questions from the file alone.',
+        '',
+        '## Verdicts',
+        '',
+    ];
+
+    const raw: Json[] = [];
+    for (const r of responses) {
+        const body = r.text || `<error: ${r.error}>`;
+        raw.push({
+            provider: r.provider,
+            model: r.model,
+            tokens_in: r.input_tokens,
+            tokens_out: r.output_tokens,
+            latency_ms: r.latency_ms,
+            error: r.error,
+            text: body,
+        });
+        mdLines.push(`### ${r.provider} (${r.model})`);
+        mdLines.push('');
+        mdLines.push(
+            `- tokens in: ${r.input_tokens} · out: ${r.output_tokens} · latency: ${r.latency_ms}ms`,
+        );
+        if (r.error) {
+            mdLines.push(`- error: \`${r.error}\``);
+        }
+        mdLines.push('');
+        mdLines.push('```');
+        mdLines.push(body.slice(0, 8000));
+        mdLines.push('```');
+        mdLines.push('');
+    }
+
+    fs.writeFileSync(mdPath, mdLines.join('\n'), 'utf-8');
+    fs.writeFileSync(jsonPath, pyJsonDumpsIndent2(raw), 'utf-8');
+    process.stderr.write(`✅  Wrote ${mdPath}\n`);
+    process.stderr.write(`✅  Wrote ${jsonPath}\n`);
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}

package/src/scripts/surface-tiers.yml

@@ -0,0 +1,68 @@
+# Surface-tier registry for src/scripts/ clusters
+#
+# road-to-install-contract-stability Phase 2. Single source of truth (council
+# 2026-06-17, claude-sonnet-4-5 + gpt-4o, converged Q2 = one central registry).
+#
+#   core = the lean stable multi-host engine that users install
+#          (install, condensation, rules/skills tooling, lint/check gates).
+#   lab  = experimental / pilot meta-tooling that must NOT destabilise the
+#          core install surface (council, MCP server, media pipelines,
+#          prediction-pool, cost analytics, chat-history, benchmarking).
+#
+# EXHAUSTIVE over src/scripts/*/ directories: scripts/check_surface_tiers.py
+# enumerates every cluster dir and fails CI if one is missing here, forcing the
+# tier decision at cluster-creation time. Top-level lab scripts are listed under
+# `lab_modules` so the core→lab boundary guard can resolve their tier; anything
+# not listed as lab defaults to core (install/condense/lint/check tooling).
+
+clusters:
+  # --- core: the lean engine ---
+  _cli: core             # CLI commands (doctor, upgrade, sync) — user-facing engine
+  _lib: core             # shared library for install / condense / CLI
+  adr: core              # ADR numbering + index tooling
+  config: core           # discovery vocabulary + pack registry
+  hooks: core            # runtime hooks (context hygiene, roadmap progress, guards)
+  repro: core            # reproduction fixtures for the engine
+  schemas: core          # JSON schemas for frontmatter validation
+  skill_tools: core      # skill scoring + persona/user-type coverage audits
+  smoke: core            # engine smoke tests
+  tools: core            # GitHub / Jira adapter stubs
+
+  # --- lab: experimental / pilot meta-tooling ---
+  _archive: lab          # archived / deprecated scripts, not on the production path
+  ai-image: lab          # AI image-generation adapters (pack ai-image, experimental)
+  ai-video: lab          # AI video pipeline adapters (pack ai-video, experimental)
+  ai_council: lab         # multi-model council orchestration, external API deps
+  command_suggester: lab # context-aware command suggestion engine, pilot
+  cost: lab              # cost tracking / budget gate (observability, Node .mjs)
+  mcp_server: lab        # MCP stdio server, separate runtime, pilot distribution
+  media: lab             # shared adapter substrate for ai-video / ai-image
+  prediction-pool: lab   # prediction-pool optimizer (fun pack, experimental)
+
+# Top-level src/scripts/*.py modules that belong to lab (module stem, no .py).
+# Used by the boundary guard to resolve `import <stem>` to the lab tier.
+# Unlisted top-level scripts default to core (install/condense/lint/check).
+lab_modules:
+  - council_cli          # council CLI entry point (scripts.ai_council.*)
+  - council_prune        # council session pruning
+  - update_prices        # refresh ai_council pricing table
+  - pattern_share        # pattern sharing (ai_council redaction)
+  - spotcheck_thin_root  # evidence spotcheck against ai_council
+  - chat_history         # chat-history engine
+  - mine_session         # session mining (chat-history dependent)
+  - mcp_render           # MCP renderer
+  - mcp_parity_smoke     # MCP smoke tests
+  - mcp_telemetry_health # MCP telemetry health
+  - mcp_telemetry_store  # MCP telemetry store
+  - mcp_telemetry_query  # MCP telemetry query
+  - pack_mcp_content     # packs MCP server content
+  - build_mcp_registry_manifest
+  - bench_run            # benchmarking runner (council clients)
+  - bench_ab_run         # A/B benchmarking runner
+  - bench_ab_v2_run      # V2 benchmark runner
+  - cost_by_conversation # cost analytics
+  - cost_summary         # cost summary
+  - build_cloud_bundle   # Claude.ai cloud-bundle builder (pilot distribution)
+  - build_linear_digest  # Linear digest builder (external service)
+  - memory_report        # memory health report
+  - memory_signal        # memory signal classifier