@holmes-lab/holmes-kit 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,136 @@ 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.18.0] - 2026-09-08
+
+Decisions become governed. A consuming project's operational decisions had been leaking into agent
+memory outside the gate — because Holmes-Kit accepted functional contracts (REQ→H→A→T) but had no
+slot for a **decision**. Now it does, and it reuses machinery already present rather than inventing
+a channel.
+
+### Added
+- **ADR as a first-class governed spec type (REQ-571)** — `spec_create(type: "ADR")` (refused as
+  "unknown spec type" through 0.17.0) now scaffolds a root decision document under `06_adr`
+  (sections Context / Decision / Consequences / Alternatives; fields `decided` / `decider`) and
+  inherits the store's full authoring governance: validate → `spec_approve` seal
+  (`approved_digest` + ledger) → post-seal tamper-block. Three deliberate boundaries: an ADR
+  carries **no** T-SPEC / `@implements` / Files-to-Touch duty (a decision is not a functional
+  contract — a separate axis from No-Spec-No-Code); it lives in its **own number space** (a
+  consuming project's existing `ADR-0001` neither blocks nor is blocked by the functional chain's
+  max); and its seal is **hitl-only** (autonomy never self-approves a decision, like an upstream
+  REQ/H-SPEC/C-SPEC).
+- **Store ADRs join the existing decision surface with zero new edge kinds (REQ-571)** — a store
+  ADR merges into the `collectDecisions` population (store wins on id collision with a legacy
+  `.ax/decisions/` entry, which coexists for back-compat), so `ADR-XXXX` citations in specs and
+  source become `constrained_by` edges, `supersedes` chains link, and the DECISION node appears —
+  all through machinery that already shipped. The graph's `SPEC:ADR` node carries the Decision
+  line as its intent summary (intent-layer parity), and the citation system recognizes `ADR-\d+`
+  (recognition only — the lexical match-scoring population stays A-SPEC-limited, so an ADR never
+  admits or reorders a file). A migration guide for consuming projects ships at
+  `docs/adr-migration.md`.
+
+- **The graph advisory now arrives at DESIGN time (REQ-572)** — measured on our own work: the
+  sealing advisory for a slice named `validator.ts` / `legacy-format.ts` / `rtm-check.ts` /
+  `constitution.ts`, three regressions landed in exactly that cluster, and the agent read none of
+  it until the suite went red. The calculation was never the gap; the **delivery time** was. So the
+  read-only `approval_status` — already the "what is blocking this right now" tool — also answers
+  `graphPreview`: `impact` (files calling INTO your declared Files-to-Touch from outside, each
+  anchor carrying its spec's intent sentence) and `density` (anchor-dense files inside the scope),
+  computed by the **same functions `spec_approve` calls**, so a preview can never disagree with the
+  seal. Read-only stays read-only: no scan, no build, and **no ledger append** (a query must not
+  pollute the observation denominator); every failure degrades to an absent field. Both authoring
+  playbooks now carry the step — read the impact before freezing Files-to-Touch, then either widen
+  the declaration, narrow the design, or leave it knowingly — pinned by test so the instruction
+  cannot evaporate. It stays a **discipline, not a gate** (hard-gate promotion waits on the
+  observation ledger's false-positive rate).
+- **Root-cause analysis carries the decision context (REQ-572)** — `maintenance_analyze` candidates
+  now ride with `decisionContext`: the ADRs constraining that file (directly, or through the specs
+  it anchors) and each decision's own sentence. That is the order a person diagnoses in — what
+  broke, then why it was left this way — and it needs no new mechanism: ADRs entered the graph with
+  REQ-571 and `constrained_by` has been built from citations since A-SPEC-293. Information only,
+  capped, never an input to the ranking.
+
+### Notes
+- Version bump is **minor** carrying one `gate-behavior` change (the new ADR type is accepted where
+  it was refused); the release classifier routes this to HITL by design. The four existing spec
+  types are unchanged — verdicts pinned across the suite.
+- REQ-572's own last slice was authored **through** the new design-time read: the preview reported
+  `maintenance-analyze.ts` at 35 anchors and `handlers.ts` at 83 (p90 = 7), so the decision-context
+  logic went into a new pure module instead of thickening either file. First recorded case of the
+  advisory changing a design before the code was written.
+
+## [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

package/README.md

@@ -14,7 +14,14 @@
 
 ---
 
-### 🛡️ Currently Supported Features (v0.14.x Production Features)
+### 🛡️ Currently Supported Features (Production Features)
+
+- 🧭 **The graph speaks BEFORE you commit to a scope** *(new in 0.18.0)*: the read-only `approval_status` now also answers `graphPreview` — `impact` (files that call INTO your declared Files-to-Touch from outside it, each anchor carrying its spec's intent sentence) and `density` (anchor-dense files inside the scope) — computed by the **same functions the sealing advisory uses**, so the preview can never disagree with the seal. Read the impact, then widen the declaration, narrow the design, or leave it knowingly; the authoring playbooks carry the step (pinned by test) and it stays a discipline, not a gate. Root-cause work gets the other half: `maintenance_analyze` candidates ride with `decisionContext` — the ADRs constraining that file and each decision's own sentence — which is the order a person diagnoses in (what broke, then why it was left this way). Both are information only: value tests pin that no ranking, score or gate reads them.
+- 📜 **ADR as a first-class governed document** *(new in 0.18.0)*: decisions stop leaking into agent memory outside the gate (a measured incident on a consuming project drove this). `spec_create(type: "ADR")` scaffolds a root decision document (Context / Decision / Consequences / Alternatives, `decided`/`decider`) under the store's full authoring governance — validate, `spec_approve` seal, ledger, tamper-block — with its **own number space** (your existing `ADR-0001` just works) and a **hitl-only seal** (autonomy never self-approves a decision). Store ADRs join the existing decision surface with zero new edge kinds: `ADR-XXXX` citations in specs/code become `constrained_by` edges, `supersedes` chains link, the graph's SPEC:ADR node carries the Decision line as its intent summary, and legacy `.ax/decisions/` entries coexist (store wins on id collision). A migration guide ships at `docs/adr-migration.md`.
+
+- 📣 **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 @@
-b540876-mtqeiitb
+cc24589-mtrjegw0

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/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;
@@ -118,6 +133,7 @@ function specApprovalAutonomy(spec, _resolveParent) {
         case 'REQ':
         case 'H-SPEC':
         case 'C-SPEC':
+        case 'ADR': // @implements A-SPEC-571.1 — a decision is the human's to seal
             return 'hitl'; // wide blast radius / structural constraint
         case 'A-SPEC': {
             const grade = breakingGrade(spec);

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

@@ -1,6 +1,9 @@
 import { SpecStore } from '../spec/spec-store';
+import { Spec } from '../spec/spec-parser';
 import { MaintenanceGroundTruth, MaintenanceAnalysis } from './maintenance-analyze';
 import { Action } from '../guardrail/phase';
+import { ScannedFile } from '../cpg/cpg-scanner';
+import { type DecisionRecord, type DecisionCitation } from '../rtm/rtm-builder';
 import { Basis } from './basis';
 import { Finding } from '../review/findings';
 import { Approval, Enforcement } from '../guardrail/risk-gate';
@@ -53,6 +56,16 @@ export declare function makeHandlers(store: SpecStore, opts?: ElicitOpts): RawHa
     }>;
 };
 type RawHandlers = ReturnType<typeof makeRawHandlers>;
+/**
+ * @implements A-SPEC-293
+ * Read `.ax/decisions/*.md` and find who cites them. Citation is the link, chosen by measurement:
+ * `governs` resolves 9 of 65 names to symbols while 37 source files and 71 spec files cite an ADR.
+ * Failure here is never fatal — a project with no decisions directory simply has no decisions.
+ */
+export declare function collectDecisions(root: string, scanned: readonly ScannedFile[], specs: readonly Spec[]): {
+    decisions: DecisionRecord[];
+    citations: DecisionCitation[];
+};
 declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     spec_create(a: any): Promise<{
         ok: boolean;
@@ -207,6 +220,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok: boolean;
         reason: string;
     } | {
+        graphPreview?: {
+            impact?: import("../rtm/impact-advisory").ImpactAdvisory;
+            density?: import("../rtm/anchor-density").AnchorDensityFinding[];
+            graphAsOf?: string;
+        } | undefined;
         id: string;
         type?: string;
         status: string;
@@ -272,6 +290,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         conflict: import("../spec/version-conflict").ConflictDetail;
         findings?: undefined;
     } | {
+        anchorDensity?: import("../rtm/anchor-density").AnchorDensityFinding[] | undefined;
         impactAdvisory?: import("../rtm/impact-advisory").ImpactAdvisory | undefined;
         approved: string;
         digest: string;
@@ -530,11 +549,6 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         changed: string[];
     }): Promise<{
         breadthWarning?: string | undefined;
-        impacted: string[];
-        impactedSummaries: {
-            id: string;
-            summary: string | null;
-        }[];
         rankedImpact: {
             file: string;
             score: number;
@@ -545,6 +559,12 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             reason: "hub" | "depth";
             inDegree?: number;
         }[] | undefined;
+        summariesOmitted?: number | undefined;
+        impacted: string[];
+        impactedSummaries: {
+            id: string;
+            summary: string | null;
+        }[];
     }>;
     rtm_reindex(a: {
         root: string;

package/dist/holmes/mcp/handlers.js

@@ -37,6 +37,7 @@ exports.HandlerRefusal = void 0;
 exports.isHandlerRefusal = isHandlerRefusal;
 exports.unreadableAmong = unreadableAmong;
 exports.makeHandlers = makeHandlers;
+exports.collectDecisions = collectDecisions;
 // @implements A-SPEC-293
 // @implements A-SPEC-292
 // @implements A-SPEC-290
@@ -153,7 +154,14 @@ const cacheDirFor = (root) => {
 // by an older build is rebuilt rather than read with new assumptions.
 // @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';
+// @implements A-SPEC-569.3 — how many impacted specs get their intent sentence attached. A prose
+// constant, never a verdict input: the impacted list itself is never truncated.
+const SUMMARY_CAP = 40;
+// @implements A-SPEC-569.1 (revision) — /2: pre-fix 0.16.0 builds could persist forged structural
+// characters in the summary column, and every other basis field would still match after upgrading.
+// A-SPEC-283's own rule applies to us too: an older build's artifact is rebuilt, never read with
+// new assumptions.
+const RTM_EXTRACTOR_VERSION = 'holmes-rtm/2';
 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
 // Same scan, with the skip report kept: the callers that make honesty claims (cpg_scan's surface,
@@ -692,8 +700,24 @@ function collectDecisions(root, scanned, specs) {
             });
         }
     }
-    catch {
-        return { decisions: [], citations: [] };
+    catch { /* @implements A-SPEC-571.2 — no legacy .ax/decisions dir is not "no decisions": store
+      ADRs below are still a source. An unreadable dir degrades to the empty legacy set, not an early
+      return that would skip the store population. */
+    }
+    // @implements A-SPEC-571.2 — store ADRs JOIN the decisions population, so the existing consumers
+    // (DECISION nodes, constrained_by citations, supersedes) light up with no new edge kind. A store
+    // ADR is the canon: same id in legacy .ax/decisions is replaced (store wins).
+    for (const spec of specs) {
+        if (spec.type !== 'ADR')
+            continue;
+        const sup = spec.frontmatter?.supersedes;
+        const supersedes = typeof sup === 'string' && sup.trim() && sup.trim() !== 'null' ? sup.trim() : null;
+        const idx = decisions.findIndex((d) => d.id === spec.id);
+        const rec = { id: spec.id, title: spec.title, status: spec.status, supersedes };
+        if (idx >= 0)
+            decisions[idx] = rec;
+        else
+            decisions.push(rec);
     }
     const ids = new Set(decisions.map((d) => d.id));
     // @implements A-SPEC-546.1 — recognise ADR-\d{3,} (4-digit ADRs no longer invisible), via a pure fn.
@@ -1323,7 +1347,58 @@ function makeRawHandlers(store, opts) {
                 const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
                 return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
             }
-            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)) };
+            // @implements A-SPEC-572.1
+            // The graph advisory, delivered at DESIGN time. Measured on our own work: A-SPEC-571.1's
+            // sealing advisory named the exact cluster three regressions then landed in — and by then
+            // the design was done. The calculation was never the gap; the delivery time was. So the
+            // read-only "what is blocking this right now" tool also answers "what will this scope leak,
+            // and where is it dense" — using the SAME functions spec_approve calls, so the preview can
+            // never disagree with the seal. Read-only stays read-only: no scan, no build, no ledger
+            // append (a query must not pollute the observation denominator), and every failure degrades
+            // to an absent field on an otherwise identical response.
+            let graphPreview;
+            try {
+                if (cur.spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    if (fs.existsSync(dbPath)) {
+                        const { declaredImpactGap } = require('../rtm/impact-advisory');
+                        const { anchorDensityFindings } = require('../rtm/anchor-density');
+                        const { filesToTouch } = require('../spec/compat-impact');
+                        const { RtmGraph } = require('../rtm/rtm-graph');
+                        const graph = new RtmGraph(dbPath);
+                        try {
+                            const ftt = filesToTouch(cur.spec);
+                            const impact = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                            }
+                            catch {
+                                return null;
+                            } });
+                            const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                            if (impact || density.length > 0) {
+                                const graphAsOf = (() => { try {
+                                    return fs.statSync(dbPath).mtime.toISOString();
+                                }
+                                catch {
+                                    return undefined;
+                                } })();
+                                graphPreview = {
+                                    ...(impact ? { impact } : {}),
+                                    ...(density.length > 0 ? { density } : {}),
+                                    ...(graphAsOf ? { graphAsOf } : {}),
+                                };
+                            }
+                        }
+                        finally {
+                            graph.close();
+                        }
+                    }
+                }
+            }
+            catch {
+                graphPreview = undefined;
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)), ...(graphPreview ? { graphPreview } : {}) };
         },
         /**
          * @implements A-SPEC-538.3
@@ -1691,6 +1766,7 @@ function makeRawHandlers(store, opts) {
             // 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;
+            let anchorDensity;
             try {
                 if (spec.type === 'A-SPEC' && a.root) {
                     const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
@@ -1698,33 +1774,61 @@ function makeRawHandlers(store, opts) {
                         const { declaredImpactGap, appendImpactAdvisory } = require('../rtm/impact-advisory');
                         const { filesToTouch } = require('../spec/compat-impact');
                         const { RtmGraph } = require('../rtm/rtm-graph');
+                        // Closed in finally (high-effort review F4): this handler lives in a long-running MCP
+                        // server, and an unclosed native handle per approval accumulates for the process
+                        // lifetime — and on Windows can hold rtm.sqlite locked against the next rebuild.
                         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();
+                        try {
+                            const ftt = filesToTouch(candidate);
+                            const gap = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
                             }
                             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(),
-                            });
+                                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(),
+                                });
+                            }
+                            // @implements A-SPEC-569.5 — anchor-density OBSERVATION, same reopened graph, same
+                            // no-scan contract, same lifecycle as the advisory above (observe → ledger → measure
+                            // before anyone proposes promotion). Never a verdict input: the seal is already done,
+                            // and its own failure degrades to "no field" on an otherwise identical response.
+                            try {
+                                const { anchorDensityFindings, appendAnchorDensity } = require('../rtm/anchor-density');
+                                const findings = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                                if (findings.length > 0) {
+                                    anchorDensity = findings;
+                                    appendAnchorDensity(a.root, {
+                                        aspec: a.id, files: findings.map((f) => ({ path: f.path, anchors: f.anchors })),
+                                        p90: findings[0].p90, ts: new Date().toISOString(),
+                                    });
+                                }
+                            }
+                            catch {
+                                anchorDensity = undefined;
+                            }
+                        }
+                        finally {
+                            graph.close();
                         }
                     }
                 }
             }
             catch {
                 impactAdvisory = undefined;
+                anchorDensity = undefined;
             }
-            return { approved: a.id, digest, ...(impactAdvisory ? { impactAdvisory } : {}) };
+            return { approved: a.id, digest, ...(impactAdvisory ? { impactAdvisory } : {}), ...(anchorDensity ? { anchorDensity } : {}) };
         },
         async spec_list(a) {
             assertSpecStoreReachable('spec_list', store, a.root); // @implements A-SPEC-419
@@ -2513,7 +2617,14 @@ function makeRawHandlers(store, opts) {
             // was asked. Bind the derivation and use it.
             const root = projectRootOf(a.root);
             const scanned = cachedScan(root);
-            const specs = await store.list();
+            // @implements A-SPEC-569.2 — the impact/advisory graph is APPROVED-ONLY. A draft needs no
+            // approval to exist, and the 0.16.0 adversarial round showed one reaching the agent-visible
+            // channels (impacted closure, advisory anchor summaries) — the trust boundary for those
+            // channels is the act of approval. NOT filterGoverned: that predicate passes drafts (it only
+            // drops outdated/legacy), which is exactly what let this in. Diagnosis (rtm_check) and
+            // matching (issue_localize / maintenance_analyze) keep their own populations — the replay
+            // pins were measured on them.
+            const specs = (await store.list()).filter((s) => s.status === 'approved');
             // @implements A-SPEC-283
             // Reuse the persisted graph when its basis still holds. Measured: on the warm path the graph
             // build is ~81% of the cost and reopening is ~0ms. `scanDigest` is the field that makes this
@@ -2540,7 +2651,12 @@ function makeRawHandlers(store, opts) {
                 // explainImpact, not impactedBy: the bounds and the breadth signal must reach the caller.
                 // An impact set is not just a list — a broad one means "review the contract", and a consumer
                 // that cannot tell the difference will try to bundle two hundred call sites.
-                const { specs: impacted, reachedByDepth, stoppedAt, seedIsHub } = (0, rtm_builder_1.explainImpact)(g, a.changed);
+                const { specs: impactedRaw, reachedByDepth, stoppedAt, seedIsHub } = (0, rtm_builder_1.explainImpact)(g, a.changed);
+                // @implements A-SPEC-569.2 — the closure walks EDGES, and an implements edge is owned by
+                // the code file, so an anchor naming a draft (or a spec nobody wrote) still emits one —
+                // deliberately, for rtm_check's dangling diagnosis. The CHANNEL filter is node existence:
+                // approved-only specs were given nodes above, so only sealed intent reaches the caller.
+                const impacted = impactedRaw.filter((id) => g.hasNode(id));
                 // @implements A-SPEC-469 — the graded FILE surface beside the spec closure, same code path
                 // as the S-484 measurement (identity, not reimplementation). Seeds are the changed symbols'
                 // nodes; the files that own them are excluded — a prediction naming the change itself is
@@ -2554,7 +2670,11 @@ function makeRawHandlers(store, opts) {
                 // @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) => {
+                // @implements A-SPEC-569.3 — capped: measured on this repository, uncapped summaries were
+                // 94% of a 104,706-byte response (a hub-grade impact of 339 specs). The omission is COUNTED,
+                // never silent, and `impacted` itself stays complete — only the annotation is bounded.
+                const shownSummaries = impacted.slice(0, SUMMARY_CAP);
+                const impactedSummaries = shownSummaries.map((id) => {
                     let summary = null;
                     try {
                         summary = g.summaryOf(id);
@@ -2562,9 +2682,11 @@ function makeRawHandlers(store, opts) {
                     catch { /* summary stays null */ }
                     return { id, summary };
                 });
