@holmes-lab/holmes-kit 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.3.4] - 2026-09-01
+
+Docs: a friendly, accurate setup guide for the opt-in semantic tiers.
+
+### Added
+
+- README Quickstart step 4: enabling the semantic layer — tier `local` (install
+  `@xenova/transformers`, no egress) and tier `cloud` (`gemini-embedding-001`): get a key from
+  Google AI Studio, store it out-of-tree via `holmes-kit semantic-key set` (stdin-only, 0600 /
+  macOS keychain, value never printed), env-var alternatives for CI
+  (`HOLMES_SEMANTIC_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY`), revocation via
+  `semantic-key unset`, and the security stance (no project-tree key source; agent
+  self-consent is gated).
+
+### Internal (measurement plumbing, no default-path change)
+
+- `alignExcerpt` request-aligned excerptor + `dumpBodies.mode` (A-SPEC-500.1) — feeds the
+  judgment-precision experiment REQ-500; default excerpts stay byte-identical.
+
+<!-- @implements A-SPEC-209 -->
+## [0.3.3] - 2026-08-31
+
+Docs-only: the README the npm page shows catches up with 0.3.x.
+
+### Changed
+
+- README rewritten to 0.3.x: the 3-tier semantic layer (consent ladder + measured recalls), the
+  graded impact surface and its pre-registered baselines, the measured-not-claimed grading against
+  the modeled-human band (independent blind-judge P 0.727 = 81% of the band), approval-dialog
+  expiry visibility, the corrected Codex wiring path (`.codex/config.toml`), the Windows row
+  corrected from a CI claim to the 2026-08-31 field validation, a zero-install `npx` one-shot row,
+  and the stale-global-shim shadowing warning (field-measured dual global roots on Windows).
+  No code changes.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.2] - 2026-08-31
 

package/README.md

@@ -14,11 +14,15 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.1.x Production Features)
+### 🛡️ Currently Supported Features (v0.3.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.
+- 🧠 **3-Tier Semantic Layer** *(new in 0.3.0)*: knowledge-graph semantic search with an explicit consent ladder — `none` (default, **zero egress**), `local` (bge-m3, no egress, optional module), `cloud` (gemini-embedding-001, opt-in via `GEMINI_API_KEY`). Measured on 305 traceability cases: recall 0.486 (lexical) → 0.667 (local) → **0.887 (cloud)**; on lexical-zero requests: 0% → 52% → **92%**. Surfaced only additively — rerank, evidence (`semCos`), and `semanticAlternates` — never as a hard filter.
+- 🎯 **Graded Impact Surface** *(new in 0.3.0)*: `rankedImpact` (personalized-PageRank over the spec/code graph) beat its pre-registered naive baseline on **both recall and precision across 3 corpora (×1.6–×17)** — the necessary condition for any better-than-a-person phrasing, measured before claimed.
 - 🐞 **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`).
+- 📏 **Measured, Not Claimed** *(new in 0.3.x)*: performance is judged against a pre-registered modeled-human band (R 0.67–0.78 / P ≈0.9±). Current official grade: **band entry on recall; division-of-labor precision 0.727 = 81% of the modeled human — reproduced by an independent context-free judge on a fresh blind window.** No superhuman claims until both metrics exceed the band.
+- 🧪 **Self-Healing & Diagnostic Doctor**: Automated integrity checks and self-healing auto-fix remediation (`holmes-kit doctor --fix` & `spec_remediate`) — wiring-handshake checks run on Windows natively as of 0.3.2.
+- 🔔 **Approval UX** *(new in 0.3.1)*: in-session approval dialogs forewarn their 120s deadline and, on expiry, the refusal says exactly where the decision went (`npx holmes-kit approve` out-of-band queue) — no more silently dead dialogs.
 - 🚦 **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.
@@ -42,7 +46,7 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 | :--- | :--- | :--- |
 | 🤖 **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 |
+| 💻 **Codex CLI / Agentic Shell** | 🥇 Tier 1 (Native) | Codex MCP integration (`.codex/config.toml`), plugin-packaged gate hooks (installed via Codex plugin marketplace) |
 | 🧩 **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.
@@ -69,10 +73,18 @@ Add `-DryRun` to see what it would do without installing. Exit codes: `0` ok / a
 | Which situation are you in? | Privileges | Command |
 |---|---|---|
 | **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` |
