@holmes-lab/holmes-kit 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -5,6 +5,66 @@ 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.23.1] - 2026-09-18
+
+A release that could not be published, and the documentation that had fallen three versions behind.
+
+### Fixed
+- **The release gate knows the ledgers 0.22.0 began tracking** (A-SPEC-668). `v0.23.0`'s publish was
+  refused on a dirty tree: 0.22.0 taught `.gitignore` to track `advisory-outcomes` and `ci-runs`, and
+  `verify-release.js`'s append-only exclusion list never heard about it. The first is appended by every
+  seal and every `approval_status`; the second by the launchd CI runner every fifteen minutes — between
+  them this repository could no longer publish at an arbitrary moment. Both are excused now, and a pin
+  asserts that every TRACKED ledger is excused, naming any that is not so the next person knows which
+  file to edit. The reverse slack is reported rather than asserted away (an excused-but-untracked ledger
+  costs nothing, because a gitignored file never shows as dirty).
+
+### Docs
+- **The README lists 0.21.0 through 0.23.0.** The feature list stopped at 0.20.0 while three releases
+  shipped. The publish playbook's docs-currency gate forbids exactly that — "a stale doc is a false
+  claim" — and it is a written step with no automation, so it was skipped twice. Automating it is the
+  next candidate.
+
+## [0.23.0] - 2026-09-18
+
+Three things this release stops doing quietly: deleting the neighbours in a config file it shares,
+going deaf when its own child process dies, and reporting a coverage shortfall it cannot explain.
+
+### Fixed
+- **A re-wire no longer deletes the other tools' entries** (A-SPEC-667). `init --agent antigravity`
+  and `init --agent codex` replaced `.agents/mcp_config.json`, `.agents/hooks.json` and
+  `marketplace.json` whole. Measured with a real `--dry-run` before the change: a neighbour MCP
+  server, a neighbour hook namespace, a neighbour plugin, a marketplace's own name and an operator's
+  `disabled` flag all survived a re-wire at a rate of zero. They now survive; only the holmes-kit
+  entry is refreshed, and `init` names what it kept. A `disabled` flag an operator set is preserved
+  rather than silently switched back on, and `init` says the gate will not run while it stands. An
+  existing file that is not readable JSON is refused with a reason instead of being replaced. The
+  Claude wiring already merged (A-SPEC-179); this gives the other two harnesses the same discipline.
+- **The MCP supervisor notices a child that died** (A-SPEC-666). With no exit handler it kept writing
+  to a dead pipe, its in-flight count never returned to zero, and the swap that would have replaced
+  the child therefore never fired — the server was permanently deaf. Reproduced against the real
+  supervisor, twice in one session and once on demand. It now answers every outstanding request with
+  a JSON-RPC error before anything else (a client must not wait for ever), resets, respawns and
+  replays the opening exchange. A child that dies having never answered spends a restart budget, so a
+  broken build stops quickly while a single crash under load restarts freely; an intentional swap or
+  `stop()` is not counted as an accident. Affects supervised runs only (`HOLMES_MCP_AUTORELOAD`).
+
+### Added
+- **The census says what an unlinked spec declared, not just where it is anchored** (A-SPEC-665).
+  `rtm_dashboard` and `/api/rtm` now classify every unlinked approved A-SPEC on a second axis —
+  `scanned-source`, `file-anchor-target`, `test-target`, `unreachable-target`, `no-declaration` —
+  beside the existing `unlinkedByReason`, and report how many specs declare a path no anchor
+  mechanism can read. Measured here: of 52 unlinked specs, zero declare a file the scanner parses, so
+  the remaining 8.1% of `codeLinkedPct` is not a missing anchor. Bucket names state what was
+  declared; whether that is a defect remains `traceGaps`'s answer.
+
+### Measured
+- macOS: 528 suites / 6,607 passed / 11 skipped, every suite green; each slice recorded red-assertion → green with an official `test_run` at both ends.
+- Linux (OrbStack Ubuntu 24.04 arm64, Node 22): judged automatically on every commit by the launchd
+  runner added in 0.22.0. Residual reds are load-dependent suites that pass when run alone —
+  `dashboard.test` was verified at 120 s alone on the VM against 370 s under load.
+- Windows: not re-run; no Windows-specific change landed.
+
 ## [0.22.0] - 2026-09-18
 
 The advisories learn what happened next. Until now this repository issued findings and recorded that

package/README.md

