@holmes-lab/holmes-kit 0.12.1 → 0.13.0

package/dist/holmes/cli/doctor.js

@@ -157,21 +157,21 @@ function npmCliEntry(env = process.env, execPath = process.execPath) {
  */
 function prefixVerdict(input) {
     const reason = input.unreadable ?? (typeof input.prefix !== 'string' || input.prefix === ''
-        ? `npm 이 돌려준 prefix 를 해석할 수 없습니다 (${String(input.prefix)})`
+        ? `npm returned a prefix that cannot be parsed (${String(input.prefix)})`
         : undefined);
     if (reason !== undefined) {
-        return { level: 'WARN', detail: `전역 prefix 를 판독하지 못했습니다 — ${reason}. 로컬 설치(--save-dev)는 이 판정과 무관하게 동작합니다.` };
+        return { level: 'WARN', detail: `Could not read the global prefix — ${reason}. A local install (--save-dev) works regardless of this verdict.` };
     }
     const prefix = input.prefix;
     if (input.writable) {
-        return { level: 'PASS', detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 가능합니다 — npm install -g 가 권한 문제 없이 동작합니다.` };
+        return { level: 'PASS', detail: `Global prefix (${prefix}) is writable by the current account — npm install -g works without permission trouble.` };
     }
     const fix = input.platform === 'win32'
-        ? 'npm config set prefix "%APPDATA%\\npm" 실행 후 %APPDATA%\\npm 을 PATH 에 추가하고 터미널을 다시 여세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.'
-        : 'npm config set prefix "$HOME/.npm-global" 실행 후 $HOME/.npm-global/bin 을 PATH 에 추가하세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.';
+        ? 'Run npm config set prefix "%APPDATA%\\npm", add %APPDATA%\\npm to PATH, and reopen the terminal. A local install (npm install --save-dev) works without this setting.'
+        : 'Run npm config set prefix "$HOME/.npm-global" and add $HOME/.npm-global/bin to PATH. A local install (npm install --save-dev) works without this setting.';
     return {
         level: 'WARN',
-        detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 불가입니다 — npm install -g 는 ${input.dir ?? ''} 에 디렉터리를 만들다 EPERM 으로 죽습니다. 패키지가 도착하기 전 단계라 어떤 패키지도 이를 고칠 수 없습니다.`,
+        detail: `Global prefix (${prefix}) is not writable by the current account — npm install -g dies with EPERM while creating a directory in ${input.dir ?? ''}. This happens before any package is transferred, so no package can fix it.`,
         fix,
     };
 }
@@ -219,7 +219,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     add('build output', built ? 'PASS' : 'FAIL', built ? `compiled output present under ${path.join(packageRoot, 'dist')}` : `missing ${serverJs}`, 
     // @implements A-SPEC-190 §16 (round 12) — the old remedy named a `prepare` script package.json
     // never declared (build/mcp/release/test/typecheck only); dist/ ships because `files` lists it.
-    built ? undefined : '이 패키지는 컴파일된 dist/ 를 함께 배포합니다 — 저장소에서 쓰는 중이라면 `npm run build`, 설치본이라면 재설치하십시오.');
+    built ? undefined : 'This package ships compiled dist/ — if you are working from the repository run `npm run build`; if this is an install, reinstall it.');
     // 2. Node version vs better-sqlite3's declared range (WARN only — a mismatch still often works).
     let sqliteRange = '(unknown)';
     try {
@@ -278,7 +278,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         // A probe must observe the gate, never feed its audit trail.
         (() => {
             const probeCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-probe-'));
-            cleanupOnSignal(probeCwd); // round-9: 인터럽트 사망에서도 남지 않는다
+            cleanupOnSignal(probeCwd); // round-9: leaves nothing behind even on an interrupt-kill
             try {
                 return (0, node_child_process_1.spawnSync)(process.execPath, [script], { input: JSON.stringify(payload), encoding: 'utf8', timeout: 20000, env: childEnv, cwd: probeCwd });
             }
@@ -441,10 +441,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
     // 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 기록을 만들 수 없습니다');
+        add('ledger signing', 'PASS', 'The ledger is signed with HOLMES_LEDGER_KEY — without the key, a forger cannot produce a chain-valid spec-approved record');
     }
     else {
-        add('ledger signing', 'WARN', '원장이 서명되지 않습니다(HOLMES_LEDGER_KEY 없음) — 체인이 평문 해시라 파일을 쓸 수 있는 자가 승인 기록도 만들 수 있고, ART-5 의 원장 대조는 장벽이 아니라 비용이 됩니다', 'HOLMES_LEDGER_KEY 를 대역외(에이전트를 기동하는 사람의 환경)에서 설정한 뒤 서버를 다시 시작하십시오. 값은 이 보고서에 절대 출력되지 않습니다.');
+        add('ledger signing', 'WARN', 'The ledger is not signed (HOLMES_LEDGER_KEY unset) — the chain is a plain hash, so anyone who can write the file can also mint approval records, and ART-5\'s ledger comparison becomes a cost rather than a barrier', 'Set HOLMES_LEDGER_KEY out-of-band (in the environment of whoever launches the agent), then restart the server. The value is never printed into this report.');
     }
     // @implements A-SPEC-535.1
     // Advisory: holmes-kit's OWN advertised MCP schema cost, and the one holmes-controlled
@@ -477,10 +477,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 }).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` 로 추적에 추가한 뒤 커밋하십시오.');
+                    add('ledger tracked', 'WARN', `Untracked ledger(s): ${untracked.join(', ')} — not in git, so the ART-2 truncation backstop (A-SPEC-455) is off for these files. The Stop gate would not catch even a wholesale emptying of the ledger`, 'Add a `!.ax/ledger/provenance*.jsonl` re-include rule to .gitignore, then `git add -f .ax/ledger/provenance*.jsonl`, and commit.');
                 }
                 else {
-                    add('ledger tracked', 'PASS', '원장이 git 에 추적됩니다 — ART-2 절단 백스톱이 커밋된 이력을 기준으로 롤백을 잡습니다');
+                    add('ledger tracked', 'PASS', 'The ledger is tracked in git — the ART-2 truncation backstop catches a rollback against the committed history');
                 }
             }
         }
@@ -520,12 +520,12 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             const { rtmCheck } = require('../rtm/rtm-check');
             const dups = rtmCheck(all).filter((i) => i.kind === 'duplicate-id');
             add('duplicate spec ids', dups.length === 0 ? 'PASS' : 'WARN', dups.length === 0
-                ? '같은 id를 가진 스펙 파일이 없습니다'
-                : `같은 id의 스펙 파일이 둘 이상: ${dups.map((d) => d.id).join(', ')}`, dups.length === 0 ? undefined
-                : '게이트는 승인되지 않은 쪽으로 판정합니다 — 남길 파일 하나만 두고 사본을 지우세요.');
+                ? 'No two spec files share an id'
+                : `Two or more spec files share an id: ${dups.map((d) => d.id).join(', ')}`, dups.length === 0 ? undefined
+                : 'The gate rules toward the unapproved side — keep one file and delete the copy.');
             add('spec chain', 'PASS', orphaned.length === 0
-                ? '승인된 스펙의 상위가 모두 approved입니다'
-                : `상위가 approved가 아닌 승인 스펙 ${orphaned.length}건: ${orphaned.map((s) => s.id).slice(0, 5).join(', ')}`);
+                ? 'Every approved spec has approved parents'
+                : `${orphaned.length} approved spec(s) with a non-approved parent: ${orphaned.map((s) => s.id).slice(0, 5).join(', ')}`);
         }
         catch { /* an unreadable corpus is doctor's other checks' business, not this one's */ }
         // @implements A-SPEC-254.1
@@ -570,7 +570,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 // "Nothing there" is not "something escaped judgment" (round-4, extended round-7): a
                 // NONEXISTENT (ENOENT) or path-broken (ENOTDIR — .ax created as a stray FILE;
                 // ENAMETOOLONG) root/dir holds nothing that could have been judged, so counting it stamped
-                // a phantom '판정 밖 1건' on pre-init targets, indistinguishable from a genuinely
+                // a phantom "1 outside the verdict" on pre-init targets, indistinguishable from a genuinely
                 // permission-locked store. Real refusals (EACCES) and cycles (ELOOP — an entry exists, it
                 // just cannot be entered) still count as unexamined regions.
                 try {
@@ -665,26 +665,26 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             collect(specsRoot);
             // No cross-reference to `spec readability` (round-3): that walker does not follow dir
             // symlinks, so the pointer was false for symlink-reached files — doctor contradicting itself.
-            const scopeNote = skipped > 0 ? ` (판정 밖 ${skipped}건)` : '';
+            const scopeNote = skipped > 0 ? ` (${skipped} outside the verdict)` : '';
             const found = detectIdCollisions(entries);
             const collisions = found.filter((i) => i.kind === 'id-collision');
             const families = found.filter((i) => i.kind === 'family-coexistence');
-            add('spec id 선점 충돌', collisions.length === 0 ? 'PASS' : 'WARN', collisions.length === 0
-                ? `같은 id를 서로 다른 스펙이 쓰는 충돌이 없습니다${scopeNote}`
+            add('spec id preemption collision', collisions.length === 0 ? 'PASS' : 'WARN', collisions.length === 0
+                ? `No id is claimed by two different specs${scopeNote}`
                 : collisions.map((c) => `${c.id}: ${c.files.join(' ↔ ')} (${c.detail})`).join('; ') + scopeNote, collisions.length === 0 ? undefined
-                : '같은 번호를 두 스펙이 선점했습니다 — 한쪽을 리넘버하고(REQ-255 전까지는 수동) 재봉인하세요.');
-            add('spec id 가족 공존', families.length === 0 ? 'PASS' : 'WARN', families.length === 0
-                ? `bare id와 dot-suffix 가족의 공존이 없습니다${scopeNote}`
+                : 'Two specs preempted the same number — renumber one (manual until REQ-255) and re-seal.');
+            add('spec id family coexistence', families.length === 0 ? 'PASS' : 'WARN', families.length === 0
+                ? `No bare id coexists with its dot-suffix family${scopeNote}`
                 : families.map((f) => `${f.id}: ${f.files.join(', ')}`).join('; ') + scopeNote, families.length === 0 ? undefined
-                : 'bare 스펙과 점 하위 가족이 공존합니다 — 두 워크스페이스가 같은 번호를 다르게 전개한 신호이니 한쪽 전개로 통일하세요.');
+                : 'A bare spec coexists with a dotted sub-family — a sign two workspaces expanded the same number differently; unify on one expansion.');
         }
         catch (e) {
             // Never a silent vanish: the corpus most likely to hold a collision (a messy half-merged
             // store) is exactly where an upstream throw would otherwise suppress the report. String(e),
             // not e.message — a thrown non-Error must not crash the survival branch itself (round-2).
             const msg = String(e instanceof Error ? e.message : e).split('\n')[0];
-            add('spec id 선점 충돌', 'WARN', `검사를 실행하지 못했습니다: ${msg}`);
-            add('spec id 가족 공존', 'WARN', `검사를 실행하지 못했습니다: ${msg}`);
+            add('spec id preemption collision', 'WARN', `could not run the check: ${msg}`);
+            add('spec id family coexistence', 'WARN', `could not run the check: ${msg}`);
         }
     }
     // @implements A-SPEC-176
@@ -696,8 +696,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         const { unreadableSpecFiles } = require('../spec/spec-store');
         const unreadable = unreadableSpecFiles(path.join(target, '.ax', 'specs'));
         add('spec readability', unreadable.length === 0 ? 'PASS' : 'WARN', unreadable.length === 0
-            ? '스펙 디렉터리의 모든 .md가 파싱됩니다'
-            : `파싱되지 않아 스펙으로 취급되지 않는 파일 ${unreadable.length}건: ${unreadable.slice(0, 5).join(', ')}`, unreadable.length === 0 ? undefined : '해당 파일의 프론트매터를 확인하세요 — 존재하지만 게이트에는 보이지 않습니다.');
+            ? 'Every .md in the spec directory parses'
+            : `${unreadable.length} file(s) not treated as specs because they do not parse: ${unreadable.slice(0, 5).join(', ')}`, unreadable.length === 0 ? undefined : 'Check the frontmatter of those files — they exist but are invisible to the gate.');
     }
     // @implements A-SPEC-178
     // Two checks that report the wiring a USER will meet, not what this process happens to see.
@@ -725,16 +725,32 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         } // absent or unreadable is "not guaranteed", which is the point
         const procApproval = !!process.env.HOLMES_APPROVAL;
         if (mcpApproval) {
-            add('approval channel', 'PASS', '승인 변수가 .mcp.json의 서버 환경에 있습니다 — spec_approve가 도달합니다');
+            add('approval channel', 'PASS', 'The approval variable is in .mcp.json\'s server env — spec_approve reaches it');
         }
         else if (!procApproval) {
             // A project that has not started approving is healthy. Warning here would put a permanent line
             // on every install, and a line that is always there is one nobody reads (REQ-153's judgement).
-            add('approval channel', 'PASS', '승인 변수가 설정되어 있지 않습니다 — 승인이 필요할 때 설정하세요');
+            add('approval channel', 'PASS', 'The approval variable is not set — set it when an approval is needed');
         }
         else {
-            add('approval channel', 'WARN', '이 프로세스에는 HOLMES_APPROVAL이 있으나 .mcp.json의 서버 환경에는 없습니다 — spec_approve는 서버 환경을 읽습니다', 'settings.local.json의 env가 MCP 서버까지 전달된다는 보장은 없습니다. 그 변수를 설정한 셸에서 Claude Code를 띄우면 자식 서버가 상속합니다.');
+            add('approval channel', 'WARN', 'This process has HOLMES_APPROVAL but .mcp.json\'s server env does not — spec_approve reads the server env', 'There is no guarantee that settings.local.json\'s env reaches the MCP server. Launch Claude Code from the shell where you set that variable, and the child server inherits it.');
         }
+        // @implements A-SPEC-552.1 — surface the project's autonomy posture so a human always knows
+        // whether the agent may self-approve. Read from the SAME place the MCP server does (.mcp.json
+        // server env), never from doctor's own process, for the reason stated above.
+        let autonomyOn = false;
+        try {
+            const raw = fs.readFileSync(path.join(target, '.mcp.json'), 'utf8');
+            const env = JSON.parse(raw)
+                .mcpServers?.[init_1.SERVER_NAME]?.env;
+            autonomyOn = !!env && !!env['HOLMES_AUTONOMOUS_APPROVAL'];
+        }
+        catch {
+            autonomyOn = false;
+        }
+        add('autonomous spec approval', 'PASS', autonomyOn
+            ? 'ON — the agent may self-approve low-risk specs; governance-critical still ask you (holmes-kit autonomy off to disable)'
+            : 'OFF — every spec approval is human (enable at init, or holmes-kit autonomy on for one session)');
         // @implements A-SPEC-251.2 — the version this project's MCP server will ACTUALLY launch, vs this
         // CLI. The stale-global trap (measured 2026-08-23: .mcp.json pinned a 0.1.9 global while the user
         // believed they had upgraded) was invisible because nothing compared them. Offline: the launch
@@ -757,17 +773,17 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const launch = (0, mcp_version_1.mcpLaunchVersion)({ command: server.command, args: server.args }, readPkgVersionAt);
                 const verdict = (0, mcp_version_1.versionDriftVerdict)(launch, cli);
                 if (verdict === 'drift') {
-                    add('mcp server version', 'WARN', `이 프로젝트의 MCP 서버는 holmes-kit ${launch} 를 띄우지만 이 CLI 는 ${cli} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, 
+                    add('mcp server version', 'WARN', `This project's MCP server launches holmes-kit ${launch}, but this CLI is ${cli} — the old server keeps starting until it is rewired`, 
                     // @implements A-SPEC-544.1 — one command installs + re-pins every workspace; init --force is the per-workspace path.
-                    `${(0, npx_bin_1.npxBin)()} holmes-kit upgrade 로 최신 설치 + 전 워크스페이스 재핀 (이 워크스페이스만 고치려면 ${(0, npx_bin_1.npxBin)()} holmes-kit init --force).`);
+                    `Run ${(0, npx_bin_1.npxBin)()} holmes-kit upgrade to install the latest and re-pin every workspace (to fix only this workspace, ${(0, npx_bin_1.npxBin)()} holmes-kit init --force).`);
                 }
                 else if (verdict === 'match') {
-                    add('mcp server version', 'PASS', `MCP 서버 버전 ${launch} 가 이 CLI 와 일치합니다`);
+                    add('mcp server version', 'PASS', `MCP server version ${launch} matches this CLI`);
                 }
