@holmes-lab/holmes-kit 0.14.0 → 0.16.0

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;

package/dist/holmes/mcp/handlers.js

@@ -151,7 +151,8 @@ const cacheDirFor = (root) => {
 };
 // @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
 // by an older build is rebuilt rather than read with new assumptions.
-const RTM_GRAPH_SCHEMA = 'rtm-graph/2';
+// @implements A-SPEC-568.1 — /3: nodes gained the intent `summary` column.
+const RTM_GRAPH_SCHEMA = 'rtm-graph/3';
 const RTM_EXTRACTOR_VERSION = 'holmes-rtm/1';
 const cachedScan = (root, repoRoot = root) => new cpg_scanner_1.CpgScanner(undefined, new scan_cache_1.ScanFileCache(cacheDirFor(root))).scan(root, repoRoot);
 // @implements A-SPEC-131
@@ -189,6 +190,7 @@ const approval_grants_1 = require("../governance/approval-grants");
 const spec_digest_1 = require("../spec/spec-digest");
 const spec_store_2 = require("../spec/spec-store");
 const breaking_change_1 = require("../spec/breaking-change");
+const compat_impact_1 = require("../spec/compat-impact");
 const approval_blockers_1 = require("../spec/approval-blockers");
 const approval_status_1 = require("../spec/approval-status");
 const ledger_timeline_1 = require("../governance/ledger-timeline");
