@holmes-lab/holmes-kit 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.6] - 2026-08-19
+
+### Documentation
+- **Current Production Features vs. Vision & Roadmap Distinction**: Explicitly separated currently supported production features in `v0.1.x` from future roadmap goals (Jira/Linear tool connectors, multi-repo polyrepo governance `REQ-211`, external SAST bridges) in `README.md` to avoid feature expectation confusion.
+
+## [0.1.5] - 2026-08-19
+
+### Added
+- **Subprocess Secret Isolation (REQ-205)**: Standardized `cleanSubprocessEnv` to scrub sensitive environment variables (`HOLMES_ROLE`, `HOLMES_ENV_CHANNEL`, `HOLMES_APPROVAL`, `HOLMES_LEDGER_KEY`) across all child process executions.
+- **Multi-Ledger Dynamic Indexing Engine (REQ-206)**: High-performance mtime/size-based indexing cache with immutable deep cloning (`cloneEvents`) and fail-closed error handling in `ProvenanceLedger`.
+- **Doctor Self-Healing Engine (REQ-207)**: Integrated `runDoctor({ autoFix: true })` auto-remediation loop and `Check.remediate()` callbacks for system diagnostic repair.
+- **CPG Incremental Indexer (REQ-208)**: SHA-256 content-hash AST parsing skip in `ScanFileCache` & `CpgScanner` with scoped directory mark-and-sweep pruning and deep `DataFlowFacts` cloning.
+- **Automated RTM & Security Taint Heatmap Generator (REQ-212)**: Self-contained interactive HTML/SVG report builder (`generateRtmHeatmap`) for spec chain coverage and security taint reachability.
+- **CI/CD Governance Gate Runner (REQ-213)**: Non-interactive headless CI runner (`holmes-kit ci`) for GitHub Actions / GitLab CI with path traversal protection and gitignore filtering.
+
+### Documentation
+- **Sherlock Holmes Vision & Philosophy**: Updated `README.md` to detail the Sherlock Holmes deduction, defect analysis, full SDLC coverage, enterprise tool harness vision, and supported AI coding tools matrix.
 
 ## [0.1.4] - 2026-08-18
 

package/README.md

@@ -6,7 +6,46 @@
 
 > **"No Spec, No Code"** — Deterministic Agentic Software Engineering (ASE) harness with causal traceability.
 