@@ -16,6 +16,14 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🧩 **Your config files survive a re-wire** *(new in 0.23.0)*: `init --agent antigravity` and `init --agent codex` used to replace `.agents/mcp_config.json`, `.agents/hooks.json` and `marketplace.json` **whole**. Measured with a real `--dry-run` before the fix: a neighbour MCP server, a neighbour hook namespace, a neighbour plugin, a marketplace's own name and an operator's `disabled` flag all survived a re-wire at a rate of **zero**. They now survive — only the holmes-kit entry is refreshed, and `init` names what it kept. A `disabled` you set stays set (and `init` says the gate will not run while it stands, rather than switching it back on silently); an existing file that is not readable JSON is refused with a reason instead of being replaced. The Claude wiring already merged; the other two harnesses now have the same discipline.
+- 🫀 **The MCP supervisor notices a child that died** *(new in 0.23.0)*: under `HOLMES_MCP_AUTORELOAD` the supervisor had no exit handler, so a crashed child left it writing to a dead pipe — its in-flight count never returned to zero, the swap that would have replaced the child never fired, and the server went **permanently deaf** (observed twice in one session, then reproduced on demand against the real class). It now answers every outstanding request with a JSON-RPC error **first** (a client must never wait for ever), then resets, respawns and replays the opening exchange. A child that dies having never answered spends a restart budget, so a broken build stops quickly while one crash under load restarts freely; an intentional swap or shutdown is not counted as an accident.
+- 🧮 **Coverage you can explain** *(new in 0.23.0)*: the RTM census already said *where* an unlinked spec is anchored; it now also says *what it declared* — `scanned-source`, `file-anchor-target`, `test-target`, `unreachable-target`, `no-declaration` — plus how many specs declare a path no anchor mechanism can read. On this repository, of 52 unlinked approved specs **zero** declare a file the scanner parses, so the remaining 8.1% of `codeLinkedPct` is not a missing anchor. Bucket names state the fact; whether one is a defect stays `traceGaps`'s answer.
+- 🤖 **A CI matrix that judges every commit, and never reads silence as green** *(new in 0.22.0)*: a maintainer-side runner takes one commit onto a Linux VM (clone → install → build → full suite) and appends exactly one row to a `ci-runs` ledger — for every outcome, including the ones where the run could not judge (`clone-failed`, `install-failed`, `vm-unreachable`). A launchd agent triggers it per commit. The Stop hook reports the matrix's last word and `doctor` gains a `ci matrix` check; a missing row reads as **"not run"**, never as a pass. Workspaces that never adopted the matrix hear nothing about it.
+- 🔁 **Advisories learn what happened next** *(new in 0.22.0)*: every finding — impact, anchor density, Files-to-Touch fulfilment, trace gap, `kills`-unapplicable — now carries a deterministic id. Sealing records it as `issued`; the next `approval_status` re-runs the **same** functions and records `resolved` when the cause is gone or `persisted` when it is not, at most one row per finding per day. An author who judges a finding unhelpful passes `dismiss: [id]`; an unknown id comes back in `dismissUnknown` rather than inventing a row. `rtm_dashboard`'s census gains the per-kind tallies. This is the numerator every "promote to a hard gate once we know the false-positive rate" sentence was missing.
+- 🧪 **`kills` that cannot apply say so** *(new in 0.22.0)*: `test_run --mutate` reports mutations that never applied as `unapplied`, separately from `survivors`. Measured here, all 22 `kills` entries in this repository wrote `where` as a file path and `mutate` as prose, so the literal-replacement engine applied **none** of them while the response still read `survivors: []` — the shape of a clean run. Sealing a T-SPEC now reports entries whose `where` is absent from the A-SPEC's anchored source, and the authoring playbook shows the grammar.
+- 🔎 **The RTM stops claiming coverage it cannot see** *(new in 0.21.0)*: `rtm_dashboard` and `/api/rtm` report `codeLinkedPct`, `unlinkedCount` and `unlinkedByReason` beside the old `coveragePct`, which read 100 while 11.4% of approved specs carried no `implements` edge. The scanner now also reads every anchor the injector can write (`.sh`/`.yml`/`.toml` anchors were planted and never indexed). Sealing gained a **Files-to-Touch fulfilment advisory** (declared paths that do not exist, as `missing`/`moved`/`alternatives`, ledgered, never blocking) and `rtm_impact` gained **trace gaps** — approved specs that declare a changed production file yet anchor only tests, with `impact_gate_check` answering `trace-gap` instead of silently widening.
+- 🩹 **`@known-defect(reason, expires=YYYY-MM-DD)` and constitution article ART-9** *(new in 0.21.0)*: a test that pins a known defect as its expected value carries a machine-readable marker. Unexpired markers are listed on the Stop hook's `tracked` channel as debt; the gate blocks only when a marker has **expired** or cannot be read (`no-reason`, `no-expires`, `bad-date`). String literals are stripped first, the expiry day itself counts as expired (UTC), and a walk that cannot start is no signal rather than a clean bill. A bypass is sometimes the right call — the marker is there so the next person can see it.
 - 🧑‍🤝‍🧑 **Concurrent Multi-Agent Workspace** *(new in 0.20.0)*: several agents, machines and clones work on one spec store and converge through Git. A Git-shareable **workspace identity** with per-checkout replica registration (`workspace_identity`) stamps every governed write with run provenance; specs become **UUID-keyed entities** (`entity_store`) whose display ids can be **renumbered without losing identity, anchors or approval closure** (`entity_renumber`); independent work from a common ancestor is **integrated** with stable identity, per-side conflict evidence, automatic renumbering of colliding new ids and explicit derived-state discharge (`entity_integrate`); single-use approvals are spent on the writer's own ledger chain so offline clones merge cleanly, and a nonce spent twice is a structured **double-spend** that freezes every authority-spending act until `ledger_reconcile`. Evidence (RED→GREEN outcomes, timelines) follows the entity across renames. Reproduced end to end in a project outside this repository on macOS and Linux.
 - 🗂️ **Approval decisions you can actually see** *(new in 0.20.0)*: `holmes-kit approve --status` (and the `--watch` header) shows the workspace, the delegation posture, and per request the risk grade, who asked (run · replica · workspace), the subject digest and exactly what a grant would open — plus recent decisions with their outcome (live until / consumed / expired / revoked / denied). A grant is now **bound to the workspace it was minted in and to the content the human read**: a copied grant is refused as `foreign-workspace`, a seal of changed content as `stale-subject`, and `approve --revoke` withdraws a live grant. Grants are git-ignored by `init`.
 - 🔁 **Import cycles are governed, at the three moments that can each do something** *(new in 0.19.0)*: the spec graph has been required to be acyclic since early on; the code graph now is too. **Guidance** reaches the agent before it designs (the authoring playbooks say "share types through a third module", pinned by test). **A design-time advisory** — `approval_status`'s `graphPreview` gains `cycles` — names the cycles your declared files are *already* in, with each edge classified as `type-erasable` (TypeScript deletes it, so it is not a runtime cycle), `lazy-require` (a workaround someone already paid for) or `eager-value`; the note says in words that this is **not** a prediction, because at approval time the code that would create a cycle does not exist yet. **A ratchet** in the Stop hook's constitution catches new cycles after the code is written — shipped in `track` (records, never blocks), and the escape is a **named exception**, never a threshold, so a project carrying legacy cycles can still adopt the harness. This repository went from three cycles to zero, and the two lazy `require()` workarounds they forced are gone.

