@holmes-lab/holmes-kit 0.19.2 → 0.19.4

package/dist/holmes/semantic/model-cache.js

@@ -0,0 +1,67 @@
+"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.modelCacheDir = modelCacheDir;
+exports.modelCacheReady = modelCacheReady;
+// @implements A-SPEC-594
+/**
+ * Where the local model's assets live, and whether they are actually there.
+ *
+ * A leaf on purpose: `tier.ts` must consult readiness, and `local-model.ts` already imports
+ * `tier.ts`, so putting this in either one closes an import cycle. Nothing here imports
+ * anything of ours.
+ */
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+function modelCacheDir(env = process.env, home = os.homedir()) {
+    return path.resolve(env.HOLMES_MODEL_CACHE || path.join(home, '.holmes', 'models'));
+}
+/**
+ * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
+ * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
+ * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
+ * doctor calls this on every run and must stay cheap and offline.
+ */
+function modelCacheReady(cacheDir = modelCacheDir()) {
+    if (cacheDir === '')
+        return false;
+    try {
+        return fs.readdirSync(cacheDir).length > 0;
+    }
+    catch {
+        return false;
+    } // absent, unreadable, not a directory — none of them are ready
+}

package/dist/holmes/semantic/tier.d.ts

@@ -22,6 +22,12 @@ export interface SemanticTier {
     egress: boolean;
     /** Where the cloud consent came from — shown by doctor/status, never the value itself. */
     keySource?: KeySource;
+    /**
+     * @implements A-SPEC-594 — 'none' only: the local runtime resolves but its model was never
+     * prepared. The distinction exists because the two 'none' states need different advice, and
+     * because reporting this one as 'local' claims a recall the tier cannot deliver.
+     */
+    localRuntimePresent?: boolean;
 }
 /**
  * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
@@ -33,5 +39,6 @@ export declare function POOLING_OF(model: string): 'cls' | 'mean';
 export declare function resolveSemanticTier(opts?: {
     env?: NodeJS.ProcessEnv;
     hasLocalModule?: boolean;
+    hasLocalModel?: boolean;
     credentials?: CredentialOpts;
 }): SemanticTier;

package/dist/holmes/semantic/tier.js

@@ -17,6 +17,7 @@ exports.CLOUD_MODEL = exports.LOCAL_MODEL = void 0;
 exports.POOLING_OF = POOLING_OF;
 exports.resolveSemanticTier = resolveSemanticTier;
 const credentials_1 = require("./credentials");
+const model_cache_1 = require("./model-cache");
 /** The local tier's model. CLS-pooled — see POOLING_OF. */
 exports.LOCAL_MODEL = 'Xenova/bge-m3';
 /** The opt-in cloud tier's model (S-491 four-arm winner). */
@@ -47,8 +48,13 @@ function resolveSemanticTier(opts = {}) {
     if (found !== null) {
         return { tier: 'cloud', model: exports.CLOUD_MODEL, egress: true, keySource: found.source };
     }
-    const hasLocal = opts.hasLocalModule ?? localModulePresent();
-    if (hasLocal)
+    // @implements A-SPEC-594 — availability is a CONJUNCTION. Once @xenova/transformers became a
+    // required dependency, `localModulePresent()` answered true for every install and stopped
+    // discriminating; a resolvable runtime with no model produces no embedding at all. Wiring
+    // presence is not readiness.
+    const hasModule = opts.hasLocalModule ?? localModulePresent();
+    const hasModel = opts.hasLocalModel ?? (0, model_cache_1.modelCacheReady)();
+    if (hasModule && hasModel)
         return { tier: 'local', model: exports.LOCAL_MODEL, egress: false };
-    return { tier: 'none', egress: false };
+    return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}) };
 }

package/dist/holmes/spec/renumber.d.ts

@@ -0,0 +1,72 @@
+export interface RenumberPlan {
+    moves: {
+        from: string;
+        to: string;
+        oldId: string;
+        newId: string;
+    }[];
+    dependsOn: {
+        file: string;
+        oldId: string;
+        newId: string;
+    }[];
+    slices: {
+        file: string;
+        from: string;
+        to: string;
+    }[];
+    anchors: {
+        file: string;
+        oldId: string;
+        newId: string;
+        count: number;
+    }[];
+    /** Child-first: T -> A -> H -> REQ. Only what a move actually unseals. */
+    unsealOrder: string[];
+    /** Parent-first: REQ -> H -> A -> T. Only what a move actually breaks. */
+    approveOrder: string[];
+    /** Reported, never rewritten. */
+    proseCandidates: {
+        file: string;
+        line: number;
+        text: string;
+    }[];
+    refusal?: string;
+}
+export interface RenumberSpec {
+    id: string;
+    type: string;
+    file: string;
+    dependsOn: string[];
+    status?: string;
+    frontmatter?: Record<string, unknown>;
+    /** The document text, so prose INSIDE a spec is reported like prose anywhere else. */
+    body?: string;
+}
+export interface RenumberInput {
+    specs: RenumberSpec[];
+    sources: {
+        file: string;
+        text: string;
+    }[];
+    oldBase: string;
+    newBase: string;
+}
+/** Rewrite ONLY `@implements` ids. Everything else in the text is left exactly as it was. */
+export declare function rewriteAnchors(text: string, pairs: {
+    oldId: string;
+    newId: string;
+}[]): string;
+export declare function planRenumber(input: RenumberInput): RenumberPlan;
+/**
+ * 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.
+ */
+export declare function applyRenumber(root: string, plan: RenumberPlan): number;
+/** Source files an anchor can live in, as `{file, text}` with repo-relative POSIX paths. */
+export declare function readSourcesForRenumber(projectRoot: string): {
+    file: string;
+    text: string;
+}[];
+/** Spec documents as the planner needs them, with store-relative POSIX paths. */
+export declare function readSpecsForRenumber(specsRoot: string): RenumberSpec[];

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.