@holmes-lab/holmes-kit 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ 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

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 @@
-b540876-mtqeiitb
+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/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/mcp/handlers.d.ts

@@ -272,6 +272,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 +531,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 +541,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

@@ -153,7 +153,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,
@@ -1691,6 +1698,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 +1706,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 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 {
-                                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(),
-                            });
+                                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 +2549,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 +2583,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 +2602,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 +2614,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/rtm/anchor-density.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Anchor-density advisory — OBSERVATION ONLY, never a gate.
+ *
+ * The measured ground: anchor density taxes localization precision (authoring ONE spec moved
+ * replay recall 0.5476→0.5060; A-SPEC-270's √-dilution exists because a 113-anchor file brushes
+ * some spec for almost any request). A count GATE was considered and REFUSED (position-dependent
+ * refusals, an incentive to stop anchoring, mechanical file splits) — so this surfaces the fact at
+ * sealing time and records it, and the observation ledger decides any future promotion, exactly
+ * the impactAdvisory lifecycle. The thresholds below are prose constants: nothing reads them into
+ * a verdict (judgments must not be budgeted).
+ */
+export interface AnchorDensityFinding {
+    path: string;
+    anchors: number;
+    p90: number;
+}
+/** Files below this live-anchor count are never flagged, whatever the distribution — a floor. */
+export declare const MIN_ANCHORS = 8;
+/**
+ * FtT files whose live anchor count sits at or above max(MIN_ANCHORS, p90 of the distribution).
+ * p90 is the value at index ceil(0.9·n)-1 of the ascending counts — deterministic, no interpolation.
+ * Pure: same inputs, same findings, in sorted path order.
+ */
+export declare function anchorDensityFindings(fttFiles: string[], counts: Array<{
+    sourcePath: string;
+    anchors: number;
+}>): AnchorDensityFinding[];
+/**
+ * The observation ledger — paths and integers only, no prose, no secrets: what a future
+ * promotion/rejection judgment will be measured on.
+ */
+export interface AnchorDensityRecord {
+    aspec: string;
+    files: Array<{
+        path: string;
+        anchors: number;
+    }>;
+    p90: number;
+    ts: string;
+    replica?: string;
+}
+export declare function appendAnchorDensity(root: string, rec: AnchorDensityRecord): boolean;
+export declare function readAnchorDensity(root: string): AnchorDensityRecord[];

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

@@ -0,0 +1,117 @@
+"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.MIN_ANCHORS = void 0;
+exports.anchorDensityFindings = anchorDensityFindings;
+exports.appendAnchorDensity = appendAnchorDensity;
+exports.readAnchorDensity = readAnchorDensity;
+// @implements A-SPEC-569.5
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
+/** Files below this live-anchor count are never flagged, whatever the distribution — a floor. */
+exports.MIN_ANCHORS = 8;
+/**
+ * FtT files whose live anchor count sits at or above max(MIN_ANCHORS, p90 of the distribution).
+ * p90 is the value at index ceil(0.9·n)-1 of the ascending counts — deterministic, no interpolation.
+ * Pure: same inputs, same findings, in sorted path order.
+ */
+function anchorDensityFindings(fttFiles, counts) {
+    if (counts.length === 0 || fttFiles.length === 0)
+        return [];
+    const sorted = counts.map((c) => c.anchors).sort((a, b) => a - b);
+    const p90 = sorted[Math.ceil(0.9 * sorted.length) - 1];
+    const threshold = Math.max(exports.MIN_ANCHORS, p90);
+    const byPath = new Map(counts.map((c) => [c.sourcePath, c.anchors]));
+    const out = [];
+    for (const f of [...new Set(fttFiles.map((p) => p.replace(/\\/g, '/')))].sort()) {
+        const anchors = byPath.get(f);
+        if (anchors !== undefined && anchors >= threshold)
+            out.push({ path: f, anchors, p90 });
+    }
+    return out;
+}
+const DENSITY_FILE_RE = /^anchor-density\.([^.]+)\.jsonl$/;
+function appendAnchorDensity(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', `anchor-density.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ ...rec, replica })}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readAnchorDensity(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => DENSITY_FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && typeof r.aspec === 'string' && Array.isArray(r.files) && typeof r.ts === 'string') {
+                    out.push(r);
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/impact-advisory.d.ts

@@ -22,11 +22,15 @@ export interface ImpactAdvisory {
             id: string;
             summary: string | null;
         }>;
+        /** @implements A-SPEC-569.3 — anchors beyond ANCHOR_CAP, counted rather than silently dropped. */
+        anchorsOmitted?: number;
     }>;
     more: number;
     graphAsOf?: string;
 }
 export declare const ADVISORY_CAP = 10;