package/dist/.build-id

@@ -1 +1 @@
-71586207-mu68mv0a
+d2304488-mu6dv817

package/dist/holmes/cli/agents.d.ts

@@ -98,6 +98,44 @@ export declare function mergeAgentsMd(existing: string | null, generated: string
  * 계산과 쓰기를 나누는 이유는 dry-run 이 실제 실행과 같은 집합을 예고해야 하기 때문이다
  * (A-SPEC-190 §9). 같은 함수가 두 경로에 답하면 둘이 어긋날 수 없다.
  */
+/**
+ * @implements A-SPEC-667
+ * Merging a wiring file the harness shares with other tools.
+ *
+ * Measured 2026-09-18 with a real `--dry-run`: a neighbour MCP server, a neighbour hook namespace, a
+ * neighbour plugin, a marketplace's own name and an operator's `disabled` flag all survived a
+ * re-wire at a rate of ZERO — the agy and codex writers replaced each file whole. The Claude path
+ * learned this in A-SPEC-179 ("merge, not replace"; `--force` means refresh the wiring, not turn off
+ * what I switched on). These functions give the other two harnesses the same discipline.
+ *
+ * Pure text in, pure text out, so `init` can merge during its COMPUTE phase and `--dry-run` predicts
+ * the bytes the write produces (the A-SPEC-190 §9 rule).
+ */
+export interface WiringMerge {
+    content: string;
+    /** Names of things that were kept because they are not ours — reported to the person verbatim. */
+    preserved: string[];
+    /** Sentences about the merged state a person needs (e.g. the wiring is present but disabled). */
+    notes: string[];
+    /** Set when the existing file could not be read; `content` is then the ORIGINAL, and init skips it. */
+    refused?: string;
+}
+/**
+ * `.agents/mcp_config.json`. Neighbour servers survive whole; inside the holmes-kit entry our
+ * command, args and `HOLMES_SPECS` win while every other key a person put there — `disabled` above
+ * all — is kept. Turning someone's switch back on without a word is the surprise this prevents.
+ */
+export declare function mergeMcpConfigJson(before: string | null, ours: string): WiringMerge;
+/** `.agents/hooks.json`. Top-level keys are tool namespaces; only ours is replaced. */
+export declare function mergeHooksJson(before: string | null, ours: string): WiringMerge;
+/**
+ * `marketplace.json`. Only the holmes-kit plugin entry is ours; the marketplace's identity and every
+ * other plugin belong to whoever created the file. Renaming someone's marketplace to ours would be
+ * the same silent theft as deleting their plugins.
+ */
+export declare function mergeMarketplaceJson(before: string | null, ours: string): WiringMerge;
+/** The merged set, by basename. `null` means "no merger" — the caller writes as it always did. */
+export declare function mergeWiringFile(basename: string, before: string | null, ours: string): WiringMerge | null;
 export declare function agentFiles(agent: Agent, opts: AgentWiringOptions): AgentFile[];
 export interface AgentLink {
     path: string;

package/dist/holmes/cli/agents.js

@@ -38,6 +38,10 @@ exports.antigravityHookCommand = antigravityHookCommand;
 exports.shortPathIfSpaced = shortPathIfSpaced;
 exports.antigravityHookWarnings = antigravityHookWarnings;
 exports.mergeAgentsMd = mergeAgentsMd;
+exports.mergeMcpConfigJson = mergeMcpConfigJson;
+exports.mergeHooksJson = mergeHooksJson;
+exports.mergeMarketplaceJson = mergeMarketplaceJson;
+exports.mergeWiringFile = mergeWiringFile;
 exports.agentFiles = agentFiles;
 exports.agentLinks = agentLinks;
 // @implements A-SPEC-202, A-SPEC-250, A-SPEC-341
@@ -297,12 +301,109 @@ function closeRun(runs, run) {
         runs.push(run);
     return [];
 }
+const HOLMES = 'holmes-kit';
+/** Parse, or explain why not. An unreadable file is never replaced: silently deleting it is the defect. */
+function parseOr(before, ours, what) {
+    if (before === null)
+        return { content: ours, preserved: [], notes: [] };
+    let prev;
+    try {
+        prev = JSON.parse(before);
+    }
+    catch {
+        return { content: before, preserved: [], notes: [], refused: `${what} is not readable JSON — left untouched; fix or remove it, then re-run init` };
+    }
+    if (prev === null || typeof prev !== 'object' || Array.isArray(prev)) {
+        return { content: before, preserved: [], notes: [], refused: `${what} is not a JSON object — left untouched; fix or remove it, then re-run init` };
+    }
+    return { prev: prev };
+}
+const isMerge = (x) => 'content' in x;
+const asObject = (v) => (v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {});
 /**
- * 이 하네스에 써야 할 파일들. **쓰지는 않는다** — 무엇을 쓸지만 말한다.
- *
- * 계산과 쓰기를 나누는 이유는 dry-run 이 실제 실행과 같은 집합을 예고해야 하기 때문이다
- * (A-SPEC-190 §9). 같은 함수가 두 경로에 답하면 둘이 어긋날 수 없다.
+ * `.agents/mcp_config.json`. Neighbour servers survive whole; inside the holmes-kit entry our
+ * command, args and `HOLMES_SPECS` win while every other key a person put there — `disabled` above
+ * all — is kept. Turning someone's switch back on without a word is the surprise this prevents.
+ */
+function mergeMcpConfigJson(before, ours) {
+    const parsed = parseOr(before, ours, 'mcp_config.json');
+    if (isMerge(parsed))
+        return parsed;
+    const oursObj = asObject(JSON.parse(ours));
+    const oursEntry = asObject(asObject(oursObj.mcpServers)[HOLMES]);
+    const prevServers = asObject(parsed.prev.mcpServers);
+    const prevEntry = asObject(prevServers[HOLMES]);
+    const keptKeys = Object.keys(prevEntry).filter((k) => k !== 'command' && k !== 'args' && k !== 'env');
+    const merged = {
+        ...prevEntry,
+        command: oursEntry.command,
+        args: oursEntry.args,
+        env: { ...asObject(prevEntry.env), ...asObject(oursEntry.env) },
+    };
+    const out = { ...parsed.prev, mcpServers: { ...prevServers, [HOLMES]: merged } };
+    const notes = [];
+    if (prevEntry.disabled === true || prevEntry.disabled === 'true') {
+        notes.push(`mcp_config.json: holmes-kit is wired but DISABLED in this config — the gate will not run until it is enabled.`);
+    }
+    return {
+        content: `${JSON.stringify(out, null, 2)}\n`,
+        preserved: [...Object.keys(prevServers).filter((k) => k !== HOLMES), ...keptKeys],
+        notes,
+    };
+}
+/** `.agents/hooks.json`. Top-level keys are tool namespaces; only ours is replaced. */
+function mergeHooksJson(before, ours) {
+    const parsed = parseOr(before, ours, 'hooks.json');
+    if (isMerge(parsed))
+        return parsed;
+    const oursObj = asObject(JSON.parse(ours));
+    const out = { ...parsed.prev, [HOLMES]: oursObj[HOLMES] };
+    return {
+        content: `${JSON.stringify(out, null, 2)}\n`,
+        preserved: Object.keys(parsed.prev).filter((k) => k !== HOLMES),
+        notes: [],
+    };
+}
+/**
+ * `marketplace.json`. Only the holmes-kit plugin entry is ours; the marketplace's identity and every
+ * other plugin belong to whoever created the file. Renaming someone's marketplace to ours would be
+ * the same silent theft as deleting their plugins.
  */
+function mergeMarketplaceJson(before, ours) {
+    const parsed = parseOr(before, ours, 'marketplace.json');
+    if (isMerge(parsed))
+        return parsed;
+    const oursObj = asObject(JSON.parse(ours));
+    const oursPlugin = (Array.isArray(oursObj.plugins) ? oursObj.plugins : []).find((p) => asObject(p).name === HOLMES);
+    const prevPlugins = Array.isArray(parsed.prev.plugins) ? parsed.prev.plugins : [];
+    const hadOurs = prevPlugins.some((p) => asObject(p).name === HOLMES);
+    const plugins = hadOurs
+        ? prevPlugins.map((p) => (asObject(p).name === HOLMES ? oursPlugin : p))
+        : [...prevPlugins, oursPlugin];
+    const keptName = typeof parsed.prev.name === 'string' && parsed.prev.name !== '' ? parsed.prev.name : undefined;
+    const out = {
+        ...parsed.prev,
+        name: keptName ?? oursObj.name,
+        interface: parsed.prev.interface ?? oursObj.interface,
+        plugins,
+    };
+    const neighbours = prevPlugins.map((p) => String(asObject(p).name ?? '')).filter((n) => n !== '' && n !== HOLMES);
+    return {
+        content: `${JSON.stringify(out, null, 2)}\n`,
+        preserved: [...neighbours, ...(keptName !== undefined && keptName !== oursObj.name ? [keptName] : [])],
+        notes: [],
+    };
+}
+/** The merged set, by basename. `null` means "no merger" — the caller writes as it always did. */
+function mergeWiringFile(basename, before, ours) {
+    if (basename === 'mcp_config.json')
+        return mergeMcpConfigJson(before, ours);
+    if (basename === 'hooks.json')
+        return mergeHooksJson(before, ours);
+    if (basename === 'marketplace.json')
+        return mergeMarketplaceJson(before, ours);
+    return null;
+}
 function agentFiles(agent, opts) {
     const { target, packageRoot, specsDir } = opts;
     switch (agent) {

package/dist/holmes/cli/init.js

@@ -471,6 +471,23 @@ function runInit(opts) {
                     }
                     continue;
                 }
+                // @implements A-SPEC-667 — these files are shared with other tools. Replacing one whole
+                // deletes a neighbour's MCP server, hooks or plugins without a word (measured 2026-09-18:
+                // every third-party entry survived at a rate of zero). Merging happens HERE, in the compute
+                // phase, so `--dry-run` predicts the bytes the write produces (A-SPEC-190 §9).
+                const wiring = (0, agents_1.mergeWiringFile)(path.basename(f.path), before, f.content);
+                if (wiring) {
+                    if (wiring.refused) {
+                        messages.push(`${f.path}: ${wiring.refused}`);
+                        continue;
+                    }
+                    changes.push({ path: f.path, before, after: wiring.content });
+                    if (wiring.preserved.length > 0)
+                        messages.push(`${f.path}: kept ${wiring.preserved.length} ${wiring.preserved.length === 1 ? 'entry that is' : 'entries that are'} not holmes-kit's — ${wiring.preserved.join(', ')}`);
+                    for (const n of wiring.notes)
+                        messages.push(n);
+                    continue;
+                }
                 changes.push({ path: f.path, before, after: f.content });
             }
             // @implements A-SPEC-586 — an antigravity hook whose path still carries a space is a hook the

package/dist/holmes/mcp/handlers/operator-inspection.d.ts

@@ -182,6 +182,8 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
                 unmapped: number;
                 nonSpec: number;
             };
+            declaredScopeByScope: Record<import("../../rtm/declared-scope").DeclaredScope, number>;
+            unreachableDeclaringCount: number;
             reqCount: number;
             pipelineCount: number;
             coveredCount: number;

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

@@ -839,6 +839,8 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
                 unmapped: number;
                 nonSpec: number;
             };
