@holmes-lab/holmes-kit 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.1.8] - 2026-08-20
+
+### Added
+- **Hybrid Dynamic CPG Engine (REQ-216)**: Dynamic test coverage trace fusion with static AST graphs to eliminate reflection/dynamic invocation false negatives.
+- **Datalog-based Program Slicing & Noise Pruning (REQ-217)**: Transitive closure reachability slicing (forward/backward/both) to prune irrelevant AST nodes and isolate affected blast radius.
+- **AST Mutation & Fuzzing Harness (REQ-214)**: Multi-operator mutation generator (relational, arithmetic, logical, unary) with mutation score calculation.
+- **TypeScript Declaration Bundling**: Full `.d.ts` declaration generation across all modules and `types` entrypoint in `package.json`.
+
 ## [0.1.7] - 2026-08-19
 
 ### Changed

package/README.md

@@ -55,7 +55,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 ```bash
 npm install -g @holmes-lab/holmes-kit
 ```
-*(Requires Node.js `>= 20.0.0` and C++ build tools for native SQLite/tree-sitter)*
+*(Prerequisites: Node.js `>= 20.0.0`. Prebuilt binaries are provided automatically for macOS, Linux, and Windows. For minimal Alpine Docker containers, install build tools: `apk add --no-cache python3 make g++`)*
 
 ### 2. Initialize in Your Project
 ```bash
@@ -104,12 +104,16 @@ flowchart LR
 | `holmes-kit init --agent all` | Non-interactive instant setup for all supported agents |
 | `holmes-kit init --dry-run` | Preview files and configuration changes without writing |
 | `holmes-kit doctor` | Comprehensive health check of specs, hooks, MCP, and anchors |
+| `holmes-kit doctor --fix` | Automatically self-heal and repair broken hooks or missing skills |
+| `holmes-kit ci` | Run non-interactive headless governance gate for GitHub Actions / GitLab CI |
+| `holmes-kit ci --json` | Run CI gate and emit machine-readable JSON results |
 
 ---
 
-## 🤖 Manual MCP Configuration
+## 🧩 Optional: Manual MCP Integration (Cursor, Windsurf, Claude Desktop)
 
-If you prefer to configure MCP manually or integrate with other IDEs, add the following to your `.mcp.json`:
+> **Note**: If you ran `holmes-kit init`, this configuration is **100% automated for you**.  
+> Use the manual configuration below only if you wish to integrate Holmes-Kit into standalone third-party MCP clients like Cursor, Windsurf, Claude Desktop, or VS Code:
 
 ```json
 {
@@ -154,11 +158,11 @@ Holmes-Kit embeds native AST & Code Property Graph (D-CPG) analyzers to track ca
 
 ---
 
-## 🏛️ Key Capabilities
+## 🔒 Source Code Availability & Distribution Policy
 
-- **Deterministic Hook Enforcement**: Gating is enforced via OS-level PreToolUse & Stop hooks, not easily bypassed prompts.
-- **D-CPG + RTM Graph**: Tree-sitter Code Property Graph + SQLite recursive-CTE for instant blast-radius impact analysis (`rtm_impact`).
-- **Cryptographic Provenance Ledger**: Every decision, approval, and gate transition is immutably recorded in `.ax/ledger/`.
+- **Distribution Mode**: Holmes-Kit is currently distributed and executable as an official public npm package ([`@holmes-lab/holmes-kit`](https://www.npmjs.com/package/@holmes-lab/holmes-kit)).
+- **Source Code Status**: The underlying source code repository is currently **private / closed-source**.
+- **Open Source Consideration**: Decisions regarding whether, when, and how to transition to a full open-source codebase will be reviewed and determined in future milestones based on enterprise feedback, security audits, and community governance requirements.
 
 ---
 

package/dist/.build-id

@@ -1 +1 @@
-47dc66a-msytu2tq
+ef6b2ad-mt1pqqxf

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

@@ -0,0 +1,50 @@
+/**
+ * 하네스별 배선물.
+ *
+ * Holmes-Kit 의 명제("승인된 스펙 없이는 코드가 들어가지 않는다")를 **집행**하는 것은 MCP
+ * 도구가 아니라 훅이다. 그래서 하네스마다 물어야 할 첫 질문은 "이 도구에 훅이 있는가"이고,
+ * 없다면 **집행한다고 말하지 않는 것**이 이 파일의 일이다. 도구는 주되 규율은 못 세우면서
+ * 세운다고 적으면, 그 문장을 믿은 사용자가 지켜지지 않는 게이트 위에서 일한다.
+ */
+export declare const AGENTS: readonly ["claude", "antigravity", "codex"];
+export type Agent = (typeof AGENTS)[number];
+/**
+ * 그 하네스에서 게이트가 **집행되는가**.
+ *
+ * - `claude` — PreToolUse/Stop 훅. 이 저장소가 처음부터 배선해 온 하네스.
+ * - `antigravity` — PreToolUse/Stop 훅이 있고 `deny`/`continue` 로 막을 수 있다(설치본의
+ *   `agy-customizations` 규약 문서와 실제 대화 기록에서 실측).
+ * - `codex` — 이 기계에 설치되어 있지 않아 훅 규약을 **재지 못했다**. 재지 못한 것을 있다고
+ *   적지 않는다. 도구(MCP)와 지침만 준다.
+ */
+export declare const HARNESS_ENFORCES: Record<Agent, boolean>;
+export interface AgentWiringOptions {
+    target: string;
+    packageRoot: string;
+    specsDir: string;
+}
+export interface AgentFile {
+    path: string;
+    content: string;
+}
+/**
+ * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
+ *
+ * 계산과 쓰기를 나누는 이유는 dry-run 이 실제 실행과 같은 집합을 예고해야 하기 때문이다
+ * (A-SPEC-190 §9). 같은 함수가 두 경로에 답하면 둘이 어긋날 수 없다.
+ */
+export declare function agentFiles(agent: Agent, opts: AgentWiringOptions): AgentFile[];
+export interface AgentLink {
+    path: string;
+    target: string;
+    why: string;
+}
+/**
+ * 하네스가 스킬을 **볼 수 있게** 하는 링크.
+ *
+ * 스킬 본문은 한 곳(`.claude/skills`)에만 둔다 — 같은 내용을 두 벌 두면 하나가 갱신될 때
+ * 다른 하나가 낡고, doctor 는 한쪽만 본다(그 드리프트가 REQ-190 의 출발점이었다). 그래서
+ * Antigravity 쪽은 링크로 같은 파일을 가리킨다. 이 배치는 타깃 안에 머물므로 설치 담장을
+ * 지나간다(A-SPEC-193 §7 이 그 담장을 '타깃 밖만'으로 좁힌 이유이기도 하다).
+ */
+export declare function agentLinks(agent: Agent, opts: AgentWiringOptions): AgentLink[];

package/dist/holmes/cli/ci-gate.d.ts

@@ -0,0 +1,18 @@
+export interface CiViolation {
+    file?: string;
+    specId?: string;
+    reason: string;
+}
+export interface CiGateResult {
+    ok: boolean;
+    violations: CiViolation[];
+    summary: string;
+}
+/**
+ * Headless CI/CD Governance Gate Runner for GitHub Actions / GitLab CI.
+ *
+ * @implements A-SPEC-213
+ */
+export declare function runCiGate(targetDir: string, options?: {
+    specsDir?: string;
+}): CiGateResult;

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

@@ -0,0 +1,44 @@
+/**
+ * `holmes-kit doctor` — install diagnostics.
+ *
+ * Native-module breakage is the likeliest failure mode of an install on another machine, and the
+ * hooks fail OPEN, so a broken install is silent: governance simply never fires. This command makes
+ * that loud. Every check reports PASS/WARN/FAIL plus a concrete remediation.
+ */
+export type Level = 'PASS' | 'WARN' | 'FAIL';
+export interface Check {
+    name: string;
+    level: Level;
+    detail: string;
+    fix?: string;
+    remediate?: () => boolean;
+}
+export interface DoctorOptions {
+    run?: ProbeRunner;
+    autoFix?: boolean;
+}
+/**
+ * Environment variables removed before spawning a probe.
+ *
+ * @implements A-SPEC-143
+ * `HOLMES_APPROVAL` grants permission, so a probe that inherits one measures the GRANT rather than
+ * the gate. `HOLMES_SPECS` redirects the spec root, so a probe reading another project's specs
+ * answers a different question than the one asked. `HOLMES_LEDGER_KEY` is deliberately NOT here: it
+ * changes how the ledger is signed, not whether the gate enforces, and stripping it could mask a
+ * real key-related failure.
+ */
+export declare const STRIPPED_FOR_PROBE: readonly ["HOLMES_APPROVAL", "HOLMES_SPECS"];
+/** The parent environment minus the variables that legitimately change a gate decision. Pure. */
+export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */
+export interface ProbeRunner {
+    /** `env` is passed EXPLICITLY so a test can observe what the child would actually receive — a
+     *  runner that never sees it cannot verify the wiring, only restate the helper. */
+    (script: string, payload: unknown, env: NodeJS.ProcessEnv): {
+        status: number | null;
+        stdout?: string;
+        stderr?: string;
+    };
+}
+export declare function runDoctor(packageRoot: string, target?: string, opts?: DoctorOptions, extraChecks?: Check[]): Promise<Check[]>;
+export declare function formatChecks(checks: Check[]): string;

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

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export declare const BEGIN = "# >>> holmes-kit >>>";
+export declare const END = "# <<< holmes-kit <<<";
+/** Derived/runtime paths holmes-kit creates in a target project. */
+export declare const IGNORE_LINES: string[];
+/**
+ * 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.
+ */
+export declare function mergeGitignore(existing: string, lines?: string[]): string;
+/** Remove the block (and the blank line that preceded it, if we added one). Inverse of merge. */
+export declare function removeGitignoreBlock(existing: string): string;
+/** True iff the holmes-kit block is present. */
+export declare function hasGitignoreBlock(existing: string): boolean;

package/dist/holmes/cli/governed-precondition.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare function hasGatedCode(target: string): boolean;
+/**
+ * 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.
+ */
+export declare function governedWarning(target: string): string[];

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

@@ -0,0 +1,14 @@
+/**
+ * `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.
+ */
+export declare function packageRoot(): string;
+export declare function main(argv: string[]): Promise<number>;

package/dist/holmes/cli/index.js

@@ -37,6 +37,7 @@ exports.packageRoot = packageRoot;
 exports.main = main;
 // @implements A-SPEC-100.2
 // @implements A-SPEC-213
+// @implements A-SPEC-215
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const init_1 = require("./init");
@@ -71,6 +72,7 @@ const KNOWN_FLAGS = {
     doctor: ['help', 'target', 'json'],
     skills: ['help', 'target'],
     ci: ['help', 'target', 'specs-dir', 'json'],
+    serve: ['help', 'target', 'port'],
 };
 class UnknownFlagError extends Error {
 }
@@ -325,6 +327,21 @@ async function main(argv) {
         }
         return res.ok ? 0 : 1;
     }
+    // @implements A-SPEC-215
+    if (cmd === 'serve') {
+        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 target = typeof flags.target === 'string' ? flags.target : process.cwd();
+        const port = typeof flags.port === 'string' ? parseInt(flags.port, 10) : undefined;
+        const { runServeCommand } = require('./serve');
+        await runServeCommand({ root: target, port });
+        return 0;
+    }
     if (cmd === 'init') {
         const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
         // 형제 열거 오류와 같은 모양(round 7): --settings·--target 은 USAGE 와 함께 exit 2 인데
@@ -428,5 +445,10 @@ async function main(argv) {
     return cmd.startsWith('-') ? 2 : 1;
 }
 if (require.main === module) {
-    main(process.argv.slice(2)).then((code) => process.exit(code));
+    main(process.argv.slice(2))
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        process.stderr.write(`[holmes-kit error] ${err?.message || err}\n`);
+        process.exit(1);
+    });
 }

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

@@ -0,0 +1,69 @@
+import { HookPlan } from './settings-merge';
+import { Agent } from './agents';
+import { Approval } from '../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.
+ */
+export declare const SERVER_NAME = "holmes-kit";
+export type InitMode = 'guardrail' | 'governed';
+export interface InitOptions {
+    target: string;
+    packageRoot: string;
+    mode: InitMode;
+    specsDir: string;
+    settingsFile: 'local' | 'project';
+    mcp: boolean;
+    matcher?: string;
+    dryRun: boolean;
+    force: boolean;
+    remove: boolean;
+    approval?: Approval;
+    agents?: Agent[];
+    allowAdditive?: boolean;
+}
+export interface FileChange {
+    path: string;
+    before: string | null;
+    after: string | null;
+}
+export interface InitResult {
+    ok: boolean;
+    exitCode: 0 | 1 | 2;
+    messages: string[];
+    changes: FileChange[];
+    /** Paths a dry-run says it WOULD DELETE — never rendered with the write verb (round-8). */
+    removals?: string[];
+}
+/**
+ * @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.
+ */
+export declare const MATCHERS: Record<InitMode, string>;
+/** Absolute hook/mcp commands, quoted so a package path containing spaces still works. */
+export declare function buildHookPlan(packageRoot: string, matcher: string, specsDir?: string): HookPlan;
+export declare const settingsPathOf: (target: string, which: "local" | "project") => string;
+export declare function runInit(opts: InitOptions): InitResult;

package/dist/holmes/cli/interactive-prompt.d.ts

@@ -0,0 +1,9 @@
+import { Agent } from './agents';
+/**
+ * Parses user input or CLI flag string into normalized Agent array.
+ */
+export declare function parseAgentList(input: string): Agent[];
+/**
+ * Renders an interactive TTY checkbox selection menu using standard readline & ANSI codes.
+ */
+export declare function promptAgentSelection(availableAgents?: readonly Agent[], currentWired?: Agent[]): Promise<Agent[]>;

package/dist/holmes/cli/playbook-skills.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare function installedSkillBytes(body: string): string;
+/**
+ * @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.
+ */
+export declare function carriesMarker(content: string): boolean;
+/**
+ * @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`.
+ */
+export declare function frontmatterEnd(content: string): number | null;
+/**
+ * @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.
+ */
+export declare function invocableSkillName(playbookName: string): string;
+/** `<target>/.claude/skills/holmes-<name>/SKILL.md` */
+export declare function skillPathFor(target: string, playbookName: string): string;
+export interface PlaybookInstallResult {
+    /** Playbook names written (new, or refreshed because the destination was ours). */
+    written: string[];
+    /** Destinations whose previous content was preserved beside them before being rewritten. */
+    backedUp: {
+        name: string;
+        path: string;
+    }[];
+    /** Names left alone because a FOREIGN file occupies the destination. */
+    skipped: string[];
+    /** Names whose destination could not be written; reported rather than thrown. */
+    failed: {
+        name: string;
+        reason: string;
+    }[];
+}
+export declare function installPlaybookSkills(packageRoot: string, target: string): PlaybookInstallResult;
+export interface PlaybookRemoveResult {
+    /** RAW directory names, case intact — round-7: the report re-prefixed a case variant and named a directory that does not exist. */
+    removed: string[];
+    failed: {
+        name: string;
+        reason: string;
+    }[];
+}
+/** Removes ONLY files carrying the marker; a foreign file, and the directory holding it, are left. */
+export declare function removePlaybookSkills(target: string): PlaybookRemoveResult;
+/**
+ * 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.
+ */
+export declare function skillLabel(name: string): string;
+export type PlaybookSkillState = 'current' | 'drifted' | 'foreign' | 'missing' | 'orphaned' | 'source-unreadable' | 'aliased' | 'unresolvable';
+/**
+ * @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.
+ */
+export declare function playbookSkillStates(packageRoot: string, target: string): {
+    name: string;
+    state: PlaybookSkillState;
+}[];
+/**
+ * @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).
+ */
+export declare function classifyExtraEntries(entries: string[], shipped: string[], sameInode: (entry: string, canonicalDir: string) => boolean | undefined, owned: (entry: string) => boolean): string[];
+/** How many recovery skills are installed — the fact `doctor` reports. */
+export declare function installedPlaybookCount(target: string): number;

package/dist/holmes/cli/roles-readme.d.ts

@@ -0,0 +1,12 @@
+/** Identifies the file as ours, so `--remove` never reclaims something a user wrote. */
+export declare const ROLES_README_MARKER = "<!-- holmes-kit:roles-guide -->";
+export declare const rolesReadmePath: (root: string) => string;
+/** Installs the guidance. A file the user has edited is left alone. */
+export declare function installRolesReadme(root: string): void;
+/**
+ * Reclaims the guidance on `init --remove`. Returns whether it was ours to remove.
+ *
+ * Only this file is touched — a project's real `policy.yaml` living beside it must survive, since
+ * removing the docs is not a request to disable governance.
+ */
+export declare function removeRolesReadme(root: string): boolean;

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

@@ -0,0 +1,14 @@
+export interface ServeOptions {
+    root: string;
+    port?: number;
+}
+/**
+ * Execute holmes-kit serve subcommand. Keeps process alive until SIGINT/SIGTERM in CLI execution.
+ *
+ * @implements A-SPEC-215
+ */
+export declare function runServeCommand(options: ServeOptions): Promise<{
+    ok: boolean;
+    url: string;
+    stop: () => Promise<void>;
+}>;

package/dist/holmes/cli/serve.js

@@ -0,0 +1,70 @@
+"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.runServeCommand = runServeCommand;
+// @implements A-SPEC-215
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const dashboard_1 = require("../server/dashboard");
+/**
+ * Execute holmes-kit serve subcommand. Keeps process alive until SIGINT/SIGTERM in CLI execution.
+ *
+ * @implements A-SPEC-215
+ */
+async function runServeCommand(options) {
+    const root = path.resolve(options.root);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        process.stderr.write(`[holmes-kit serve] Target directory does not exist: ${root}\n`);
+        process.exit(2);
+    }
+    const handle = await (0, dashboard_1.startDashboardServer)({ root, port: options.port });
+    process.stdout.write(`🚀 Holmes-Kit Dashboard Server running at ${handle.url}\nPress Ctrl+C to stop.\n`);
+    if (process.env.NODE_ENV !== 'test') {
+        await new Promise((resolve) => {
+            const shutdown = async () => {
+                process.stdout.write(`\nStopping Holmes-Kit Dashboard Server...\n`);
+                await handle.stop();
+                resolve();
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
+    }
+    return {
+        ok: true,
+        url: handle.url,
+        stop: handle.stop,
+    };
+}