@holmes-lab/holmes-kit 0.20.2 → 0.22.0

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.22.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,29 @@ T-SPEC 필수 섹션은 4분면 그대로다: **Normal · Corner · Negative ·
 케이스인지**가 드러나게 쓴다. 그리고 frontmatter `depends_on: [대상 A-SPEC]` — 이 간선이 없으면
 승인해도 코드 게이트가 열리지 않는다 — 그때 게이트가 `depends_on`을 지목한다(`promote-slice`의 「T-SPEC 거부는 상태를 구별해 말한다」).
 
+### `kills:` 문법 — `where`는 소스 조각이지 파일 경로가 아니다
+
+T-SPEC frontmatter의 `kills`는 판별력을 스펙 필드로 승격한 것이다: 엔진(`test_run --mutate`)이 A-SPEC을
+`@implements`하는 **프로덕션 소스 안의 리터럴 `where`를 `mutate`로 치환**하고, 커버 테스트가 붉어지는지
+본다. 그래서 `where`는 그 소스에 **글자 그대로 존재하는 조각**이어야 한다.
+
+```yaml
+kills:
+  - where: "if (reason === '')"
+    mutate: "if (false)"
+```
+
+`where: src/holmes/foo.ts`처럼 파일 경로를 적거나 `mutate`에 산문("검사를 제거한다")을 적으면 아무것도
+적용되지 않는다 — 2026-09-17 실측에서 이 저장소의 22개 엔트리 전부가 그 모양이었다. 이제 두 곳이 그것을
+말한다: T-SPEC 승인(`spec_approve`·`approval_status`)이 적용 불가 엔트리를 `killsAdvisory`
+(`kills-unapplicable`) **소견으로 보고**하고(봉인은 그대로 된다), `test_run --mutate`는 적용되지 않은
+엔트리를 `unapplied`로 `survivors`와 구별해 싣는다. `survivors: []`는 `unapplied`가 비어 있을 때만 "생존
+변이 없음"이다.
+
+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`로 보고한다(집행 표는 그대로: 이것은 게이트가
+  아니라 보고다).
 
 ## 집행 요약