@holmes-lab/holmes-kit 0.19.3 → 0.19.5

package/dist/holmes/spec/renumber.js

@@ -0,0 +1,341 @@
+"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.rewriteAnchors = rewriteAnchors;
+exports.planRenumber = planRenumber;
+exports.applyRenumber = applyRenumber;
+exports.readSourcesForRenumber = readSourcesForRenumber;
+exports.readSpecsForRenumber = readSpecsForRenumber;
+// @implements A-SPEC-255
+/**
+ * Renumbering a spec, as a contract instead of a memory exercise.
+ *
+ * A spec id lives in eight places: the filename, the frontmatter `id`, every child's `depends_on`,
+ * the `slice` tag, source `@implements` anchors, test titles, prose citations and the CHANGELOG.
+ * Measured 2026-08-23, a person doing REQ-220 → 253 by hand moved two anchors and left SEVEN prose
+ * references — two test `describe` titles among six, plus a comment inside the SHIPPED install.ps1 —
+ * and the bulk regex brought in to catch the rest rewrote REQ-253's own `source.ref` into a citation
+ * of itself. Review caught all three before release; that is not a process.
+ *
+ * So the contract is deliberately ASYMMETRIC:
+ *
+ *   definite grammar  (filename, id, depends_on, slice, @implements)  -> the tool MOVES it
+ *   needs context     (prose, comments, test titles, CHANGELOG, ref:) -> the tool NAMES it
+ *
+ * The tool never substitutes prose. That substitution IS the accident.
+ *
+ * Re-sealing is not here either: `spec_approve` is the only sealer (REQ-245 principle — a second
+ * sealer becomes a second truth and they drift). This module reports the two ORDERS instead, and
+ * they are opposites: `spec_unseal` refuses while an approved child depends on the target, so
+ * unsealing runs child-first; `spec_approve` refuses while a parent is unsealed, so re-approving
+ * runs parent-first.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_id_1 = require("./spec-id");
+/** The anchor grammar, shared with `rtm/anchor-ids.ts` so the two judgments cannot drift apart. */
+const ID_RE = String.raw `(?:REQ|A-SPEC|H-SPEC|C-SPEC|T-SPEC)-\d{3,}(?:\.\d+)?`;
+const ANCHOR_LIST_RE = new RegExp(String.raw `(@implements[ \t]+)(${ID_RE}(?:[ \t]*,[ \t]*${ID_RE})*)`, 'g');
+/** Unseal is child-first; re-approve is the exact reverse. */
+const CHILD_FIRST = ['T-SPEC', 'C-SPEC', 'A-SPEC', 'H-SPEC', 'REQ'];
+const baseOf = (id) => {
+    const n = (0, spec_id_1.specIdBase)(id);
+    return n === null ? '' : String(n);
+};
+/** `A-SPEC-596.1` -> `A-SPEC-599.1`: the dot suffix is identity, not base. */
+const renamed = (id, oldBase, newBase) => baseOf(id) !== oldBase ? id : id.replace(new RegExp(`-${oldBase}(\\.\\d+)?$`), `-${newBase}$1`);
+const EMPTY = () => ({
+    moves: [], dependsOn: [], slices: [], anchors: [], unsealOrder: [], approveOrder: [], proseCandidates: [],
+});
+/** Rewrite ONLY `@implements` ids. Everything else in the text is left exactly as it was. */
+function rewriteAnchors(text, pairs) {
+    if (pairs.length === 0)
+        return text;
+    const map = new Map(pairs.map((p) => [p.oldId, p.newId]));
+    return text.replace(ANCHOR_LIST_RE, (_m, marker, list) => marker + list.split(/([ \t]*,[ \t]*)/).map((part) => map.get(part.trim()) ?? part).join(''));
+}
+function planRenumber(input) {
+    const { specs = [], sources = [], oldBase, newBase } = input ?? {};
+    const refuse = (reason) => ({ ...EMPTY(), refusal: reason });
+    const family = specs.filter((s) => baseOf(s.id) === oldBase);
+    if (family.length === 0)
+        return refuse(`base ${oldBase} 를 쓰는 스펙이 없습니다 — 옮길 것이 없습니다.`);
+    // A partial plan invites a partial move, so an occupied destination empties EVERY list.
+    const taken = specs.filter((s) => baseOf(s.id) === newBase).map((s) => s.id);
+    if (taken.length > 0)
+        return refuse(`목적지 base ${newBase} 는 이미 ${taken.join(', ')} 가 쓰고 있습니다 — 리넘버가 새 충돌을 만들 수 없습니다.`);
+    const plan = EMPTY();
+    const pairs = [];
+    for (const s of family) {
+        const newId = renamed(s.id, oldBase, newBase);
+        pairs.push({ oldId: s.id, newId });
+        plan.moves.push({
+            from: s.file,
+            to: path.posix.join(path.posix.dirname(s.file.replace(/\\/g, '/')), `${newId}.md`),
+            oldId: s.id, newId,
+        });
+    }
+    const moving = new Set(pairs.map((p) => p.oldId));
+    // Every spec in the store that NAMES one of the moving ids — children of the family included.
+    for (const s of specs) {
+        for (const parent of s.dependsOn ?? []) {
+            if (!moving.has(parent))
+                continue;
+            plan.dependsOn.push({ file: s.file, oldId: parent, newId: renamed(parent, oldBase, newBase) });
+        }
+        const slice = s.frontmatter?.slice;
+        if (typeof slice === 'string' && slice.includes(oldBase)) {
+            plan.slices.push({ file: s.file, from: slice, to: slice.split(oldBase).join(newBase) });
+        }
+    }
+    // `depends_on` is hashed by specDigest; `id` is NOT. A spec that only MOVES keeps a valid seal,
+    // so it belongs in neither order — demanding an unnecessary unseal would add risk for nothing.
+    const reseal = new Set(plan.dependsOn.map((d) => d.file));
+    const affected = specs.filter((s) => reseal.has(s.file) && (s.status ?? '') === 'approved');
+    const byKind = (a, b) => CHILD_FIRST.indexOf(a.type) - CHILD_FIRST.indexOf(b.type);
+    plan.unsealOrder = [...affected].sort(byKind).map((s) => s.id);
+    plan.approveOrder = [...affected].sort(byKind).reverse().map((s) => renamed(s.id, oldBase, newBase));
+    const idInText = new RegExp(String.raw `(?:REQ|A-SPEC|H-SPEC|C-SPEC|T-SPEC)-${oldBase}(?:\.\d+)?\b`);
+    /** A line the tool will NOT rewrite but a human must look at. Anchors are excluded — those move. */
+    const scanProse = (file, text, skipFrontmatter) => {
+        const lines = text.split('\n');
+        // A spec's frontmatter (`id`, `depends_on`, `parent_digests`) is STRUCTURED — the tool moves it,
+        // so reporting it would be noise that trains the reader to skim the list.
+        let end = 0;
+        if (skipFrontmatter && lines[0] === '---') {
+            const close = lines.indexOf('---', 1);
+            end = close === -1 ? 0 : close + 1;
+        }
+        lines.forEach((line, i) => {
+            if (i < end)
+                return;
+            if (!idInText.test(line))
+                return;
+            if (!idInText.test(line.replace(ANCHOR_LIST_RE, '')))
+                return; // the only mention was an anchor
+            plan.proseCandidates.push({ file, line: i + 1, text: line });
+        });
+    };
+    // Prose inside a SPEC BODY counts. Measured on the real Windows branch: H-SPEC-596 said "Satisfy
+    // every REQ-596 success criterion" and A-SPEC-596 said "as specified in REQ-596" — sections that
+    // specDigest hashes, and that after a move would cite a spec which no longer exists. Scanning only
+    // src/ and scripts/ reported zero candidates there: a false all-clear.
+    for (const s of specs) {
+        if (typeof s.body === 'string')
+            scanProse(s.file, s.body, true);
+    }
+    for (const src of sources) {
+        const anchored = new Map();
+        for (const m of src.text.matchAll(ANCHOR_LIST_RE)) {
+            for (const id of m[1 + 1].split(/[ \t]*,[ \t]*/).map((x) => x.trim())) {
+                if (moving.has(id))
+                    anchored.set(id, (anchored.get(id) ?? 0) + 1);
+            }
+        }
+        for (const [oldId, count] of anchored) {
+            plan.anchors.push({ file: src.file, oldId, newId: renamed(oldId, oldBase, newBase), count });
+        }
+        // A line that mentions the old id but is NOT an anchor needs context to rewrite correctly.
+        // Name it; do not touch it.
+        scanProse(src.file, src.text, false);
+    }
+    return plan;
+}
+/**
+ * Apply the plan's STRUCTURED edits. `proseCandidates` is not read here — that is the whole point.
+ * A half-renumbered store is worse than an unrenumbered one, so a failure returns what it moved.
+ */
+function applyRenumber(root, plan) {
+    if (plan.refusal)
+        throw new Error(plan.refusal);
+    const abs = (rel) => path.join(root, rel);
+    // Snapshot EVERY file this call will touch, not just the ones it renames: an anchor rewrite that
+    // throws after a depends_on rewrite succeeded would otherwise leave the store half-edited, which
+    // is worse than not having started. Content and location are restored together.
+    const snapshot = new Map();
+    const remember = (rel) => {
+        if (snapshot.has(rel))
+            return;
+        try {
+            snapshot.set(rel, fs.readFileSync(abs(rel), 'utf8'));
+        }
+        catch { /* absent: the move will name it */ }
+    };
+    const moved = [];
+    const created = [];
+    try {
+        for (const mv of plan.moves) {
+            remember(mv.from);
+            fs.mkdirSync(path.dirname(abs(mv.to)), { recursive: true });
+            fs.renameSync(abs(mv.from), abs(mv.to));
+            moved.push(mv);
+            created.push(mv.to);
+            const at = abs(mv.to);
+            fs.writeFileSync(at, fs.readFileSync(at, 'utf8')
+                .replace(new RegExp(`^(id:[ \\t]*)${mv.oldId}[ \\t]*$`, 'm'), `$1${mv.newId}`));
+        }
+        const relocated = new Map(plan.moves.map((m) => [m.from, m.to]));
+        const edit = (file, fn) => {
+            const rel = relocated.get(file) ?? file;
+            if (!relocated.has(file))
+                remember(rel);
+            const at = abs(rel);
+            fs.writeFileSync(at, fn(fs.readFileSync(at, 'utf8')));
+        };
+        for (const d of plan.dependsOn) {
+            edit(d.file, (t) => t.replace(new RegExp(`(-[ \\t]*|\\[[ \\t]*)${d.oldId}\\b`, 'g'), `$1${d.newId}`));
+        }
+        for (const s of plan.slices)
+            edit(s.file, (t) => t.split(s.from).join(s.to));
+        // Each anchor entry carries its OWN ids. Deriving them from `moves` instead coupled the two
+        // passes, and because specs and sources live under different roots this function is called twice
+        // — once with `anchors: []`, once with `moves: []` — so the second call silently rewrote nothing
+        // while the specs had already moved. Measured on the real branch: 22 files kept the old id.
+        const byFile = new Map();
+        for (const a of plan.anchors) {
+            byFile.set(a.file, [...(byFile.get(a.file) ?? []), { oldId: a.oldId, newId: a.newId }]);
+        }
+        for (const [file, pairs] of byFile)
+            edit(file, (t) => rewriteAnchors(t, pairs));
+        return plan.moves.length;
+    }
+    catch (e) {
+        for (const rel of created.reverse()) {
+            try {
+                fs.rmSync(abs(rel), { force: true });
+            }
+            catch { /* best effort */ }
+        }
+        for (const [rel, text] of snapshot) {
+            try {
+                fs.mkdirSync(path.dirname(abs(rel)), { recursive: true });
+                fs.writeFileSync(abs(rel), text);
+            }
+            catch { /* best effort: the original error is what matters */ }
+        }
+        void moved;
+        throw e;
+    }
+}
+/**
+ * The I/O half, kept HERE rather than in the MCP handler: `handlers.ts` carries 92 anchors against a
+ * p90 of 7, and every rule added there is a rule nobody can find later. The handler stays a wiring.
+ */
+const SOURCE_DIRS = ['src', 'scripts'];
+const SOURCE_EXT = /\.(ts|js|mjs|cjs|ps1|sh)$/;
+function walk(dir, out = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (e.name !== 'node_modules')
+                walk(p, out);
+        }
+        else if (SOURCE_EXT.test(e.name))
+            out.push(p);
+    }
+    return out;
+}
+/** Source files an anchor can live in, as `{file, text}` with repo-relative POSIX paths. */
+function readSourcesForRenumber(projectRoot) {
+    const out = [];
+    for (const d of SOURCE_DIRS) {
+        for (const abs of walk(path.join(projectRoot, d))) {
+            try {
+                out.push({
+                    file: path.relative(projectRoot, abs).split(path.sep).join('/'),
+                    text: fs.readFileSync(abs, 'utf8'),
+                });
+            }
+            catch { /* unreadable is not anchored */ }
+        }
+    }
+    return out;
+}
+/** Spec documents as the planner needs them, with store-relative POSIX paths. */
+function readSpecsForRenumber(specsRoot) {
+    const out = [];
+    for (const abs of walk(specsRoot).concat((function md(dir, acc = []) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return acc;
+        }
+        for (const e of entries) {
+            const p = path.join(dir, e.name);
+            if (e.isDirectory())
+                md(p, acc);
+            else if (e.name.endsWith('.md'))
+                acc.push(p);
+        }
+        return acc;
+    })(specsRoot))) {
+        if (!abs.endsWith('.md'))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+        if (!fm)
+            continue;
+        const field = (k) => (new RegExp(`^${k}:[ \\t]*(.+)$`, 'm').exec(fm[1])?.[1] ?? '').trim();
+        const id = field('id');
+        if (id === '')
+            continue;
+        const deps = (/^depends_on:\n((?:[ \t]*-[ \t]*.+\n?)+)/m.exec(fm[1])?.[1] ?? '')
+            .split('\n').map((l) => l.replace(/^[ \t]*-[ \t]*/, '').trim()).filter((x) => x !== '');
+        const inline = /^depends_on:[ \t]*\[(.*)\]/m.exec(fm[1])?.[1];
+        out.push({
+            id, type: field('type'), status: field('status'),
+            file: path.relative(specsRoot, abs).split(path.sep).join('/'),
+            dependsOn: inline !== undefined ? inline.split(',').map((x) => x.trim()).filter(Boolean) : deps,
+            frontmatter: { slice: field('slice') || undefined },
+            body: text,
+        });
+    }
+    return out;
+}

