@holmes-lab/holmes-kit 0.20.1 → 0.21.0

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";

package/dist/holmes/mcp/handlers.js

@@ -919,6 +919,10 @@ function makeRawHandlers(store, opts) {
             projectRootOf,
             refusal: reason => new HandlerRefusal(reason),
             fileDigestOf,
+            // @implements A-SPEC-658 — the impact gate reads trace gaps from the same store and scan the
+            // graph handlers use.
+            listSpecs: () => store.list(),
+            cachedScan,
         }),
         // @implements A-SPEC-642 — placed in the one slot no public-key-order pin covers (the handler suites pin
         // spec_create..spec_upgrade, spec_retire..spec_unseal, spec_unseal+5, spec_approve+4, spec_next+3,

package/dist/holmes/rtm/anchor-comment.d.ts

@@ -6,4 +6,6 @@
  * a syntax this map does not know returns null and the caller must REFUSE to write — an honest
  * refusal beats a broken file, and beats an anchor the gate cannot read.
  */
+export declare const INJECTABLE_EXTENSIONS: readonly string[];
+export declare const INJECTABLE_BASENAMES: readonly string[];
 export declare function anchorLineFor(filePath: string, aspecId: string): string | null;

package/dist/holmes/rtm/anchor-comment.js

@@ -9,6 +9,7 @@
  * refusal beats a broken file, and beats an anchor the gate cannot read.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.INJECTABLE_BASENAMES = exports.INJECTABLE_EXTENSIONS = void 0;
 exports.anchorLineFor = anchorLineFor;
 const SLASH = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'java', 'c', 'h', 'cc', 'cpp',
     'hpp', 'cs', 'go', 'rs', 'swift', 'kt', 'kts', 'scala', 'dart']);
@@ -16,6 +17,13 @@ const HASH = new Set(['py', 'rb', 'sh', 'bash', 'zsh', 'fish', 'yml', 'yaml', 't
     'r', 'jl', 'cmake', 'mk']);
 const CSS = new Set(['css', 'scss', 'less']);
 const HASH_BASENAMES = new Set(['Makefile', 'Dockerfile', 'Rakefile', 'Gemfile']);
