@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/dist/holmes/cli/init.js

@@ -46,6 +46,7 @@ const playbook_skills_1 = require("./playbook-skills");
 const agents_1 = require("./agents");
 const roles_readme_1 = require("./roles-readme");
 const mcp_launcher_1 = require("./mcp-launcher");
+const codex_toml_1 = require("./codex-toml");
 const pre_tool_use_1 = require("../hooks/pre-tool-use");
 const governed_precondition_1 = require("./governed-precondition");
 const risk_gate_1 = require("../guardrail/risk-gate");
@@ -343,6 +344,71 @@ function runInit(opts) {
         }
         messages.push('Restart Claude Code — hooks and MCP servers are read at session start.');
     }
+    // @implements A-SPEC-266 — Codex reads MCP servers from `.codex/config.toml` (TOML
+    // `[mcp_servers.*]`), NOT the `.codex/mcp_config.json` (JSON) this project used to write and Codex
+    // never loaded. That file also holds the user's other Codex settings, so — like `.mcp.json` — we
+    // MERGE only our table. The obsolete JSON is migrated away so no dead wiring is left behind.
+    let codexJsonToMigrate = null; // deleted only after the write loop confirms config.toml
+    {
+        const codexDir = path.join(opts.target, '.codex');
+        const codexTomlPath = path.join(codexDir, 'config.toml');
+        const codexJsonPath = path.join(codexDir, 'mcp_config.json');
+        // A `.codex/config.toml` we cannot read (a directory, a permission wall, a dangling symlink) is
+        // NOT touched — reading it eagerly with readFileSync threw and crashed the whole init. Mirror the
+        // `.mcp.json` "refusing to touch it" discipline: skip codex wiring and say so, migrate nothing.
+        let codexTomlBefore = null;
+        let codexUnreadable = false;
+        if (fs.existsSync(codexTomlPath)) {
+            try {
+                codexTomlBefore = fs.readFileSync(codexTomlPath, 'utf8');
+            }
+            catch {
+                codexUnreadable = true;
+            }
+        }
+        const wantsCodex = (opts.agents ?? []).includes('codex') && !codexUnreadable;
+        if (codexUnreadable)
+            messages.push(`Refusing to touch ${codexTomlPath} — it is not a readable file. Fix or remove it, then re-run.`);
+        // @implements A-SPEC-266 (round-2 F3) — the obsolete JSON is deleted AFTER the config.toml write is
+        // confirmed, never before: an eager delete followed by a failed toml write left the user with NO
+        // codex wiring at all (and a message claiming nothing was lost). Here we only PLAN the migration;
+        // the deletion runs post-write-loop (dry-run just previews it in `removals`).
+        const migrateAwayCodexJson = () => {
+            if (!fs.existsSync(codexJsonPath))
+                return;
+            if (opts.dryRun) {
+                removals.push(codexJsonPath);
+                return;
+            }
+            codexJsonToMigrate = codexJsonPath;
+        };
+        if (opts.remove) {
+            if (codexTomlBefore !== null) {
+                const after = (0, codex_toml_1.removeCodexToml)(codexTomlBefore);
+                if (after.trim() === '' && after !== codexTomlBefore) {
+                    // Our table was the only content — delete the file rather than leave it empty.
+                    if (opts.dryRun)
+                        removals.push(codexTomlPath);
+                    else if (fs.existsSync(codexTomlPath)) {
+                        fs.rmSync(codexTomlPath, { force: true });
+                        messages.push(`Removed ${codexTomlPath} (holmes-kit MCP table was its only content).`);
+                    }
+                }
+                else if (after !== codexTomlBefore) {
+                    changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
+                }
+            }
+            migrateAwayCodexJson();
+        }
+        else if (wantsCodex && opts.mcp) {
+            const mcpBin = path.join(opts.packageRoot, 'bin', 'holmes-mcp.js');
+            const entry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
+            const after = (0, codex_toml_1.mergeCodexToml)(codexTomlBefore, (0, codex_toml_1.codexMcpBlock)(entry, opts.specsDir));
+            if (after !== codexTomlBefore)
+                changes.push({ path: codexTomlPath, before: codexTomlBefore, after });
+            migrateAwayCodexJson();
+        }
+    }
     if (opts.dryRun) {
         // @implements A-SPEC-190 (round 8) — dry-run must plan the SAME set the real run touches, and
         // must not print a deletion under the verb 'would write'. Round-7 planned installs only from
@@ -422,6 +488,18 @@ function runInit(opts) {
                     ] };
             }
         }