@@ -1560,6 +1562,22 @@ function makeRawHandlers(store, opts) {
             const breakingIssue = (0, breaking_change_1.checkBreakingChangeDeclared)(candidate);
             if (breakingIssue)
                 return { ok: false, reason: breakingIssue };
+            // @implements A-SPEC-565.1 — the compat declaration duty rides the SAME act (REQ-565): sealing
+            // is when "did you consider the three harnesses and the three OSes" is due, and act-time is
+            // what keeps 512 already-approved specs out of retroactive violation (the 38-violation incident
+            // above). The bound reader feeds the OS cross-check from this root's working tree.
+            const compatIssue = (0, compat_impact_1.checkCompatDeclared)(candidate, {
+                // No root → no working tree to read: the OS cross-check skips file-by-file (fail-open),
+                // while the declaration syntax itself is still enforced — the duty never depends on `root`.
+                readFile: (rel) => { try {
+                    return a.root ? fs.readFileSync(path.join(a.root, rel), 'utf8') : null;
+                }
+                catch {
+                    return null;
+                } },
+            });
+            if (compatIssue)
+                return { ok: false, reason: compatIssue };
             // @implements A-SPEC-182
             // A document whose prose is still the generator's placeholder must not be sealed. Measured
             // 2026-08-13 on a brownfield adoption: H-SPEC-100 took `status: approved` and an
@@ -1667,7 +1685,46 @@ function makeRawHandlers(store, opts) {
             if (approveResolved.source === 'grant' && approveResolved.root && approveResolved.approval.nonce) {
                 (0, approval_grants_1.consumeGrantFile)(approveResolved.root, approveResolved.approval.nonce);
             }
-            return { approved: a.id, digest };
+            // @implements A-SPEC-566.2 — the impact advisory rides the SUCCESS, after the seal is done:
+            // the verdict is already committed, so nothing here can change it (advisory, never gate —
+            // Judgments must not be budgeted). Reuses the persisted graph READ-ONLY; it never scans,
+            // parses or builds (scan:build measured 20~38x — an approval must not pay that), and every
+            // failure below degrades to "no advisory field" on an otherwise identical response.
+            let impactAdvisory;
+            try {
+                if (spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    if (fs.existsSync(dbPath)) {
+                        const { declaredImpactGap, appendImpactAdvisory } = require('../rtm/impact-advisory');
+                        const { filesToTouch } = require('../spec/compat-impact');
+                        const { RtmGraph } = require('../rtm/rtm-graph');
+                        const graph = new RtmGraph(dbPath);
+                        const gap = declaredImpactGap(filesToTouch(candidate), graph, (rel) => { try {
+                            return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                        }
+                        catch {
+                            return null;
+                        } });
+                        if (gap) {
+                            const graphAsOf = (() => { try {
+                                return fs.statSync(dbPath).mtime.toISOString();
+                            }
+                            catch {
+                                return undefined;
+                            } })();
+                            impactAdvisory = { ...gap, ...(graphAsOf ? { graphAsOf } : {}) };
+                            appendImpactAdvisory(a.root, {
+                                aspec: a.id, files: gap.files.map((f) => f.path), more: gap.more,
+                                ...(graphAsOf ? { graphAsOf } : {}), ts: new Date().toISOString(),
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                impactAdvisory = undefined;
+            }
+            return { approved: a.id, digest, ...(impactAdvisory ? { impactAdvisory } : {}) };
         },
         async spec_list(a) {
             assertSpecStoreReachable('spec_list', store, a.root); // @implements A-SPEC-419
@@ -2188,6 +2245,9 @@ function makeRawHandlers(store, opts) {
             // (cached vectors only, set fixed, covered hits move, why-line attached). Any missing
             // signal — no tier, no key, cold cache, embed failure — leaves the report untouched;
             // localization itself never fails because of the semantic layer.
+            //
+            // A spec-intent-vector assist (REQ-568 S3) was wired ahead of localizeIssue here and REVERTED
+            // on its pre-registered replay — see rtm/localize.ts at the matchedSpecs join for the numbers.
             try {
                 if (report.hits.length > 1
                     && (0, localize_1.citationsIn)(a.issue, new Set(governed.map((s) => s.id))).cited.length === 0) {
@@ -2491,8 +2551,20 @@ function makeRawHandlers(store, opts) {
                     .map((id) => (id.includes('@') ? id.slice(id.lastIndexOf('@') + 1) : ''))
                     .filter((f) => f !== ''));
                 const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(g.dumpCanonical()), riSeeds, riExclude, assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
+                // @implements A-SPEC-568.2 — the intent sentence beside every impacted spec id, same order
+                // as `impacted` (which stays a bare id list for its existing consumers). Information only:
+                // nothing reads it back into the walk, the ranking or any gate.
+                const impactedSummaries = impacted.map((id) => {
+                    let summary = null;
+                    try {
+                        summary = g.summaryOf(id);
+                    }
+                    catch { /* summary stays null */ }
+                    return { id, summary };
+                });
                 return {
                     impacted,
+                    impactedSummaries,
                     rankedImpact,
                     reachedByDepth,
                     bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,
@@ -3347,6 +3419,8 @@ independent_test: true
 depends_on:
   - ${hspecId}
 breaking_change: 'none'
+harness_impact: 'none: TODO — 3하네스(claude/codex/agy) 영향 검토 후 기술'
+os_impact: 'none: TODO — 3OS(windows/mac/linux) 영향 검토 후 기술'
 ---
 
 ## Objective

package/dist/holmes/mcp/server.js

@@ -42,6 +42,17 @@ const handlers = (0, handlers_1.makeHandlers)(store, {
         return 'unknown';
     } },
 });
+// @implements A-SPEC-564.1 — the session-context stamp: WHO attached, name AND version (the version
+// was received and dropped for months). Written HERE because the server is the one place all three
+// harnesses pass through; lazy-once via the call path (clientInfo exists only after initialize, and
+// the ledger's root arrives with the first rooted call). Fail-open by construction.
+const { makeSessionStamper } = require('../governance/session-context');
+const stampSession = makeSessionStamper(() => { try {
+    return server.getClientVersion();
+}
+catch {
+    return undefined;
+} });
 // @implements A-SPEC-259 — the advertised version is the package's own, not a literal that froze at
 // 0.1.0: a hardcoded serverInfo.version blinds any client-side drift diagnosis.
 const PKG_VERSION = (() => {
@@ -109,6 +120,7 @@ const TOOLS = Object.keys(handlers)
 });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+    stampSession(req.params.arguments?.root);
     // @implements A-SPEC-189
     // The server is the first consumer of its own advertised schemas. Before this check, 15 of 26
     // handlers threw raw internal errors at `{}` over the wire, and a one-key typo in reverse_anchor