@holmes-lab/holmes-kit 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.5] - 2026-09-01
+
+Two P0 dogfooding fixes: the self-healer no longer breaks what it heals, and Python evidence
+finally flows on venv projects.
+
+### Fixed
+
+- **spec_remediate language-blind `//` injection** (A-SPEC-501.1, dogfooded twice): the anchor is
+  now injected in the file's own comment syntax (`#` for py/yml/sh/toml + Makefile/Dockerfile,
+  `//` for the C family — byte-identical to before, `/* */` for CSS), and a file whose syntax the
+  tool does not know is **refused with guidance** instead of broken. Every injected form is
+  round-trip verified against the real anchor scanner, so injector and scanner can no longer
+  drift apart.
+- **test_run on Python venv projects** (A-SPEC-502.1): the interpreter resolves from evidence —
+  `HOLMES_PYTHON` first, then a `.venv`/`venv` carrying `pyvenv.cfg`, then the old `python3`
+  fallback (byte-identical when no venv exists). A `conftest.py` in the scoped file list widens
+  to its directory (the fixture's actual blast radius) instead of collection-ERRORing the whole
+  run — measured: the same tree passed 1995 cases manually while every scoped run failed.
+
+<!-- @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
 

package/README.md

@@ -117,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)
@@ -193,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+; 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](.ax/decisions/ADR-015_platform-tier-is-decided-by-executed-verification.md) for tier criteria and residual risks (NTFS 8.3 names, reserved device names, 260-char paths; no Windows CI yet) |
+| **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 @@
-8c7f0ed-mthde5yw
+f98587b-mthg333w

package/dist/holmes/mcp/handlers.js

@@ -130,6 +130,7 @@ const package_1 = require("../review/package");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const elicit_approval_1 = require("./elicit-approval");
+const anchor_comment_1 = require("../rtm/anchor-comment");
 const approval_queue_1 = require("../governance/approval-queue");
 const approval_grants_1 = require("../governance/approval-grants");
 const spec_digest_1 = require("../spec/spec-digest");
