@holmes-lab/holmes-kit 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -5,6 +5,69 @@ 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.26.1] - 2026-09-20
+
+Three judgements that were computed and reached nobody now reach a person, and a spec number another
+machine took is seen before the merge instead of after the conflict. Work from two machines: the
+Windows checkout found that the renumber tool had been dead there, and lost a slice to the collision
+that tool exists to repair.
+
+### Added
+- **A spec id another workspace took is seen BEFORE the merge** (A-SPEC-254.2, A-SPEC-700, A-SPEC-700.1).
+  `doctor --target` gains `spec id collision with remote refs`. Measured 2026-09-20: two machines
+  allocated `REQ-694` thirteen minutes apart, neither could see the other, and it surfaced only as an
+  add/add conflict after the push was refused — costing a rebuilt slice and five out-of-band
+  approvals. The check reads each remote-tracking ref **as last fetched** (no network; `fetch` stays
+  yours) and judges only documents each side **added** since they parted: a spec one side merely
+  *edited* is ordinary divergence, not a collision, so this does not cry wolf before every pull. On a
+  collision the advice is the plan, not a shrug —
+  `Before merging — move 901 → 903: spec_renumber(oldBase=901, newBase=903); then re-seal …`.
+  The side that moves is the one **not published yet** (a public number may already be cited), and
+  the destination is free on **both** sides. "Published" is judged by equal content, never by path:
+  a spec's path is derived from its number, so a colliding number is on the remote by definition.
+  No git, or no remote, is a PASS that says so.
+- **`architecture.cycleIgnore` in `ax.config.json`** (A-SPEC-694). The named exception the cycle
+  ratchet promised in 0.19 finally has a place to be written: path prefixes whose cycles are not the
+  project's to fix (vendored trees). A cycle is excepted only when **every** member lies under one;
+  one that straddles project code is still reported. `reference` does not pardon `reference-impl/`,
+  a prefix meaning "everything" is dropped, and a broken config excepts nothing. Excepted cycles stay
+  in the observation ledger, counted.
+- **The release gate says how far the GitHub README has fallen behind** (A-SPEC-696). Syncing the
+  README that npm's `homepage` points at is a playbook step that runs *after* the publish, so no gate
+  could see it — and measured 2026-09-20 it had been skipped for seventeen README-changing releases.
+  The *next* release's gate now compares the remote README with each release tag's and reports
+  `matches v0.19.3 — 17 release(s) with README changes behind`, `diverged`, or `could not check (…)`.
+  Report only: nothing in that block can refuse a release.
+
+### Fixed
+- **The cycle ratchet had never spoken to anyone** (A-SPEC-694). Since the commit that introduced it,
+  the Stop hook computed the code cycles, wrote them to the observation ledger, and then called the
+  verdict **without them** — so the `ART-2` tracked line was dead code in the product, and 0.26.0's
+  widening of the ratchet to eight language families landed on the same dead path. Every unit test
+  passed because each handed the evidence in directly; the RED for this fix runs the *built hook as a
+  process*. The line is now emitted, bounded (five cycles, five members each, the rest **counted**):
+  measured here, one vendored cycle has 46 members. Still non-blocking — the hook supplies `track`.
+- **`npm publish --dry-run` could not pass the release gate** (A-SPEC-695). npm exports
+  `npm_config_dry_run=true` to `prepublishOnly`; the gate handed it to jest; and the suite's own
+  `npx -p <tarball>` then installed nothing, so a green tree was refused as "not publishable". The
+  evidence environment now drops that one key — named, not a `npm_config_*` sweep, which would take
+  the registry and proxy settings with it.
+- **`spec_renumber` was dead on Windows** (A-SPEC-699). The frontmatter fence and the `depends_on`
+  block were LF-only and `core.autocrlf=true` makes every spec CRLF, so the tool read **zero** specs
+  and reported "nothing to move" — indistinguishable from an empty store. It now reads them, and its
+  refusal carries how many it could not read.
+- doctor's id-collision advice still read "manual until REQ-255" after REQ-255 had shipped; it names
+  `spec_renumber` now (A-SPEC-700.1).
+
+### Changed
+- Two Windows reds were the tests' own defects, not the product's (A-SPEC-697, A-SPEC-698): an
+  overlap fixture matched a `/`-joined suffix against a `path.join` path, so the refusal it exists to
+  assert had never been exercised on win32; and a supervisor teardown now retries the directory
+  removal Windows briefly holds after the owning process is gone.
+- A-SPEC-692's `breaking_change` said "tests only" while its own Files to Touch listed three product
+  handlers; corrected to `gate-behavior` and re-sealed. A-SPEC-700's chain was corrected to describe
+  a planner over the existing detector rather than a second detector.
+
 ## [0.26.0] - 2026-09-20
 
 Architecture you declare is now judged in every language the graph can follow, and the verdict

package/README.md

@@ -16,6 +16,8 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🔢 **A spec number another machine took is seen before the merge** *(new in 0.26.1)*: two checkouts allocated `REQ-694` thirteen minutes apart, neither could see the other, and it surfaced only as an add/add conflict after the push was refused — a rebuilt slice and five out-of-band approvals. `doctor --target` now reads each remote-tracking ref **as last fetched** (no network) and judges only the documents each side *added* since they parted, so a spec one side merely edited is divergence, not an alarm. On a collision the advice is the plan: `Before merging — move 901 → 903: spec_renumber(oldBase=901, newBase=903); then re-seal`. The side that moves is the one not published yet, the destination is free on both sides, and "published" means equal content — never path, because a spec's path is its number.
+- 🔁 **The cycle ratchet finally speaks — and takes a named exception** *(new in 0.26.1)*: since the commit that introduced it, the Stop hook computed the code cycles and called the verdict without them, so the `ART-2` line had never been printed; every unit test passed because each handed the evidence in directly. It is emitted now, bounded (five cycles, five members each, the rest counted — one vendored cycle here has 46 members), and `ax.config.json` gains `architecture.cycleIgnore`: prefixes for trees that are not yours to fix. A cycle is excepted only when every member lies under one, `reference` does not pardon `reference-impl/`, a broken config excepts nothing, and excepted cycles stay counted in the ledger.
 - 🧬 **Declare your architecture, in every language the graph can follow** *(new in 0.26.0)*: a C-SPEC's `## Forbidden Edges` takes a third rule kind beside `import` and `call` — `- inherits src/app -x-> ConcreteBase`, an exact match enforced at the pre-edit gate. Nothing is inferred: the rule reads the graph's `inherits` edges and never asks which class is "abstract", which is what makes it hold in Go, where interface satisfaction cannot be inferred at all. A project that already breaks the rule it wants adopts it with a **baseline that expires** — `- allow until 2026-09-27 : inherits src/legacy/a.ts -> LegacyBase`, exact on kind, file and target, never a prefix. Past its date the allowance still holds, because an expiry that blocked would turn the rule into a barrier to adoption; it is **reported** instead, carrying `(reconfirmed n since <date>)` so a twelfth renewal cannot hide.
 - 🏛️ **The architecture verdict reaches the person closing the turn** *(new in 0.26.0)*: the scan-wide judgement existed and nothing in the product called it — measured, zero consumers outside the tests — so an expired baseline was neither blocked nor seen, and a time-boxed allowance could not be told from a permanent pardon. The Stop hook now prints `ARCH` lines on the non-blocking `tracked` channel: violations no baseline covers, expired baselines with their renewal count, and **which rule kind could not be judged in which extension** (`inherits rules NOT judged in: .js, .py, .tsx`) — asked per kind, over the files a rule of that kind actually judges, because a pooled answer called a language *judged* for a rule it could not see. No rule declared, nothing said and nothing paid: the judgement shares the one scan the cycle ratchet already makes (measured here: scan 6.6 s, judgement 0.14 s).
 - ♻️ **The cycle ratchet judges every language it can resolve** *(new in 0.26.0)*: the Stop hook had re-implemented import resolution beside the graph builder's — relative specifiers only, four extensions. Measured on fixtures shaped the way each language requires: 16 import edges, 2 survived; 9 planted cycles, 1 found. It cost nothing in an all-TypeScript tree (919 edges either way), which is how it survived to 0.25, and everything in a Java, Go, Python or Rust consumer. There is now **one** resolver, consumed by both; a language whose specifiers do not resolve stays `unavailable` rather than reading as clean, and a wide Go package cycle is capped per cycle with the dropped members counted.

