@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/cli/doctor.js

@@ -35,13 +35,19 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STRIPPED_FOR_PROBE = void 0;
 exports.globalInstallDir = globalInstallDir;
+exports.npmCliEntry = npmCliEntry;
 exports.prefixVerdict = prefixVerdict;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
 exports.formatChecks = formatChecks;
+exports.wiringHandshakeChecks = wiringHandshakeChecks;
+exports.semanticTierVerdict = semanticTierVerdict;
+exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
+// @implements A-SPEC-442
 // @implements A-SPEC-207
 // @implements A-SPEC-100.2
 const fs = __importStar(require("node:fs"));
+const tier_1 = require("../semantic/tier");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
@@ -52,7 +58,25 @@ const playbook_skills_1 = require("./playbook-skills");
 const init_1 = require("./init");
 const mcp_version_1 = require("./mcp-version");
 const codex_toml_1 = require("./codex-toml");
+const agents_1 = require("./agents");
 const mcp_launcher_1 = require("./mcp-launcher");
+/**
+ * Checks if a script path belongs to the packageRoot, supporting symlinked global installs.
+ */
+function resolvesToPackage(filePath, packageRoot) {
+    if (!filePath || !fs.existsSync(filePath))
+        return false;
+    try {
+        if (path.resolve(filePath).startsWith(path.resolve(packageRoot) + path.sep))
+            return true;
+        const realFile = fs.realpathSync(filePath);
+        const realPkg = fs.realpathSync(packageRoot);
+        return realFile.startsWith(realPkg + path.sep);
+    }
+    catch {
+        return false;
+    }
+}
 const GRAMMARS = [
     'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp', 'tree-sitter-java',
     'tree-sitter-go', 'tree-sitter-rust', 'tree-sitter-cpp',
@@ -83,6 +107,33 @@ function globalInstallDir(prefix, platform) {
         ? `${prefix.replace(/[\\/]+$/, '')}\\node_modules`
         : `${prefix.replace(/\/+$/, '')}/lib/node_modules`;
 }
+/**
+ * @implements A-SPEC-466 — W-5. npm's own JS entry, so the prefix probe can run it with THIS node
+ * binary instead of spawning the name 'npm' — which on Windows is a `.cmd` shim that execFileSync
+ * cannot start (ENOENT; naming the .cmd is EINVAL under Node's batch-file mitigation), leaving the
+ * global-prefix check a permanent WARN there.
+ *
+ * Candidates, in order: the `npm_execpath` this process was launched under (exact when running via
+ * npm/npx — guarded to npm-cli.js so an npx/yarn launcher is not mistaken for npm), then the two
+ * standard layouts next to the node binary — `<dir>\node_modules\npm` (Windows official,
+ * nvm-windows) and `<dir>/../lib/node_modules/npm` (POSIX standard, nvm). Homebrew's Cellar
+ * matches neither (measured) — null there, and the caller keeps the plain-'npm' spawn, which is
+ * today's behavior and has no .cmd problem on POSIX. env/execPath are injectable for tests only.
+ */
+function npmCliEntry(env = process.env, execPath = process.execPath) {
+    const fromEnv = env.npm_execpath;
+    if (fromEnv && path.basename(fromEnv) === 'npm-cli.js' && fs.existsSync(fromEnv))
+        return fromEnv;
+    const bin = path.dirname(execPath);
+    for (const cand of [
+        path.join(bin, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        path.join(bin, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ]) {
+        if (fs.existsSync(cand))
+            return cand;
+    }
+    return null;
+}
 /**
  * Judge the global prefix. Pure — the probing lives with the caller.
  *
@@ -252,6 +303,12 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     //    before it answers (a false FAIL this check produced on its first run).
     if (built) {
         checks.push(await mcpHandshakeCheck(packageRoot));
+        // @implements A-SPEC-323
+        // Every wired harness, actually started. The check above proves THIS INSTALL can serve; these
+        // prove the wiring each harness will really run reaches a server. Measured: 367ms for three.
+        // A doctor run with no target has no harness wiring to prove — skipped, not failed.
+        if (target)
+            checks.push(...await wiringHandshakeChecks(target));
     }
     // 7. Target wiring — do the configured commands point at THIS installed package and exist?
     if (target) {
@@ -276,7 +333,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             else {
                 const stale = cmds.filter((c) => {
                     const p = (0, settings_merge_1.hookScriptPath)(c);
-                    return !p || !fs.existsSync(p) || !path.resolve(p).startsWith(path.resolve(packageRoot) + path.sep);
+                    return !resolvesToPackage(p, packageRoot);
                 });
                 add('target wiring', stale.length === 0 ? 'PASS' : 'FAIL', stale.length === 0 ? `${cmds.length} holmes hook(s) resolve to this install` : `stale/foreign command(s): ${stale.join(' | ')}`, stale.length === 0 ? undefined : 'Re-run `holmes-kit init --force` in the target to refresh the absolute paths.');
             }
@@ -366,6 +423,53 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     // 8. Environment — presence only, never values (these hold out-of-band secrets).
     const present = ['HOLMES_SPECS', 'HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY', 'HOLMES_MCP_PROFILE']
         .map((k) => `${k}=${process.env[k] ? 'set' : 'unset'}`).join(' ');
+    // @implements A-SPEC-454
+    // The CONSEQUENCE, not the fact. `environment` already prints HOLMES_LEDGER_KEY=set|unset among
+    // three siblings, and that told nobody what it decides. Measured 2026-08-30: with no key the
+    // provenance chain is a plain hash chain, so appending a chain-valid `spec-approved` line with
+    // this package's own API silences ART-5 while chain.verify() still returns ok. A-SPEC-453's
+    // ledger comparison is then a COST — one more forged artifact — rather than a barrier.
+    //
+    // WARN, not FAIL: running unsigned is a deployment choice, and marking choices as failures
+    // teaches operators to skip doctor (the judgement A-SPEC-153 already made for role policy). WARN,
+    // not PASS: `codex gate` set the precedent — a thing that is wired but not yet enforcing is not
+    // a pass. Presence only; the value is an out-of-band secret and is never read into the report.
+    if (process.env.HOLMES_LEDGER_KEY) {
+        add('ledger signing', 'PASS', '원장이 HOLMES_LEDGER_KEY 로 서명됩니다 — 키 없는 위조자는 체인 정합한 spec-approved 기록을 만들 수 없습니다');
+    }
+    else {
+        add('ledger signing', 'WARN', '원장이 서명되지 않습니다(HOLMES_LEDGER_KEY 없음) — 체인이 평문 해시라 파일을 쓸 수 있는 자가 승인 기록도 만들 수 있고, ART-5 의 원장 대조는 장벽이 아니라 비용이 됩니다', 'HOLMES_LEDGER_KEY 를 대역외(에이전트를 기동하는 사람의 환경)에서 설정한 뒤 서버를 다시 시작하십시오. 값은 이 보고서에 절대 출력되지 않습니다.');
+    }
+    // @implements A-SPEC-457
+    // Whether the ART-2 truncation backstop (A-SPEC-455) is even armed. That backstop compares the
+    // committed ledger to the working copy and enumerates targets with `git ls-files .ax/ledger`; an
+    // UNTRACKED ledger yields an empty list, so truncation goes uncaught (measured 2026-08-30). The
+    // ledger is untracked whenever the .gitignore re-include is missing or the first ledger commit
+    // has not happened. Same silent-precondition gap as A-SPEC-454 (signing) — surface it, do not fix
+    // the user's .gitignore. Only when a ledger actually exists in a git repo; nothing to protect
+    // otherwise.
+    if (target !== undefined) {
+        try {
+            const ledgerDir = path.join(target, '.ax', 'ledger');
+            const onDisk = fs.existsSync(ledgerDir)
+                ? fs.readdirSync(ledgerDir).filter((f) => /^provenance[\w.-]*\.jsonl$/.test(f))
+                : [];
+            if (onDisk.length > 0) {
+                // Throws outside a git repo -> caught below -> no check added (no tracking concept).
+                const tracked = new Set((0, node_child_process_1.execFileSync)('git', ['ls-files', '.ax/ledger'], {
+                    cwd: target, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+                }).split('\n').map((l) => l.trim().split('/').pop()).filter(Boolean));
+                const untracked = onDisk.filter((f) => !tracked.has(f));
+                if (untracked.length > 0) {
+                    add('ledger tracked', 'WARN', `추적되지 않는 원장: ${untracked.join(', ')} — git 에 없어 ART-2 절단 백스톱(A-SPEC-455)이 이 파일에 대해 꺼져 있습니다. 원장을 통째로 비워도 Stop 게이트가 잡지 못합니다`, '.gitignore 에 `!.ax/ledger/provenance*.jsonl` 되살림 규칙을 두고 `git add -f .ax/ledger/provenance*.jsonl` 로 추적에 추가한 뒤 커밋하십시오.');
+                }
+                else {
+                    add('ledger tracked', 'PASS', '원장이 git 에 추적됩니다 — ART-2 절단 백스톱이 커밋된 이력을 기준으로 롤백을 잡습니다');
+                }
+            }
+        }
+        catch { /* not a git repo, or git unavailable: no tracking concept, no check */ }
+    }
     // @implements A-SPEC-153
     // Reports, never judges. Not having roles on is a choice, not a defect; a FAIL here would teach
     // operators that doctor's failures are noise, which costs more than this check is worth.
@@ -666,8 +770,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                         add('mcp wiring spawn', 'WARN', `.mcp.json carries no runnable ${init_1.SERVER_NAME} entry`, 'Run `holmes-kit init` in the target to write the wiring.');
                     }
                     else if (server.command === 'node') {
+                        // @implements A-SPEC-323
+                        // Existence only, and it no longer stands in for the handshake. This branch used to be
+                        // the whole check for the common wiring, so "the file is there" was reported as if the
+                        // server had been proven to start. `wiringHandshakeChecks` below now proves that, for
+                        // every wired harness; this stays as the cheap, fast FAIL for a path that is simply gone.
                         const bin = server.args[0] ?? '';
-                        add('mcp wiring spawn', fs.existsSync(bin) ? 'PASS' : 'FAIL', fs.existsSync(bin) ? `node wiring resolves: ${bin}` : `node wiring points at a missing file: ${bin}`, fs.existsSync(bin) ? undefined : 'Run `holmes-kit init` in the target to rewire the absolute path.');
+                        add('mcp wiring spawn', fs.existsSync(bin) ? 'PASS' : 'FAIL', fs.existsSync(bin) ? `node wiring resolves: ${bin} (handshake proven separately)` : `node wiring points at a missing file: ${bin}`, fs.existsSync(bin) ? undefined : 'Run `holmes-kit init` in the target to rewire the absolute path.');
                     }
                     else {
                         checks.push(await wiringSpawnCheck(server.command, server.args));
@@ -690,7 +799,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const stopCmd = entry?.Stop?.[0]?.command ?? '';
                 const stale = [preCmd, stopCmd].filter((c) => {
                     const p2 = (0, settings_merge_1.hookScriptPath)(c);
-                    return !p2 || !fs.existsSync(p2) || !path.resolve(p2).startsWith(path.resolve(packageRoot) + path.sep);
+                    return !resolvesToPackage(p2, packageRoot);
                 });
                 if (entry === undefined) {
                     add('antigravity wiring', 'WARN', `${agyHooks} 에 holmes-kit 항목이 없습니다`, 'holmes-kit init --target <dir> --agent antigravity');
@@ -755,6 +864,45 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                     const pin = (0, mcp_version_1.mcpLaunchVersion)({ command: entry.command, args: entry.args });
                     add('codex wiring', pin !== null ? 'PASS' : 'FAIL', pin !== null ? `npx 핀 ${pin} 으로 해석됩니다` : `배선에서 실행 버전을 읽을 수 없습니다: ${entry.command} ${entry.args.join(' ')}`, pin !== null ? undefined : 'holmes-kit init --target <dir> --agent codex 로 다시 배선하십시오.');
                 }
+                // @implements A-SPEC-442 (was A-SPEC-423)
+                // Codex CAN hard-enforce, but only from an INSTALLED plugin: it loads plugins from
+                // marketplace snapshots, never from a manifest sitting in the project (measured, four
+                // probes on codex-cli 0.151.0). doctor is offline and cannot see whether the user ran the
+                // two install commands, so PASS is not available here — the presence of files is not the
+                // presence of a gate. That inference is what A-SPEC-441 got wrong, and reporting PASS for
+                // it made the tool agree with the mistake.
+                const cdxPluginJson = path.join(target, agents_1.CODEX_PLUGIN_DIR, '.codex-plugin', 'plugin.json');
+                const cdxHooksJson = path.join(target, agents_1.CODEX_PLUGIN_DIR, 'hooks.json');
+                const cdxMarketplace = path.join(target, '.agents', 'plugins', 'marketplace.json');
+                const installCmds = `codex plugin marketplace add "${target}" 후 codex plugin add holmes-kit@${agents_1.CODEX_MARKETPLACE}`;
+                if (fs.existsSync(cdxPluginJson) && fs.existsSync(cdxHooksJson) && fs.existsSync(cdxMarketplace)) {
+                    try {
+                        const h = JSON.parse(fs.readFileSync(cdxHooksJson, 'utf8'));
+                        const manifest = JSON.parse(fs.readFileSync(cdxPluginJson, 'utf8'));
+                        const preCmd = h.hooks?.PreToolUse?.[0]?.hooks?.[0]?.command ?? '';
+                        const stopCmd = h.hooks?.Stop?.[0]?.command ?? '';
+                        const stale = [preCmd, stopCmd].filter((c) => {
+                            const p2 = (0, settings_merge_1.hookScriptPath)(c);
+                            return !resolvesToPackage(p2, packageRoot);
+                        });
+                        if (stale.length > 0) {
+                            add('codex gate', 'FAIL', `이 설치본을 가리키지 않는 훅 명령: ${stale.join(' | ')}`, 'holmes-kit init --target <dir> --agent codex --force 로 절대 경로를 갱신하십시오.');
+                        }
+                        else if (manifest.hooks !== './hooks.json') {
+                            // The one path measured to load. `./hooks/hooks.json` parses fine and never fires.
+                            add('codex gate', 'FAIL', `플러그인 매니페스트의 hooks 가 './hooks.json' 이 아닙니다: ${String(manifest.hooks)} — Codex 가 적재하지 않습니다`, 'holmes-kit init --target <dir> --agent codex --force 로 다시 배선하십시오.');
+                        }
+                        else {
+                            add('codex gate', 'WARN', '플러그인 배선은 옳습니다 — 그러나 설치되기 전까지 게이트는 집행되지 않습니다(Codex 는 설치된 마켓플레이스에서만 플러그인을 적재하며, doctor 는 설치 여부를 오프라인에서 확인할 수 없습니다)', `${installCmds} 를 실행한 뒤 새 세션에서 사용하십시오.`);
+                        }
+                    }
+                    catch {
+                        add('codex gate', 'FAIL', `${cdxHooksJson} 를 읽을 수 없습니다(JSON 아님)`, '파일을 고치거나 지우고 다시 배선하십시오.');
+                    }
+                }
+                else {
+                    add('codex gate', 'WARN', 'codex 플러그인 배선(.agents/plugins/marketplace.json, .holmes/codex-plugin/holmes-kit)이 없습니다 — MCP 도구만 동작하며 게이트가 집행되지 않습니다', `holmes-kit init --target <dir> --agent codex 로 배선한 뒤 ${installCmds} 로 설치하십시오.`);
+                }
             }
         }
         else if (fs.existsSync(cdxJson)) {
@@ -779,7 +927,14 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     {
         let verdict;
         try {
-            const prefix = (0, node_child_process_1.execFileSync)('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' }).trim();
+            // @implements A-SPEC-466 — W-5. Windows npm is a .cmd shim, so execFileSync('npm') is ENOENT
+            // and this check was a permanent WARN on every Windows machine. npm's own JS entry run with
+            // THIS node binary removes the shim; when no entry is found (e.g. Homebrew's Cellar layout —
+            // measured), the plain name keeps today's POSIX behavior, where there is no .cmd problem.
+            const npmCli = npmCliEntry();
+            const prefix = (npmCli !== null
+                ? (0, node_child_process_1.execFileSync)(process.execPath, [npmCli, 'config', 'get', 'prefix'], { encoding: 'utf8' })
+                : (0, node_child_process_1.execFileSync)('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' })).trim();
             const dir = globalInstallDir(prefix, process.platform);
             let probe = dir;
             while (!fs.existsSync(probe)) {
@@ -801,6 +956,19 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         }
         add('global prefix', verdict.level, verdict.detail, verdict.fix);
     }
