@holmes-lab/holmes-kit 0.20.2 → 0.21.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.21.0] - 2026-09-17
+
+The backlog-hardening cycle: the RTM stops claiming coverage it cannot see, sealing reports what a
+spec's Files to Touch left behind, and a known defect pinned by a test now carries a marker with an
+expiry — reported as debt, never a block, until the grace runs out.
+
+### Added
+- **Code-link census with reasons** (A-SPEC-655). `rtm_dashboard` and `/api/rtm` report `codeLinkedPct`,
+  `unlinkedCount` and `unlinkedByReason` (`test-only`, `file-anchor`, `test-and-file`, `weak-anchor`, `none`)
+  next to the old `coveragePct`, which still reads 100 while 11.4% of approved specs have no `implements`
+  edge. The scanner now reads every anchor the injector can write (`.sh/.yml/.toml/...` file anchors were
+  planted and never indexed). Measured here: 636 approved, 563 linked, 73 unlinked — 72 test-only.
+- **Files-to-Touch fulfilment advisory** (A-SPEC-656). At `spec_approve` and in `approval_status`, a sealed
+  A-SPEC whose declared paths do not exist is reported as `missing`, `moved` (same basename elsewhere) or
+  `alternatives`; the verdict is appended to `.ax/ledger/ftt-fulfilment.<replica>.jsonl`. Never blocks.
+  Four genuinely unfulfilled paths on three sealed specs were found on the first run.
+- **Trace gaps** (A-SPEC-658). `rtm_impact` returns `traceGaps` — approved specs that declare a scanned
+  production file in Files to Touch yet anchor only tests — and `impact_gate_check` answers `trace-gap`
+  with remediation instead of silently widening. Measured here: 21 specs, 29 spec/file pairs.
+- **`@known-defect(reason, expires=YYYY-MM-DD)`** (A-SPEC-660) and constitution article **ART-9**. A test
+  that pins a known defect as its expected value carries the marker on a comment line; the Stop hook walks
+  test files, lists unexpired markers on the `tracked` channel as `known-defect debt`, and blocks only when
+  a marker has expired or cannot be read (`no-reason`, `no-expires`, `bad-date`). String literals are
+  stripped first, the expiry day itself counts as expired (UTC), and a walk that cannot start is no signal.
+  Walk cost ≈61 ms per Stop on this tree; zero markers exist yet.
+- **`[observability]` obligation in the authoring playbooks** (A-SPEC-659). A slice that creates a record
+  must declare the obligation in its H-SPEC and carry a record→read round-trip case in its T-SPEC; the
+  existing tag-correspondence check reports the gap. Pinned so the prose cannot claim the gate blocks.
+
+### Fixed
+- **Windows-spelled in-project `.ax` paths are judged by location, not spelling** (A-SPEC-657). A Bash
+  write to `C:\proj\.ax\...`, `/c/proj/.ax/...` or `C:/proj/.ax/...` reached the protected-path check
+  as an outside-project path and was masked out of it; drive, MSYS and backslash spellings now normalise
+  to the project root first. Found by the Windows agent's residual-red evidence, reproduced on macOS.
+
+### Measured
+- macOS: 515 suites / 6,534 passed / 11 skipped; every slice recorded red-assertion → green; official
+  `test_run` green at b18ff0bf, last-green recorded.
+- `kills` mutation testing: all 22 existing entries write `where` as a file path and `mutate` as prose,
+  so the literal-replacement engine applies none of them and `--mutate` reports `survivors: []`. Making
+  `kills` mandatory is deferred behind a `where`-validation slice (`docs/goals/EVIDENCE-kills-cost-2026-09-17.md`).
+- Linux (OrbStack Ubuntu 24.04 arm64, Node 24): 514 / 515 suites green; the one red is the documented
+  `tree-sitter@0.21.1` source-compile failure against Node 24 headers on ARM Linux (README, unchanged since
+  0.19.4) — the npx wiring case installs the packed tarball and that install fails there. On Node 22 the
+  same tarball installs, the MCP handshake answers with the package version, and the suite is green.
+- Windows: not re-run for this release; the only Windows-relevant change is A-SPEC-657, reproduced and
+  pinned on macOS from the Windows agent's evidence.
+
 ## [0.20.2] - 2026-09-16
 
 Two findings the Windows cycle recorded and could not close, closed — without giving autonomy or the

package/dist/.build-id

