@holmes-lab/holmes-kit 0.1.0

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

@@ -0,0 +1,84 @@
+"use strict";
+// @implements A-SPEC-100.2
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IGNORE_LINES = exports.END = exports.BEGIN = void 0;
+exports.mergeGitignore = mergeGitignore;
+exports.removeGitignoreBlock = removeGitignoreBlock;
+exports.hasGitignoreBlock = hasGitignoreBlock;
+/**
+ * PURE .gitignore block merge. holmes-kit writes derived state under `.ax/` in the TARGET project
+ * (ledger, cpg_cache, reports) that must never be committed. The block is delimited so it can be
+ * added, refreshed, and removed exactly — never touching the user's own lines.
+ */
+exports.BEGIN = '# >>> holmes-kit >>>';
+exports.END = '# <<< holmes-kit <<<';
+/** Derived/runtime paths holmes-kit creates in a target project. */
+exports.IGNORE_LINES = [
+    // @implements A-SPEC-148
+    // ADR-012 decided the provenance and progress ledgers are SSOT and must be SHARED — "what cannot
+    // be reconstructed must be shared", because a colleague's clone otherwise has an empty chain and
+    // cannot answer who decided what, when, or why. That decision was only ever applied to this
+    // repository's hand-edited .gitignore; every project `init` touched still ignored the whole
+    // directory, so ADR-012 was silently not in force for anyone else.
+    //
+    // The wildcard covers the per-replica chains too (`provenance.<replicaId>.jsonl`). Without it the
+    // split would have made the shared artefact local again — the exact regression the split exists
+    // to enable collaboration around.
+    '.ax/ledger/*',
+    '!.ax/ledger/provenance*.jsonl',
+    '!.ax/ledger/progress.jsonl',
+    '.ax/cpg_cache/',
+    '.ax/cpg_cache.json',
+    '.ax/reports/',
+    '.ax/*.sqlite*',
+    // `init` snapshots every config it touches before writing. Those snapshots are recovery aids, not
+    // project content — left untracked they show up in `git status` and read as install damage.
+    '.ax/state/',
+    '*.holmes-bak-*',
+    // @implements A-SPEC-193 — 하네스 배선물은 이 **설치본의 절대 경로**를 담는다(훅은 hooks.json
+    // 이 있는 디렉터리를 cwd 로 돌고, 패키지가 어디 설치됐는지는 기계마다 다르다). 그 경로가
+    // VCS 에 들어가면 다른 기계에서 남의 설치를 부르거나 아무것도 부르지 못한다. 팀과 공유하고
+    // 싶다면 이 두 줄을 지우고 명령을 상대 경로로 바꾸면 된다 — 기본값은 새지 않는 쪽이다.
+    '.agents/hooks.json',
+    '.agents/mcp_config.json',
+];
+function findBlock(text) {
+    const lines = text.split('\n');
+    const start = lines.findIndex((l) => l.trim() === exports.BEGIN);
+    if (start < 0)
+        return null;
+    const end = lines.findIndex((l, i) => i > start && l.trim() === exports.END);
+    return end < 0 ? null : { start, end };
+}
+/**
+ * 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.
+ */
+function mergeGitignore(existing, lines = exports.IGNORE_LINES) {
+    const block = [exports.BEGIN, ...lines, exports.END];
+    const found = findBlock(existing);
+    if (found) {
+        const src = existing.split('\n');
+        return [...src.slice(0, found.start), ...block, ...src.slice(found.end + 1)].join('\n');
+    }
+    if (existing.trim() === '')
+        return block.join('\n') + '\n';
+    const sep = existing.endsWith('\n') ? '' : '\n';
+    return `${existing}${sep}\n${block.join('\n')}\n`;
+}
+/** Remove the block (and the blank line that preceded it, if we added one). Inverse of merge. */
+function removeGitignoreBlock(existing) {
+    const found = findBlock(existing);
+    if (!found)
+        return existing;
+    const src = existing.split('\n');
+    let start = found.start;
+    if (start > 0 && src[start - 1].trim() === '')
+        start -= 1; // drop the separator blank line
+    const out = [...src.slice(0, start), ...src.slice(found.end + 1)];
+    return out.join('\n');
+}
+/** True iff the holmes-kit block is present. */
+function hasGitignoreBlock(existing) {
+    return findBlock(existing) !== null;
+}