package/dist/holmes/spec/spec-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The base number inside a spec id, as a SPEC-layer fact.
+ *
+ * It lived in `mcp/spec-id-guard.ts` because `spec_create` was its first caller, but the spec layer
+ * may not import the mcp layer (C-SPEC-224: `import src/holmes/spec/ -x-> src/holmes/mcp/`), and
+ * renumbering needs the same parse. Defined here and re-exported there, so there is one parser and
+ * the dependency points the way the architecture says it must.
+ */
+export declare function specIdBase(id: string): number | null;

package/dist/holmes/spec/spec-id.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specIdBase = specIdBase;
+// @implements A-SPEC-252
+// @implements A-SPEC-255
+/**
+ * The base number inside a spec id, as a SPEC-layer fact.
+ *
+ * It lived in `mcp/spec-id-guard.ts` because `spec_create` was its first caller, but the spec layer
+ * may not import the mcp layer (C-SPEC-224: `import src/holmes/spec/ -x-> src/holmes/mcp/`), and
+ * renumbering needs the same parse. Defined here and re-exported there, so there is one parser and
+ * the dependency points the way the architecture says it must.
+ */
+function specIdBase(id) {
+    if (typeof id !== 'string')
+        return null;
+    // 마지막 하이픈 뒤의 숫자 토막(점 앞)을 base 로 본다.
+    const m = /-(\d+)(?:\.\d+)?\s*$/.exec(id.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    return Number.isNaN(n) ? null : n;
+}

package/docs/install-guide.md

@@ -99,17 +99,22 @@ silently: `npm ci` exits 0, `better-sqlite3` never runs `prebuild-install`, and
 npm 12.0.1, Node 24.19.0). `npx holmes-kit doctor` names this cause as `scripts-blocked` and prints
 the commands below; do not reinstall — a reinstall reproduces the same state.
 