-                // 'unknown' → 항목 없음: 판정 불능을 결함으로 만들지 않는다.
+                // 'unknown' -> no entry: an undecidable check is not turned into a defect.
             }
         }
-        catch { /* .mcp.json 부재/파싱 실패 → 이 점검 없이 진행 */ }
+        catch { /* .mcp.json absent or unparseable -> proceed without this check */ }
         // @implements A-SPEC-259 — the wiring is judged by SPAWNING it. String comparison is exactly how
         // the dead `npx -y <pkg>@<ver> holmes-mcp` form (npx resolves the default bin and hands
         // `holmes-mcp` to it as an argument) passed the launcher test, this doctor's own handshake check
@@ -805,8 +821,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 }
             }
         }
-        // @implements A-SPEC-193 — 배선된 하네스마다 그 하네스의 배선을 검사한다. 배선되지 않은
-        // 하네스는 진단하지 않는다(없는 것을 결함이라 부르면 doctor 가 소음이 된다).
+        // @implements A-SPEC-193 — for each wired harness, check that harness's wiring. A harness that is
+        // not wired is not diagnosed (calling an absence a defect turns doctor into noise).
         const agyHooks = path.join(target, '.agents', 'hooks.json');
         if (fs.existsSync(agyHooks)) {
             try {
@@ -820,25 +836,25 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const stale = [scriptOf(pre?.hooks?.[0]), scriptOf(entry?.Stop?.[0])]
                     .filter((p2) => !resolvesToPackage(p2, packageRoot));
                 if (entry === undefined) {
-                    add('antigravity wiring', 'WARN', `${agyHooks} 에 holmes-kit 항목이 없습니다`, 'holmes-kit init --target <dir> --agent antigravity');
+                    add('antigravity wiring', 'WARN', `${agyHooks} has no holmes-kit entry`, 'holmes-kit init --target <dir> --agent antigravity');
                 }
                 else if (stale.length > 0) {
-                    add('antigravity wiring', 'FAIL', `이 설치본을 가리키지 않는 훅 경로: ${stale.join(' | ')}`, 'holmes-kit init --target <dir> --agent antigravity --force 로 절대 경로를 갱신하십시오.');
+                    add('antigravity wiring', 'FAIL', `hook path(s) not pointing at this install: ${stale.join(' | ')}`, 'Run holmes-kit init --target <dir> --agent antigravity --force to refresh the absolute paths.');
                 }
                 else if ((pre?.matcher ?? '') !== '*') {
-                    // 매처가 좁으면 그 밖의 도구가 게이트를 지나간다 — 조용한 구멍이므로 말한다.
-                    add('antigravity wiring', 'WARN', `PreToolUse 매처가 '${pre?.matcher ?? ''}' 입니다 — '*' 가 아니면 그 밖의 도구는 게이트에 닿지 않습니다`, "matcher 를 '*' 로 되돌리십시오.");
+                    // A narrow matcher lets other tools pass the gate — a silent hole, so say it.
+                    add('antigravity wiring', 'WARN', `The PreToolUse matcher is '${pre?.matcher ?? ''}' — unless it is '*', other tools never reach the gate`, "Restore the matcher to '*'.");
                 }
                 else {
-                    add('antigravity wiring', 'PASS', 'PreToolUse·Stop 이 이 설치본을 가리킵니다');
+                    add('antigravity wiring', 'PASS', 'PreToolUse and Stop point at this install');
                 }
             }
             catch {
-                add('antigravity wiring', 'FAIL', `${agyHooks} 를 읽을 수 없습니다(JSON 아님)`, '파일을 고치거나 지우고 다시 배선하십시오.');
+                add('antigravity wiring', 'FAIL', `${agyHooks} cannot be read (not JSON)`, 'Fix or delete the file and rewire.');
             }
-            // 스킬이 그 하네스에 보이는가 — 링크가 끊기면 스킬은 조용히 사라진다.
+            // Are the skills visible to that harness — a broken link makes skills silently disappear.
             const agySkills = path.join(target, '.agents', 'skills');
-            add('antigravity skills', fs.existsSync(agySkills) ? 'PASS' : 'WARN', fs.existsSync(agySkills) ? `${agySkills} 가 스킬을 가리킵니다` : `${agySkills} 가 없습니다 — 이 하네스는 스킬을 보지 못합니다`, fs.existsSync(agySkills) ? undefined : `${path.join('..', '.claude', 'skills')} 로 링크하거나 복사하십시오.`);
+            add('antigravity skills', fs.existsSync(agySkills) ? 'PASS' : 'WARN', fs.existsSync(agySkills) ? `${agySkills} points at the skills` : `${agySkills} is missing — this harness cannot see the skills`, fs.existsSync(agySkills) ? undefined : `Link or copy it to ${path.join('..', '.claude', 'skills')}.`);
         }
         // @implements A-SPEC-266 (was A-SPEC-264) — Codex reads MCP servers from `.codex/config.toml`
         // (TOML `[mcp_servers.*]`), so we check the file Codex actually loads — not the