package/dist/holmes/cli/governed-precondition.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DIRS = void 0;
+exports.hasGatedCode = hasGatedCode;
+exports.governedWarning = governedWarning;
+// @implements A-SPEC-172
+/**
+ * What a governed transition is about to block, and which playbook undoes it.
+ *
+ * Measured 2026-08-12: `init --mode governed --force` on a target with no approved A-SPEC succeeded
+ * and printed nothing about the precondition — from that moment every code write was denied. Without
+ * `--force` the same situation is refused with three lines that explain it. The transition passing is
+ * defensible (starting greenfield in governed mode and authoring specs first is a supported path);
+ * saying nothing is not.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const phase_1 = require("../guardrail/phase");
+const playbook_skills_1 = require("./playbook-skills");
+/**
+ * Directories that are never the user's own code.
+ *
+ * `.ax` and `.claude` are written by init itself, and `node_modules` is present in nearly every JS
+ * project — counting any of them makes the answer permanently `true` and the branch vacuous.
+ */
+const SKIP_DIRS = new Set([
+    '.ax', '.git', '.claude', 'node_modules', 'dist', 'build', 'vendor', 'target', '.venv', '__pycache__',
+]);
+/**
+ * How many directories the walk may visit.
+ *
+ * The cap only bites on projects with NO code — the walk returns at the first gated file — and those
+ * are exactly the ones where exhausting it gives the wrong playbook. Measured 2026-08-12 at roughly
+ * 0.05ms per directory, so 2000 costs about 100ms inside a one-shot command that also writes files
+ * and installs skills.
+ */
+exports.MAX_DIRS = 2000;
+/**
+ * Does this target contain a file the Write/Edit gate would refuse once governed mode is live?
+ *
+ * The judgement is `classifyAction` — the gate's own function. Re-deriving "is this code" from a
+ * second extension list would leave two sources of truth, and the guidance would be wrong the moment
+ * they drifted apart (the failure REQ-163 measured for path identity).
+ *
+ * Content is never read: `classifyAction`'s shebang signal needs the file open, which does not fit
+ * the cost ceiling, and missing it errs toward `adopt` — the harmless direction.
+ */
+function hasGatedCode(target) {
+    const queue = [target];
+    const seen = new Set();
+    let visited = 0;
+    while (queue.length > 0) {
+        // Budget exhausted before an answer: report the safe side. `adopt` on an empty project wastes a
+        // moment; `author-slice` on a real codebase is wrong advice.
+        if (visited >= exports.MAX_DIRS)
+            return true;
+        const dir = queue.shift();
+        visited++;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // an unreadable subdirectory must not take init down with it
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            let isDir = e.isDirectory();
+            let isFile = e.isFile();
+            // A symlinked source tree is still code the gate will deny writes to — REQ-163 made resolved
+            // identity the rule for paths, and skipping links here would put a second, disagreeing answer
+            // next to the gate's. One stat per link, not per file.
+            if (e.isSymbolicLink()) {
+                try {
+                    const st = fs.statSync(full);
+                    isDir = st.isDirectory();
+                    isFile = st.isFile();
+                }
+                catch {
+                    continue; // dangling link
+                }
+            }
+            if (isDir) {
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                let real;
+                try {
+                    real = fs.realpathSync(full);
+                }
+                catch {
+                    real = full;
+                }
+                // Links make one real tree reachable under several names. A cycle is already bounded by the
+                // kernel's ELOOP and by MAX_DIRS; what this stops is spending the budget re-walking the same
+                // directory, which would trip the cap and report code in a project that has none.
+                if (seen.has(real))
+                    continue;
+                seen.add(real);
+                queue.push(full);
+            }
+            else if (isFile) {
+                const rel = path.relative(target, full);
+                if ((0, phase_1.classifyAction)(rel) === 'WRITE_CODE')
+                    return true; // the answer is boolean — stop here
+            }
+        }
+    }
+    return false;
+}
+/**
+ * The three lines a forced governed transition owes the user: that the precondition was skipped,
+ * what is now denied (and what still works), and the one playbook that fits this target.
+ *
+ * Naming both playbooks would hand the judgement back to the user, which is the defect itself.
+ */
+function governedWarning(target) {
+    return [
+        'Warning: --force skipped the governed precondition — this target has no approved A-SPEC.',
+        'Until one is approved, the Write/Edit gate denies EVERY code edit here (spec authoring is allowed).',
+        hasGatedCode(target)
+            ? `Existing code found — run the '${(0, playbook_skills_1.invocableSkillName)('adopt')}' skill to reverse-engineer specs from it.`
+            : `No code here yet — run the '${(0, playbook_skills_1.invocableSkillName)('author-slice')}' skill to write and approve a spec chain first.`,
+    ];
+}