-Only **one** package needs its script: `better-sqlite3`. The 8 tree-sitter packages are also
+Two packages need their scripts: **`better-sqlite3` and `sharp`**. SQLite provides local storage;
+sharp is required by the local semantic runtime. The 8 tree-sitter packages are also
 listed as blocked, but they load from their shipped `prebuilds/` without the script (measured on
 all 8), so they are deliberately NOT approved. This repository's `package.json` therefore carries
 
 ```json
-"allowScripts": { "better-sqlite3@12.11.1": true }
+"allowScripts": { "better-sqlite3@12.11.1": true, "sharp@0.32.6": true }
 ```
 
 pinned to the lockfile version, so a dependency bump forces a fresh review (a test fails until the
 pin is updated). Recovery, by how you installed — on Windows use the `.cmd` spellings (see below):
 
+The table below shows SQLite recovery. Repeat approval for `sharp@0.32.6` and rebuild `sharp`
+when its native binding is missing. On PowerShell 5.1, run each command separately and proceed
+only if `$LASTEXITCODE` is zero; `&&` requires a newer PowerShell.
+
 | Layout | Commands |
 |---|---|
 | A project that depends on holmes-kit | `npm install-scripts approve better-sqlite3@12.11.1` then `npm rebuild better-sqlite3 --foreground-scripts` (from the project root; this writes the pin into YOUR package.json) |
