@holmes-lab/holmes-kit 0.21.0 → 0.23.1

package/CHANGELOG.md

@@ -5,6 +5,118 @@ 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
+it had issued them; nothing recorded whether anyone acted. That missing half is the numerator every
+"promote this to a hard gate once we know the false-positive rate" sentence needed.
+
+### Added
+- **Advisory reaction ledger** (A-SPEC-663). Every finding — impact-advisory, anchor-density,
+  Files-to-Touch fulfilment, trace-gap, kills-unapplicable — now has a deterministic id (kind + spec +
+  canonical payload). `spec_approve` records it as `issued` and answers with `advisoryIds`; the next
+  `approval_status` re-runs the SAME finding 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]` to `spec_approve`; an id the ledger does not know comes back in
+  `dismissUnknown` rather than inventing a row. `rtm_dashboard`'s census gains `advisoryOutcomes`
+  (issued / resolved / persisted / dismissed per kind) and `approval_status` gains `advisoryHistory`.
+  Rows live in `.ax/ledger/advisory-outcomes.<replica>.jsonl` and carry ids, spec ids, outcome words and
+  commit hashes only. Queries never issue a finding the seal did not, so the observation denominator
+  stays the seal's.
+- **`kills` applicability** (A-SPEC-662). `test_run --mutate` now reports mutations that never applied
+  as `unapplied`, separately from `survivors` — measured here, all 22 `kills` entries in this repository
+  write `where` as a file path and `mutate` as prose, so the literal-replacement engine applied none of
+  them and the response still read `survivors: []`, the shape of a clean run. Sealing a T-SPEC (and
+  previewing it with `approval_status`) reports entries whose `where` literal is absent from the
+  A-SPEC's anchored production source as a `kills-unapplicable` finding. Never blocking. The
+  author-slice playbook now shows the grammar.
+- **CI matrix, minimal form** (A-SPEC-664). `scripts/ci-orb-linux.sh` runs one commit's full suite on an
+  OrbStack Linux machine and appends exactly one row to `.ax/ledger/ci-runs.<host>.jsonl` — for every
+  outcome, including the ones where the run could not judge (`clone-failed`, `install-failed`,
+  `vm-unreachable`). A watch script and a launchd agent trigger it. The Stop hook reports the matrix's
+  last word on a tracked line and `doctor` gains a `ci matrix` check, and neither ever reads a missing
+  row as green: absence is "not run". The scripts are maintainer tools and are not shipped; a workspace
+  with no `ci-runs` ledger hears nothing about the matrix at all.
+
+### Fixed
+- **Trace-gap anchors: 21 approved specs joined the graph.** Each declared a scanned production file in
+  its Files to Touch while anchoring only tests, so `rtm_impact` could not see them. Their anchors now
+  sit in the files they declared. Unlinked approved specs fell from 73 to 52 and trace gaps from 21 to
+  0; `codeLinkedPct` rose from 88.6 to 91.9. The remaining 52 declare no scanned production file — they
+  are test- and document-only specs, not gaps.
+- **The runner counted focused suites as failures.** jest reports a suite that used `test.only` with
+  status `focused`; filtering on `!== 'passed'` made five healthy suites look red in the first two
+  Linux rows. Only `failed` counts now.
+
+### Measured
+- macOS: 524 suites / 6,581 passed / 11 skipped; every slice recorded red-assertion → green; official
+  `test_run` green at each step.
+- Linux (OrbStack Ubuntu 24.04 arm64, Node 22): five recorded runs, the last one unattended via launchd.
+  The residual reds are load-dependent suites (`dashboard.test`, `entity-store-boundaries`,
+  `entity-git-snapshot`) that pass when run alone; the host was running other agents' work at the time.
+- First reaction rows in this repository: 22 trace-gap findings issued, 22 resolved by the anchor move.
+- Windows: not re-run for this release; no Windows-specific change landed.
+
 ## [0.21.0] - 2026-09-17
 
 The backlog-hardening cycle: the RTM stops claiming coverage it cannot see, sealing reports what a

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 @@
-bdbd4f85-mu4ywfad
+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,8 +38,13 @@ 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
 // @implements A-SPEC-442
 // @implements A-SPEC-193
 const path = __importStar(require("node:path"));
@@ -296,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/doctor.d.ts

@@ -171,6 +171,7 @@ export declare function wiringSpawnCheck(command: string, args: string[], timeou
  * the same honest-diagnosis lineage as the codex-wiring WARN (never a gate).
  */
 export declare function pushGateCheck(target: string): Check | null;
+export declare function ciMatrixCheck(target: string): Check | null;
 export declare function formatChecks(checks: Check[]): string;
 /**
  * Prove that EVERY wired harness can actually start a server, not merely that its file parses.

package/dist/holmes/cli/doctor.js

@@ -47,10 +47,12 @@ exports.resolveWiringPath = resolveWiringPath;
 exports.runDoctor = runDoctor;
 exports.wiringSpawnCheck = wiringSpawnCheck;
 exports.pushGateCheck = pushGateCheck;
+exports.ciMatrixCheck = ciMatrixCheck;
 exports.formatChecks = formatChecks;
 exports.wiringHandshakeChecks = wiringHandshakeChecks;
 exports.semanticTierVerdict = semanticTierVerdict;
 exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
+// @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
 // @implements A-SPEC-594
 // @implements A-SPEC-592
 // @implements A-SPEC-591
@@ -65,6 +67,7 @@ const native_deps_1 = require("./native-deps");
 const tier_1 = require("../semantic/tier");
 const probe_process_1 = require("./probe-process");
 const npx_cache_check_1 = require("./npx-cache-check");
+const ci_runs_1 = require("../project/ci-runs");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
@@ -1261,6 +1264,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         const pg = pushGateCheck(target ?? process.cwd());
         if (pg)
             checks.push(pg);
+        const ci = ciMatrixCheck(target ?? process.cwd()); // @implements A-SPEC-664
+        if (ci)
+            checks.push(ci);
     }
     if (extraChecks) {
         checks.push(...extraChecks);
@@ -1554,6 +1560,42 @@ function pushGateCheck(target) {
         return null;
     } // diagnosis must never crash doctor
 }
+// @implements A-SPEC-664
+// The CI matrix as doctor sees it: PASS only for a green row at HEAD; everything else is a WARN that
+// says exactly what the ledger says — "not run" when there is no row, the failed suites when red,
+// the infrastructure status when the run could not judge. Never a FAIL: the matrix informs.
+function ciMatrixCheck(target) {
+    try {
+        if (!fs.existsSync(path.join(target, '.ax')))
+            return null;
+        if (!(0, ci_runs_1.hasCiLedger)(target))
+            return null; // @implements A-SPEC-664 — same adoption predicate as the hook
+        const runs = (0, ci_runs_1.readCiRuns)(target);
+        let head;
+        try {
+            head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: target, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        }
+        catch {
+            head = undefined;
+        }
+        const behind = (rev) => {
+            try {
+                return Number((0, node_child_process_1.execFileSync)('git', ['rev-list', '--count', `${rev}..HEAD`], { cwd: target, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim());
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const v = (0, ci_runs_1.ciVerdict)(runs, 'linux', head, behind);
+        const detail = (0, ci_runs_1.ciStatusLine)(v);
+        if (v.state === 'green' && v.behind === 0)
+            return { name: 'ci matrix', level: 'PASS', detail };
+        return { name: 'ci matrix', level: 'WARN', detail, fix: 'Run scripts/ci-orb-linux.sh HEAD (or install the launchd agent: scripts/ci-orb-linux-install.sh)' };
+    }
+    catch {
+        return null;
+    } // diagnosis must never crash doctor
+}
 function formatChecks(checks) {
     const lines = checks.map((c) => {
         const head = `${c.level.padEnd(4)} ${c.name} — ${c.detail}`;

package/dist/holmes/cli/index.js

@@ -37,6 +37,7 @@ exports.isBrokenPipe = void 0;
 exports.packageRoot = packageRoot;
 exports.main = main;
 exports.installPipeGuard = installPipeGuard;
+// @implements A-SPEC-549.2
 // @implements A-SPEC-591, A-SPEC-626
 const cli_execution_1 = require("./cli-execution");
 // @implements A-SPEC-100.2

package/dist/holmes/cli/init.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
 exports.buildHookPlan = buildHookPlan;
 exports.runInit = runInit;
+// @implements A-SPEC-340
 // @implements A-SPEC-100.2
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -470,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/cpg/language-parser-walk.js

@@ -1,3 +1,4 @@
+// @implements A-SPEC-302
 'use strict';
 // Single source of truth for the per-language symbol/edge tree-walking
 // logic. Called from BOTH the inline (production) parse path and the

package/dist/holmes/hooks/stop.d.ts

@@ -2,7 +2,9 @@ import { PendingRequest } from '../governance/approval-queue';
 import { Spec } from '../spec/spec-parser';
 import type { TestOutcome } from '../review/test-runner';
 import { type KnownDefectJudgement } from '../rtm/known-defects';
+import { type CiVerdict } from '../project/ci-runs';
 export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
+export declare function collectCiVerdicts(root: string, now?: Date): CiVerdict[];
 /**
  * @implements A-SPEC-100.2
  * Stop-hook governance gate (Phase-2 #1: push, not pull).
@@ -31,6 +33,11 @@ export interface StopEvidence {
      * `undefined` is no signal — a walk that could not run must not read as marker-free.
      */
     knownDefects?: KnownDefectJudgement;
+    /**
+     * @implements A-SPEC-664 — what the CI matrix last said about this tree, per OS. Absent when the
+     * hook could not look; a `not-run` verdict when it looked and found no row (never silence).
+     */
+    ci?: CiVerdict[];
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

package/dist/holmes/hooks/stop.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.collectKnownDefects = collectKnownDefects;
+exports.collectCiVerdicts = collectCiVerdicts;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
 exports.dependencyReappraisals = dependencyReappraisals;
@@ -79,6 +80,7 @@ const constitution_debt_1 = require("../governance/constitution-debt");
 const root_1 = require("../project/root");
 const known_defects_1 = require("../rtm/known-defects");
 const test_files_1 = require("../cpg/test-files");
+const ci_runs_1 = require("../project/ci-runs");
 // @implements A-SPEC-660 — the I/O half of the known-defect marker: walk the workspace's test files
 // (the same directory rule and test predicate ART-4's anchor scan uses), parse each for markers,
 // judge them against the injected clock. A walk that cannot START is NO SIGNAL (undefined) — never
@@ -126,6 +128,40 @@ function collectKnownDefects(root, now) {
         return undefined;
     }
 }
+// @implements A-SPEC-664 — the I/O half of the CI line: read the ci-runs ledger, judge Linux (always)
+// and any other OS that has a row, with git measuring how far each judged commit sits behind HEAD.
+// A tree without a ledger yields a `not-run` verdict — a line, not an absence.
+function collectCiVerdicts(root, now = new Date()) {
+    void now;
+    // @implements A-SPEC-664 — a workspace that never ran the matrix hears nothing about it. Past this
+    // line the matrix IS adopted here, so a missing row is reported rather than passed over in silence.
+    if (!(0, ci_runs_1.hasCiLedger)(root))
+        return [];
+    let runs = [];
+    try {
+        runs = (0, ci_runs_1.readCiRuns)(root);
+    }
+    catch {
+        runs = [];
+    }
+    let head;
+    try {
+        head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).trim();
+    }
+    catch {
+        head = undefined;
+    }
+    const behind = (rev) => {
+        try {
+            return Number((0, node_child_process_1.execFileSync)('git', ['rev-list', '--count', `${rev}..HEAD`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).trim());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const oses = ['linux', ...[...new Set(runs.map((r) => r.os))].filter((o) => o !== 'linux').sort()];
+    return oses.map((os) => (0, ci_runs_1.ciVerdict)(runs, os, head, behind));
+}
 /**
  * @implements A-SPEC-534.4
  * ART-8 evidence (I/O half): the A-SPECs whose DIRTY source files carry an @implements anchor. git is
@@ -492,6 +528,7 @@ const TRACK_LABELS = {
     'ART-8': 'RED-first',
     'ART-2': 'code-graph cycles',
     'ART-9': 'known-defect debt',
+    'CI': 'matrix',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -557,6 +594,14 @@ function evaluateStop(specs, evidence) {
         const t = evidence.knownDefects.unexpired.map((k) => ({ article: 'ART-9', detail: `${k.file}:${k.line}: known defect "${k.reason}" until ${k.expires}` }));
         tracked = [...(tracked ?? []), ...t];
     }
+    // @implements A-SPEC-664 — the CI matrix's last word, one tracked line per OS. Never a block: a
+    // red Linux run is information for the person closing the turn, and "not run" is said out loud
+    // because the alternative — silence — reads as green (measured 2026-09-17: 136 environmental reds
+    // surfaced only because someone ran the suite by hand before a release).
+    if (evidence?.ci && evidence.ci.length > 0) {
+        const t = evidence.ci.map((v) => ({ article: 'CI', detail: (0, ci_runs_1.ciStatusLine)(v) }));
+        tracked = [...(tracked ?? []), ...t];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -1141,7 +1186,15 @@ if (require.main === module) {
             catch { /* maintenance, never a hook failure */ }
             // @implements A-SPEC-660 — the marker walk: no signal when it cannot run (never a clean verdict).
             const knownDefects = collectKnownDefects(stopProjectRoot(), new Date());
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}) });
+            // @implements A-SPEC-664 — the CI matrix line rides beside the constitution's verdict.
+            let ci;
+            try {
+                ci = collectCiVerdicts(stopProjectRoot());
+            }
+            catch {
+                ci = undefined;
+            }
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

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

@@ -15,6 +15,11 @@ export interface OperatorInspectionContext {
         reason: string;
     };
     fetchJson(url: string): Promise<any>;
+    /** A-SPEC-663 — the production scan, for the trace-gap finding (same closure test_run uses). */
+    cachedScan?(root: string, repoRoot?: string): Array<{
+        path: string;
+        implementsSpecs?: string[];
+    }>;
     /** A-SPEC-642 — the shared approval channel and queue hint, for the reconciliation act. */
     resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
         kind: string;
@@ -46,6 +51,9 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
         ok: boolean;
         reason: string;
     } | {
+        advisoryHistory?: import("../../rtm/advisory-outcomes").AdvisoryState[] | undefined;
+        advisoryIds?: Partial<Record<string, string>> | undefined;
+        killsAdvisory?: import("../../review/kills-check").KillsAdvisory | undefined;
         fttFulfilment?: import("../../rtm/ftt-fulfilment").FttFulfilment | undefined;
         graphPreview?: {
             impact?: import("../../rtm/impact-advisory").ImpactAdvisory;
@@ -162,7 +170,27 @@ export declare function createOperatorInspectionHandlers(context: OperatorInspec
         ok: boolean;
         url: string;
         running: boolean;
-        census: import("../../server/dashboard-launcher").DashboardCensusExtended;
+        census: {
+            advisoryOutcomes?: import("../../rtm/advisory-outcomes").AdvisoryCensus | undefined;
+            codeLinkedPct: number;
+            codeLinkedCount: number;
+            unlinkedCount: number;
+            unlinkedByReason: Record<import("../../rtm/link-census").UnlinkedReason, number>;
+            excluded: {
+                total: number;
+                retired: number;
+                unmapped: number;
+                nonSpec: number;
+            };
+            declaredScopeByScope: Record<import("../../rtm/declared-scope").DeclaredScope, number>;
+            unreachableDeclaringCount: number;
+            reqCount: number;
+            pipelineCount: number;
+            coveredCount: number;
+            coveragePct: number;
+            retiredCount: number;
+            findingsScanned: boolean;
+        };
         reason?: undefined;
     }>;
 };