package/dist/holmes/cli/index.js

@@ -0,0 +1,384 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageRoot = packageRoot;
+exports.main = main;
+// @implements A-SPEC-100.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const init_1 = require("./init");
+const doctor_1 = require("./doctor");
+/**
+ * `holmes-kit` CLI entry — argv dispatch, hand-rolled (no new dependency).
+ *
+ * Commands:
+ *   init [--mode guardrail|governed] [--target dir] [--dry-run] [--remove] [--force] ...
+ *   doctor [--target dir] [--json]
+ */
+/**
+ * The installed package root. From `dist/holmes/cli/index.js` that is three levels up. Node resolves
+ * a global bin symlink to its real path before setting __dirname, so this is correct even when the
+ * command is invoked through the PATH shim.
+ */
+function packageRoot() {
+    return path.resolve(__dirname, '..', '..', '..');
+}
+/**
+ * @implements A-SPEC-171
+ * What each command accepts. `help` is common to all.
+ *
+ * Declared because the parser used to accept ANY `--key` and drop it when nobody read it —
+ * measured 2026-08-12, `holmes-kit init --help` wired a clean directory instead of printing
+ * anything, because `--help` was stored and ignored like any other unknown key. Special-casing
+ * `--help` would only postpone the next typo, so the rule is the declaration itself: this is
+ * REQ-144's "cannot decide is not permission", applied to CLI arguments.
+ */
+const KNOWN_FLAGS = {
+    init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent'],
+    doctor: ['help', 'target', 'json'],
+    skills: ['help', 'target'],
+};
+class UnknownFlagError extends Error {
+}
+/**
+ * Flags that take NO value. Declared, because the old parser stored the NEXT token as any flag's
+ * value: `init --dry-run .` swallowed `.` into dry-run, the boolean read false, and the "show me
+ * what you'd do" spelling performed a REAL write (round-3 HIGH; same class inverted --remove and
+ * --force). A boolean flag must never consume a token.
+ */
+const BOOLEAN_FLAGS = new Set(['help', 'dry-run', 'no-mcp', 'remove', 'force', 'json']);
+function parseFlags(argv, known) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--')) {
+            positionals.push(a);
+            continue;
+        }
+        if (a === '--') {
+            // The conventional options terminator. Naming it `unknown flag: --` was fail-closed but a
+            // misdiagnosis (round-4) — this CLI takes no positionals that would need one.
+            throw new UnknownFlagError("the '--' option terminator is not supported — this CLI takes flags only");
+        }
+        // GNU `--key=value` — refusing it as `unknown flag: --target=/path` was fail-closed but
+        // misdiagnosed (round-3).
+        let key = a.slice(2);
+        let inline;
+        const eq = key.indexOf('=');
+        if (eq >= 0) {
+            inline = key.slice(eq + 1);
+            key = key.slice(0, eq);
+        }
+        if (known && !known.includes(key))
+            throw new UnknownFlagError(`unknown flag: --${key}`);
+        if (BOOLEAN_FLAGS.has(key)) {
+            if (inline !== undefined)
+                throw new UnknownFlagError(`--${key} takes no value`);
+            flags[key] = true;
+            continue;
+        }
+        // @implements A-SPEC-190 (round 7) — a repeated value flag silently took the LAST one:
+        // `--target A --target B` acted on B while the operator was looking at A. 'Cannot decide is not
+        // permission' applies to the operator's own contradiction too.
+        if (Object.prototype.hasOwnProperty.call(flags, key)) {
+            throw new UnknownFlagError(`--${key} was given more than once — say it once, or the run acts on a directory you did not read`);
+        }
+        if (inline !== undefined) {
+            flags[key] = inline;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+            flags[key] = next;
+            i++;
+        }
+        else {
+            flags[key] = true;
+        }
+    }
+    return { flags, positionals };
+}
+function readApproval() {
+    const raw = process.env.HOLMES_APPROVAL;
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+const USAGE = `holmes-kit — deterministic ASE governance for a project
+
+  holmes-kit init [flags]      wire holmes-kit into a target project
+    --mode guardrail|governed  guardrail (default): gates only dangerous shell commands; safe on a
+                               spec-less project. governed: adds the No-Spec-No-Code Write/Edit gate
+                               (refused unless the target already has an approved A-SPEC).
+    --target <dir>             target project (default: cwd)
+    --specs-dir <rel>          spec directory (default: .ax/specs)
+    --settings local|project   which settings file to merge (default: local)
+    --agent <list>             also wire these harnesses (claude|antigravity|codex|all,
+                               comma-separated). Default: claude only.
+    --no-mcp                   skip .mcp.json / MCP server registration
+    --matcher <str>            override the PreToolUse matcher (escape hatch)
+    --dry-run                  print the diff, write nothing
+    --remove                   remove holmes-kit wiring (holmes-owned entries only)
+    --force                    re-wire an already-wired target (requires HOLMES_APPROVAL)
+
+  holmes-kit doctor [flags]    diagnose the install
+    --target <dir>             also verify that target's wiring points at this install
+    --json                     machine-readable output
+
+  holmes-kit skills refresh [flags]   refresh the recovery skills holmes-kit owns
+    --target <dir>             target project (default: cwd; must exist). Touches ONLY marker-owned
+                               skill files (installs absent ones, REWRITES all marker-owned ones,
+                               skips yours); never reads or writes governance wiring, so no
+                               approval is needed.
+
+  holmes-kit --version | --help
+`;
+async function main(argv) {
+    const cmd = argv[0];
+    // @implements A-SPEC-190 (round 7) — `holmes-kit constructor` resolved through the prototype
+    // chain to a truthy non-array and crashed with an unhandled TypeError instead of saying
+    // 'unknown command' (same class the MCP boundary fixed in REQ-189).
+    const knownFlagsFor = (c) => c !== undefined && Object.prototype.hasOwnProperty.call(KNOWN_FLAGS, c) ? KNOWN_FLAGS[c] : undefined;
+    let flags;
+    let positionals;
+    try {
+        ({ flags, positionals } = parseFlags(argv.slice(1), knownFlagsFor(cmd)));
+    }
+    catch (e) {
+        if (e instanceof UnknownFlagError) {
+            // Named, because a typo is the thing the user has to fix and a nameless refusal sends them
+            // nowhere (REQ-155).
+            process.stderr.write(`${e.message}\n\n${USAGE}`);
+            return 2;
+        }
+        throw e;
+    }
+    if (knownFlagsFor(cmd) && !flags.help) {
+        // A value-taking flag with no value parses as boolean true; silently substituting a default
+        // acts where the operator did NOT point ("cannot decide is not permission", REQ-144).
+        for (const [key, v] of Object.entries(flags)) {
+            // `--target` (true) AND `--target=` ('') both point at nothing — an empty inline value
+            // resolved to CWD and wired it silently (round-5 HIGH).
+            if (!BOOLEAN_FLAGS.has(key) && (v === true || (typeof v === 'string' && v.trim() === ''))) {
+                process.stderr.write(`--${key} requires a value\n\n${USAGE}`);
+                return 2;
+            }
+        }
+        // Positionals these commands do not take are refused, not dropped: `skills refresh <dir>`
+        // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
+        const expected = cmd === 'skills' ? ['refresh'] : [];
+        const unexpected = positionals.filter((p) => !expected.includes(p));
+        if (unexpected.length > 0) {
+            const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
+            process.stderr.write(`unexpected argument: ${unexpected[0]}${hint}\n\n${USAGE}`);
+            return 2;
+        }
+    }
+    // @implements A-SPEC-171
+    // BEFORE any side effect. The measured defect was not that help was missing but that the writing
+    // happened first, so the order here is the fix.
+    if (knownFlagsFor(cmd) && flags.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (cmd === '--version' || cmd === '-v') {
+        let v = '0.0.0';
+        try {
+            v = JSON.parse(fs.readFileSync(path.join(packageRoot(), 'package.json'), 'utf8')).version;
+        }
+        catch { /* keep default */ }
+        process.stdout.write(`${v}\n`);
+        return 0;
+    }
+    if (cmd === 'doctor') {
+        // A nonexistent target read as "healthy but unwired" and both advised remedies then refused it
+        // (round-6) — the typo is the diagnosis, so say it.
+        if (typeof flags.target === 'string') {
+            const t = path.resolve(flags.target);
+            if (!fs.existsSync(t) || !fs.statSync(t).isDirectory()) {
+                process.stderr.write(`--target ${t} is not an existing directory\n\n${USAGE}`);
+                return 2;
+            }
+        }
+        const checks = await (0, doctor_1.runDoctor)(packageRoot(), typeof flags.target === 'string' ? path.resolve(flags.target) : undefined);
+        process.stdout.write(flags.json ? JSON.stringify(checks, null, 2) + '\n' : (0, doctor_1.formatChecks)(checks) + '\n');
+        return checks.some((c) => c.level === 'FAIL') ? 1 : 0;
+    }
+    if (cmd === 'skills') {
+        // @implements A-SPEC-190
+        // Doctor's drift remedy must actually WORK: `init --target` on a wired target exits 2 (the
+        // self-disarm guard) and --force demands governance approval — a refusal loop for advisory
+        // files. This surface calls the same installer and touches ONLY marker-owned skills; wiring
+        // (settings, hooks, MCP, specs) is never read or written, so the guard's territory is intact.
+        // Subcommand comes from the parser's positionals (round-2/3: hand-rolled token scans misparsed
+        // both `--target /path refresh` and `refresh /path`); the unexpected-positional guard above has
+        // already refused anything beyond `refresh`.
+        if (!positionals.includes('refresh')) {
+            process.stderr.write(`unknown skills subcommand: (none) — expected \`skills refresh\`\n\n${USAGE}`);
+            return 2;
+        }
+        const { installPlaybookSkills, invocableSkillName, skillLabel } = require('./playbook-skills');
+        const target = path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd());
+        // A nonexistent target would be FABRICATED wholesale (measured: a literal `~` directory) and
+        // reported as success — refresh repairs an install, it does not create projects.
+        if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+            process.stderr.write(`--target ${target} is not an existing directory\n\n${USAGE}`);
+            return 2;
+        }
+        const r = installPlaybookSkills(packageRoot(), target);
+        if (r.written.length)
+            process.stdout.write(`Refreshed ${r.written.length} recovery skill(s) under ${path.join(target, '.claude', 'skills')}: ${r.written.map(invocableSkillName).join(', ')}\n`);
+        if (r.written.length === 0 && r.skipped.length === 0 && r.failed.length === 0) {
+            // 이 패키지가 플레이북을 하나도 싣지 않았다 — 'Refreshed 0' 은 성공처럼 읽힌다.
+            process.stderr.write(`This holmes-kit package ships no playbooks — nothing to refresh under ${path.join(target, '.claude', 'skills')}. Reinstall or upgrade holmes-kit itself.\n`);
+            return 1;
+        }
+        // round-7: a skill DIRECTORY the user manages as a symlink has no SKILL.md inside, so naming
+        // that file sent the reader to a path that does not exist. Name what actually occupies the spot.
+        for (const s of r.skipped) {
+            const file = path.join(target, '.claude', 'skills', invocableSkillName(s), 'SKILL.md');
+            const occupied = fs.existsSync(file) ? file : path.dirname(file);
+            process.stdout.write(`Left your own ${occupied} untouched (not written by holmes-kit)\n`);
+        }
+        // Invocable name in failures too (A-SPEC-172): the bare name sends the reader to a directory
+        // that does not exist.
+        for (const b of r.backedUp)
+            process.stdout.write(`Kept the previous ${invocableSkillName(b.name)} content at ${b.path}\n`);
+        for (const f of r.failed)
+            process.stderr.write(`Could not refresh recovery skill ${skillLabel(f.name)}: ${f.reason}\n`);
+        return r.failed.length > 0 ? 1 : 0;
+    }
+    if (cmd === 'init') {
+        const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
+        // 형제 열거 오류와 같은 모양(round 7): --settings·--target 은 USAGE 와 함께 exit 2 인데
+        // --mode 만 맨몸 exit 1 이었다 — 같은 실수의 진단이 두 벌이면 스크립트가 갈린다.
+        if (mode !== 'guardrail' && mode !== 'governed') {
+            process.stderr.write(`unknown --mode ${mode} (guardrail|governed)\n\n${USAGE}`);
+            return 2;
+        }
+        // Same rule as --mode (round-6: an unknown --settings silently substituted 'local' — the very
+        // "cannot decide is not permission" this file's own comment cites).
+        if (typeof flags.settings === 'string' && flags.settings !== 'local' && flags.settings !== 'project') {
+            process.stderr.write(`unknown --settings ${flags.settings} (local|project)\n\n${USAGE}`);
+            return 2;
+        }
+        // Same guard `skills refresh` carries (round-5: a typo'd --target FABRICATED a deep bogus
+        // project tree and wired it, exit 0 — init wires an EXISTING project, it does not mint one).
+        if (typeof flags.target === 'string') {
+            const t = path.resolve(flags.target);
+            if (!fs.existsSync(t) || !fs.statSync(t).isDirectory()) {
+                process.stderr.write(`--target ${t} is not an existing directory\n\n${USAGE}`);
+                return 2;
+            }
+        }
+        // @implements A-SPEC-190 (round 7) — `--specs-dir` was the one value flag with no validation:
+        // init READ it as target-relative but WIRED it verbatim, so an absolute or escaping path left
+        // the hook and the wiring pointing at two different directories.
+        const specsDir = typeof flags['specs-dir'] === 'string' ? flags['specs-dir'] : '.ax/specs';
+        // round-9: the value is interpolated into a hook COMMAND STRING, so a quote or a shell
+        // metacharacter would break out of it. A spec directory is a plain relative path; anything that
+        // could change the meaning of the command line is refused rather than escaped.
+        if (path.isAbsolute(specsDir) || specsDir.split(/[\\/]/).includes('..') || specsDir.startsWith('~')
+            || /["'`$\\;&|<>\n\r]/.test(specsDir)) {
+            // '~' 는 셸이 확장하지 못했을 때만 남는다 — 그대로 두면 대상 안에 리터럴 '~' 디렉터리를
+            // 만들고 배선까지 그 이름으로 간다(round 8).
+            process.stderr.write(`--specs-dir ${specsDir} must be a plain relative path inside the target (no '..', no '~', no quotes or shell metacharacters)\n\n${USAGE}`);
+            return 2;
+        }
+        // @implements A-SPEC-193 — 모르는 하네스 이름은 조용히 무시하지 않는다. 배선했다는 보고와
+        // 실제가 어긋나는 것이 이 파일이 --mode·--settings 에서 이미 두 번 고친 실패 유형이다.
+        const { AGENTS } = require('./agents');
+        let agents = [];
+        if (typeof flags.agent === 'string' && flags.agent !== '') {
+            const asked = flags.agent.split(',').map((s) => s.trim()).filter((s) => s !== '');
+            const wanted = asked.includes('all') ? [...AGENTS] : asked;
+            const unknown = wanted.filter((a) => !AGENTS.includes(a));
+            if (unknown.length > 0) {
+                process.stderr.write(`unknown --agent ${unknown.join(', ')} (${AGENTS.join('|')}|all)\n\n${USAGE}`);
+                return 2;
+            }
+            agents = wanted;
+        }
+        const opts = {
+            agents,
+            target: path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd()),
+            packageRoot: packageRoot(),
+            mode,
+            specsDir,
+            settingsFile: flags.settings === 'project' ? 'project' : 'local',
+            mcp: flags['no-mcp'] !== true,
+            matcher: typeof flags.matcher === 'string' ? flags.matcher : undefined,
+            dryRun: flags['dry-run'] === true,
+            force: flags.force === true,
+            remove: flags.remove === true,
+            approval: readApproval(),
+        };
+        const res = (0, init_1.runInit)(opts);
+        for (const m of res.messages)
+            process[res.ok ? 'stdout' : 'stderr'].write(`${m}\n`);
+        if (res.ok) {
+            // round-8: a planned DELETION printed under 'would write' contradicted the line above it.
+            for (const p of res.removals ?? [])
+                process.stdout.write(`  would remove ${p}\n`);
+            for (const c of res.changes) {
+                const verb = opts.dryRun ? 'would write' : 'wrote';
+                process.stdout.write(`  ${verb} ${c.path}\n`);
+                if (opts.dryRun && c.after) {
+                    process.stdout.write(c.after.split('\n').map((l) => `    | ${l}`).join('\n') + '\n');
+                }
+            }
+        }
+        return res.exitCode;
+    }
+    // round-8: `holmes-kit --target x` 나 `holmes-kit --` 처럼 명령 자리에 플래그가 오면 exit 1,
+    // 같은 토큰이 하위 명령 뒤에 오면 exit 2 였다 — 같은 실수에 두 가지 진단.
+    process.stderr.write(cmd.startsWith('-')
+        ? `unknown flag in command position: ${cmd}\n\n${USAGE}`
+        : `unknown command: ${cmd}\n\n${USAGE}`);
+    return cmd.startsWith('-') ? 2 : 1;
+}
+if (require.main === module) {
+    main(process.argv.slice(2)).then((code) => process.exit(code));
+}