@@ -178,3 +183,86 @@ Expect `0 fail` on a healthy install (a few `warn` lines are normal — measured
 | Approving the tree-sitter grammars in `allowScripts` | Measured unnecessary — they load from shipped prebuilds — and every extra approval is code that runs at install time |
 | Recommending `npx @holmes-lab/holmes-kit init` with no install | `init` writes wiring with absolute paths; under bare `npx` those point into the npx cache and break when it is pruned |
 | Fixing your npm prefix from inside the package | A package rewriting your npm configuration is exactly the supply-chain behaviour this guide warns about |
+## ARM Linux needs Node 20 or 22
+
+On **linux-arm64**, installation fails on **Node 24** and succeeds on Node 20 and 22 (measured
+2026-09-10 in a Debian 12 container with python3, make and g++ all present). The cause is not a
+missing toolchain: `tree-sitter@0.21.1` ships prebuilds only for `darwin-arm64`, `darwin-x64`,
+`linux-x64` and `win32-x64`, so ARM Linux compiles from source, and that compile fails against
+Node 24 headers. On x64 the prebuild is used and nothing is compiled, which is why the same Node
+version is fine there.
+
+The failure happens while npm is still installing dependencies — before Holmes-Kit exists — so
+`doctor` cannot diagnose it and this note is the only warning available. If `npm install` dies with
+`gyp ERR!` in `tree_sitter_runtime_binding`, switch to Node 20 or 22 on that machine.
+
+# Default local embeddings (Windows, macOS, Linux)
+
+Holmes-Kit ships with the **Xenova/bge-m3** local tier available, but **preparing it is
+opt-in**: neither package installation, nor `holmes-kit init`, nor the Windows bootstrap
+downloads model assets on its own. Run one command when you want it:
+
+```text
+holmes-kit semantic-setup
+```
+
+To prepare it during installation instead, set `HOLMES_AUTO_MODEL_INSTALL=1` before
+installing. `HOLMES_SKIP_MODEL_INSTALL=1` still refuses preparation and **outranks** the
+opt-in, so an explicit refusal is never overridden. All three harnesses and all three
+operating systems share this default — Windows does not prepare the model when macOS and
+Linux do not.
+
+The first setup downloads public model assets from Hugging Face; it sends no repository
+text. Normal embedding inference is offline and will not download missing assets.
+The model revision is pinned to `4de13258303883538bd53b696b452bf8099f0858`.
+
+Until the model is prepared, `doctor` reports the semantic tier as **none** and names what
+it costs — requests lexical search misses (measured 16.4%) have 0% recall — together with the
+command that changes it. A runtime that resolves is not a tier that answers, so an unprepared
+local runtime is never reported as the `local` tier.
+
+The Windows `scripts/install.ps1` bootstrap honours the same opt-in. With
+`HOLMES_AUTO_MODEL_INSTALL=1` it prepares the model after npm installation and when the
+requested Holmes-Kit version is already installed, printing readiness only after successful
+inference; failure prints `semantic-setup` / `semantic-check` recovery commands while preserving
+the installed graph tools. Without the opt-in it prepares nothing and names the command. Dry runs
+and the explicit skip flag do no model work.
+
+Run `holmes-kit semantic-check` after installation. Success means an actual CPU inference
+produced a finite, normalized 1024-dimensional vector. `doctor` deliberately reports local
+readiness as unverified: resolving a package does not prove that its native libraries or
+model files work. Run `holmes-kit semantic-setup` to prepare the model and retry verification.
+Both commands bound their worker to 15 minutes and return nonzero on failure. Automatic
+setup failure leaves graph features available and reports a retry instruction; npm may
+hide successful lifecycle output, so use `--foreground-scripts` when inspecting installation.
+
+Models are shared between projects in `~/.holmes/models` (Windows:
+`%USERPROFILE%\.holmes\models`). Set `HOLMES_MODEL_CACHE` to override this directory,
+including for a prepopulated offline cache. Set `HOLMES_SKIP_MODEL_INSTALL=1` to refuse
+automatic preparation explicitly; it outranks `HOLMES_AUTO_MODEL_INSTALL=1` and does not
+disable an explicit setup/check command. An empty cache directory counts as not prepared —
+an interrupted download leaves exactly that, and reading it as ready would be a false PASS.
+For source checkouts, build first, then run `node bin/holmes-kit.js semantic-setup`.
+
+If npm blocks lifecycle scripts, run `npm install-scripts ls`, review the blocked versions,
+approve the required runtime scripts in the **consuming project's** policy, and then run
+`holmes-kit semantic-setup`. A dependency's `allowScripts` does not grant consent on behalf
+of the consuming project. In this checkout, `sharp@0.32.6` is explicitly allowed.
+For this pinned sharp version in a project installation, the repair is:
+
+```text
+npm install-scripts approve sharp@0.32.6
+npm rebuild sharp --foreground-scripts
+holmes-kit semantic-setup
+holmes-kit semantic-check
+```
+
+Windows verification on 2026-09-10: Node 24.19.0, Transformers.js 2.17.2, sharp 0.32.6.
+The initial failure was a missing `sharp-win32-x64.node` after blocked install scripts.
+Repairing sharp and downloading the pinned model succeeded; English and Korean inputs
+both produced valid vectors with remote model access disabled. macOS/Linux use the same
+implementation, but this Windows session did not execute platform-native tests there.
+
+The optional cloud credential file uses a protected current-user-only NTFS DACL on Windows.
+Permission setup is verified before a new key is written; failure preserves the prior key and
+refuses the new value. The macOS keychain and POSIX 0700/0600 fallback remain available.

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.19.3",
+  "version": "0.19.5",
   "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",
@@ -22,6 +22,7 @@
     "node": ">=20"
   },
   "scripts": {
+    "postinstall": "node -e \"const p='./dist/holmes/semantic/local-model.js';if(require('fs').existsSync(p)){process.exitCode=require(p).runModelSetup({automatic:true})}else{console.error('BGE-M3 setup pending: build this source checkout, then run holmes-kit semantic-setup.')}\"",
     "build": "tsc && node -e \"const{execSync}=require('child_process'),fs=require('fs');const id=(()=>{try{return execSync('git rev-parse --short HEAD').toString().trim()}catch{return 'nogit'}})();fs.writeFileSync('dist/.build-id',id+'-'+Date.now().toString(36))\"",
     "test": "npm run typecheck && jest",
     "mcp": "node bin/holmes-mcp.js",
@@ -73,7 +74,8 @@
     "tree-sitter-rust": "^0.21.0",
     "tree-sitter-typescript": "^0.21.2",
     "typescript": "^5.0.0",
-    "web-tree-sitter": "0.27.0"
+    "web-tree-sitter": "0.27.0",
+    "@xenova/transformers": "^2.17.2"
   },
   "repository": {
     "type": "git",
@@ -87,6 +89,10 @@
     "access": "public"
   },
   "allowScripts": {
-    "better-sqlite3@12.11.1": true
+    "better-sqlite3@12.11.1": true,
+    "sharp@0.32.6": true
+  },
+  "overrides": {
+    "protobufjs": "^7.6.3"
   }
 }

