@holmes-lab/holmes-kit 0.1.18 → 0.2.1

package/dist/holmes/cli/codex-toml.js

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_TABLE = void 0;
+exports.codexMcpBlock = codexMcpBlock;
+exports.mergeCodexToml = mergeCodexToml;
+exports.removeCodexToml = removeCodexToml;
+exports.readCodexHolmesEntry = readCodexHolmesEntry;
+/** The one table holmes-kit owns in a Codex config.toml. */
+exports.CODEX_TABLE = 'mcp_servers.holmes-kit';
+const HEADER = `[${exports.CODEX_TABLE}]`;
+/** TOML basic-string escape — backslash and quote, the named whitespace escapes, then any remaining
+ * C0 control character as \uXXXX. Built by code point so no literal control byte lives in the source. */
+function tomlStr(s) {
+    let out = '';
+    for (const ch of s) {
+        const code = ch.codePointAt(0);
+        if (ch === '\\')
+            out += '\\\\';
+        else if (ch === '"')
+            out += '\\"';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += ch;
+    }
+    return `"${out}"`;
+}
+/**
+ * Serialize the `[mcp_servers.holmes-kit]` table. `env` is an inline table so the whole entry is ONE
+ * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
+ * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
+ */
+function codexMcpBlock(entry, specsDir) {
+    const args = entry.args.map(tomlStr).join(', ');
+    return [
+        HEADER,
+        `command = ${tomlStr(entry.command)}`,
+        `args = [${args}]`,
+        `env = { HOLMES_SPECS = ${tomlStr(specsDir)} }`,
+        '',
+    ].join('\n');
+}
+/** Advance the string/bracket state across one line's characters (comments end the line). */
+function advance(line, st) {
+    let { ml, depth } = st;
+    let i = 0;
+    while (i < line.length) {
+        if (ml === '"""') {
+            if (line.startsWith('"""', i)) {
+                ml = null;
+                i += 3;
+            }
+            else if (line[i] === '\\') {
+                i += 2;
+            }
+            else
+                i += 1;
+            continue;
+        }
+        if (ml === "'''") { // literal: no escapes
+            if (line.startsWith("'''", i)) {
+                ml = null;
+                i += 3;
+            }
+            else
+                i += 1;
+            continue;
+        }
+        if (line.startsWith('"""', i)) {
+            ml = '"""';
+            i += 3;
+            continue;
+        }
+        if (line.startsWith("'''", i)) {
+            ml = "'''";
+            i += 3;
+            continue;
+        }
+        const c = line[i];
+        if (c === '#')
+            break; // comment runs to end of line
+        if (c === '"') {
+            i += 1;
+            while (i < line.length && line[i] !== '"') {
+                if (line[i] === '\\')
+                    i += 1;
+                i += 1;
+            }
+            i += 1;
+            continue;
+        }
+        if (c === "'") {
+            i += 1;
+            while (i < line.length && line[i] !== "'")
+                i += 1;
+            i += 1;
+            continue;
+        }
+        if (c === '[' || c === '{') {
+            depth += 1;
+            i += 1;
+            continue;
+        }
+        if (c === ']' || c === '}') {
+            depth = Math.max(0, depth - 1);
+            i += 1;
+            continue;
+        }
+        i += 1;
+    }
+    return { ml, depth };
+}
+/** State at the START of each line (index-aligned to `lines`). */
+function lineStartStates(lines) {
+    const states = [];
+    let st = { ml: null, depth: 0 };
+    for (const line of lines) {
+        states.push(st);
+        st = advance(line, st);
+    }
+    return states;
+}
+/**
+ * The dotted key path of a table-header line, quotes stripped and each segment trimmed — so
+ * `[mcp_servers.holmes-kit]`, `[mcp_servers."holmes-kit"]`, and `[ mcp_servers . holmes-kit ]` all
+ * yield ['mcp_servers','holmes-kit'] (TOML treats them as the SAME table; missing an alias would
+ * append a duplicate table and invalidate the whole file — round-1 quoted-key, round-2 whitespace).
+ * Returns null when the line is not a table header.
+ */
+function tableKeyPath(line) {
+    const m = line.match(/^\s*\[\[?([^\]]*)\]\]?\s*(#.*)?$/);
+    if (!m)
+        return null;
+    const inner = m[1];
+    const segs = [];
+    let cur = '';
+    let q = null;
+    for (let i = 0; i < inner.length; i++) {
+        const c = inner[i];
+        if (q) {
+            if (c === q)
+                q = null;
+            else
+                cur += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            q = c;
+            continue;
+        }
+        if (c === '.') {
+            segs.push(cur.trim());
+            cur = '';
+            continue;
+        }
+        cur += c;
+    }
+    segs.push(cur.trim());
+    if (q !== null)
+        return null; // unbalanced quote — not a clean header
+    return segs;
+}
+const isOurTable = (kp) => kp.length === 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
+const isOurPrefix = (kp) => kp.length >= 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
+/**
+ * Locate our region as a [start, end) line-index pair, or null if absent. `start` is our table's
+ * header line; `end` is the first later line that opens a DIFFERENT top-level table (exclusive), or
+ * lines.length. Only real headers (outside strings, bracket-depth 0) are considered — AND the end
+ * boundary closes on ANY top-level header line, even one `tableKeyPath` cannot normalize (e.g. a
+ * quoted key containing `]`). That fail-safe is the point: an unrecognized header is never OURS, so
+ * treating it as a boundary preserves the foreign table rather than swallowing it (round-3 finding).
+ */
+function ourRegion(lines) {
+    const states = lineStartStates(lines);
+    const isTopLevelHeaderLine = (i) => states[i].ml === null && states[i].depth === 0 && /^\s*\[/.test(lines[i]);
+    const keyAt = (i) => (isTopLevelHeaderLine(i) ? tableKeyPath(lines[i]) : null);
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const kp = keyAt(i);
+        if (kp && isOurTable(kp)) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (!isTopLevelHeaderLine(i))
+            continue;
+        const kp = tableKeyPath(lines[i]);
+        if (!(kp && isOurPrefix(kp))) {
+            end = i;
+            break;
+        } // any non-our (incl. unparseable) header closes us
+    }
+    return { start, end };
+}
+/**
+ * Merge `block` (a full `codexMcpBlock` output) into `existing`. When `existing` is null/empty the
+ * block stands alone. When our table is already present its region is REPLACED (no duplicate); when
+ * absent the block is appended after a blank-line separator. Every other line is preserved verbatim.
+ */
+function mergeCodexToml(existing, block) {
+    if (existing == null || existing.trim() === '')
+        return block;
+    const lines = existing.split('\n');
+    const region = ourRegion(lines);
+    const blockLines = block.replace(/\n$/, '').split('\n');
+    if (region) {
+        const after = lines.slice(region.end);
+        const merged = [...lines.slice(0, region.start), ...blockLines, ...after];
+        return merged.join('\n').replace(/\n*$/, '\n');
+    }
+    // Append: exactly one blank line between the user's content and our block.
+    const base = existing.replace(/\n*$/, '');
+    return `${base}\n\n${block.replace(/\n*$/, '')}\n`;
+}
+/** Strip our region from `existing`, preserving everything else. Absent → returned unchanged. */
+function removeCodexToml(existing) {
+    const lines = existing.split('\n');
+    const region = ourRegion(lines);
+    if (!region)
+        return existing;
+    const before = lines.slice(0, region.start);
+    const after = lines.slice(region.end);
+    // Drop a trailing blank line left dangling between `before` and `after` so removal is clean.
+    while (before.length > 0 && before[before.length - 1].trim() === '')
+        before.pop();
+    const merged = [...before, ...after];
+    const joined = merged.join('\n');
+    if (joined.trim() === '')
+        return '';
+    return joined.replace(/\n*$/, '\n');
+}
+/**
+ * Read `{command,args}` from our table in a config.toml — for doctor's drift check. Parses only the
+ * shape `codexMcpBlock` writes; anything it cannot read returns null (doctor then WARNs rather than
+ * translating an unreadable wiring into a pass).
+ */
+function readCodexHolmesEntry(raw) {
+    const lines = raw.split('\n');
+    const region = ourRegion(lines);
+    if (!region)
+        return null;
+    let command = null;
+    let args = null;
+    for (let i = region.start + 1; i < region.end; i++) {
+        const cmd = lines[i].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/);
+        if (cmd)
+            command = unescapeToml(cmd[1]);
+        const arr = lines[i].match(/^\s*args\s*=\s*\[(.*)\]\s*(#.*)?$/);
+        if (arr)
+            args = parseTomlStringArray(arr[1]);
+    }
+    if (command === null || args === null)
+        return null;
+    return { command, args };
+}
+function unescapeToml(s) {
+    return s.replace(/\\(u[0-9a-fA-F]{4}|.)/g, (_, e) => {
+        if (e[0] === 'u')
+            return String.fromCharCode(parseInt(e.slice(1), 16));
+        const map = { n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' };
+        return map[e] ?? e;
+    });
+}
+/** Parse a TOML inline array of basic strings: `"a", "b"` → ['a','b']. Non-conforming → []. */
+function parseTomlStringArray(inner) {
+    const out = [];
+    const re = /"((?:[^"\\]|\\.)*)"/g;
+    let mm;
+    while ((mm = re.exec(inner)) !== null)
+        out.push(unescapeToml(mm[1]));
+    return out;
+}

