@holmes-lab/holmes-kit 0.22.0 → 0.23.2

package/CHANGELOG.md

@@ -5,6 +5,116 @@ 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.2] - 2026-09-18
+
+Three rules that existed only in prose, and the one number a broken parser had published.
+
+### Fixed
+- **The Files-to-Touch parser reads every declared path** (A-SPEC-670). It took only the **first word
+  of a list item**, so measured over all 678 approved specs here, **88 specs declared 172 paths that
+  were never read** — 24 of them parsed to zero while naming files plainly. Five forms accounted for
+  every miss: several paths on one line (71), an indented continuation line (39), the second path on a
+  line whose first was read (32), a Korean first word (22), and a prose paragraph instead of a list (5).
+  A slashed path is now read wherever it sits; a bare `name.ext` keeps the old position rule, because
+  the root-file predicate accepts any extension and without it `module.exports` and a prose `b.ts`
+  become declared files. A declared path that does not exist but is the suffix of exactly one
+  repository file is reported as `abbreviated` rather than a defect (measured: unique in all 8 cases),
+  and two candidates stays an ambiguity where nothing is guessed. Cost over the whole corpus: **zero**
+  new `missing` findings, zero new `moved`, 26 abbreviations resolved.
+- **A number 0.23.0 published was the parser's, not the corpus's** (A-SPEC-665, corrected). The
+  declaration census read `scanned-source 0 / no-declaration 4` for this repository's 52 unlinked
+  specs, and the README said the remaining 8.1% of `codeLinkedPct` was therefore not a missing anchor.
+  With the parser fixed the same census reads **3 and 0**: `A-SPEC-495`, `A-SPEC-549.3` and
+  `A-SPEC-549.4` declare scanned production files that carry no anchor, and **five real trace gaps**
+  were behind them. The 665 chain was unsealed leaf-first and corrected, and its pin no longer names
+  spec ids — pinning those ids pinned the defect. Its own rule ("assert the sum and the property, not
+  the numbers") is what kept the fix from looking like a violation.
+- **The shipped instruction says how a spec body is written** (A-SPEC-671). `init` wrote into every
+  consumer's `AGENTS.md` that specs are authored with four MCP tools, and **none of the 44 tools takes
+  section text**. Authoring here means editing the scaffolded markdown, which the same rule read as
+  forbidden — and the collision is guaranteed, not occasional: of the four documents `spec_slice_init`
+  scaffolds, exactly one section is left blank (the REQ's `Success Criteria`) and that blank is
+  precisely what approval refuses. An agent in another workspace hit this, refused to break the rule,
+  and asked for a tool that does not exist; its judgement was correct. Rule 1 now separates the two
+  acts the tools perform (**scaffold** and **seal**), states that a body is written by editing the
+  generated markdown, and says the Success Criteria is empty on purpose. The empty-criteria refusal
+  now names the file and the heading. No new tool and no loosened gate: taking bodies as tool
+  arguments is a worse authoring surface, and auto-filling the stub would restore the pass nobody
+  earned that A-SPEC-505.1 exists to prevent.
+
+### Added
+- **The publish gate reads the docs** (A-SPEC-669). `playbooks/publish/PLAYBOOK.md` step 2.5 has
+  demanded a documentation pass since 0.16.0 with nothing enforcing it, and it failed four times —
+  0.16.0, and 0.21.0/0.22.0/0.23.0, which shipped with the README feature list stuck at 0.20.0.
+  `verify-release.js` now refuses a missing CHANGELOG entry for the version being published, and an
+  entry carrying `### Added` while `README.md` has not changed since the previous release. Validated
+  against eight releases before it was written: it refuses exactly 0.21.0, 0.22.0 and 0.23.0 and
+  passes the other five. Uncited sealed specs and version-pinned README headings are **reported only**
+  — measured poor gates, since 0.20.0 cited none of its 57 sealed specs and was an honest release. The
+  drift question (is the old wording still true?) is judgement and is deliberately not automated: a
+  machine imitating it would produce a pass nobody earned, which is the 0.16.0 incident itself. With no
+  previous tag the README rule is **skipped and says so**.
+
+## [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,16 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 📐 **Declarations are read as written** *(new in 0.23.2)*: `Files to Touch` is where a spec declares the files it will touch, and three things read it — fulfilment advisories, the declaration census and the approval impact note. The parser took only the **first word of a list item**, so measured over 678 approved specs here, **88 specs and 172 paths were declared and never read**; 24 of them parsed to zero while naming files plainly. Several paths on one line, an indented continuation, a Korean first word, a prose paragraph — all invisible. They are read now, wherever they sit, and a bare `name.ext` keeps its old position rule so a property access like `module.exports` is still not a file. A declared path that does not exist but is the suffix of exactly one repository file is reported as an abbreviation rather than a defect; two candidates stays an ambiguity and nothing is guessed. Cost, measured across the whole corpus: **zero** new `missing` findings.
+- 📄 **The publish gate reads the docs** *(new in 0.23.2)*: the publish playbook has demanded "bring README and CHANGELOG up to this release" since 0.16.0 and only prose enforced it, so it failed four times — including 0.21.0, 0.22.0 and 0.23.0, which each shipped with a feature list frozen at 0.20.0. The release gate now refuses two things it can decide: a missing CHANGELOG entry for the version being published, and an entry with `### Added` while `README.md` has not changed since the previous release. Replayed over eight releases it refuses exactly the three that were stale and passes the other five. What needs judgement — is the old wording still true? — stays with the person and is **reported**, never faked; a check that could not run says so instead of reading as a pass.
+- 🧩 **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, corrected in 0.23.2)*: 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. Bucket names state the fact; whether one is a defect stays `traceGaps`'s answer. **0.23.0 published a wrong number here**: it read "of 52 unlinked specs, zero declare a file the scanner parses, so the remaining 8.1% is not a missing anchor". That zero was the Files-to-Touch parser's, not the corpus's — see the 0.23.2 entry. The same census now reads three, and five real trace gaps were behind it.
+- 🤖 **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
+86f8d89c-mu6hz0ua

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

@@ -70,6 +70,7 @@ export declare function shortPathIfSpaced(p: string): string;
  * space, or win32 where 8.3 resolved it).
  */
 export declare function antigravityHookWarnings(packageRoot: string): string[];