package/scripts/install.ps1

@@ -1,13 +1,10 @@
+# @implements A-SPEC-593
 <#
 .SYNOPSIS
   Holmes-Kit bootstrap installer for Windows.  @implements A-SPEC-253
 .DESCRIPTION
-  Runs BEFORE npm to fix what npm cannot: a protected CWD (an elevated PowerShell opens in
-  C:\WINDOWS\System32 and `npm install` dies there with EPERM), an unwritable global prefix
-  (C:\Program Files\nodejs), a too-old Node.js, and native-build failures that print compiler
-  noise instead of the one command that installs the toolchain.  Then it runs
-  `npm install -g @holmes-lab/holmes-kit`.  Windows PowerShell 5.1 only; no prompts; nothing
-  persistent is changed.
+  Checks the working directory, npm prefix, Node version, and native install failures.
+  Installs Holmes-Kit and prepares BGE-M3 through the shared CLI. PowerShell 5.1; no prompts.
 .PARAMETER DryRun   Run every check, print the npm command that WOULD run, exit 0 without running it.
 .PARAMETER Version  Package version to install (default: latest).
 .PARAMETER Prefix   Optional npm --prefix for the global install.
@@ -16,8 +13,7 @@
 .NOTES
   Exit codes: 0 ok / already installed, 2 argument error, 3 Node too old, 4 npm failed, 5 not on PATH.
 #>