@@ -854,17 +870,18 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             }
             catch { /* handled below */ }
             if (raw === null) {
-                add('codex wiring', 'FAIL', `${cdxToml} 를 읽을 수 없습니다`, '파일 권한을 확인하거나 지우고 다시 배선하십시오.');
+                add('codex wiring', 'FAIL', `${cdxToml} cannot be read`, 'Check the file permissions, or delete it and rewire.');
             }
             else {
                 const entry = (0, codex_toml_1.readCodexHolmesEntry)(raw);
                 if (!entry) {
-                    add('codex wiring', 'WARN', `${cdxToml} 에 실행 가능한 [mcp_servers.${init_1.SERVER_NAME}] 항목이 없습니다 — 반쯤 된 배선입니다`, 'holmes-kit init --target <dir> --agent codex 로 다시 배선하십시오.');
+                    add('codex wiring', 'WARN', `${cdxToml} has no runnable [mcp_servers.${init_1.SERVER_NAME}] entry — a half-done wiring`, 'Rewire with holmes-kit init --target <dir> --agent codex.');
                 }
                 else if (entry.command === 'node') {
-                    // @implements A-SPEC-266 — "이 설치본으로 해석됩니다"는 존재만으로는 부족하다: node 배선은
-                    // holmes-mcp.js 를 가리켜야 한다. 아무 존재 파일(예: /etc/hosts)에 PASS 를 주면 "해석된다"는
-                    // 주장이 검사보다 강해진다(적대 라운드 Finding 2). 파일명까지 확인해 그 간극을 좁힌다.
+                    // @implements A-SPEC-266 — "resolves to this install" is not enough on existence alone: a
+                    // node wiring must point at holmes-mcp.js. Passing any existing file (e.g. /etc/hosts) makes
+                    // the "resolves" claim stronger than the check (adversarial round, Finding 2). Verify the
+                    // basename too, to close that gap.
                     const bin = entry.args[0] ?? '';
                     // Resolve the link before judging the name (round-2 F4): a symlink literally named
                     // `holmes-mcp.js` pointing at /etc/hosts must not read as "resolves to this install".
@@ -875,12 +892,12 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                         return '';
                     } })();
                     const resolvesHere = realBin !== '' && path.basename(realBin) === 'holmes-mcp.js';