+export declare const AGENTS_MD: (enforced: boolean) => string;
 export declare const MANAGED_BEGIN = "<!-- holmes-kit:managed:begin -->";
 export declare const MANAGED_END = "<!-- holmes-kit:managed:end -->";
 /**
@@ -98,6 +99,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

@@ -33,11 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MANAGED_END = exports.MANAGED_BEGIN = exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
+exports.MANAGED_END = exports.MANAGED_BEGIN = exports.AGENTS_MD = exports.CODEX_MARKETPLACE = exports.CODEX_PLUGIN_DIR = exports.HARNESS_ENFORCES = exports.AGENTS = void 0;
 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
@@ -197,7 +201,9 @@ This repository operates under **No Spec, No Code** governance. An approved spec
 
 1. **Tool-First Principle (NO Workaround Scripts)**:
    - Creating or mutating \`.ax/specs\` or governance ledgers via arbitrary temporary scripts (\`/tmp/*.js\`) is strictly forbidden.
-   - Use only \`spec_slice_init\`, \`spec_slice_approve\`, \`spec_create\`, and \`spec_approve\` MCP tools to author and seal specs.
+   - \`spec_slice_init\` and \`spec_create\` SCAFFOLD spec documents; \`spec_slice_approve\` and \`spec_approve\` SEAL them. Use these tools for those two acts — never a script.
+   - **Writing the body is editing the file.** After scaffolding, fill the \`TODO\` placeholders by editing the generated spec markdown in \`.ax/specs/\` with your normal editor. This is the expected authoring path, not a workaround — no MCP tool takes section text.
+   - A REQ's \`## Success Criteria\` is scaffolded EMPTY on purpose, because a generator must not invent what "satisfied" means. Approval is refused until you write observable criteria there.
 
 2. **Anchor-First Principle (Mandatory Code Anchors)**:
    - When creating or modifying source code and test files, line 1 MUST include an explicit anchor comment: \`// @\` + \`implements A-SPEC-XXX\`.
@@ -208,7 +214,7 @@ This repository operates under **No Spec, No Code** governance. An approved spec
 
 ## Procedure
 
-1. Run \`spec_slice_init\` or \`spec_create\` to author REQ -> H-SPEC -> A-SPEC.
+1. Run \`spec_slice_init\` or \`spec_create\` to scaffold REQ -> H-SPEC -> A-SPEC, then edit the generated markdown to replace every \`TODO\` and to write the REQ's Success Criteria.
 2. Approve specs via \`spec_slice_approve\` or \`spec_approve\`.
 3. **Before editing source**, run \`maintenance_analyze({ root, request, persist: true })\` and keep the digest it returns — that persisted analysis is what the pre-edit evidence gate checks.
 4. **Write tests first** and verify failure (RED stage).
@@ -223,6 +229,7 @@ ${enforced
     ? `Gates are **enforced**. Tool calls that write un-anchored code or target unapproved specifications will be denied. Unresolved critical findings block completion.`
     : `This harness does not have measured **hook enforcement points**. Holmes-Kit provides tools and guidance here without active gate blocking.`}
 `;
+exports.AGENTS_MD = AGENTS_MD;
 exports.MANAGED_BEGIN = '<!-- holmes-kit:managed:begin -->';
 exports.MANAGED_END = '<!-- holmes-kit:managed:end -->';
 const PRESERVED_NOTE = '<!-- kept from this file by holmes-kit init — holmes-kit does not write below this line -->';
@@ -297,12 +304,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) {
@@ -314,7 +418,7 @@ function agentFiles(agent, opts) {
             return [
                 { path: path.join(target, '.agents', 'hooks.json'), content: hooksJson(packageRoot) },
                 { path: path.join(target, '.agents', 'mcp_config.json'), content: mcpConfig(packageRoot, specsDir, opts.launcher) },
-                { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.antigravity) },
+                { path: path.join(target, 'AGENTS.md'), content: (0, exports.AGENTS_MD)(exports.HARNESS_ENFORCES.antigravity) },
             ];
         case 'codex':
             // @implements A-SPEC-442 (was A-SPEC-266, A-SPEC-441) — Codex plugin, at the layout Codex reads:
@@ -379,7 +483,7 @@ function agentFiles(agent, opts) {
                         },
                     }, null, 2)}\n`,
                 },
-                { path: path.join(target, 'AGENTS.md'), content: AGENTS_MD(exports.HARNESS_ENFORCES.codex) },
+                { path: path.join(target, 'AGENTS.md'), content: (0, exports.AGENTS_MD)(exports.HARNESS_ENFORCES.codex) },
             ];
         default:
             // 모르는 하네스를 조용히 건너뛰면 "배선했다"는 보고와 실제가 어긋난다.

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/rtm/ftt-fulfilment.d.ts

@@ -19,6 +19,14 @@ export interface FttFulfilment {
         path: string;
         line: string;
     }>;
+    /**
+     * @implements A-SPEC-670 — a declared path that does not exist but is the suffix of exactly ONE
+     * repository file is the same file written short, not a defect — reported, never counted as one.
+     */
+    abbreviated?: Array<{
+        path: string;
+        resolvedTo: string;
+    }>;
 }
 export interface FulfilmentRecord {
     aspec: string;
@@ -29,9 +37,22 @@ export interface FulfilmentRecord {
     replica?: string;
 }
 /**
- * List items only, first word only — the REQ-654 token rule (a slashed path or an item-shaped
- * root filename; prose is nothing). Globs and extension-less paths (directories) are not items:
- * their fulfilment is not a single file's existence.
+ * @implements A-SPEC-670
+ * Every path-shaped token in the section, wherever it sits on the line.
+ *
+ * REQ-654 read only the first word of a list item. Measured over all 678 A-SPECs on 2026-09-18,
+ * that lost 172 declared paths across 88 specs — 24 of which parsed to zero while naming files
+ * plainly, so the census called them "no declaration" and one wrong conclusion was published from
+ * it. Five forms accounted for every miss: several paths on one line, an indented continuation
+ * line, the second path on a line whose first was read, a Korean first word, and a prose paragraph
+ * written instead of a list.
+ *
+ * The widened rule is safe because of WHERE it reads: this is the Files-to-Touch section, whose
+ * whole purpose is declaration. One line in the entire corpus carries a negation word, and the path
+ * on it is a declaration too — so there is no measured population of "mentioned but not declared".
+ *
+ * What REQ-654 excluded stays excluded, for its original reason: globs and extension-less paths
+ * (directories) are not items, because their fulfilment is not one file's existence.
  */
 export declare function fttItems(fttText: string): FttItem[];
 export declare function fttFulfilment(fttText: string, exists: (rel: string) => boolean, locate: (basename: string) => string[]): FttFulfilment | null;

package/dist/holmes/rtm/ftt-fulfilment.js

@@ -57,30 +57,62 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const scope_judgment_1 = require("../guardrail/scope-judgment");
 const replica_id_1 = require("../governance/replica-id");
-const ITEM_RE = /^\s*[-*]\s+(.*)$/;
 const NEW_RE = /\((신규|new)\)/i;
 const ALT_RE = /또는|\bor\b/;
 const SLASHED = /^[\w@.-]+(?:\/[\w@.-]+)+$/;
 const HAS_EXT = /\.[A-Za-z][A-Za-z0-9]*$/;
+/** Token boundaries as the corpus actually writes them: backticks, quotes, brackets, `·`, commas. */
+const TOKEN_SPLIT = /[`'"()[\]{}<>,;·、，\s]+/;
 /**
- * List items only, first word only — the REQ-654 token rule (a slashed path or an item-shaped
- * root filename; prose is nothing). Globs and extension-less paths (directories) are not items:
- * their fulfilment is not a single file's existence.
+ * @implements A-SPEC-670
+ * Every path-shaped token in the section, wherever it sits on the line.
+ *
+ * REQ-654 read only the first word of a list item. Measured over all 678 A-SPECs on 2026-09-18,
+ * that lost 172 declared paths across 88 specs — 24 of which parsed to zero while naming files
+ * plainly, so the census called them "no declaration" and one wrong conclusion was published from
+ * it. Five forms accounted for every miss: several paths on one line, an indented continuation
+ * line, the second path on a line whose first was read, a Korean first word, and a prose paragraph
+ * written instead of a list.
+ *
+ * The widened rule is safe because of WHERE it reads: this is the Files-to-Touch section, whose
+ * whole purpose is declaration. One line in the entire corpus carries a negation word, and the path
+ * on it is a declaration too — so there is no measured population of "mentioned but not declared".
+ *
+ * What REQ-654 excluded stays excluded, for its original reason: globs and extension-less paths
+ * (directories) are not items, because their fulfilment is not one file's existence.
  */
 function fttItems(fttText) {
     const out = [];
+    const seen = new Set();
     for (const raw of String(fttText ?? '').replace(/\\/g, '/').split('\n')) {
-        const m = ITEM_RE.exec(raw);
-        if (!m)
+        const isListItem = /^\s*[-*]\s+/.test(raw);
+        const line = raw.replace(/^\s*[-*]\s+/, '').trim();
+        if (line === '')
             continue;
-        const line = m[1].trim();
-        const word = (line.split(/\s+/)[0] ?? '').replace(/^[`'"]+|[`'"]+$/g, '').replace(/^`?([^`]*?)`?\(/, '$1(');
-        const token = word.replace(/\(.*$/, ''); // `src/b.ts`(new) → src/b.ts
-        if (!token || token.includes('*') || !HAS_EXT.test(token))
-            continue;
-        if (!(SLASHED.test(token) || (0, scope_judgment_1.isRootFileToken)(token)))
-            continue;
-        out.push({ path: token, line, isNew: NEW_RE.test(line), alternative: ALT_RE.test(line) });
+        const isNew = NEW_RE.test(line);
+        const alternative = ALT_RE.test(line);
+        // Splitting on backticks leaves an empty first piece for `` `a.ts` ``, so "first" counts real
+        // words, not array slots — otherwise every backticked root filename loses its position.
+        const pieces = line.split(TOKEN_SPLIT).filter((w) => w !== '');
+        for (let i = 0; i < pieces.length; i += 1) {
+            // Trailing sentence punctuation is not part of a path; a leading `./` is not part of its identity.
+            const token = pieces[i].replace(/^\.\//, '').replace(/[.,;:]+$/, '');
+            if (!token || token.includes('*') || !HAS_EXT.test(token))
+                continue;
+            // A SLASHED path is admitted wherever it sits — that is the whole point of REQ-670, and a
+            // slash makes it unmistakably a path. A bare `name.ext` is NOT: `isRootFileToken` accepts any
+            // extension, so mid-line it would swallow `module.exports` and a prose `b.ts` (both measured
+            // in A-SPEC-656's pins). Root-file tokens therefore keep REQ-654's position exactly: the first
+            // word of a LIST ITEM. Measured: dropping the list condition admitted `semanticArm.gates` from
+            // a continuation line in A-SPEC-488 — one new false "missing" across the whole corpus, and the
+            // only one. With the condition restored the widening adds 172 declarations and no new finding.
+            if (!SLASHED.test(token) && !(isListItem && i === 0 && (0, scope_judgment_1.isRootFileToken)(token)))
+                continue;
+            if (seen.has(token))
+                continue;
+            seen.add(token);
+            out.push({ path: token, line, isNew, alternative });
+        }
     }
     return out;
 }
@@ -91,6 +123,7 @@ function fttFulfilment(fttText, exists, locate) {
     const missing = [];
     const moved = [];
     const alternatives = [];
+    const abbreviated = [];
     for (const it of items) {
         if (it.alternative) {
             alternatives.push({ path: it.path, line: it.line });
@@ -100,14 +133,25 @@ function fttFulfilment(fttText, exists, locate) {
             continue;
         const base = it.path.slice(it.path.lastIndexOf('/') + 1);
         const foundAt = [...new Set(locate(base))].filter((p) => p !== it.path).sort();
+        // @implements A-SPEC-670 — `project/root.ts` beside `src/holmes/project/root.ts` is the same
+        // file written short, measured 8 times in this corpus and unique every time. Only a UNIQUE
+        // suffix match earns this: two candidates is an ambiguity, and a guess there would invent a
+        // fact. Anything else keeps its old verdict, so the rule swallows no real absence.
+        const suffixHits = foundAt.filter((p) => p.endsWith(`/${it.path}`));
+        if (suffixHits.length === 1) {
+            abbreviated.push({ path: it.path, resolvedTo: suffixHits[0] });
+            continue;
+        }
         if (foundAt.length > 0)
             moved.push({ path: it.path, foundAt });
         else
             missing.push({ path: it.path, isNew: it.isNew });
     }
-    if (missing.length === 0 && moved.length === 0 && alternatives.length === 0)
+    if (missing.length === 0 && moved.length === 0 && alternatives.length === 0 && abbreviated.length === 0)
         return null;
-    return { declared: items.length, missing, moved, alternatives };
+    // Present only when it has something to say: an always-there empty array would change the shape
+    // every existing caller and pin reads, for a fact that is not there.
+    return { declared: items.length, missing, moved, alternatives, ...(abbreviated.length > 0 ? { abbreviated } : {}) };
 }
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.ax']);
 /** One walk, then O(1) lookups. Unreadable directories are skipped, never reported as empty. */

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/dist/holmes/spec/approval-blockers.js

@@ -272,7 +272,11 @@ function unactionableCriteriaBlocker(spec) {
     const quality = (0, acceptance_quality_1.acceptanceQuality)(spec);
     if (quality === 'stated')
         return null;
+    // @implements A-SPEC-671 — the refusal now says WHERE. It named what was wrong and stopped, and on
+    // 2026-09-18 an agent in another workspace read the shipped AGENTS.md rule ("author with these
+    // four tools"), found no tool that writes a section body, and halted rather than break the rule.
+    // The section is filled by editing the file, so the refusal hands over the file and the heading.
     return quality === 'absent'
-        ? `REQ ${spec.id}의 Success Criteria가 비어 있습니다 — 관측 가능한 기준을 채운 뒤 승인하십시오`
+        ? `REQ ${spec.id}의 Success Criteria가 비어 있습니다 — \`.ax/specs/01_req/${spec.id}.md\` 의 \`## Success Criteria\` 절을 편집기로 열어 관측 가능한 기준을 채운 뒤 승인하십시오`
         : `REQ ${spec.id}의 Success Criteria가 전량 보일러플레이트입니다('구현·테스트 완료'는 충족 정의가 아닙니다) — 각 항목이 검증 동사·측정 대상을 갖게 고친 뒤 승인하십시오`;
 }

package/package.json

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