package/dist/.build-id

@@ -1 +1 @@
-a53bfcd1-mu95v98e
+256f1396-mu9du216

package/dist/holmes/cli/doctor.js

@@ -754,10 +754,12 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         // (id count) and stays untouched. OWN try/catch (round-1): sharing the block above meant an
         // unrelated upstream throw silently erased these checks — a failure here must surface as WARN,
         // never as a vanished line.
+        // @implements A-SPEC-254.2 — the local walk's entries, kept for the remote-ref check below. `undefined`
+        // means the walk itself failed, and then that check says so rather than judging an empty store.
+        let localIdEntries;
         try {
-            const { detectIdCollisions } = require('../spec/id-collision');
+            const { detectIdCollisions, collisionKeyOf } = require('../spec/id-collision');
             const { parseSpec } = require('../spec/spec-parser');
-            const crypto = require('node:crypto');
             const specsRoot = path.join(target, '.ax', 'specs');
             const entries = [];
             let skipped = 0; // would-be specs present but not judged — a PASS must name its reduced scope (round-1)
@@ -769,13 +771,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             // (mirrors parseSpec), per-line trailing whitespace and blank lines dropped (formatting is not
             // substance for an advisory WARN), plus the substantive frontmatter (type/title/dependsOn) via
             // JSON array serialization — no field aliasing. The SEAL digest is untouched, as before.
-            const collisionKey = (folded, spec) => {
-                const fence = /^---\n[\s\S]*?\n---\n?/.exec(folded);
-                const body = (fence ? folded.slice(fence[0].length) : folded)
-                    .split('\n').map((l) => l.trimEnd()).filter((l) => l !== '').join('\n');
-                return 'sha256:' + crypto.createHash('sha256')
-                    .update(JSON.stringify([spec.type, spec.title, [...spec.dependsOn].sort(), body])).digest('hex');
-            };
+            // @implements A-SPEC-254.2 — that key now lives in `id-collision.ts` as `collisionKeyOf`, because the
+            // remote-ref collector below must produce the SAME key for the same document. It was moved, not
+            // rewritten: the round-1..3 reasoning above still describes it.
+            const collisionKey = collisionKeyOf;
             // Symlinked directories are FOLLOWED (round-2): `Dirent.isDirectory()` is false for a dir
             // symlink, so specs behind one silently left the judgment with skipped=0 — an unqualified PASS
             // over an unexamined store. The realpath visited-set breaks symlink cycles. An UNREADABLE or
@@ -880,6 +879,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 }
             };
             collect(specsRoot);
+            localIdEntries = entries;
             // No cross-reference to `spec readability` (round-3): that walker does not follow dir
             // symlinks, so the pointer was false for symlink-reached files — doctor contradicting itself.
             const scopeNote = skipped > 0 ? ` (${skipped} outside the verdict)` : '';
@@ -889,7 +889,10 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             add('spec id preemption collision', collisions.length === 0 ? 'PASS' : 'WARN', collisions.length === 0
                 ? `No id is claimed by two different specs${scopeNote}`
                 : collisions.map((c) => `${c.id}: ${c.files.join(' ↔ ')} (${c.detail})`).join('; ') + scopeNote, collisions.length === 0 ? undefined
-                : 'Two specs preempted the same number — renumber one (manual until REQ-255) and re-seal.');
+                // @implements A-SPEC-700.1 — this line still told people to renumber BY HAND "until REQ-255" long after
+                // REQ-255 shipped, sending people to handwork the tool replaces. No plan is offered HERE:
+                // both copies sit in one store, so there is no published/unpublished side to choose by.
+                : 'Two specs preempted the same number — move one family with spec_renumber (dry-run first), then re-seal.');
             add('spec id family coexistence', families.length === 0 ? 'PASS' : 'WARN', families.length === 0
                 ? `No bare id coexists with its dot-suffix family${scopeNote}`
                 : families.map((f) => `${f.id}: ${f.files.join(', ')}`).join('; ') + scopeNote, families.length === 0 ? undefined
@@ -903,6 +906,46 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
             add('spec id preemption collision', 'WARN', `could not run the check: ${msg}`);
             add('spec id family coexistence', 'WARN', `could not run the check: ${msg}`);
         }
+        // @implements A-SPEC-254.2 — the MERGE-TIME half of REQ-254. The walk above sees this checkout
+        // only, so a number another machine took stayed invisible until git refused the push (measured
+        // 2026-09-20: REQ-694 allocated twice, thirteen minutes apart, surfacing as an add/add conflict).
+        // Judged: documents each side ADDED since it parted from a remote-tracking ref — an EDITED spec
+        // is ordinary divergence, not a collision. Refs are read as they stand (no network; `fetch` is
+        // the caller's), the PASS names the refs it looked at so a stale ref cannot read as "no collision
+        // with the remote", and no git / no remote is a PASS with its reason (REQ-128). OWN try, for the
+        // round-1 reason: a failure here must not erase the two lines above.
+        try {
+            if (localIdEntries === undefined)
+                throw new Error('the local spec walk did not complete');
+            const { detectIdCollisions } = require('../spec/id-collision');
+            const { collectRemoteAddedSpecs } = require('../spec/remote-spec-refs');
+            const remote = collectRemoteAddedSpecs(target);
+            if (remote.unavailable !== undefined) {
+                add('spec id collision with remote refs', 'PASS', remote.unavailable);
+            }
+            else {
+                const addedLocally = localIdEntries.filter((e) => !remote.baseFiles.has(e.file));
+                const found = detectIdCollisions([...addedLocally, ...remote.entries]).filter((i) => i.kind === 'id-collision');
+                // @implements A-SPEC-700.1 — the planner's first caller. WHICH number moves (the side not
+                // published yet) and WHERE (free on both sides) was decided by hand on 2026-09-20; it is a rule.
+                const { planIdReconcile, reconcileInputsFrom, reconcileAdvice } = require('../spec/id-collision');
+                const advice = found.length === 0 ? '' : reconcileAdvice(planIdReconcile(reconcileInputsFrom({ issues: found, local: localIdEntries, addedLocally, remote })));
+                // Names, bounded: a repository with dozens of stale branches must not turn one check into a
+                // paragraph. The count is always exact; the names are the first few, sorted.
+                const named = remote.refs.slice(0, 3).join(', ') + (remote.refs.length > 3 ? ` +${remote.refs.length - 3} more` : '');
+                const scope = ` (compared with ${remote.refs.length} remote-tracking ref(s) as last fetched: ${named || 'none comparable'}`
+                    + `${remote.skipped > 0 ? `; ${remote.skipped} unreadable` : ''})`;
+                add('spec id collision with remote refs', found.length === 0 ? 'PASS' : 'WARN', found.length === 0
+                    ? `No id added here was also added on a remote-tracking ref${scope}`
+                    : found.map((c) => `${c.id}: ${c.files.join(' ↔ ')}`).join('; ') + scope, found.length === 0 ? undefined
+                    : (advice !== '' ? `Before merging — ${advice}.`
+                        : 'Another workspace took the same number. Move the side that is NOT published yet with spec_renumber BEFORE merging, then re-seal.'));
+            }
+        }
+        catch (e) {
+            const msg = String(e instanceof Error ? e.message : e).split('\n')[0];
+            add('spec id collision with remote refs', 'WARN', `could not run the check: ${msg}`);
+        }
     }
     // @implements A-SPEC-176
     // `list()` drops any file it cannot parse, which is correct for a gate but leaves the author

