@holmes-lab/holmes-kit 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,124 @@ 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.17.0] - 2026-09-07
+
+An adversarial review of 0.16.0's own new surfaces, run against the shipped tarball the day it
+went out, drove this release: the newest repair is always the next target, and this time the
+findings were sealed before anyone else could find them. The release gate itself also gets the
+fix for the incident that let 0.16.0 ship with a frozen README.
+
+### Fixed
+- **Graph-row forgery via spec prose (REQ-569 S1, HIGH)** — a DRAFT spec (no approval needed to
+  exist) whose YAML double-quoted title carried `\n`/`\t` escapes could forge rows in the graph's
+  canonical dump, which the PPR view parsed as **real call edges** — poisoning `rankedImpact` and
+  `maintenance_analyze` (reproduced against the shipped 0.16.0 artifact, then killed). Sealed at
+  BOTH boundaries independently: `specSummary` now folds whitespace over the whole summary (title
+  included — the sentence-only fold was the hole), and `RtmGraph.addNode` folds structural
+  characters at the storage boundary so no future caller can break a dump row either. Each face
+  verified alone. A high-effort review of this very fix then widened it: tabs riding in via spec
+  `id:`/`depends_on:` still shifted dump columns, so `dumpCanonical` now folds EVERY text column
+  at emission (single choke point; the 13-cell row invariant is pinned by test), and the graph
+  extractor version bumped to `holmes-rtm/2` so a persisted store written by unfixed 0.16.0 —
+  whose summary column may already carry forged rows — is force-rebuilt instead of reused.
+- **Grader/doctor parity pair (REQ-569 S4)** — `isHighRiskPath` folds `.` path segments before
+  judging (`src/holmes/./governance/x.ts` no longer dodges the risk roots; `..` is deliberately
+  NOT folded — the grader widens sight, never impersonates path resolution, and the enforcer
+  stays byte-literal). The codex doctor's npx-pin branch now compares the pin against the
+  installed version and WARNs on a stale pin (parity with the `.mcp.json` drift check) — an old
+  fixture that had enshrined the gap as PASS was repinned to the current version. Review
+  follow-ups sealed in the same release: a `..`-bearing Files-to-Touch token is now FLAGGED
+  high-risk (the hook does not canonicalize relative paths, so a `src/app/../holmes/...` spelling
+  stayed admissible at the byte-literal enforcer while the grader called it benign — flagging the
+  ambiguous ascent token closes the self-approval hole without impersonating path resolution);
+  non-semver pins (`@latest`, `^x.y.z`) judge `unknown` instead of an inverted "stale pin" WARN;
+  and the sealing-time advisory now closes its SQLite handle (a per-approval native-handle leak in
+  the long-lived MCP server, and a file-lock risk on Windows).
+- **The docs-currency gate is bidirectional now (REQ-570)** — 0.16.0 shipped with README's
+  feature list frozen at "v0.14.x" and zero 0.16.0 entries, because the gate's instruction was
+  "grep for stale phrases": a feature never written produces zero hits, and zero hits read as
+  "no drift". The publish playbook now demands three checks per user-facing change — ADDITION
+  (the entry must exist; zero grep hits are a missing-entry signal, not a pass), drift (the old
+  wording), and stale markers (version-pinned section labels are drift generators and get
+  removed, not policed). The incident is recorded in the playbook itself, the README repaired
+  retroactively, and the new wording pinned by tests.
+
+### Changed
+- **The impact/advisory graph is approved-only (REQ-569 S2)** — the persisted RTM graph that
+  feeds `rtm_impact`, the sealing-time advisory and the intent summaries now builds from SEALED
+  specs only: a draft needs no approval to exist, so it can no longer reach the agent-visible
+  channels (that was the forgery's delivery vehicle). The closure walks edges, so the channel
+  filter is node existence — an anchor naming a draft keeps its id but carries no prose until
+  approval. Diagnosis (`rtm_check`) and matching (`issue_localize`) keep their existing
+  populations; old `rtm.sqlite` files rebuild automatically on basis drift. Replay pins unmoved
+  to the digit.
+- **Annotation caps (REQ-569 S3)** — `impactedSummaries` caps at 40 (`summariesOmitted` counts
+  the rest; `impacted` itself is never truncated) and advisory anchors cap at 10 per file
+  (`anchorsOmitted`). Measured on this repository's hub-grade impact (342 specs): the response
+  shrank **104,706 → 18,708 bytes (−82%)**, and the omitted tail costs no summary lookups.
+
+### Added
+- **Anchor-density advisory (REQ-569 S5, observation only)** — sealing an A-SPEC whose
+  Files-to-Touch contains an anchor-dense file (live `implements` count ≥ max(8, p90 of the
+  store's distribution)) annotates the response with `anchorDensity: [{path, anchors, p90}]` and
+  records it to `anchor-density.<replica>.jsonl` (paths and integers only). Grounded in the
+  measured precision tax of anchor accumulation (authoring one spec moved replay recall
+  0.5476→0.5060); a count GATE was considered and refused — the thresholds are prose constants,
+  and promotion or rejection will be decided by this ledger, the impactAdvisory lifecycle.
+
+### Notes
+- One inherited finding was honestly killed instead of "fixed": the recorded
+  "scanTestAnchors only sees a file's first anchor" defect does **not reproduce** at HEAD (all
+  standalone-comment anchors are consumed by ART-4 and the execution-evidence attribution alike);
+  the only non-recognition is the trailing-comment form, which is the sealed anchor idiom rule.
+  Stale findings get re-measured, not re-fixed.
+
+## [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/README.md

@@ -14,7 +14,11 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.14.x Production Features)
+### 🛡️ Currently Supported Features (Production Features)
+
+- 📣 **Impact Advisory at sealing time** *(new in 0.16.0)*: approving an A-SPEC now returns what your Files-to-Touch declaration *missed* — files whose symbols **call into** the declared scope from outside it (1-hop, capped, repo-relative allow-list), computed from the persisted RTM graph at the moment of sealing. Advisory, never verdict: it rides the response *after* the seal commits, degrades to absence on any failure, and every emission lands in an observation ledger so its false-positive rate is **measured before** anyone proposes a hard gate. The graph 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). *(0.17.0 hardening)*: the advisory/impact graph is **approved-only** (a draft needs no approval to exist, so it can no longer reach these agent-visible channels), summary prose can't forge graph rows (structural characters fold at both the extraction and storage boundaries), and annotations are capped with explicit omission counts (a hub-grade response shrank 104.7KB → 18.7KB, −82%). Sealing also gains an **anchor-density advisory** (observation-only): an A-SPEC whose Files-to-Touch contains an anchor-dense file (live anchors ≥ max(8, p90)) is annotated with `anchorDensity: [{path, anchors, p90}]` and ledgered — grounded in the measured precision tax of anchor accumulation; a count *gate* was considered and refused.
+- 🗣️ **The graph speaks intent** *(new in 0.16.0)*: every SPEC node stores a one-sentence intent summary (`"<title> — <first sentence of its intent section>"`, schema `rtm-graph/3`, old stores rebuild automatically) — extracted deterministically, **never generated** (same store, byte-identical graph; measured cost +6.4% build time / +4.2% file size). Advisory anchors arrive as `{id, summary}` and `rtm_impact` adds `impactedSummaries`, so the reader sees *which intent* is at risk without a spec-store round trip. Information only: value tests pin that no verdict, ranking or gate reads the prose.
+- 📇 **Session-context observability** *(new in 0.16.0)*: the ledger records which agent/model drove a session and what the governance overhead cost, per replica (`session-context.<replica>.jsonl`), grounding field reports in machine attribution instead of guesswork.
 
 - 📋 **Requirements & Specification Governance**: Strict **"No Spec, No Code"** enforcement with 4-tier spec chain traceability (`REQ ➔ H-SPEC ➔ A-SPEC ➔ T-SPEC`) and `// @implements A-SPEC-XXX` code anchors (comma-lists and every anchor in a file participate in the gate).
 - 🔴 **Inbuilt TDD — RED-first, enforced not asked** *(new in 0.9.0)*: the test-first discipline is a holmes-installed `holmes-tdd-slice` skill **and** a new constitution article **ART-8**. A changed A-SPEC must show a recorded `red-assertion → green` sequence in the ledger; a `red-error` (a test that could not run) is not a valid RED, so "the covering test failed *correctly*" is judged mechanically, not on trust. `test_run` classifies each covered file (`red-assertion`/`red-error`/`green`) and records per-A-SPEC outcomes the Stop hook reads. Ships at `redFirstEvidence: track` (observe-first, non-blocking; `strict`/`off` per repo), evidence-gated and jest-only for now. A T-SPEC may also declare `kills:` mutations and `test_run --mutate` reports which SURVIVED (a coverage gap). Where superpowers *asks* for RED-first and discriminating power, holmes-kit *proves* them.

package/dist/.build-id

@@ -1 +1 @@
-2a7fb45-mtps37rf
+20f5f64-mtrggtxw

package/dist/holmes/cli/doctor.js

@@ -897,7 +897,21 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 }
                 else {
                     const pin = (0, mcp_version_1.mcpLaunchVersion)({ command: entry.command, args: entry.args });
-                    add('codex wiring', pin !== null ? 'PASS' : 'FAIL', pin !== null ? `resolves via the npx pin ${pin}` : `cannot read a launch version from the wiring: ${entry.command} ${entry.args.join(' ')}`, pin !== null ? undefined : 'Rewire with holmes-kit init --target <dir> --agent codex.');
+                    // @implements A-SPEC-569.4 — parity with the .mcp.json drift check (A-SPEC-251.2): a pin
+                    // that RESOLVES is not enough, because a stale pin quietly keeps launching yesterday's
+                    // gate. Same verdict function (non-semver pins like @latest judge 'unknown' → PASS, not
+                    // an inverted "stale" WARN), same fix shape; an unreadable pin stays FAIL as before.
+                    const cliVer = (0, mcp_launcher_1.readPackageVersion)(packageRoot); // same accessor as the .mcp.json check — one source of truth
+                    const drift = cliVer ? (0, mcp_version_1.versionDriftVerdict)(pin, cliVer) : 'unknown';
+                    if (pin === null) {
+                        add('codex wiring', 'FAIL', `cannot read a launch version from the wiring: ${entry.command} ${entry.args.join(' ')}`, 'Rewire with holmes-kit init --target <dir> --agent codex.');
+                    }
+                    else if (drift === 'drift') {
+                        add('codex wiring', 'WARN', `resolves via the npx pin ${pin}, but this install is ${cliVer} — a stale pin keeps launching the old server`, 'Rewire with holmes-kit init --target <dir> --agent codex --force to refresh the pin.');
+                    }
+                    else {
+                        add('codex wiring', 'PASS', `resolves via the npx pin ${pin}`);
+                    }
                 }
                 // @implements A-SPEC-442 (was A-SPEC-423)
                 // Codex CAN hard-enforce, but only from an INSTALLED plugin: it loads plugins from

