@holmes-lab/holmes-kit 0.20.2 → 0.21.0

package/dist/holmes/rtm/link-census.js

@@ -0,0 +1,90 @@
+"use strict";
+// @implements A-SPEC-655
+/**
+ * RTM link census — which approved A-SPECs the code graph cannot see, and why.
+ *
+ * Measured 2026-09-16 on this repository: the dashboard census said coveragePct 100 while only
+ * 558/630 approved A-SPECs (88.6%) carried an `implements` edge; the other 72 were anchored only
+ * in test files the scanner deliberately excludes. "Unknown" and "absent" were the same number.
+ * The census here keeps the graph's contracts (tests and non-AST files stay OUT of the graph —
+ * cpg-scanner.ts:141-147 is a sealed decision) and classifies the gap instead:
+ *
+ *   test-only      anchored only in test files (a characterization / docs / CI slice — legitimate)
+ *   file-anchor    anchored only in files the injector can write but the indexer never parses
+ *   test-and-file  both of the above
+ *   weak-anchor    anchored nowhere, but a file inside the spec's own Files to Touch names the id
+ *   none           no trace at all
+ *
+ * The weak-anchor predicate is deliberately NARROW. The backlog card that proposed it ("any
+ * `A-SPEC-N` mention in a comment without a matching @implements") scores 817 false positives and
+ * 0 true positives on this repository; the narrowed form scores 0 and 0. Pure: every reader is
+ * injected, so the classifier is testable without a filesystem.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNLINKED_REASONS = void 0;
+exports.emptyByReason = emptyByReason;
+exports.pct1 = pct1;
+exports.weakMentionsFor = weakMentionsFor;
+exports.linkCensus = linkCensus;
+exports.UNLINKED_REASONS = ['test-only', 'file-anchor', 'test-and-file', 'weak-anchor', 'none'];
+function emptyByReason() {
+    return { 'test-only': 0, 'file-anchor': 0, 'test-and-file': 0, 'weak-anchor': 0, none: 0 };
+}
+/** Percentage with one decimal; a zero denominator reads as 0, never NaN. */
+function pct1(num, den) {
+    return den > 0 ? Math.round((num / den) * 1000) / 10 : 0;
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Files-to-Touch paths whose text names EXACTLY `id`. `A-SPEC-12` does not match `A-SPEC-120` or
+ * `A-SPEC-12.1`. A reader returning null (unreadable, absent) contributes nothing — an unreadable
+ * file is neither a mention nor evidence of its absence.
+ */
+function weakMentionsFor(id, fttFiles, readText) {
+    const re = new RegExp(String.raw `(?<![\w.-])${escapeRe(id)}(?!\w|\.\d)`);
+    const out = [];
+    for (const rel of fttFiles) {
+        const text = readText(rel);
+        if (text !== null && text !== undefined && re.test(text))
+            out.push(rel);
+    }
+    return [...new Set(out)].sort();
+}
+function invert(map) {
+    const byId = new Map();
+    for (const [file, ids] of Object.entries(map ?? {})) {
+        for (const id of ids ?? []) {
+            const list = byId.get(id) ?? [];
+            if (!list.includes(file))
+                list.push(file);
+            byId.set(id, list);
+        }
+    }
+    return byId;
+}
+function linkCensus(input) {
+    const implemented = new Set(input.implemented);
+    const tests = invert(input.testAnchors);
+    const files = invert(input.fileAnchors);
+    const byReason = emptyByReason();
+    const unlinked = [];
+    const ids = [...new Set(input.approvedIds)].sort();
+    let codeLinked = 0;
+    for (const id of ids) {
+        if (implemented.has(id)) {
+            codeLinked++;
+            continue;
+        }
+        const t = tests.get(id) ?? [];
+        const f = files.get(id) ?? [];
+        const mentions = t.length === 0 && f.length === 0 ? [...(input.weakMentions?.[id] ?? [])].sort() : [];
+        const reason = t.length && f.length ? 'test-and-file'
+            : t.length ? 'test-only'
+                : f.length ? 'file-anchor'
+                    : mentions.length ? 'weak-anchor'
+                        : 'none';
+        byReason[reason]++;
+        unlinked.push({ id, reason, anchoredIn: [...t, ...f].sort(), mentionedIn: mentions });
+    }
+    return { total: ids.length, codeLinked, codeLinkedPct: pct1(codeLinked, ids.length), unlinked, byReason };
+}

package/dist/holmes/rtm/trace-gaps.d.ts

@@ -0,0 +1,20 @@
+export interface UnlinkedSpec {
+    id: string;
+    ftt: string;
+}
+export interface TraceGap {
+    id: string;
+    file: string;
+    summary?: string | null;
+}
+/** Approved A-SPECs no scanned (production) file anchors, with their Files-to-Touch text; sorted by id. */
+export declare function unlinkedApproved(specs: ReadonlyArray<{
+    id: string;
+    type: string;
+    status: string;
+    sections?: Record<string, string>;
+}>, scanned: ReadonlyArray<{
+    implementsSpecs?: string[];
+}>): UnlinkedSpec[];
+/** (id, file) for every changed file an unlinked spec declares; sorted by id then file; no duplicates. */
+export declare function traceGaps(changedFiles: string[], unlinked: UnlinkedSpec[], summaryOf?: (id: string) => string | null): TraceGap[];

package/dist/holmes/rtm/trace-gaps.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unlinkedApproved = unlinkedApproved;
+exports.traceGaps = traceGaps;
+// @implements A-SPEC-658
+/**
+ * Trace gaps — the approved A-SPECs the graph cannot see when a file they declare changes.
+ *
+ * `rtm_impact` walks `implements` edges, and an approved A-SPEC that no production source anchors
+ * has none: it can never appear in any impact set, however directly the change concerns it. That
+ * is not "no impact", it is "cannot see" — and until now the two had the same shape (silence).
+ * Measured 2026-09-17 on this repository: 24 of the 72 unlinked approved specs (REQ-655's census)
+ * declare 34 scanned production files in their Files to Touch — change `hooks/pre-tool-use.ts`
+ * today and A-SPEC-202 / A-SPEC-250 stay unmentioned. The jarvis incident was the same shape
+ * (`_fmt_at` changed, REQ-347 unreported).
+ *
+ * Pure: the population is the same one REQ-655 counts (approved A-SPEC minus scanned anchors), the
+ * declared files come from REQ-656's item parser (REQ-654's token rule, globs excluded), and the
+ * result is an intersection. Information for `rtm_impact`, a `widen` reason for the impact gate;
+ * never a verdict on its own.
+ */
+const ftt_fulfilment_1 = require("./ftt-fulfilment");
+/** Approved A-SPECs no scanned (production) file anchors, with their Files-to-Touch text; sorted by id. */
+function unlinkedApproved(specs, scanned) {
+    const anchored = new Set();
+    for (const f of scanned)
+        for (const id of f.implementsSpecs ?? [])
+            anchored.add(id);
+    return specs
+        .filter((s) => s.type === 'A-SPEC' && s.status === 'approved' && !anchored.has(s.id))
+        .map((s) => ({ id: s.id, ftt: String(s.sections?.['Files to Touch'] ?? '') }))
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/** (id, file) for every changed file an unlinked spec declares; sorted by id then file; no duplicates. */
+function traceGaps(changedFiles, unlinked, summaryOf) {
+    const files = new Set(changedFiles.map((p) => p.replace(/\\/g, '/')));
+    if (files.size === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const u of unlinked) {
+        for (const item of (0, ftt_fulfilment_1.fttItems)(u.ftt)) {
+            if (!files.has(item.path))
+                continue;
+            const key = `${u.id} ${item.path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const gap = { id: u.id, file: item.path };
+            if (summaryOf) {
+                let s = null;
+                try {
+                    s = summaryOf(`SPEC:${u.id}`);
+                }
+                catch {
+                    s = null;
+                }
+                gap.summary = s;
+            }
+            out.push(gap);
+        }
+    }
+    return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+}

package/dist/holmes/server/dashboard-launcher.d.ts

@@ -1,3 +1,4 @@
+import { UnlinkedReason } from '../rtm/link-census';
 /** Honesty summary of what a launched dashboard shows — derived from the endpoints it serves. */
 export interface DashboardCensus {
     reqCount: number;
@@ -13,6 +14,25 @@ export interface DashboardCensus {
  * coveragePct never divides by zero.
  */
 export declare function dashboardCensus(rtm: any, heatmap: any): DashboardCensus;
+/** The honesty census plus the code-link axis. `dashboardCensus` above stays byte-identical (pinned). */
+export interface DashboardCensusExtended extends DashboardCensus {
+    codeLinkedPct: number;
+    codeLinkedCount: number;
+    unlinkedCount: number;
+    unlinkedByReason: Record<UnlinkedReason, number>;
+    excluded: {
+        total: number;
+        retired: number;
+        unmapped: number;
+        nonSpec: number;
+    };
+}
+/**
+ * Pure: the pinned census plus the code-link axis from `/api/rtm`'s `linkCensus`, `coveragePct`
+ * with one decimal, and the documents the axes exclude (retired / unmapped / non-spec) counted
+ * with their reasons. A payload without `linkCensus` (an older server) folds to zeros, never throws.
+ */
+export declare function dashboardCensusExtended(rtm: any, heatmap: any): DashboardCensusExtended;
 export interface LaunchResult {
     url: string;
     port: number;

package/dist/holmes/server/dashboard-launcher.js

@@ -1,10 +1,12 @@
 "use strict";
-// @implements A-SPEC-545.3
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dashboardCensus = dashboardCensus;
+exports.dashboardCensusExtended = dashboardCensusExtended;
 exports.ensureDashboard = ensureDashboard;
 exports._resetLauncher = _resetLauncher;
 exports._stopAll = _stopAll;
+// @implements A-SPEC-545.3
+const link_census_1 = require("../rtm/link-census");
 /**
  * @implements A-SPEC-545.3
  * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
@@ -24,6 +26,27 @@ function dashboardCensus(rtm, heatmap) {
         findingsScanned: heatmap?.findingsScanned === true,
     };
 }
+/**
+ * Pure: the pinned census plus the code-link axis from `/api/rtm`'s `linkCensus`, `coveragePct`
+ * with one decimal, and the documents the axes exclude (retired / unmapped / non-spec) counted
+ * with their reasons. A payload without `linkCensus` (an older server) folds to zeros, never throws.
+ */
+function dashboardCensusExtended(rtm, heatmap) {
+    const base = dashboardCensus(rtm, heatmap);
+    const lc = rtm?.linkCensus;
+    const retired = rtm?.retired?.count ?? 0;
+    const unmapped = rtm?.unmapped?.count ?? 0;
+    const nonSpec = rtm?.nonSpec?.count ?? 0;
+    return {
+        ...base,
+        coveragePct: (0, link_census_1.pct1)(heatmap?.completeCount ?? 0, heatmap?.pipelineCount ?? 0),
+        codeLinkedPct: typeof lc?.codeLinkedPct === 'number' ? lc.codeLinkedPct : 0,
+        codeLinkedCount: typeof lc?.codeLinked === 'number' ? lc.codeLinked : 0,
+        unlinkedCount: Array.isArray(lc?.unlinked) ? lc.unlinked.length : 0,
+        unlinkedByReason: { ...(0, link_census_1.emptyByReason)(), ...(lc?.byReason ?? {}) },
+        excluded: { total: retired + unmapped + nonSpec, retired, unmapped, nonSpec },
+    };
+}
 const live = new Map();
 /**
  * @implements A-SPEC-545.3

package/dist/holmes/server/dashboard.js

@@ -55,6 +55,9 @@ const ast_store_1 = require("../cpg/foundation/ast-store");
 const cfg_1 = require("../cpg/foundation/cfg");
 const cdg_1 = require("../cpg/foundation/cdg");
 const cfg_view_1 = require("./cfg-view");
+const link_census_1 = require("../rtm/link-census");
+const test_scope_1 = require("../rtm/test-scope");
+const file_anchors_1 = require("../rtm/file-anchors");
 /**
  * Start a lightweight standalone Node.js HTTP server for interactive dashboard & RTM visualization.
  *
@@ -94,10 +97,44 @@ async function startDashboardServer(options) {
                     for (const s of f.implementsSpecs)
                         implementedSpecIds.add(s);
                 }
+                // @implements A-SPEC-655 — the code-link axis, with a reason on every unlinked A-SPEC.
+                // Tests and non-AST files stay OUT of the graph (cpg-scanner.ts:141-147 is sealed); their
+                // anchors are read off-graph so the census can tell "anchored where the graph cannot see"
+                // from "no trace at all". Measured 2026-09-16 on this repository: 72 of 630 approved
+                // A-SPECs were invisible to the graph and every one of them was a test-only slice.
+                const approvedAspecs = specs.filter((s) => s.id.startsWith('A-SPEC') && s.status === 'approved');
+                const testAnchors = (0, test_scope_1.scanTestAnchors)(root);
+                const fileAnchors = (0, file_anchors_1.scanFileAnchors)(root);
+                const anchoredAnywhere = new Set(implementedSpecIds);
+                for (const ids of [...Object.values(testAnchors), ...Object.values(fileAnchors)])
+                    for (const id of ids)
+                        anchoredAnywhere.add(id);
+                const readRel = (rel) => {
+                    const abs = path.resolve(root, rel);
+                    if (!abs.startsWith(root + path.sep))
+                        return null; // a Files-to-Touch line is text, not a path we trust
+                    try {
+                        return fs.readFileSync(abs, 'utf8');
+                    }
+                    catch {
+                        return null;
+                    }
+                };
+                const weakMentions = {};
+                for (const s of approvedAspecs) {
+                    if (anchoredAnywhere.has(s.id))
+                        continue;
+                    const ftt = String(s.sections?.['Files to Touch'] ?? '');
+                    const tokens = [...new Set(ftt.match(/[\w@.*-]+(?:\/[\w@.*-]+)+/g) ?? [])].filter((t) => !t.includes('*'));
+                    weakMentions[s.id] = (0, link_census_1.weakMentionsFor)(s.id, tokens, readRel);
+                }
+                const census = (0, link_census_1.linkCensus)({ approvedIds: approvedAspecs.map((s) => s.id), implemented: implementedSpecIds, testAnchors, fileAnchors, weakMentions });
+                const reasonOf = new Map(census.unlinked.map((u) => [u.id, u.reason]));
                 const enrichedSpecs = specs.map((s) => {
                     const isA = s.id.startsWith('A-SPEC');
                     const covered = isA ? implementedSpecIds.has(s.id) : s.status === 'approved';
-                    return { ...s, covered, legacyStatus: !isCanonicalStatus(s.status) };
+                    const reason = reasonOf.get(s.id);
+                    return { ...s, covered, legacyStatus: !isCanonicalStatus(s.status), ...(reason ? { unlinkedReason: reason } : {}) };
                 });
                 // Two axes, never one number. Approval (a spec was signed off) and implementation (code is
                 // anchored to it) answer different questions, and a spec whose status is outside the
@@ -156,6 +193,7 @@ async function startDashboardServer(options) {
                     coveredCount,
                     approval,
                     implementation,
+                    linkCensus: census,
                     unmapped,
                     nonSpec,
                     retired,
@@ -1131,7 +1169,7 @@ function renderDashboardHtml() {
                 <div class="tree-row tree-row-aspec">
                   <div class="tree-label">🔵 <strong>\${escapeHtml(a.id)}</strong>: \${escapeHtml(a.title || '')}</div>
                   <div>
-                    <span class="neighbor-rel \${a.covered ? 'badge-covered' : 'badge-uncovered'}" style="margin-right:8px;">\${a.covered ? 'COVERED' : 'UNCOVERED'}</span>
+                    <span class="neighbor-rel \${a.covered ? 'badge-covered' : 'badge-uncovered'}" style="margin-right:8px;">\${a.covered ? 'COVERED' : 'UNLINKED · ' + escapeHtml(a.unlinkedReason || 'none')}</span>
                     <button class="jump-btn" onclick="focusSpecInGraph('\${escapeHtml(a.id)}')">🕸️ View in Graph</button>
                   </div>
                 </div>

package/package.json

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

@@ -82,6 +82,13 @@ Criteria · Non-Functional · Assumptions · Open Questions.** 필수 필드: `r
 부모 REQ의 Success Criteria가 이 설계로 어떻게 달성되는지가 본문이다. Open Questions는 비워두는
 칸이 아니다 — 아직 결정하지 않은 것을 결정하지 않았다고 적는 곳이고, 닫을 때는 근거와 함께 닫는다.
 
+**관측을 신설하거나 좌표를 바꾸는 슬라이스**(계측·원장·카운터·지표·이벤트 기록)는 `## Non-Functional`에
+`- [observability] <무엇을 기록하고 어디서 어떤 키로 읽는가>` 의무를 적는다. 기록 쪽만 검증한 테스트는
+읽는 쪽이 보는 좌표에 없는 기록을 잡지 못한다 — jarvis 실사고(2026-09-08): `kind`가 고정돼 조회가
+구조적으로 0이었고, 그 0 위에서 설계 결정이 두 번 내려졌다. 이 의무는 T-SPEC의 `[observability]`
+케이스와 대응되어야 하며, 대응이 없으면 `review_scope`·`maintenance_analyze`가 `obligationGaps`로
+**보고**한다 — 차단이 아니라 보고다(`obligationGapsFor`; 태그 어휘는 열려 있어 새 필드가 필요 없다).
+
 ## Files to Touch를 확정하기 전에 — 설계-시점 영향 범위 읽기
 
 A-SPEC의 Files to Touch는 **스코프 선언**이고, 그래프는 그 선언이 무엇을 빠뜨리는지 이미 안다.
@@ -117,6 +124,10 @@ T-SPEC 필수 섹션은 4분면 그대로다: **Normal · Corner · Negative ·
 케이스인지**가 드러나게 쓴다. 그리고 frontmatter `depends_on: [대상 A-SPEC]` — 이 간선이 없으면
 승인해도 코드 게이트가 열리지 않는다 — 그때 게이트가 `depends_on`을 지목한다(`promote-slice`의 「T-SPEC 거부는 상태를 구별해 말한다」).
 
+H-SPEC에 `[observability]` 의무가 있으면 T-SPEC은 **기록→조회 왕복** 케이스를
+`- [observability] Given … When … Then …`으로 적는다: 쓰기 API를 부르고, **읽는 쪽이 실제로 쓰는 읽기
+API**로 같은 좌표를 조회해 행이 있음을 단언한다. 태그는 줄 시작에서만 인식된다(`nonfunctional.ts`).
+
 ## 흔한 오해
 
 | 오해 | 사실 |

package/playbooks/tdd-slice/PLAYBOOK.md

@@ -57,6 +57,10 @@ holmes는 기계적으로 판별한다: `red-error`로는 red→green 시퀀스
   요구한다.
 - `[명예제]` 테스트를 쓰기 전에 **그 테스트를 실패시킬 프로덕션 변경을 한 문장으로 말하라**. 말할
   수 없다면 그 테스트는 무엇도 지키지 못한다. (C층 `kills:`가 이를 스펙 필드로 승격한다.)
+- `[obligationGaps]` 관측을 신설하는 슬라이스는 **기록→조회 왕복**을 단언한다 — 기록 함수를 부른 뒤
+  소비자가 쓰는 읽기 경로로 같은 좌표를 읽는다. H-SPEC `[observability]` 의무와 T-SPEC 케이스 태그의
+  대응을 `obligationGapsFor`가 검사해 `obligationGaps`로 보고한다(집행 표는 그대로: 이것은 게이트가
+  아니라 보고다).
 
 ## 집행 요약