package/dist/holmes/cli/release-docs.d.ts

@@ -25,3 +25,30 @@ export interface ProfileDriftInput {
  * is why the "current document" case is tested — a check that always speaks is not a check.
  */
 export declare function profileDriftFindings(input: ProfileDriftInput): string[];
+/**
+ * @implements A-SPEC-696
+ * Which release is the GitHub README a copy of — and how many README-changing releases has it missed?
+ *
+ * Step 6 of the publish playbook (sync the README npm's `homepage` points at) is prose, and it runs
+ * AFTER the publish, so that release's own gate can never check it. Measured 2026-09-20: the remote
+ * README was byte-identical to v0.19.0 and v0.19.3 while six release lines shipped, and nothing
+ * said so. The NEXT release's gate can see it: had the last sync happened, the remote would equal
+ * the latest tag's README.
+ *
+ * Pure — the caller does the network and the git. One sentence or `null`; `null` means there is
+ * nothing a person needs to do. A remote that could not be read is NEVER `null`: silence would read
+ * as "in step", which is exactly the silence six releases passed through.
+ *
+ * Byte comparison after folding line endings, and nothing cleverer. "Mostly the same" is not judged:
+ * a remote that matches no tag is reported as DIVERGED, not as behind, because the natural response
+ * to "behind" is an overwrite and someone may have edited the page on GitHub.
+ */
+export declare function externalReadmeLag(input: {
+    remote: string | null;
+    reason?: string;
+    /** Release tags with their README, OLDEST FIRST. */
+    tagged: ReadonlyArray<{
+        tag: string;
+        readme: string;
+    }>;
+}): string | null;

package/dist/holmes/cli/release-docs.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.repoTargetFrom = repoTargetFrom;
 exports.profileDriftFindings = profileDriftFindings;
+exports.externalReadmeLag = externalReadmeLag;
 /**
  * The GitHub target this project publishes to, read from `package.json`.
  *
@@ -66,3 +67,47 @@ function isShipped(version) {
         return false;
     return Number(m[1]) > 0 || Number(m[2]) > 0;
 }
+/**
+ * @implements A-SPEC-696
+ * Which release is the GitHub README a copy of — and how many README-changing releases has it missed?
+ *
+ * Step 6 of the publish playbook (sync the README npm's `homepage` points at) is prose, and it runs
+ * AFTER the publish, so that release's own gate can never check it. Measured 2026-09-20: the remote
+ * README was byte-identical to v0.19.0 and v0.19.3 while six release lines shipped, and nothing
+ * said so. The NEXT release's gate can see it: had the last sync happened, the remote would equal
+ * the latest tag's README.
+ *
+ * Pure — the caller does the network and the git. One sentence or `null`; `null` means there is
+ * nothing a person needs to do. A remote that could not be read is NEVER `null`: silence would read
+ * as "in step", which is exactly the silence six releases passed through.
+ *
+ * Byte comparison after folding line endings, and nothing cleverer. "Mostly the same" is not judged:
+ * a remote that matches no tag is reported as DIVERGED, not as behind, because the natural response
+ * to "behind" is an overwrite and someone may have edited the page on GitHub.
+ */
+function externalReadmeLag(input) {
+    if (input.remote === null)
+        return `could not check the GitHub README (${input.reason ?? 'unknown'})`;
+    const tagged = input.tagged ?? [];
+    if (tagged.length === 0)
+        return null;
+    // A CRLF working tree and the LF copy GitHub serves are one document (the lesson A-SPEC-692 left).
+    const fold = (text) => String(text).replace(/\r\n/g, '\n');
+    const remote = fold(input.remote);
+    // The NEWEST matching tag: v0.19.0 and v0.19.3 shared a README, and naming the older one would
+    // overstate the lag.
+    let at = -1;
+    for (let i = 0; i < tagged.length; i++)
+        if (fold(tagged[i].readme) === remote)
+            at = i;
+    if (at === -1)
+        return 'GitHub README matches no release tag — diverged, or edited on GitHub';
+    if (at === tagged.length - 1)
+        return null;
+    // Only releases that CHANGED the README count. A test-only patch release moves nothing a reader
+    // sees, and counting it would warn when there is nothing to sync.
+    const missed = tagged.slice(at + 1).filter((t) => fold(t.readme) !== remote).length;
+    if (missed === 0)
+        return null;
+    return `GitHub README matches ${tagged[at].tag} — ${missed} release(s) with README changes behind`;
+}

package/dist/holmes/config/config.d.ts

@@ -25,6 +25,17 @@ export interface AxConfig {
     storage: {
         specStore: string;
     };
+    architecture: {
+        /**
+         * @implements A-SPEC-694
+         * Areas whose code cycles are a NAMED EXCEPTION to the ART-2 ratchet — vendored trees the project
+         * cannot fix. A cycle is excepted only when EVERY member lies under one of these prefixes; one
+         * that straddles project code is still reported. Excepted cycles stay in the observation ledger,
+         * counted. It lives here, in a root file whose change passes a human, because an agent that
+         * could pardon its own violations would make the exception worthless.
+         */
+        cycleIgnore: string[];
+    };
 }
 export declare const DEFAULT_CONFIG: AxConfig;
 export declare function loadConfig(root: string): AxConfig;

package/dist/holmes/config/config.js

@@ -50,6 +50,7 @@ exports.DEFAULT_CONFIG = {
     guardrail: { enforcement: 'block', enforceHighRisk: true, overrideRequiresAdr: true, preEditEvidence: 'warn', redFirstEvidence: 'track' },
     highRiskDomains: ['@auth', '@payment'],
     storage: { specStore: 'local-markdown' },
+    architecture: { cycleIgnore: [] },
 };
 function deepMerge(base, ov) {
     if (ov == null || typeof ov !== 'object')
@@ -69,7 +70,16 @@ function loadConfig(root) {
     // Fall back to the strict DEFAULT_CONFIG (enforcement:'block') so a broken file cannot silently
     // weaken or disable governance — a bad config degrades to the safest posture, not to an exception.
     try {
-        return structuredClone(deepMerge(exports.DEFAULT_CONFIG, JSON.parse(fs.readFileSync(f, 'utf8'))));
+        const merged = structuredClone(deepMerge(exports.DEFAULT_CONFIG, JSON.parse(fs.readFileSync(f, 'utf8'))));
+        // @implements A-SPEC-694 — `deepMerge` copies a non-object override as it arrived, so
+        // `"architecture": "x"` or `"cycleIgnore": "reference"` would reach the ratchet as written. An
+        // exception list must never fail TOWARD a wider exception: anything that is not an array of
+        // strings reads as no exception at all.
+        const declared = merged.architecture?.cycleIgnore;
+        merged.architecture = {
+            cycleIgnore: Array.isArray(declared) ? declared.filter((x) => typeof x === 'string') : [],
+        };
+        return merged;
     }
     catch {
         return structuredClone(exports.DEFAULT_CONFIG);

package/dist/holmes/cpg/cycle-report.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The two ends around a judgement that was already right.
+ *
+ * `cycleRatchetViolations(current, allowed)` has honoured a named exception since A-SPEC-574.4, and
+ * the Stop hook has supplied `allowed: []` since the same day — there was nowhere to name one. And
+ * what the judgement found had no bounded way to be said: `trackedLines` joins every detail of an
+ * article into ONE line, and measured 2026-09-20 this repository carries a 46-member cycle inside a
+ * vendored tree. Wiring the evidence without these two would have printed thousands of characters a
+ * turn about code nobody here can change — "a rule that blocks adoption is not a rule, it is a
+ * barrier" (REQ-574), in its observational form.
+ *
+ * Pure, and it judges nothing: one function fills the list the judgement reads, the other renders
+ * what the judgement returned. The caps bound RENDERING only — no verdict reads them (REQ-569 S5).
+ */
+import { type Cycle, type CycleViolation } from './cycle-detect';
+/** How many cycles one ART-2 line names before it counts the rest. */
+export declare const CYCLE_LINE_CAP = 5;
+/** How many members of one cycle are named before the rest are counted. The ledger keeps them all. */
+export declare const CYCLE_LINE_MEMBERS = 5;
+/**
+ * The keys of the cycles that lie ENTIRELY inside ignored areas — what the hook supplies as `allowed`.
+ *
+ * Entirely, because a cycle that straddles project code and a vendored tree is the project's to
+ * fix: if one ignored member were enough, the declaration would become a way to hide the project's
+ * own cycles behind a neighbour.
+ */
+export declare function ignoredCycleKeys(cycles: readonly Cycle[], prefixes: readonly string[]): string[];
+/**
+ * The ratchet's violations as `tracked` details of bounded length.
+ *
+ * The wording is A-SPEC-574.4's (`code import cycle: a -> b -> a`), kept so nothing that reads it
+ * has to change. What is folded is COUNTED, per cycle and across cycles: a truncation that does not
+ * announce itself reads as the whole list. The full membership is in the observation ledger.
+ */
+export declare function cycleStatusDetails(violations: readonly CycleViolation[], scopeSuffix: string): string[];

package/dist/holmes/cpg/cycle-report.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CYCLE_LINE_MEMBERS = exports.CYCLE_LINE_CAP = void 0;
+exports.ignoredCycleKeys = ignoredCycleKeys;
+exports.cycleStatusDetails = cycleStatusDetails;
+// @implements A-SPEC-694
+/**
+ * The two ends around a judgement that was already right.
+ *
+ * `cycleRatchetViolations(current, allowed)` has honoured a named exception since A-SPEC-574.4, and
+ * the Stop hook has supplied `allowed: []` since the same day — there was nowhere to name one. And
+ * what the judgement found had no bounded way to be said: `trackedLines` joins every detail of an
+ * article into ONE line, and measured 2026-09-20 this repository carries a 46-member cycle inside a
+ * vendored tree. Wiring the evidence without these two would have printed thousands of characters a
+ * turn about code nobody here can change — "a rule that blocks adoption is not a rule, it is a
+ * barrier" (REQ-574), in its observational form.
+ *
+ * Pure, and it judges nothing: one function fills the list the judgement reads, the other renders
+ * what the judgement returned. The caps bound RENDERING only — no verdict reads them (REQ-569 S5).
+ */
+const cycle_detect_1 = require("./cycle-detect");
+/** How many cycles one ART-2 line names before it counts the rest. */
+exports.CYCLE_LINE_CAP = 5;
+/** How many members of one cycle are named before the rest are counted. The ledger keeps them all. */
+exports.CYCLE_LINE_MEMBERS = 5;
+/**
+ * A prefix as the scanner spells paths: forward slashes, no leading `./`, no trailing `/`.
+ *
+ * A prefix that normalises to nothing (`''`, `.`, `/`, `./`) means "everything" and is DROPPED. One
+ * line that switches the whole ratchet off is not an exception, it is a switch, and a switch is a
+ * different decision from the one this field records.
+ */
+function normalisePrefix(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const p = raw.replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '').replace(/^\/+/, '');
+    return p === '' || p === '.' ? null : p;
+}
+/** At a path boundary only — `reference` must not pardon `reference-impl/` (shape is not location). */
+const under = (file, prefix) => file === prefix || file.startsWith(`${prefix}/`);
+/**
+ * The keys of the cycles that lie ENTIRELY inside ignored areas — what the hook supplies as `allowed`.
+ *
+ * Entirely, because a cycle that straddles project code and a vendored tree is the project's to
+ * fix: if one ignored member were enough, the declaration would become a way to hide the project's
+ * own cycles behind a neighbour.
+ */
+function ignoredCycleKeys(cycles, prefixes) {
+    const areas = (Array.isArray(prefixes) ? prefixes : []).map(normalisePrefix).filter((p) => p !== null);
+    if (areas.length === 0)
+        return [];
+    return cycles
+        .filter((c) => c.files.length > 0 && c.files.every((f) => areas.some((a) => under(f, a))))
+        .map((c) => (0, cycle_detect_1.cycleKey)(c.files));
+}
+/**
+ * The ratchet's violations as `tracked` details of bounded length.
+ *
+ * The wording is A-SPEC-574.4's (`code import cycle: a -> b -> a`), kept so nothing that reads it
+ * has to change. What is folded is COUNTED, per cycle and across cycles: a truncation that does not
+ * announce itself reads as the whole list. The full membership is in the observation ledger.
+ */
+function cycleStatusDetails(violations, scopeSuffix) {
+    const details = violations.slice(0, exports.CYCLE_LINE_CAP).map((v) => {
+        const shown = v.files.slice(0, exports.CYCLE_LINE_MEMBERS);
+        const folded = v.files.length - shown.length;
+        const more = folded > 0 ? ` -> (+${folded} more)` : '';
+        return `code import cycle: ${shown.join(' -> ')}${more} -> ${v.files[0]}${scopeSuffix}`;
+    });
+    const foldedCycles = violations.length - exports.CYCLE_LINE_CAP;
+    if (foldedCycles > 0)
+        details.push(`… and ${foldedCycles} more import cycle(s)${scopeSuffix}`);
+    return details;
+}

package/dist/holmes/hooks/stop.js

@@ -92,6 +92,7 @@ const dist_freshness_1 = require("../project/dist-freshness");
 const analysis_currency_1 = require("../project/analysis-currency");
 const forbidden_edges_1 = require("../cpg/forbidden-edges");
 const forbidden_edge_report_1 = require("../cpg/forbidden-edge-report");
+const cycle_report_1 = require("../cpg/cycle-report");
 // @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
@@ -668,8 +669,10 @@ function evaluateStop(specs, evidence) {
     if (evidence?.cycles !== undefined && evidence.cycles.mode === 'track') {
         const scope = evidence.cycles.scope.unavailable.length > 0
             ? ` (NOT judged: ${evidence.cycles.scope.unavailable.join(', ')})` : '';
-        const t = (0, cycle_detect_1.cycleRatchetViolations)(evidence.cycles.current, evidence.cycles.allowed)
-            .map((x) => ({ article: 'ART-2', detail: `code ${x.detail}${scope}` }));
+        // @implements A-SPEC-694 — rendered through `cycleStatusDetails`, which bounds the line: every
+        // detail of an article is joined into ONE line, and a 46-member cycle was measured in this tree.
+        const t = (0, cycle_report_1.cycleStatusDetails)((0, cycle_detect_1.cycleRatchetViolations)(evidence.cycles.current, evidence.cycles.allowed), scope)
+            .map((detail) => ({ article: 'ART-2', detail }));
         if (t.length)
             tracked = [...(tracked ?? []), ...t];
     }
@@ -1299,6 +1302,14 @@ if (require.main === module) {
                 cycles = scanCodeCycles(root, sharedScan);
                 if (cycles === undefined)
                     throw new Error('cycle scan unavailable');
+                // @implements A-SPEC-694 — the named exception A-SPEC-574.4 promised finally has a source.
+                // A config that cannot be read excepts NOTHING: this list must never fail toward wider.
+                try {
+                    cycles.allowed = (0, cycle_report_1.ignoredCycleKeys)(cycles.current, (0, config_1.loadConfig)(root).architecture.cycleIgnore);
+                }
+                catch {
+                    cycles.allowed = [];
+                }
                 // @implements A-SPEC-578.1 — record the observation the promotion criterion waits on.
                 // EVERY run, including a clean one: a false-positive rate is violations over chances, and a
                 // ledger that only speaks when something is wrong keeps the numerator and drops the
@@ -1426,7 +1437,11 @@ if (require.main === module) {
             catch {
                 semantic = undefined;
             }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}) });
+            // @implements A-SPEC-694 — `cycles` rides in the evidence below. It was computed and written
+            // to the observation ledger from the founding commit on (071bbf0c) and never handed over, so
+            // the ART-2 track branch and the constitution's strict branch were dead code in the product:
+            // the ratchet had never spoken to anyone. The mode it carries is still the constant `track`.
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
             // @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/spec-lifecycle.d.ts

@@ -70,20 +70,22 @@ export declare function createSpecLifecycleHandlers(context: SpecLifecycleContex
         newBase: string;
         dryRun?: boolean;
     }): Promise<{
+        unreadable?: string[] | undefined;
+        ok: boolean;
+        reason: string;
+        dryRun?: undefined;
+        plan?: undefined;
+        movedSpecs?: undefined;
+    } | {
         ok: boolean;
         dryRun: boolean;
         plan: import("../../spec/renumber").RenumberPlan;
-        reason?: undefined;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
         movedSpecs: number;
         plan: import("../../spec/renumber").RenumberPlan;
-        reason?: undefined;
-    } | {
-        ok: boolean;
-        reason: string;
     }>;
     /**
      * @implements A-SPEC-538.1

package/dist/holmes/mcp/handlers/spec-lifecycle.js

@@ -181,13 +181,26 @@ function createSpecLifecycleHandlers(context) {
                     }
                 }
                 const projectRoot = path.resolve(specsRoot, '..', '..');
+                const read = (0, renumber_1.readSpecsForRenumber)(specsRoot);
                 const plan = (0, renumber_1.planRenumber)({
-                    specs: (0, renumber_1.readSpecsForRenumber)(specsRoot),
+                    specs: read.specs,
                     sources: (0, renumber_1.readSourcesForRenumber)(projectRoot),
                     oldBase: String(a.oldBase), newBase: String(a.newBase),
                 });
+                // @implements A-SPEC-699 — a refusal that cannot say whether the store was empty or merely
+                // unreadable sends the caller to the source. Measured 2026-09-20: this tool answered
+                // "nothing to move" while 300-odd specs sat in front of it, and the answer alone could not
+                // distinguish the two. Carry the counts, and name the files while there are few.
                 if (plan.refusal)
-                    return { ok: false, reason: plan.refusal };
+                    return {
+                        ok: false,
+                        reason: plan.refusal
+                            + ` (읽은 스펙 ${read.specs.length}개`
+                            + (read.unreadable.length > 0
+                                ? `, 프론트매터를 읽지 못한 파일 ${read.unreadable.length}개: ${read.unreadable.slice(0, 5).join(', ')}${read.unreadable.length > 5 ? ' …' : ''})`
+                                : ')'),
+                        ...(read.unreadable.length > 0 ? { unreadable: read.unreadable } : {}),
+                    };
                 if (a.dryRun !== false)
                     return { ok: true, dryRun: true, plan };
                 // @implements A-SPEC-638 — in a registered workspace the raw publication is preceded by a

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

@@ -728,20 +728,22 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         newBase: string;
         dryRun?: boolean;
     }) => Promise<{
+        unreadable?: string[] | undefined;
+        ok: boolean;
+        reason: string;
+        dryRun?: undefined;
+        plan?: undefined;
+        movedSpecs?: undefined;
+    } | {
         ok: boolean;
         dryRun: boolean;
         plan: import("../spec/renumber").RenumberPlan;
-        reason?: undefined;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
         movedSpecs: number;
         plan: import("../spec/renumber").RenumberPlan;
-        reason?: undefined;
-    } | {
-        ok: boolean;
-        reason: string;
     }>;
     spec_unseal: (a: {
         root?: string;

package/dist/holmes/project/root.js

@@ -86,7 +86,17 @@ function cleanSubprocessEnv(env = process.env) {
 // elicitation path — 9 elicitation tests red on a tree whose full suite was green, twice, and
 // identically on the previous commit. A posture is an approval channel, never a property of the code
 // under test; an evidence run must judge the same in an autonomous workspace and a human-gated one.
-const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL']);
+// @implements A-SPEC-695
+// `NPM_CONFIG_DRY_RUN` is the fourth of the same family and the first that is not ours. Measured
+// 2026-09-20: `npm publish --dry-run` — the command the publish playbook itself prescribes — exports
+// `npm_config_dry_run=true` to `prepublishOnly`; the release gate handed it to jest; and the
+// mcp-launcher suite's own `npx -p <tarball>` then installed NOTHING, so the handshake returned null
+// and the gate refused a green tree twice with "this source is not publishable". Load was suspected
+// first (load 38, the Linux CI running); the failure reproduces alone in 0.25 s with the variable set.
+// "Do nothing" is the one npm setting that contradicts what an evidence run is for. It is named, not
+// swept: a `/^npm_config_/` sweep would take the registry, the cache and the proxy with it, and a
+// suite behind a private registry would go red for a reason that has nothing to do with the tree.
+const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL', 'NPM_CONFIG_DRY_RUN']);
 function cleanTestEnv(env = process.env) {
     const cleaned = cleanSubprocessEnv(env);
     for (const k of Object.keys(cleaned)) {

package/dist/holmes/spec/id-collision.d.ts

@@ -1,3 +1,4 @@
+import type { Spec } from './spec-parser';
 /**
  * Distributed id-preemption detection (REQ-254): two disconnected workspaces each see the same local
  * max and issue the same spec number, and the collision is silent at create AND at push — the
@@ -37,3 +38,100 @@ export interface IdCollisionIssue {
     detail: string;
 }
 export declare function detectIdCollisions(entries: IdCollisionEntry[]): IdCollisionIssue[];
+/**
+ * Which colliding number moves, and where to.
+ *
+ * `detectIdCollisions` above (REQ-254) says a number is claimed twice; `spec_renumber` (REQ-255)
+ * can move a family. Nothing joined them, so doctor's advice still reads "renumber one (manual
+ * until REQ-255)" — stale, since REQ-255 shipped — and the decision fell to a person every time.
+ * Measured 2026-09-20: two machines each allocated REQ-694, and recovering it by hand cost a
+ * rebuilt slice and five out-of-band approvals.
+ *
+ * This is the rule, not the execution: it consumes the detector's issues and returns destinations.
+ * Applying them stays with `spec_renumber`, so adopting the entity store later swaps the engine
+ * without touching this.
+ */
+export interface ReconcileMove {
+    from: string;
+    to: string;
+    reason: string;
+}
+export interface ReconcileBlock {
+    base: string;
+    reason: string;
+}
+export interface ReconcilePlan {
+    moves: ReconcileMove[];
+    unresolved: ReconcileBlock[];
+}
+export interface ReconcileInput {
+    /** Output of `detectIdCollisions`; entries that are not `id-collision` are ignored. */
+    issues: readonly IdCollisionIssue[];
+    /** Every base this checkout holds. */
+    localBases: ReadonlySet<string>;
+    /** Every base the remote-tracking refs hold. */
+    remoteBases: ReadonlySet<string>;
+    /**
+     * The bases of THIS CHECKOUT that are already on the remote — not "what the remote holds".
+     *
+     * A colliding base is by definition published on the remote side, so the only open question is
+     * whether the LOCAL one is too. This input was first called `pushedBases` ("bases already
+     * published"), which reads as the remote's set; a caller filling it that way puts every collision
+     * in it and receives an empty plan, silently. A contract that makes the natural caller wrong is the
+     * defect, so the name now says whose publication it means. A base in here must not move — a public
+     * number may already be cited — and the plan says so instead of choosing.
+     */
+    localPublishedBases: ReadonlySet<string>;
+}
+/** "REQ-694" -> "694"; "T-SPEC-700.1" -> "700"; anything else has no base. */
+export declare function baseOfSpecId(id: string): string | undefined;
+export declare function planIdReconcile(input: ReconcileInput): ReconcilePlan;
+/**
+ * The collision identity of one spec document: the WHOLE BODY, canonicalised.
+ *
+ * Moved here from doctor's collection layer, unchanged, because a second collector now needs it —
+ * the one that reads remote-tracking refs. Two copies of an identity function is how the same
+ * document comes to have two keys, and then every shared spec reads as a collision.
+ *
+ * What it hashes is the record of three adversarial rounds (see doctor.ts): not a composite of
+ * parser splits (each split blind spot leaked, one at a time), but everything after the frontmatter
+ * with CRLF folded by the caller, per-line trailing whitespace and blank lines dropped, plus the
+ * substantive frontmatter (type, title, sorted depends_on) through JSON array serialisation so no
+ * field can alias another. The SEAL digest is a separate signal and is not part of this key.
+ *
+ * `folded` must already be CRLF-folded — both collectors fold exactly where they read.
+ */
+export declare function collisionKeyOf(folded: string, spec: Spec): string;
+/**
+ * The planner's inputs, derived from what the two collectors already know.
+ *
+ * `planIdReconcile` shipped with no caller. This is the first half of giving it one; it stays pure
+ * (entries in, sets out) so the rule it feeds remains assertable without a repository.
+ *
+ * THE ONE DECISION HERE is what "published" means for a LOCAL base. It cannot be "the path exists on
+ * the remote": a spec's path is derived from its number, so a colliding number has that path on the
+ * remote by definition, and reading it that way marks every collision as published on both sides —
+ * the exact misreading `localPublishedBases` was renamed to prevent (A-SPEC-700). A local document
+ * is published when some remote ref holds the SAME CONTENT at the same path.
+ */
+export declare function reconcileInputsFrom(input: {
+    issues: readonly IdCollisionIssue[];
+    /** Every local entry — all of them claim a number, whether or not they were added recently. */
+    local: readonly IdCollisionEntry[];
+    /** The local entries that were not present at a merge-base. */
+    addedLocally: readonly IdCollisionEntry[];
+    /** `collectRemoteAddedSpecs` output: `entries[].file` is `<ref>:<store-relative path>`. */
+    remote: {
+        entries: readonly IdCollisionEntry[];
+        baseFiles: ReadonlySet<string>;
+    };
+}): ReconcileInput;
+/**
+ * The plan, worded for the person who has to act on it. Empty plan → empty string, so the caller
+ * can tell "nothing to say" apart and fall back to a general sentence.
+ *
+ * The engine's name appears HERE and nowhere in the planner: `planIdReconcile` says what moves
+ * where, and only this sentence says with what — so swapping `spec_renumber` for `entity_renumber`
+ * after adoption is a one-line change to wording, not to the rule.
+ */
+export declare function reconcileAdvice(plan: ReconcilePlan): string;

package/dist/holmes/spec/id-collision.js

@@ -1,7 +1,46 @@
 "use strict";
-// @implements A-SPEC-254.1
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectIdCollisions = detectIdCollisions;
+exports.baseOfSpecId = baseOfSpecId;
+exports.planIdReconcile = planIdReconcile;
+exports.collisionKeyOf = collisionKeyOf;
+exports.reconcileInputsFrom = reconcileInputsFrom;
+exports.reconcileAdvice = reconcileAdvice;
+// @implements A-SPEC-254.1
+const crypto = __importStar(require("node:crypto"));
 // Only A-SPEC and T-SPEC may carry dot sub-numbers (the engine enforces this), so only they can
 // have a bare/dotted family split. REQ/H-SPEC ids are structurally exempt.
 const DOTTED = /^([AT]-SPEC-\d+)\.\d+$/;
@@ -84,3 +123,112 @@ function detectIdCollisions(entries) {
     }
     return issues.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.kind < b.kind ? -1 : 1));
 }
