@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/cli/playbook-skills.js

@@ -0,0 +1,711 @@
+"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.PLAYBOOK_SKILL_MARKER = void 0;
+exports.installedSkillBytes = installedSkillBytes;
+exports.carriesMarker = carriesMarker;
+exports.frontmatterEnd = frontmatterEnd;
+exports.invocableSkillName = invocableSkillName;
+exports.skillPathFor = skillPathFor;
+exports.installPlaybookSkills = installPlaybookSkills;
+exports.removePlaybookSkills = removePlaybookSkills;
+exports.skillLabel = skillLabel;
+exports.playbookSkillStates = playbookSkillStates;
+exports.classifyExtraEntries = classifyExtraEntries;
+exports.installedPlaybookCount = installedPlaybookCount;
+// @implements A-SPEC-142
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Install the recovery playbooks into a project as agent skills.
+ *
+ * WHY this exists, measured: the gate denies with five deliberately specific strings, and each
+ * playbook is a skill whose `description` quotes the exact deny text that should summon it — the
+ * layer that turns a refusal into a next step. It did not ship. `npm pack --dry-run` carried ZERO
+ * playbook files, because `files: ["bin/","dist/"]` covered neither `playbooks/` nor anything like
+ * it, and `init` never wrote one either. Every installed user got the enforcement and none of the
+ * recovery, while all 47 conformance assertions passed in this repository and protected nobody.
+ *
+ * Playbooks are ADVISORY. No gate decision reads them, and a user who deletes every one of them
+ * still gets identical enforcement — which is why a missing playbook is a doctor WARN, never a FAIL.
+ */
+/**
+ * Marks a file as OURS. Ownership is decided by this marker and never by the path, because the path
+ * is exactly what a user's own skill of the same name would occupy, and overwriting that would be
+ * the same class of error as clobbering their settings.
+ */
+exports.PLAYBOOK_SKILL_MARKER = '<!-- installed by holmes-kit; edits will be replaced on upgrade -->';
+/**
+ * @implements A-SPEC-190 (round 7)
+ * The bytes an install writes. The marker used to go FIRST, which put it ahead of the playbook's
+ * YAML frontmatter — and frontmatter is only frontmatter when it starts at byte 0. Measured on this
+ * repository's own installed skills: the agent's skill list rendered
+ * `holmes-adopt: <!-- installed by holmes-kit; edits will be replaced on upgrade -->` for all three,
+ * i.e. the `description` that quotes the deny text — the entire reason this layer exists, since a
+ * refusal is supposed to summon the playbook by that sentence — was destroyed at install time,
+ * while doctor certified the layout as `current`. The marker now follows the frontmatter block.
+ */
+function installedSkillBytes(body) {
+    const end = frontmatterEnd(body);
+    if (end === null)
+        return `${exports.PLAYBOOK_SKILL_MARKER}\n${body}`;
+    // The offset is computed on normalised text; a body with CRLF or a BOM is rewritten normalised so
+    // the marker cannot land inside the frontmatter it must follow.
+    const text = body.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const head = text.slice(0, end);
+    return `${head}${head.endsWith('\n') ? '' : '\n'}${exports.PLAYBOOK_SKILL_MARKER}\n${text.slice(end)}`;
+}
+/**
+ * @implements A-SPEC-190 (round 7)
+ * Ownership is the marker AT ITS PLACE, not the string anywhere in the file. `includes` made any
+ * document that merely QUOTES the marker — documentation about holmes-kit, a review note — read as
+ * ours: doctor called it `drifted` and the refresh it advised overwrote the user's file with no
+ * backup. A quotation is not a claim of ownership.
+ */
+function carriesMarker(content) {
+    // Round-8: judging on raw bytes made ownership brittle in the direction that cannot be repaired.
+    // A CRLF normalisation (a Windows editor, `core.autocrlf`, `.gitattributes eol=crlf`), a BOM, or a
+    // trailing space on the marker line each turned a file the kit itself wrote into `foreign` —
+    // permanently, since install then skips it forever and doctor advises deleting it as "yours".
+    // Whitespace and line endings are not ownership; the marker is.
+    const text = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const markerAt = (s) => {
+        const line = s.split('\n', 1)[0];
+        return line.trimEnd() === exports.PLAYBOOK_SKILL_MARKER;
+    };
+    if (markerAt(text))
+        return true; // 옛 배치(마커 먼저) — 우리 것이므로 고칠 수 있다
+    const fm = frontmatterEnd(text);
+    // 빈 줄 하나가 소유를 지우지 않는다(round-9: frontmatter 뒤 개행 하나로 영구 foreign 이 됐다).
+    return fm !== null && markerAt(text.slice(fm).replace(/^\s*\n/, ''));
+}
+/**
+ * @implements A-SPEC-190 (round 8)
+ * Where a leading YAML frontmatter block ends, or null. Round-8 measured the shapes the first
+ * regex missed — a BOM, an EMPTY block (`---\n---\n`), and a closing fence at end-of-file with no
+ * trailing newline — each of which sent the marker back to byte 0, recreating the CRITICAL the
+ * round-7 fix existed to remove while doctor certified the result as `current`.
+ */
+function frontmatterEnd(content) {
+    const text = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    if (!/^---[ \t]*(\n|$)/.test(text))
+        return null;
+    const m = /\n---[ \t]*(\n|$)/.exec(text.slice(3));
+    if (!m)
+        return null;
+    return 3 + m.index + m[0].length;
+}
+/**
+ * @implements A-SPEC-172
+ * What the user types to reach a playbook.
+ *
+ * The install directory is namespaced (`holmes-adopt`), but the internal playbook name is bare
+ * (`adopt`), and every message echoed the bare one. Measured 2026-08-12 on an installed tarball: init
+ * printed `Installed 3 recovery skill(s): adopt, author-slice, promote-slice` while nothing by those
+ * names existed. Anything shown to a user goes through here.
+ */
+function invocableSkillName(playbookName) {
+    return `holmes-${playbookName}`;
+}
+/** `<target>/.claude/skills/holmes-<name>/SKILL.md` */
+function skillPathFor(target, playbookName) {
+    return path.join(target, '.claude', 'skills', invocableSkillName(playbookName), 'SKILL.md');
+}
+function playbookNames(packageRoot) {
+    const dir = path.join(packageRoot, 'playbooks');
+    try {
+        return fs.readdirSync(dir)
+            // Presence by lstat, not existsSync (round-8): existsSync follows links and needs read
+            // permission, so a DANGLING PLAYBOOK.md link or an unreadable playbook directory dropped the
+            // name from the shipped list — and a currently-installed skill of that name then read as
+            // `orphaned`, i.e. doctor told the operator to DELETE a skill the package still ships.
+            // A damaged source is reported as damage (`source-unreadable`), never as an orphan.
+            .filter((n) => { try {
+            fs.lstatSync(path.join(dir, n, 'PLAYBOOK.md'));
+            return true;
+        }
+        catch {
+            return false;
+        } })
+            .sort();
+    }
+    catch {
+        return []; // no playbooks directory: nothing to install, not an error
+    }
+}
+const isOurs = (file) => {
+    try {
+        return carriesMarker(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * @implements A-SPEC-190 (round 8)
+ * Which shipped names resolve to the SAME file as another (a link between skill directories, at file
+ * or directory level). Shared by install and by the state report so both say the same thing.
+ */
+function aliasGroupsOf(packageRoot, target) {
+    const names = playbookNames(packageRoot);
+    const realOf = (name) => {
+        const dest = skillPathFor(target, name);
+        try {
+            return fs.realpathSync(dest);
+        }
+        catch { /* not yet materialised */ }
+        try {
+            return path.join(fs.realpathSync(path.dirname(dest)), path.basename(dest));
+        }
+        catch {
+            return dest;
+        }
+    };
+    // @implements A-SPEC-190 §10 (round 9) — identity is (dev, ino), not a path STRING. On a
+    // case-insensitive filesystem (macOS default) `…/holmes-Adopt/SKILL.md` and `…/holmes-adopt/SKILL.md`
+    // are one file with two spellings, so the string-keyed grouping saw two destinations and let one
+    // playbook's body overwrite the other's — the exact harm the round-8 pre-scan was added to stop.
+    const identity = (name) => {
+        const real = realOf(name);
+        try {
+            const st = fs.statSync(real);
+            return `${st.dev}:${st.ino}`;
+        }
+        catch { /* not yet there */ }
+        try {
+            const st = fs.statSync(path.dirname(real));
+            return `${st.dev}:${st.ino}:${path.basename(real).toLowerCase()}`;
+        }
+        catch { /* dangling */ }
+        // round-9: a DANGLING directory link resolves to nothing, so the old fallback compared path
+        // STRINGS — two skills whose links point at one missing directory read as two destinations and
+        // one playbook's body overwrote the other's, exit 0. Follow the link TEXTUALLY: where it points
+        // is identity enough, even when nothing is there yet.
+        const dest = skillPathFor(target, name);
+        let dir = path.dirname(dest);
+        for (let hop = 0; hop < 10; hop++) {
+            try {
+                if (!fs.lstatSync(dir).isSymbolicLink())
+                    break;
+                dir = path.resolve(path.dirname(dir), fs.readlinkSync(dir));
+            }
+            catch {
+                break;
+            }
+        }
+        return path.join(dir, path.basename(dest)).toLowerCase();
+    };
+    const groups = new Map();
+    for (const name of names) {
+        const key = identity(name);
+        const g = groups.get(key);
+        if (g)
+            g.push(name);
+        else
+            groups.set(key, [name]);
+    }
+    const out = new Map();
+    for (const [, group] of groups) {
+        if (group.length < 2)
+            continue;
+        for (const n of group)
+            out.set(n, group.filter((o) => o !== n));
+    }
+    return out;
+}
+function aliasedNames(packageRoot, target) {
+    return new Set(aliasGroupsOf(packageRoot, target).keys());
+}
+/**
+ * The skills root, but only if it is genuinely INSIDE the target.
+ *
+ * @implements A-SPEC-190 §12 (round 11) — the link was refused at `.claude/skills` and at each skill
+ * directory, and traversed one level ABOVE both: with `<target>/.claude` itself a link to a central
+ * store, install wrote five shipped skills into someone else's tree and reported success, and
+ * `--remove` then deleted marker-owned files there with `failed` empty. One containment question,
+ * asked once, cannot be walked around by moving the link up a level. It also names the component
+ * that is actually a link — the old wording blamed `.claude/skills` for `.claude`.
+ */
+function skillsRootInside(target) {
+    const dir = path.join(target, '.claude', 'skills');
+    let base;
+    try {
+        base = fs.realpathSync(target);
+    }
+    catch {
+        return { dir };
+    } // 타깃이 없으면 상류가 답한다
+    // @implements A-SPEC-193 §7 — 묻는 것은 "링크인가"가 아니라 "**타깃 밖으로 나가는가**"다.
+    // 첫 판(§12)은 해소된 경로가 제자리와 다르기만 하면 거부했는데, 그것은 다중 에이전트의 표준
+    // 배치를 통째로 막는다: 원본을 `.agents/skills` 에 두고 `.claude/skills` 를 그리로 링크하는
+    // SSOT 는 타깃 **안**에 머문다(실측: 그 배치에서 written 0, 전 스킬 unresolvable). §12 가
+    // 막으려던 해악은 타깃 밖 중앙 저장소의 파괴였고, 그 해악은 아래 검사로 그대로 막힌다.
+    for (const rel of [path.join('.claude'), path.join('.claude', 'skills')]) {
+        const at = path.join(target, rel);
+        let real;
+        try {
+            real = fs.realpathSync(at);
+        }
+        catch {
+            continue;
+        } // 아직 없는 것은 여기서 만든다
+        if (real !== base && !real.startsWith(base + path.sep)) {
+            return { refusal: `${at} 가 타깃(${target}) 밖(${real})을 가리킵니다 — 링크 너머의 파일을 쓰거나 지우지 않았습니다. 링크를 풀거나 그 저장소에서 직접 다루십시오` };
+        }
+    }
+    return { dir };
+}
+function installPlaybookSkills(packageRoot, target) {
+    const out = { written: [], backedUp: [], skipped: [], failed: [] };
+    const rootCheck = skillsRootInside(target);
+    if ('refusal' in rootCheck) {
+        out.failed.push({ name: path.join('.claude', 'skills'), reason: rootCheck.refusal });
+        return out;
+    }
+    // @implements A-SPEC-190 (round 8) — two destinations can resolve to ONE file (a link between
+    // skill directories, at file OR directory level). The round-7 guard noticed the collision only
+    // when the SECOND write arrived, by which time the first had already destroyed the other skill's
+    // body — success reported, never converging. The aliases are computed BEFORE anything is written,
+    // and every member of a colliding set is refused with the alias named.
+    const names = playbookNames(packageRoot);
+    const collidingWith0 = aliasGroupsOf(packageRoot, target);
+    const realOf = (name) => {
+        const dest = skillPathFor(target, name);
+        try {
+            return fs.realpathSync(dest);
+        }
+        catch { /* not yet materialised */ }
+        // The file may not exist while its DIRECTORY is a link into another skill — resolve the parent.
+        try {
+            return path.join(fs.realpathSync(path.dirname(dest)), path.basename(dest));
+        }
+        catch {
+            return dest;
+        }
+    };
+    const collidingWith = collidingWith0;
+    for (const name of names) {
+        const others = collidingWith.get(name);
+        if (others) {
+            out.failed.push({ name, reason: `${skillPathFor(target, name)} 와 ${others.map((o) => skillPathFor(target, o)).join(', ')} 가 같은 파일(${realOf(name)})로 해석됩니다 — 한쪽 본문이 다른 쪽을 덮어쓰지 않도록 아무것도 쓰지 않았습니다. 링크를 풀고 다시 실행하십시오` });
+        }
+    }
+    for (const name of names) {
+        if (collidingWith.has(name))
+            continue;
+        const dest = skillPathFor(target, name);
+        try {
+            // Presence by lstat, not existsSync: existsSync FOLLOWS symlinks, so a user's broken or
+            // self-referential symlink read as "absent" and the shipped file was written over it —
+            // while doctor, classifying the same entry foreign, promised "leaves it untouched"
+            // (round-2 ELOOP finding). An entry we cannot prove ours is never overwritten.
+            const present = (() => {
+                try {
+                    fs.lstatSync(dest);
+                    return true;
+                }
+                catch { /* fall through */ }
+                try {
+                    return fs.lstatSync(path.dirname(dest)).isSymbolicLink();
+                }
+                catch {
+                    return false;
+                }
+            })();
+            if (present && !isOurs(dest)) {
+                out.skipped.push(name);
+                continue;
+            }
+            const body = fs.readFileSync(path.join(packageRoot, 'playbooks', name, 'PLAYBOOK.md'), 'utf8');
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            // Write via a temp file in the same directory, then rename: a half-written skill is worse than
+            // an absent one, and rename within a directory is atomic. Same discipline as the settings merge.
+            // Rename onto the REAL file: a user's file-level symlink to a marker-owned SKILL.md (dotfiles
+            // pattern) was replaced by a plain file, leaving the linked central copy stale under a marker
+            // that promises replacement on upgrade (round-3). Resolving first refreshes THROUGH the link
+            // and preserves it; for a plain file realpath is the path itself.
+            const real = (() => { try {
+                return fs.realpathSync(dest);
+            }
+            catch {
+                return dest;
+            } })();
+            // Unique name + 'wx' (round-5): a FIXED tmp name silently consumed a user's file planted
+            // there, followed a planted symlink, and raced concurrent runs. 'wx' refuses to open any
+            // existing path (including a symlink) and the suffix defuses collisions.
+            const tmp = `${real}.holmes-tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+            // Preserve the destination's mode (round-5: refreshing through a link rewrote a 0600
+            // central copy as 0644).
+            const prevMode = (() => { try {
+                return fs.statSync(real).mode & 0o777;
+            }
+            catch {
+                return undefined;
+            } })();
+            // @implements A-SPEC-190 (round 8) — a marker-owned file whose bytes differ is REWRITTEN, and
+            // that is the point of refresh. But 'ours' is judged by a marker anyone can paste at the top
+            // of their own notes, so the rewrite keeps a recoverable copy the way init's settings merge
+            // does. Nothing is destroyed without a `.holmes-bak` beside it, and the caller is told.
+            // @implements A-SPEC-190 §10 (round 9) — the round-8 backup was itself a hazard: a FIXED name
+            // written with the default flag followed a planted `SKILL.md.holmes-bak` symlink and destroyed
+            // an arbitrary file outside the target, a second rewrite overwrote the first backup (the
+            // user's original gone for good), a swallowed failure left the only copy destroyed in
+            // silence, and utf8 round-tripping replaced non-UTF8 bytes with U+FFFD. Bytes, a unique name,
+            // 'wx' (which refuses any existing path INCLUDING a symlink), and — if the copy cannot be
+            // made — the rewrite does not happen at all.
+            const prevBytes = (() => { try {
+                return fs.readFileSync(real);
+            }
+            catch {
+                return undefined;
+            } })();
+            const wanted = installedSkillBytes(body);
+            if (prevBytes !== undefined && prevBytes.toString('utf8') !== wanted) {
+                // round-9: beside the DESTINATION, never beside the link's far end. The rewrite follows a
+                // user's symlink by design (§5g), but a file the kit CREATES belongs inside the target the
+                // operator named — a backup appearing in a central dotfiles repo is a write they never
+                // asked for.
+                // round-9 (3rd): asking whether the SKILL DIRECTORY is a link closed one level and left the
+                // one above it open — with `.claude/skills` itself linked into a dotfiles repo the backup
+                // still landed outside the target, and the report printed an in-target path for a file that
+                // was never there. Containment is a fact about the RESOLVED location, not about which
+                // component happened to be a link.
+                //
+                // When neither candidate resolves inside the target, nothing new is invented: this falls
+                // into the rule §10(a) already set — a rewrite whose previous content cannot be preserved
+                // does not happen, and says so. Minting a backup directory of our own in a project that
+                // deliberately keeps its skills elsewhere would be one more write the operator did not ask
+                // for, which is the very thing this clause exists to stop.
+                const insideTarget = (p) => {
+                    try {
+                        const real = fs.realpathSync(path.dirname(p));
+                        const base = fs.realpathSync(target);
+                        return real === base || real.startsWith(base + path.sep);
+                    }
+                    catch {
+                        return false;
+                    }
+                };
+                const suffix = `.holmes-bak-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+                const bak = [
+                    `${dest}${suffix}`,
+                    path.join(path.dirname(path.dirname(dest)), `${invocableSkillName(name)}.SKILL.md${suffix}`),
+                ].find(insideTarget);
+                if (bak === undefined) {
+                    out.failed.push({ name, reason: `${dest} 의 이전 내용을 타깃(${target}) 안에 보존할 수 없어 다시 쓰지 않았습니다 — .claude/skills 가 타깃 밖을 가리키는 링크입니다. 링크를 풀거나 그 저장소에서 직접 갱신하십시오` });
+                    continue;
+                }
+                try {
+                    fs.writeFileSync(bak, prevBytes, { flag: 'wx' });
+                    out.backedUp.push({ name, path: bak });
+                }
+                catch (bakErr) {
+                    out.failed.push({ name, reason: `${skillPathFor(target, name)} 의 이전 내용을 보존할 수 없어 다시 쓰지 않았습니다: ${bakErr instanceof Error ? bakErr.message : String(bakErr)}` });
+                    continue;
+                }
+            }
+            let madeBackup = out.backedUp.find((b) => b.name === name && b.path.includes('holmes-bak-'))?.path;
+            try {
+                fs.writeFileSync(tmp, wanted, { encoding: 'utf8', flag: 'wx' });
+                if (prevMode !== undefined)
+                    fs.chmodSync(tmp, prevMode);
+                fs.renameSync(tmp, real);
+                madeBackup = undefined; // 갱신이 끝났으므로 백업은 정당하게 남는다
+            }
+            finally {
+                // round-9: a failed rewrite left BOTH the backup and the temp file behind, so following
+                // doctor's advice grew two files per attempt — a remedy loop that never converges and never
+                // repairs. Nothing we could not finish is left on disk.
+                try {
+                    fs.rmSync(tmp, { force: true });
+                }
+                catch { /* already gone */ }
+                if (madeBackup !== undefined) {
+                    try {
+                        fs.rmSync(madeBackup, { force: true });
+                    }
+                    catch { /* leave it */ }
+                    out.backedUp = out.backedUp.filter((b) => b.path !== madeBackup);
+                }
+            }
+            out.written.push(name);
+        }
+        catch (err) {
+            // A permission problem must not kill an init that has already done real work.
+            // round-7: the raw message named the unique temp path ('…SKILL.md.holmes-tmp-4711-x9f2'),
+            // a file that never existed by the time the operator read it — the reason now names the
+            // destination they can actually inspect.
+            const raw = err instanceof Error ? err.message : String(err);
+            out.failed.push({ name, reason: `${skillPathFor(target, name)}: ${raw.replace(/\.holmes-tmp-\d+-[a-z0-9]+/g, '')}` });
+        }
+    }
+    return out;
+}
+/** Removes ONLY files carrying the marker; a foreign file, and the directory holding it, are left. */
+function removePlaybookSkills(target) {
+    const out = { removed: [], failed: [] };
+    // round-9 (3rd): the per-skill guard refused a link while `readdirSync` had already followed the
+    // link ONE LEVEL UP — a `.claude/skills -> ~/dotfiles/skills` project lost its central store to
+    // `init --remove`, with `failed` empty and the report naming in-target paths nothing touched.
+    // The same one physical link cannot be refused below and traversed above. §12 moved that question
+    // one level further up, where `.claude` itself was the link.
+    const rootCheck = skillsRootInside(target);
+    if ('refusal' in rootCheck) {
+        out.failed.push({ name: path.join('.claude', 'skills'), reason: rootCheck.refusal });
+        return out;
+    }
+    const skillsDir = rootCheck.dir;
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries.sort()) {
+        // Case-folded prefix (round-3): a case-only rename to `Holmes-adopt` still read as current on a
+        // case-insensitive FS, but failed this exact-case check — uninstall left the marker-owned file
+        // behind and the count disagreed with the states. Ownership is the MARKER's job, not the case's.
+        if (!entry.toLowerCase().startsWith('holmes-'))
+            continue;
+        const file = path.join(skillsDir, entry, 'SKILL.md');
+        try {
+            // @implements A-SPEC-190 (round 8) — a skill DIRECTORY the user manages as a symlink pointed
+            // at a central copy OUTSIDE the target: remove deleted that copy, reported the in-target path
+            // it never touched, and left the link dangling so reinstall failed forever after.
+            if (fs.lstatSync(path.join(skillsDir, entry)).isSymbolicLink()) {
+                out.failed.push({ name: entry, reason: `${path.join(skillsDir, entry)} 는 심볼릭 링크입니다 — 링크 너머의 파일을 지우지 않았습니다. 링크를 직접 정리하십시오` });
+                continue;
+            }
+            if (!fs.existsSync(file) || !isOurs(file))
+                continue;
+            fs.rmSync(file);
+            // round-9: our own backups kept the directory alive, and no state named the leftovers — the
+            // uninstall never converged. What we wrote, we take back.
+            try {
+                for (const leftover of fs.readdirSync(path.join(skillsDir, entry))) {
+                    if (leftover.startsWith('SKILL.md.holmes-bak'))
+                        fs.rmSync(path.join(skillsDir, entry, leftover), { force: true });
+                }
+            }
+            catch { /* leave it */ }
+            // Only if nothing else lives there — a user may keep their own files alongside ours.
+            try {
+                if (fs.readdirSync(path.join(skillsDir, entry)).length === 0)
+                    fs.rmdirSync(path.join(skillsDir, entry));
+            }
+            catch { /* leave it */ }
+            out.removed.push(entry);
+        }
+        catch (err) {
+            out.failed.push({ name: entry, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return out;
+}
+// @implements A-SPEC-190
+// @implements A-SPEC-190 §20 (round 13) — `unresolvable`: the skills root points outside the target,
+// so nothing under it is ours to judge OR to repair. A state of its own, because calling it
+// `drifted` prescribes a refresh that is refused every time.
+/**
+ * How a failed entry should be NAMED in a report.
+ *
+ * @implements A-SPEC-190 §21 (round 13) — root-level refusals carry `.claude/skills` as their name,
+ * and the callers ran every name through `invocableSkillName`, printing `holmes-.claude/skills` —
+ * a skill that does not exist. Round 7 fixed the same prefixing on the remove side. A name that
+ * already looks like a path is a path.
+ */
+function skillLabel(name) {
+    return name.includes('/') || name.includes('\\') ? name : invocableSkillName(name);
+}
+/**
+ * @implements A-SPEC-190
+ * Per-playbook state of the installed copy, judged against the bytes install would write NOW
+ * (`marker + '\n' + shipped body`). An installed skill is a COPY: the kit's conventions move on
+ * while the copy stays frozen at install time. Measured 2026-08-15 in this very repository: all
+ * three installed skills had drifted (diff 50/38/64 lines) and the author-slice copy still taught
+ * the abolished `A-SPEC-125.5 → T-SPEC-1255` id convention — while the count-only doctor check
+ * reported "3 of 3 … PASS". Equality with the reconstruction is the single source of truth; a
+ * version stamp or hash file would be a second truth that itself goes stale.
+ *
+ * A shipped body that cannot be read (a race — playbookNames just confirmed it) yields no entry
+ * for that name: silence beats a wrong repair hint.
+ */
+function playbookSkillStates(packageRoot, target) {
+    const out = [];
+    // @implements A-SPEC-190 §20 (round 13) — §12's fence went on install and remove, not on the
+    // function DOCTOR judges from. So with `<target>/.claude` linked outside the target, doctor read
+    // the files beyond the link, declared them drifted/missing, and prescribed `skills refresh` —
+    // which §12 refuses every time. A diagnosis whose remedy can never run is worse than no
+    // diagnosis: it teaches the operator to ignore the tool. Say the one thing that IS actionable.
+    const fenced = skillsRootInside(target);
+    if ('refusal' in fenced) {
+        return playbookNames(packageRoot).map((name) => ({ name, state: 'unresolvable' }));
+    }
+    const shipped = playbookNames(packageRoot);
+    for (const name of shipped) {
+        let body;
+        // @implements A-SPEC-190 (round 7) — an unreadable SHIPPED playbook used to `continue`, so the
+        // name vanished from the report: doctor said PASS (or the nonsense '3 of 0') while the refresh
+        // it never advised exited 1 on the same target. The package's own damage gets its own state.
+        try {
+            body = fs.readFileSync(path.join(packageRoot, 'playbooks', name, 'PLAYBOOK.md'), 'utf8');
+        }
+        catch {
+            out.push({ name, state: 'source-unreadable' });
+            continue;
+        }
+        const dest = skillPathFor(target, name);
+        // @implements A-SPEC-190 (round 8) — two skills resolving to ONE file is a state, not just an
+        // install-time failure: doctor used to call one of them `drifted` and advise a refresh that
+        // could only ever exit 1. The operator has to unlink; say so.
+        if (aliasedNames(packageRoot, target).has(name)) {
+            out.push({ name, state: 'aliased' });
+            continue;
+        }
+        let installed;
+        try {
+            installed = fs.readFileSync(dest, 'utf8');
+        }
+        catch (err) {
+            // ENOENT alone is absence — but only when nothing occupies the path: readFileSync FOLLOWS
+            // symlinks, so a BROKEN link also reads ENOENT while install's lstat sees it present and
+            // skips it as foreign (round-3: doctor said 'missing', the advised refresh said 'yours' —
+            // an unresolvable loop). Presence is judged the way install judges it: by lstat. Any other
+            // read failure (EACCES, EISDIR, ELOOP…) means the marker cannot be read, and ownership is
+            // decided by the marker — a file we cannot prove ours is not ours to repair.
+            const lstatPresent = (() => {
+                try {
+                    fs.lstatSync(dest);
+                    return true;
+                }
+                catch { /* fall through */ }
+                // round-8: the SKILLS directory itself may be a dangling link. Reading through it is ENOENT
+                // while install's mkdir/write is ENOENT too — the old 'missing' verdict advised a refresh
+                // that could only ever fail, the exact non-convergent loop rounds 3 and 5 closed one level
+                // deeper. Something occupies the path; it is not ours to repair.
+                try {
+                    const skillsRoot = path.dirname(path.dirname(dest));
+                    if (fs.lstatSync(skillsRoot).isSymbolicLink() && !fs.existsSync(skillsRoot))
+                        return true;
+                }
+                catch { /* fall through */ }
+                // The skill DIRECTORY itself may be a (possibly dangling) symlink the user manages —
+                // read fails ENOENT through it while something clearly occupies the path (round-5:
+                // 'missing' here + install's skip = another unresolvable remedy loop).
+                try {
+                    return fs.lstatSync(path.dirname(dest)).isSymbolicLink();
+                }
+                catch {
+                    return false;
+                }
+            })();
+            out.push({ name, state: err.code === 'ENOENT' && !lstatPresent ? 'missing' : 'foreign' });
+            continue;
+        }
+        const state = !carriesMarker(installed) ? 'foreign'
+            : installed === installedSkillBytes(body) ? 'current' : 'drifted';
+        out.push({ name, state });
+    }
+    // Marker-owned installs of names we no longer ship are STALE GUIDANCE — exactly REQ-190's problem
+    // class — yet the shipped loop above cannot see them. Markerless non-shipped entries are the
+    // user's own skills and stay off our list entirely.
+    const skillsDir = path.join(target, '.claude', 'skills');
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of classifyExtraEntries(entries, shipped, (entry2, canonical) => {
+        try {
+            const a = fs.statSync(path.join(skillsDir, entry2));
+            const b = fs.statSync(path.join(skillsDir, canonical));
+            return a.ino === b.ino && a.dev === b.dev;
+        }
+        catch {
+            return undefined;
+        }
+    }, (entry2) => isOurs(path.join(skillsDir, entry2, 'SKILL.md')))) {
+        // The RAW directory name, case intact (round-6 HIGH): slicing the prefix folded
+        // `Holmes-adopt` to `adopt`, doctor re-prefixed it to `holmes-adopt`, and the orphan remedy
+        // told the operator to DELETE THE CURRENT SKILL on a case-sensitive FS.
+        out.push({ name: entry, state: 'orphaned' });
+    }
+    return out;
+}
+/**
+ * @implements A-SPEC-190 (§6)
+ * Which extra `.claude/skills` entries are ORPHANED marker-owned installs? Pure — the fs facts
+ * (inode identity, marker ownership) come in as functions, so the case-SENSITIVE world is testable
+ * on any machine (round-5 HIGH lived exactly in the branch this box's case-folding FS cannot
+ * exercise: `Holmes-adopt` sliced to `adopt`, matched shipped, and was swallowed BEFORE the
+ * variant/inode logic — doctor printed PASS over stale marker-owned guidance).
+ *
+ * - exact canonical entries are the shipped loop's business (skip);
+ * - a case-variant with the SAME inode is the same physical dir (case-insensitive FS — skip;
+ *   round-2: double-counting made the orphan remedy delete the current skill);
+ * - everything else marker-owned is orphaned; unreadable/markerless stays silent (ownership is
+ *   the marker's job — user territory).
+ */
+function classifyExtraEntries(entries, shipped, sameInode, owned) {
+    const orphans = [];
+    for (const entry of [...entries].sort()) {
+        if (!entry.toLowerCase().startsWith('holmes-'))
+            continue; // 'Holmes-adopt' is still ours to judge
+        const name = entry.slice('holmes-'.length);
+        if (entry.startsWith('holmes-') && shipped.includes(name))
+            continue; // exact canonical only
+        const variantOf = shipped.find((s) => `holmes-${s}`.toLowerCase() === entry.toLowerCase());
+        if (variantOf && sameInode(entry, invocableSkillName(variantOf)) === true)
+            continue;
+        if (owned(entry))
+            orphans.push(entry); // RAW entry — the name the operator must act on
+    }
+    return orphans;
+}
+/** How many recovery skills are installed — the fact `doctor` reports. */
+function installedPlaybookCount(target) {
+    const skillsDir = path.join(target, '.claude', 'skills');
+    try {
+        return fs.readdirSync(skillsDir)
+            .filter((e) => e.toLowerCase().startsWith('holmes-') && isOurs(path.join(skillsDir, e, 'SKILL.md')))
+            .length;
+    }
+    catch {
+        return 0;
+    }
+}