package/dist/holmes/cli/mcp-version.d.ts

@@ -19,5 +19,8 @@ export interface McpEntryShape {
  */
 export declare function mcpLaunchVersion(entry: McpEntryShape, readVersion?: (packageDir: string) => string | undefined): string | null;
 export type DriftVerdict = 'match' | 'drift' | 'unknown';
-/** launch 를 못 뽑았으면 unknown(거짓 drift 를 만들지 않는다). 같으면 match, 다르면 drift. */
+/** launch 를 못 뽑았으면 unknown(거짓 drift 를 만들지 않는다). 같으면 match, 다르면 drift.
+ * @implements A-SPEC-569.4 — 비-semver 런치 문자열(`latest`·`next`·`^0.16.0`)도 unknown:
+ * `@latest` 핀은 최신을 띄우는데 "구 서버를 계속 띄운다"는 drift 경고는 역진단이었다(고강도
+ * 리뷰 F5). 정확 semver 만 오프라인에서 비교 가능하다 — 판정 불능은 결함으로 둔갑시키지 않는다. */
 export declare function versionDriftVerdict(launchVersion: string | null, cliVersion: string): DriftVerdict;

package/dist/holmes/cli/mcp-version.js

@@ -74,9 +74,12 @@ function mcpLaunchVersion(entry, readVersion) {
     }
     return null;
 }