+/** "REQ-694" -> "694"; "T-SPEC-700.1" -> "700"; anything else has no base. */
+function baseOfSpecId(id) {
+    return /-(\d{3,})(?:\.\d+)?$/.exec(id)?.[1];
+}
+function planIdReconcile(input) {
+    const { issues, localBases, remoteBases, localPublishedBases } = input;
+    const bases = new Set();
+    for (const issue of issues) {
+        if (issue.kind !== 'id-collision')
+            continue;
+        const base = baseOfSpecId(issue.id);
+        if (base !== undefined)
+            bases.add(base);
+    }
+    const moves = [];
+    const unresolved = [];
+    // Destinations must clear BOTH sides, and each other: choosing from the local maximum alone walks
+    // straight into the next merge, and two collisions resolved in one pass must not land together.
+    const taken = new Set([...localBases, ...remoteBases]);
+    for (const base of [...bases].sort((a, b) => Number(a) - Number(b))) {
+        if (localPublishedBases.has(base)) {
+            unresolved.push({ base, reason: 'both sides are published; a person has to choose which one moves' });
+            continue;
+        }
+        let candidate = Number(base) + 1;
+        while (taken.has(String(candidate)))
+            candidate++;
+        const to = String(candidate);
+        taken.add(to);
+        moves.push({ from: base, to, reason: 'local base is not published yet' });
+    }
+    return { moves, unresolved };
+}
+// @implements A-SPEC-254.2
+/**
+ * The collision identity of one spec document: the WHOLE BODY, canonicalised.
+ *
+ * Moved here from doctor's collection layer, unchanged, because a second collector now needs it —
+ * the one that reads remote-tracking refs. Two copies of an identity function is how the same
+ * document comes to have two keys, and then every shared spec reads as a collision.
+ *
+ * What it hashes is the record of three adversarial rounds (see doctor.ts): not a composite of
+ * parser splits (each split blind spot leaked, one at a time), but everything after the frontmatter
+ * with CRLF folded by the caller, per-line trailing whitespace and blank lines dropped, plus the
+ * substantive frontmatter (type, title, sorted depends_on) through JSON array serialisation so no
+ * field can alias another. The SEAL digest is a separate signal and is not part of this key.
+ *
+ * `folded` must already be CRLF-folded — both collectors fold exactly where they read.
+ */
+function collisionKeyOf(folded, spec) {
+    const fence = /^---\n[\s\S]*?\n---\n?/.exec(folded);
+    const body = (fence ? folded.slice(fence[0].length) : folded)
+        .split('\n').map((l) => l.trimEnd()).filter((l) => l !== '').join('\n');
+    return 'sha256:' + crypto.createHash('sha256')
+        .update(JSON.stringify([spec.type, spec.title, [...spec.dependsOn].sort(), body])).digest('hex');
+}
+// @implements A-SPEC-700.1
+/**
+ * The planner's inputs, derived from what the two collectors already know.
+ *
+ * `planIdReconcile` shipped with no caller. This is the first half of giving it one; it stays pure
+ * (entries in, sets out) so the rule it feeds remains assertable without a repository.
+ *
+ * THE ONE DECISION HERE is what "published" means for a LOCAL base. It cannot be "the path exists on
+ * the remote": a spec's path is derived from its number, so a colliding number has that path on the
+ * remote by definition, and reading it that way marks every collision as published on both sides —
+ * the exact misreading `localPublishedBases` was renamed to prevent (A-SPEC-700). A local document
+ * is published when some remote ref holds the SAME CONTENT at the same path.
+ */
+function reconcileInputsFrom(input) {
+    const basesOf = (ids) => {
+        const out = new Set();
+        for (const id of ids) {
+            const b = baseOfSpecId(id);
+            if (b !== undefined)
+                out.add(b);
+        }
+        return out;
+    };
+    // A store-relative path names its spec id: `01_req/REQ-900.md` → `REQ-900`.
+    const idOfPath = (file) => file.slice(file.lastIndexOf('/') + 1).replace(/\.md$/, '');
+    const remotePathOf = (file) => file.slice(file.indexOf(':') + 1);
+    const remoteKeys = new Set(input.remote.entries.map((e) => `${remotePathOf(e.file)}\u0000${e.contentDigest}`));
+    const published = input.addedLocally.filter((e) => remoteKeys.has(`${e.file}\u0000${e.contentDigest}`));
+    return {
+        issues: input.issues,
+        localBases: basesOf(input.local.map((e) => e.id)),
+        remoteBases: basesOf([...[...input.remote.baseFiles].map(idOfPath), ...input.remote.entries.map((e) => e.id)]),
+        localPublishedBases: basesOf(published.map((e) => e.id)),
+    };
+}
+// @implements A-SPEC-700.1
+/**
+ * The plan, worded for the person who has to act on it. Empty plan → empty string, so the caller
+ * can tell "nothing to say" apart and fall back to a general sentence.
+ *
+ * The engine's name appears HERE and nowhere in the planner: `planIdReconcile` says what moves
+ * where, and only this sentence says with what — so swapping `spec_renumber` for `entity_renumber`
+ * after adoption is a one-line change to wording, not to the rule.
+ */
+function reconcileAdvice(plan) {
+    const parts = [
+        ...plan.moves.map((m) => `move ${m.from} → ${m.to}: spec_renumber(oldBase=${m.from}, newBase=${m.to})`),
+        ...plan.unresolved.map((u) => `${u.base}: both sides are published — a person has to choose which one moves`),
+    ];
+    if (parts.length === 0)
+        return '';
+    return parts.join('; ') + (plan.moves.length > 0 ? '; then re-seal with spec_approve, and merge' : '');
+}