-                    add('codex wiring', resolvesHere ? 'PASS' : 'FAIL', resolvesHere ? `MCP 배선이 이 설치본으로 해석됩니다: ${bin}`
-                        : (fs.existsSync(bin) ? `MCP 배선이 holmes-mcp.js 가 아닌 파일을 가리킵니다: ${bin}` : `MCP 배선이 없는 파일을 가리킵니다: ${bin}`), resolvesHere ? undefined : 'holmes-kit init --target <dir> --agent codex --force 로 절대 경로를 갱신하십시오.');
+                    add('codex wiring', resolvesHere ? 'PASS' : 'FAIL', resolvesHere ? `MCP wiring resolves to this install: ${bin}`
+                        : (fs.existsSync(bin) ? `MCP wiring points at a file that is not holmes-mcp.js: ${bin}` : `MCP wiring points at a missing file: ${bin}`), resolvesHere ? undefined : 'Run holmes-kit init --target <dir> --agent codex --force to refresh the absolute path.');
                 }
                 else {
                     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 로 다시 배선하십시오.');
+                    add('codex wiring', pin !== null ? 'PASS' : 'FAIL', pin !== null ? `resolves via the npx pin ${pin}` : `cannot read a launch version from the wiring: ${entry.command} ${entry.args.join(' ')}`, pin !== null ? undefined : 'Rewire with 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
@@ -897,7 +914,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 // location only) is caught instead of passing as "wiring is correct" when it cannot install.
                 const cdxMarketplaceNew = path.join(target, '.claude-plugin', 'marketplace.json');
                 const cdxMarketplaceOld = path.join(target, '.agents', 'plugins', 'marketplace.json');
-                const installCmds = `codex plugin marketplace add "${target}" 후 codex plugin add holmes-kit@${agents_1.CODEX_MARKETPLACE}`;
+                const installCmds = `codex plugin marketplace add "${target}", then codex plugin add holmes-kit@${agents_1.CODEX_MARKETPLACE}`;
                 if (fs.existsSync(cdxPluginJson) && fs.existsSync(cdxHooksJson) && (fs.existsSync(cdxMarketplaceNew) || fs.existsSync(cdxMarketplaceOld))) {
                     try {
                         const h = JSON.parse(fs.readFileSync(cdxHooksJson, 'utf8'));
@@ -909,33 +926,33 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                             return !resolvesToPackage(p2, packageRoot);
                         });
                         if (stale.length > 0) {
-                            add('codex gate', 'FAIL', `이 설치본을 가리키지 않는 훅 명령: ${stale.join(' | ')}`, 'holmes-kit init --target <dir> --agent codex --force 로 절대 경로를 갱신하십시오.');
+                            add('codex gate', 'FAIL', `hook command(s) not pointing at this install: ${stale.join(' | ')}`, 'Run holmes-kit init --target <dir> --agent codex --force to refresh the absolute paths.');
                         }
                         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 로 다시 배선하십시오.');
+                            add('codex gate', 'FAIL', `the plugin manifest's hooks is not './hooks.json': ${String(manifest.hooks)} — Codex does not load it`, 'Rewire with holmes-kit init --target <dir> --agent codex --force.');
                         }
                         else if (!fs.existsSync(cdxMarketplaceNew)) {
                             // @implements A-SPEC-533.3 — hooks are correct, but the marketplace manifest is only at
                             // the old `.agents/plugins/` location; codex 0.152.x reads `.claude-plugin/` and cannot
                             // install this. Judged AFTER the stale-hook / manifest FAILs so those still win.
-                            add('codex gate', 'WARN', `codex 0.152.x 가 읽는 .claude-plugin/marketplace.json 이 없습니다 — 구 위치(.agents/plugins/marketplace.json)만 있어 codex plugin marketplace add 가 "manifest 없음" 으로 실패합니다 (0.151.x 는 .agents/plugins/, 0.152.x 는 .claude-plugin/)`, 'holmes-kit init --target <dir> --agent codex --force 로 다시 배선하면 두 위치에 매니페스트가 놓입니다.');
+                            add('codex gate', 'WARN', `.claude-plugin/marketplace.json (read by codex 0.152.x) is missing — only the old location (.agents/plugins/marketplace.json) is present, so codex plugin marketplace add fails with "no manifest" (0.151.x reads .agents/plugins/, 0.152.x reads .claude-plugin/)`, 'Rewiring with holmes-kit init --target <dir> --agent codex --force places the manifest in both locations.');
                         }
                         else {
-                            add('codex gate', 'WARN', '플러그인 배선은 옳습니다 — 그러나 설치되기 전까지 게이트는 집행되지 않습니다(Codex 는 설치된 마켓플레이스에서만 플러그인을 적재하며, doctor 는 설치 여부를 오프라인에서 확인할 수 없습니다)', `${installCmds} 를 실행한 뒤 새 세션에서 사용하십시오.`);
+                            add('codex gate', 'WARN', 'The plugin wiring is correct — but the gate is not enforced until it is installed (Codex only loads plugins from an installed marketplace, and doctor cannot verify installation offline)', `Run ${installCmds}, then use it in a new session.`);
                         }
                     }
                     catch {
-                        add('codex gate', 'FAIL', `${cdxHooksJson} 를 읽을 수 없습니다(JSON 아님)`, '파일을 고치거나 지우고 다시 배선하십시오.');
+                        add('codex gate', 'FAIL', `${cdxHooksJson} cannot be read (not JSON)`, 'Fix or delete the file and rewire.');
                     }
                 }
                 else {
-                    add('codex gate', 'WARN', 'codex 플러그인 배선(.agents/plugins/marketplace.json, .holmes/codex-plugin/holmes-kit)이 없습니다 — MCP 도구만 동작하며 게이트가 집행되지 않습니다', `holmes-kit init --target <dir> --agent codex 로 배선한 뒤 ${installCmds} 로 설치하십시오.`);
+                    add('codex gate', 'WARN', 'The codex plugin wiring (.agents/plugins/marketplace.json, .holmes/codex-plugin/holmes-kit) is missing — only the MCP tools work; the gate is not enforced', `Wire it with holmes-kit init --target <dir> --agent codex, then install with ${installCmds}.`);
                 }
             }
         }
         else if (fs.existsSync(cdxJson)) {
-            add('codex wiring', 'WARN', `codex 배선이 Codex 가 읽지 않는 구식 위치(${cdxJson})에 있습니다 — config.toml 로 옮겨야 합니다`, 'holmes-kit init --target <dir> --agent codex 로 다시 배선하면 config.toml 로 이전되고 구식 파일이 정리됩니다.');
+            add('codex wiring', 'WARN', `codex wiring sits in a legacy location Codex does not read (${cdxJson}) — it must move to config.toml`, 'Rewiring with holmes-kit init --target <dir> --agent codex migrates it to config.toml and cleans up the legacy file.');
         }
         try {
             const sp = wiredSettingsPath(target);
@@ -945,8 +962,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 .map((g) => g.matcher ?? '');
             const drifted = wired.filter((m) => m !== init_1.MATCHERS.guardrail);
             add('hook matcher', drifted.length === 0 ? 'PASS' : 'WARN', drifted.length === 0
-                ? `배선된 매처가 출하 기본값과 같습니다 (${init_1.MATCHERS.guardrail})`
-                : `배선 ${drifted.join(' | ')} / 출하 기본값 ${init_1.MATCHERS.guardrail} — 매처에 걸리지 않는 도구는 훅에 도달하지 않습니다`, drifted.length === 0 ? undefined : 'holmes-kit init --target <dir> --force 로 갱신하고 Claude Code를 재시작하세요.');
+                ? `The wired matcher equals the shipped default (${init_1.MATCHERS.guardrail})`
+                : `wired ${drifted.join(' | ')} / shipped default ${init_1.MATCHERS.guardrail} — a tool the matcher does not catch never reaches the hook`, drifted.length === 0 ? undefined : 'Run holmes-kit init --target <dir> --force to refresh it, and restart Claude Code.');
         }
         catch { /* an unreadable settings file is `target wiring`'s business, not this check's */ }
     }