-/** launch 를 못 뽑았으면 unknown(거짓 drift 를 만들지 않는다). 같으면 match, 다르면 drift. */
+/** launch 를 못 뽑았으면 unknown(거짓 drift 를 만들지 않는다). 같으면 match, 다르면 drift.
+ * @implements A-SPEC-569.4 — 비-semver 런치 문자열(`latest`·`next`·`^0.16.0`)도 unknown:
+ * `@latest` 핀은 최신을 띄우는데 "구 서버를 계속 띄운다"는 drift 경고는 역진단이었다(고강도
+ * 리뷰 F5). 정확 semver 만 오프라인에서 비교 가능하다 — 판정 불능은 결함으로 둔갑시키지 않는다. */
 function versionDriftVerdict(launchVersion, cliVersion) {
-    if (launchVersion === null)
+    if (launchVersion === null || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(launchVersion))
         return 'unknown';
     return launchVersion === cliVersion ? 'match' : 'drift';
 }

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/autonomy.js

@@ -80,7 +80,22 @@ const TAINT_MARKERS = ['taint', 'dataflow-taint', 'flow-sensitive'];
 // purpose, because a glob spanning the gate surface must never self-approve.
 const GLOB_RISK_ROOTS = [...HIGH_RISK_PREFIXES, 'src/holmes/rtm/'];
 function isHighRiskPath(p) {
-    const raw = p.replace(/^\.\//, '').replace(/^["'`]|["'`]$/g, '');
+    // @implements A-SPEC-569.4 — '.' segments fold BEFORE the verdict: `src/holmes/./governance/x`
+    // dodged every prefix check while naming the gate surface exactly (REQ-556's remaining edge).
+    // Deliberately NOT `..`: folding that would impersonate path resolution this grader cannot do
+    // (shape is not location) — over-inclusion is allowed here, invented precision is not. The
+    // enforcer (matchesFtt) stays byte-literal, so a /./-token still admits nothing: only the
+    // grader's sight widened, never the gate's admission.
+    const unquoted = p.replace(/^["'`]|["'`]$/g, '');
+    // @implements A-SPEC-569.4 (revision, high-effort review F3) — a `..` segment is NOT folded
+    // (folding would impersonate path resolution this grader cannot do) but it IS flagged: the hook
+    // does not canonicalize relative paths, so `src/app/../holmes/governance/x.ts` stays admissible
+    // at the byte-literal enforcer under its own spelling while a fold-blind grader called it
+    // benign. An ascent token is ambiguous about where it lands, and ambiguity over the gate
+    // surface grades high-risk — over-inclusive on purpose, the rule this module already owns.
+    if (/(^|\/)\.\.(\/|$)/.test(unquoted))
+        return true;
+    const raw = unquoted.replace(/\/\.(?=\/|$)/g, '').replace(/^(\.\/)+/, '');
     const s = raw.toLowerCase();
     if (HIGH_RISK_PREFIXES.some((pre) => s.startsWith(pre)))
         return true;

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;