+            declaredScopeByScope: Record<import("../rtm/declared-scope").DeclaredScope, number>;
+            unreachableDeclaringCount: number;
             reqCount: number;
             pipelineCount: number;
             coveredCount: number;

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

@@ -1,5 +1,12 @@
 /** Opt-in switch. Absent means the entry point behaves exactly as it did before this existed. */
 export declare const AUTORELOAD_ENV = "HOLMES_MCP_AUTORELOAD";
+/**
+ * @implements A-SPEC-666 — how many times a child may die WITHOUT ever answering before the
+ * supervisor stops replacing it. A server that worked and then died once has not spent this budget;
+ * only a child that produced nothing in its whole life counts, so "a broken build that dies on every
+ * spawn" stops quickly while "one OOM under load" restarts freely.
+ */
+export declare const MAX_CONSECUTIVE_SILENT_DEATHS = 5;
 export declare function autoreloadEnabled(env: NodeJS.ProcessEnv): boolean;
 /**
  * Whether the child may be replaced right now.
@@ -63,10 +70,38 @@ export declare class Supervisor {
      * supervisor makes, that the connection does not drop.
      */
     private handshake;
+    /**
+     * @implements A-SPEC-666 — WHICH requests are unanswered, not merely how many. `inflight` counts
+     * for the swap decision and its counter is contracted to count without identifying (A-SPEC-516.1);
+     * answering a death needs identity, so it is tracked separately rather than by widening that one.
+     */
+    private pending;
+    /** True while an exit we caused (a swap, a stop) is expected — not every death is an accident. */
+    private expectedExit;
+    /** Consecutive children that died having never answered anything. Reset by any answer. */
+    private silentDeaths;
+    private answeredSinceSpawn;
+    /** True once the limit is reached: the supervisor stops replacing and says so. */
+    private givenUp;
     constructor(repoRoot: string, onSwap?: ((from: string, to: string, replayed: number) => void) | undefined);
     start(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream): void;
     private forward;
     private swap;
     private spawnChild;