+// @implements A-SPEC-655 — the injector's syntax set, exported so the census can read every file
+// the injector may have written. Measured 2026-09-16: this map knew `.sh/.yml/.toml/...` and the
+// indexer's SCANNABLE_EXTENSIONS did not, so `spec_remediate` planted anchors the graph could
+// never see (scripts/ci-local.sh → A-SPEC-530.1). `rtm/file-anchors.ts` reads the difference and
+// link-census.test.ts pins INJECTABLE ⊆ SCANNABLE ∪ FILE_ANCHOR over the whole set.
+exports.INJECTABLE_EXTENSIONS = [...new Set([...SLASH, ...HASH, ...CSS])].sort();
+exports.INJECTABLE_BASENAMES = [...HASH_BASENAMES].sort();
 function anchorLineFor(filePath, aspecId) {
     const basename = filePath.slice(filePath.lastIndexOf('/') + 1);
     if (HASH_BASENAMES.has(basename))

package/dist/holmes/rtm/file-anchors.d.ts

@@ -0,0 +1,9 @@
+/** Extensions the injector writes that the indexer does not parse — the census reads these. */
+export declare const FILE_ANCHOR_EXTENSIONS: readonly string[];
+/** True for a PROJECT-RELATIVE POSIX path the file-anchor scanner reads. */
+export declare function isFileAnchorPath(rel: string): boolean;
+/**
+ * Repo-relative POSIX path → A-SPEC ids, for every file `isFileAnchorPath` admits. Same walk and
+ * resilience as `scanTestAnchors`: unreadable files are skipped, never reported as anchor-less.
+ */
+export declare function scanFileAnchors(root: string): Record<string, string[]>;

package/dist/holmes/rtm/file-anchors.js

@@ -0,0 +1,128 @@
+"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.FILE_ANCHOR_EXTENSIONS = void 0;
+exports.isFileAnchorPath = isFileAnchorPath;
+exports.scanFileAnchors = scanFileAnchors;
+// @implements A-SPEC-655
+/**
+ * Anchors in files the injector can write but the indexer never parses.
+ *
+ * `anchor-comment.ts` knows the comment syntax of `.sh/.yml/.toml/.rb/...` and `spec_remediate`
+ * injects `# @implements` there; `cpg-scanner.ts` ingests 19 AST extensions and none of those.
+ * Measured 2026-09-16: `scripts/ci-local.sh` carries a hash-comment anchor line naming
+ * A-SPEC-530.1 that no graph edge will ever reflect. (The id is deliberately not written here in
+ * anchor form: the scanner reads the marker anywhere in a file, and this module's first attempt
+ * quoted the line verbatim — which made THIS file the implementer of A-SPEC-530.1.) This scanner reads exactly the injector's set minus the indexer's set —
+ * off-graph, like `scanTestAnchors` — so the census can say "anchored in a file the graph does
+ * not parse" instead of "no trace". The set difference is computed, not copied: when either list
+ * moves, `FILE_ANCHOR_EXTENSIONS` follows, and link-census.test.ts pins the inclusion invariant
+ * INJECTABLE ⊆ SCANNABLE ∪ FILE_ANCHOR over the whole set.
+ *
+ * NOT a graph input. Test files stay out (isTestFile), `.ax/` stays out (spec documents mention
+ * the marker in prose), and nothing here creates a node or an edge.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const anchor_comment_1 = require("./anchor-comment");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const test_scope_1 = require("./test-scope");
+const SCANNABLE = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS.map((e) => e.replace(/^\./, '')));
+/** Extensions the injector writes that the indexer does not parse — the census reads these. */
+exports.FILE_ANCHOR_EXTENSIONS = anchor_comment_1.INJECTABLE_EXTENSIONS.filter((e) => !SCANNABLE.has(e));
+const FILE_ANCHOR = new Set(exports.FILE_ANCHOR_EXTENSIONS);
+const BASENAMES = new Set(anchor_comment_1.INJECTABLE_BASENAMES);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.ax']);
+// `isTestFile` is language-scoped on purpose (an unscoped `tests/` rule once swallowed
+// `src/holmes/spec/**`); a shell script or workflow under a test directory has no such hazard and is
+// test scaffolding, so the directory rule applies here in full.
+const TEST_DIRS = new Set(['test', 'tests', '__tests__']);
+/** True for a PROJECT-RELATIVE POSIX path the file-anchor scanner reads. */
+function isFileAnchorPath(rel) {
+    const segs = rel.split('/');
+    if (rel.startsWith('.ax/') || segs.some((seg) => SKIP_DIRS.has(seg)))
+        return false;
+    if ((0, cpg_scanner_1.isTestFile)(rel) || segs.slice(0, -1).some((seg) => TEST_DIRS.has(seg)))
+        return false;
+    const base = rel.slice(rel.lastIndexOf('/') + 1);
+    if (BASENAMES.has(base))
+        return true;
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0)
+        return false;
+    return FILE_ANCHOR.has(base.slice(dot + 1).toLowerCase());
+}
+/**
+ * Repo-relative POSIX path → A-SPEC ids, for every file `isFileAnchorPath` admits. Same walk and
+ * resilience as `scanTestAnchors`: unreadable files are skipped, never reported as anchor-less.
+ */
+function scanFileAnchors(root) {
+    const out = {};
+    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('/');
+            if (!isFileAnchorPath(rel))
+                continue;
+            let text;
+            try {
+                text = fs.readFileSync(abs, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const ids = (0, test_scope_1.extractAnchors)(text);
+            if (ids.length)
+                out[rel] = ids;
+        }
+    };
+    walk(root);
+    return out;
+}

package/dist/holmes/rtm/ftt-fulfilment.d.ts

@@ -0,0 +1,42 @@
+export interface FttItem {
+    path: string;
+    line: string;
+    isNew: boolean;
+    alternative: boolean;
+}
+export interface FttFulfilment {
+    /** Items examined — so "no finding" can be told from "nothing to examine". */
+    declared: number;
+    missing: Array<{
+        path: string;
+        isNew: boolean;
+    }>;
+    moved: Array<{
+        path: string;
+        foundAt: string[];
+    }>;
+    alternatives: Array<{
+        path: string;
+        line: string;
+    }>;
+}
+export interface FulfilmentRecord {
+    aspec: string;
+    declared: number;
+    missing: string[];
+    moved: string[];
+    ts: string;
+    replica?: string;
+}
+/**
+ * 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.
+ */
+export declare function fttItems(fttText: string): FttItem[];
+export declare function fttFulfilment(fttText: string, exists: (rel: string) => boolean, locate: (basename: string) => string[]): FttFulfilment | null;
+/** One walk, then O(1) lookups. Unreadable directories are skipped, never reported as empty. */
+export declare function locateByBasename(root: string): (basename: string) => string[];
+/** The observation ledger — repo-relative paths, a spec id, integers and a timestamp; nothing else. */
+export declare function appendFttFulfilment(root: string, rec: FulfilmentRecord): boolean;
+export declare function readFttFulfilments(root: string): FulfilmentRecord[];

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;