@holmes-lab/holmes-kit 0.1.17 → 0.2.0

package/dist/holmes/cli/doctor.js

@@ -407,6 +407,164 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 : `상위가 approved가 아닌 승인 스펙 ${orphaned.length}건: ${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
+        // Distributed id preemption (the 2026-08-23 REQ-220 incident): two offline workspaces issue the
+        // same number, silent at create and at push. Judgment lives in the ONE pure detector; identity is
+        // the CANONICAL spec digest (specDigest: CRLF-folded, SEAL_FIELDS excluded — round-1: raw bytes
+        // turned a CRLF checkout difference into a fake collision, and trusting the self-declared seal
+        // hid a real one). The existing `duplicate spec ids` check above answers a different question
+        // (id count) and stays untouched. OWN try/catch (round-1): sharing the block above meant an
+        // unrelated upstream throw silently erased these checks — a failure here must surface as WARN,
+        // never as a vanished line.
+        try {
+            const { detectIdCollisions } = require('../spec/id-collision');
+            const { parseSpec } = require('../spec/spec-parser');
+            const crypto = require('node:crypto');
+            const specsRoot = path.join(target, '.ax', 'specs');
+            const entries = [];
+            let skipped = 0; // would-be specs present but not judged — a PASS must name its reduced scope (round-1)
+            // The collision identity is the WHOLE BODY, canonicalized — not a composite of parser splits
+            // (round-3): the round-2 specDigest+preamble composite inherited every split blind spot one at
+            // a time (preamble missing → round-2; fence-gap text in NEITHER half → round-3), and hashing
+            // the preamble raw made whitespace-only byte differences collide with a false forgery
+            // accusation on top. One key over everything after the frontmatter ends the class: CRLF folded
+            // (mirrors parseSpec), per-line trailing whitespace and blank lines dropped (formatting is not
+            // substance for an advisory WARN), plus the substantive frontmatter (type/title/dependsOn) via
+            // JSON array serialization — no field aliasing. The SEAL digest is untouched, as before.
+            const collisionKey = (folded, spec) => {
+                const fence = /^---\n[\s\S]*?\n---\n?/.exec(folded);
+                const body = (fence ? folded.slice(fence[0].length) : folded)
+                    .split('\n').map((l) => l.trimEnd()).filter((l) => l !== '').join('\n');
+                return 'sha256:' + crypto.createHash('sha256')
+                    .update(JSON.stringify([spec.type, spec.title, [...spec.dependsOn].sort(), body])).digest('hex');
+            };
+            // Symlinked directories are FOLLOWED (round-2): `Dirent.isDirectory()` is false for a dir
+            // symlink, so specs behind one silently left the judgment with skipped=0 — an unqualified PASS
+            // over an unexamined store. The realpath visited-set breaks symlink cycles. An UNREADABLE or
+            // un-realpathable directory counts into `skipped` (round-3) — a subtree the walk could not
+            // enter is an unexamined region, and a PASS must never silently span it.
+            const seen = new Set();
+            const collect = (d) => {
+                let real;
+                // "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
+                // permission-locked store. Real refusals (EACCES) and cycles (ELOOP — an entry exists, it
+                // just cannot be entered) still count as unexamined regions.
+                try {
+                    real = fs.realpathSync(d);
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'ENAMETOOLONG')
+                        skipped++;
+                    return;
+                }
+                if (seen.has(real))
+                    return;
+                seen.add(real);
+                let dirents;
+                // The FOURTH errno site of the absence class (round-8): a regular FILE at the specs path
+                // (realpath succeeds, readdir throws ENOTDIR) holds nothing judgeable — same doctrine as a
+                // TOCTOU-deleted dir (ENOENT, round-5). EACCES stays counted (an enterable-refused dir is a
+                // real unexamined region — the round-3 chmod pin rides this catch).
+                try {
+                    dirents = fs.readdirSync(d, { withFileTypes: true });
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                        skipped++;
+                    return;
+                }
+                for (const e of dirents) {
+                    const p = path.join(d, e.name);
+                    let isDir = e.isDirectory();
+                    let isFile = e.isFile();
+                    if (!isDir && !isFile && e.isSymbolicLink()) {
+                        // The round-4 errno rule applies HERE too (round-5): a target that DOES NOT RESOLVE —
+                        // ENOENT/ELOOP, and equally ENOTDIR/ENAMETOOLONG (round-6: "any other errno means the
+                        // target exists" was false for a link traversing a regular file) — is absence, so only
+                        // a spec-LOOKING name counts (round-3: a dangling assets.png fabricates a phantom scope
+                        // reduction). A genuinely REFUSED target (EACCES …) exists but cannot even be typed: an
+                        // unexamined region regardless of its name, counted unconditionally.
+                        try {
+                            const st = fs.statSync(p);
+                            isDir = st.isDirectory();
+                            isFile = st.isFile();
+                        }
+                        catch (err) {
+                            const code = err.code;
+                            const unresolved = code === 'ENOENT' || code === 'ELOOP' || code === 'ENOTDIR' || code === 'ENAMETOOLONG';
+                            if (unresolved) {
+                                if (e.name.endsWith('.md'))
+                                    skipped++;
+                            }
+                            else
+                                skipped++;
+                            continue;
+                        }
+                    }
+                    if (isDir) {
+                        collect(p);
+                        continue;
+                    }
+                    if (!e.name.endsWith('.md'))
+                        continue;
+                    // TYPE before READ (round-6): readFileSync's open(2) blocks FOREVER on a FIFO with no
+                    // writer — no throw, no survival catch, doctor simply never completes. A non-regular
+                    // file named *.md cannot be judged; it is counted, never opened.
+                    if (!isFile) {
+                        skipped++;
+                        continue;
+                    }
+                    try {
+                        // Strip a UTF-8 BOM before parsing (round-1): a BOM broke the frontmatter match, so a
+                        // BOM'd colliding replica silently vanished from the judgment instead of participating.
+                        const raw = fs.readFileSync(p, 'utf8').replace(/^/, '');
+                        const folded = raw.replace(/\r\n/g, '\n');
+                        const spec = parseSpec(folded);
+                        if (!spec.id) {
+                            skipped++;
+                            continue;
+                        } // unreadable-as-spec, still counted (round-1)
+                        entries.push({
+                            file: path.relative(specsRoot, p).split(path.sep).join('/'),
+                            id: spec.id,
+                            approvedDigest: typeof spec.frontmatter.approved_digest === 'string' ? spec.frontmatter.approved_digest : undefined,
+                            contentDigest: collisionKey(folded, spec),
+                        });
+                    }
+                    catch {
+                        skipped++;
+                    }
+                }
+            };
+            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 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}`
+                : 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}`
+                : families.map((f) => `${f.id}: ${f.files.join(', ')}`).join('; ') + scopeNote, families.length === 0 ? undefined
+                : 'bare 스펙과 점 하위 가족이 공존합니다 — 두 워크스페이스가 같은 번호를 다르게 전개한 신호이니 한쪽 전개로 통일하세요.');
+        }
+        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}`);
+        }
     }
     // @implements A-SPEC-176
     // `list()` drops any file it cannot parse, which is correct for a gate but leaves the author