-Holmes-Kit is a **deterministic control plane** for AI coding agents (**Claude Code**, **Antigravity CLI**, **Codex CLI**). It enforces architectural discipline at the hook layer so that every line of code is causally traceable back to approved specifications (`REQ → H-SPEC → A-SPEC → T-SPEC`).
+---
+
+## 🕵️ Philosophy & Vision: Beyond Code Generation
+
+**Holmes-Kit** is not merely an AI code generator. Inspired by **Sherlock Holmes**, Holmes-Kit is built to **deduce, track down, and analyze code defects, structural drift, and security vulnerabilities** across the full Software Development Life Cycle (**SDLC**).
+
+---
+
+### 🛡️ Currently Supported Features (v0.1.x Production Features)
+
+- 📋 **Requirements & Specification Governance**: Strict **"No Spec, No Code"** enforcement with 4-tier spec chain traceability (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) and `// @implements A-SPEC-XXX` line 1 code anchors.
+- 🐞 **Causal Defect Localization & CPG**: AST Code Property Graph (CPG) & Dataflow Taint reachability analysis across 7 languages (TS/JS, Python, Go, Rust, Java, C/C++, C#).
+- 🧪 **Self-Healing & Diagnostic Doctor**: Automated integrity checks and self-healing auto-fix remediation (`holmes-kit doctor --fix` & `spec_remediate`).
+- 🚦 **CI/CD Governance Gate Runner**: Non-interactive headless CI/CD build gate (`holmes-kit ci`) for GitHub Actions and GitLab CI pipelines.
+- 📊 **Automated RTM & Taint Heatmap**: Interactive standalone HTML/SVG report generation (`generateRtmHeatmap`) for spec coverage and security dataflow reachability.
+- 🤖 **CLI-First AI Harness Matrix**: Native process hook gating for Claude Code, Antigravity CLI (AGY), Codex CLI, and Google Antigravity SDK.
+
+---
+
+### 🚀 Full SDLC Vision & Roadmap (Future Goals)
+
+Holmes-Kit strives to expand into a unified enterprise SDLC harness bridging external development tools:
+- 🔌 **Enterprise Issue Tracker Connectors**: Flexible synchronization with Jira, GitHub Issues, Linear, and Notion.
+- 🌐 **Multi-Repository Polyrepo Governance**: Multi-repo spec chain synchronization and cross-repository dependency impact analysis (`REQ-211`).
+- 🛡️ **External SAST & Linter Bridge**: Deep integration with SonarQube, Semgrep, and ESLint findings.
+
+---
+
+## 🤖 Supported AI Coding Tools & Environments (CLI-First Focus)
+
+Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hooks, subshell isolation, and deterministic control plane enforcement are natively guaranteed:
+
+| AI Coding Agent / Framework | Harness Tier | Integration & Enforcement Mechanisms |
+| :--- | :--- | :--- |
+| 🤖 **Claude Code CLI** | 🥇 Tier 1 (Native) | OS PreToolUse & Stop hooks (`.claude/settings.local.json`), MCP server (`.mcp.json`) |
+| 🚀 **Antigravity CLI (AGY)** | 🥇 Tier 1 (Native) | AGY Hooks (`hooks.json`), MCP config (`.agents/mcp_config.json`), Governance Skills |
+| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/mcp_config.json`), Subshell Isolation Gates |
+| 🧩 **Google Antigravity SDK** | 🥇 Tier 1 (Native) | Autonomous Agent SDK bindings and cryptographic provenance verification |
+
+> **Note**: Holmes-Kit focuses strictly on CLI-based autonomous agents to guarantee 100% deterministic OS hook gating (`deny` enforcement) before file modifications occur.
 
 ---
 

package/dist/.build-id

@@ -1 +1 @@
-acd8a7b-msxveq6c
+9337c9a-msytbtde

package/dist/holmes/cli/ci-gate.js

@@ -0,0 +1,103 @@
+"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.runCiGate = runCiGate;
+// @implements A-SPEC-213
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const pre_tool_use_1 = require("../hooks/pre-tool-use");
+const ignore_1 = require("../project/ignore");
+/**
+ * Headless CI/CD Governance Gate Runner for GitHub Actions / GitLab CI.
+ *
+ * @implements A-SPEC-213
+ */
+function runCiGate(targetDir, options) {
+    const root = path.resolve(targetDir);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return {
+            ok: false,
+            violations: [{ reason: `Target directory does not exist or is not a directory: ${root}` }],
+            summary: `[Holmes-Kit CI Gate Refusal] Target directory is invalid — ${root}`,
+        };
+    }
+    const specsDirName = options?.specsDir ?? (0, pre_tool_use_1.wiredSpecsDir)(process.argv, process.env);
+    const specsDir = path.resolve(root, specsDirName);
+    if (!(0, pre_tool_use_1.isGovernedProject)(specsDir, process.env)) {
+        return {
+            ok: true,
+            violations: [],
+            summary: `[Holmes-Kit CI Gate] Project is not governed (${specsDirName} absent) — skipping CI gate checks.`,
+        };
+    }
+    const ignore = (0, ignore_1.loadIgnore)(root);
+    const scanner = new cpg_scanner_1.CpgScanner();
+    const scannedFiles = scanner.scan(root, root);
+    const violations = [];
+    for (const sf of scannedFiles) {
+        const rel = path.relative(root, sf.path).split(path.sep).join('/');
+        if (ignore.isIgnored(rel))
+            continue;
+        // Check if scannable source file has no approved implements anchor
+        if (sf.implementsSpecs.length === 0) {
+            violations.push({
+                file: rel,
+                reason: `Missing line 1 // @implements anchor comment`,
+            });
+        }
+        if (sf.unanchoredImplements.length > 0) {
+            for (const wrongKind of sf.unanchoredImplements) {
+                violations.push({
+                    file: rel,
+                    specId: wrongKind,
+                    reason: `Invalid anchor kind @implements ${wrongKind} — only A-SPEC anchors are valid code implementation anchors`,
+                });
+            }
+        }
+    }
+    if (violations.length > 0) {
+        return {
+            ok: false,
+            violations,
+            summary: `[Holmes-Kit CI Gate Refusal] Governance Violations Detected — ${violations.length} un-anchored file(s) or invalid spec anchors found in PR commit range.`,
+        };
+    }
+    return {
+        ok: true,
+        violations: [],
+        summary: `[Holmes-Kit CI Gate Success] 100% Governance Conformance — All scanned files carry valid approved spec anchors.`,
+    };
+}

package/dist/holmes/cli/doctor.js

@@ -37,6 +37,7 @@ exports.STRIPPED_FOR_PROBE = void 0;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
 exports.formatChecks = formatChecks;