+        // @implements A-SPEC-266 (round-2 F3) — the config.toml write above is confirmed now, so it is
+        // safe to remove the obsolete JSON. Doing it earlier risked deleting codex's only wiring and then
+        // failing the toml write.
+        if (codexJsonToMigrate !== null && fs.existsSync(codexJsonToMigrate)) {
+            try {
+                fs.rmSync(codexJsonToMigrate, { force: true });
+                messages.push(`Removed obsolete ${codexJsonToMigrate} (Codex never read it — MCP wiring now lives in config.toml).`);
+            }
+            catch (e) {
+                messages.push(`Could not remove obsolete ${codexJsonToMigrate}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         if (!opts.remove && opts.mode === 'governed') {
             for (const d of SPEC_SUBDIRS)
                 fs.mkdirSync(path.join(opts.target, opts.specsDir, d), { recursive: true });

package/dist/holmes/cli/interactive-prompt.js

@@ -52,12 +52,12 @@ function parseAgentList(input) {
 /**
  * Renders an interactive TTY checkbox selection menu using standard readline & ANSI codes.
  */
-async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWired = ['claude']) {
+async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWired = [...agents_1.AGENTS]) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        return ['claude', 'antigravity']; // Fallback for non-TTY
+        return [...availableAgents]; // Fallback for non-TTY — default to all harnesses
     }
     return new Promise((resolve) => {
-        const selected = new Set(currentWired.length ? currentWired : ['claude', 'antigravity']);
+        const selected = new Set(currentWired.length ? currentWired : [...availableAgents]);
         let cursor = 0;
         const items = [...availableAgents, 'all'];
         const rl = readline.createInterface({
@@ -91,7 +91,7 @@ async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWi
                 }
                 else if (item === 'codex') {
                     isChecked = selected.has('codex');
-                    label = '💻 Codex CLI            (.codex/mcp_config.json)';
+                    label = '💻 Codex CLI            (.codex/config.toml)';
                 }
                 const box = isChecked ? '[X]' : '[ ]';
                 const line = `${prefix}${box} ${label}\n`;

package/dist/holmes/cli/mcp-launcher.d.ts

@@ -1,8 +1,8 @@
 /**
  * MCP 서버 배선의 launch 방식을 한 곳에서 계산한다.
  *
- * 왜 한 곳인가: `.mcp.json`(Claude)·`.agents/mcp_config.json`(antigravity)·`.codex/mcp_config.json`
- * 세 배선이 같은 서버를 띄운다. 셋이 각자 command/args 를 지으면 하나가 npx 로 옮겨갈 때 나머지가
+ * 왜 한 곳인가: `.mcp.json`(Claude)·`.agents/mcp_config.json`(antigravity)·`.codex/config.toml`
+ * (codex, TOML `[mcp_servers.holmes-kit]` — A-SPEC-266) 세 배선이 같은 서버를 띄운다. 셋이 각자 command/args 를 지으면 하나가 npx 로 옮겨갈 때 나머지가
  * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-251 자체의 출발점이었다.
  *
  * 왜 두 모드인가: 최종 사용자는 npm 설치본에서 init 하므로 `npx ...@<정확한버전> holmes-mcp` 가

package/dist/holmes/cli/semantic-key.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `holmes-kit semantic-key set|unset|status` — the human's consent act for the cloud semantic
+ * tier, made convenient AND safe:
+ *
+ * - `set` reads the key from STDIN (hidden prompt on a TTY, one piped line otherwise). The key
+ *   never appears in argv — ps and shell history are exactly the surfaces a third-party PC leaks
+ *   from. Storage prefers the OS keychain (darwin, fed over stdin too) and falls back to
+ *   ~/.holmes/credentials.json at 0600 under 0700.
+ * - `status` prints the SOURCE only. The value never appears in any output — the same promise
+ *   doctor's ledger-signing check already makes for HOLMES_LEDGER_KEY.
+ * - `unset` clears both stores.
+ */
+import { type CredentialOpts } from '../semantic/credentials';
+export interface SemanticKeyIo {
+    /** Resolves one secret line. The default hides TTY echo; tests inject. */
+    readSecret: (prompt: string) => Promise<string>;
+    write: (line: string) => void;
+}
+export declare function runSemanticKey(sub: string | undefined, io?: SemanticKeyIo, cred?: CredentialOpts): Promise<number>;

package/dist/holmes/cli/semantic-key.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSemanticKey = runSemanticKey;
+// @implements A-SPEC-477
+/**
+ * `holmes-kit semantic-key set|unset|status` — the human's consent act for the cloud semantic
+ * tier, made convenient AND safe:
+ *
+ * - `set` reads the key from STDIN (hidden prompt on a TTY, one piped line otherwise). The key
+ *   never appears in argv — ps and shell history are exactly the surfaces a third-party PC leaks
+ *   from. Storage prefers the OS keychain (darwin, fed over stdin too) and falls back to
+ *   ~/.holmes/credentials.json at 0600 under 0700.
+ * - `status` prints the SOURCE only. The value never appears in any output — the same promise
+ *   doctor's ledger-signing check already makes for HOLMES_LEDGER_KEY.
+ * - `unset` clears both stores.
+ */
+const credentials_1 = require("../semantic/credentials");
+const defaultIo = {
+    readSecret: (prompt) => new Promise((resolve, reject) => {
+        process.stderr.write(prompt);
+        const chunks = [];
+        const stdin = process.stdin;
+        if (stdin.isTTY) {
+            stdin.setRawMode?.(true);
+            stdin.resume();
+            let buf = '';
+            const onData = (d) => {
+                const c = d.toString('utf8');
+                if (c === '\r' || c === '\n' || c === '') {
+                    stdin.setRawMode?.(false);
+                    stdin.pause();
+                    stdin.off('data', onData);
+                    process.stderr.write('\n');
+                    resolve(buf);
+                }
+                else if (c === '') {
+                    stdin.setRawMode?.(false);
+                    stdin.pause();
+                    stdin.off('data', onData);
+                    reject(new Error('aborted'));
+                }
+                else if (c === '' || c === '\b') {
+                    buf = buf.slice(0, -1);
+                }
+                else {
+                    buf += c; // no echo — the hiding IS the point
+                }
+            };
+            stdin.on('data', onData);
+        }
+        else {
+            stdin.on('data', (d) => chunks.push(Buffer.from(d)));
+            stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8').split('\n')[0] ?? ''));
+            stdin.on('error', reject);
+        }
+    }),
+    write: (line) => process.stdout.write(line + '\n'),
+};
+const SOURCE_LABEL = {
+    'env': 'HOLMES_SEMANTIC_API_KEY (환경변수)',
+    'env-compat': 'GEMINI_API_KEY (환경변수)',
+    'keychain': 'macOS 키체인 (holmes-kit/semantic)',
+    'file': '~/.holmes/credentials.json (0600)',
+};
+async function runSemanticKey(sub, io = defaultIo, cred = {}) {
+    if (sub === 'set') {
+        const key = (await io.readSecret('cloud semantic 티어 API 키 입력(표시되지 않음): ')).trim();
+        if (key === '') {
+            io.write('빈 키는 저장하지 않습니다.');
+            return 2;
+        }
+        const where = (0, credentials_1.storeSemanticKey)(key, cred);
+        io.write(`저장됨: ${SOURCE_LABEL[where]} — 키 설정은 이그레스(스펙 산문·경로·심볼명 외부 전송) 동의입니다. 값은 어떤 출력에도 표시되지 않습니다.`);
+        return 0;
+    }
+    if (sub === 'unset') {
+        (0, credentials_1.removeSemanticKey)(cred);
+        io.write('semantic 키 제거됨 (키체인·파일 양쪽).');
+        return 0;
+    }
+    if (sub === 'status' || sub === undefined) {
+        const r = (0, credentials_1.resolveSemanticKey)(cred);
+        if (r === null) {
+            io.write('semantic 키: 없음 — cloud 티어 비활성. `holmes-kit semantic-key set` 으로 opt-in 하십시오(키 설정 = 이그레스 동의).');
+        }
+        else {
+            io.write(`semantic 키: 설정됨 — 출처 ${SOURCE_LABEL[r.source]}. 값은 표시되지 않습니다.`);
+        }
+        return 0;
+    }
+    io.write(`unknown subcommand: ${sub} (set|unset|status)`);
+    return 2;
+}

package/dist/holmes/config/config.d.ts

@@ -3,6 +3,15 @@ export interface AxConfig {
         enforcement: 'block' | 'warn' | 'off';
         enforceHighRisk: boolean;
         overrideRequiresAdr: boolean;
+        /**
+         * @implements A-SPEC-278
+         * Pre-edit impact evidence enforcement. Defaults to `off` — unlike `enforcement`, whose strict
+         * default is the safe posture, the safe default HERE is off: switching it on changes the working
+         * discipline of every session in the repository, and that belongs to the repository's owner.
+         * A malformed config also lands here, so a broken file can neither weaken governance nor
+         * silently impose a new one.
+         */
+        preEditEvidence: 'off' | 'warn' | 'block';
     };
     highRiskDomains: string[];
     storage: {

package/dist/holmes/config/config.js

@@ -35,12 +35,19 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_CONFIG = void 0;
 exports.loadConfig = loadConfig;
+// @implements A-SPEC-278
 // @implements A-SPEC-125.5
 // src/holmes/config/config.ts
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 exports.DEFAULT_CONFIG = {
-    guardrail: { enforcement: 'block', enforceHighRisk: true, overrideRequiresAdr: true },
+    // @implements A-SPEC-332
+    // `warn`, not `off` and not `block`. Off left Phase 2 present in code and absent in behaviour;
+    // block would refuse every source edit today, because `.ax/evidence` is empty (n=0) and the gate's
+    // first refusal is `no-analysis`. Warn reports the missing evidence without stopping work, which
+    // is also the only path that accumulates the data a later block decision would need. Raised as an
+    // authority question rather than decided by measurement — the user chose this level.
+    guardrail: { enforcement: 'block', enforceHighRisk: true, overrideRequiresAdr: true, preEditEvidence: 'warn' },
     highRiskDomains: ['@auth', '@payment'],
     storage: { specStore: 'local-markdown' },
 };

package/dist/holmes/cpg/language-capability.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What the extractor actually recovers, per language.
+ *
+ * Goal Phase 4 requires that per-language coverage and its limits always travel with the result.
+ * They did not, and the capability is genuinely uneven — measured with fixtures 2026-08-28, symbols
+ * come out of every advertised language, `imports` only out of Python and TypeScript-family files,
+ * and `inherits` out of NONE of them, not even where the declaration is completely unambiguous
+ * (`class Child(Base)`, `extends Base`).
+ *
+ * The problem was never the unevenness; it was the silence. Coverage reported only extensions
+ * OUTSIDE the scannable set, so an impact answer over a Java file looked exactly as trustworthy as
+ * one over Python while resting on strictly less evidence, and every downstream answer inherited
+ * that asymmetry without anyone being told.
+ *
+ * This table is pinned against the real scanner by fixtures in the sibling test. If it drifts from
+ * reality in either direction that test fails — a capability table that cannot fail guarantees
+ * nothing.
+ */
+export declare const EXTRACTABLE_RELATIONS: readonly ["calls", "imports", "inherits"];
+export type ExtractableRelation = typeof EXTRACTABLE_RELATIONS[number];
+export interface LanguageCapability {
+    symbols: boolean;
+    /** What the SCANNER recovers from the source text. */
+    relations: ExtractableRelation[];
+    /**
+     * @implements A-SPEC-286
+     * What actually becomes a GRAPH edge — always a subset of `relations`.
+     *
+     * These are different claims and conflating them misleads. Measured 2026-08-28: the scanner emits
+     * 1,892 `imports` edges of which zero reach the graph, because their target is a module path
+     * rather than a symbol and the builder resolves symbol-to-symbol relations only. Everything
+     * downstream — impact, localization, the pre-edit gate — queries the graph, so the graph column is
+     * the one a coverage claim has to be made in.
+     */
+    graphResolved: ExtractableRelation[];
+}
+export declare const LANGUAGE_CAPABILITY: Record<string, LanguageCapability>;
+export declare function capabilityFor(ext: string): LanguageCapability | undefined;
+export interface LanguageGap {
+    ext: string;
+    /** Relation kinds this language's extractor does NOT recover at all. */
+    missing: ExtractableRelation[];
+    /**
+     * @implements A-SPEC-286
+     * Recovered by the scanner but never resolved into a graph edge. A distinct fact from `missing`:
+     * the information exists and is still unusable to anything that queries the graph.
+     */
+    extractedButUnresolved: ExtractableRelation[];
+}
+/**
+ * The capability gaps for the languages ACTUALLY present in a scan.
+ *
+ * Only languages that appear are listed: enumerating every language the tool could theoretically
+ * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
+ * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
+ */
+export declare function capabilityGapsFor(sourcePaths: readonly string[]): LanguageGap[];
+/** Every advertised extension must have an entry; a blank would be a silent overclaim. */
+export declare const ADVERTISED_EXTENSIONS: readonly string[];
+/**
+ * An unknown extension gets a family of its own rather than joining a shared bucket: an unfamiliar
+ * language must not be able to take another language's definitions. Narrowing is the safe direction
+ * — it costs recall, which is disclosed, instead of asserting something false.
+ */
+export declare function languageFamilyOf(ext: string): string;

package/dist/holmes/cpg/language-capability.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADVERTISED_EXTENSIONS = exports.LANGUAGE_CAPABILITY = exports.EXTRACTABLE_RELATIONS = void 0;
+exports.capabilityFor = capabilityFor;
+exports.capabilityGapsFor = capabilityGapsFor;
+exports.languageFamilyOf = languageFamilyOf;
+// @implements A-SPEC-289
+// @implements A-SPEC-288
+// @implements A-SPEC-287
+// @implements A-SPEC-286
+// @implements A-SPEC-285
+const path = __importStar(require("node:path"));
+const cpg_scanner_1 = require("./cpg-scanner");
+/**
+ * What the extractor actually recovers, per language.
+ *
+ * Goal Phase 4 requires that per-language coverage and its limits always travel with the result.
+ * They did not, and the capability is genuinely uneven — measured with fixtures 2026-08-28, symbols
+ * come out of every advertised language, `imports` only out of Python and TypeScript-family files,
+ * and `inherits` out of NONE of them, not even where the declaration is completely unambiguous
+ * (`class Child(Base)`, `extends Base`).
+ *
+ * The problem was never the unevenness; it was the silence. Coverage reported only extensions
+ * OUTSIDE the scannable set, so an impact answer over a Java file looked exactly as trustworthy as
+ * one over Python while resting on strictly less evidence, and every downstream answer inherited
+ * that asymmetry without anyone being told.
+ *
+ * This table is pinned against the real scanner by fixtures in the sibling test. If it drifts from
+ * reality in either direction that test fails — a capability table that cannot fail guarantees
+ * nothing.
+ */
+exports.EXTRACTABLE_RELATIONS = ['calls', 'imports', 'inherits'];
+// @implements A-SPEC-288 — `extends` joins Python's inheritance; `implements` stays a stated gap.
+// @implements A-SPEC-289 — imports now resolve to FILE nodes when the specifier is relative and
+// names a scanned file; bare specifiers stay external and unresolved by design.
+const TS_FAMILY = { symbols: true, relations: ['calls', 'imports', 'inherits'], graphResolved: ['calls', 'imports', 'inherits'] };
+/** Symbols and calls only — no import edges, no inheritance. */
+const CALLS_ONLY = { symbols: true, relations: ['calls'], graphResolved: ['calls'] };
+exports.LANGUAGE_CAPABILITY = {
+    '.ts': TS_FAMILY, '.mts': TS_FAMILY, '.cts': TS_FAMILY, '.tsx': TS_FAMILY,
+    '.js': TS_FAMILY, '.mjs': TS_FAMILY, '.jsx': TS_FAMILY,
+    // CommonJS `require()` is not recovered as an import, unlike ESM `import` — measured.
+    '.cjs': CALLS_ONLY,
+    // @implements A-SPEC-286 — the first language whose inheritance is both extracted AND resolved.
+    '.py': { symbols: true, relations: ['calls', 'imports', 'inherits'], graphResolved: ['calls', 'imports', 'inherits'] },
+    '.java': CALLS_ONLY, '.cs': CALLS_ONLY, '.go': CALLS_ONLY, '.rs': CALLS_ONLY,
+    // @implements A-SPEC-287 — C++ used to extract calls that never became graph edges, because its
+    // edge scope omitted the class node the symbol walk uses. Fixed; it now resolves like the others.
+    '.cpp': CALLS_ONLY, '.cc': CALLS_ONLY, '.cxx': CALLS_ONLY,
+    '.hpp': CALLS_ONLY, '.hh': CALLS_ONLY, '.h': CALLS_ONLY,
+};
+function capabilityFor(ext) {
+    return exports.LANGUAGE_CAPABILITY[ext.toLowerCase()];
+}
+/**
+ * The capability gaps for the languages ACTUALLY present in a scan.
+ *
+ * Only languages that appear are listed: enumerating every language the tool could theoretically
+ * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
+ * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
+ */
+function capabilityGapsFor(sourcePaths) {
+    const present = new Set();
+    for (const p of sourcePaths) {
+        const ext = path.extname(p).toLowerCase();
+        if (capabilityFor(ext))
+            present.add(ext);
+    }
+    return [...present].sort()
+        .map((ext) => {
+        const cap = capabilityFor(ext);
+        return {
+            ext,
+            missing: exports.EXTRACTABLE_RELATIONS.filter((r) => !cap.relations.includes(r)),
+            extractedButUnresolved: cap.relations.filter((r) => !cap.graphResolved.includes(r)),
+        };
+    })
+        .filter((gap) => gap.missing.length > 0 || gap.extractedButUnresolved.length > 0);
+}
+/** Every advertised extension must have an entry; a blank would be a silent overclaim. */
+exports.ADVERTISED_EXTENSIONS = cpg_scanner_1.SCANNABLE_EXTENSIONS;
+// @implements A-SPEC-300
+/**
+ * Extensions that can actually call each other, grouped.
+ *
+ * Name resolution links a call to a definition when the name is defined in exactly one file. That
+ * rule had no notion of language, and measured on a five-language fixture (2026-08-28) it asserted
+ *   CODE:Child.run@Child.java --calls--> CODE:helper@lib.rs
+ * A Java method calling a Rust function. Worse, the correct target sat in the SAME file: it was
+ * missed on qualification, leaving the Rust definition as the only candidate, so the precision rule
+ * actively confirmed a wrong answer. A missing edge widens scope; a wrong edge narrows it onto the
+ * wrong place.
+ *
+ * The groups follow real interop, not file-name similarity: TypeScript and JavaScript genuinely call
+ * each other, and a C++ implementation genuinely calls its header's declarations.
+ */
+const LANGUAGE_FAMILIES = {
+    '.ts': 'ts-js', '.mts': 'ts-js', '.cts': 'ts-js', '.tsx': 'ts-js',
+    '.js': 'ts-js', '.mjs': 'ts-js', '.jsx': 'ts-js', '.cjs': 'ts-js',
+    '.py': 'python',
+    '.java': 'java', '.cs': 'csharp', '.go': 'go', '.rs': 'rust',
+    '.cpp': 'cpp', '.cc': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp', '.hh': 'cpp', '.h': 'cpp',
+};
+/**
+ * An unknown extension gets a family of its own rather than joining a shared bucket: an unfamiliar
+ * language must not be able to take another language's definitions. Narrowing is the safe direction
+ * — it costs recall, which is disclosed, instead of asserting something false.
+ */
+function languageFamilyOf(ext) {
+    const lower = ext.toLowerCase();
+    return LANGUAGE_FAMILIES[lower] ?? `ext:${lower}`;
+}