@holmes-lab/holmes-kit 0.20.2 → 0.22.0

package/dist/holmes/rtm/ftt-fulfilment.js

@@ -0,0 +1,195 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fttItems = fttItems;
+exports.fttFulfilment = fttFulfilment;
+exports.locateByBasename = locateByBasename;
+exports.appendFttFulfilment = appendFttFulfilment;
+exports.readFttFulfilments = readFttFulfilments;
+// @implements A-SPEC-656
+/**
+ * Files-to-Touch fulfilment — the paths a sealed A-SPEC promised and never made.
+ *
+ * `declaredImpactGap` says what the declaration MISSED (from the call graph); this says what the
+ * declaration PROMISED and the tree does not hold (from the filesystem). Measured 2026-09-16 on
+ * this repository: four promised paths across three approved specs never existed, and nothing
+ * named them — every gate reads the other direction (code → declaration). The same measurement
+ * found the three false-positive shapes a naive existence check would raise, so each has its own
+ * bucket: an item written as an alternative ("또는" / "or"), a basename that lives elsewhere
+ * (location drift), and prose that is not an item at all (already not a token under REQ-654).
+ *
+ * ADVISORY, NEVER VERDICT: nothing here can change ok/refuse/grant. NO GUESSING: a failed read
+ * propagates to the caller, which drops the field rather than inventing a finding.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const scope_judgment_1 = require("../guardrail/scope-judgment");
+const replica_id_1 = require("../governance/replica-id");
+const ITEM_RE = /^\s*[-*]\s+(.*)$/;
+const NEW_RE = /\((신규|new)\)/i;
+const ALT_RE = /또는|\bor\b/;
+const SLASHED = /^[\w@.-]+(?:\/[\w@.-]+)+$/;
+const HAS_EXT = /\.[A-Za-z][A-Za-z0-9]*$/;
+/**
+ * List items only, first word only — the REQ-654 token rule (a slashed path or an item-shaped
+ * root filename; prose is nothing). Globs and extension-less paths (directories) are not items:
+ * their fulfilment is not a single file's existence.
+ */
+function fttItems(fttText) {
+    const out = [];
+    for (const raw of String(fttText ?? '').replace(/\\/g, '/').split('\n')) {
+        const m = ITEM_RE.exec(raw);
+        if (!m)
+            continue;
+        const line = m[1].trim();
+        const word = (line.split(/\s+/)[0] ?? '').replace(/^[`'"]+|[`'"]+$/g, '').replace(/^`?([^`]*?)`?\(/, '$1(');
+        const token = word.replace(/\(.*$/, ''); // `src/b.ts`(new) → src/b.ts
+        if (!token || token.includes('*') || !HAS_EXT.test(token))
+            continue;
+        if (!(SLASHED.test(token) || (0, scope_judgment_1.isRootFileToken)(token)))
+            continue;
+        out.push({ path: token, line, isNew: NEW_RE.test(line), alternative: ALT_RE.test(line) });
+    }
+    return out;
+}
+function fttFulfilment(fttText, exists, locate) {
+    const items = fttItems(fttText);
+    if (items.length === 0)
+        return null;
+    const missing = [];
+    const moved = [];
+    const alternatives = [];
+    for (const it of items) {
+        if (it.alternative) {
+            alternatives.push({ path: it.path, line: it.line });
+            continue;
+        }
+        if (exists(it.path))
+            continue;
+        const base = it.path.slice(it.path.lastIndexOf('/') + 1);
+        const foundAt = [...new Set(locate(base))].filter((p) => p !== it.path).sort();
+        if (foundAt.length > 0)
+            moved.push({ path: it.path, foundAt });
+        else
+            missing.push({ path: it.path, isNew: it.isNew });
+    }
+    if (missing.length === 0 && moved.length === 0 && alternatives.length === 0)
+        return null;
+    return { declared: items.length, missing, moved, alternatives };
+}
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.ax']);
+/** One walk, then O(1) lookups. Unreadable directories are skipped, never reported as empty. */
+function locateByBasename(root) {
+    const byBase = new Map();
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (SKIP_DIRS.has(e.name))
+                continue;
+            const abs = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            const list = byBase.get(e.name) ?? [];
+            list.push(rel);
+            byBase.set(e.name, list);
+        }
+    };
+    walk(root);
+    return (basename) => [...(byBase.get(basename) ?? [])].sort();
+}
+const LEDGER_RE = /^ftt-fulfilment\.([^.]+)\.jsonl$/;
+/** The observation ledger — repo-relative paths, a spec id, integers and a timestamp; nothing else. */
+function appendFttFulfilment(root, rec) {
+    try {
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        let replica = 'local';
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = path.join(root, '.ax', 'ledger', `ftt-fulfilment.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const line = { aspec: rec.aspec, declared: rec.declared, missing: [...rec.missing], moved: [...rec.moved], ts: rec.ts, replica };
+        fs.appendFileSync(file, `${JSON.stringify(line)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readFttFulfilments(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => LEDGER_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const raw of text.split('\n')) {
+            const s = raw.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r.aspec === 'string' && Array.isArray(r.missing) && Array.isArray(r.moved) && typeof r.ts === 'string')
+                    out.push(r);
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/known-defects.d.ts

@@ -0,0 +1,26 @@
+export interface KnownDefect {
+    file: string;
+    line: number;
+    reason: string;
+    expires: string;
+}
+export interface MalformedMarker {
+    file: string;
+    line: number;
+    text: string;
+    why: 'no-reason' | 'no-expires' | 'bad-date';
+}
+export interface KnownDefectJudgement {
+    unexpired: KnownDefect[];
+    expired: KnownDefect[];
+    malformed: MalformedMarker[];
+}
+export declare function knownDefectsIn(source: string, file: string): {
+    markers: KnownDefect[];
+    malformed: MalformedMarker[];
+};
+/** Expired when the expiry day's UTC midnight is at or before `now` — the day itself counts as expired. */
+export declare function judgeKnownDefects(found: {
+    markers: KnownDefect[];
+    malformed: MalformedMarker[];
+}, now: Date): KnownDefectJudgement;

package/dist/holmes/rtm/known-defects.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.knownDefectsIn = knownDefectsIn;
+exports.judgeKnownDefects = judgeKnownDefects;
+// @implements A-SPEC-660
+/**
+ * `@known-defect(<reason>, expires=YYYY-MM-DD)` — the machine-readable marker for an assertion that
+ * pins a KNOWN DEFECT as the expected value.
+ *
+ * jarvis 2026-09-08: a query that could only ever return 0 was worked around instead of fixed, the
+ * workaround was pinned by a test (`assert raw == []`), and to every gate that test was
+ * indistinguishable from a healthy one — green, anchored, covered. The docstring said "trap"; only
+ * people read docstrings, and the next person repeated the misjudgement. Three precedents make the
+ * shape: posixOnly(reason) refuses a reason-less skip, countTestCases folds a marker head into
+ * ART-4's evidence, sessionAutonomyActive judges `expires` fail-closed.
+ *
+ * Pure. Markers are read from COMMENT lines only, after string literals are removed — the ART-4
+ * counter's lesson, so a fixture string never becomes a marker. A marker that cannot be read is
+ * returned as `malformed`, never dropped: a typo that parses to nothing reads as "the rule passed".
+ * The clock is injected; nothing here reads process time.
+ */
+const anchor_ids_1 = require("./anchor-ids");
+// A comment line (`//`, `/*`, `*`, `#`) carrying the marker; the body runs to the closing paren.
+const MARKER_LINE_RE = /^[ \t]*(?:\/\/|\/\*|\*|#)[^\n]*?@known-defect\(([^)]*)\)/;
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** The calendar date's UTC midnight, or null when the string is not a real date. */
+function utcMidnightOf(date) {
+    const m = DATE_RE.exec(date);
+    if (!m)
+        return null;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const t = Date.UTC(y, mo - 1, d);
+    const back = new Date(t);
+    return back.getUTCFullYear() === y && back.getUTCMonth() === mo - 1 && back.getUTCDate() === d ? t : null;
+}
+function knownDefectsIn(source, file) {
+    const markers = [];
+    const malformed = [];
+    const lines = (0, anchor_ids_1.stripStringLiterals)(String(source ?? '')).split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = MARKER_LINE_RE.exec(lines[i]);
+        if (!m)
+            continue;
+        const body = m[1];
+        const text = `@known-defect(${body})`;
+        const at = body.lastIndexOf(', expires=');
+        if (at === -1) {
+            malformed.push({ file, line: i + 1, text, why: 'no-expires' });
+            continue;
+        }
+        const reason = body.slice(0, at).trim();
+        const expires = body.slice(at + ', expires='.length).trim();
+        if (reason === '') {
+            malformed.push({ file, line: i + 1, text, why: 'no-reason' });
+            continue;
+        }
+        if (utcMidnightOf(expires) === null) {
+            malformed.push({ file, line: i + 1, text, why: 'bad-date' });
+            continue;
+        }
+        markers.push({ file, line: i + 1, reason, expires });
+    }
+    return { markers, malformed };
+}
+/** Expired when the expiry day's UTC midnight is at or before `now` — the day itself counts as expired. */
+function judgeKnownDefects(found, now) {
+    const unexpired = [];
+    const expired = [];
+    for (const k of found.markers) {
+        const t = utcMidnightOf(k.expires);
+        if (t === null || t <= now.getTime())
+            expired.push(k);
+        else
+            unexpired.push(k);
+    }
+    return { unexpired, expired, malformed: [...found.malformed] };
+}

package/dist/holmes/rtm/link-census.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+export type UnlinkedReason = 'test-only' | 'file-anchor' | 'test-and-file' | 'weak-anchor' | 'none';
+export interface UnlinkedSpec {
+    id: string;
+    reason: UnlinkedReason;
+    /** Test and file-anchor paths that carry the id, sorted. Empty for weak-anchor / none. */
+    anchoredIn: string[];
+    /** Files-to-Touch paths whose text names the id — weak-anchor only. */
+    mentionedIn: string[];
+}
+export interface LinkCensus {
+    total: number;
+    codeLinked: number;
+    /** One decimal, never NaN. */
+    codeLinkedPct: number;
+    /** Sorted by id. */
+    unlinked: UnlinkedSpec[];
+    /** Always carries all five keys. */
+    byReason: Record<UnlinkedReason, number>;
+}
+export interface LinkCensusInput {
+    approvedIds: string[];
+    /** Ids anchored by production (scanned) source — the ids that own an `implements` edge. */
+    implemented: Iterable<string>;
+    /** `scanTestAnchors` shape: repo-relative POSIX path → ids. */
+    testAnchors: Record<string, string[]>;
+    /** `scanFileAnchors` shape: repo-relative POSIX path → ids. */
+    fileAnchors: Record<string, string[]>;
+    /** id → Files-to-Touch paths whose text names it (see `weakMentionsFor`). */
+    weakMentions: Record<string, string[]>;
+}
+export declare const UNLINKED_REASONS: readonly UnlinkedReason[];
+export declare function emptyByReason(): Record<UnlinkedReason, number>;
+/** Percentage with one decimal; a zero denominator reads as 0, never NaN. */
+export declare function pct1(num: number, den: number): number;
+/**
+ * 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.
+ */
+export declare function weakMentionsFor(id: string, fttFiles: string[], readText: (rel: string) => string | null): string[];
+export declare function linkCensus(input: LinkCensusInput): LinkCensus;

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/rtm-graph.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RtmGraph = void 0;
+// @implements A-SPEC-588
 // @implements A-SPEC-293
 // @implements A-SPEC-644
 // @implements A-SPEC-289

package/dist/holmes/rtm/taint-benchmark.js

@@ -38,6 +38,7 @@ exports.runTaintBenchmarkAsync = runTaintBenchmarkAsync;
 exports.compareEngines = compareEngines;
 exports.runTaintBenchmark = runTaintBenchmark;
 exports.taintOnRealCorpus = taintOnRealCorpus;
+// @implements A-SPEC-355
 // @implements A-SPEC-354
 const language_parser_1 = require("../cpg/language-parser");
 const dataflow_taint_1 = require("./dataflow-taint");

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