+// @implements A-SPEC-207
 // @implements A-SPEC-100.2
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -95,7 +96,7 @@ function wiredSettingsPath(target) {
         return (0, init_1.settingsPathOf)(target, 'project');
     return (0, init_1.settingsPathOf)(target, fs.existsSync((0, init_1.settingsPathOf)(target, 'local')) ? 'local' : 'project');
 }
-async function runDoctor(packageRoot, target, opts) {
+async function runDoctor(packageRoot, target, opts, extraChecks) {
     const checks = [];
     const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
     // 1. Build output — also the "prepare didn't run" detector.
@@ -451,6 +452,23 @@ async function runDoctor(packageRoot, target, opts) {
     }
     add('gate blind spots', 'PASS', (0, blind_spots_1.blindSpotSummary)());
     add('environment', 'PASS', present);
+    if (extraChecks) {
+        checks.push(...extraChecks);
+    }
+    if (opts?.autoFix) {
+        for (const c of checks) {
+            if ((c.level === 'FAIL' || c.level === 'WARN') && c.remediate) {
+                try {
+                    const ok = c.remediate();
+                    if (ok) {
+                        c.level = 'PASS';
+                        c.detail = `[REPAIRED] ${c.detail}`;
+                    }
+                }
+                catch { /* remediation failed */ }
+            }
+        }
+    }
     return checks;
 }
 /**

package/dist/holmes/cli/index.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.packageRoot = packageRoot;
 exports.main = main;
 // @implements A-SPEC-100.2
+// @implements A-SPEC-213
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const init_1 = require("./init");
@@ -69,6 +70,7 @@ const KNOWN_FLAGS = {
     init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent'],
     doctor: ['help', 'target', 'json'],
     skills: ['help', 'target'],
+    ci: ['help', 'target', 'specs-dir', 'json'],
 };
 class UnknownFlagError extends Error {
 }
@@ -290,6 +292,39 @@ async function main(argv) {
             process.stderr.write(`Could not refresh recovery skill ${skillLabel(f.name)}: ${f.reason}\n`);
         return r.failed.length > 0 ? 1 : 0;
     }
+    // @implements A-SPEC-213
+    if (cmd === 'ci') {
+        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 specsDir = typeof flags['specs-dir'] === 'string' ? flags['specs-dir'] : undefined;
+        if (specsDir !== undefined) {
+            if (path.isAbsolute(specsDir) || specsDir.split(/[\\/]/).includes('..') || specsDir.startsWith('~')
+                || /["'`$\\;&|<>\n\r]/.test(specsDir)) {
+                process.stderr.write(`--specs-dir ${specsDir} must be a plain relative path inside the target (no '..', no '~', no quotes or shell metacharacters)\n\n${USAGE}`);
+                return 2;
+            }
+        }
+        const target = typeof flags.target === 'string' ? flags.target : process.cwd();
+        const { runCiGate } = require('./ci-gate');
+        const res = runCiGate(target, { specsDir });
+        if (flags.json === true) {
+            process.stdout.write(JSON.stringify(res, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(res.summary + '\n');
+            for (const v of res.violations) {
+                const fileLabel = v.file ? ` [${v.file}]` : '';
+                const specLabel = v.specId ? ` (${v.specId})` : '';
+                process.stderr.write(`  - ${fileLabel}${specLabel}: ${v.reason}\n`);
+            }
+        }
+        return res.ok ? 0 : 1;
+    }
     if (cmd === 'init') {
         const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
         // 형제 열거 오류와 같은 모양(round 7): --settings·--target 은 USAGE 와 함께 exit 2 인데

package/dist/holmes/cpg/cpg-scanner.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CpgScanner = exports.isTestFile = exports.TEST_FILE_PATTERNS = exports.SCANNABLE_EXTENSIONS = exports.SKIP = void 0;
+// @implements A-SPEC-208
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const language_parser_1 = require("./language-parser");
@@ -206,7 +207,8 @@ class CpgScanner {
             }
         };
         walk(rootDir);
-        this.cache?.save(); // batched persist + mark-and-sweep prune, once per scan
+        const scopeRel = (0, source_path_1.toSourcePath)(repoRoot, rootDir);
+        this.cache?.save(scopeRel === '.' ? undefined : scopeRel); // batched persist + scoped mark-and-sweep prune
         return out;
     }
 }

package/dist/holmes/cpg/scan-cache.js

@@ -34,10 +34,26 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScanFileCache = exports.SCAN_CACHE_VERSION = void 0;
+// @implements A-SPEC-208
 // @implements A-SPEC-113.1
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_crypto_1 = require("node:crypto");
+function cloneExpr(e) {
+    if (!e)
+        return { text: '', refs: [], callees: [] };
+    return { text: e.text, refs: [...(e.refs ?? [])], callees: [...(e.callees ?? [])] };
+}
+function cloneDataFlow(df) {
+    if (!df)
+        return undefined;
+    return {
+        defs: (df.defs ?? []).map((d) => ({ ...d, expr: cloneExpr(d.expr) })),
+        calls: (df.calls ?? []).map((c) => ({ ...c, args: (c.args ?? []).map(cloneExpr) })),
+        params: (df.params ?? []).map((p) => ({ ...p })),
+        returns: (df.returns ?? []).map((r) => ({ ...r, expr: cloneExpr(r.expr) })),
+    };
+}
 // Bump on ANY change to symbol extraction, grammar versions, or the ScannedFile schema (review D3:
 // without a version stamp, cached entries kept serving OLD-parser symbols indefinitely after an
 // upgrade — content hashes match, so nothing else invalidates them). A mismatch drops the whole
@@ -75,7 +91,14 @@ class ScanFileCache {
             this.hits++;
             // Default array fields so an entry from a slightly older writer can never yield `undefined`
             // where a fresh scan yields [] (review D3b — downstream iterates these).
-            return { ...e.file, symbols: e.file.symbols ?? [], implementsSpecs: e.file.implementsSpecs ?? [], unanchoredImplements: e.file.unanchoredImplements ?? [] };
+            return {
+                ...e.file,
+                symbols: (e.file.symbols ?? []).map((s) => ({ ...s })),
+                implementsSpecs: [...(e.file.implementsSpecs ?? [])],
+                unanchoredImplements: [...(e.file.unanchoredImplements ?? [])],
+                edges: e.file.edges ? e.file.edges.map((edge) => ({ ...edge })) : undefined,
+                dataflow: cloneDataFlow(e.file.dataflow),
+            };
         }
         this.misses++;
         return undefined;
@@ -89,20 +112,29 @@ class ScanFileCache {
      * Persist once per scan. Mark-and-sweep: entries whose path was NOT seen this scan belong to
      * deleted/renamed files — pruned so the cache cannot grow unboundedly. No-op when nothing changed.
      */
-    save() {
-        const stale = Object.keys(this.entries).filter((p) => !this.seen.has(p));
+    save(scannedScopeDir) {
+        const scopePrefix = scannedScopeDir ? (scannedScopeDir.endsWith('/') ? scannedScopeDir : scannedScopeDir + '/') : undefined;
+        const stale = Object.keys(this.entries).filter((p) => {
+            if (this.seen.has(p))
+                return false;
+            // If a scoped directory was scanned, only prune stale entries within that directory
+            if (scopePrefix && p !== scannedScopeDir && !p.startsWith(scopePrefix))
+                return false;
+            return true;
+        });
         for (const p of stale) {
             delete this.entries[p];
             this.dirty = true;
         }
-        if (!this.dirty)
-            return;
         try {
-            fs.mkdirSync(this.dir, { recursive: true });
-            fs.writeFileSync(this.file, JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries }), 'utf8');
-            this.dirty = false;
+            if (this.dirty) {
+                fs.mkdirSync(this.dir, { recursive: true });
+                fs.writeFileSync(this.file, JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries }), 'utf8');
+                this.dirty = false;
+            }
         }
         catch { /* cache persistence is best-effort — next scan just runs colder */ }