+| **Zero-install one-shot** (try it first) | none | `npx -y @holmes-lab/holmes-kit init` — npx fetches and runs, nothing to install beforehand |
 | Company-managed PC / restricted account | none | same — no system directory is touched |
 | CI / container | none | same, plus `--prefer-online` right after a release |
 | CLI across many projects (`-g`) | depends | run `npm config get prefix` first — see below |
 
+**Stale global shadowing** *(field-measured on Windows, 2026-08-31)*: an old global install makes the
+bare `holmes-kit` command run the OLD version while `npx holmes-kit` runs the local one — and
+Windows has TWO global roots (`C:\Program Files\nodejs` and `%APPDATA%\npm`), so `npm uninstall -g`
+against one root can leave a live shim in the other. If `holmes-kit --version` and
+`npx holmes-kit --version` disagree, run `where.exe holmes-kit` (Windows) / `which -a holmes-kit`
+and remove the stale shim; prefer the `npx` form day-to-day.
+
 **Before `npm install -g`**: if `npm config get prefix` names a protected directory
 (`C:\Program Files\nodejs`, `/usr/local`), `-g` dies with `EPERM` **before any package file
 arrives** — no package version can fix that, and elevation is the wrong fix (it runs native
@@ -96,7 +108,7 @@ npx holmes-kit init      # drop the npx prefix if you installed with -g
 ? Select the AI Agent harnesses to wire into this project:
   [X] 🤖 Claude Code          (.claude/settings.local.json, .mcp.json)
   [X] 🚀 Antigravity CLI (AGY) (.agents/mcp_config.json, hooks.json, skills)
-  [ ] 💻 Codex CLI            (.codex/mcp_config.json)
+  [ ] 💻 Codex CLI            (.codex/config.toml)
 ```
 
 ### 3. Verify Health
@@ -105,6 +117,46 @@ npx holmes-kit doctor
 ```
 *If everything is green, your project is governed and ready for AI pair-programming!*
 
+### 4. Optional: Enable the Semantic Layer (Tier `local` / Tier `cloud`)
+
+Out of the box Holmes-Kit runs tier **`none`** — lexical + citation + graph search, **zero
+egress**. Two opt-in tiers raise recall on requests your vocabulary can't reach (measured on 305
+traceability cases — see the feature list above):
+
+**Tier `local` — no egress, no account.** Install the optional embedding runtime next to
+holmes-kit and the local model (`bge-m3`) is picked up automatically:
+```bash
+npm install --save-dev @xenova/transformers
+npx holmes-kit doctor        # → semantic tier: local (no egress)
+```
+
+**Tier `cloud` — highest recall, explicit consent (`gemini-embedding-001`).** Setting a key IS
+the consent act: with a key present, repository-derived text is sent to Google's embedding API.
+
+1. Get a Gemini API key (Google AI Studio → <https://aistudio.google.com/apikey>; the free tier
+   is enough to try it).
+2. Store it **outside your project tree** with the built-in command — the key rides **stdin,
+   never argv**, lands in `~/.holmes/credentials.json` with `0600` permissions, and no output
+   ever contains the value:
+   ```bash
+   npx holmes-kit semantic-key set        # hidden prompt on a TTY; or:  echo "$KEY" | npx holmes-kit semantic-key set
+   npx holmes-kit semantic-key status     # shows the key's SOURCE only, never the value
+   npx holmes-kit doctor                  # → semantic tier: cloud (egress: on)
+   ```
+   On macOS the key prefers the system keychain; elsewhere the `0600` file is the store.
+   Environment variables also work and take precedence (`HOLMES_SEMANTIC_API_KEY` dedicated, or
+   the ecosystem-compatible `GEMINI_API_KEY` / `GOOGLE_API_KEY`) — useful for CI. Prefer
+   `semantic-key set` on workstations: it keeps the key out of shell history, `.env` files, and
+   the repository.
+3. To revoke consent at any time:
+   ```bash
+   npx holmes-kit semantic-key unset      # clears the stored key; tier falls back to local/none
+   ```
+
+> 🔒 **Never** commit a key, pass it as a CLI argument, or put it in a file inside the project
+> tree. Holmes-Kit's credential chain has **no project-tree source by design**, and agents are
+> gated from setting keys on their own — consent stays a human act.
+
 ---
 
 ## 🔄 Daily Workflow (How It Works)
