@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/cli/init.js

@@ -0,0 +1,462 @@
+"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.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
+exports.buildHookPlan = buildHookPlan;
+exports.runInit = runInit;
+// @implements A-SPEC-100.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const settings_merge_1 = require("./settings-merge");
+const gitignore_merge_1 = require("./gitignore-merge");
+const settings_merge_2 = require("./settings-merge");
+const playbook_skills_1 = require("./playbook-skills");
+const agents_1 = require("./agents");
+const roles_readme_1 = require("./roles-readme");
+const pre_tool_use_1 = require("../hooks/pre-tool-use");
+const governed_precondition_1 = require("./governed-precondition");
+const risk_gate_1 = require("../guardrail/risk-gate");
+/**
+ * `holmes-kit init` — wire holmes-kit into a TARGET project (the I/O half; all merge logic is pure
+ * and lives in settings-merge.ts / gitignore-merge.ts).
+ *
+ * The mode choice is the single most consequential decision this tool makes:
+ *   guardrail (DEFAULT) — PreToolUse matcher 'Bash' + Stop. On a spec-less project this blocks
+ *                         nothing (the shell-code-write gate checks for approved specs first, and the
+ *                         Stop gate early-returns on an empty governed set).
+ *   governed            — matcher 'Bash|Write|Edit'. phaseCheck has NO empty-spec escape, so on a
+ *                         project without an approved A-SPEC this denies EVERY code write — it would
+ *                         brick the target. Hence the precondition check below.
+ */
+exports.SERVER_NAME = 'holmes-kit';
+/**
+ * @implements A-SPEC-163
+ * Which tools the PreToolUse hook is registered for.
+ *
+ * `guardrail` used to be `Bash` alone, so an installed project's `Write` never reached the hook at
+ * all — measured 2026-08-08 against a real install. Fixing the gate's own tool predicate would have
+ * changed nothing there, which is the third time a capability existed in the repo and stopped at the
+ * installer (REQ-142, REQ-153).
+ *
+ * `.*` rather than a list: the list is what let `MultiEdit` and `NotebookEdit` through, and the next
+ * tool would repeat it. The gate itself decides what is a write (`writesFiles`); the matcher only
+ * decides what it gets to look at, and it should look at everything.
+ */
+/**
+ * @implements A-SPEC-178
+ * The matcher `init` installs. Exported so `doctor` compares against THIS value rather than a second
+ * spelling of it — a copy drifts the moment this changes, and doctor would then warn about correct
+ * wiring, which is worse than saying nothing.
+ */
+exports.MATCHERS = { guardrail: '.*', governed: '.*' };
+const SPEC_SUBDIRS = ['01_req', '02_h-spec', '03_a-spec', '04_cpg', '05_t-spec'];
+/** Absolute hook/mcp commands, quoted so a package path containing spaces still works. */
+function buildHookPlan(packageRoot, matcher, specsDir = '.ax/specs') {
+    // @implements A-SPEC-190 (round 8) — the spec directory reached the MCP server (HOLMES_SPECS in
+    // .mcp.json) and NOT the hooks, which fall back to '.ax/specs'. So `init --mode governed
+    // --specs-dir docs/specs` reported governed while the gate looked at an empty default directory
+    // and refused nothing: the wiring and the enforcement pointed at two different projects. The
+    // hooks are told on their own command line; the default stays byte-identical to previous installs.
+    const arg = specsDir === '.ax/specs' ? '' : ` --specs "${specsDir}"`;
+    const q = (p) => `node "${p}"${arg}`;
+    return {
+        preToolUseMatcher: matcher,
+        preToolUseCommand: q(path.join(packageRoot, 'dist', 'holmes', 'hooks', 'pre-tool-use.js')),
+        stopCommand: q(path.join(packageRoot, 'dist', 'holmes', 'hooks', 'stop.js')),
+    };
+}
+/**
+ * @implements A-SPEC-190 §17 (round 13) — "could not read" was folded into "is not there", so a
+ * settings file the process lacks permission to read (EACCES, EISDIR, a dangling link) was treated
+ * as absent and REPLACED by a fresh holmes-only file — and the backup beside it was empty, because
+ * the previous content could not be read either. Absence is a fact about the filesystem; an
+ * unreadable file is a fact about this process, and only one of them licenses an overwrite.
+ */
+function readJson(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        const missing = e.code === 'ENOENT';
+        return { value: undefined, raw: null, parseError: false, unreadable: !missing };
+    }
+    try {
+        return { value: JSON.parse(raw), raw, parseError: false, unreadable: false };
+    }
+    catch {
+        return { value: undefined, raw, parseError: true, unreadable: false };
+    }
+}
+/** Backup + atomic write (temp in the same dir, then rename) so a crash can't leave a half file. */
+function writeFileSafe(file, content) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // Write through a user's symlink, not over it (round-5: a dotfiles-style symlinked
+    // settings.local.json was replaced by a plain file, orphaning the central copy).
+    const real = (() => { try {
+        return fs.realpathSync(file);
+    }
+    catch {
+        return file;
+    } })();
+    // @implements A-SPEC-190 §15 (round 12) — the backup followed the symlink's FAR end. For the
+    // dotfiles pattern (`.claude/settings.local.json -> ~/dotfiles/…`) every run dropped a new file
+    // into the user's OTHER repository while the CLI reported an in-target path, and it copied
+    // unconditionally, so byte-identical re-runs accumulated forever. A backup belongs beside the name
+    // we were given, is only made when the content actually changes, and is created exclusively.
+    let madeBackup;
+    if (fs.existsSync(real)) {
+        let prev;
+        try {
+            prev = fs.readFileSync(real, 'utf8');
+        }
+        catch (e) {
+            // §17: 읽지 못한 파일을 덮어쓰지 않는다 — 백업이 0바이트가 되고 사용자 설정이 사라진다.
+            throw new Error(`${file} 를 읽을 수 없어 덮어쓰지 않았습니다: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (prev !== content) {
+            const stamp = `${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+            const bak = `${file}.holmes-bak-${stamp}`;
+            try {
+                fs.writeFileSync(bak, prev, { flag: 'wx' });
+                madeBackup = bak;
+            }
+            catch { /* 백업을 못 만들면 그대로 둔다 — 아래 쓰기는 원자적이다 */ }
+        }
+    }
+    // Same discipline the playbook writer earned in round-5/6: unique suffix + 'wx' (a predictable
+    // pid-only path followed a planted symlink), and mode preservation — this file HOLDS the
+    // out-of-band approval env, and a rewrite silently widened 0600 → 0644.
+    const prevMode = (() => { try {
+        return fs.statSync(real).mode & 0o777;
+    }
+    catch {
+        return undefined;
+    } })();
+    const tmp = `${real}.holmes-tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+    // @implements A-SPEC-190 §18 (round 13) — the playbook writer earned this cleanup in round 9 and
+    // it never crossed here: a failed rename left BOTH the temp file (holding the whole settings
+    // payload) and the backup behind, one pair per attempt, and died on a raw Node stack. Nothing we
+    // could not finish is left on disk, and the failure is reported as a refusal.
+    let renamed = false;
+    try {
+        fs.writeFileSync(tmp, content, { encoding: 'utf8', flag: 'wx' });
+        if (prevMode !== undefined)
+            fs.chmodSync(tmp, prevMode);
+        fs.renameSync(tmp, real);
+        renamed = true;
+    }
+    catch (e) {
+        throw new Error(`${file} 를 쓰지 못했습니다: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        if (!renamed) {
+            try {
+                fs.rmSync(tmp, { force: true });
+            }
+            catch { /* already gone */ }
+            if (madeBackup !== undefined) {
+                try {
+                    fs.rmSync(madeBackup, { force: true });
+                }
+                catch { /* already gone */ }
+            }
+        }
+    }
+}
+const settingsPathOf = (target, which) => path.join(target, '.claude', which === 'local' ? 'settings.local.json' : 'settings.json');
+exports.settingsPathOf = settingsPathOf;
+/** Does the target already carry holmes wiring? (idempotency + self-disarm guard) */
+function alreadyWired(settings) {
+    return Object.values(settings?.hooks ?? {}).some((groups) => (groups ?? []).some((g) => (g.hooks ?? []).some((h) => (0, settings_merge_1.isHolmesCommand)(h.command))));
+}
+function runInit(opts) {
+    const messages = [];
+    const changes = [];
+    const removals = [];
+    const settingsPath = (0, exports.settingsPathOf)(opts.target, opts.settingsFile);
+    const mcpPath = path.join(opts.target, '.mcp.json');
+    const gitignorePath = path.join(opts.target, '.gitignore');
+    // The installed package must actually be built — this doubles as the "prepare didn't run" detector.
+    const hookJs = path.join(opts.packageRoot, 'dist', 'holmes', 'hooks', 'pre-tool-use.js');
+    if (!fs.existsSync(hookJs)) {
+        return { ok: false, exitCode: 1, changes, messages: [
+                `holmes-kit is not built: ${hookJs} is missing.`,
+                // @implements A-SPEC-190 §16 (round 12) — this named a `prepare` script package.json does not
+                // declare (only build/mcp/release/test/typecheck exist), so the remedy sent readers to inspect
+                // npm settings for a hook that was never there. dist/ ships because `files` lists it.
+                '이 패키지는 컴파일된 dist/ 를 함께 배포합니다 — 저장소에서 쓰는 중이라면 `npm run build`, 설치본이라면 재설치하십시오.',
+            ] };
+    }
+    const s = readJson(settingsPath);
+    if (s.parseError) {
+        return { ok: false, exitCode: 2, changes, messages: [
+                `${settingsPath} is not valid JSON (comments/JSONC are not supported here).`,
+                'Refusing to touch it — merge the holmes-kit hooks by hand, or fix the file and re-run.',
+            ] };
+    }
+    // Self-disarm guard: an agent inside a governed session could otherwise call `init --matcher Nothing`
+    // to weaken its own governance. Re-wiring an already-wired target needs --force AND a valid
+    // out-of-band approval.
+    // @implements A-SPEC-190 §19 (round 13) — the self-disarm guard had two doors out. It asked
+    // `alreadyWired` about the file THIS invocation happens to name, so a target wired through
+    // `.claude/settings.json` was silently re-wired by `--settings local` with no approval at all;
+    // and both the guard and the approval requirement excluded `--remove`, which is the most complete
+    // way to take governance off. A session must not be able to unwire the gate that governs it,
+    // whichever flag it reaches for. Wiring is asked of BOTH settings files.
+    const wiredAnywhere = ['local', 'project'].some((which) => alreadyWired(readJson((0, exports.settingsPathOf)(opts.target, which)).value));
+    if (!opts.remove && wiredAnywhere && !opts.force) {
+        return { ok: false, exitCode: 2, changes, messages: [
+                'This target already has holmes-kit wiring. Re-run with --force to change it.',
+            ] };
+    }
+    if ((opts.force || (opts.remove && wiredAnywhere))
+        && !(0, risk_gate_1.approvalCovers)(opts.approval, { kind: 'governance-wiring', target: opts.target }, new Date().toISOString())) {
+        // covers, not merely well-formed (round-3): an expired or elsewhere-scoped token re-wired
+        // governance — the exact master-key behaviour A-SPEC-133's narrowing exists to end.
+        return { ok: false, exitCode: 2, changes, messages: [
+                opts.remove
+                    ? '거버넌스 배선을 벗기는 것도 배선을 바꾸는 것입니다 — 대역외 승인이 필요합니다 (자기무장해제 방지).'
+                    : '--force changes existing governance wiring and requires an out-of-band approval that covers it.',
+                `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "governance-wiring") and re-run.`,
+            ] };
+    }
+    const m = readJson(mcpPath);
+    if (m.parseError) {
+        return { ok: false, exitCode: 2, changes, messages: [`${mcpPath} is not valid JSON — refusing to touch it.`] };
+    }
+    const gitignoreBefore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    if (opts.remove) {
+        let settings = (0, settings_merge_1.removeHooks)(s.value);
+        settings = (0, settings_merge_1.disableMcpServer)(settings, exports.SERVER_NAME);
+        changes.push({ path: settingsPath, before: s.raw, after: s.raw === null ? null : JSON.stringify(settings, null, 2) + '\n' });
+        if (m.raw !== null) {
+            changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.removeMcpServer)(m.value, exports.SERVER_NAME), null, 2) + '\n' });
+        }
+        if ((0, gitignore_merge_1.hasGitignoreBlock)(gitignoreBefore)) {
+            changes.push({ path: gitignorePath, before: gitignoreBefore, after: (0, gitignore_merge_1.removeGitignoreBlock)(gitignoreBefore) });
+        }
+        // round-7: the past tense fired under --dry-run too, so 'Removed' announced a removal that
+        // had not happened — the one spelling whose entire purpose is to write nothing.
+        messages.push(opts.dryRun
+            ? 'Would remove holmes-kit wiring (holmes-owned entries only; your other settings would be untouched).'
+            : 'Removed holmes-kit wiring (holmes-owned entries only; your other settings are untouched).');
+    }
+    else {
+        // @implements A-SPEC-172
+        // GOVERNED PRECONDITION: without an approved A-SPEC the phase gate denies every code write.
+        // The check runs on BOTH paths. It used to sit behind `!opts.force`, so a forced transition never
+        // computed it and said nothing — the same situation the refusal below explains in three lines.
+        // `--force` changes what happens with the answer, never whether the answer is known.
+        if (opts.mode === 'governed') {
+            const specs = (0, pre_tool_use_1.readSpecsSync)(path.join(opts.target, opts.specsDir));
+            const approvedAspec = specs.some((sp) => sp.type === 'A-SPEC' && sp.status === 'approved');
+            if (!approvedAspec) {
+                if (!opts.force) {
+                    return { ok: false, exitCode: 2, changes, messages: [
+                            'Refusing --mode governed: this target has no approved A-SPEC.',
+                            'The Write/Edit gate has no empty-spec escape, so it would deny EVERY code edit here.',
+                            'Start with --mode guardrail, author a spec chain, approve it out-of-band, then re-run with --mode governed.',
+                        ] };
+                }
+                // Passing is the design — greenfield governed is a supported path — but not silently.
+                messages.push(...(0, governed_precondition_1.governedWarning)(opts.target));
+            }
+        }
+        const matcher = opts.matcher ?? exports.MATCHERS[opts.mode];
+        const plan = buildHookPlan(opts.packageRoot, matcher, opts.specsDir);
+        let settings = (0, settings_merge_1.mergeHooks)(s.value, plan);
+        if (opts.mcp) {
+            settings = (0, settings_merge_1.enableMcpServer)(settings, exports.SERVER_NAME);
+            const mcpBin = path.join(opts.packageRoot, 'bin', 'holmes-mcp.js');
+            // @implements A-SPEC-179
+            // Say what survived. A quiet keep is as unverifiable as the quiet delete this replaced — the
+            // operator has no other way to confirm the thing they switched on is still on.
+            const prevEnv = m.value
+                ?.mcpServers?.[exports.SERVER_NAME]?.env ?? {};
+            const kept = Object.keys(prevEnv).filter((k) => !settings_merge_2.HOLMES_OWNED_MCP_ENV.includes(k));
+            if (kept.length > 0)
+                messages.push(`Preserved your MCP server env: ${kept.join(', ')}`);
+            changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.mergeMcpServers)(m.value, exports.SERVER_NAME, mcpBin, opts.specsDir), null, 2) + '\n' });
+        }
+        changes.push({ path: settingsPath, before: s.raw, after: JSON.stringify(settings, null, 2) + '\n' });
+        const gitignoreAfter = (0, gitignore_merge_1.mergeGitignore)(gitignoreBefore);
+        if (gitignoreAfter !== gitignoreBefore)
+            changes.push({ path: gitignorePath, before: gitignoreBefore || null, after: gitignoreAfter });
+        messages.push(`mode=${opts.mode} matcher=${matcher} specs=${opts.specsDir}`);
+        if (opts.mode === 'guardrail') {
+            messages.push('Guardrail mode: nothing is blocked on a spec-less project; only genuinely dangerous shell commands are gated.');
+        }
+        else {
+            messages.push('Governed mode: No-Spec-No-Code is live. Approving a spec needs out-of-band approval:');
+            messages.push(`  HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' claude`);
+        }
+        messages.push('Restart Claude Code — hooks and MCP servers are read at session start.');
+    }
+    if (opts.dryRun) {
+        // @implements A-SPEC-190 (round 8) — dry-run must plan the SAME set the real run touches, and
+        // must not print a deletion under the verb 'would write'. Round-7 planned installs only from
+        // shipped states, so `--remove` under-reported (orphaned marker-owned skills are deleted by the
+        // real run and were absent from the plan: 3 announced, 4 deleted), and every planned path was
+        // rendered by the caller's write-verb.
+        const { playbookSkillStates } = require('./playbook-skills');
+        const states = playbookSkillStates(opts.packageRoot, opts.target);
+        if (opts.remove) {
+            // removePlaybookSkills deletes every marker-owned `holmes-*` SKILL.md — shipped or orphaned.
+            const planned = states.filter((x) => x.state === 'current' || x.state === 'drifted' || x.state === 'orphaned' || x.state === 'aliased');
+            for (const p of planned) {
+                removals.push(p.state === 'orphaned'
+                    ? path.join(opts.target, '.claude', 'skills', p.name, 'SKILL.md')
+                    : (0, playbook_skills_1.skillPathFor)(opts.target, p.name));
+            }
+            if (planned.length)
+                messages.push(`Would remove ${planned.length} recovery skill(s): ${planned.map((p) => p.state === 'orphaned' ? p.name : (0, playbook_skills_1.invocableSkillName)(p.name)).join(', ')}`);
+        }
+        else {
+            // aliased 도 설치되지 않는다(쓰기 전에 거부된다) — 계획이 실행보다 많으면 그것도 거짓말이다.
+            const planned = states.filter((x) => x.state !== 'foreign' && x.state !== 'orphaned' && x.state !== 'source-unreadable' && x.state !== 'aliased');
+            for (const p of planned)
+                changes.push({ path: (0, playbook_skills_1.skillPathFor)(opts.target, p.name), before: null, after: null });
+            if (planned.length)
+                messages.push(`Would install/refresh ${planned.length} recovery skill(s): ${planned.map((p) => (0, playbook_skills_1.invocableSkillName)(p.name)).join(', ')}`);
+        }
+    }
+    // @implements A-SPEC-193 — 하네스별 배선물. 계산과 쓰기를 나누므로 dry-run 이 실제 실행과
+    // 같은 집합을 예고한다(A-SPEC-190 §9 의 규율). Claude 는 위에서 이미 배선했으므로 빈 목록이다.
+    if (!opts.remove) {
+        for (const agent of opts.agents ?? []) {
+            for (const f of (0, agents_1.agentFiles)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir })) {
+                const before = fs.existsSync(f.path) ? fs.readFileSync(f.path, 'utf8') : null;
+                changes.push({ path: f.path, before, after: f.content });
+            }
+            messages.push(agents_1.HARNESS_ENFORCES[agent]
+                ? `${agent}: 게이트가 집행됩니다 (훅 배선됨).`
+                : `${agent}: 도구와 지침만 배선했습니다 — 이 하네스에서는 게이트를 집행하지 않습니다.`);
+            // 링크는 내용이 아니라 배치다 — dry-run 에서는 말만 하고, 실제 실행에서만 만든다.
+            for (const link of (0, agents_1.agentLinks)(agent, { target: opts.target, packageRoot: opts.packageRoot, specsDir: opts.specsDir })) {
+                if (opts.dryRun) {
+                    messages.push(`Would link ${link.path} -> ${link.target} (${link.why})`);
+                    continue;
+                }
+                try {
+                    if (!fs.existsSync(link.path)) {
+                        fs.mkdirSync(path.dirname(link.path), { recursive: true });
+                        fs.symlinkSync(link.target, link.path, 'dir');
+                        messages.push(`linked ${link.path} -> ${link.target}`);
+                    }
+                }
+                catch (e) {
+                    // 심링크를 만들 수 없는 파일시스템(일부 Windows 배치)에서는 사실을 말하고 넘어간다 —
+                    // 조용히 복사본을 만들면 그것이 곧 드리프트의 출발점이다.
+                    messages.push(`${link.path} 를 링크하지 못했습니다(${e instanceof Error ? e.message : String(e)}) —`
+                        + ` 이 하네스가 스킬을 보려면 ${link.target} 를 직접 링크하거나 복사하십시오.`);
+                }
+            }
+        }
+    }
+    if (!opts.dryRun) {
+        // @implements A-SPEC-190 §17/§18 (round 13) — a write we refuse to make (unreadable original)
+        // or cannot finish (rename failure) is a REFUSAL with a next action, not a raw Node stack. The
+        // files already written stay written and are reported; nothing half-written is left behind.
+        for (const c of changes) {
+            if (c.after === null)
+                continue;
+            try {
+                writeFileSafe(c.path, c.after);
+            }
+            catch (e) {
+                return { ok: false, exitCode: 2, changes, messages: [
+                        ...messages,
+                        e instanceof Error ? e.message : String(e),
+                        '권한과 소유자를 확인한 뒤 다시 실행하십시오 — 읽지 못한 파일은 덮어쓰지 않았습니다.',
+                    ] };
+            }
+        }
+        if (!opts.remove && opts.mode === 'governed') {
+            for (const d of SPEC_SUBDIRS)
+                fs.mkdirSync(path.join(opts.target, opts.specsDir, d), { recursive: true });
+        }
+        // @implements A-SPEC-142
+        // The recovery layer. Measured before this existed: `npm pack` carried zero playbooks and init
+        // wrote none, so an installed user got every deny string and none of the guidance written to
+        // answer them. Advisory by design — no gate decision reads these, so a failure here reports and
+        // never fails the init that has already done real work.
+        if (opts.remove) {
+            const r = (0, playbook_skills_1.removePlaybookSkills)(opts.target);
+            // round-9: the failures were dropped on the floor — a refusal ('this is a symlink; I did not
+            // delete through it') became silence, so the report said 3 and the disk said 2 with no word
+            // about the third.
+            for (const f of r.failed)
+                messages.push(`Could not remove ${f.name}: ${f.reason}`);
+            // round-7: the names are RAW directory names already — re-prefixing them produced the
+            // canonical skill's name for a case variant, i.e. a delete report about a different directory.
+            if (r.removed.length)
+                messages.push(`Removed ${r.removed.length} recovery skill(s) under ${path.join(opts.target, '.claude', 'skills')}: ${r.removed.join(', ')}`);
+        }
+        else {
+            const r = (0, playbook_skills_1.installPlaybookSkills)(opts.packageRoot, opts.target);
+            if (r.written.length)
+                messages.push(`Installed ${r.written.length} recovery skill(s) under ${path.join(opts.target, '.claude', 'skills')}: ${r.written.map(playbook_skills_1.invocableSkillName).join(', ')}`);
+            for (const n of r.skipped) {
+                const file = (0, playbook_skills_1.skillPathFor)(opts.target, n);
+                messages.push(`Left your own ${fs.existsSync(file) ? file : path.dirname(file)} untouched (not written by holmes-kit).`);
+            }
+            for (const b of r.backedUp)
+                messages.push(`Kept the previous ${(0, playbook_skills_1.invocableSkillName)(b.name)} content at ${b.path}`);
+            for (const f of r.failed)
+                messages.push(`Could not install recovery skill ${(0, playbook_skills_1.skillLabel)(f.name)}: ${f.reason}`);
+        }
+    }
+    // @implements A-SPEC-153
+    // Role guidance, deliberately INERT. `loadRolePolicy` reads only .yaml/.yml, so this markdown
+    // leaves the gate's decision unchanged — a project turns roles on by adding its own policy file.
+    // Shipping an active policy here would put every newly initialised project behind a fail-closed
+    // gate on first run.
+    if (opts.remove) {
+        if (!opts.dryRun && (0, roles_readme_1.removeRolesReadme)(opts.target))
+            messages.push('Removed .ax/roles/README.md (role guidance).');
+    }
+    else {
+        // @implements A-SPEC-171
+        // `--dry-run` says "write nothing", and this call did not honour it — measured 2026-08-12, a
+        // dry run left .ax/roles/README.md behind. Introduced by REQ-153, which added the guidance
+        // without threading the flag through. The message still prints, because describing what WOULD
+        // happen is exactly what a dry run is for.
+        if (!opts.dryRun)
+            (0, roles_readme_1.installRolesReadme)(opts.target);
+        messages.push('Role policy is OPTIONAL and currently off — see .ax/roles/README.md to enable it.');
+    }
+    return { ok: true, exitCode: 0, messages, changes, removals };
+}