@@ -3037,9 +3038,17 @@ depends_on:
             if (a.targetFile && a.aspecId) {
                 const fullPath = path.isAbsolute(a.targetFile) ? a.targetFile : path.join(root, a.targetFile);
                 if (fs.existsSync(fullPath)) {
+                    // @implements A-SPEC-501.1 — BUG-4 (dogfooded twice): the old unconditional
+                    // `// @implements` broke Python/YAML targets outright AND produced anchors the scanner
+                    // could not read. The syntax comes from the one map the scanner is aligned with, an
+                    // unknown syntax is an honest refusal, and the containment check is form-agnostic so a
+                    // `#` anchor is not double-injected.
+                    const anchorTag = (0, anchor_comment_1.anchorLineFor)(fullPath, a.aspecId);
                     const content = fs.readFileSync(fullPath, 'utf8');
-                    const anchorTag = `// @implements ${a.aspecId}`;
-                    if (!content.includes(anchorTag)) {
+                    if (anchorTag === null) {
+                        actionsTaken.push(`앵커 주입 거부: ${path.basename(fullPath)} — 이 확장자의 주석 문법을 모릅니다. 파일 관례에 맞는 주석으로 1행에 '@implements ${a.aspecId}'를 직접 추가하십시오`);
+                    }
+                    else if (!content.includes(`@implements ${a.aspecId}`)) {
                         fs.writeFileSync(fullPath, `${anchorTag}\n${content}`);
                         actionsTaken.push(`Injected ${anchorTag} on line 1 of ${a.targetFile}`);
                     }

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/python-env.d.ts

@@ -0,0 +1,7 @@
+export interface PythonEnvDeps {
+    env: NodeJS.ProcessEnv;
+    exists: (p: string) => boolean;
+    platform: NodeJS.Platform;
+}
+export declare function pythonFor(cwd: string, deps: PythonEnvDeps): string;
+export declare function pytestTargets(files: string[]): string[];

package/dist/holmes/review/python-env.js

@@ -0,0 +1,76 @@
+"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.pythonFor = pythonFor;
+exports.pytestTargets = pytestTargets;
+// @implements A-SPEC-502.1
+/**
+ * The two pure transforms that stand between planTestRun and runPytest's execFileSync — BUG-2,
+ * dogfooded on a real .venv project, where both halves of the evidence system idled:
+ *
+ * WHICH python: PATH's python3 was the system interpreter (no pytest), so last-green was never
+ * recorded and ART-4 debt piled 12 entries deep. The interpreter now resolves from EVIDENCE —
+ * pyvenv.cfg, the same proof containsPyvenvCfg uses in the scanner — never from a directory name,
+ * with HOLMES_PYTHON as the explicit operator escape hatch above all detection.
+ *
+ * WHAT arguments: conftest.py is a legitimate TEST FILE for anchor/coverage purposes, but not a
+ * runnable target — passed verbatim it collection-ERRORs every scoped run (measured: the same
+ * tree's manual `pytest tests/` was green, 1995 cases). A conftest argument WIDENS to its
+ * directory — the fixture's actual blast radius — because dropping it would verify less and
+ * keeping it verbatim verifies nothing.
+ */
+const path = __importStar(require("node:path"));
+function pythonFor(cwd, deps) {
+    const explicit = deps.env.HOLMES_PYTHON;
+    if (typeof explicit === 'string' && explicit.trim() !== '')
+        return explicit;
+    for (const dir of ['.venv', 'venv']) {
+        if (deps.exists(path.join(cwd, dir, 'pyvenv.cfg'))) {
+            return deps.platform === 'win32'
+                ? path.join(cwd, dir, 'Scripts', 'python.exe')
+                : path.join(cwd, dir, 'bin', 'python');
+        }
+    }
+    return 'python3';
+}
+function pytestTargets(files) {
+    const out = [];
+    for (const f of files) {
+        const target = path.basename(f) === 'conftest.py' ? path.dirname(f) : f;
+        if (!out.includes(target))
+            out.push(target);
+    }
+    return out;
+}

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/dist/holmes/review/test-runner.d.ts

@@ -75,6 +75,12 @@ export declare function parseJUnitXmlCounts(xml: string, ext?: string): Record<s
  * there), and a repo with no local jest could never yield meaningful suite evidence anyway.
  */
 export declare function jestEntry(cwd: string): string | null;
+/** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
+export declare function runPytest(files: string[], mode: TestRunPlan['mode'], cwd: string): {
+    passed: boolean;
+    tail: string;
+    executed: Record<string, number>;
+};
 /**
  * @implements A-SPEC-137.2
  * Executed-test count from `cargo test` text output. cargo prints one `test <name> ... ok|FAILED|

package/dist/holmes/review/test-runner.js

@@ -39,6 +39,7 @@ exports.parseGoTestJson = parseGoTestJson;
 exports.parseExecutedCounts = parseExecutedCounts;
 exports.parseJUnitXmlCounts = parseJUnitXmlCounts;
 exports.jestEntry = jestEntry;
+exports.runPytest = runPytest;
 exports.parseCargoTest = parseCargoTest;
 exports.runCargo = runCargo;
 exports.runGradle = runGradle;
@@ -50,6 +51,7 @@ const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const python_env_1 = require("./python-env");
 function planTestRun(scope) {
     if (scope.tier === 'full') {
         return { mode: 'full', testFiles: [], reason: 'full regression — run the entire suite' };
@@ -241,6 +243,7 @@ function runJest(files, mode, cwd) {
     }
 }
 /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
+// @implements A-SPEC-502.1 — exported for the wiring test (a fake venv python capturing argv).
 function runPytest(files, mode, cwd) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'holmes-pytest-'));
     const report = path.join(dir, 'report.xml');
@@ -253,8 +256,12 @@ function runPytest(files, mode, cwd) {
     // attribute per testcase. pytest's default since v6 is xunit2, which carries only `classname` —
     // measured: a green 4-passed/1-skipped run yielded ZERO per-file evidence under the default, so
     // the tier gate would have had nothing to verify against.
+    // @implements A-SPEC-502.1 — BUG-2, both halves: the interpreter resolves from pyvenv.cfg
+    // evidence (HOLMES_PYTHON above all, python3 fallback byte-identical to the old path), and a
+    // conftest.py argument widens to its directory instead of collection-ERRORing the whole run.
     const args = ['-m', 'pytest', '-q', '-o', 'junit_family=xunit1', `--junit-xml=${report}`,
-        ...(mode === 'scoped' ? ['--', ...files] : [])];
+        ...(mode === 'scoped' ? ['--', ...(0, python_env_1.pytestTargets)(files)] : [])];
+    const python = (0, python_env_1.pythonFor)(cwd, { env: process.env, exists: fs.existsSync, platform: process.platform });
     const read = () => {
         try {
             return parseJUnitXmlCounts(fs.readFileSync(report, 'utf8'));
@@ -264,7 +271,7 @@ function runPytest(files, mode, cwd) {
         }
     };
     try {
-        const out = (0, node_child_process_1.execFileSync)('python3', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        const out = (0, node_child_process_1.execFileSync)(python, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
         return { passed: true, tail: tailOf(out), executed: read() };
     }
     catch (e) {

package/dist/holmes/rtm/anchor-comment.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one comment-syntax truth the anchor INJECTOR shares with the anchor SCANNER. BUG-4
+ * (dogfooded twice): spec_remediate wrote `// @implements` into every file type — a YAML workflow
+ * became a parse error, a Python golden file a SyntaxError, and the anchor was not even legible to
+ * extractAnchors. Every form emitted here matches the scanner's comment prefixes (`//`, `/*`, `#`);
+ * a syntax this map does not know returns null and the caller must REFUSE to write — an honest
+ * refusal beats a broken file, and beats an anchor the gate cannot read.
+ */
+export declare function anchorLineFor(filePath: string, aspecId: string): string | null;

package/dist/holmes/rtm/anchor-comment.js

@@ -0,0 +1,34 @@
+"use strict";
+// @implements A-SPEC-501.1
+/**
+ * The one comment-syntax truth the anchor INJECTOR shares with the anchor SCANNER. BUG-4
+ * (dogfooded twice): spec_remediate wrote `// @implements` into every file type — a YAML workflow
+ * became a parse error, a Python golden file a SyntaxError, and the anchor was not even legible to
+ * extractAnchors. Every form emitted here matches the scanner's comment prefixes (`//`, `/*`, `#`);
+ * a syntax this map does not know returns null and the caller must REFUSE to write — an honest
+ * refusal beats a broken file, and beats an anchor the gate cannot read.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anchorLineFor = anchorLineFor;
+const SLASH = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'java', 'c', 'h', 'cc', 'cpp',
+    'hpp', 'cs', 'go', 'rs', 'swift', 'kt', 'kts', 'scala', 'dart']);
+const HASH = new Set(['py', 'rb', 'sh', 'bash', 'zsh', 'fish', 'yml', 'yaml', 'toml', 'pl', 'pm',
+    'r', 'jl', 'cmake', 'mk']);
+const CSS = new Set(['css', 'scss', 'less']);
+const HASH_BASENAMES = new Set(['Makefile', 'Dockerfile', 'Rakefile', 'Gemfile']);
+function anchorLineFor(filePath, aspecId) {
+    const basename = filePath.slice(filePath.lastIndexOf('/') + 1);
+    if (HASH_BASENAMES.has(basename))
+        return `# @implements ${aspecId}`;
+    const dot = basename.lastIndexOf('.');
+    if (dot <= 0)
+        return null;
+    const ext = basename.slice(dot + 1).toLowerCase();
+    if (SLASH.has(ext))
+        return `// @implements ${aspecId}`;
+    if (HASH.has(ext))
+        return `# @implements ${aspecId}`;
+    if (CSS.has(ext))
+        return `/* @implements ${aspecId} */`;
+    return null;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.3.3",
+  "version": "0.3.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",