@holmes-lab/holmes-kit 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.16.0] - 2026-09-07
+
+The graph learns to speak intent, and the call graph learns to speak up at sealing time. An A-SPEC
+approval now returns what your Files-to-Touch declaration *missed* — and every spec the graph
+names arrives with its one-sentence intent beside the id, extracted (never generated) from the
+spec store. Two more mechanisms were benchmarked under pre-registration and honestly discarded.
+
+### Added
+- **Impact advisory on approval (REQ-566)** — a successful A-SPEC `spec_approve` may now carry
+  `impactAdvisory`: files whose symbols **call into** the declared Files-to-Touch but sit outside
+  the declaration (1-hop, capped at 10, repo-relative allow-list). Advisory, never verdict: it
+  rides the response *after* the seal is committed, degrades to absence on any failure, and every
+  emission lands in an observation ledger (`.ax/ledger/impact-advisories.<replica>.jsonl` — paths,
+  ids and integers only) so its false-positive rate is measured *before* anyone proposes a hard
+  gate. The RTM graph persists at `.ax/rtm.sqlite` and keeps itself fresh: `rtm_impact` rebuilds
+  on basis drift, and the Stop hook spawns a TTL-gated detached reindex (staleness was measured as
+  the advisory's quality factor: 7 findings on an 8-day-old graph, 17 after a fresh one).
+- **SPEC intent summaries in the graph (REQ-568)** — graph nodes gain a `summary` column (schema
+  `rtm-graph/2` → `/3`; old stores rebuild automatically on first use, no migration step). Every
+  SPEC node stores `"<title> — <first sentence of its intent section>"`, extracted
+  deterministically (REQ=Problem / Need, H-SPEC=Intent, A-SPEC=Objective; 200-char cap; title-less
+  legacy specs — 20 measured in this very store — fall back to sentence, then id). Same store,
+  byte-identical graph; measured cost +6.4% build time / +4.2% file size. `RtmGraph.summaryOf(id)`
+  reads it back, and `rtm_impact` responses add `impactedSummaries: [{id, summary}]` beside the
+  unchanged `impacted` list.
+- **Session-context observability (REQ-564)** — the ledger records which agent/model drove a
+  session and what the governance overhead cost, per replica
+  (`.ax/ledger/session-context.<replica>.jsonl`), grounding field reports in machine attribution.
+
+### Changed
+- **`impactAdvisory.files[].anchors` shape (REQ-568, code-interface)** — anchors are now
+  `[{id, summary}]` instead of `string[]`, so the reader sees *which intent* is at risk without a
+  spec-store round trip. Consumers parsing anchors must read `.id`. The summary is information
+  only: value tests pin that the advisory's file list, ordering and `more` count are independent
+  of the prose, and the observation ledger stays prose-free.
+
+### Notes
+- Two pre-registered negatives, kept as records rather than shipped: the judgement-axis
+  FACT/EVIDENCE bundle tied its bench (0.480 vs 0.478) and was discarded with its re-attempt
+  conditions sealed (REQ-567, 15th rejection); a spec-intent **vector assist** for uncited
+  requests was built, measured byte-identical to the lexical path over 441 held-out traceability
+  cases (long queries already match ~371 specs lexically; the lexical-zero segment is protected by
+  the reorder-not-admit rule), reverted, and its A/T-SPECs retired (REQ-568 S3, 16th rejection).
+  The S-491 embedding win belongs to direct query→file ranking and does not transport through the
+  spec-matching layer.
+
 ## [0.15.0] - 2026-09-06
 
 The first field report on Holmes-Kit's own operational data (1,412 unique approval requests vs. 8

package/dist/.build-id

@@ -1 +1 @@
-2a7fb45-mtps37rf
+b540876-mtqeiitb

package/dist/holmes/governance/approval-queue.d.ts

@@ -27,6 +27,9 @@ export interface RefusalRecord {
     why: string;
     ts: string;
     replica?: string;
+    /** @implements A-SPEC-564.2 — the byte size of the deny feedback this refusal put back into the
+     * conversation (base reason + queue hint). Observation only; absent on legacy records. */
+    reasonBytes?: number;
 }
 export declare function refusalsFilename(replica: string): string;
 /** Born split: there is no legacy single `refusals.jsonl` — the file did not exist before replicas did. */
@@ -121,6 +124,7 @@ export declare function enqueueApprovalRequest(root: string, req: {
     kind: string;
     target: string;
     why: string;
+    reasonBytes?: number;
 }): boolean;
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 export declare function readQueue(root: string, opts?: {
@@ -137,4 +141,6 @@ export declare function queueHint(root: string, req: {
     kind: string;
     target: string;
     why: string;
+}, opts?: {
+    baseReasonBytes?: number;
 }): string;

package/dist/holmes/governance/approval-queue.js

@@ -281,6 +281,10 @@ function enqueueApprovalRequest(root, req) {
             why: req.why,
             ts: new Date().toISOString(),
             ...(replica !== undefined && replica !== '' ? { replica } : {}),
+            // @implements A-SPEC-564.2 — only the refusal log carries the feedback cost; inbox kinds have
+            // no deny text to measure.
+            ...(!exports.DECISION_KINDS.has(req.kind) && typeof req.reasonBytes === 'number' && Number.isFinite(req.reasonBytes)
+                ? { reasonBytes: Math.max(0, Math.round(req.reasonBytes)) } : {}),
         };
         // TYPE BEFORE WRITE, for the same reason as the read (round-7): `appendFileSync` on a FIFO with
         // no reader blocks in open(2) forever. Guarding only the reader left the GATE wedged — measured:
@@ -344,7 +348,7 @@ function readQueue(root, opts) {
  * Appended ONLY when the enqueue succeeded: a hint naming an id that was never written would send
  * the operator to an empty list.
  */
-function queueHint(root, req) {
+function queueHint(root, req, opts) {
     const id = approvalRequestId(req.kind, req.target);
     // @implements A-SPEC-246
     // Decisions are read BEFORE filing, so a human's answer reaches the agent in the very refusal
@@ -375,7 +379,11 @@ function queueHint(root, req) {
     const denialLine = decided?.event === 'denied'
         ? (0, screen_safe_1.wrapColumns)(`\n[거부됨${decided.reason ? `: ${(0, screen_safe_1.flattenField)(decided.reason, 300)}` : ''}] 같은 요청을 반복하지 말고 거부 사유를 해소해 사용자와 상의하십시오.`, 76, '  \u2502 ')
         : '';
-    return enqueueApprovalRequest(root, req)
-        ? `${denialLine}\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`
+    // @implements A-SPEC-564.2 — the hint is composed BEFORE the enqueue so the refusal record can
+    // carry its own feedback cost: reasonBytes = the caller's base reason + this hint, i.e. the text
+    // that actually re-enters the conversation. Observation only — nothing reads it on a gate path.
+    const hint = `${denialLine}\n[승인 대기 ${id}] 운영자: ${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
+    return enqueueApprovalRequest(root, { ...req, reasonBytes: (opts?.baseReasonBytes ?? 0) + hint.length })
+        ? hint
         : denialLine;
 }

package/dist/holmes/governance/session-context.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The session-context ledger: WHO attached (agent name@version) and — where a harness exposes it —
+ * WITH WHAT (model ids, token totals). REQ-564's whole point is that none of this existed anywhere
+ * in the ledgers (measured across provenance, outcomes and the queue), while the sources were one
+ * line away: MCP clientInfo carries {name, version} for ALL three harnesses (the server used the
+ * name and dropped the version), and Claude's transcript carries model + usage per message.
+ *
+ * HARNESS-NEUTRAL BY CONSTRUCTION: the client stamp is written by the MCP SERVER, which every
+ * harness talks to — the first design pinned it on the Stop hook and was caught as Claude-biased
+ * (the owner's catch that also produced REQ-565's gate). Enrichment beyond the stamp is
+ * capability-declared per harness, never faked.
+ *
+ * NUMBERS ONLY. Records carry names, versions, model ids and integers. The transcript's
+ * conversation text, commands and paths have no field to land in — the same structural privacy
+ * QueueEventLite uses. Observation NEVER feeds a verdict (Judgments must not be budgeted).
+ */
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreation: number;
+}
+export interface ClientRecord {
+    kind: 'client';
+    sessionKey: string;
+    client: string;
+    clientVersion: string;
+    ts: string;
+    replica?: string;
+}
+export interface UsageRecord {
+    kind: 'usage';
+    sessionKey: string;
+    models: string[];
+    usage: UsageTotals;
+    turns: number;
+    truncated?: boolean;
+    ts: string;
+    replica?: string;
+}
+export type SessionContextRecord = ClientRecord | UsageRecord;
+export declare function sessionContextFilename(replica: string): string;
+/** Born split: no legacy single file — this ledger never existed before replicas did. */
+export declare function isSessionContextFilename(name: string): boolean;
+/** Append to THIS machine's chain. Fail-open: observation must never break the observed. */
+export declare function appendSessionContext(root: string, rec: SessionContextRecord): boolean;
+/** Every replica's records, merged by ts (stable). Missing dir → []; corrupt lines skipped. */
+export declare function readSessionContext(root: string): SessionContextRecord[];
+/**
+ * @implements A-SPEC-564.1
+ * The lazy-once stamper the MCP server wires into its call path. Lazy because `getClientVersion()`
+ * has a value only AFTER initialize — the first tool call is the earliest honest moment — and
+ * because the ledger's location arrives with the first `root`-carrying call. Once, because a
+ * session has one identity; a root-less call defers rather than consumes the chance.
+ */
+export declare function makeSessionStamper(info: () => {
+    name?: string;
+    version?: string;
+} | undefined, append?: (root: string, rec: ClientRecord) => boolean, sessionKey?: string): (root: unknown) => void;
+/**
+ * @implements A-SPEC-564.2
+ * Numbers out of a Claude transcript — model ids, the four usage sums, a turn count. Streaming and
+ * capped: a giant transcript yields an honest partial sum with `truncated`, never a slow Stop (a
+ * huge response once blocked the very fix that would have shrunk it — observation must not repeat
+ * that shape). The return type has no field a conversation could leak through.
+ */
+export declare function summarizeTranscript(lines: Iterable<string>, opts?: {
+    maxBytes?: number;
+}): {
+    models: string[];
+    usage: UsageTotals;
+    turns: number;
+    truncated: boolean;
+};

package/dist/holmes/governance/session-context.js

@@ -0,0 +1,179 @@
+"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.sessionContextFilename = sessionContextFilename;
+exports.isSessionContextFilename = isSessionContextFilename;
+exports.appendSessionContext = appendSessionContext;
+exports.readSessionContext = readSessionContext;
+exports.makeSessionStamper = makeSessionStamper;
+exports.summarizeTranscript = summarizeTranscript;
+// @implements A-SPEC-564.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("./replica-id");
+const FILE_RE = /^session-context\.([^.]+)\.jsonl$/;
+function sessionContextFilename(replica) {
+    return `session-context.${replica}.jsonl`;
+}
+/** Born split: no legacy single file — this ledger never existed before replicas did. */
+function isSessionContextFilename(name) {
+    return FILE_RE.test(name);
+}
+/** Append to THIS machine's chain. Fail-open: observation must never break the observed. */
+function appendSessionContext(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', sessionContextFilename(replica));
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ ...rec, replica })}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Every replica's records, merged by ts (stable). Missing dir → []; corrupt lines skipped. */
+function readSessionContext(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter(isSessionContextFilename).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    let i = 0;
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && (r.kind === 'client' || r.kind === 'usage')
+                    && typeof r.sessionKey === 'string' && typeof r.ts === 'string') {
+                    out.push({ r: r, i: i++ });
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out.sort((a, b) => (a.r.ts < b.r.ts ? -1 : a.r.ts > b.r.ts ? 1 : a.i - b.i)).map((e) => e.r);
+}
+/**
+ * @implements A-SPEC-564.1
+ * The lazy-once stamper the MCP server wires into its call path. Lazy because `getClientVersion()`
+ * has a value only AFTER initialize — the first tool call is the earliest honest moment — and
+ * because the ledger's location arrives with the first `root`-carrying call. Once, because a
+ * session has one identity; a root-less call defers rather than consumes the chance.
+ */
+function makeSessionStamper(info, append = appendSessionContext, sessionKey = `mcp-${process.pid}`) {
+    let stamped = false;
+    return (root) => {
+        if (stamped || typeof root !== 'string' || root === '')
+            return;
+        try {
+            const v = (() => { try {
+                return info();
+            }
+            catch {
+                return undefined;
+            } })();
+            stamped = append(root, {
+                kind: 'client',
+                sessionKey,
+                client: v?.name ?? 'unknown',
+                clientVersion: v?.version ?? 'unknown',
+                ts: new Date().toISOString(),
+            });
+        }
+        catch { /* observation must never break the observed call */ }
+    };
+}
+/**
+ * @implements A-SPEC-564.2
+ * Numbers out of a Claude transcript — model ids, the four usage sums, a turn count. Streaming and
+ * capped: a giant transcript yields an honest partial sum with `truncated`, never a slow Stop (a
+ * huge response once blocked the very fix that would have shrunk it — observation must not repeat
+ * that shape). The return type has no field a conversation could leak through.
+ */
+function summarizeTranscript(lines, opts) {
+    const maxBytes = opts?.maxBytes ?? 64 * 1024 * 1024;
+    const models = [];
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
+    let turns = 0;
+    let bytes = 0;
+    let truncated = false;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    for (const line of lines) {
+        bytes += line.length + 1;
+        if (bytes > maxBytes) {
+            truncated = true;
+            break;
+        }
+        let m;
+        try {
+            const d = JSON.parse(line);
+            m = d && typeof d === 'object' ? d.message : undefined;
+        }
+        catch {
+            continue;
+        }
+        if (!m || typeof m !== 'object' || !m.usage || typeof m.usage !== 'object')
+            continue;
+        turns += 1;
+        if (typeof m.model === 'string' && m.model !== '' && !models.includes(m.model))
+            models.push(m.model);
+        usage.input += num(m.usage.input_tokens);
+        usage.output += num(m.usage.output_tokens);
+        usage.cacheRead += num(m.usage.cache_read_input_tokens);
+        usage.cacheCreation += num(m.usage.cache_creation_input_tokens);
+    }
+    return { models, usage, turns, truncated };
+}

package/dist/holmes/hooks/pre-tool-use.js

@@ -461,8 +461,11 @@ function evaluateHook(input, specsDir, opts) {
             // @implements A-SPEC-244 — the refusal itself files the review request. The queue kind is the
             // approval SCOPE kind ('shell'), so the reviewing CLI can mint a covering grant mechanically.
             if (!covers) {
-                return deny('requires an approval that covers this command'
-                    + (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'shell', target: command, why: assessment.reasons.join('; ') }));
+                // @implements A-SPEC-564.2 — the base reason's length rides along so the refusal record
+                // knows the FULL feedback cost (base + hint), not just the hint's half.
+                const base = 'requires an approval that covers this command';
+                return deny(base
+                    + (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'shell', target: command, why: assessment.reasons.join('; ') }, { baseReasonBytes: base.length }));
             }
             // @implements A-SPEC-141
             // Check and spend in ONE atomic operation. The previous shape asked `isNonceConsumed(...)`

package/dist/holmes/hooks/rtm-refresh-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/holmes/hooks/rtm-refresh-child.js

@@ -0,0 +1,56 @@
+"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 });
+// @implements A-SPEC-566.4
+/**
+ * The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
+ * by `maybeSpawnRtmRefresh` (rtm-refresh.ts) outside any turn; nothing in the hook path imports
+ * this file, which is what keeps A-SPEC-510.2 honest (no wasm rides into a gate process).
+ * rtm_impact's warm path IS the refresh: hash-cached scan, reusable-graph rebuild when stale.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+if (require.main === module) {
+    try {
+        const root = process.argv[2];
+        if (root && fs.existsSync(path.join(root, '.ax'))) {
+            const { makeHandlers } = require('../mcp/handlers');
+            const { LocalMarkdownRepository } = require('../spec/spec-store');
+            const h = makeHandlers(new LocalMarkdownRepository(path.join(root, '.ax', 'specs')));
+            void h.rtm_impact({ root, changed: [] }).catch(() => undefined);
+        }
+    }
+    catch { /* fail-soft: a failed refresh leaves the old graph, which the advisory tolerates */ }
+}

package/dist/holmes/hooks/rtm-refresh.d.ts

@@ -0,0 +1,13 @@
+export declare const RTM_REFRESH_TTL_MS: number;
+export declare const RTM_REFRESH_MARKER: string;
+export interface RtmRefreshOpts {
+    root: string;
+    now: number;
+    execPath: string;
+    scriptPath: string;
+    spawn: (cmd: string, args: string[], opts: object) => {
+        unref?: () => void;
+    };
+    ttlMs?: number;
+}
+export declare function maybeSpawnRtmRefresh(opts: RtmRefreshOpts): void;

package/dist/holmes/hooks/rtm-refresh.js

@@ -0,0 +1,76 @@
+"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.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
+exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
+// @implements A-SPEC-566.4
+/**
+ * Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
+ * be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
+ * hook — the moment changes exist — spawns a DETACHED reindex behind a TTL gate. The idiom is
+ * A-SPEC-547.2's update refresh verbatim: TTL file, detached child, fail-soft everywhere; the
+ * parent never waits (zero turn latency) and the approval path still only ever REOPENS the graph.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.RTM_REFRESH_TTL_MS = 30 * 60 * 1000;
+exports.RTM_REFRESH_MARKER = path.join('.ax', 'state', 'rtm-refresh-last');
+function maybeSpawnRtmRefresh(opts) {
+    try {
+        if (!fs.existsSync(path.join(opts.root, '.ax')))
+            return; // nothing to refresh
+        const marker = path.join(opts.root, exports.RTM_REFRESH_MARKER);
+        const ttl = opts.ttlMs ?? exports.RTM_REFRESH_TTL_MS;
+        try {
+            const age = opts.now - fs.statSync(marker).mtimeMs;
+            if (age < ttl)
+                return; // one refresh per window
+        }
+        catch { /* absent marker → refresh is due */ }
+        // Touch BEFORE spawning: a burst of Stops inside one window must not stampede children.
+        try {
+            fs.mkdirSync(path.dirname(marker), { recursive: true });
+            fs.writeFileSync(marker, String(opts.now));
+            fs.utimesSync(marker, new Date(opts.now), new Date(opts.now));
+        }
+        catch { /* an unwritable marker is not a reason to skip the refresh itself */ }
+        const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root], { detached: true, stdio: 'ignore' });
+        child?.unref?.();
+    }
+    catch { /* freshness is maintenance, never a hook failure */ }
+}
+// The child lives in rtm-refresh-child.ts, NOT here: this module is required by the Stop hook, and
+// the gate path must never carry the AST substrate (A-SPEC-510.2 pinned it, and its static check
+// caught the first cut of this slice doing exactly that). The gate side is fs+path only.

package/dist/holmes/hooks/stop.js

@@ -910,6 +910,48 @@ if (require.main === module) {
             const unrecorded = unrecordedApprovals(stopProjectRoot());
             // @implements A-SPEC-455
             const rolledBack = rolledBackLedgers(stopProjectRoot());
+            // @implements A-SPEC-564.2 — the Claude usage enrichment: numbers out of transcript_path into
+            // the session-context ledger, once per session. Capability-declared: Codex/AGY pass no
+            // transcript_path and skip silently. Fail-open around EVERYTHING — observation never touches
+            // the verdict below (Judgments must not be budgeted), and a giant transcript yields a capped
+            // partial sum, never a slow Stop.
+            try {
+                const tPath = input.transcript_path;
+                if (typeof tPath === 'string' && tPath !== '') {
+                    const sc = require('../governance/session-context');
+                    const root = stopProjectRoot();
+                    const already = sc.readSessionContext(root).some((r) => r.kind === 'usage' && r.sessionKey === sessionId);
+                    if (!already) {
+                        // Adversarial round (2026-09-06): a FIFO at transcript_path blocked this read FOREVER,
+                        // wedging every turn end — the queue writer's round-7 lesson, replayed on the observer.
+                        // TYPE BEFORE READ: only a regular file is a transcript; anything else is a silent skip.
+                        if (!fs.lstatSync(tPath).isFile())
+                            throw new Error('not a regular file');
+                        const text = fs.readFileSync(tPath, 'utf8');
+                        const sum = sc.summarizeTranscript(text.split('\n'));
+                        if (sum.turns > 0) {
+                            sc.appendSessionContext(root, {
+                                kind: 'usage', sessionKey: sessionId, models: sum.models, usage: sum.usage,
+                                turns: sum.turns, ...(sum.truncated ? { truncated: true } : {}), ts: new Date().toISOString(),
+                            });
+                        }
+                    }
+                }
+            }
+            catch { /* silent skip — the other harnesses' path, and any read failure, land here */ }
+            // @implements A-SPEC-566.4 — graph freshness rides the same turn boundary, detached and
+            // TTL-gated (A-SPEC-547.2's idiom): staleness was MEASURED to be the advisory's quality
+            // factor (7 findings on an 8-day graph, 17 after a 1s reindex). Never waits, never judges.
+            try {
+                const { maybeSpawnRtmRefresh } = require('./rtm-refresh');
+                const cp = require('node:child_process');
+                maybeSpawnRtmRefresh({
+                    root: stopProjectRoot(), now: Date.now(), execPath: process.execPath,
+                    scriptPath: path.resolve(__dirname, 'rtm-refresh-child.js'),
+                    spawn: (cmd, args, o) => cp.spawn(cmd, args, o),
+                });
+            }
+            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-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.

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

@@ -261,23 +261,18 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         reason: string;
         findings?: undefined;
         conflict?: undefined;
-        approved?: undefined;
-        digest?: undefined;
     } | {
         ok: boolean;
         reason: string;
         findings: import("../spec/validator").Finding[];
         conflict?: undefined;
-        approved?: undefined;
-        digest?: undefined;
     } | {
         ok: boolean;
         reason: string;
         conflict: import("../spec/version-conflict").ConflictDetail;
         findings?: undefined;
-        approved?: undefined;
-        digest?: undefined;
     } | {
+        impactAdvisory?: import("../rtm/impact-advisory").ImpactAdvisory | undefined;
         approved: string;
         digest: string;
         ok?: undefined;
@@ -536,6 +531,10 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     }): Promise<{
         breadthWarning?: string | undefined;
         impacted: string[];
+        impactedSummaries: {
+            id: string;
+            summary: string | null;
+        }[];
         rankedImpact: {
             file: string;
             score: number;