@holmes-lab/holmes-kit 0.18.0 → 0.19.0

package/dist/holmes/review/symbol-truth.d.ts

@@ -0,0 +1,14 @@
+export interface SymbolRange {
+    name: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * The symbols a commit's changed lines fall inside, in symbol-list order, deduped.
+ *
+ * A change that lands outside every symbol (an import line, a top-level constant) yields nothing —
+ * and a case with no symbol truth drops OUT of the symbol denominator rather than scoring zero. An
+ * unanswerable case is not a failed one, which is the same rule `evaluationMetrics` already applies
+ * to files.
+ */
+export declare function symbolsTouched(symbols: readonly SymbolRange[], changedLines: readonly number[]): string[];

package/dist/holmes/review/symbol-truth.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symbolsTouched = symbolsTouched;
+/**
+ * The symbols a commit's changed lines fall inside, in symbol-list order, deduped.
+ *
+ * A change that lands outside every symbol (an import line, a top-level constant) yields nothing —
+ * and a case with no symbol truth drops OUT of the symbol denominator rather than scoring zero. An
+ * unanswerable case is not a failed one, which is the same rule `evaluationMetrics` already applies
+ * to files.
+ */
+function symbolsTouched(symbols, changedLines) {
+    if (symbols.length === 0 || changedLines.length === 0)
+        return [];
+    const out = [];
+    for (const s of symbols) {
+        // Both ends inclusive: the signature line and the closing line are part of the symbol.
+        if (changedLines.some((line) => line >= s.startLine && line <= s.endLine) && !out.includes(s.name)) {
+            out.push(s.name);
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/defuse-symbols.d.ts

@@ -0,0 +1,17 @@
+import type { DataFlowFacts } from '../cpg/language-parser';
+/**
+ * Order a file's function names by how close they sit, in def-use terms, to what the request says.
+ *
+ * Three tiers, stable within each so the result is deterministic (the downstream lists are
+ * position-indexed): functions the request names directly, functions one def-use step from those,
+ * then everything else in its original order. A term matching nothing leaves the order untouched —
+ * an empty first tier must not shuffle the list.
+ */
+export declare function rankSymbolsByDefUse(facts: DataFlowFacts, terms: readonly string[], order: readonly string[]): string[];
+/**
+ * Append what def-use suggested behind what the lexical layer matched.
+ *
+ * Never in front: this repository has already measured a re-ranker deleting the lexical answer, so
+ * a second signal rides behind the first rather than replacing it.
+ */
+export declare function enrichCandidateSymbols(lexical: readonly string[], suggested: readonly string[]): string[];

package/dist/holmes/rtm/defuse-symbols.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankSymbolsByDefUse = rankSymbolsByDefUse;
+exports.enrichCandidateSymbols = enrichCandidateSymbols;
+/** Names a function mentions anywhere the walk recovered them: params, defs, and call arguments. */
+function surfaceOf(facts) {
+    const out = new Map();
+    const push = (fn, ...words) => {
+        const bucket = out.get(fn) ?? out.set(fn, []).get(fn);
+        for (const w of words)
+            if (w !== '' && !bucket.includes(w))
+                bucket.push(w);
+    };
+    for (const p of facts.params)
+        push(p.fn, p.name);
+    for (const d of facts.defs)
+        push(d.fn, d.name, ...d.expr.refs, ...d.expr.callees);
+    for (const c of facts.calls) {
+        push(c.fn, c.callee);
+        for (const a of c.args)
+            push(c.fn, ...a.refs, ...a.callees);
+    }
+    for (const r of facts.returns)
+        push(r.fn, ...r.expr.refs, ...r.expr.callees);
+    return out;
+}
+/**
+ * Order a file's function names by how close they sit, in def-use terms, to what the request says.
+ *
+ * Three tiers, stable within each so the result is deterministic (the downstream lists are
+ * position-indexed): functions the request names directly, functions one def-use step from those,
+ * then everything else in its original order. A term matching nothing leaves the order untouched —
+ * an empty first tier must not shuffle the list.
+ */
+function rankSymbolsByDefUse(facts, terms, order) {
+    if (order.length === 0)
+        return [];
+    const lowered = terms.map((t) => t.toLowerCase()).filter((t) => t !== '');
+    if (lowered.length === 0)
+        return [...order];
+    const surface = surfaceOf(facts);
+    // A function is "named" when a request term appears in its own name or in any identifier its
+    // body touches. Substring, not equality: `config` has to reach `configPath`.
+    const names = (fn) => [fn, ...(surface.get(fn) ?? [])];
+    const direct = new Set();
+    for (const fn of new Set([...order, ...surface.keys()])) {
+        if (names(fn).some((n) => lowered.some((t) => n.toLowerCase().includes(t))))
+            direct.add(fn);
+    }
+    if (direct.size === 0)
+        return [...order];
+    // One def-use step: a function that reads what a direct one defined, or that sits on either end
+    // of a call with it. Call adjacency counts BOTH ways — the caller of a named function is as
+    // relevant as its callee, and a one-directional rule would silently favour one.
+    const definedByDirect = new Set();
+    for (const d of facts.defs)
+        if (direct.has(d.fn))
+            definedByDirect.add(d.name);
+    const near = new Set();
+    const mark = (fn) => { if (!direct.has(fn))
+        near.add(fn); };
+    for (const d of facts.defs)
+        if (d.expr.refs.some((r) => definedByDirect.has(r)))
+            mark(d.fn);
+    for (const c of facts.calls) {
+        if (c.args.some((a) => a.refs.some((r) => definedByDirect.has(r))))
+            mark(c.fn);
+        if (direct.has(c.fn))
+            mark(c.callee);
+        if (direct.has(c.callee))
+            mark(c.fn);
+    }
+    for (const r of facts.returns)
+        if (r.expr.refs.some((x) => definedByDirect.has(x)))
+            mark(r.fn);
+    const tier = (fn) => (direct.has(fn) ? 0 : near.has(fn) ? 1 : 2);
+    return [...order].sort((a, b) => tier(a) - tier(b) || order.indexOf(a) - order.indexOf(b));
+}
+/**
+ * Append what def-use suggested behind what the lexical layer matched.
+ *
+ * Never in front: this repository has already measured a re-ranker deleting the lexical answer, so
+ * a second signal rides behind the first rather than replacing it.
+ */
+function enrichCandidateSymbols(lexical, suggested) {
+    const out = [...lexical];
+    for (const s of suggested)
+        if (!out.includes(s))
+            out.push(s);
+    return out;
+}

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/package.json

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

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 로 집행**한다. 코드 그래프도 같은 기준을 향한다.