@holmes-lab/holmes-kit 0.18.0 → 0.19.2

package/dist/holmes/rtm/incremental.js

@@ -56,7 +56,12 @@ function applyIncremental(graph, changes, ctx) {
     }
     if (!ctx.allScanned)
         return { callEdgesResolved: false };
+    // @implements A-SPEC-573.5 — `calls_ambiguous` is rebuilt by the same pass, so it must be cleared
+    // by the same pass. Missing it left a stale candidate edge behind when an ambiguity RESOLVED
+    // (the second definer was deleted), and incremental stopped converging with a full rebuild —
+    // caught by A-SPEC-280's convergence property, which is exactly what it is for.
     graph.removeEdgesByRel('calls');
+    graph.removeEdgesByRel('calls_ambiguous');
     (0, rtm_builder_1.addCallEdges)(ctx.allScanned(), graph, ctx.buildOptions);
     return { callEdgesResolved: true };
 }

package/dist/holmes/rtm/rtm-builder.d.ts

@@ -16,6 +16,14 @@ import { ScannedFile } from '../cpg/cpg-scanner';
  */
 export interface ResolutionReport {
     resolved: number;
+    /**
+     * @implements A-SPEC-573.5
+     * Candidate edges kept for a call whose name is defined in more than one place. Census on this
+     * repository (2026-09-08): 102 qualified-name and 590 last-segment collisions were being dropped
+     * against 3,067 resolved edges — 22.6% of the call graph, at a mean fan-out of 2.29. They ride on
+     * the `calls_ambiguous` relation, which every certainty-requiring reader filters out by name.
+     */
+    ambiguousEdges: number;
     /** Callee defined in several files: precision-over-recall refused to guess. A real miss. */
     ambiguous: number;
     /** Callee defined nowhere in the scan — usually an external package or runtime builtin. */

package/dist/holmes/rtm/rtm-builder.js

@@ -139,7 +139,7 @@ function buildRtm(specs, scanned, graph, opts) {
     // on a 56k-insert graph (216 ms -> 173 ms with a transaction; 88 -> 52 ms with cached statements).
     // It also makes a failed build atomic — no half-graph that could be mistaken for a complete one.
     let resolution = {
-        resolved: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
+        resolved: 0, ambiguousEdges: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
     };
     graph.transaction(() => {
         // Add spec nodes and dependencies
@@ -185,7 +185,7 @@ function buildRtm(specs, scanned, graph, opts) {
  */
 function addCallEdges(scanned, graph, opts) {
     const report = {
-        resolved: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
+        resolved: 0, ambiguousEdges: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
     };
     // @implements A-SPEC-300
     // Indexes are built PER LANGUAGE FAMILY. Resolution used to look across the whole scan, so a Java
@@ -247,11 +247,37 @@ function addCallEdges(scanned, graph, opts) {
             }
             const family = familyOf(f.sourcePath);
             const table = definedIn.get(family);
+            // @implements A-SPEC-573.5 — an ambiguous target is a CANDIDATE SET, not a dead end. Both
+            // shapes of ambiguity keep every candidate on `calls_ambiguous`; `calls` still means "one
+            // place, certain", so nothing that reads certainty changes. Emitting nothing was buying
+            // precision at the cost of 22.6% of the call graph.
+            const ambiguousCandidates = (qn, paths) => {
+                for (const p of paths) {
+                    const to = `CODE:${qn}@${p}`;
+                    if (to === fromId)
+                        continue; // self-recursion carries no impact, ambiguous or not
+                    graph.addEdge(fromId, to, 'calls_ambiguous', f.sourcePath, fact(opts, `${f.sourcePath}`, 'name-resolution', null));
+                    report.ambiguousEdges++;
+                }
+            };
             let target = null;
             if (table?.has(e.to))
                 target = { qn: e.to, paths: table.get(e.to) };
-            else
-                target = byLastSegment.get(family)?.get(e.to) ?? null;
+            else {
+                const byLast = byLastSegment.get(family);
+                const hit = byLast?.get(e.to);
+                if (hit === null) {
+                    // The last segment is owned by several qualified names — keep every owner as a candidate.
+                    for (const [qn, paths] of table ?? []) {
+                        const last = qn.includes('.') ? qn.slice(qn.lastIndexOf('.') + 1) : qn;
+                        if (last === e.to)
+                            ambiguousCandidates(qn, paths);
+                    }
+                    report.unknownTarget++;
+                    continue;
+                }
+                target = hit ?? null;
+            }
             if (!target) {
                 report.unknownTarget++;
                 continue;
@@ -259,9 +285,10 @@ function addCallEdges(scanned, graph, opts) {
             const sameFile = target.paths.includes(f.sourcePath);
             const path = sameFile ? f.sourcePath : (target.paths.length === 1 ? target.paths[0] : null);
             if (!path) {
+                ambiguousCandidates(target.qn, target.paths);
                 report.ambiguous++;
                 continue;
-            } // defined in several files — emit nothing
+            }
             const toId = `CODE:${target.qn}@${path}`;
             if (toId === fromId) {
                 report.selfReference++;

package/dist/holmes/rtm/rtm-graph.d.ts

@@ -136,6 +136,17 @@ export declare class RtmGraph {
          */
         maxCalleeInDegree?: number;
     }): string[];
+    /**
+     * Every resolved FILE->FILE `imports` edge, as repo-relative path pairs.
+     *
+     * Exists because cycle detection needs the whole import graph at once, and the alternative —
+     * parsing `dumpCanonical()` — builds a multi-megabyte string on every call to answer a question
+     * one query answers.
+     */
+    importEdges(): Array<{
+        from: string;
+        to: string;
+    }>;
     /**
      * @implements A-SPEC-289
      * Repo-relative paths of the files that import this one, via resolved FILE->FILE `imports` edges.

package/dist/holmes/rtm/rtm-graph.js

@@ -224,6 +224,19 @@ class RtmGraph {
             : this.callees(id).filter((callee) => this.callerCount(callee) <= limit);
         return [...new Set([...this.impactSourcesOf(id), ...downstream])].sort();
     }
+    // @implements A-SPEC-574.2
+    /**
+     * Every resolved FILE->FILE `imports` edge, as repo-relative path pairs.
+     *
+     * Exists because cycle detection needs the whole import graph at once, and the alternative —
+     * parsing `dumpCanonical()` — builds a multi-megabyte string on every call to answer a question
+     * one query answers.
+     */
+    importEdges() {
+        return this.db.prepare("SELECT DISTINCT src, dst FROM edges WHERE rel='imports' ORDER BY src ASC, dst ASC")
+            .all()
+            .map((r) => ({ from: r.src.replace(/^FILE:/, ''), to: r.dst.replace(/^FILE:/, '') }));
+    }
     /**
      * @implements A-SPEC-289
      * Repo-relative paths of the files that import this one, via resolved FILE->FILE `imports` edges.

package/dist/holmes/spec/legacy-fields.d.ts

@@ -0,0 +1,2 @@
+/** Frontmatter key that carries a pre-migration `depends_on` value. */
+export declare const LEGACY_DEPENDS_FIELD = "legacy_depends_on";

package/dist/holmes/spec/legacy-fields.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_DEPENDS_FIELD = void 0;
+// @implements A-SPEC-574.3
+// One constant, in a module neither side owns. `spec-parser` needed the field name and `legacy-format`
+// needed the parser's `Spec` type, so each imported the other — a cycle held up by a single string.
+// Shared things belong to a third module; that is the whole rule.
+/** Frontmatter key that carries a pre-migration `depends_on` value. */
+exports.LEGACY_DEPENDS_FIELD = 'legacy_depends_on';

package/dist/holmes/spec/legacy-format.d.ts

@@ -48,7 +48,7 @@ export declare const LEGACY_STATUS_FIELD = "legacy_status";
  * computation — asserting it anyway is the fabrication this repository keeps removing. Verbatim
  * preservation leaves the judgement to a person who can actually make it.
  */
-export declare const LEGACY_DEPENDS_FIELD = "legacy_depends_on";
+export { LEGACY_DEPENDS_FIELD } from './legacy-fields';
 /**
  * Classify a document by FORMAT, not by validity.
  *

package/dist/holmes/spec/legacy-format.js

@@ -21,7 +21,10 @@ exports.LEGACY_STATUS_FIELD = 'legacy_status';
  * computation — asserting it anyway is the fabrication this repository keeps removing. Verbatim
  * preservation leaves the judgement to a person who can actually make it.
  */
-exports.LEGACY_DEPENDS_FIELD = 'legacy_depends_on';
+// @implements A-SPEC-574.3 — moved to `legacy-fields` and re-exported, so existing importers
+// keep working while the cycle it created is gone.
+var legacy_fields_1 = require("./legacy-fields");
+Object.defineProperty(exports, "LEGACY_DEPENDS_FIELD", { enumerable: true, get: function () { return legacy_fields_1.LEGACY_DEPENDS_FIELD; } });
 /**
  * Classify a document by FORMAT, not by validity.
  *

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

@@ -37,7 +37,9 @@ exports.parseDependsOn = parseDependsOn;
 exports.parseSpec = parseSpec;
 exports.serializeSpec = serializeSpec;
 const yaml = __importStar(require("js-yaml"));
-const legacy_format_1 = require("./legacy-format");
+// @implements A-SPEC-574.3 — from the shared module, not from `legacy-format`, which imports
+// this file's `Spec` type. That pair was a cycle over one string constant.
+const legacy_fields_1 = require("./legacy-fields");
 /**
  * Read `depends_on` in every spelling the corpus contains, keeping what cannot be represented.
  *
@@ -121,8 +123,8 @@ function parseSpec(input) {
     const deps = parseDependsOn(fm.depends_on);
     // @implements A-SPEC-221 — never overwrite an existing preservation: a second round trip must not
     // chew up what the first one saved, the same rule `legacy_status` follows.
-    if (deps.legacy !== null && fm[legacy_format_1.LEGACY_DEPENDS_FIELD] === undefined) {
-        fm[legacy_format_1.LEGACY_DEPENDS_FIELD] = deps.legacy;
+    if (deps.legacy !== null && fm[legacy_fields_1.LEGACY_DEPENDS_FIELD] === undefined) {
+        fm[legacy_fields_1.LEGACY_DEPENDS_FIELD] = deps.legacy;
     }
     return {
         id: String(fm.id ?? ''),

package/docs/install-guide.md

@@ -91,19 +91,63 @@ Your npm metadata cache predates the release — measured minutes after publishi
 registry already listed the version while a default-cache install still refused it. Add
 `--prefer-online`, or retry in a few minutes.
 
+### npm 12: `better-sqlite3` has no binary and nothing failed
+
+npm 12 (and npm ≥ 11.19) **blocks dependency install scripts by default** and skips them
+silently: `npm ci` exits 0, `better-sqlite3` never runs `prebuild-install`, and the first
+`require` dies with "Could not locate the bindings file". Measured 2026-09-09 (Windows 11,
+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
+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 }
+```
+
+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):
+
+| 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) |
+| This repository checkout | already approved — `npm rebuild better-sqlite3 --foreground-scripts` if the binary is missing |
+| Global (`npm install -g`) | `npm rebuild -g better-sqlite3 --foreground-scripts --allow-scripts=better-sqlite3` — a per-command flag scoped to one package; no npm config is changed. Target the dependency: `rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies `EEXIST` under npm 12 (measured). If this fails `EPERM` under `C:\Program Files\nodejs`, your prefix is protected — see "Before `npm install -g`" above |
+| Bare `npx` | not repairable in place — do a local install and use the first row |
+
+Never use `--dangerously-allow-all-scripts` or a global `allow-scripts` config: the point of the
+policy is that only the reviewed package runs code at install time. Older npm 11 (measured 11.6.2)
+ignores the `allowScripts` field and runs scripts as before; npm 11.19 honours it exactly like 12.
+
+### Windows: `npm`/`npx` are blocked by the PowerShell execution policy
+
+`npm`, `npx` and `holmes-kit` resolve to `.ps1` shims first, and a `Restricted`/`AllSigned`
+policy refuses them (PSSecurityException). The `.cmd` shims always run: `npm.cmd`, `npx.cmd`.
+doctor emits `.cmd` commands on Windows and appends the policy note when it can observe a
+blocking policy. Do not change the execution policy to fix this.
+
 ### `better-sqlite3` fails to build
 
 The one dependency that may need a toolchain. The 8 tree-sitter grammars ship prebuilt binaries
 (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) and compile nothing; `better-sqlite3`
 downloads a prebuild at install time and **falls back to compiling** when none matches your
-platform and Node ABI. If it compiles, you need:
+platform and Node ABI. doctor reports this as `build-failed` — with the approval in place, the
+script ran and left no binary — and names what it can observe on Windows (Python on PATH, Visual
+Studio C++ Build Tools, a space in the install path). It cannot observe a failed prebuild
+download; rerun with `--foreground-scripts` to see the script's own output. If it compiles, you
+need:
 
 | Platform | Toolchain |
 |---|---|
-| Windows | Visual Studio Build Tools (C++ workload) |
+| Windows | Visual Studio Build Tools (C++ workload) + Python 3 on PATH; prefer an install path without spaces |
 | macOS | Xcode Command Line Tools (`xcode-select --install`) |
 | Alpine | `apk add --no-cache python3 make g++` |
 
+A binary that exists but fails with `NODE_MODULE_VERSION` was built for another Node — doctor
+calls that `abi-mismatch`; rebuild against the Node you run.
+
 ### `spawn sh ENOENT` during a git-URL install
 
 `npm i -g git+ssh://…` is not a supported path: npm 11 clones the repository into its cache and
@@ -117,15 +161,20 @@ npx holmes-kit doctor        # local install
 holmes-kit doctor            # global install
 ```
 
-Expect `10 pass, 1 warn, 0 fail` on a healthy install. The lines that matter most:
+Expect `0 fail` on a healthy install (a few `warn` lines are normal — measured `12 pass, 4 warn,
+0 fail` on a Windows source checkout). The lines that matter most:
 
 - `global prefix` — whether `-g` would work on this machine, and the remedy if not
-- `tree-sitter grammars` / `better-sqlite3` — whether the native modules actually load
+- `tree-sitter grammars` — every grammar actually PARSES in a fresh process (`8 grammars parse`)
+- `better-sqlite3` — loads and runs a `:memory:` query; on FAIL the detail names the cause
+  (`scripts-blocked`, `abi-mismatch`, `build-failed`, or `unknown` with the raw error) and the fix
+  is the exact command for your install layout
 
 ## What we deliberately do NOT do
 
 | Idea | Why not |
 |---|---|
-| A `postinstall` script that prints guidance | Triggers npm 11's `allow-scripts` warning and forfeits this package's current property of running no install scripts at all |
+| A `postinstall` script that prints guidance | Under npm 12 it would be blocked like any other install script, and it forfeits this package's property of running no install scripts of its own |
+| 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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.18.0",
+  "version": "0.19.2",
   "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",
@@ -85,5 +85,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true
   }
 }

package/playbooks/author-slice/PLAYBOOK.md

@@ -136,3 +136,17 @@ T-SPEC 필수 섹션은 4분면 그대로다: **Normal · Corner · Negative ·
 번호가 A-SPEC과 T-SPEC에 한정되는 것, 그리고 스펙 폴더 밑 `.ts`가 author 게이트로 강등되지 않는다는 사실. 번호
 상속 관습은 엔진이 강제하지 않으므로 테스트도 고정하지 않는다 — 관습은 관습이라 말한다. 변이
 검사로 판별력을 증명한 뒤 신뢰한다.
+
+### 순환 의존을 만들지 않는다
+
+두 모듈이 서로를 import 하면 순환이다. **설계 단계에서 피하는 것이 유일하게 값싼 시점이다** ——
+코드가 쓰인 뒤에는 공유 타입 추출이나 지연 `require()` 워크어라운드로만 풀 수 있고, 후자는
+순환을 숨길 뿐 없애지 않는다.
+
+- **공유 타입은 별도 모듈로 뺀다.** A 와 B 가 같은 타입을 필요로 하면 그 타입은 A 도 B 도 아닌
+  세 번째 모듈에 있어야 한다.
+- **타입만 필요하면 `import type` 을 쓴다.** TypeScript 가 방출에서 지우므로 런타임 순환이 되지
+  않는다. 값 import 로 두면 타입만 쓰면서도 순환을 만든다.
+- **지연 `require()` 로 순환을 우회하지 않는다.** 그것은 수리가 아니라 청구서 이연이다.
+
+이 저장소는 **스펙 그래프의 무순환을 ART-2 로 집행**한다. 코드 그래프도 같은 기준을 향한다.

package/playbooks/publish/PLAYBOOK.md

@@ -96,6 +96,38 @@ npm publish --access public
 
 ---
 
+### 6단계: 외부 문서 표면 (External Docs Reach) — 발행이 닿는 곳까지 정직하게
+
+npm 만 갱신하고 끝나면, 사람들이 실제로 읽는 문서는 낡은 채로 남는다. **사고 이력**: 이 저장소에는
+GitHub 리모트가 없어(origin 이 로컬 gitea) 0.16.0·0.17.0·0.18.0 **세 릴리스 동안** GitHub README 가
+한 번도 갱신되지 않았고, `package.json` 의 `homepage` 가 바로 그 문서를 가리킨다.
+
+**발행이 성공한 뒤에만** 실행한다 — 실패한 릴리스의 문서를 최신이라고 주장하지 않는다.
+
+1. **대상 파생 (하드코딩 금지)**: `package.json` 의 `repository` 에서 `<owner>/<repo>` 를 얻는다
+   (`repoTargetFrom`). 이 플레이북은 **소비 프로젝트에도 설치**되므로 특정 저장소를 박아 두면 남의
+   릴리스가 그 저장소를 덮어쓴다. 파생 실패 → **SKIP(사유: `repository` 필드 없음/비-GitHub)**.
+2. **덮어쓸 것을 먼저 본다**: `gh api repos/<owner>/<repo>/contents/README.md` 로 원격을 읽어
+   로컬과의 차이를 **보고**한다. 원격이 분기했다면 동기화는 남의 편집을 지우는 행위다 — 사람이
+   알고 결정해야 한다.
+3. **동기화**: 로컬 `README.md` 를 `gh api --method PUT` 으로 올린다(`sha` 는 2 에서 읽은 값).
+4. **재조회 검증**: 다시 읽어 로컬과 일치하는지 확인한다. **쓴 것과 남은 것은 다를 수 있다** —
+   검증 없는 "갱신했다"는 주장이지 사실이 아니다.
+5. **profile README drift 감지 (자동 수정 금지)**: `<owner>/.github` 의 `profile/README.md` 를 읽어
+   `profileDriftFindings` 로 주장-현실 불일치를 **보고만** 한다. 포지셔닝 문안은 오너 결정이며
+   릴리스 절차가 정할 것이 아니다.
+6. **SKIP 은 값이지 침묵이 아니다**: `gh` 미설치 / 미인증(`gh auth status` 실패) / 권한 없음 /
+   `repository` 부재 — 각각 **무엇을 하지 않았는지 명시**하고 다음으로 간다. 소비 프로젝트의 발행을
+   우리 편의로 막지 않는다. 다만 **조용한 성공은 금지** — 아무 말 없이 넘어가면 그것은 3단계
+   전부를 한 것처럼 읽힌다.
+
+> [!CAUTION]
+> 2.5단계가 로컬 문서에 적용하는 규율("drift 도 누락도 거짓 주장이다")은 **외부 표면에도** 적용된다.
+> 다른 점은 하나뿐이다: repo README 는 로컬의 사본이라 **동기화**하고, profile README 는 독립
+> 문서라 **감지·보고**한다. 무엇이 정본인가가 처방을 정한다.
+
+---
+
 ## 플레이북 트리거 조건
 - "npm publish"
 - "release to npm"

package/playbooks/tdd-slice/PLAYBOOK.md

@@ -85,3 +85,17 @@ holmes는 기계적으로 판별한다: `red-error`로는 red→green 시퀀스
 
 `src/holmes/playbooks/tdd-slice.test.ts` — 이 스킬이 집행 태그(ART-1/4/8)와 red-assertion/red-error
 구별을 담고, 설치기가 이를 발견함을 고정한다. 상시 스위트 포함.
+
+### 순환 의존을 만들지 않는다
+
+두 모듈이 서로를 import 하면 순환이다. **설계 단계에서 피하는 것이 유일하게 값싼 시점이다** ——
+코드가 쓰인 뒤에는 공유 타입 추출이나 지연 `require()` 워크어라운드로만 풀 수 있고, 후자는
+순환을 숨길 뿐 없애지 않는다.
+
+- **공유 타입은 별도 모듈로 뺀다.** A 와 B 가 같은 타입을 필요로 하면 그 타입은 A 도 B 도 아닌
+  세 번째 모듈에 있어야 한다.
+- **타입만 필요하면 `import type` 을 쓴다.** TypeScript 가 방출에서 지우므로 런타임 순환이 되지
+  않는다. 값 import 로 두면 타입만 쓰면서도 순환을 만든다.
+- **지연 `require()` 로 순환을 우회하지 않는다.** 그것은 수리가 아니라 청구서 이연이다.
+
+이 저장소는 **스펙 그래프의 무순환을 ART-2 로 집행**한다. 코드 그래프도 같은 기준을 향한다.