-# Non-positional on purpose: otherwise `install.ps1 foo` binds `foo` to -Version and runs a REAL
-# `npm install -g @holmes-lab/holmes-kit@foo` from a typo.  Stray tokens land in $Rest -> exit 2.
+# Stray positional tokens land in $Rest and exit 2 before installation.
 [CmdletBinding(PositionalBinding = $false)]
 param(
   [Parameter(Mandatory = $false)][switch]$DryRun,
@@ -34,17 +30,10 @@ $script:NodeMajorFloor = 20
 $script:PackageName = '@holmes-lab/holmes-kit'
 $script:BinName = 'holmes-kit'
 
-# Failure classifier.  Pure: npm's combined output in, one token out.  Precedence is fixed so the
-# most ACTIONABLE cause wins when several signatures appear in the same transcript - an EPERM in a
-# protected directory also drags node-gyp down with it, and telling the user to install MSVC
-# would send them the wrong way.
+# Classify npm failures with directory errors taking precedence over downstream build noise.
 function Get-InstallFailureKind([string]$NpmOutput) {
   if ($null -eq $NpmOutput) { $NpmOutput = '' }
-  # Two EPERMs, one code.  CWD (System32): relocating fixes it.  GLOBAL PREFIX (C:\Program Files\
-  # nodejs, the Node installer's default): only --prefix fixes it.  Measured 2026-08-23: after the
-  # relocation the install still died on `mkdir 'C:\Program Files\nodejs\node_modules\@holmes-lab'`.
-  # Keyed on the FAILING PATH line, not any mention of that directory: every npm stack trace names
-  # npm's own home under Program Files\nodejs\node_modules\npm, which is not the error.
+  # Match the failing prefix path, not npm's own installation mentioned in every stack trace.
   if ($NpmOutput -match 'EPERM' -and $NpmOutput -match "(?m)^npm error path .*Program Files[\\/]+nodejs[\\/]+node_modules[\\/]+(?!npm[\\/])") { return 'eperm-prefix' }
   if ($NpmOutput -match 'EPERM' -and ($NpmOutput -match 'mkdir' -or $NpmOutput -match 'System32' -or $NpmOutput -match 'Program Files')) { return 'eperm' }
   if ($NpmOutput -match 'MSB\d{4}' -or $NpmOutput -match 'MSBuild' -or $NpmOutput -match 'Visual Studio' -or $NpmOutput -match 'vcvarsall') { return 'msbuild' }
@@ -97,10 +86,27 @@ npm exited with an error this installer does not recognise.  The last lines of i
 '@
 }
 
-# Stage helpers
 function Write-Stage([string]$Text) { Write-Host $Text }
 function Write-Problem([string]$Text) { [Console]::Error.WriteLine($Text) }
 
+function Initialize-LocalModel {
+  if ($DryRun) { return }
+  # A-SPEC-594: semantic-setup always downloads, so the opt-in gate lives HERE or Windows keeps fetching while macOS/Linux no longer do. Skip outranks opt-in.
+  if ($env:HOLMES_SKIP_MODEL_INSTALL -eq '1' -or $env:HOLMES_AUTO_MODEL_INSTALL -ne '1') {
+    if ($env:HOLMES_SKIP_MODEL_INSTALL -eq '1') { Write-Stage 'BGE-M3 preparation skipped (HOLMES_SKIP_MODEL_INSTALL=1). Run holmes-kit semantic-setup when ready.' }
+    else { Write-Stage 'BGE-M3 is not prepared automatically. Run holmes-kit semantic-setup to download the public model once, or set HOLMES_AUTO_MODEL_INSTALL=1 before installing. Graph features work without it.' }
+    return
+  }
+  Write-Stage 'Preparing and verifying BGE-M3 through holmes-kit semantic-setup...'
+  $modelCode = 1; $prev = $ErrorActionPreference; $ErrorActionPreference = 'Continue'
+  try {
+    & $script:BinName semantic-setup 2>&1 | ForEach-Object { Write-Stage "$_" }
+    $modelCode = $LASTEXITCODE
+  } catch { $modelCode = 1 } finally { $ErrorActionPreference = $prev }
+  if ($modelCode -eq 0) { Write-Stage 'BGE-M3 ready: local inference verified.' }
+  else { Write-Problem 'BGE-M3 unavailable. Holmes-Kit graph features remain installed. Run holmes-kit semantic-setup, then holmes-kit semantic-check to verify readiness.' }
+}
+
 function Get-NormalizedPath([string]$P) {
   if ([string]::IsNullOrWhiteSpace($P)) { return $null }
   $t = $P.TrimEnd('\', '/')
@@ -118,8 +124,7 @@ function Test-UnderRoot([string]$Candidate, [string]$Root) {
 
 function Test-ProtectedDirectory([string]$Dir) {
   $here = Get-NormalizedPath $Dir
-  # The drive root is protected only when $PWD IS the root (C:\) - everything on the drive is
-  # under it, so treating it like the other roots would relocate every project on the machine.
+  # Protect the drive root itself, not every project beneath it.
   $driveRoot = Get-NormalizedPath ([IO.Path]::GetPathRoot($Dir))
   if ($null -ne $driveRoot -and $here -eq $driveRoot) { return $true }
   $roots = @($env:SystemRoot, $env:ProgramFiles, ${env:ProgramFiles(x86)}, $env:ProgramData)
@@ -165,7 +170,7 @@ function Get-InstalledVersion {
 }
 
 function Get-NpmPrefix {
-  # Skipped in -DryRun only when npm is absent; otherwise it is a local config read, no network.
+  # A local configuration read, without network access.
   $r = Invoke-Npm @('config', 'get', 'prefix')
   if ($r.Code -ne 0) { return $null }
   $v = $r.Output.Trim()
@@ -174,8 +179,7 @@ function Get-NpmPrefix {
 }
 
 function Invoke-Npm([string[]]$Arguments) {
-  # Array arguments, never one interpolated string; npm is npm.cmd on Windows and needs the
-  # .cmd resolution that `&` performs.  Both streams are merged so the classifier sees everything.
+  # Array arguments preserve Windows .cmd resolution; merge streams for failure classification.
   $npm = Get-Command npm.cmd -ErrorAction SilentlyContinue
   if ($null -eq $npm) { $npm = Get-Command npm -ErrorAction SilentlyContinue }
   if ($null -eq $npm) { return @{ Code = 127; Output = 'npm was not found on PATH' } }
@@ -190,7 +194,6 @@ function Invoke-Npm([string[]]$Arguments) {
   return @{ Code = $code; Output = ($lines -join "`n") }
 }
 
-# Pipeline
 function Invoke-Main {
   # Stage 0 - arguments
   if ($null -ne $Rest -and $Rest.Count -gt 0) {
@@ -238,14 +241,13 @@ function Invoke-Main {
     }
     if ($want -ne 'latest' -and $installed -eq $want) {
       Write-Stage ("already installed ({0})" -f $installed)
+      Initialize-LocalModel
       return 0
     }
     Write-Stage ("holmes-kit {0} is installed; will install {1}" -f $installed, $Version)
   }
 
-  # Stage 4b - prefix guard.  A non-elevated shell cannot write the Node installer's default
-  # prefix (C:\Program Files\nodejs) and Stage 1 does not help.  Per-user prefix for THIS call
-  # only; the user's npm config is never modified (REQ-253 Constraint 2).
+  # Stage 4b - use a writable per-user prefix for this call; never modify npm configuration.
   if ([string]::IsNullOrWhiteSpace($Prefix) -and -not (Test-Elevated)) {
     $cur = Get-NpmPrefix
     if ($null -ne $cur -and (Test-ProtectedDirectory $cur)) {
@@ -287,6 +289,7 @@ function Invoke-Main {
   }
   $v = Get-InstalledVersion
   Write-Stage ("holmes-kit {0} installed" -f $v)
+  Initialize-LocalModel
   return 0
 }