@@ -487,6 +645,38 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             }
         }
         catch { /* .mcp.json 부재/파싱 실패 → 이 점검 없이 진행 */ }
+        // @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
+        // (which starts the server directly, not through the wiring), and the release tarball probe —
+        // measured 2026-08-23. A node wiring is judged on path existence (a source checkout must not pay
+        // a spawn), an absent .mcp.json is skipped by name, and the spawn is BOUNDED: it succeeds or
+        // fails inside its deadline, never hangs (REQ-258's lesson, applied from this check onward).
+        {
+            const mcpPath = path.join(target, '.mcp.json');
+            if (!fs.existsSync(mcpPath)) {
+                add('mcp wiring spawn', 'PASS', 'skipped — no .mcp.json in the target: an absent wiring is not a dead one');
+            }
+            else {
+                try {
+                    const server = JSON.parse(fs.readFileSync(mcpPath, 'utf8'))
+                        .mcpServers?.[init_1.SERVER_NAME];
+                    if (!server || typeof server.command !== 'string' || !Array.isArray(server.args)) {
+                        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') {
+                        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.');
+                    }
+                    else {
+                        checks.push(await wiringSpawnCheck(server.command, server.args));
+                    }
+                }
+                catch {
+                    add('mcp wiring spawn', 'WARN', 'could not read .mcp.json', 'Run `holmes-kit init` in the target to rewrite the wiring.');
+                }
+            }
+        }
         // @implements A-SPEC-193 — 배선된 하네스마다 그 하네스의 배선을 검사한다. 배선되지 않은
         // 하네스는 진단하지 않는다(없는 것을 결함이라 부르면 doctor 가 소음이 된다).
         const agyHooks = path.join(target, '.agents', 'hooks.json');
