@holmes-lab/holmes-kit 0.26.0 → 0.26.2

package/CHANGELOG.md

@@ -5,6 +5,106 @@ 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.2] - 2026-09-20
+
+The last stretch of the number-collision repair: the plan `doctor` has been printing since 0.26.1 can
+now be executed — the plan a person saw, under one approval, before the merge.
+
+### Added
+- **`spec_reconcile` — the seen plan, one approval, before the merge** (A-SPEC-700.2). 0.26.1 detected a
+  spec number another machine took and printed the plan; executing it was still a person calling
+  `spec_renumber` once per family. `spec_reconcile({operation:'plan'})` is read-only: it chains the
+  existing collectors, collision detector, planner and `planRenumber` — no new judgement — and returns
+  the moves, how many documents / `depends_on` / anchors each rewrites, the re-seal order, the prose
+  candidates, and a `target` derived from the plan's content alone (no clock, no nonce: the same state
+  plans to the same target). `apply` takes that plan back, **rebuilds it inside the store hold**, and
+  refuses `plan-changed` if it is no longer the one that was seen — a fetch in between may have given
+  the destination away. It then demands one `config-write` approval bound to `target`, and runs every
+  move through the same path `spec_renumber` uses. Found while building it: `spec_renumber`'s own apply
+  asks for **no approval at all**, although it rewrites approved documents and source anchors; this
+  tool is the first path that honours REQ-700's "one approval" constraint, and the standalone tool is
+  unchanged (a separate decision). It never seals — `spec_approve` stays the only sealer, and the order
+  is returned. Prose is reported, never rewritten. No remote, or no git, is an answer (`moves: []` with
+  a note), not a refusal. Measured cost: the tool adds ≈414 schema tokens (41 tools ≈ 10,724).
+  An adversarial pass **run, not read**: forged `moves` under a true `target` are never read (what runs
+  is the recomputed plan); a grant is spent once and a refused apply spends nothing; a second move that
+  stops reports `moved` / `remaining` and planning again yields only the rest. It found one defect,
+  fixed here: with two colliding families that depend on each other, the re-seal order named a document
+  a sibling move had already renamed.
+- `doctor`'s collision advice now ends by naming the tool: `… then re-seal with spec_approve, and merge
+  (spec_reconcile plan → apply runs every move under one approval)`.
+
+### Fixed
+- **A finished entity operation is no longer read as "interrupted" or "vanished"** (A-SPEC-701). The
+  pending-operation scan read each `journal.json` twice while retirement is a single rename, so a scan
+  racing a retirement could see the journal on the first read and not the second, and refuse
+  `recovery-required` for work that had just completed — measured as the Linux CI red on
+  `entity-store-boundaries` at a commit that changed no code. The scan reads once and skips an
+  operation whose directory has retired; the set of legal outcomes is not widened.
+
+## [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,9 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🤝 **The collision plan runs under one approval** *(new in 0.26.2)*: 0.26.1 saw a spec number another machine took and printed the plan; carrying it out was still one `spec_renumber` call per family, and that tool's apply asks for no approval although it rewrites approved documents and source anchors. `spec_reconcile` `plan` is read-only and returns the moves, what each rewrites, the re-seal order, the prose it will **not** touch, and a `target` derived from the plan's content alone. `apply` rebuilds the plan inside the store hold, refuses `plan-changed` if a fetch moved it since you looked, demands one `config-write` approval bound to that `target`, and runs every move through the path `spec_renumber` already uses. Forged `moves` are never read — what runs is the recomputed plan. It never seals: `spec_approve` stays the only sealer. No remote is an answer, not a refusal.
+- 🔢 **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
+29f20e72-mu9gw8dl

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

@@ -1,5 +1,6 @@
 import { SpecStore } from '../../spec/spec-store';
 import { Approval } from '../../guardrail/risk-gate';
+import { type RenumberPlan } from '../../spec/renumber';
 export interface SpecLifecycleContext {
     store: SpecStore;
     resolveLedgerRoot(root?: string): {
@@ -64,26 +65,41 @@ export declare function createSpecLifecycleHandlers(context: SpecLifecycleContex
         dependents: string[];
         reason?: undefined;
     }>;
+    /**
+     * @implements A-SPEC-700.2
+     * The plan a person SAW, executed under ONE approval, before the merge. `plan` reads; `apply`
+     * rebuilds the plan, refuses `plan-changed` if it is not the one that was seen, demands a
+     * `config-write` approval bound to the plan's `target`, then runs every move through the SAME
+     * path `spec_renumber` uses, inside one store hold. It never seals: `spec_approve` is the only
+     * sealer, so `approveOrder` is returned and the caller runs it.
+     */
+    spec_reconcile(a: {
+        root?: string;
+        operation?: string;
+        plan?: unknown;
+    }): Promise<Record<string, unknown>>;
     spec_renumber(a: {
         root?: string;
         oldBase: string;
         newBase: string;
         dryRun?: boolean;
     }): Promise<{
+        unreadable?: string[] | undefined;
         ok: boolean;
-        dryRun: boolean;
-        plan: import("../../spec/renumber").RenumberPlan;
-        reason?: undefined;
+        reason: string;
+        dryRun?: undefined;
+        plan?: undefined;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
-        movedSpecs: number;
-        plan: import("../../spec/renumber").RenumberPlan;
-        reason?: undefined;
+        plan: RenumberPlan;
+        movedSpecs?: undefined;
     } | {
         ok: boolean;
-        reason: string;
+        dryRun: boolean;
+        movedSpecs: number;
+        plan: RenumberPlan;
     }>;
     /**
      * @implements A-SPEC-538.1