+                const summariesOmitted = impacted.length - shownSummaries.length;
                 return {
                     impacted,
                     impactedSummaries,
+                    ...(summariesOmitted > 0 ? { summariesOmitted } : {}),
                     rankedImpact,
                     reachedByDepth,
                     bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,

package/dist/holmes/mcp/maintenance-analyze.d.ts

@@ -3,6 +3,7 @@ import type { Spec } from '../spec/spec-parser';
 import type { RtmGraph } from '../rtm/rtm-graph';
 import type { ContextBundle } from '../context/bundler';
 import { type TestScope } from '../rtm/test-scope';
+import { type DecisionContextEntry } from '../rtm/decision-context';
 import type { ResolutionReport } from '../rtm/rtm-builder';
 import { type TestEvidence } from '../review/test-evidence';
 import { type LanguageGap } from '../cpg/language-capability';
@@ -212,6 +213,8 @@ export interface MaintenanceAnalysis {
         score: number;
         symbols: string[];
         evidence: string[];
+        /** @implements A-SPEC-572.3 — decisions constraining this candidate; information only. */
+        decisionContext?: DecisionContextEntry[];
     }>;
     /**
      * @implements A-SPEC-494 — the semantic ALTERNATES: top-3 cached-vector cosines among files

package/dist/holmes/mcp/maintenance-analyze.js

@@ -26,6 +26,11 @@ const scope_1 = require("../review/scope");
 // the measured numbers transfer to the shipped surface.
 const assoc_arm_1 = require("../assoc/assoc-arm");
 const acceptance_quality_1 = require("../spec/acceptance-quality");
+// @implements A-SPEC-572.3 — the decision lookup lives in its own pure module: this file
+// already carries 35 anchors (p90 is 7), and the design-time density advisory said so BEFORE
+// this slice fixed its Files-to-Touch. Adding logic here would have made the file denser; the
+// call site is one line, the logic is next door.
+const decision_context_1 = require("../rtm/decision-context");
 const taint_1 = require("../rtm/taint");
 const test_evidence_1 = require("../review/test-evidence");
 const language_capability_1 = require("../cpg/language-capability");
@@ -377,6 +382,21 @@ function analyzeMaintenance(input) {
         symbols: sortedUnique(hit.matchedSymbols),
         evidence: [...hit.why],
     }));
+    // @implements A-SPEC-572.3
+    // "What broke" then "why is it this way" — the order a person diagnoses in. The decisions are
+    // already in the graph (REQ-571 put store ADRs there; A-SPEC-293 builds `constrained_by` from
+    // citations), so this is a lookup, not a new mechanism. Information only: it rides beside a
+    // candidate and never enters the score or the ordering above.
+    {
+        const anchorsOf = new Map(scanned.map((f) => [f.sourcePath, f.implementsSpecs ?? []]));
+        const ctx = (0, decision_context_1.decisionContextFor)(candidates.map((c) => c.file), (file) => anchorsOf.get(file) ?? [], input.graph);
+        for (const candidate of candidates) {
+            const entries = ctx.get(candidate.file);
+            if (entries && entries.length > 0) {
+                candidate.decisionContext = entries;
+            }
+        }
+    }
     // @implements A-SPEC-478 — the uncited semantic head rerank, exactly the arm S-495 measured:
     // same math (cosine over cached doc vectors, pool FIXED), same gate (the request cited no
     // spec). The gate is load-bearing both ways — uncited corpora gained +26%/+93% at the head,