package/dist/holmes/spec/remote-spec-refs.d.ts

@@ -0,0 +1,16 @@
+import { type IdCollisionEntry } from './id-collision';
+export interface RemoteAddedSpecs {
+    /** The remote-tracking refs that were compared — a PASS must be able to name what it looked at. */
+    refs: string[];
+    /** Documents each ref added since the merge-base, `file` spelled `<ref>:<store-relative path>`. */
+    entries: IdCollisionEntry[];
+    /** Store-relative spec paths already present at a merge-base: local files NOT in here are "added locally". */
+    baseFiles: Set<string>;
+    /** Blobs and refs that could not be read — a reduced scope is said, never hidden. */
+    skipped: number;
+    /** Why nothing was compared (no git, no remote-tracking ref). An answer, not a refusal (REQ-128). */
+    unavailable?: string;
+}
+/** Runs one git command and returns its stdout as a Buffer. Injectable so a failure can be staged. */
+export type GitRunner = (root: string, args: string[], input?: string) => Buffer;
+export declare function collectRemoteAddedSpecs(root: string, git?: GitRunner): RemoteAddedSpecs;

package/dist/holmes/spec/remote-spec-refs.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
+// @implements A-SPEC-254.2
+/**
+ * The merge-time half of REQ-254: which spec documents did each remote-tracking ref ADD since this
+ * checkout and that ref parted?
+ *
+ * `detectIdCollisions` shipped with doctor walking `.ax/specs` alone, so a number another machine
+ * took stayed invisible until git refused the push. Measured 2026-09-20: the Mac Studio committed
+ * REQ-694 at 11:05, a Windows checkout allocated REQ-694 at 11:18, neither could see the other, and
+ * it surfaced as an add/add conflict on `.ax/specs/01_req/REQ-694.md`. What was missing was
+ * collection, not judgement — so this module collects and judges nothing.
+ *
+ * WHY "ADDED SINCE THE MERGE-BASE" AND NOT "SAME ID, DIFFERENT CONTENT". The same spec edited on one
+ * side (a re-seal after a correction, a body that was expanded) is ordinary divergence, and calling
+ * it a collision would cry wolf before every pull. A collision is two sides taking the same NEW
+ * number without seeing each other. A spec's path is derived from its number, so that set is exactly
+ * what git would report as an add/add conflict — asked before the merge instead of after it.
+ *
+ * NO NETWORK. Remote-tracking refs are read as they stand; `fetch` is the caller's business.
+ * Detection tied to the network cannot prepare a merge offline (REQ-254: local-first).
+ *
+ * READ-ONLY. The only git subcommands are for-each-ref, merge-base, diff, ls-tree and cat-file.
+ */
+const node_child_process_1 = require("node:child_process");
+const spec_parser_1 = require("./spec-parser");
+const id_collision_1 = require("./id-collision");
+const root_1 = require("../project/root");
+const SPECS = '.ax/specs';
+const defaultGit = (root, args, input) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], {
+    input, stdio: ['pipe', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(process.env), maxBuffer: 256 * 1024 * 1024,
+});
+const lines = (buf) => buf.toString('utf8').split('\n').map((l) => l.trim()).filter((l) => l !== '');
+const storeRelative = (repoPath) => repoPath.slice(SPECS.length + 1);
+/**
+ * Parse `git cat-file --batch` output: `<sha> <type> <size>\n<bytes>\n` per object, or
+ * `<name> missing\n`. Sizes are BYTES, so this walks the Buffer — a string walk would drift on the
+ * first multi-byte character, and these documents are mostly Korean.
+ */
+function readBatch(out, count) {
+    const blobs = [];
+    let at = 0;
+    for (let i = 0; i < count && at < out.length; i++) {
+        const eol = out.indexOf(0x0a, at);
+        if (eol === -1)
+            break;
+        const header = out.subarray(at, eol).toString('utf8');
+        at = eol + 1;
+        if (header.endsWith(' missing')) {
+            blobs.push(null);
+            continue;
+        }
+        const size = Number(header.split(' ')[2]);
+        if (!Number.isFinite(size)) {
+            blobs.push(null);
+            continue;
+        }
+        blobs.push(out.subarray(at, at + size));
+        at += size + 1;
+    }
+    while (blobs.length < count)
+        blobs.push(null);
+    return blobs;
+}
+function collectRemoteAddedSpecs(root, git = defaultGit) {
+    const result = { refs: [], entries: [], baseFiles: new Set(), skipped: 0 };
+    // `--show-prefix` also tells us where the workspace sits inside the repository. A workspace that is
+    // not the repository root would need its paths re-based; that shape is reported, not guessed at.
+    let prefix;
+    try {
+        prefix = git(root, ['rev-parse', '--show-prefix']).toString('utf8').trim();
+    }
+    catch {
+        result.unavailable = 'not a git repository — nothing to compare against';
+        return result;
+    }
+    if (prefix !== '') {
+        result.unavailable = 'the workspace is not the repository root — nothing to compare against';
+        return result;
+    }
+    // `%(symref)` is non-empty for origin/HEAD: a symbolic ref names another ref, and counting it
+    // would read every document twice and inflate the ref count a PASS reports.
+    const refs = lines(git(root, ['for-each-ref', '--format=%(refname:short)%09%(symref)', 'refs/remotes']))
+        .map((l) => l.split('\t')).filter(([, symref]) => !symref).map(([name]) => name).sort();
+    if (refs.length === 0) {
+        result.unavailable = 'no remote-tracking refs — nothing to compare against';
+        return result;
+    }
+    const seenBlob = new Set();
+    for (const ref of refs) {
+        let base;
+        try {
+            base = git(root, ['merge-base', 'HEAD', ref]).toString('utf8').trim();
+        }
+        catch {
+            result.skipped++;
+            continue;
+        } // unrelated history, or no HEAD yet
+        if (base === '') {
+            result.skipped++;
+            continue;
+        }
+        result.refs.push(ref);
+        for (const p of lines(git(root, ['ls-tree', '-r', '--name-only', base, '--', SPECS]))) {
+            if (p.endsWith('.md'))
+                result.baseFiles.add(storeRelative(p));
+        }
+        const added = lines(git(root, ['diff', '--name-only', '--diff-filter=A', '--no-renames', base, ref, '--', SPECS]))
+            .filter((p) => p.endsWith('.md'));
+        if (added.length === 0)
+            continue;
+        // ONE process per ref, not one per document.
+        const blobs = readBatch(git(root, ['cat-file', '--batch'], added.map((p) => `${ref}:${p}`).join('\n') + '\n'), added.length);
+        added.forEach((repoPath, i) => {
+            const blob = blobs[i];
+            if (blob === null) {
+                result.skipped++;
+                return;
+            }
+            try {
+                // Folded exactly where doctor's local walker folds (BOM stripped, CRLF → LF), so a CRLF
+                // working-tree copy and the LF blob of the same document get the same key.
+                const folded = blob.toString('utf8').replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+                const spec = (0, spec_parser_1.parseSpec)(folded);
+                if (!spec.id) {
+                    result.skipped++;
+                    return;
+                }
+                const contentDigest = (0, id_collision_1.collisionKeyOf)(folded, spec);
+                const dedupe = `${repoPath}\u0000${contentDigest}`;
+                if (seenBlob.has(dedupe))
+                    return; // the same document reached through two refs
+                seenBlob.add(dedupe);
+                result.entries.push({
+                    file: `${ref}:${storeRelative(repoPath)}`,
+                    id: spec.id,
+                    approvedDigest: typeof spec.frontmatter.approved_digest === 'string' ? spec.frontmatter.approved_digest : undefined,
+                    contentDigest,
+                });
+            }
+            catch {
+                result.skipped++;
+            }
+        });
+    }
+    return result;
+}