@@ -522,6 +712,30 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             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')} 로 링크하거나 복사하십시오.`);
         }
+        // @implements A-SPEC-264 — 세 하네스 중 codex 만 배선 검사가 없었다(REQ-264 실측). 배선된
+        // 하네스마다 그 하네스의 배선을 검사한다는 A-SPEC-193 의 원칙 그대로: 파일이 없으면
+        // 진단하지 않고, 있으면 이 설치본으로 해석되는지를 판정한다.
+        const cdxMcp = path.join(target, '.codex', 'mcp_config.json');
+        if (fs.existsSync(cdxMcp)) {
+            try {
+                const doc = JSON.parse(fs.readFileSync(cdxMcp, 'utf8'));
+                const entry = doc.mcpServers?.[init_1.SERVER_NAME];
+                if (!entry || typeof entry.command !== 'string' || !Array.isArray(entry.args)) {
+                    add('codex wiring', 'WARN', `${cdxMcp} 에 실행 가능한 ${init_1.SERVER_NAME} 항목이 없습니다 — 반쯤 된 배선입니다`, 'holmes-kit init --target <dir> --agent codex 로 다시 배선하십시오.');
+                }
+                else if (entry.command === 'node') {
+                    const bin = entry.args[0] ?? '';
+                    add('codex wiring', fs.existsSync(bin) ? 'PASS' : 'FAIL', fs.existsSync(bin) ? `MCP 배선이 이 설치본으로 해석됩니다: ${bin}` : `MCP 배선이 없는 파일을 가리킵니다: ${bin}`, fs.existsSync(bin) ? undefined : 'holmes-kit init --target <dir> --agent codex --force 로 절대 경로를 갱신하십시오.');
+                }
+                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 로 다시 배선하십시오.');
+                }
+            }
+            catch {
+                add('codex wiring', 'FAIL', `${cdxMcp} 를 읽을 수 없습니다(JSON 아님)`, '파일을 고치거나 지우고 다시 배선하십시오.');
+            }
+        }
         try {
             const sp = wiredSettingsPath(target);
             const st = JSON.parse(fs.readFileSync(sp, 'utf8'));
@@ -616,6 +830,54 @@ function cleanupOnSignal(dir) {
  * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
  * very first run against a healthy server).
  */
+// @implements A-SPEC-259
+// Spawn the TARGET's wiring verbatim and require initialize inside the deadline. Unlike
+// `mcpHandshakeCheck` below (which proves this INSTALL can serve), this proves the WIRING the
+// harness will actually run reaches a server — the gap the dead npx form lived in.
+function wiringSpawnCheck(command, args, timeoutMs = 30000) {
+    const quoted = `${command} ${args.join(' ')}`;
+    return new Promise((resolve) => {
+        let done = false;
+        let out = '';
+        let child;
+        const finish = (level, detail, fix) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                child.kill();
+            }
+            catch { /* already gone */ }
+            resolve({ name: 'mcp wiring spawn', level, detail, fix });
+        };
+        const timer = setTimeout(() => finish('FAIL', `wiring did not answer initialize within ${timeoutMs / 1000}s: \`${quoted}\``, 'Re-run `holmes-kit init` in the target to rewrite the wiring, then re-run doctor.'), timeoutMs);
+        try {
+            child = (0, node_child_process_1.spawn)(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch (e) {
+            finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.');
+            return;
+        }
+        child.on('error', (e) => finish('FAIL', `wiring could not be spawned: \`${quoted}\` — ${e.message}`, 'Re-run `holmes-kit init` in the target to rewrite the wiring.'));
+        child.on('exit', (code) => finish('FAIL', `wiring exited (code ${code}) before answering initialize: \`${quoted}\``, 'Re-run `holmes-kit init` in the target to rewrite the wiring.'));
+        child.stdin?.on('error', () => { });
+        child.stdout?.on('data', (d) => {
+            out += String(d);
+            for (const line of out.split('\n')) {
+                try {
+                    const m = JSON.parse(line);
+                    if (m?.result?.serverInfo) {
+                        finish('PASS', `wiring reaches a live server (v${m.result.serverInfo.version ?? '?'}): \`${quoted}\``);
+                        return;
+                    }
+                }
+                catch { /* partial line */ }
+            }
+        });
+        child.stdin?.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'holmes-doctor', version: '1' } } }) + '\n');
+    });
+}
 function mcpHandshakeCheck(packageRoot, timeoutMs = 15000) {
     return new Promise((resolve) => {
         const mcpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-doctor-mcp-'));

package/dist/holmes/cli/gitignore-merge.d.ts

@@ -7,6 +7,10 @@ export declare const BEGIN = "# >>> holmes-kit >>>";
 export declare const END = "# <<< holmes-kit <<<";
 /** Derived/runtime paths holmes-kit creates in a target project. */
 export declare const IGNORE_LINES: string[];
+export declare const ATTRIBUTE_LINES: string[];
+/** As `mergeGitignore`, over `.gitattributes` — the same marker block machinery, so idempotence
+ *  and user-content preservation are inherited rather than re-implemented. */
+export declare function mergeGitattributes(existing: string): string;
 /**
  * Add (or refresh) the holmes-kit block. Idempotent: a second call reproduces the same text.
  * Preserves everything outside the block, and preserves whether the file ended with a newline.

package/dist/holmes/cli/gitignore-merge.js

@@ -1,7 +1,8 @@
 "use strict";
 // @implements A-SPEC-100.2
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IGNORE_LINES = exports.END = exports.BEGIN = void 0;
+exports.ATTRIBUTE_LINES = exports.IGNORE_LINES = exports.END = exports.BEGIN = void 0;
+exports.mergeGitattributes = mergeGitattributes;
 exports.mergeGitignore = mergeGitignore;
 exports.removeGitignoreBlock = removeGitignoreBlock;
 exports.hasGitignoreBlock = hasGitignoreBlock;
@@ -42,6 +43,21 @@ exports.IGNORE_LINES = [
     '.agents/hooks.json',
     '.agents/mcp_config.json',
 ];
+// @implements A-SPEC-256.1
+// Merge attributes for the append-only files: `union` keeps BOTH sides' lines on merge — for these
+// files "both" is always the right answer (the 2026-08-23 merge resolved every such conflict by
+// hand to exactly this). The resulting chain seams are `ledger rechain`'s job, not the merge's.
+exports.ATTRIBUTE_LINES = [
+    '# @implements A-SPEC-256.1 — append-only 파일은 병합에서 양쪽 줄을 모두 보존한다(union).',
+    '# 남는 체인 이음새는 `holmes-kit ledger rechain`의 일이다.',
+    '.ax/ledger/*.jsonl merge=union',
+    '.ax/approvals/queue.jsonl merge=union',
+];
+/** As `mergeGitignore`, over `.gitattributes` — the same marker block machinery, so idempotence
+ *  and user-content preservation are inherited rather than re-implemented. */
+function mergeGitattributes(existing) {
+    return mergeGitignore(existing, exports.ATTRIBUTE_LINES);
+}
 function findBlock(text) {
     const lines = text.split('\n');
     const start = lines.findIndex((l) => l.trim() === exports.BEGIN);

package/dist/holmes/cli/index.d.ts

@@ -12,3 +12,26 @@
  */
 export declare function packageRoot(): string;
 export declare function main(argv: string[]): Promise<number>;
+/**
+ * @implements A-SPEC-262.1
+ * Is this the normal end of a pipeline rather than a fault? Round-10: `approve --list | head` printed
+ * a Node stack dump and exited 1 — on a command whose own help says it is for scripts, where a
+ * consumer that stops reading is how pipelines end. Exported so the decision is testable without
+ * spawning a process and racing a pipe.
+ */
+export declare const isBrokenPipe: (err: NodeJS.ErrnoException | undefined) => boolean;
+/**
+ * @implements A-SPEC-262.1
+ * A broken stdout pipe is the normal end of `| head`, not a fault worth a thousand bytes of Node
+ * internals on the operator's screen; exit quietly with the conventional status.
+ *
+ * Round-10 installed this ONLY inside `if (require.main === module)`. Round-11 measured that the
+ * shipped `holmes-kit` never runs that block — `bin/holmes-kit.js` loads this file as a MODULE and
+ * calls `main()`, so `require.main` is the bin, not this module. The guard was therefore DEAD on the
+ * shipped binary: an interactive or `--watch` surface piped to a reader that closes (`| head`)
+ * crashed with an unhandled `'error'` EPIPE stack and exit 1 (measured byte-identical for one-shot
+ * and watch — a shared adapter property, not a watch defect). Installing from `main()` — the one
+ * path every shipped invocation takes — makes the round-10 fix actually run. Idempotent: the module
+ * flag keeps repeated `main()` calls (the test suite) from stacking listeners.
+ */
+export declare function installPipeGuard(): void;