+        this.seen.clear();
     }
 }
 exports.ScanFileCache = ScanFileCache;

package/dist/holmes/governance/provenance-ledger.js

@@ -105,8 +105,10 @@ class ProvenanceLedger {
         try {
             names = fs.readdirSync(this.dir);
         }
-        catch {
-            return [];
+        catch (err) {
+            if (err && err.code === 'ENOENT')
+                return [];
+            throw err;
         }
         const out = [];
         if (names.includes(LEGACY))
@@ -133,6 +135,12 @@ class ProvenanceLedger {
             }
         }).join('|');
     }
+    cloneEvents(events) {
+        return events.map((e) => ({
+            ...e,
+            inputs: e.inputs ? [...e.inputs] : undefined,
+        }));
+    }
     /**
      * Every event across every chain, ordered by `(ts, replicaId, seq)`.
      *
@@ -144,25 +152,18 @@ class ProvenanceLedger {
         const ch = this.chains();
         const key = this.computeMtimeKey(ch);
         if (this.indexCache && this.indexCache.key === key) {
-            return this.indexCache.events;
+            return this.cloneEvents(this.indexCache.events);
         }
         const out = [];
-        let fullyConsistent = true;
         for (const c of ch) {
-            try {
-                for (const e of new provenance_chain_1.ProvenanceChain(c.file).load())
-                    out.push({ ...e, replicaId: c.replicaId });
-            }
-            catch {
-                fullyConsistent = false;
+            for (const e of new provenance_chain_1.ProvenanceChain(c.file).load()) {
+                out.push({ ...e, replicaId: c.replicaId });
             }
         }
         const sortKey = (e) => `${e.ts} ${e.replicaId ?? ''} ${String(e.seq).padStart(12, '0')}`;
         out.sort((a, b) => (sortKey(a) < sortKey(b) ? -1 : sortKey(a) > sortKey(b) ? 1 : 0));
-        if (fullyConsistent) {
-            this.indexCache = { key, events: out };
-        }
-        return out;
+        this.indexCache = { key, events: out };
+        return this.cloneEvents(out);
     }
     /** Each chain verified on its own; one bad chain fails the whole ledger, and is named. */
     verifyAll() {

package/dist/holmes/rtm/heatmap.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRtmHeatmap = generateRtmHeatmap;
+/**
+ * Generate a standalone interactive HTML/SVG Heatmap Report for RTM Traceability & Taint Coverage.
+ *
+ * @implements A-SPEC-212
+ */
+function generateRtmHeatmap(specs, options) {
+    const safeSpecs = Array.isArray(specs) ? specs : [];
+    const totalSpecs = safeSpecs.length;
+    const coveredSpecs = safeSpecs.filter((s) => s && s.covered === true).length;
+    const coveragePct = totalSpecs > 0 ? Math.round((coveredSpecs / totalSpecs) * 100) : 0;
+    const title = options?.title ?? 'Holmes-Kit RTM & Security Taint Heatmap';
+    const isDark = options?.theme !== 'light';
+    const bgColor = isDark ? '#0f172a' : '#f8fafc';
+    const cardBg = isDark ? '#1e293b' : '#ffffff';
+    const textColor = isDark ? '#f8fafc' : '#0f172a';
+    const coveredBg = isDark ? '#065f46' : '#d1fae5';
+    const coveredText = isDark ? '#34d399' : '#065f46';
+    const uncoveredBg = isDark ? '#991b1b' : '#fee2e2';
+    const uncoveredText = isDark ? '#f87171' : '#991b1b';
+    const cellsHtml = safeSpecs
+        .map((s) => {
+        const isCovered = s && s.covered === true;
+        const bg = isCovered ? coveredBg : uncoveredBg;
+        const fg = isCovered ? coveredText : uncoveredText;
+        const cls = isCovered ? 'badge-covered' : 'badge-uncovered';
+        const statusLabel = isCovered ? 'COVERED' : 'UNCOVERED';
+        return `
+      <div class="card ${cls}" style="background-color: ${bg}; color: ${fg}; padding: 12px; border-radius: 8px; border: 1px solid rgba(255,255,255,0.1);">
+        <div style="font-weight: bold; font-size: 14px;">${escapeHtml(s?.id)}</div>
+        <div style="font-size: 12px; margin-top: 4px; opacity: 0.9;">${escapeHtml(s?.title)}</div>
+        <span style="display: inline-block; margin-top: 8px; font-size: 10px; font-weight: 800; text-transform: uppercase;">${statusLabel}</span>
+      </div>`;
+    })
+        .join('\n');
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; background-color: ${bgColor}; color: ${textColor}; margin: 0; padding: 24px; }
+    .header { margin-bottom: 24px; border-bottom: 1px solid rgba(255,255,255,0.1); padding-bottom: 16px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 12px; }
+    .stat-badge { font-size: 32px; font-weight: 800; color: ${coveragePct >= 80 ? '#10b981' : coveragePct >= 50 ? '#f59e0b' : '#ef4444'}; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>🔍 ${escapeHtml(title)}</h1>
+    <div>Specification Coverage: <span class="stat-badge">${coveragePct}%</span> (${coveredSpecs} / ${totalSpecs} Specs Covered)</div>
+  </div>
+  <div class="grid">
+    ${cellsHtml}
+  </div>
+</body>
+</html>`;
+    return { html, coveragePct, totalSpecs, coveredSpecs };
+}
+function escapeHtml(val) {
+    return String(val ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}

package/package.json

@@ -1,6 +1,7 @@
 {
+  "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "bin": {