+    /**
+     * @implements A-SPEC-666
+     * Drop the ids of every COMPLETE response line from `pending`; return the unfinished tail so a
+     * reply split across chunks is not lost. A line with neither `result` nor `error` is a
+     * notification, not an answer, and retires nothing.
+     */
+    private retireAnsweredIds;
+    /**
+     * @implements A-SPEC-666
+     * The child is gone. Measured 2026-09-18: without this, `this.child` kept pointing at the corpse,
+     * every later request was written to a dead pipe, `inflight` never returned to zero and
+     * `shouldSwap`'s `inflight === 0` therefore never fired — the server was deaf for the rest of the
+     * session, twice in one day. Order matters: free the client first, then decide about a replacement.
+     */
+    private onChildGone;
     stop(): void;
 }

package/dist/holmes/mcp/supervisor.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Supervisor = exports.AUTORELOAD_ENV = void 0;
+exports.Supervisor = exports.MAX_CONSECUTIVE_SILENT_DEATHS = exports.AUTORELOAD_ENV = void 0;
 exports.autoreloadEnabled = autoreloadEnabled;
 exports.shouldSwap = shouldSwap;
 exports.createResponseCounter = createResponseCounter;
@@ -43,6 +43,13 @@ const path = __importStar(require("node:path"));
 const basis_1 = require("./basis");
 /** Opt-in switch. Absent means the entry point behaves exactly as it did before this existed. */
 exports.AUTORELOAD_ENV = 'HOLMES_MCP_AUTORELOAD';