+/** @implements A-SPEC-569.3 — anchors annotated per advisory file; a prose constant, never a verdict input. */
+export declare const ANCHOR_CAP = 10;
 export declare function declaredImpactGap(fttFiles: string[], graph: GraphLike, readFile: (rel: string) => string | null, opts?: {
     cap?: number;
 }): ImpactAdvisory | null;

package/dist/holmes/rtm/impact-advisory.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADVISORY_CAP = void 0;
+exports.ANCHOR_CAP = exports.ADVISORY_CAP = void 0;
 exports.declaredImpactGap = declaredImpactGap;
 exports.appendImpactAdvisory = appendImpactAdvisory;
 exports.readImpactAdvisories = readImpactAdvisories;
@@ -43,6 +43,8 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const replica_id_1 = require("../governance/replica-id");
 exports.ADVISORY_CAP = 10;
+/** @implements A-SPEC-569.3 — anchors annotated per advisory file; a prose constant, never a verdict input. */
+exports.ANCHOR_CAP = 10;
 /** The ONLY shape allowed into the ledger: `seg/seg/…` of word characters, dots and dashes —
  * no leading slash, no drive letter, no backslash, no empty or `..` segment. */
 function isRepoRelative(p) {
@@ -99,12 +101,16 @@ function declaredImpactGap(fttFiles, graph, readFile, opts) {
                         ids = anchorsIn(text);
                 }
                 catch { /* anchors stay [] */ }
+                // @implements A-SPEC-569.3 — capped BEFORE the summary lookups, so the omitted tail costs
+                // no SELECTs either; the omission is counted, never silent.
+                const shownIds = ids.slice(0, exports.ANCHOR_CAP);
+                const anchorsOmitted = ids.length - shownIds.length;
                 // @implements A-SPEC-568.2 — the anchor's intent sentence rides BESIDE the id, read from the
                 // graph S1 built. Information only: nothing below this line feeds files/more/ordering, and a
                 // failing lookup downgrades to null rather than killing the finding (an advisory never guesses).
                 return {
                     path,
-                    anchors: ids.map((id) => {
+                    anchors: shownIds.map((id) => {
                         let summary = null;
                         try {
                             summary = graph.summaryOf(`SPEC:${id}`);
@@ -112,6 +118,7 @@ function declaredImpactGap(fttFiles, graph, readFile, opts) {
                         catch { /* summary stays null */ }
                         return { id, summary };
                     }),
+                    ...(anchorsOmitted > 0 ? { anchorsOmitted } : {}),
                 };
             }),
             more: sorted.length - shown.length,

package/dist/holmes/rtm/rtm-builder.js

@@ -91,15 +91,23 @@ function specSummary(s) {
     const text = (section ? (s.sections?.[section] ?? '') : '').replace(/\s+/g, ' ').trim();
     // Measured 2026-09-07 on this store: 20 legacy specs carry title '' — the summary falls back to
     // the sentence alone, then to the id, because SC1 admits no empty summary on any path.
+    let result;
     if (text === '' || text === 'TODO')
-        return title !== '' ? title : s.id;
-    // First sentence: up to the first . ! or ? that ends a word — the lookahead keeps `A-SPEC-129.2`
-    // whole, because its dot is followed by a digit, not by whitespace or the end.
-    const m = /^(.*?[.!?])(?=\s|$)/.exec(text);
-    let sentence = m ? m[1] : text;
-    if (sentence.length > SUMMARY_SENTENCE_CAP)
-        sentence = `${sentence.slice(0, SUMMARY_SENTENCE_CAP)}…`;
-    return title !== '' ? `${title} — ${sentence}` : sentence;
+        result = title !== '' ? title : s.id;
+    else {
+        // First sentence: up to the first . ! or ? that ends a word — the lookahead keeps `A-SPEC-129.2`
+        // whole, because its dot is followed by a digit, not by whitespace or the end.
+        const m = /^(.*?[.!?])(?=\s|$)/.exec(text);
+        let sentence = m ? m[1] : text;
+        if (sentence.length > SUMMARY_SENTENCE_CAP)
+            sentence = `${sentence.slice(0, SUMMARY_SENTENCE_CAP)}…`;
+        result = title !== '' ? `${title} — ${sentence}` : sentence;
+    }
+    // @implements A-SPEC-569.1 — the WHOLE summary folds, title included. The first cut normalized
+    // only the sentence, and a YAML double-quoted title carried \n/\t straight into dumpCanonical,
+    // where graphViewOf parsed the forged row as a real call edge (0.16.0 adversarial reproduction).
+    // Prose must never carry the dump's structural characters.
+    return result.replace(/\s+/g, ' ').trim();
 }
 /**
  * Adds one scanned file's CODE nodes and `implements` edges to the graph,

package/dist/holmes/rtm/rtm-graph.d.ts

@@ -61,6 +61,9 @@ export declare class RtmGraph {
      */
     summaryOf(id: string): string | null;
     addEdge(src: string, dst: string, rel: string, sourcePath?: string, provenance?: Provenance): void;
+    /** @implements A-SPEC-569.1 — does the graph hold this node? SELECT 1, no row materialization:
+     * the approved-only channel filter (A-SPEC-569.2) asks exactly this and nothing more. */
+    hasNode(id: string): boolean;
     /** @implements A-SPEC-281 — how this node got here, or null if the node is unknown. */
     provenanceOfNode(id: string): Provenance | null;
     /** @implements A-SPEC-281 — how this edge got here, or null if the edge is unknown. */
@@ -212,6 +215,15 @@ export declare class RtmGraph {
     clear(): void;
     /** @implements A-SPEC-283 — the journal mode actually in force, so the pragma can be asserted. */
     journalMode(): string;
+    /**
+     * @implements A-SPEC-569.5
+     * Live anchors per source file — distinct SPEC targets of `implements` edges, one GROUP BY.
+     * Feeds the anchor-density OBSERVATION at sealing time; nothing reads it into a verdict.
+     */
+    implementsAnchorCounts(): Array<{
+        sourcePath: string;
+        anchors: number;
+    }>;
     nodeCount(): number;
     edgeCount(): number;
     close(): void;

package/dist/holmes/rtm/rtm-graph.js

@@ -120,7 +120,11 @@ class RtmGraph {
     edgeStmt;
     addNode(id, kind, sourcePath, provenance, summary) {
         this.nodeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO nodes (id,kind,source_path,summary,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
-        this.nodeStmt.run(id, kind, sourcePath ?? null, summary ?? null, ...provenanceRow(provenance));
+        // @implements A-SPEC-569.1 — the STORAGE boundary folds structural characters too, so a future
+        // caller that never went through specSummary still cannot forge dumpCanonical rows. Second,
+        // independent face of the seal (each face is verified alone).
+        const foldedSummary = summary == null ? null : summary.replace(/\s+/g, ' ').trim();
+        this.nodeStmt.run(id, kind, sourcePath ?? null, foldedSummary, ...provenanceRow(provenance));
     }
     /**
      * @implements A-SPEC-568.1
@@ -137,6 +141,11 @@ class RtmGraph {
         this.edgeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO edges (src,dst,rel,source_path,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
         this.edgeStmt.run(src, dst, rel, sourcePath ?? null, ...provenanceRow(provenance));
     }
+    /** @implements A-SPEC-569.1 — does the graph hold this node? SELECT 1, no row materialization:
+     * the approved-only channel filter (A-SPEC-569.2) asks exactly this and nothing more. */
+    hasNode(id) {
+        return this.db.prepare('SELECT 1 FROM nodes WHERE id = ?').get(id) !== undefined;
+    }
     /** @implements A-SPEC-281 — how this node got here, or null if the node is unknown. */
     provenanceOfNode(id) {
         return provenanceOf(this.db.prepare('SELECT * FROM nodes WHERE id = ?').get(id));
@@ -364,15 +373,21 @@ class RtmGraph {
         // @implements A-SPEC-281 — provenance is part of the value, so a provenance-only divergence
         // between a full rebuild and an incremental update is caught rather than passing as equal.
         const cols = PROVENANCE_COLUMNS.join(', ');
-        const prov = (r) => PROVENANCE_COLUMNS.map((c) => (r[c] === null || r[c] === undefined ? '' : String(r[c]))).join('\t');
+        // @implements A-SPEC-569.1 (revision) — EVERY text column folds at emission. Sealing columns
+        // one at a time (title → summary) was whack-a-mole: high-effort review found id/depends_on
+        // carrying tabs into these rows and shifting columns under graphViewOf. The dump's structural
+        // characters are the dump's own concern, so this is the single choke point; the row-shape
+        // invariant (exactly 13 cells, structural-char-free) is pinned by test.
+        const fold = (v) => (v === null || v === undefined ? '' : String(v).replace(/[\t\n\r]+/g, ' '));
+        const prov = (r) => PROVENANCE_COLUMNS.map((c) => fold(r[c])).join('\t');
         const nodes = this.db.prepare(`SELECT id, kind, source_path, summary, ${cols} FROM nodes ORDER BY id`).all();
         const edges = this.db.prepare(`SELECT src, dst, rel, source_path, ${cols} FROM edges ORDER BY src, dst, rel`).all();
         return [
             // @implements A-SPEC-568.1 — summary is part of the VALUE (appended last so every positional
             // consumer of the earlier columns is untouched); a summary-only divergence between two builds
             // must fail the convergence comparison rather than pass as equal.
-            ...nodes.map((n) => `N\t${n.id}\t${n.kind}\t${n.source_path ?? ''}\t${prov(n)}\t${n.summary ?? ''}`),
-            ...edges.map((e) => `E\t${e.src}\t${e.dst}\t${e.rel}\t${e.source_path ?? ''}\t${prov(e)}`),
+            ...nodes.map((n) => `N\t${fold(n.id)}\t${fold(n.kind)}\t${fold(n.source_path)}\t${prov(n)}\t${fold(n.summary)}`),
+            ...edges.map((e) => `E\t${fold(e.src)}\t${fold(e.dst)}\t${fold(e.rel)}\t${fold(e.source_path)}\t${prov(e)}`),
         ].join('\n');
     }
     /**
@@ -416,6 +431,16 @@ class RtmGraph {
     journalMode() {
         return String(this.db.pragma('journal_mode', { simple: true }) ?? '');
     }
+    /**
+     * @implements A-SPEC-569.5
+     * Live anchors per source file — distinct SPEC targets of `implements` edges, one GROUP BY.
+     * Feeds the anchor-density OBSERVATION at sealing time; nothing reads it into a verdict.
+     */
+    implementsAnchorCounts() {
+        return this.db.prepare(`SELECT source_path AS sourcePath, COUNT(DISTINCT dst) AS anchors FROM edges
+        WHERE rel='implements' AND source_path IS NOT NULL GROUP BY source_path ORDER BY source_path ASC`)
+            .all();
+    }
     nodeCount() { return this.db.prepare('SELECT COUNT(*) AS c FROM nodes').get().c; }
     edgeCount() { return this.db.prepare('SELECT COUNT(*) AS c FROM edges').get().c; }
     close() { this.db.close(); }

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",

package/playbooks/publish/PLAYBOOK.md

@@ -37,15 +37,24 @@ npm publish 는 **비가역·외부노출**이라 기본은 HITL(사람 승인)
 ---
 
 ### 2.5단계: 문서 정합성 게이트 (Docs Currency Gate) — 배포는 정직한 고지다
-타르볼에 문서가 **포함**됐는지가 아니라 **최신인지**를 diff로 검사한다(이 단계 없이 폐기된 동작이 README에
-현재형으로 남는 사고가 실제로 있었다):
+타르볼에 문서가 **포함**됐는지가 아니라 **최신인지**를 검사한다. 부정직은 두 방향이다: 거짓을
+남기는 것(drift)과 참을 숨기는 것(absence) — 둘 다 차단한다. (사고 이력 둘: 폐기된 동작이
+README 에 현재형으로 남은 사고, 그리고 **0.16.0 — 신기능 3건이 README 기능 목록에 아예 없는데
+"옛 문구 grep 0건"이 통과로 읽혀 그대로 배포된 사고.**)
 1. 직전 릴리스 태그 이후 승인된 스펙 열거: `git log <last-tag>..HEAD --name-only -- .ax/specs/03_a-spec/`.
-2. 각 A-SPEC 중 **사용자-대면**(CLI 명령/플래그, 동작 변경, env 스위치, 게이트 행동)인 것마다:
-   - `CHANGELOG.md` 의 이번 버전 항목이 그 변화를 기술하는가.
-   - `README.md` 의 기능 목록/CLI 치트시트가 새 명령·플래그를 담고, **폐기된 동작을 현재형으로 서술하지
-     않는가**(바뀐 동작의 옛 문구를 `grep` 으로 점검).
+2. 각 A-SPEC 중 **사용자-대면**(CLI 명령/플래그, MCP 응답 필드, 동작 변경, env 스위치, 게이트
+   행동, 신규 원장/아티팩트)인 것마다 — **세 검사를 모두**:
+   - **(2a) 추가-검사(absence)**: `CHANGELOG.md` 이번 버전 항목과 `README.md` 기능 목록에 그
+     변화의 항목이 **존재**하는가. 기능 이름으로 `grep` 해서 **0건이면 그것은 '통과'가 아니라
+     누락 신호다** — 쓴 적 없는 기능은 옛 문구도 없다.
+   - **(2b) drift-검사**: 바뀐 동작의 **옛 문구**를 `grep` 으로 점검 — 폐기된 동작을 현재형으로
+     서술하지 않는가.
+   - **(2c) 스테일 마커**: 기능 섹션 제목 등의 **버전-고정 라벨**("vX.Y.x Features" 류)은 매
+     릴리스 수동 갱신을 요구하는 drift 발생기다 — 발견 즉시 버전-무관 표현으로 제거한다(항목별
+     *(new in X.Y.Z)* 가 시점을 말한다).
 > [!CAUTION]
-> 사용자-대면 변화가 CHANGELOG/README 에 반영되지 않았으면 배포 중단 — 문서 drift 는 거짓 주장이다.
+> 사용자-대면 변화가 CHANGELOG/README 에 반영되지 않았으면 배포 중단 — 문서 drift 도, 문서
+> 누락도 거짓 주장이다.
 
 ---