@holmes-lab/holmes-kit 0.21.0 → 0.23.1

package/dist/holmes/rtm/advisory-outcomes.js

@@ -0,0 +1,314 @@
+"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.ADVISORY_KINDS = void 0;
+exports.canonical = canonical;
+exports.advisoryId = advisoryId;
+exports.foldAdvisoryState = foldAdvisoryState;
+exports.judgeAdvisories = judgeAdvisories;
+exports.dismissAdvisories = dismissAdvisories;
+exports.advisoryCensus = advisoryCensus;
+exports.appendAdvisoryOutcomes = appendAdvisoryOutcomes;
+exports.readAdvisoryOutcomes = readAdvisoryOutcomes;
+exports.traceGapAdvisories = traceGapAdvisories;
+exports.currentAdvisoryKeys = currentAdvisoryKeys;
+exports.recordAdvisoryOutcomes = recordAdvisoryOutcomes;
+exports.traceGapFiles = traceGapFiles;
+exports.gitHeadOf = gitHeadOf;
+exports.traceGapFor = traceGapFor;
+// @implements A-SPEC-663
+/**
+ * The advisory REACTION ledger — the numerator every promotion decision has been missing.
+ *
+ * This repository already issues five advisory kinds (impact-advisory, anchor-density, ftt-fulfilment,
+ * trace-gap, kills-unapplicable) and records the ISSUE of most of them. Measured 2026-09-18: 77
+ * impact-advisory rows, 76 anchor-density rows, and not one row anywhere saying what the author did
+ * next. Tricorder's "not useful" button and Google's "productive mutant" metric count the reaction,
+ * not the emission; without that count "promote to a hard gate once the ledger answers the false-
+ * positive rate" has no ledger to ask.
+ *
+ * Pure: identity, judgement and folding take rows in and give rows out. The append/read helpers are
+ * the only I/O and follow the other advisory ledgers (per-replica jsonl, repo-relative content only).
+ */
+const crypto = __importStar(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
+const ftt_fulfilment_1 = require("./ftt-fulfilment");
+const trace_gaps_1 = require("./trace-gaps");
+/** Canonical JSON: sorted keys, arrays kept in order — the same payload always gives the same id. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const o = value;
+        return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Deterministic identity of one finding: kind + spec + canonical payload → sha256, first 16 hex. */
+function advisoryId(kind, aspec, payload) {
+    return crypto.createHash('sha256').update(`${kind}|${aspec}|${canonical(payload)}`).digest('hex').slice(0, 16);
+}
+/** Latest state per id, in first-seen order. `dismissed` and `resolved` are terminal until re-issued. */
+function foldAdvisoryState(rows) {
+    const byId = new Map();
+    for (const r of rows) {
+        const cur = byId.get(r.id);
+        if (!cur) {
+            byId.set(r.id, { id: r.id, kind: r.kind, aspec: r.aspec, firstSeen: r.firstSeen, last: r.outcome, lastAt: r.judgedAt, rows: 1 });
+            continue;
+        }
+        cur.rows += 1;
+        if (r.judgedAt >= cur.lastAt) {
+            cur.last = r.outcome;
+            cur.lastAt = r.judgedAt;
+        }
+    }
+    return [...byId.values()];
+}
+const day = (iso) => iso.slice(0, 10);
+/**
+ * Judge the advisories a re-evaluation produced against what the ledger already knows.
+ *  - a current finding with no state, or whose last state is resolved/dismissed → `issued`
+ *  - a current finding whose last state is issued/persisted → `persisted`
+ *  - an open (issued/persisted) finding of the judged scope that is no longer current → `resolved`
+ * One row per (id, outcome) per UTC day: re-running the same query the same day adds nothing.
+ * `scope` names which open findings this evaluation could have seen (so an unrelated spec's finding
+ * is never resolved by a query that did not look at it).
+ */
+function judgeAdvisories(state, current, scope, now, head, recent = [], opts = {}) {
+    const issue = opts.issue !== false;
+    const out = [];
+    const today = recent.filter((r) => day(r.judgedAt) === day(now));
+    const seen = new Set(today.map((r) => `${r.id}|${r.outcome}`));
+    // `persisted` is a heartbeat, not an event: at most one row per id per day, and never on the day
+    // the finding was issued — the same query repeated the same day must add nothing.
+    const touchedToday = new Set(today.map((r) => r.id));
+    const push = (k, outcome, firstSeen) => {
+        if (seen.has(`${k.id}|${outcome}`))
+            return;
+        if (outcome === 'persisted' && touchedToday.has(k.id))
+            return;
+        seen.add(`${k.id}|${outcome}`);
+        touchedToday.add(k.id);
+        out.push({ id: k.id, kind: k.kind, aspec: k.aspec, outcome, firstSeen, judgedAt: now, head });
+    };
+    const byId = new Map(state.map((s) => [s.id, s]));
+    const currentIds = new Set(current.map((c) => c.id));
+    for (const c of current) {
+        const s = byId.get(c.id);
+        if (!s || s.last === 'resolved' || s.last === 'dismissed') {
+            if (issue)
+                push(c, 'issued', now);
+        }
+        else
+            push(c, 'persisted', s.firstSeen);
+    }
+    for (const s of state) {
+        if (!scope(s) || currentIds.has(s.id))
+            continue;
+        if (s.last === 'issued' || s.last === 'persisted')
+            push(s, 'resolved', s.firstSeen);
+    }
+    return out;
+}
+/** Explicit dismissal by the author: only for findings the ledger knows and that are still open. */
+function dismissAdvisories(state, ids, now, head) {
+    const byId = new Map(state.map((s) => [s.id, s]));
+    const out = [];
+    for (const id of ids) {
+        const s = byId.get(id);
+        if (!s || (s.last !== 'issued' && s.last !== 'persisted'))
+            continue;
+        out.push({ id: s.id, kind: s.kind, aspec: s.aspec, outcome: 'dismissed', firstSeen: s.firstSeen, judgedAt: now, head });
+    }
+    return out;
+}
+exports.ADVISORY_KINDS = ['impact-advisory', 'anchor-density', 'ftt-fulfilment', 'trace-gap', 'kills-unapplicable'];
+/** Per kind: how many findings were ever issued, and how many stand resolved / persisted / dismissed now. */
+function advisoryCensus(rows) {
+    const out = Object.fromEntries(exports.ADVISORY_KINDS.map((k) => [k, { issued: 0, resolved: 0, persisted: 0, dismissed: 0 }]));
+    for (const s of foldAdvisoryState(rows)) {
+        const c = out[s.kind];
+        if (!c)
+            continue;
+        c.issued += 1;
+        if (s.last === 'resolved')
+            c.resolved += 1;
+        else if (s.last === 'persisted')
+            c.persisted += 1;
+        else if (s.last === 'dismissed')
+            c.dismissed += 1;
+    }
+    return out;
+}
+// Scanned files carry ABSOLUTE paths (CpgScanner); Files to Touch are repo-relative. Compare in one spelling.
+function relPosix(p, root) {
+    const rel = root && path.isAbsolute(p) ? path.relative(root, p) : p;
+    return rel.split(path.sep).join('/').replace(/\\/g, '/');
+}
+const FILE_RE = /^advisory-outcomes\.([^.]+)\.jsonl$/;
+function appendAdvisoryOutcomes(root, rows) {
+    if (rows.length === 0)
+        return true;
+    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', `advisory-outcomes.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, rows.map((r) => `${JSON.stringify({ ...r, replica })}\n`).join(''));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readAdvisoryOutcomes(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, n), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* a torn line is not a record */ }
+        }
+    }
+    return out.sort((a, b) => (a.judgedAt < b.judgedAt ? -1 : a.judgedAt > b.judgedAt ? 1 : 0));
+}
+/**
+ * One trace-gap finding per unlinked approved A-SPEC that declares at least one SCANNED production
+ * file in its Files to Touch — the same population REQ-658 reports per change, taken whole. The
+ * payload is the sorted file list, so moving one anchor changes the id (a smaller gap is a new
+ * finding, the old one resolved) — honest, if noisy; the census counts findings, not specs.
+ */
+function traceGapAdvisories(specs, scanned, root = '') {
+    const scannedPaths = new Set(scanned.map((f) => relPosix(f.path, root)));
+    const out = [];
+    for (const u of (0, trace_gaps_1.unlinkedApproved)(specs, scanned)) {
+        const files = [...new Set((0, ftt_fulfilment_1.fttItems)(u.ftt).map((i) => i.path).filter((p) => scannedPaths.has(p)))].sort();
+        if (files.length === 0)
+            continue;
+        out.push({ id: advisoryId('trace-gap', u.id, { files }), kind: 'trace-gap', aspec: u.id });
+    }
+    return out;
+}
+function currentAdvisoryKeys(aspec, c) {
+    const keys = [];
+    const ids = {};
+    const add = (kind, payload) => { const id = advisoryId(kind, aspec, payload); keys.push({ id, kind, aspec }); ids[kind] = id; };
+    if (c.impactAdvisory && c.impactAdvisory.files.length > 0)
+        add('impact-advisory', { files: c.impactAdvisory.files.map((f) => f.path) });
+    if (c.anchorDensity && c.anchorDensity.length > 0)
+        add('anchor-density', { files: c.anchorDensity.map((f) => f.path) });
+    if (c.fttFulfilment)
+        add('ftt-fulfilment', { missing: c.fttFulfilment.missing.map((m) => m.path), moved: c.fttFulfilment.moved.map((m) => m.path), alternatives: c.fttFulfilment.alternatives.map((m) => m.path) });
+    if (c.killsAdvisory && c.killsAdvisory.unapplicable.length > 0)
+        add('kills-unapplicable', { unapplicable: c.killsAdvisory.unapplicable.map((u) => ({ where: u.where, reason: u.reason })) });
+    if (c.traceGap && c.traceGap.files.length > 0)
+        add('trace-gap', { files: [...c.traceGap.files].sort() });
+    return { keys, ids };
+}
+/**
+ * One act: read the ledger, judge `current` against it within `scope`, apply explicit dismissals,
+ * append, and return what the response should carry. I/O failures leave the response without the
+ * fields (the seal or the query is unaffected). Never throws.
+ */
+function recordAdvisoryOutcomes(root, aspec, current, scope, head, dismiss = [], now = new Date().toISOString(), opts = {}) {
+    try {
+        const rows = readAdvisoryOutcomes(root);
+        const state = foldAdvisoryState(rows);
+        const judged = judgeAdvisories(state, current, scope, now, head, rows, opts);
+        const after = foldAdvisoryState([...rows, ...judged]);
+        const dismissed = dismissAdvisories(after, dismiss, now, head);
+        const known = new Set(dismissed.map((d) => d.id));
+        const dismissUnknown = dismiss.filter((id) => !known.has(id));
+        appendAdvisoryOutcomes(root, [...judged, ...dismissed]);
+        const history = foldAdvisoryState([...rows, ...judged, ...dismissed]).filter((s) => s.aspec === aspec);
+        return { history, dismissUnknown };
+    }
+    catch {
+        return { history: [], dismissUnknown: dismiss };
+    }
+}
+/** The scanned production files an A-SPEC declares — the trace-gap payload for one spec. */
+function traceGapFiles(spec, scanned, root = '') {
+    const scannedPaths = new Set(scanned.map((f) => relPosix(f.path, root)));
+    return [...new Set((0, ftt_fulfilment_1.fttItems)(String(spec.sections?.['Files to Touch'] ?? '')).map((i) => i.path).filter((p) => scannedPaths.has(p)))].sort();
+}
+/** The commit a reaction row is judged at; 'nogit' when git cannot say. Never throws. */
+function gitHeadOf(root) {
+    try {
+        return (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || 'nogit';
+    }
+    catch {
+        return 'nogit';
+    }
+}
+/**
+ * The trace-gap finding for ONE spec, status aside: the scanned production files it declares, or
+ * null when a scanned file already anchors it or it declares none. Used at the seal (where the
+ * spec is approved by the time this runs) and in the preview.
+ */
+function traceGapFor(specId, spec, scanned, root = '') {
+    for (const f of scanned)
+        if ((f.implementsSpecs ?? []).includes(specId))
+            return null;
+    const files = traceGapFiles(spec, scanned, root);
+    return files.length > 0 ? { files } : null;
+}

package/dist/holmes/rtm/declared-scope.d.ts

@@ -0,0 +1,28 @@
+export type DeclaredScope = 'scanned-source' | 'file-anchor-target' | 'test-target' | 'unreachable-target' | 'no-declaration';
+export interface ScopePredicates {
+    isScanned(rel: string): boolean;
+    isFileAnchorable(rel: string): boolean;
+    isTest(rel: string): boolean;
+}
+export declare const DECLARED_SCOPES: readonly DeclaredScope[];
+export declare function emptyByScope(): Record<DeclaredScope, number>;
+/**
+ * One label per spec, by the STRONGEST reachability its declaration offers: a scanned source beats a
+ * file-anchor target beats a test file beats nothing any mechanism reads. `unreachable` is filled
+ * whatever the label is, because a single label hides the `docs/x.md` sitting beside a test file —
+ * measured here, 21 of the 52 unlinked specs declare at least one such path.
+ * The Files-to-Touch parser is REQ-656's, so path extraction has exactly one definition.
+ */
+export declare function declaredScopeOf(fttText: string, p: ScopePredicates): {
+    scope: DeclaredScope;
+    unreachable: string[];
+};
+/** Every entry labelled exactly once, so the aggregate sums to the population it was given. */
+export declare function declaredScopeCensus(entries: ReadonlyArray<{
+    id: string;
+    ftt: string;
+}>, p: ScopePredicates): {
+    byId: Record<string, DeclaredScope>;
+    byScope: Record<DeclaredScope, number>;
+    unreachableDeclaring: number;
+};

package/dist/holmes/rtm/declared-scope.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECLARED_SCOPES = void 0;
+exports.emptyByScope = emptyByScope;
+exports.declaredScopeOf = declaredScopeOf;
+exports.declaredScopeCensus = declaredScopeCensus;
+// @implements A-SPEC-665
+/**
+ * The DECLARATION axis of an unlinked approved A-SPEC.
+ *
+ * REQ-655's census answers "where is this spec anchored" (`UnlinkedReason`). It cannot answer the
+ * question a reader actually has when `codeLinkedPct` reads 91.9: is there production code for this
+ * spec to be linked to at all? Measured 2026-09-18, after REQ-664's S3 moved 21 anchors: of the 52
+ * unlinked approved specs, ZERO declare a file the scanner parses. They are unlinked because they
+ * have no such file, not because an anchor is missing.
+ *
+ * The two axes sit side by side and never share a name. This one names what a spec DECLARED — a
+ * fact — and says nothing about whether that is acceptable; `traceGaps` remains the reader that
+ * calls one of these situations a gap.
+ *
+ * Pure: every reachability question is injected, so the classification follows the mechanisms'
+ * own definitions rather than a second copy of them.
+ */
+const ftt_fulfilment_1 = require("./ftt-fulfilment");
+exports.DECLARED_SCOPES = ['scanned-source', 'file-anchor-target', 'test-target', 'unreachable-target', 'no-declaration'];
+function emptyByScope() {
+    return { 'scanned-source': 0, 'file-anchor-target': 0, 'test-target': 0, 'unreachable-target': 0, 'no-declaration': 0 };
+}
+/**
+ * One label per spec, by the STRONGEST reachability its declaration offers: a scanned source beats a
+ * file-anchor target beats a test file beats nothing any mechanism reads. `unreachable` is filled
+ * whatever the label is, because a single label hides the `docs/x.md` sitting beside a test file —
+ * measured here, 21 of the 52 unlinked specs declare at least one such path.
+ * The Files-to-Touch parser is REQ-656's, so path extraction has exactly one definition.
+ */
+function declaredScopeOf(fttText, p) {
+    const items = [...new Set((0, ftt_fulfilment_1.fttItems)(String(fttText ?? '')).map((i) => i.path))];
+    if (items.length === 0)
+        return { scope: 'no-declaration', unreachable: [] };
+    const unreachable = items.filter((rel) => !p.isScanned(rel) && !p.isFileAnchorable(rel) && !p.isTest(rel)).sort();
+    const scope = items.some((rel) => p.isScanned(rel)) ? 'scanned-source'
+        : items.some((rel) => p.isFileAnchorable(rel)) ? 'file-anchor-target'
+            : items.some((rel) => p.isTest(rel)) ? 'test-target'
+                : 'unreachable-target';
+    return { scope, unreachable };
+}
+/** Every entry labelled exactly once, so the aggregate sums to the population it was given. */
+function declaredScopeCensus(entries, p) {
+    const byId = {};
+    const byScope = emptyByScope();
+    let unreachableDeclaring = 0;
+    for (const e of entries) {
+        const r = declaredScopeOf(e.ftt, p);
+        byId[e.id] = r.scope;
+        byScope[r.scope] += 1;
+        if (r.unreachable.length > 0)
+            unreachableDeclaring += 1;
+    }
+    return { byId, byScope, unreachableDeclaring };
+}

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/server/dashboard-launcher.d.ts

@@ -1,4 +1,5 @@
 import { UnlinkedReason } from '../rtm/link-census';
+import { DeclaredScope } from '../rtm/declared-scope';
 /** Honesty summary of what a launched dashboard shows — derived from the endpoints it serves. */
 export interface DashboardCensus {
     reqCount: number;
@@ -26,6 +27,12 @@ export interface DashboardCensusExtended extends DashboardCensus {
         unmapped: number;
         nonSpec: number;
     };
+    /**
+     * @implements A-SPEC-665 — the declaration axis beside the anchor axis: what the unlinked specs
+     * DECLARED, next to where they are anchored. A payload without it folds to zeros like the rest.
+     */
+    declaredScopeByScope: Record<DeclaredScope, number>;
+    unreachableDeclaringCount: number;
 }
 /**
  * Pure: the pinned census plus the code-link axis from `/api/rtm`'s `linkCensus`, `coveragePct`

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

@@ -7,6 +7,7 @@ exports._resetLauncher = _resetLauncher;
 exports._stopAll = _stopAll;
 // @implements A-SPEC-545.3
 const link_census_1 = require("../rtm/link-census");
+const declared_scope_1 = require("../rtm/declared-scope");
 /**
  * @implements A-SPEC-545.3
  * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
@@ -45,6 +46,8 @@ function dashboardCensusExtended(rtm, heatmap) {
         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 },
+        declaredScopeByScope: { ...(0, declared_scope_1.emptyByScope)(), ...(rtm?.declaredScope?.byScope ?? {}) },
+        unreachableDeclaringCount: typeof rtm?.declaredScope?.unreachableDeclaring === 'number' ? rtm.declaredScope.unreachableDeclaring : 0,
     };
 }
 const live = new Map();

package/dist/holmes/server/dashboard.js

@@ -58,6 +58,8 @@ 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");
+const declared_scope_1 = require("../rtm/declared-scope");
+const test_files_1 = require("../cpg/test-files");
 /**
  * Start a lightweight standalone Node.js HTTP server for interactive dashboard & RTM visualization.
  *
@@ -130,11 +132,20 @@ async function startDashboardServer(options) {
                 }
                 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]));
+                // @implements A-SPEC-665 — the second axis. The anchor axis above says WHERE a spec is
+                // anchored; this one says what it DECLARED, which is the only way to tell "an anchor is
+                // missing" from "there is no production file to anchor". Predicates come from the mechanisms
+                // themselves (the scan's own paths, the file-anchor predicate, the test predicate) so the two
+                // readers cannot drift apart.
+                const scannedPaths = new Set(files.map((f) => f.sourcePath));
+                const fttOf = new Map(specs.map((s) => [s.id, String(s.sections?.['Files to Touch'] ?? '')]));
+                const declaredScope = (0, declared_scope_1.declaredScopeCensus)(census.unlinked.map((u) => ({ id: u.id, ftt: fttOf.get(u.id) ?? '' })), { isScanned: (rel) => scannedPaths.has(rel), isFileAnchorable: (rel) => (0, file_anchors_1.isFileAnchorPath)(rel), isTest: (rel) => (0, test_files_1.isTestFile)(rel) });
                 const enrichedSpecs = specs.map((s) => {
                     const isA = s.id.startsWith('A-SPEC');
                     const covered = isA ? implementedSpecIds.has(s.id) : s.status === 'approved';
                     const reason = reasonOf.get(s.id);
-                    return { ...s, covered, legacyStatus: !isCanonicalStatus(s.status), ...(reason ? { unlinkedReason: reason } : {}) };
+                    const scope = declaredScope.byId[s.id];
+                    return { ...s, covered, legacyStatus: !isCanonicalStatus(s.status), ...(reason ? { unlinkedReason: reason } : {}), ...(scope ? { declaredScope: scope } : {}) };
                 });
                 // 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
@@ -194,6 +205,8 @@ async function startDashboardServer(options) {
                     approval,
                     implementation,
                     linkCensus: census,
+                    // @implements A-SPEC-665
+                    declaredScope: { byScope: declaredScope.byScope, unreachableDeclaring: declaredScope.unreachableDeclaring },
                     unmapped,
                     nonSpec,
                     retired,

package/package.json

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

@@ -124,6 +124,25 @@ 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`).