package/dist/holmes/cli/doctor.js

@@ -51,6 +51,7 @@ const settings_merge_1 = require("./settings-merge");
 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 mcp_launcher_1 = require("./mcp-launcher");
 const GRAMMARS = [
     'tree-sitter-typescript', 'tree-sitter-python', 'tree-sitter-c-sharp', 'tree-sitter-java',
@@ -407,6 +408,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
@@ -554,6 +713,53 @@ 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-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
+        // `.codex/mcp_config.json` (JSON) this project used to write and Codex never read. Same A-SPEC-193
+        // principle: no file → no diagnosis; a present file is judged for whether it resolves to THIS
+        // install. A leftover JSON with no config.toml is a stale wiring in a location Codex ignores → WARN.
+        const cdxToml = path.join(target, '.codex', 'config.toml');
+        const cdxJson = path.join(target, '.codex', 'mcp_config.json');
+        if (fs.existsSync(cdxToml)) {
+            let raw = null;
+            try {
+                raw = fs.readFileSync(cdxToml, 'utf8');
+            }
+            catch { /* handled below */ }
+            if (raw === null) {
+                add('codex wiring', 'FAIL', `${cdxToml} 를 읽을 수 없습니다`, '파일 권한을 확인하거나 지우고 다시 배선하십시오.');
+            }
+            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 로 다시 배선하십시오.');
+                }
+                else if (entry.command === 'node') {
+                    // @implements A-SPEC-266 — "이 설치본으로 해석됩니다"는 존재만으로는 부족하다: node 배선은
+                    // holmes-mcp.js 를 가리켜야 한다. 아무 존재 파일(예: /etc/hosts)에 PASS 를 주면 "해석된다"는
+                    // 주장이 검사보다 강해진다(적대 라운드 Finding 2). 파일명까지 확인해 그 간극을 좁힌다.
+                    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".
+                    const realBin = (() => { try {
+                        return fs.realpathSync(bin);
+                    }
+                    catch {
+                        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 로 절대 경로를 갱신하십시오.');
+                }
+                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 로 다시 배선하십시오.');
+                }
+            }
+        }
+        else if (fs.existsSync(cdxJson)) {
+            add('codex wiring', 'WARN', `codex 배선이 Codex 가 읽지 않는 구식 위치(${cdxJson})에 있습니다 — config.toml 로 옮겨야 합니다`, 'holmes-kit init --target <dir> --agent codex 로 다시 배선하면 config.toml 로 이전되고 구식 파일이 정리됩니다.');
+        }
         try {
             const sp = wiredSettingsPath(target);
             const st = JSON.parse(fs.readFileSync(sp, 'utf8'));

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;