package/dist/holmes/spec/renumber.d.ts

@@ -126,5 +126,15 @@ export declare function readSourcesForRenumber(projectRoot: string): {
     file: string;
     text: string;
 }[];
-/** Spec documents as the planner needs them, with store-relative POSIX paths. */
-export declare function readSpecsForRenumber(specsRoot: string): RenumberSpec[];
+/**
+ * Spec documents as the planner needs them, with store-relative POSIX paths.
+ *
+ * @implements A-SPEC-699 — `unreadable` exists because the absence of it cost a day. A `.md` whose
+ * frontmatter would not parse used to be skipped by a bare `continue`, so "this store holds no
+ * specs" and "I could not read any of these specs" reached the caller as the same answer. They are
+ * different facts and the caller has to be able to tell them apart.
+ */
+export declare function readSpecsForRenumber(specsRoot: string): {
+    specs: RenumberSpec[];
+    unreadable: string[];
+};

package/dist/holmes/spec/renumber.js

@@ -489,9 +489,17 @@ function readSourcesForRenumber(projectRoot) {
     }
     return out;
 }
-/** Spec documents as the planner needs them, with store-relative POSIX paths. */
+/**
+ * Spec documents as the planner needs them, with store-relative POSIX paths.
+ *
+ * @implements A-SPEC-699 — `unreadable` exists because the absence of it cost a day. A `.md` whose
+ * frontmatter would not parse used to be skipped by a bare `continue`, so "this store holds no
+ * specs" and "I could not read any of these specs" reached the caller as the same answer. They are
+ * different facts and the caller has to be able to tell them apart.
+ */
 function readSpecsForRenumber(specsRoot) {
     const out = [];
+    const unreadable = [];
     for (const abs of walk(specsRoot).concat((function md(dir, acc = []) {
         let entries;
         try {
@@ -511,21 +519,32 @@ function readSpecsForRenumber(specsRoot) {
     })(specsRoot))) {
         if (!abs.endsWith('.md'))
             continue;
+        const rel = path.relative(specsRoot, abs).split(path.sep).join('/');
         let text;
         try {
             text = fs.readFileSync(abs, 'utf8');
         }
         catch {
+            unreadable.push(rel);
             continue;
         }
-        const fm = /^---\n([\s\S]*?)\n---/.exec(text);
-        if (!fm)
+        // @implements A-SPEC-699 — `\r?\n`, not `\n`. A checkout with core.autocrlf=true holds every
+        // spec as CRLF, and an LF-only fence matched none of them.
+        const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+        if (!fm) {
+            unreadable.push(rel);
             continue;
+        }
         const field = (k) => (new RegExp(`^${k}:[ \\t]*(.+)$`, 'm').exec(fm[1])?.[1] ?? '').trim();
         const id = field('id');
-        if (id === '')
+        if (id === '') {
+            unreadable.push(rel);
             continue;
-        const deps = (/^depends_on:\n((?:[ \t]*-[ \t]*.+\n?)+)/m.exec(fm[1])?.[1] ?? '')
+        }
+        // @implements A-SPEC-699 — the fence is not the only LF-only site. Fixing it alone would leave
+        // this one matching nothing on CRLF, so every family would come back with no edges and both
+        // unsealOrder and approveOrder would arrive empty: the same silence, one layer down.
+        const deps = (/^depends_on:\r?\n((?:[ \t]*-[ \t]*.+\r?\n?)+)/m.exec(fm[1])?.[1] ?? '')
             .split('\n').map((l) => l.replace(/^[ \t]*-[ \t]*/, '').trim()).filter((x) => x !== '');
         const inline = /^depends_on:[ \t]*\[(.*)\]/m.exec(fm[1])?.[1];
         out.push({
@@ -536,5 +555,5 @@ function readSpecsForRenumber(specsRoot) {
             body: text,
         });
     }
-    return out;
+    return { specs: out, unreadable };
 }

package/package.json

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