@@ -989,13 +1006,13 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         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
+        // @implements A-SPEC-477 — the ".env stopgap" 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('semantic key location', 'WARN', `Found a semantic-key pattern in the project .env — an in-tree key is a commit-accident and in-session-read surface`
+                + (envTemp.mode !== undefined && (envTemp.mode & 0o077) !== 0 ? ` (file mode ${(envTemp.mode & 0o777).toString(8)} — wider than 0600)` : '') + '.', 'Store it out of the tree with `holmes-kit semantic-key set` (the keychain, or ~/.holmes/credentials.json at 0600), then remove that line from .env.');
         }
     }
     add('environment', 'PASS', present);
@@ -1074,7 +1091,7 @@ function wiringSpawnCheck(command, args, timeoutMs = 30000, platform = process.p
     const spec = (0, spawn_spec_1.spawnSpecFor)(command, args, platform);
     // The re-init prescription is only honest when the wiring might actually be stale. A command the
     // OS cannot find (ENOENT) re-inits into the identical failure forever — the measured loop.
-    const enoentFix = `\`${command}\` 명령을 찾지 못했습니다(PATH 또는 플랫폼) — 배선 문자열이 옳다면 재-init은 도움이 되지 않습니다. 같은 명령을 셸에서 직접 실행해 확인하십시오.`;
+    const enoentFix = `The \`${command}\` command was not found (PATH or platform) — if the wiring string is correct, re-init does not help. Run the same command directly in a shell to check.`;
     const spawnFailFix = (e) => e?.code === 'ENOENT' ? enoentFix : 'Re-run `holmes-kit init` in the target to rewrite the wiring.';
     return new Promise((resolve) => {
         let done = false;
@@ -1120,8 +1137,8 @@ function wiringSpawnCheck(command, args, timeoutMs = 30000, platform = process.p
                         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` 후 다시 실행하거나,'
-                                + ' 그 버전이 레지스트리에 게시됐는지 확인하십시오. 하네스는 응답한 버전으로 집행합니다.');
+                            finish('WARN', `wiring pins ${pinned} but the live server answered v${live}: \`${quoted}\``, 'npx may resolve to a cached old version — run `npx clear-npx-cache` and retry, or'
+                                + ' confirm that version is published to the registry. The harness enforces with whatever version answered.');
                             return;
                         }
                         finish('PASS', `wiring reaches a live server (v${live}): \`${quoted}\``);
@@ -1227,7 +1244,7 @@ function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
                 }
                 catch {
                     continue;
-                } // 서버의 로그 줄은 프로토콜이 아니다
+                } // a server log line is not the protocol
                 if (msg.error && (msg.id === 1 || msg.id === 2)) {
                     finish('FAIL', `MCP server answered ${msg.id === 1 ? 'initialize' : 'tools/list'} with an error: ${String(msg.error.message ?? msg.error.code)}`, 'The server started but refused the handshake — check the installed version against this package.');
                     return;
@@ -1279,11 +1296,11 @@ function pushGateCheck(target) {
         const hookPath = path.join(effectiveHooksDir(target), 'pre-push');
         const installed = fs.existsSync(hookPath) && fs.readFileSync(hookPath, 'utf8').includes(PUSH_HOOK_SIGNATURE);
         return installed
-            ? { name: 'push gate', level: 'PASS', detail: 'pre-push 증빙 게이트가 설치되어 있습니다 (test_run 원장 대조)' }
+            ? { name: 'push gate', level: 'PASS', detail: 'The pre-push evidence gate is installed (test_run ledger comparison)' }
             : {
                 name: 'push gate', level: 'WARN',
-                detail: 'pre-push 증빙 게이트가 설치되어 있지 않습니다 — 미검증 HEAD 가 다른 에이전트의 기준선이 될 수 있습니다',
-                fix: `${(0, npx_bin_1.npxBin)()} holmes-kit install-push-gate 를 실행하십시오 (기존 훅은 덮지 않습니다)`,
+                detail: 'The pre-push evidence gate is not installed — an unverified HEAD could become another agent\'s baseline',
+                fix: `Run ${(0, npx_bin_1.npxBin)()} holmes-kit install-push-gate (it does not overwrite an existing hook)`,
             };
     }
     catch {
@@ -1310,7 +1327,7 @@ function formatChecks(checks) {
  * 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
+ *   PASS codex wiring      — MCP wiring resolves to this install       <- 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
@@ -1348,15 +1365,15 @@ async function wiringHandshakeChecks(target) {
             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} 로 다시 배선하십시오.` });
+            out.push({ name, level: 'WARN', detail: `Could not read a runnable ${init_1.SERVER_NAME} wiring from ${wiring.file}`,
+                fix: `Rewire with 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 로 경로를 갱신하십시오.` });
+                out.push({ name, level: 'FAIL', detail: `The wiring points at a missing file: ${bin}`,
+                    fix: `Run holmes-kit init --target <dir> --agent ${wiring.label} --force to refresh the path.` });
                 continue;
             }
         }
@@ -1386,28 +1403,28 @@ function semanticTierVerdict(t) {
         // 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' : '알 수 없음';
+                : t.keySource === 'keychain' ? 'macOS keychain'
+                    : t.keySource === 'file' ? '~/.holmes/credentials.json' : 'unknown';
         return {
             level: 'PASS',
-            detail: `의미 검색 티어: cloud (${t.model}, 키 출처: ${src}) — 스펙 산문·파일 경로·심볼명이 외부(Google API)로 전송됩니다. 키 설정이 이 전송에 대한 동의이며, 값은 이 보고서에 절대 출력되지 않습니다.`,
+            detail: `Semantic search tier: cloud (${t.model}, key source: ${src}) — spec prose, file paths, and symbol names are sent to an external service (Google API). Setting the key is consent to that transfer, and the value is never printed into this report.`,
         };
     }
     if (t.tier === 'local') {
         return {
             level: 'PASS',
-            detail: `의미 검색 티어: local (${t.model}, ${(0, tier_1.POOLING_OF)(t.model ?? '')} 풀링) — 이그레스 없음. 어휘가 닿지 않는 요청의 52%를 회수합니다(실측).`,
+            detail: `Semantic search tier: local (${t.model}, ${(0, tier_1.POOLING_OF)(t.model ?? '')} pooling) — no egress. Recovers 52% of requests lexical search misses (measured).`,
         };
     }
     return {
         level: 'PASS',
-        detail: '의미 검색 티어: none — 어휘·인용·그래프만 사용 중입니다. 어휘가 닿지 않는 요청(실측 16.4%)은 회수율 0%입니다.',
-        fix: '로컬 티어(이그레스 없음): npm i @xenova/transformers — 어휘-제로 회수 0→52%. cloud 티어(opt-in, 외부 전송 동의): GEMINI_API_KEY 설정 — 0→92%.',
+        detail: 'Semantic search tier: none — using lexical, citation, and graph signals only. Requests lexical search misses (measured 16.4%) have 0% recall.',
+        fix: 'Local tier (no egress): npm i @xenova/transformers — lexical-zero recall 0→52%. Cloud tier (opt-in, consent to external transfer): set GEMINI_API_KEY — 0→92%.',
     };
 }
 /**
  * @implements A-SPEC-477
- * Detects the "임시 조치": a semantic key pattern inside the PROJECT's .env. The value is read
+ * Detects the "stopgap": 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) {