@@ -181,11 +233,11 @@ Holmes-Kit embeds native AST & Code Property Graph (D-CPG) analyzers to track ca
 | **macOS** | Apple Silicon (arm64) / Intel (x64) | ✅ Tier 1 | macOS 12+ (Full hook enforcement) |
 | **Linux** | x86_64 / arm64 | ✅ Tier 1 | Ubuntu, Debian, Fedora, Arch, RHEL |
 | **Windows (WSL2)** | x86_64 | ✅ Tier 1 | WSL2 Ubuntu/Debian recommended |
-| **Windows Native** | x86_64 | ✅ Tier 1 | Windows 10/11 (Node.js 20+ with C++ build tools). Gate parity verified from CI — see [ADR-015](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md) for the graduation criteria and the residual risks (NTFS 8.3 names, reserved device names, 260-char paths) |
+| **Windows Native** | x86_64 | ✅ Tier 1 | Windows 10/11 (Node.js 20+; prebuilt natives, no build tools needed in the common case). **Field-validated 2026-08-31** on a real user machine: registry install, natives (better-sqlite3 + 7 tree-sitter grammars), both OS gates, MCP handshake (30 tools), interactive init TUI, out-of-band approval channel (doctor 25 PASS; the 4 false FAILs it also showed were doctor's own win32 spawn bug, fixed in 0.3.2). See ADR-015 (platform tier is decided by executed verification — internal decision record) for tier criteria and residual risks (NTFS 8.3 names, reserved device names, 260-char paths; no Windows CI yet) |
 
 > **Runtime Requirement**: Node.js `>= 20.0.0` (LTS recommended)
 >
-> **How a tier is decided**: by the verification that actually executes, not by declaration. A platform is Tier 1 only while its gate verdicts are exercised by the suite; if that stops being true it is demoted and the demotion is recorded. See [ADR-015](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md).
+> **How a tier is decided**: by the verification that actually executes, not by declaration. A platform is Tier 1 only while its gate verdicts are exercised by the suite; if that stops being true it is demoted and the demotion is recorded. See ADR-015 (platform tier is decided by executed verification — internal decision record).
 
 ---
 

package/dist/.build-id

@@ -1 +1 @@
-5010ff8-mthc0xla
+68b5982-mthe8y11

package/dist/holmes/review/excerpt-align.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Request-aligned excerpting for the judgment-measurement dump. The excerpt ladder
+ * (S-505→S-516) showed excerpt information content DOMINATES the agent-judge's precision, and
+ * the shipped head-slice starves the judge exactly when the relevant region sits mid-file —
+ * imports and module prose fill the window and the judge degrades to filename guessing.
+ *
+ * The alignment is deliberately dumb and PURE: slide a chars-wide window at half-stride and keep
+ * the one containing the most DISTINCT request tokens (presence, not frequency — one dense
+ * mention must not outvote three different matched concepts). Ties keep the EARLIEST window and
+ * zero overlap falls back to the head slice, so where there is no signal the behavior is
+ * byte-identical to the status quo. Every return is a verbatim substring — the judge must only
+ * ever see real code.
+ */
+export declare function alignExcerpt(text: string, request: string, chars: number): string;

package/dist/holmes/review/excerpt-align.js

@@ -0,0 +1,51 @@
+"use strict";
+// @implements A-SPEC-500.1
+/**
+ * Request-aligned excerpting for the judgment-measurement dump. The excerpt ladder
+ * (S-505→S-516) showed excerpt information content DOMINATES the agent-judge's precision, and
+ * the shipped head-slice starves the judge exactly when the relevant region sits mid-file —
+ * imports and module prose fill the window and the judge degrades to filename guessing.
+ *
+ * The alignment is deliberately dumb and PURE: slide a chars-wide window at half-stride and keep
+ * the one containing the most DISTINCT request tokens (presence, not frequency — one dense
+ * mention must not outvote three different matched concepts). Ties keep the EARLIEST window and
+ * zero overlap falls back to the head slice, so where there is no signal the behavior is
+ * byte-identical to the status quo. Every return is a verbatim substring — the judge must only
+ * ever see real code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alignExcerpt = alignExcerpt;
+const tokensOf = (request) => {
+    const seen = new Set();
+    for (const m of request.toLowerCase().match(/[a-z0-9_$가-힣]+/g) ?? []) {
+        if (m.length >= 3)
+            seen.add(m);
+    }
+    return [...seen];
+};
+function alignExcerpt(text, request, chars) {
+    if (text.length <= chars)
+        return text;
+    const tokens = tokensOf(request);
+    const head = text.slice(0, chars);
+    if (tokens.length === 0)
+        return head;
+    const stride = Math.ceil(chars / 2);
+    let best = head;
+    let bestCount = 0;
+    for (let at = 0; at < text.length; at += stride) {
+        const window = text.slice(at, at + chars);
+        const lower = window.toLowerCase();
+        let count = 0;
+        for (const t of tokens)
+            if (lower.includes(t))
+                count++;
+        if (count > bestCount) {
+            bestCount = count;
+            best = window;
+        }
+        if (at + chars >= text.length)
+            break;
+    }
+    return bestCount === 0 ? head : best;
+}

package/dist/holmes/review/run-replay.d.ts

@@ -241,6 +241,8 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
         chars: number;
         /** @implements A-SPEC-490 — drop leading license blocks before excerpting; default false keeps S-507 bytes. */
         skipLicense?: boolean;
+        /** @implements A-SPEC-500.1 — 'aligned' excerpts the request-densest window instead of the head; default 'head' keeps prior bytes. */
+        mode?: 'head' | 'aligned';
     };
 }): Promise<ReplayResult>;
 /**

package/dist/holmes/review/run-replay.js

@@ -64,6 +64,7 @@ const localize_1 = require("../rtm/localize");
 // @implements A-SPEC-483 — content-level verification: the candidate's BODY, read from the
 // materialized parent tree.
 const content_verify_1 = require("./content-verify");
+const excerpt_align_1 = require("./excerpt-align");
 // @implements A-SPEC-467 — the associative-recall arm: measured beside the product, never inside it.
 const assoc_arm_1 = require("../assoc/assoc-arm");
 // @implements A-SPEC-470 — the impact axis's Phase-B external yardstick, always scored.
@@ -265,7 +266,11 @@ async function runReplay(corpus, limit, opts = {}) {
                                 const raw = fs.readFileSync(path.join(dest, f), 'utf8');
                                 // @implements A-SPEC-490 — the informative excerpt: license blocks first, then cut.
                                 const text = opts.dumpBodies.skipLicense === true ? (0, content_verify_1.skipLicenseHeader)(raw) : raw;
-                                bodies[f] = text.slice(0, opts.dumpBodies.chars);
+                                // @implements A-SPEC-500.1 — 'aligned' picks the request-densest window; the
+                                // default stays the head slice, byte-identical to the pre-mode path.
+                                bodies[f] = opts.dumpBodies.mode === 'aligned'
+                                    ? (0, excerpt_align_1.alignExcerpt)(text, c.subject, opts.dumpBodies.chars)
+                                    : text.slice(0, opts.dumpBodies.chars);
                             }
                             catch { /* unreadable candidate: omitted */ }
                         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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",
   "types": "dist/holmes/mcp/server.d.ts",