+/**
+ * @implements A-SPEC-666 — how many times a child may die WITHOUT ever answering before the
+ * supervisor stops replacing it. A server that worked and then died once has not spent this budget;
+ * only a child that produced nothing in its whole life counts, so "a broken build that dies on every
+ * spawn" stops quickly while "one OOM under load" restarts freely.
+ */
+exports.MAX_CONSECUTIVE_SILENT_DEATHS = 5;
 function autoreloadEnabled(env) {
     const v = env[exports.AUTORELOAD_ENV];
     return typeof v === 'string' && v.trim() !== '';
@@ -144,6 +151,19 @@ class Supervisor {
      * supervisor makes, that the connection does not drop.
      */
     handshake = [];
+    /**
+     * @implements A-SPEC-666 — WHICH requests are unanswered, not merely how many. `inflight` counts
+     * for the swap decision and its counter is contracted to count without identifying (A-SPEC-516.1);
+     * answering a death needs identity, so it is tracked separately rather than by widening that one.
+     */
+    pending = new Set();
+    /** True while an exit we caused (a swap, a stop) is expected — not every death is an accident. */
+    expectedExit = false;
+    /** Consecutive children that died having never answered anything. Reset by any answer. */
+    silentDeaths = 0;
+    answeredSinceSpawn = false;
+    /** True once the limit is reached: the supervisor stops replacing and says so. */
+    givenUp = false;
     constructor(repoRoot, onSwap) {
         this.repoRoot = repoRoot;
         this.onSwap = onSwap;
@@ -165,12 +185,14 @@ class Supervisor {
     forward(line, stdout) {
         const trimmed = line.trim();
         let isRequest = false;
+        let requestId;
         if (trimmed.startsWith('{')) {
             try {
                 const msg = JSON.parse(trimmed);
                 if (msg.method === 'initialize' || msg.method === 'notifications/initialized')
                     this.handshake.push(line);
                 isRequest = msg.id !== undefined;
+                requestId = msg.id;
             }
             catch { /* unparseable input is relayed untouched; the child owns protocol errors */ }
         }
@@ -181,12 +203,16 @@ class Supervisor {
         const disk = (0, basis_1.loadedBuildId)(this.repoRoot);
         if (shouldSwap(this.loaded, disk, this.inflight))
             this.swap(disk, stdout);
-        if (isRequest)
+        if (isRequest) {
             this.inflight++;
+            if (requestId !== undefined)
+                this.pending.add(requestId); // @implements A-SPEC-666
+        }
         this.child?.stdin.write(line);
     }
     swap(to, stdout) {
         const from = this.loaded;
+        this.expectedExit = true; // @implements A-SPEC-666 — we are replacing it on purpose
         this.child?.kill();
         this.loaded = to;
         this.spawnChild(stdout);
@@ -217,6 +243,10 @@ class Supervisor {
         // @implements A-SPEC-516.1 — one counter per child: a half-read line from the process being
         // replaced must not be finished by its successor's first chunk.
         const counter = createResponseCounter();
+        // @implements A-SPEC-666 — a fresh child has answered nothing yet; the silent-death budget is
+        // spent only by children that stay silent for their whole life.
+        this.answeredSinceSpawn = false;
+        let idCarry = '';
         child.stdout.on('data', (d) => {
             const text = d.toString();
             // Relay FIRST. Counting is an observation and must never delay or alter the bytes.
@@ -226,9 +256,82 @@ class Supervisor {
             // count would let a swap happen mid-request, which is the mis-delivered answer this whole
             // mechanism defers swaps to avoid.
             this.inflight = Math.max(0, this.inflight - counter.push(text));
+            // @implements A-SPEC-666 — and separately, WHICH ids were answered, so a death can reply to
+            // the rest. Its own line assembly: the counter above is contracted to count, not to identify.
+            idCarry = this.retireAnsweredIds(idCarry + text);
         });
+        child.on('exit', () => this.onChildGone(stdout));
+        child.on('error', () => this.onChildGone(stdout));
+    }
+    /**
+     * @implements A-SPEC-666
+     * Drop the ids of every COMPLETE response line from `pending`; return the unfinished tail so a
+     * reply split across chunks is not lost. A line with neither `result` nor `error` is a
+     * notification, not an answer, and retires nothing.
+     */
+    retireAnsweredIds(buffered) {
+        const parts = buffered.split('\n');
+        const tail = parts.pop() ?? '';
+        for (const line of parts) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith('{'))
+                continue;
+            try {
+                const msg = JSON.parse(trimmed);
+                if (msg.id === undefined)
+                    continue;
+                if (msg.result === undefined && msg.error === undefined)
+                    continue;
+                if (this.pending.delete(msg.id))
+                    this.answeredSinceSpawn = true;
+                else
+                    this.answeredSinceSpawn = true; // an answer we did not track is still an answer
+            }
+            catch { /* a partial or malformed line retires nothing */ }
+        }
+        return tail;
+    }
+    /**
+     * @implements A-SPEC-666
+     * The child is gone. Measured 2026-09-18: without this, `this.child` kept pointing at the corpse,
+     * every later request was written to a dead pipe, `inflight` never returned to zero and
+     * `shouldSwap`'s `inflight === 0` therefore never fired — the server was deaf for the rest of the
+     * session, twice in one day. Order matters: free the client first, then decide about a replacement.
+     */
+    onChildGone(stdout) {
+        if (this.expectedExit) {
+            this.expectedExit = false;
+            return;
+        } // a swap or a stop, not an accident
+        if (this.givenUp)
+            return;
+        // 1. Answer what the dead child never will. A request without a reply is a client waiting for ever.
+        for (const id of this.pending) {
+            stdout.write(`${JSON.stringify({
+                jsonrpc: '2.0', id,
+                error: { code: -32603, message: 'holmes-kit MCP child process exited before answering this request' },
+            })}\n`);
+        }
+        const orphaned = this.pending.size;
+        this.pending.clear();
+        this.inflight = 0;
+        // 2. A child that produced nothing in its whole life spends the budget; one that worked does not.
+        this.silentDeaths = this.answeredSinceSpawn ? 0 : this.silentDeaths + 1;
+        if (this.silentDeaths >= exports.MAX_CONSECUTIVE_SILENT_DEATHS) {
+            this.givenUp = true;
+            this.child = undefined;
+            process.stderr.write(`[holmes-kit] MCP child died ${this.silentDeaths} times without answering — stopped restarting it. Check the build (\`npm run build\`) and restart the server.\n`);
+            return;
+        }
+        // 3. Replace it and re-send the opening exchange, exactly as a swap does.
+        process.stderr.write(`[holmes-kit] MCP child exited unexpectedly; restarting (${orphaned} unanswered request(s) failed).\n`);
+        this.spawnChild(stdout);
+        for (const line of this.handshake)
+            this.child?.stdin.write(line);
     }
     stop() {
+        this.expectedExit = true; // @implements A-SPEC-666 — a shutdown is not an accident
+        this.givenUp = true; // ... and nothing may respawn after it
         this.child?.kill();
     }
 }

package/dist/holmes/rtm/declared-scope.d.ts

@@ -0,0 +1,28 @@
+export type DeclaredScope = 'scanned-source' | 'file-anchor-target' | 'test-target' | 'unreachable-target' | 'no-declaration';
+export interface ScopePredicates {
+    isScanned(rel: string): boolean;
+    isFileAnchorable(rel: string): boolean;
+    isTest(rel: string): boolean;
+}
+export declare const DECLARED_SCOPES: readonly DeclaredScope[];
+export declare function emptyByScope(): Record<DeclaredScope, number>;
+/**
+ * One label per spec, by the STRONGEST reachability its declaration offers: a scanned source beats a
+ * file-anchor target beats a test file beats nothing any mechanism reads. `unreachable` is filled
+ * whatever the label is, because a single label hides the `docs/x.md` sitting beside a test file —
+ * measured here, 21 of the 52 unlinked specs declare at least one such path.
+ * The Files-to-Touch parser is REQ-656's, so path extraction has exactly one definition.
+ */
+export declare function declaredScopeOf(fttText: string, p: ScopePredicates): {
+    scope: DeclaredScope;
+    unreachable: string[];
+};
+/** Every entry labelled exactly once, so the aggregate sums to the population it was given. */
+export declare function declaredScopeCensus(entries: ReadonlyArray<{
+    id: string;
+    ftt: string;
+}>, p: ScopePredicates): {
+    byId: Record<string, DeclaredScope>;
+    byScope: Record<DeclaredScope, number>;
+    unreachableDeclaring: number;
+};

package/dist/holmes/rtm/declared-scope.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECLARED_SCOPES = void 0;
+exports.emptyByScope = emptyByScope;
+exports.declaredScopeOf = declaredScopeOf;
+exports.declaredScopeCensus = declaredScopeCensus;
+// @implements A-SPEC-665
+/**
+ * The DECLARATION axis of an unlinked approved A-SPEC.
+ *
+ * REQ-655's census answers "where is this spec anchored" (`UnlinkedReason`). It cannot answer the
+ * question a reader actually has when `codeLinkedPct` reads 91.9: is there production code for this
+ * spec to be linked to at all? Measured 2026-09-18, after REQ-664's S3 moved 21 anchors: of the 52
+ * unlinked approved specs, ZERO declare a file the scanner parses. They are unlinked because they
+ * have no such file, not because an anchor is missing.
+ *
+ * The two axes sit side by side and never share a name. This one names what a spec DECLARED — a
+ * fact — and says nothing about whether that is acceptable; `traceGaps` remains the reader that
+ * calls one of these situations a gap.
+ *
+ * Pure: every reachability question is injected, so the classification follows the mechanisms'
+ * own definitions rather than a second copy of them.
+ */
+const ftt_fulfilment_1 = require("./ftt-fulfilment");
+exports.DECLARED_SCOPES = ['scanned-source', 'file-anchor-target', 'test-target', 'unreachable-target', 'no-declaration'];
+function emptyByScope() {
+    return { 'scanned-source': 0, 'file-anchor-target': 0, 'test-target': 0, 'unreachable-target': 0, 'no-declaration': 0 };
+}
+/**
+ * One label per spec, by the STRONGEST reachability its declaration offers: a scanned source beats a
+ * file-anchor target beats a test file beats nothing any mechanism reads. `unreachable` is filled
+ * whatever the label is, because a single label hides the `docs/x.md` sitting beside a test file —
+ * measured here, 21 of the 52 unlinked specs declare at least one such path.
+ * The Files-to-Touch parser is REQ-656's, so path extraction has exactly one definition.
+ */
+function declaredScopeOf(fttText, p) {
+    const items = [...new Set((0, ftt_fulfilment_1.fttItems)(String(fttText ?? '')).map((i) => i.path))];
+    if (items.length === 0)
+        return { scope: 'no-declaration', unreachable: [] };
+    const unreachable = items.filter((rel) => !p.isScanned(rel) && !p.isFileAnchorable(rel) && !p.isTest(rel)).sort();
+    const scope = items.some((rel) => p.isScanned(rel)) ? 'scanned-source'
+        : items.some((rel) => p.isFileAnchorable(rel)) ? 'file-anchor-target'
+            : items.some((rel) => p.isTest(rel)) ? 'test-target'
+                : 'unreachable-target';
+    return { scope, unreachable };
+}
+/** Every entry labelled exactly once, so the aggregate sums to the population it was given. */
+function declaredScopeCensus(entries, p) {
+    const byId = {};
+    const byScope = emptyByScope();
+    let unreachableDeclaring = 0;
+    for (const e of entries) {
+        const r = declaredScopeOf(e.ftt, p);
+        byId[e.id] = r.scope;
+        byScope[r.scope] += 1;
+        if (r.unreachable.length > 0)
+            unreachableDeclaring += 1;
+    }
+    return { byId, byScope, unreachableDeclaring };
+}

package/dist/holmes/server/dashboard-launcher.d.ts

@@ -1,4 +1,5 @@
 import { UnlinkedReason } from '../rtm/link-census';
+import { DeclaredScope } from '../rtm/declared-scope';
 /** Honesty summary of what a launched dashboard shows — derived from the endpoints it serves. */
 export interface DashboardCensus {
     reqCount: number;
@@ -26,6 +27,12 @@ export interface DashboardCensusExtended extends DashboardCensus {
         unmapped: number;
         nonSpec: number;
     };
+    /**
+     * @implements A-SPEC-665 — the declaration axis beside the anchor axis: what the unlinked specs
+     * DECLARED, next to where they are anchored. A payload without it folds to zeros like the rest.
+     */
+    declaredScopeByScope: Record<DeclaredScope, number>;
+    unreachableDeclaringCount: number;
 }
 /**
  * Pure: the pinned census plus the code-link axis from `/api/rtm`'s `linkCensus`, `coveragePct`

package/dist/holmes/server/dashboard-launcher.js

@@ -7,6 +7,7 @@ exports._resetLauncher = _resetLauncher;
 exports._stopAll = _stopAll;
 // @implements A-SPEC-545.3
 const link_census_1 = require("../rtm/link-census");
+const declared_scope_1 = require("../rtm/declared-scope");
 /**
  * @implements A-SPEC-545.3
  * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
@@ -45,6 +46,8 @@ function dashboardCensusExtended(rtm, heatmap) {
         unlinkedCount: Array.isArray(lc?.unlinked) ? lc.unlinked.length : 0,
         unlinkedByReason: { ...(0, link_census_1.emptyByReason)(), ...(lc?.byReason ?? {}) },
         excluded: { total: retired + unmapped + nonSpec, retired, unmapped, nonSpec },
+        declaredScopeByScope: { ...(0, declared_scope_1.emptyByScope)(), ...(rtm?.declaredScope?.byScope ?? {}) },
+        unreachableDeclaringCount: typeof rtm?.declaredScope?.unreachableDeclaring === 'number' ? rtm.declaredScope.unreachableDeclaring : 0,
     };
 }
 const live = new Map();

package/dist/holmes/server/dashboard.js

@@ -58,6 +58,8 @@ const cfg_view_1 = require("./cfg-view");
 const link_census_1 = require("../rtm/link-census");
 const test_scope_1 = require("../rtm/test-scope");
 const file_anchors_1 = require("../rtm/file-anchors");
+const declared_scope_1 = require("../rtm/declared-scope");
+const test_files_1 = require("../cpg/test-files");
 /**
  * Start a lightweight standalone Node.js HTTP server for interactive dashboard & RTM visualization.
  *
@@ -130,11 +132,20 @@ async function startDashboardServer(options) {
                 }
                 const census = (0, link_census_1.linkCensus)({ approvedIds: approvedAspecs.map((s) => s.id), implemented: implementedSpecIds, testAnchors, fileAnchors, weakMentions });
                 const reasonOf = new Map(census.unlinked.map((u) => [u.id, u.reason]));
+                // @implements A-SPEC-665 — the second axis. The anchor axis above says WHERE a spec is
+                // anchored; this one says what it DECLARED, which is the only way to tell "an anchor is
+                // missing" from "there is no production file to anchor". Predicates come from the mechanisms
+                // themselves (the scan's own paths, the file-anchor predicate, the test predicate) so the two
+                // readers cannot drift apart.
+                const scannedPaths = new Set(files.map((f) => f.sourcePath));
+                const fttOf = new Map(specs.map((s) => [s.id, String(s.sections?.['Files to Touch'] ?? '')]));
+                const declaredScope = (0, declared_scope_1.declaredScopeCensus)(census.unlinked.map((u) => ({ id: u.id, ftt: fttOf.get(u.id) ?? '' })), { isScanned: (rel) => scannedPaths.has(rel), isFileAnchorable: (rel) => (0, file_anchors_1.isFileAnchorPath)(rel), isTest: (rel) => (0, test_files_1.isTestFile)(rel) });
                 const enrichedSpecs = specs.map((s) => {
                     const isA = s.id.startsWith('A-SPEC');
                     const covered = isA ? implementedSpecIds.has(s.id) : s.status === 'approved';
                     const reason = reasonOf.get(s.id);
-                    return { ...s, covered, legacyStatus: !isCanonicalStatus(s.status), ...(reason ? { unlinkedReason: reason } : {}) };
+                    const scope = declaredScope.byId[s.id];
+                    return { ...s, covered, legacyStatus: !isCanonicalStatus(s.status), ...(reason ? { unlinkedReason: reason } : {}), ...(scope ? { declaredScope: scope } : {}) };
                 });
                 // Two axes, never one number. Approval (a spec was signed off) and implementation (code is
                 // anchored to it) answer different questions, and a spec whose status is outside the
@@ -194,6 +205,8 @@ async function startDashboardServer(options) {
                     approval,
                     implementation,
                     linkCensus: census,
+                    // @implements A-SPEC-665
+                    declaredScope: { byScope: declaredScope.byScope, unreachableDeclaring: declaredScope.unreachableDeclaring },
                     unmapped,
                     nonSpec,
                     retired,

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "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",