+    {
+        const t = (0, tier_1.resolveSemanticTier)();
+        const v = semanticTierVerdict(t);
+        add('semantic tier', v.level, v.detail, v.fix);
+        // @implements A-SPEC-477 — the ".env 임시조치" detection: a key in a project-tree file is a
+        // commit-accident surface, world-readable at 644, and readable by every in-session tool. The
+        // value is read to detect the pattern and never printed.
+        const envTemp = detectTreeKeyTemporary(target ?? process.cwd());
+        if (envTemp.found) {
+            add('semantic key location', 'WARN', `프로젝트 .env 에서 semantic 키 패턴을 발견했습니다 — 트리 안 키는 커밋 사고·세션 열람 표면입니다`
+                + (envTemp.mode !== undefined && (envTemp.mode & 0o077) !== 0 ? ` (파일 권한 ${(envTemp.mode & 0o777).toString(8)} — 0600 초과)` : '') + '.', '`holmes-kit semantic-key set` 으로 트리 밖(키체인 또는 ~/.holmes/credentials.json 0600)에 저장한 뒤 .env 에서 해당 줄을 제거하십시오.');
+        }
+    }
     add('environment', 'PASS', present);
     if (extraChecks) {
         checks.push(...extraChecks);
@@ -892,7 +1060,23 @@ function wiringSpawnCheck(command, args, timeoutMs = 30000) {
                 try {
                     const m = JSON.parse(line);
                     if (m?.result?.serverInfo) {
-                        finish('PASS', `wiring reaches a live server (v${m.result.serverInfo.version ?? '?'}): \`${quoted}\``);
+                        // @implements A-SPEC-422
+                        // The version was printed and never checked. Measured on the installed build: all three
+                        // harness handshakes said `reaches a live server (v0.1.18)` for a wiring pinned at
+                        // `@0.2.1` and all three PASSed, so a harness governed by an older server — missing
+                        // whatever gates and disclosures that version lacks — read as fully verified.
+                        //
+                        // Only compared when the wiring NAMES a version. An absolute-path or globally-installed
+                        // wiring pins nothing, and warning without a baseline would be the false alarm this
+                        // repository has already had to undo twice.
+                        const live = m.result.serverInfo.version ?? '?';
+                        const pinned = /@holmes-lab\/holmes-kit@([0-9][^\s"'`]*)/.exec(quoted)?.[1];
+                        if (pinned !== undefined && live !== '?' && live !== pinned) {
+                            finish('WARN', `wiring pins ${pinned} but the live server answered v${live}: \`${quoted}\``, 'npx 는 캐시된 옛 버전으로 해석될 수 있습니다 — `npx clear-npx-cache` 후 다시 실행하거나,'
+                                + ' 그 버전이 레지스트리에 게시됐는지 확인하십시오. 하네스는 응답한 버전으로 집행합니다.');
+                            return;
+                        }
+                        finish('PASS', `wiring reaches a live server (v${live}): \`${quoted}\``);
                         return;
                     }
                 }
@@ -1039,3 +1223,125 @@ function formatChecks(checks) {
     lines.push(`\n${checks.length - fails - warns} pass, ${warns} warn, ${fails} fail`);
     return lines.join('\n');
 }
+// @implements A-SPEC-323
+/**
+ * Prove that EVERY wired harness can actually start a server, not merely that its file parses.
+ *
+ * A user reported that `holmes-kit init --agent codex` wrote a file Codex never reads and that doctor
+ * passed on it anyway. Measured against the current tree, the first half was already fixed by
+ * A-SPEC-266 — init writes `.codex/config.toml` with `[mcp_servers.*]`, migrates the legacy JSON, and
+ * doctor flags the old location. But the second half was real and sat one layer further in:
+ *
+ *   PASS mcp wiring spawn  — node wiring resolves: …/holmes-mcp.js   <- existence only
+ *   PASS codex wiring      — MCP 배선이 이 설치본으로 해석됩니다      <- path resolution only
+ *
+ * The one check that drives a real `initialize -> tools/list` ran for `.mcp.json` ONLY, and only when
+ * the command was not `node` — which is what init writes for all three harnesses. So on the common
+ * path nothing ever started a server through the wiring a harness would actually use.
+ *
+ * The `node` fast-path is gone. Existence survives as a fast FAIL, because spending a 30s deadline on
+ * a path that does not exist tells nobody anything new.
+ */
+async function wiringHandshakeChecks(target) {
+    const wirings = [
+        {
+            label: 'claude', file: path.join(target, '.mcp.json'),
+            read: (raw) => entryOf(JSON.parse(raw)?.mcpServers?.[init_1.SERVER_NAME]),
+        },
+        {
+            label: 'codex', file: path.join(target, '.codex', 'config.toml'),
+            read: (raw) => entryOf((0, codex_toml_1.readCodexHolmesEntry)(raw)),
+        },
+        {
+            label: 'antigravity', file: path.join(target, '.agents', 'mcp_config.json'),
+            read: (raw) => entryOf(JSON.parse(raw)?.mcpServers?.[init_1.SERVER_NAME]),
+        },
+    ];
+    const out = [];
+    for (const wiring of wirings) {
+        // An absent wiring is not a dead one — the harness simply is not wired here.
+        if (!fs.existsSync(wiring.file))
+            continue;
+        const name = `${wiring.label} wiring handshake`;
+        let entry = null;
+        try {
+            entry = wiring.read(fs.readFileSync(wiring.file, 'utf8'));
+        }
+        catch {
+            entry = null;
+        }
+        if (!entry) {
+            out.push({ name, level: 'WARN', detail: `${wiring.file} 에서 실행 가능한 ${init_1.SERVER_NAME} 배선을 읽지 못했습니다`,
+                fix: `holmes-kit init --target <dir> --agent ${wiring.label} 로 다시 배선하십시오.` });
+            continue;
+        }
+        if (entry.command === 'node') {
+            const bin = entry.args[0] ?? '';
+            if (!fs.existsSync(bin)) {
+                out.push({ name, level: 'FAIL', detail: `배선이 없는 파일을 가리킵니다: ${bin}`,
+                    fix: `holmes-kit init --target <dir> --agent ${wiring.label} --force 로 경로를 갱신하십시오.` });
+                continue;
+            }
+        }
+        const check = await wiringSpawnCheck(entry.command, entry.args);
+        out.push({ ...check, name });
+    }
+    return out;
+}
+/** A wiring entry is usable only if BOTH halves are present; a half-written one is not runnable. */
+function entryOf(value) {
+    const e = value;
+    if (!e || typeof e.command !== 'string' || !Array.isArray(e.args))
+        return null;
+    return { command: e.command, args: e.args };
+}
+/**
+ * @implements A-SPEC-476
+ * The semantic tier's doctor verdict, pure so the three states are unit-testable offline.
+ * The cloud notice NAMES the egress — what leaves the machine and where — because the key being
+ * set is the consent, and consent must be able to see what it consented to. The 'none' state
+ * quotes the measured stakes (lexical-zero recovery 0% -> 52% local / 92% cloud, S-491) so the
+ * user decides the trade with numbers rather than adjectives.
+ */
+function semanticTierVerdict(t) {
+    if (t.tier === 'cloud') {
+        // @implements A-SPEC-477 — the SOURCE of the consent is shown (env/keychain/file); the value
+        // never is. Consent must be able to see what it consented to, and where it lives.
+        const src = t.keySource === 'env' ? 'HOLMES_SEMANTIC_API_KEY'
+            : t.keySource === 'env-compat' ? 'GEMINI_API_KEY'
+                : t.keySource === 'keychain' ? 'macOS 키체인'
+                    : t.keySource === 'file' ? '~/.holmes/credentials.json' : '알 수 없음';
+        return {
+            level: 'PASS',
+            detail: `의미 검색 티어: cloud (${t.model}, 키 출처: ${src}) — 스펙 산문·파일 경로·심볼명이 외부(Google API)로 전송됩니다. 키 설정이 이 전송에 대한 동의이며, 값은 이 보고서에 절대 출력되지 않습니다.`,
+        };
+    }
+    if (t.tier === 'local') {
+        return {
+            level: 'PASS',
+            detail: `의미 검색 티어: local (${t.model}, ${(0, tier_1.POOLING_OF)(t.model ?? '')} 풀링) — 이그레스 없음. 어휘가 닿지 않는 요청의 52%를 회수합니다(실측).`,
+        };
+    }
+    return {
+        level: 'PASS',
+        detail: '의미 검색 티어: none — 어휘·인용·그래프만 사용 중입니다. 어휘가 닿지 않는 요청(실측 16.4%)은 회수율 0%입니다.',
+        fix: '로컬 티어(이그레스 없음): npm i @xenova/transformers — 어휘-제로 회수 0→52%. cloud 티어(opt-in, 외부 전송 동의): GEMINI_API_KEY 설정 — 0→92%.',
+    };
+}
+/**
+ * @implements A-SPEC-477
+ * Detects the "임시 조치": a semantic key pattern inside the PROJECT's .env. The value is read
+ * only to detect the pattern and is never returned or printed.
+ */
+function detectTreeKeyTemporary(root) {
+    try {
+        const p = path.join(root, '.env');
+        const text = fs.readFileSync(p, 'utf8');
+        if (!/^(?:GEMINI_API_KEY|GOOGLE_API_KEY|HOLMES_SEMANTIC_API_KEY)\s*=/m.test(text))
+            return { found: false };
+        return { found: true, mode: fs.statSync(p).mode & 0o777 };
+    }
+    catch {
+        return { found: false };
+    }
+}

package/dist/holmes/cli/index.js

@@ -78,6 +78,8 @@ const KNOWN_FLAGS = {
     serve: ['help', 'target', 'port'],
     approve: ['help', 'target', 'list', 'grant', 'deny', 'ask', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'],
     ledger: ['help', 'target', 'ref', 'dry-run'],
+    // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
+    'semantic-key': ['help'],
 };
 // @implements A-SPEC-171 — subcommands that render their OWN usage on `--help`. A-SPEC-171 governs
 // "help before any side effect"; a command whose usage lives past this handler (approve, whose
@@ -200,6 +202,10 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
     <ref>                      list index (1,2,…), full id, or a unique id prefix
     --target <dir>             project root (default: cwd)
 
+  holmes-kit semantic-key set|unset|status   cloud semantic 티어 opt-in 키 관리
+                             set 은 stdin 으로만 입력받습니다(값은 argv·출력 어디에도 남지 않음).
+                             키 설정은 이그레스(스펙 산문·경로·심볼명 외부 전송) 동의입니다.
+
   holmes-kit doctor [flags]    diagnose the install
     --target <dir>             also verify that target's wiring points at this install
     --json                     machine-readable output
@@ -246,7 +252,8 @@ async function main(argv) {
         }
         // Positionals these commands do not take are refused, not dropped: `skills refresh <dir>`
         // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
-        const expected = cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain'] : [];
+        const expected = cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
+            : cmd === 'semantic-key' ? ['set', 'unset', 'status'] : [];
         const unexpected = positionals.filter((p) => !expected.includes(p));
         if (unexpected.length > 0) {
             const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
@@ -276,6 +283,11 @@ async function main(argv) {
         process.stdout.write(`${v}\n`);
         return 0;
     }
+    if (cmd === 'semantic-key') {
+        // @implements A-SPEC-477 — set|unset|status; the key rides stdin, never argv.
+        const { runSemanticKey } = await Promise.resolve().then(() => __importStar(require('./semantic-key')));
+        return runSemanticKey(positionals[0]);
+    }
     if (cmd === 'doctor') {
         // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
         // (round-6) — the typo is the diagnosis, so say it.

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' },
 };