@holmes-lab/holmes-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2026-08-18
+
+### Added
+- **26 Atomic MCP Tools**: Full suite of MCP tools including `spec_create`, `spec_approve`, `spec_validate`, `spec_list`, `cpg_scan`, `taint_scan`, `rtm_impact`, `context_bundle`, `reverse_scan`, `reverse_draft`, `reverse_anchor`, and `issue_localize`.
+- **Multilingual CPG & Taint Analysis**: Tree-sitter CPG parsers and dataflow reachability engines supporting 7 languages (TypeScript, Python, Java, Go, Rust, C++, C#).
+- **No-Spec-No-Code Gating**: PreToolUse and Stop hooks enforcing strict specification chain (`REQ → H-SPEC → A-SPEC → T-SPEC → Code`) with cryptographic digests.
+- **Centralized Message Registry**: 3-part structured English messages (`[Subsystem] Title — Technical Cause — Next Action`) via `src/holmes/messages/registry.ts`.
+- **System Health Diagnostics**: Automated 8-point health check command (`holmes-kit doctor`).
+- **Brownfield Adoption Toolchain**: Legacy code reverse-engineering and spec recovery via `holmes-adopt` playbook.
+
+### Security
+- **Subprocess Secret Isolation (REQ-194)**: Forcibly scrub `HOLMES_APPROVAL` and `HOLMES_LEDGER_KEY` from all subshell and child process environments spawned by `run_command` and `execFileSync`.
+- **Cryptographic Content Seals**: Cryptographic SHA-256 digest sealing for approved specifications and tamper-evident ledgers.
+- **Adversarial Hardening (REQ-189 ~ REQ-193)**: Schema typo validation (`validate-args`), path traversal containment, and symlink wall protection against out-of-bounds file edits.
+- **Internal Spec ID Masking (REQ-195)**: Mask internal harness Spec IDs in runtime refusal output while preserving target project Spec IDs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holmes-Kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# 🔍 Holmes-Kit
+
+[![npm version](https://img.shields.io/npm/v/holmes-kit.svg)](https://www.npmjs.com/package/holmes-kit)
+[![node version](https://img.shields.io/node/v/holmes-kit.svg)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Deterministic Agentic Software Engineering (ASE) harness with causal traceability.**
+
+Holmes-Kit is not just a coding assistant — it is a **deterministic control plane** that governs how AI agents build software, so that every line of code is causally traceable back to a requirement, a design, and a decision ("who, when, why"). The governance is enforced in code (not prompts), so an agent cannot rationalize its way past it.
+
+> Detective, not autocomplete: like Sherlock Holmes, the harness reasons from evidence — requirements → design → code → tests → decisions — over an exact causal graph, not probabilistic guesses.
+
+## Core Ideas
+
+- **Deterministic control plane** — governance/traceability live in code; the LLM is advisory. Phase gating, RTM integrity, and impact analysis are exact queries, never approximations.
+- **Governance spec chain** — `REQ → H-SPEC → A-SPEC → C-SPEC → T-SPEC`, plus a runtime `JOB` ledger. Code anchors to its A-SPEC via `@implements A-SPEC-NNN`.
+- **Phase guardrail (block-and-redirect)** — the current SE phase is *derived from graph state*, not a mutable flag. Out-of-phase actions (e.g. writing code with no approved A-SPEC/T-SPEC) are blocked and the agent is redirected to the correct next step.
+- **D-CPG + RTM** — tree-sitter Code Property Graph + SQLite RTM graph (recursive-CTE reachability). `rtm_impact` answers "which specs does changing this symbol affect?" — the core of causal traceability.
+- **Hexagonal Ports & Adapters** — local Markdown today, enterprise adapters (DB/JIRA/Confluence) later, with no core rework.
+- **Decision provenance** — architecture decisions are recorded as ADRs and linked into the graph.
+
+## Requirements & Prerequisites
+
+- **Node.js**: `>= 20.0.0` (Enforced via `.npmrc`)
+- **C++ Build Toolchain**: Xcode Command Line Tools (`xcode-select --install` on macOS) or `build-essential` / `g++` / `make` (Linux) for native `better-sqlite3` and `tree-sitter` C++ Addon compilation.
+
+## Installation & Setup
+
+### 1. Installation
+
+#### Option A: Direct Git Release Installation (v0.1.1)
+
+```bash
+# Global CLI install with allowed native C++ build scripts
+npm install -g --allow-scripts=better-sqlite3,tree-sitter,tree-sitter-c-sharp,tree-sitter-cpp,tree-sitter-go,tree-sitter-java,tree-sitter-python,tree-sitter-rust,tree-sitter-typescript \
+  "git+https://github.com/snpark-io/holmes-kit.git#v0.1.1"
+
+# Verify installation health
+holmes-kit doctor
+```
+
+#### Option B: Clean 1-Line Installation via NPM Registry
+
+```bash
+# Once published to npm registry:
+npm install -g holmes-kit
+
+# Verify health
+holmes-kit doctor
+```
+
+### 2. Project Initialization
+
+```bash
+cd /path/to/your/project
+holmes-kit init --dry-run     # Preview configuration without writing
+holmes-kit init               # Wire Holmes-Kit hooks into target project
+```
+
+### 3. MCP Integration
+
+Add Holmes-Kit as an MCP server in your editor or agent environment (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "holmes-kit": {
+      "command": "npx",
+      "args": ["-y", "holmes-mcp"]
+    }
+  }
+}
+```
+
+### 4. Environment Variables (Optional)
+
+```bash
+cp .env.example .env
+# Edit .env and fill in your values
+```
+
+## Status
+
+Under active development on branch `feat/holmes-kit-ase-design`.
+
+- **v0.1** — spec standard + MCP guardrail (spec validation, `rtm_check`, phase guardrail, MCP server, hook).
+- **v0.2** — D-CPG + RTM traceability (tree-sitter symbols/edges, CPG scanner, RTM graph, change-impact, MCP `cpg_scan`/`rtm_impact`). Dogfooded on Holmes-Kit's own source.
+
+Target architecture and design records live in [`docs/architecture/`](docs/architecture/) and decisions in [`.ax/decisions/`](.ax/decisions/).
+
+## Build & Test
+
+```bash
+npm install
+npm run typecheck  # TypeScript static type check
+npm run build      # tsc → dist/holmes/**
+npm test           # jest full test suite
+```
+
+## License
+
+MIT

package/bin/holmes-hook-antigravity.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// @implements A-SPEC-193
+// Antigravity PreToolUse 진입점 — 번역만 한다. 판정은 dist 의 훅 프로그램이 내린다.
+//
+// 가드는 require 앞에서 Node 내장만으로 돈다(bin/holmes-kit.js 와 같은 이유). 그리고 가드가
+// 걸렸을 때 **열지 않는다**: 게이트를 세우라고 배선해 둔 훅이 실행되지 못했다면 그것은 허용이
+// 아니라 거부다 — 조용히 여는 것이 이 저장소가 반복해서 고쳐 온 실패 유형이다.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const deny = (reason) => {
+  process.stdout.write(JSON.stringify({ decision: 'deny', reason }));
+  process.exit(0);
+};
+
+const entry = path.join(__dirname, '..', 'dist', 'holmes', 'hooks', 'adapters', 'antigravity.js');
+if (!fs.existsSync(entry)) {
+  deny(`[Holmes-Kit] 빌드 산출물이 없습니다: ${entry} — 게이트를 세울 수 없어 허용하지 않습니다.`
+    + ' 저장소에서 쓰는 중이라면 `npm run build`, 설치본이라면 재설치하십시오.');
+}
+
+let buf = '';
+process.stdin.on('data', (c) => { buf += c; });
+process.stdin.on('end', () => {
+  try {
+    const { adaptPreToolUse } = require(entry);
+    process.stdout.write(JSON.stringify(adaptPreToolUse(buf, process.cwd())));
+  } catch (e) {
+    deny(`[Holmes-Kit] 게이트를 실행하지 못했습니다: ${e && e.message ? e.message : String(e)}`);
+  }
+});

package/bin/holmes-kit.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// @implements A-SPEC-100.2
+// @implements A-SPEC-173
+// The guard runs BEFORE the require, using only Node built-ins. `runInit` carries the same guidance
+// but lives inside `dist` — measured 2026-08-12, a package whose `prepare` was blocked emitted
+// `node:internal/modules/cjs/loader` from every entry point and that guidance never ran.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const entry = path.join(__dirname, '..', 'dist', 'holmes', 'cli', 'index.js');
+if (!fs.existsSync(entry)) {
+  process.stderr.write(
+    `holmes-kit is not built: ${entry} is missing.\n`
+    + 'The package ships compiled output via its `prepare` script, which npm may have blocked.\n'
+    + 'Check `npm config get ignore-scripts` and `npm config get omit`, then reinstall.\n'
+    + 'Native dependencies need `npm i <pkg> --allow-scripts` on npm 11+.\n');
+  process.exit(1);
+}
+
+require('../dist/holmes/cli/index.js')
+  .main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => { process.stderr.write(`${err && err.stack ? err.stack : err}\n`); process.exit(1); });

package/bin/holmes-mcp.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// @implements A-SPEC-162
+// @implements A-SPEC-173
+// The guard runs BEFORE the require, using only Node built-ins — see bin/holmes-kit.js. The wording
+// is duplicated rather than shared: reading it from `dist` is exactly the dependency that fails here.
+// `bin-guard.test.ts` pins the two copies to each other so they cannot drift.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const entry = path.join(__dirname, '..', 'dist', 'holmes', 'mcp', 'supervisor.js');
+if (!fs.existsSync(entry)) {
+  // stderr, never stdout: stdout is the JSON-RPC channel and a diagnostic written there would be
+  // read as a malformed protocol message rather than as advice.
+  process.stderr.write(
+    `holmes-kit is not built: ${entry} is missing.\n`
+    + 'The package ships compiled output via its `prepare` script, which npm may have blocked.\n'
+    + 'Check `npm config get ignore-scripts` and `npm config get omit`, then reinstall.\n'
+    + 'Native dependencies need `npm i <pkg> --allow-scripts` on npm 11+.\n');
+  process.exit(1);
+}
+
+// Opt-in only. Without HOLMES_MCP_AUTORELOAD this is the same direct require it has always been —
+// swapping the implementation under a shipped user mid-session would be an undeclared change in gate
+// behaviour, which ADR-013 forbids.
+const { AUTORELOAD_ENV, autoreloadEnabled, Supervisor } = require('../dist/holmes/mcp/supervisor.js');
+
+if (autoreloadEnabled(process.env)) {
+  const sup = new Supervisor(path.resolve(__dirname, '..'), (from, to, replayed) =>
+    process.stderr.write(`[Holmes-Kit] MCP 서버 구현을 교체했습니다: ${from} → ${to} (replayed=${replayed})\n`));
+  sup.start(process.stdin, process.stdout);
+  process.on('exit', () => sup.stop());
+} else {
+  require('../dist/holmes/mcp/server.js');
+}

package/bin/holmes-stop-antigravity.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// @implements A-SPEC-193
+// Antigravity Stop 진입점 — 번역만 한다. 판정은 dist 의 Stop 훅이 내린다.
+//
+// PreToolUse 와 달리 여기서는 실패가 **열어 준다**. Stop 훅은 이미 fail-open 계약이다: 턴을
+// 죽이지 않는다. 정지를 막지 못하는 것은 규율의 손실이고, 정지를 막아 놓고 이유를 대지 못하는
+// 것은 사용자를 가두는 것이다 — 둘 중 후자가 더 나쁘다.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const pass = () => { process.stdout.write('{}'); process.exit(0); };
+
+const entry = path.join(__dirname, '..', 'dist', 'holmes', 'hooks', 'adapters', 'antigravity.js');
+if (!fs.existsSync(entry)) {
+  process.stderr.write(`[Holmes-Kit] 빌드 산출물이 없습니다: ${entry}\n`);
+  pass();
+}
+
+let buf = '';
+process.stdin.on('data', (c) => { buf += c; });
+process.stdin.on('end', () => {
+  try {
+    const { adaptStop } = require(entry);
+    process.stdout.write(JSON.stringify(adaptStop(buf, process.cwd())));
+  } catch (e) {
+    process.stderr.write(`[Holmes-Kit] Stop 게이트를 실행하지 못했습니다: ${e && e.message ? e.message : String(e)}\n`);
+    pass();
+  }
+});

package/dist/.build-id

@@ -0,0 +1 @@
+e26507b-msxetwff

package/dist/holmes/cli/agents.js

@@ -0,0 +1,168 @@
+"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.HARNESS_ENFORCES = exports.AGENTS = void 0;
+exports.agentFiles = agentFiles;
+exports.agentLinks = agentLinks;
+// @implements A-SPEC-193
+const path = __importStar(require("node:path"));
+/**
+ * 하네스별 배선물.
+ *
+ * Holmes-Kit 의 명제("승인된 스펙 없이는 코드가 들어가지 않는다")를 **집행**하는 것은 MCP
+ * 도구가 아니라 훅이다. 그래서 하네스마다 물어야 할 첫 질문은 "이 도구에 훅이 있는가"이고,
+ * 없다면 **집행한다고 말하지 않는 것**이 이 파일의 일이다. 도구는 주되 규율은 못 세우면서
+ * 세운다고 적으면, 그 문장을 믿은 사용자가 지켜지지 않는 게이트 위에서 일한다.
+ */
+exports.AGENTS = ['claude', 'antigravity', 'codex'];
+/**
+ * 그 하네스에서 게이트가 **집행되는가**.
+ *
+ * - `claude` — PreToolUse/Stop 훅. 이 저장소가 처음부터 배선해 온 하네스.
+ * - `antigravity` — PreToolUse/Stop 훅이 있고 `deny`/`continue` 로 막을 수 있다(설치본의
+ *   `agy-customizations` 규약 문서와 실제 대화 기록에서 실측).
+ * - `codex` — 이 기계에 설치되어 있지 않아 훅 규약을 **재지 못했다**. 재지 못한 것을 있다고
+ *   적지 않는다. 도구(MCP)와 지침만 준다.
+ */
+exports.HARNESS_ENFORCES = {
+    claude: true,
+    antigravity: true,
+    codex: false,
+};
+const q = (p) => p;
+const mcpConfig = (packageRoot, specsDir) => `${JSON.stringify({
+    mcpServers: {
+        'holmes-kit': {
+            command: 'node',
+            args: [q(path.join(packageRoot, 'bin', 'holmes-mcp.js'))],
+            env: { HOLMES_SPECS: specsDir },
+        },
+    },
+}, null, 2)}\n`;
+/**
+ * Antigravity 훅 배선.
+ *
+ * 매처는 `*` 다. 좁히면 그 밖의 도구가 게이트를 지나가고, Antigravity 의 도구 목록은 우리가
+ * 통제하지 않는다 — 이름을 열거하는 순간 다음에 추가되는 도구가 무료 통행권을 얻는다.
+ * (Claude 배선이 `guardrail` 모드에서 좁은 매처를 쓰는 것과 다른 선택인데, 그쪽은 그 좁힘이
+ * 무엇을 뜻하는지 문서화된 모드 선택이고 여기는 기본 배선이기 때문이다.)
+ */
+const hooksJson = (packageRoot) => `${JSON.stringify({
+    'holmes-kit': {
+        PreToolUse: [{
+                matcher: '*',
+                hooks: [{
+                        type: 'command',
+                        command: `node ${path.join(packageRoot, 'bin', 'holmes-hook-antigravity.js')}`,
+                        timeout: 30,
+                    }],
+            }],
+        Stop: [{
+                type: 'command',
+                command: `node ${path.join(packageRoot, 'bin', 'holmes-stop-antigravity.js')}`,
+                timeout: 30,
+            }],
+    },
+}, null, 2)}\n`;
+const AGENTS_MD = (enforced) => `# Holmes-Kit — 이 저장소의 작업 규율
+
+이 저장소는 **No Spec, No Code** 로 운영된다. 코드를 쓰기 전에 승인된 스펙이 있어야 한다.
+
+## 절차
+
+1. \`spec_create\` 로 REQ → H-SPEC → A-SPEC 을 쓰고 \`spec_approve\` 로 승인한다.
+2. **테스트를 먼저** 쓰고 실패(RED)를 확인한다.
+3. T-SPEC 을 승인한다(거울 규약: \`A-SPEC-188\` → \`T-SPEC-188\`).
+4. 그 다음에 구현한다.
+
+\`spec_next\` 가 다음에 할 일을 말해 준다. \`phase_check\` 로 지금 하려는 행동이 허용되는지
+미리 물을 수 있다.
+
+## 이 하네스에서의 집행
+
+${enforced
+    ? `게이트가 **집행된다**. 승인된 스펙 없이 코드를 쓰려 하면 도구 호출이 거부되고, 해소되지
+않은 치명 발견이 있으면 턴이 끝나지 않는다. 거부 문면이 다음에 무엇을 하면 되는지 말한다.`
+    : `이 하네스에는 우리가 실측한 **훅 집행 지점이 없다**. 그래서 Holmes-Kit 은 여기서 도구와
+지침만 제공하고 **게이트를 집행하지 않는다** — 규율은 조언으로만 선다. 집행이 필요하면 Claude
+Code 나 Antigravity 하네스에서 작업하라. (이 문장은 우리가 그 도구의 훅 규약을 재지 못했다는
+사실의 기록이지, 그 도구에 훅이 없다는 단정이 아니다.)`}
+`;
+/**
+ * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
+ *
+ * 계산과 쓰기를 나누는 이유는 dry-run 이 실제 실행과 같은 집합을 예고해야 하기 때문이다
+ * (A-SPEC-190 §9). 같은 함수가 두 경로에 답하면 둘이 어긋날 수 없다.
+ */
+function agentFiles(agent, opts) {
+    const { target, packageRoot, specsDir } = opts;
+    switch (agent) {
+        case 'claude':
+            // Claude 배선은 init 이 이미 쓴다(settings*, .mcp.json, .claude/skills) — 여기서 겹쳐
+            // 쓰면 그것이 두 번째 진실이 된다.
+            return [];
+        case 'antigravity':
+            return [
+                { path: path.join(target, '.agents', 'hooks.json'), content: hooksJson(packageRoot) },
+                { path: path.join(target, '.agents', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir) },
+                { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.antigravity) },
+            ];
+        case 'codex':
+            return [
+                { path: path.join(target, '.codex', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir) },
+                { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.codex) },
+            ];
+        default:
+            // 모르는 하네스를 조용히 건너뛰면 "배선했다"는 보고와 실제가 어긋난다.
+            throw new Error(`알 수 없는 하네스: ${String(agent)} — 아는 것: ${exports.AGENTS.join(', ')}`);
+    }
+}
+/**
+ * 하네스가 스킬을 **볼 수 있게** 하는 링크.
+ *
+ * 스킬 본문은 한 곳(`.claude/skills`)에만 둔다 — 같은 내용을 두 벌 두면 하나가 갱신될 때
+ * 다른 하나가 낡고, doctor 는 한쪽만 본다(그 드리프트가 REQ-190 의 출발점이었다). 그래서
+ * Antigravity 쪽은 링크로 같은 파일을 가리킨다. 이 배치는 타깃 안에 머물므로 설치 담장을
+ * 지나간다(A-SPEC-193 §7 이 그 담장을 '타깃 밖만'으로 좁힌 이유이기도 하다).
+ */
+function agentLinks(agent, opts) {
+    if (agent !== 'antigravity')
+        return [];
+    return [{
+            path: path.join(opts.target, '.agents', 'skills'),
+            target: path.join('..', '.claude', 'skills'),
+            why: '스킬 본문은 .claude/skills 한 곳에 둔다 — 두 벌이면 하나가 낡는다',
+        }];
+}