@@ -1 +1 @@
-5796f530-mu3b082d
+bdbd4f85-mu4ywfad

package/dist/holmes/governance/constitution.d.ts

@@ -1,5 +1,6 @@
 import { Spec } from '../spec/spec-parser';
 import type { TestOutcome } from '../review/test-runner';
+import type { KnownDefect, MalformedMarker } from '../rtm/known-defects';
 /**
  * L1 — Governance CONSTITUTION (target-architecture §7 L1).
  *
@@ -26,6 +27,16 @@ export interface ConstitutionViolation {
 }
 export interface ConstitutionContext {
     specs: Spec[];
+    /**
+     * @implements A-SPEC-660
+     * `@known-defect` markers the hook judged EXPIRED or could not read — ART-9's evidence. Supplied by
+     * the hook like every other article's evidence; absent means silent (no signal, not clean).
+     * Unexpired markers never reach the constitution: they are debt on the tracked channel.
+     */
+    knownDefects?: {
+        expired: KnownDefect[];
+        malformed: MalformedMarker[];
+    };
     /**
      * @implements A-SPEC-160
      * Recorded review findings, for ART-6. Supplied by the hook, like ART-4's evidence — the

package/dist/holmes/governance/constitution.js

@@ -42,13 +42,18 @@ exports.ARTICLES = {
     'ART-4': 'Coverage honesty — declared coverage must be backed by real anchored test cases, not prose',
     'ART-5': 'Approval is out-of-band — a spec cannot self-approve; governance config cannot be self-written',
     'ART-8': 'Test-first is observed — a changed A-SPEC must show a recorded red-assertion→green sequence before it is done (a red-error is not a valid RED)',
+    // @implements A-SPEC-660
+    'ART-9': '알려진 결함을 기대값으로 고정한 단언은 표식(@known-defect)과 만료일을 가진다 — 만료가 지났거나 표식이 깨진 단언은 미완이다 (미만료 표식은 tracked 로 보고만 된다: 우회는 때로 옳은 선택이다)',
 };
 function verifyConstitution(ctx) {
     const governed = (0, spec_types_1.filterGoverned)(ctx.specs);
     // @implements A-SPEC-191 (§4b) — the early return may NOT swallow recorded findings: a project
     // that reviews before authoring specs (measured: adopt flow, reverse_scan first) held an open
     // critical while Stop passed, because ART-7 was accidentally coupled to spec-graph existence.
-    if (governed.length === 0 && (ctx.findings ?? []).length === 0)
+    // @implements A-SPEC-660 — nor may it swallow judged @known-defect markers: an expired bypass in a
+    // spec-less project is still an expired bypass.
+    const knownDefectEvidence = (ctx.knownDefects?.expired.length ?? 0) + (ctx.knownDefects?.malformed.length ?? 0) > 0;
+    if (governed.length === 0 && (ctx.findings ?? []).length === 0 && !knownDefectEvidence)
         return []; // rows 가 아니라 원본 기준 — 오염 행만 있는 원장도 감식 대상이다
     const resolve = (id) => ctx.specs.find((s) => s.id === id) ?? null;
     const v = [];
@@ -175,5 +180,14 @@ function verifyConstitution(ctx) {
             v.push({ article: 'ART-7', detail: `finding ${f.id}${gist}: 해소가 갈라진 빌드에서 봉인되었습니다 (basis ${f.basis}) — 현재 빌드로 재검증해 다시 기록하십시오` });
         }
     }
+    // @implements A-SPEC-660 — ART-9. An expired marker is a bypass whose grace ran out; an unreadable
+    // one is a debt nobody can see. Unexpired markers never reach here (tracked channel). Absent input
+    // is silence, not a clean verdict — the hook decides whether it could look.
+    for (const k of ctx.knownDefects?.expired ?? []) {
+        v.push({ article: 'ART-9', detail: `${k.file}:${k.line}: known defect "${k.reason}" expired ${k.expires} — fix the root cause or renew the marker with a reason (ART-9)` });
+    }
+    for (const m of ctx.knownDefects?.malformed ?? []) {
+        v.push({ article: 'ART-9', detail: `${m.file}:${m.line}: @known-defect marker is ${m.why} — a marker that cannot be read is a debt nobody can see (ART-9)` });
+    }
     return v;
 }

package/dist/holmes/guardrail/impact-gate.d.ts

@@ -13,7 +13,7 @@ import type { EvidenceArtifact } from '../mcp/maintenance-evidence';
  */
 export type EditDecision = 'allow' | 'widen' | 'refuse';
 export interface EditEvidenceReason {
-    code: 'no-analysis' | 'basis-drift' | 'target-out-of-scope' | 'contract-untested' | 'unproven-absence' | 'architecture-unchecked' | 'target-drift' | 'basis-unverifiable' | 'security-unchecked' | 'compatibility-unchecked';
+    code: 'no-analysis' | 'basis-drift' | 'target-out-of-scope' | 'contract-untested' | 'unproven-absence' | 'architecture-unchecked' | 'target-drift' | 'basis-unverifiable' | 'security-unchecked' | 'compatibility-unchecked' | 'trace-gap';
     detail: string;
 }
 export interface EditEvidenceInput {
@@ -30,6 +30,15 @@ export interface EditEvidenceInput {
      * is caught even while HEAD sits still.
      */
     currentTargetDigest?: string | null;
+    /**
+     * @implements A-SPEC-658
+     * Approved A-SPECs that declare `target` in their Files to Touch but are anchored by no source —
+     * computed by the caller (the handler owns the spec store and the scan; this module stays pure).
+     */
+    traceGaps?: Array<{
+        id: string;
+        file: string;
+    }>;
 }
 export interface EditEvidenceVerdict {
     decision: EditDecision;

package/dist/holmes/guardrail/impact-gate.js

@@ -80,6 +80,8 @@ const REMEDIATION = {
     'security-unchecked': 'The security axis was never examined — re-run maintenance_analyze against a tree it can actually scan so data-flow reachability is walked.',
     'compatibility-unchecked': 'The compatibility axis was never examined — re-run maintenance_analyze where the spec store is readable so breaking-change declarations can be read.',
     'basis-unverifiable': 'The analysis recorded no digest for this file, or the file cannot be read now, so drift cannot be ruled out — re-run maintenance_analyze with persist: true to take a verifiable basis.',
+    // @implements A-SPEC-658
+    'trace-gap': 'The target is declared in the Files to Touch of approved A-SPEC(s) that no source file anchors, so the graph cannot see their impact — anchor the implementing source (spec_remediate) or include those specs in the analysis request and re-run maintenance_analyze.',
 };
 const RANK = { allow: 0, widen: 1, refuse: 2 };
 function evaluateEditEvidence(inputArgs) {
@@ -89,6 +91,21 @@ function evaluateEditEvidence(inputArgs) {
     let decision = 'allow';
     const escalate = (next) => { if (RANK[next] > RANK[decision])
         decision = next; };
+    // @implements A-SPEC-658 — a trace gap is "we could not look" wearing a file's name: the target is
+    // declared by an approved A-SPEC no source anchors, so the graph's silence about that spec is
+    // ignorance, not absence. It widens, never lowers a refusal, and never speaks for one (the
+    // primary remediation below stays the refusal's). The caller computes the list; this stays pure.
+    const traceGapReason = () => {
+        const gaps = inputArgs.traceGaps ?? [];
+        if (gaps.length === 0)
+            return;
+        const ids = [...new Set(gaps.map((g) => g.id))].sort();
+        reasons.push({
+            code: 'trace-gap',
+            detail: `${target} is declared by approved ${ids.join(', ')} that no source anchors — the graph cannot see their impact.`,
+        });
+        escalate('widen');
+    };
     const artifact = inputArgs.artifact;
     if (!artifact) {
         // The proportional path: ordinary prose needs no graph evidence. A governing document does, and
@@ -96,6 +113,7 @@ function evaluateEditEvidence(inputArgs) {
         if (lowRisk)
             return { decision: 'allow', reasons: [], remediation: '', lowRisk: true };
         reasons.push({ code: 'no-analysis', detail: `No impact analysis backs an edit to ${target}.` });
+        traceGapReason(); // two reasons, both stated; the remediation stays the refusal's
         return { decision: 'refuse', reasons, remediation: REMEDIATION['no-analysis'], lowRisk };
     }
     // (2) An analysis describes one commit. Once HEAD moves, its claims are about a tree that no
@@ -183,6 +201,7 @@ function evaluateEditEvidence(inputArgs) {
         });
         escalate('widen');
     }
+    traceGapReason();
     // Lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal.
     const primary = reasons.find((r) => r.code === 'basis-drift')
         ?? reasons.find((r) => r.code === 'target-drift')

package/dist/holmes/guardrail/risk-classifier.d.ts

@@ -13,6 +13,7 @@ export declare function rmCommandTargets(cmd: string): string[];
  * project and stays protected, so nothing is weakened for the case the rule exists to cover. With no
  * projectRoot supplied the command is returned unchanged — unknown scope stays conservative.
  */
+export declare function normalizeWindowsPathSpellings(cmd: string): string;
 export declare function scopeAxToProject(cmd: string, projectRoot?: string): string;
 /**
  * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so

package/dist/holmes/guardrail/risk-classifier.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rmCommandTargets = rmCommandTargets;
+exports.normalizeWindowsPathSpellings = normalizeWindowsPathSpellings;
 exports.scopeAxToProject = scopeAxToProject;
 exports.normalizeCommandPaths = normalizeCommandPaths;
 exports.classifyReversibility = classifyReversibility;
@@ -248,11 +249,33 @@ const DESTRUCTIVE_CMD_CHECKS = [
  * project and stays protected, so nothing is weakened for the case the rule exists to cover. With no
  * projectRoot supplied the command is returned unchanged — unknown scope stays conservative.
  */
+// @implements A-SPEC-657 — Windows spellings (drive `C:/…`, `C:\…`, MSYS `/c/…`) of a path INSIDE
+// the project were masked as another project's, and the backslash spelling matched no `.ax/` rule at
+// all (measured on Windows 2026-09-17, reproduced on macOS 4/4). The five `.ax` rules below consume
+// the string this function hands them, so one normalisation closes every spelling at once. Pure
+// string logic: no process.platform, no filesystem — a POSIX suite verifies the Windows verdicts.
+function normalizeWindowsPathSpellings(cmd) {
+    return cmd
+        // `C:\a\b`, `C:/a/b` → `c:/a/b` — a drive is one letter, a colon and a separator, at a token
+        // boundary; `http://` and `a:b` never match.
+        .replace(/(^|[\s'"=(])([A-Za-z]):[\\/]([^\s'"()]*)/g, (_m, pre, d, rest) => `${pre}${d.toLowerCase()}:/${rest.replace(/\\/g, '/')}`)
+        // MSYS/Git-Bash `/c/a/b` → `c:/a/b`.
+        .replace(/(^|[\s'"=(])\/([A-Za-z])\/(?=[^\s'"()/])/g, (_m, pre, d) => `${pre}${d.toLowerCase()}:/`);
+}
 function scopeAxToProject(cmd, projectRoot) {
+    const spelled = normalizeWindowsPathSpellings(cmd);
     if (!projectRoot)
-        return cmd;
-    const root = projectRoot.replace(/\\/g, '/').replace(/\/+$/, '');
-    return cmd.replace(/(^|[\s'"=(:])(\/[^\s'"()]*\/\.ax\/[^\s'"()]*)/g, (m, pre, abs) => (abs === root || abs.startsWith(`${root}/`) ? m : `${pre}<other-project-path>`));
+        return spelled;
+    const root = normalizeWindowsPathSpellings(projectRoot.replace(/\\/g, '/')).replace(/\/+$/, '');
+    // NTFS folds case (foldsCaseBySyntax says the same of a drive letter); POSIX does not.
+    const drive = /^[a-z]:\//.test(root);
+    const inside = (abs) => {
+        const a = drive ? abs.toLowerCase() : abs;
+        const r = drive ? root.toLowerCase() : root;
+        return a === r || a.startsWith(`${r}/`);
+    };
+    // The pre-class no longer admits `:` — that is what cut `C:/proj/.ax/x` down to `/proj/.ax/x`.
+    return spelled.replace(/(^|[\s'"=(])((?:[a-z]:)?\/[^\s'"()]*\/\.ax\/[^\s'"()]*)/g, (m, pre, abs) => (inside(abs) ? m : `${pre}<other-project-path>`));
 }
 // `state` joined the protected set with P3 (REQ-134): it holds the constitution-debt and the
 // last-green baseline, so a single-file `rm` there would bypass the WRITE_CODE debt gate — measured

package/dist/holmes/hooks/stop.d.ts

@@ -1,6 +1,8 @@
 import { PendingRequest } from '../governance/approval-queue';
 import { Spec } from '../spec/spec-parser';
 import type { TestOutcome } from '../review/test-runner';
+import { type KnownDefectJudgement } from '../rtm/known-defects';
+export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
 /**
  * @implements A-SPEC-100.2
  * Stop-hook governance gate (Phase-2 #1: push, not pull).
@@ -22,6 +24,13 @@ import type { TestOutcome } from '../review/test-runner';
 export interface StopEvidence {
     /** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
     testCasesByAspec?: Record<string, number>;
+    /**
+     * @implements A-SPEC-660
+     * `@known-defect` markers found in the workspace's test files, judged against the clock by the
+     * CLI: unexpired ones are DEBT (tracked, never blocking), expired and malformed ones are ART-9.
+     * `undefined` is no signal — a walk that could not run must not read as marker-free.
+     */
+    knownDefects?: KnownDefectJudgement;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

package/dist/holmes/hooks/stop.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
+exports.collectKnownDefects = collectKnownDefects;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
 exports.dependencyReappraisals = dependencyReappraisals;
@@ -76,6 +77,55 @@ const pre_tool_use_1 = require("./pre-tool-use");
 const governance_history_1 = require("../guardrail/governance-history");
 const constitution_debt_1 = require("../governance/constitution-debt");
 const root_1 = require("../project/root");
+const known_defects_1 = require("../rtm/known-defects");
+const test_files_1 = require("../cpg/test-files");
+// @implements A-SPEC-660 — the I/O half of the known-defect marker: walk the workspace's test files
+// (the same directory rule and test predicate ART-4's anchor scan uses), parse each for markers,
+// judge them against the injected clock. A walk that cannot START is NO SIGNAL (undefined) — never
+// an empty judgement; an unreadable file inside a readable tree is skipped like scanTestAnchors does.
+function collectKnownDefects(root, now) {
+    try {
+        if (!fs.statSync(root).isDirectory())
+            return undefined;
+        const found = { markers: [], malformed: [] };
+        const walk = (dir) => {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist' || e.name === '.ax')
+                    continue;
+                const abs = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    walk(abs);
+                    continue;
+                }
+                const rel = path.relative(root, abs).split(path.sep).join('/');
+                if (!(0, test_files_1.isTestFile)(rel))
+                    continue;
+                let text;
+                try {
+                    text = fs.readFileSync(abs, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                const r = (0, known_defects_1.knownDefectsIn)(text, rel);
+                found.markers.push(...r.markers);
+                found.malformed.push(...r.malformed);
+            }
+        };
+        walk(root);
+        return (0, known_defects_1.judgeKnownDefects)(found, now);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * @implements A-SPEC-534.4
  * ART-8 evidence (I/O half): the A-SPECs whose DIRTY source files carry an @implements anchor. git is
@@ -441,6 +491,7 @@ function governanceLostPreflight(specsDir, projectRoot) {
 const TRACK_LABELS = {
     'ART-8': 'RED-first',
     'ART-2': 'code-graph cycles',
+    'ART-9': 'known-defect debt',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -476,6 +527,8 @@ function evaluateStop(specs, evidence) {
         specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
         redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
         cycles: evidence?.cycles,
+        // @implements A-SPEC-660 — only the expired and unreadable markers are the constitution's business.
+        ...(evidence?.knownDefects ? { knownDefects: { expired: evidence.knownDefects.expired, malformed: evidence.knownDefects.malformed } } : {}),
     });
     // @implements A-SPEC-534.4 — `track` records ART-8 findings without blocking the turn. Computed
     // separately (the constitution stays silent on ART-8 outside strict) and returned in `tracked` for
@@ -497,6 +550,13 @@ function evaluateStop(specs, evidence) {
         if (t.length)
             tracked = [...(tracked ?? []), ...t];
     }
+    // @implements A-SPEC-660 — unexpired known-defect markers are DEBT: recorded on the tracked channel
+    // with file, line, reason and expiry, never a block. A bypass is sometimes the right call; the
+    // marker exists so the next person can see it, and ART-9 speaks only once the grace runs out.
+    if (evidence?.knownDefects && evidence.knownDefects.unexpired.length > 0) {
+        const t = evidence.knownDefects.unexpired.map((k) => ({ article: 'ART-9', detail: `${k.file}:${k.line}: known defect "${k.reason}" until ${k.expires}` }));
+        tracked = [...(tracked ?? []), ...t];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -1079,7 +1139,9 @@ if (require.main === module) {
                 });
             }
             catch { /* maintenance, never a hook failure */ }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec });
+            // @implements A-SPEC-660 — the marker walk: no signal when it cannot run (never a clean verdict).
+            const knownDefects = collectKnownDefects(stopProjectRoot(), new Date());
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

package/dist/holmes/mcp/handlers/graph-operations.d.ts

@@ -64,6 +64,7 @@ export declare function createGraphOperationsHandlers(context: GraphOperationsCo
             reason: "hub" | "depth";
             inDegree?: number;
         }[] | undefined;
+        traceGaps?: import("../../rtm/trace-gaps").TraceGap[] | undefined;
         summariesOmitted?: number | undefined;
         impacted: string[];
         impactedSummaries: {

package/dist/holmes/mcp/handlers/graph-operations.js

@@ -45,6 +45,7 @@ const root_1 = require("../../project/root");
 const rtm_builder_1 = require("../../rtm/rtm-builder");
 const graph_store_1 = require("../../rtm/graph-store");
 const assoc_arm_1 = require("../../assoc/assoc-arm");
+const trace_gaps_1 = require("../../rtm/trace-gaps");
 // @implements A-SPEC-478 — the semantic tier runtime stays at the async reindex edge.
 const tier_1 = require("../../semantic/tier");
 const vector_cache_1 = require("../../semantic/vector-cache");
@@ -119,7 +120,8 @@ function createGraphOperationsHandlers(context) {
             // drops outdated/legacy), which is exactly what let this in. Diagnosis (rtm_check) and
             // matching (issue_localize / maintenance_analyze) keep their own populations — the replay
             // pins were measured on them.
-            const specs = (await context.listSpecs()).filter((s) => s.status === 'approved');
+            const specsAll = await context.listSpecs();
+            const specs = specsAll.filter((s) => s.status === 'approved');
             // @implements A-SPEC-283
             // Reuse the persisted graph when its basis still holds. Measured: on the warm path the graph
             // build is ~81% of the cost and reopening is ~0ms. `scanDigest` is the field that makes this
@@ -181,11 +183,26 @@ function createGraphOperationsHandlers(context) {
                     return { id, summary };
                 });
                 const summariesOmitted = impacted.length - shownSummaries.length;
+                // @implements A-SPEC-658 — the specs the graph CANNOT see for these changes: approved,
+                // anchored by no production source, and declaring a changed symbol's file. Information
+                // beside the closure, never inside it; unresolved symbols yield no files and therefore no
+                // guess.
+                const changedFiles = a.changed.flatMap((qn) => g.codeNodeIds(qn))
+                    .map((id) => id.slice(id.lastIndexOf('@') + 1)).filter((f) => f !== '');
+                const gaps = changedFiles.length > 0
+                    ? (0, trace_gaps_1.traceGaps)(changedFiles, (0, trace_gaps_1.unlinkedApproved)(specsAll, scanned), (id) => { try {
+                        return g.summaryOf(id);
+                    }
+                    catch {
+                        return null;
+                    } })
+                    : [];
                 answered = true;
                 return {
                     impacted,
                     impactedSummaries,
                     ...(summariesOmitted > 0 ? { summariesOmitted } : {}),
+                    ...(gaps.length > 0 ? { traceGaps: gaps } : {}),
                     rankedImpact,
                     reachedByDepth,
                     bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,

package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts

@@ -1,8 +1,12 @@
+import type { Spec } from '../../spec/spec-parser';
+import type { ScannedFile } from '../../cpg/cpg-scanner';
 interface MaintenanceEvidenceContext {
     foreignRootReason(root: string): string | null;
     projectRootOf(root: string): string;
     refusal(reason: string): Error;
     fileDigestOf(root: string, relativePath: string): string | null;
+    listSpecs(): Promise<Spec[]>;
+    cachedScan(root: string): ScannedFile[];
 }
 /** Raw handlers: the public facade attaches basis exactly once. */
 export declare function createMaintenanceEvidenceHandlers(context: MaintenanceEvidenceContext): {

package/dist/holmes/mcp/handlers/maintenance-evidence.js

@@ -41,6 +41,7 @@ const node_child_process_1 = require("node:child_process");
 const maintenance_evidence_1 = require("../maintenance-evidence");
 const impact_gate_1 = require("../../guardrail/impact-gate");
 const root_1 = require("../../project/root");
+const trace_gaps_1 = require("../../rtm/trace-gaps");
 /** Raw handlers: the public facade attaches basis exactly once. */
 function createMaintenanceEvidenceHandlers(context) {
     return {
@@ -77,11 +78,25 @@ function createMaintenanceEvidenceHandlers(context) {
                     throw context.refusal(`이 프로젝트에 저장된 분석이 아닙니다: ${a.digest}`);
                 artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
             }
+            const target = a.target.replace(/\\/g, '/');
+            // @implements A-SPEC-658 — approved specs that declare this file but anchor nothing: the graph
+            // cannot see them, so the gate must not read their silence as "no impact". A failed lookup
+            // drops the input (information lost, verdict unchanged) rather than inventing a gap.
+            let gaps;
+            try {
+                const found = (0, trace_gaps_1.traceGaps)([target], (0, trace_gaps_1.unlinkedApproved)(await context.listSpecs(), context.cachedScan(root)));
+                if (found.length > 0)
+                    gaps = found.map(({ id, file }) => ({ id, file }));
+            }
+            catch {
+                gaps = undefined;
+            }
             return (0, impact_gate_1.evaluateEditEvidence)({
-                target: a.target.replace(/\\/g, '/'),
+                target,
                 artifact,
                 currentHead: head,
                 currentTargetDigest: context.fileDigestOf(root, a.target),
+                ...(gaps ? { traceGaps: gaps } : {}),
             });
         },
         // @implements A-SPEC-268

package/dist/holmes/mcp/handlers/operator-inspection.d.ts

@@ -46,6 +46,7 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
         ok: boolean;
         reason: string;
     } | {
+        fttFulfilment?: import("../../rtm/ftt-fulfilment").FttFulfilment | undefined;
         graphPreview?: {
             impact?: import("../../rtm/impact-advisory").ImpactAdvisory;
             density?: Array<import("../../rtm/anchor-density").AnchorDensityFinding>;
@@ -161,7 +162,7 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
         ok: boolean;
         url: string;
         running: boolean;
-        census: import("../../server/dashboard-launcher").DashboardCensus;
+        census: import("../../server/dashboard-launcher").DashboardCensusExtended;
         reason?: undefined;
     }>;
 };

package/dist/holmes/mcp/handlers/operator-inspection.js

@@ -190,7 +190,28 @@ function createOperatorInspectionHandlers(context) {
             catch {
                 graphPreview = undefined;
             }
-            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, context.resolver(all)), ...(graphPreview ? { graphPreview } : {}) };
+            // @implements A-SPEC-656 — the same promised-but-absent finding sealing will report, delivered
+            // BEFORE sealing (REQ-572: delivery time was the gap, not the calculation) and without a ledger
+            // write (a query must not pollute the observation denominator). Same pure function as the seal.
+            let fttFulfilment;
+            try {
+                if (cur.spec.type === 'A-SPEC' && a.root) {
+                    const root = a.root;
+                    const { fttFulfilment: compute, locateByBasename } = require('../../rtm/ftt-fulfilment');
+                    const exists = (rel) => {
+                        const abs = path.resolve(root, rel);
+                        return abs.startsWith(root + path.sep) && fs.existsSync(abs);
+                    };
+                    const found = compute(String(cur.spec.sections?.['Files to Touch'] ?? ''), exists, locateByBasename(root));
+                    if (found)
+                        fttFulfilment = found;
+                }
+            }
+            catch {
+                fttFulfilment = undefined;
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, context.resolver(all)), ...(graphPreview ? { graphPreview } : {}),
+                ...(fttFulfilment ? { fttFulfilment } : {}) };
         },
         /**
          * @implements A-SPEC-538.3
@@ -270,11 +291,12 @@ function createOperatorInspectionHandlers(context) {
                 return { ok: false, reason: dest.reason };
             try {
                 const { startDashboardServer } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard')));
-                const { ensureDashboard, dashboardCensus } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard-launcher')));
+                // @implements A-SPEC-655 — the census carries the code-link axis beside pipeline coverage.
+                const { ensureDashboard, dashboardCensusExtended } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard-launcher')));
                 const launch = await ensureDashboard(dest.root, a.port, (opts) => startDashboardServer(opts));
                 const rtm = await context.fetchJson(`${launch.url}/api/rtm`);
                 const heatmap = await context.fetchJson(`${launch.url}/api/rtm/heatmap`);
-                return { ok: true, url: launch.url, running: launch.running, census: dashboardCensus(rtm, heatmap) };
+                return { ok: true, url: launch.url, running: launch.running, census: dashboardCensusExtended(rtm, heatmap) };
             }
             catch (err) {
                 return { ok: false, reason: `대시보드 기동 실패: ${err?.message ?? String(err)}` };

package/dist/holmes/mcp/handlers/spec-approval.d.ts

@@ -57,6 +57,7 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
         reason: string;
         conflict: import("../../spec/version-conflict").ConflictDetail;
     } | {
+        fttFulfilment?: import("../../rtm/ftt-fulfilment").FttFulfilment | undefined;
         impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
         impactGraph?: {
             status: "current" | "stale" | "unverified";

package/dist/holmes/mcp/handlers/spec-approval.js

@@ -415,8 +415,36 @@ function createSpecApprovalHandlers(context) {
                 impactGraph = undefined;
                 impactAdvisoryUnavailable = undefined;
             }
+            // @implements A-SPEC-656 — the promised-but-absent side of the declaration, filesystem only,
+            // independent of the graph block above (no rtm.sqlite needed). Advisory: the seal is already
+            // done. The finding rides the response and lands in its own observation ledger so its
+            // false-positive rate can be measured before anyone proposes a gate; a failed read drops the
+            // field rather than inventing a finding. Parsing, buckets and the walk live in the pure module.
+            let fttFulfilment;
+            try {
+                if (spec.type === 'A-SPEC' && a.root) {
+                    const root = a.root;
+                    const { fttFulfilment: compute, locateByBasename, appendFttFulfilment } = require('../../rtm/ftt-fulfilment');
+                    const exists = (rel) => {
+                        const abs = path.resolve(root, rel);
+                        return abs.startsWith(root + path.sep) && fs.existsSync(abs);
+                    };
+                    const found = compute(String(candidate.sections?.['Files to Touch'] ?? ''), exists, locateByBasename(root));
+                    if (found) {
+                        fttFulfilment = found;
+                        appendFttFulfilment(root, {
+                            aspec: a.id, declared: found.declared, missing: found.missing.map((m) => m.path),
+                            moved: found.moved.map((m) => m.path), ts: new Date().toISOString(),
+                        });
+                    }
+                }
+            }
+            catch {
+                fttFulfilment = undefined;
+            }
             return { approved: a.id, digest, ...(impactAdvisory ? { impactAdvisory } : {}), ...(anchorDensity ? { anchorDensity } : {}),
-                ...(impactGraph ? { impactGraph } : {}), ...(impactAdvisoryUnavailable ? { impactAdvisoryUnavailable } : {}) };
+                ...(impactGraph ? { impactGraph } : {}), ...(impactAdvisoryUnavailable ? { impactAdvisoryUnavailable } : {}),
+                ...(fttFulfilment ? { fttFulfilment } : {}) };
         },
         /**
          * Pin a REQ's citations: compute the content digest of every cited source that resolves inside

package/dist/holmes/mcp/handlers.d.ts

@@ -410,6 +410,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             reason: "hub" | "depth";
             inDegree?: number;
         }[] | undefined;
+        traceGaps?: import("../rtm/trace-gaps").TraceGap[] | undefined;
         summariesOmitted?: number | undefined;
         impacted: string[];
         impactedSummaries: {
@@ -770,6 +771,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok: boolean;
         reason: string;
     } | {
+        fttFulfilment?: import("../rtm/ftt-fulfilment").FttFulfilment | undefined;
         graphPreview?: {
             impact?: import("../rtm/impact-advisory").ImpactAdvisory;
             density?: Array<import("../rtm/anchor-density").AnchorDensityFinding>;
@@ -822,7 +824,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok: boolean;
         url: string;
         running: boolean;
-        census: import("../server/dashboard-launcher").DashboardCensus;
+        census: import("../server/dashboard-launcher").DashboardCensusExtended;
         reason?: undefined;
     }>;
     spec_approve: (a: {
@@ -844,6 +846,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         reason: string;
         conflict: import("../spec/version-conflict").ConflictDetail;
     } | {
+        fttFulfilment?: import("../rtm/ftt-fulfilment").FttFulfilment | undefined;
         impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
         impactGraph?: {
             status: "current" | "stale" | "unverified";