@holmes-lab/holmes-kit 0.26.1 → 0.26.2

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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

package/README.md

@@ -16,6 +16,7 @@
 
 ### 🛡️ 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.

package/dist/.build-id

@@ -1 +1 @@
-256f1396-mu9du216
+29f20e72-mu9gw8dl

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,6 +65,19 @@ 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;
@@ -79,13 +93,13 @@ export declare function createSpecLifecycleHandlers(context: SpecLifecycleContex
     } | {
         ok: boolean;
         dryRun: boolean;
-        plan: import("../../spec/renumber").RenumberPlan;
+        plan: RenumberPlan;
         movedSpecs?: undefined;
     } | {
         ok: boolean;
         dryRun: boolean;
         movedSpecs: number;
-        plan: import("../../spec/renumber").RenumberPlan;
+        plan: RenumberPlan;
     }>;
     /**
      * @implements A-SPEC-538.1

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

@@ -47,8 +47,148 @@ const ledger_store_1 = require("../../governance/ledger-store");
 const provenance_chain_1 = require("../../governance/provenance-chain");
 const approval_grants_1 = require("../../governance/approval-grants");
 const renumber_1 = require("../../spec/renumber");
+const id_collision_1 = require("../../spec/id-collision");
+const remote_spec_refs_1 = require("../../spec/remote-spec-refs");
 function createSpecLifecycleHandlers(context) {
     const { store, resolveLedgerRoot } = context;
+    const renumberRun = (specsRoot, a, journaled) => {
+        try {
+            if ((0, entity_store_1.inspectEntityStore)(specsRoot).state === 'active')
+                return { ok: false, reason: 'An activated store requires entity_renumber to preserve entity UUIDs and references; raw legacy renumber is unavailable.' };
+        }
+        catch (error) {
+            // Unmarked legacy file stores retain the existing API. Corrupt or pending entity state never falls back.
+            if (!(error instanceof entity_transaction_1.EntityStoreError) || error.code !== 'missing-workspace') {
+                if (error instanceof entity_transaction_1.EntityStoreError)
+                    return { ok: false, reason: error.message };
+                throw error;
+            }
+        }
+        const projectRoot = path.resolve(specsRoot, '..', '..');
+        const read = (0, renumber_1.readSpecsForRenumber)(specsRoot);
+        const plan = (0, renumber_1.planRenumber)({
+            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
+                    + ` (읽은 스펙 ${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
+        // rollback journal holding the original bytes of every file it will touch, so an interrupted
+        // run is inspectable and reversible through entity_store recovery.
+        let retire;
+        const identity = journaled ? (0, workspace_identity_1.workspaceIdentity)(journaled.root) : undefined;
+        if (journaled && identity && identity.state === 'registered') {
+            const operationId = (0, node_crypto_1.randomUUID)();
+            const rel = (abs) => path.relative(journaled.root, abs).split(path.sep).join('/');
+            const touched = [...new Set([
+                    ...plan.moves.flatMap((m) => [rel(path.join(specsRoot, m.from)), rel(path.join(specsRoot, m.to))]),
+                    ...plan.dependsOn.map((d) => rel(path.join(specsRoot, d.file))),
+                    ...plan.slices.map((s) => rel(path.join(specsRoot, s.file))),
+                    ...plan.anchors.map((anchor) => rel(path.join(projectRoot, anchor.file))),
+                ])].sort();
+            const changes = touched.map((locator) => ({ locator, before: (0, entity_transaction_1.readEntityBytes)(path.join(journaled.root, locator))?.toString('base64') ?? null }));
+            const text = JSON.stringify({ schema: entity_store_1.LEGACY_RENUMBER_JOURNAL_SCHEMA, operationId, workspaceId: identity.workspaceId, storeLocator: journaled.locator, oldBase: String(a.oldBase), newBase: String(a.newBase), changes }) + '\n';
+            (0, entity_transaction_1.publishEntityRecord)(journaled.root, '.ax/state/entity-transactions/' + operationId + '/journal.json', text);
+            retire = () => (0, entity_transaction_1.retireEntityOperation)(journaled.root, operationId, journaled.locator, (0, entity_transaction_1.entityContentVersion)(text));
+        }
+        const movedSpecs = (0, renumber_1.applyRenumber)(specsRoot, { ...plan, anchors: [] });
+        (0, renumber_1.applyRenumber)(projectRoot, { ...plan, moves: [], dependsOn: [], slices: [] });
+        new ledger_store_1.FileLedgerStore(path.join(projectRoot, '.ax', 'ledger')).append({
+            ts: new Date().toISOString(),
+            actor: 'spec_renumber',
+            kind: 'spec-renumbered',
+            summary: `renumbered base ${a.oldBase} -> ${a.newBase}: ${movedSpecs} spec(s), ${plan.anchors.length} anchored file(s), ${plan.proseCandidates.length} prose candidate(s) left for a human`,
+            inputs: plan.moves.map((m) => `${m.oldId}->${m.newId}`),
+        });
+        retire?.();
+        return { ok: true, dryRun: false, movedSpecs, plan };
+    };
+    // @implements A-SPEC-700.2
+    const RECONCILE_SCHEMA = 'holmes-spec-reconcile/1';
+    /** Same refusal, same words, as `spec_renumber`: an adopted store moves ids with `entity_renumber`. */
+    const adoptedRefusal = (specsRoot) => {
+        try {
+            if ((0, entity_store_1.inspectEntityStore)(specsRoot).state === 'active')
+                return 'An activated store requires entity_renumber to preserve entity UUIDs and references; raw legacy renumber is unavailable.';
+        }
+        catch (error) {
+            if (!(error instanceof entity_transaction_1.EntityStoreError) || error.code !== 'missing-workspace') {
+                if (error instanceof entity_transaction_1.EntityStoreError)
+                    return error.message;
+                throw error;
+            }
+        }
+        return undefined;
+    };
+    /**
+     * READ-ONLY. No new judgment: the collectors, `detectIdCollisions`, `planIdReconcile` and
+     * `planRenumber` decide everything; this only chains them and names the result. `target` is derived
+     * from content alone — no clock, no nonce — so the plan a person approved can be rebuilt and compared.
+     */
+    const computeReconcile = (specsRoot) => {
+        const refused = adoptedRefusal(specsRoot);
+        if (refused !== undefined)
+            return { ok: false, reason: refused };
+        const projectRoot = path.resolve(specsRoot, '..', '..');
+        const local = (0, remote_spec_refs_1.collectLocalSpecEntries)(specsRoot);
+        const remote = (0, remote_spec_refs_1.collectRemoteAddedSpecs)(projectRoot);
+        const out = { schema: RECONCILE_SCHEMA, moves: [], unresolved: [], remoteRefs: [...remote.refs].sort(), rewrites: [], approveOrder: [], proseCandidates: [], target: '' };
+        if (remote.unavailable !== undefined)
+            out.note = remote.unavailable;
+        else {
+            const addedLocally = local.entries.filter((e) => !remote.baseFiles.has(e.file));
+            const issues = (0, id_collision_1.detectIdCollisions)([...addedLocally, ...remote.entries]).filter((i) => i.kind === 'id-collision');
+            const planned = (0, id_collision_1.planIdReconcile)((0, id_collision_1.reconcileInputsFrom)({ issues, local: local.entries, addedLocally, remote }));
+            out.moves = planned.moves;
+            out.unresolved = planned.unresolved;
+            if (planned.moves.length > 0) {
+                const read = (0, renumber_1.readSpecsForRenumber)(specsRoot);
+                const sources = (0, renumber_1.readSourcesForRenumber)(projectRoot);
+                for (const move of planned.moves) {
+                    const plan = (0, renumber_1.planRenumber)({ specs: read.specs, sources, oldBase: move.from, newBase: move.to });
+                    // One refusal refuses the WHOLE plan: a partial plan must not become a partial move.
+                    if (plan.refusal)
+                        return { ok: false, reason: `move ${move.from} → ${move.to} cannot be planned: ${plan.refusal}` };
+                    out.rewrites.push({ base: move.from, specs: plan.moves.length, dependsOn: plan.dependsOn.length, anchors: plan.anchors.reduce((n, x) => n + x.count, 0) });
+                    out.approveOrder.push(...plan.approveOrder);
+                    out.proseCandidates.push(...plan.proseCandidates);
+                }
+            }
+        }
+        // `planRenumber` knows ONE family, so an id it returned may itself be moved by a sibling move
+        // (measured: `H-SPEC-902` depending on REQ-901 came back after 902 had gone to 904). Destinations
+        // are free on both sides, so none is another move's source and one pass settles every name.
+        const settle = (id) => {
+            for (const m of out.moves) {
+                const next = id.replace(new RegExp(`-${m.from}(\\.\\d+)?$`), `-${m.to}$1`);
+                if (next !== id)
+                    return next;
+            }
+            return id;
+        };
+        const PARENT_FIRST = ['REQ', 'H-SPEC', 'A-SPEC', 'C-SPEC', 'T-SPEC'];
+        const rank = (id) => PARENT_FIRST.findIndex((k) => id.startsWith(k + '-'));
+        out.approveOrder = [...new Set(out.approveOrder.map(settle))]
+            .map((id, i) => ({ id, i })).sort((x, y) => rank(x.id) - rank(y.id) || x.i - y.i).map((x) => x.id);
+        out.target = 'spec-reconcile:sha256:' + (0, node_crypto_1.createHash)('sha256')
+            .update(JSON.stringify({ moves: out.moves, unresolved: out.unresolved, remoteRefs: out.remoteRefs, rewrites: out.rewrites })).digest('hex');
+        return { ok: true, plan: out };
+    };
     return {
         /**
          * Move a document to `outdated` — the only path there.
@@ -156,84 +296,116 @@ function createSpecLifecycleHandlers(context) {
             });
             return { ok: true, retired: true, id: a.id, dependents: dependents.map((s) => s.id) };
         },
-        // @implements A-SPEC-255 — the WIRING only. The judgment is `planRenumber`, which is pure and
-        // tested directly; this handler adds no rules of its own. Re-sealing is deliberately absent:
-        // `spec_approve` is the only sealer, so the plan reports the two ORDERS and the caller runs them.
-        // @implements A-SPEC-255 — WIRING only. The judgment lives in `planRenumber`, which is pure and
-        // tested directly; nothing here adds a rule. Re-sealing is deliberately absent: `spec_approve`
-        // is the only sealer (a second sealer becomes a second truth), so the plan reports the two
-        // ORDERS and the caller runs them. `dryRun` defaults to true — a renumber is read before it runs.
-        async spec_renumber(a) {
+        /**
+         * @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.
+         */
+        async spec_reconcile(a) {
             const specsRoot = store.specsRoot;
             if (typeof specsRoot !== 'string')
-                return { ok: false, reason: '파일 스토어에 묶인 서버에서만 리넘버할 수 있습니다.' };
-            const run = (journaled) => {
+                return { ok: false, reason: '파일 스토어에 묶인 서버에서만 번호 충돌을 수습할 수 있습니다.' };
+            if (a.operation !== 'plan' && a.operation !== 'apply')
+                return { ok: false, reason: "operation must be 'plan' or 'apply'" };
+            if (a.operation === 'plan') {
+                const computed = computeReconcile(specsRoot);
+                return computed.ok ? { ok: true, operation: 'plan', plan: computed.plan } : computed;
+            }
+            const seen = a.plan;
+            if (!seen || typeof seen !== 'object')
+                return { ok: false, reason: "apply requires `plan` — the object `operation: 'plan'` returned" };
+            if (seen.schema !== RECONCILE_SCHEMA || typeof seen.target !== 'string')
+                return { ok: false, reason: `apply requires a plan with schema ${RECONCILE_SCHEMA} and its target` };
+            const execute = (journaled) => {
+                // Recomputed INSIDE the hold: the plan that runs is the plan that was compared.
+                const computed = computeReconcile(specsRoot);
+                if (!computed.ok)
+                    return computed;
+                const plan = computed.plan;
+                if (plan.target !== seen.target)
+                    return { ok: false, code: 'plan-changed', reason: `the plan changed since it was seen (seen ${seen.target}, now ${plan.target}) — a fetch or a new spec moved it. Plan again and approve that one.`, plan };
+                if (plan.moves.length === 0)
+                    return { ok: true, operation: 'apply', moved: [], approveOrder: [], proseCandidates: [], reason: 'nothing to move' };
+                const approvalRaw = process.env.HOLMES_APPROVAL;
+                let approval;
                 try {
-                    if ((0, entity_store_1.inspectEntityStore)(specsRoot).state === 'active')
-                        return { ok: false, reason: 'An activated store requires entity_renumber to preserve entity UUIDs and references; raw legacy renumber is unavailable.' };
+                    approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
                 }
-                catch (error) {
-                    // Unmarked legacy file stores retain the existing API. Corrupt or pending entity state never falls back.
-                    if (!(error instanceof entity_transaction_1.EntityStoreError) || error.code !== 'missing-workspace') {
-                        if (error instanceof entity_transaction_1.EntityStoreError)
-                            return { ok: false, reason: error.message };
-                        throw error;
-                    }
+                catch {
+                    approval = undefined;
                 }
-                const projectRoot = path.resolve(specsRoot, '..', '..');
-                const read = (0, renumber_1.readSpecsForRenumber)(specsRoot);
-                const plan = (0, renumber_1.planRenumber)({
-                    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)
+                const action = { kind: 'config-write', target: plan.target };
+                const resolved = context.resolveHandlerApproval(a.root, approval, action, new Date().toISOString());
+                if (!resolved)
                     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 } : {}),
+                        reason: `spec_reconcile apply rewrites approved documents and source anchors — it requires one approval covering { kind: "config-write", target: "${plan.target}" }.`
+                            + context.refusalQueueHint(a.root, { ...action, why: `번호 충돌 수습: ${plan.moves.map((m) => `${m.from}→${m.to}`).join(', ')}` }),
                     };
-                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
-                // rollback journal holding the original bytes of every file it will touch, so an interrupted
-                // run is inspectable and reversible through entity_store recovery.
-                let retire;
-                const identity = journaled ? (0, workspace_identity_1.workspaceIdentity)(journaled.root) : undefined;
-                if (journaled && identity && identity.state === 'registered') {
-                    const operationId = (0, node_crypto_1.randomUUID)();
-                    const rel = (abs) => path.relative(journaled.root, abs).split(path.sep).join('/');
-                    const touched = [...new Set([
-                            ...plan.moves.flatMap((m) => [rel(path.join(specsRoot, m.from)), rel(path.join(specsRoot, m.to))]),
-                            ...plan.dependsOn.map((d) => rel(path.join(specsRoot, d.file))),
-                            ...plan.slices.map((s) => rel(path.join(specsRoot, s.file))),
-                            ...plan.anchors.map((anchor) => rel(path.join(projectRoot, anchor.file))),
-                        ])].sort();
-                    const changes = touched.map((locator) => ({ locator, before: (0, entity_transaction_1.readEntityBytes)(path.join(journaled.root, locator))?.toString('base64') ?? null }));
-                    const text = JSON.stringify({ schema: entity_store_1.LEGACY_RENUMBER_JOURNAL_SCHEMA, operationId, workspaceId: identity.workspaceId, storeLocator: journaled.locator, oldBase: String(a.oldBase), newBase: String(a.newBase), changes }) + '\n';
-                    (0, entity_transaction_1.publishEntityRecord)(journaled.root, '.ax/state/entity-transactions/' + operationId + '/journal.json', text);
-                    retire = () => (0, entity_transaction_1.retireEntityOperation)(journaled.root, operationId, journaled.locator, (0, entity_transaction_1.entityContentVersion)(text));
+                // @implements A-SPEC-245 — a grant that authorized the move is spent by it.
+                if (resolved.source === 'grant' && resolved.root && resolved.approval.nonce)
+                    (0, approval_grants_1.consumeGrantFile)(resolved.root, resolved.approval.nonce);
+                const moved = [];
+                for (const move of plan.moves) {
+                    // A throw mid-move (disk, permissions) is reported like a refusal: the caller must learn
+                    // which families DID move, or the only way to find out is to read the tree.
+                    let result;
+                    try {
+                        result = renumberRun(specsRoot, { oldBase: move.from, newBase: move.to, dryRun: false }, journaled);
+                    }
+                    catch (error) {
+                        result = { ok: false, reason: String(error instanceof Error ? error.message : error).split('\n')[0] };
+                    }
+                    // Finished moves stay finished and no longer collide, so planning again yields the rest.
+                    if (!result.ok)
+                        return { ok: false, reason: `move ${move.from} → ${move.to} stopped: ${result.reason}`, moved, remaining: plan.moves.slice(moved.length) };
+                    moved.push({ from: move.from, to: move.to, specs: result.movedSpecs ?? 0 });
                 }
-                const movedSpecs = (0, renumber_1.applyRenumber)(specsRoot, { ...plan, anchors: [] });
-                (0, renumber_1.applyRenumber)(projectRoot, { ...plan, moves: [], dependsOn: [], slices: [] });
-                new ledger_store_1.FileLedgerStore(path.join(projectRoot, '.ax', 'ledger')).append({
+                new ledger_store_1.FileLedgerStore(path.join(path.resolve(specsRoot, '..', '..'), '.ax', 'ledger')).append({
                     ts: new Date().toISOString(),
-                    actor: 'spec_renumber',
-                    kind: 'spec-renumbered',
-                    summary: `renumbered base ${a.oldBase} -> ${a.newBase}: ${movedSpecs} spec(s), ${plan.anchors.length} anchored file(s), ${plan.proseCandidates.length} prose candidate(s) left for a human`,
-                    inputs: plan.moves.map((m) => `${m.oldId}->${m.newId}`),
+                    actor: 'spec_reconcile',
+                    kind: 'spec-reconciled',
+                    summary: `reconciled ${moved.length} base(s) against ${plan.remoteRefs.join(', ')}: ${moved.map((m) => `${m.from}->${m.to}`).join(', ')}; approved by ${resolved.approval.actor ?? 'unknown'}`,
+                    inputs: [plan.target, ...moved.map((m) => `${m.from}->${m.to}`), ...plan.remoteRefs],
+                    authorization: (0, provenance_chain_1.authorizationRef)(resolved.approval.actor, resolved.approval.token),
                 });
-                retire?.();
-                return { ok: true, dryRun: false, movedSpecs, plan };
+                return { ok: true, operation: 'apply', moved, approveOrder: plan.approveOrder, proseCandidates: plan.proseCandidates };
             };
+            let bound;
+            try {
+                bound = (0, entity_store_1.entityStoreBinding)(specsRoot);
+            }
+            catch (error) {
+                if (error instanceof entity_transaction_1.EntityStoreError && error.code === 'missing-workspace')
+                    return execute();
+                if (error instanceof entity_transaction_1.EntityStoreError)
+                    return { ok: false, reason: error.message };
+                throw error;
+            }
+            try {
+                return (0, entity_transaction_1.withEntityStoreLock)(bound.root, bound.locator, () => execute({ root: bound.root, locator: bound.locator }));
+            }
+            catch (error) {
+                if (error instanceof entity_transaction_1.EntityStoreError)
+                    return { ok: false, reason: error.message };
+                throw error;
+            }
+        },
+        // @implements A-SPEC-255 — the WIRING only. The judgment is `planRenumber`, which is pure and
+        // tested directly; this handler adds no rules of its own. Re-sealing is deliberately absent:
+        // `spec_approve` is the only sealer, so the plan reports the two ORDERS and the caller runs them.
+        // @implements A-SPEC-255 — WIRING only. The judgment lives in `planRenumber`, which is pure and
+        // tested directly; nothing here adds a rule. Re-sealing is deliberately absent: `spec_approve`
+        // is the only sealer (a second sealer becomes a second truth), so the plan reports the two
+        // ORDERS and the caller runs them. `dryRun` defaults to true — a renumber is read before it runs.
+        async spec_renumber(a) {
+            const specsRoot = store.specsRoot;
+            if (typeof specsRoot !== 'string')
+                return { ok: false, reason: '파일 스토어에 묶인 서버에서만 리넘버할 수 있습니다.' };
+            const run = (journaled) => renumberRun(specsRoot, a, journaled);
             if (a.dryRun !== false)
                 return run();
             let bound;

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

@@ -395,6 +395,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         pending?: undefined;
         code?: undefined;
     }>;
+    spec_reconcile: (a: {
+        root?: string;
+        operation?: string;
+        plan?: unknown;
+    }) => Promise<Record<string, unknown>>;
     rtm_impact: (a: {
         root: string;
         changed: string[];

package/dist/holmes/mcp/handlers.js

@@ -930,6 +930,8 @@ function makeRawHandlers(store, opts) {
         // citation_pin+4, phase_check+3, cpg_scan+3, taint_scan..issue_localize, test_run+3, issue_localize+3,
         // rtm_impact+4, rtm_reindex..review_record, review_prepare..risk_check, risk_check±, and the tail).
         ledger_reconcile: operatorInspection.ledger_reconcile,
+        // @implements A-SPEC-700.2 — same unpinned slot: `spec_retire..spec_unseal` is a pinned run.
+        spec_reconcile: specLifecycle.spec_reconcile,
         rtm_impact: graphOperations.rtm_impact,
         rtm_reindex: graphOperations.rtm_reindex,
         context_bundle: reviewQueries.context_bundle,

package/dist/holmes/mcp/tool-schemas.js

@@ -145,6 +145,19 @@ exports.TOOL_SCHEMAS = {
             required: ['oldBase', 'newBase'],
         },
     },
+    // @implements A-SPEC-700.2
+    spec_reconcile: {
+        description: "Before a merge: find spec numbers this checkout ADDED that a remote-tracking ref also added with different content, plan which side moves and where, and apply that exact plan under ONE approval. `plan` is read-only and needs no network (remote-tracking refs are read as last fetched; `fetch` is yours): it returns the moves (the side NOT published yet moves; the destination is free on both sides), what each move rewrites, the documents to re-seal afterwards, prose candidates, and a `target` derived from the plan's content. `apply` takes that plan back VERBATIM, recomputes it, and refuses `plan-changed` if anything moved in between; it then requires an out-of-band approval of kind `config-write` bound to `target`, and moves each base through the same journaled path `spec_renumber` uses. It rewrites only places with a definite grammar (filenames, frontmatter `id`, `depends_on`, `slice`, source `@implements` anchors); prose is REPORTED, never substituted. It does NOT re-seal — `spec_approve` remains the only sealer; `approveOrder` is parent-first. An empty plan applies without asking anyone. An adopted (entity) store is refused: use `entity_renumber` there.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                operation: { type: 'string', enum: ['plan', 'apply'], description: 'plan = read-only; apply = execute the exact plan returned by plan.' },
+                plan: { type: 'object', description: 'apply only: the entire unchanged plan object returned by operation "plan".' },
+                root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
+            },
+            required: ['operation'],
+        },
+    },
     spec_unseal: {
         description: "The inverse of spec_approve: return ONE sealed (approved) spec to an editable `status: draft`, clearing `approved_digest` and `parent_digests` in a single ACT, and record `spec-unsealed` in the provenance ledger. Un-sealing WITHDRAWS a seal, so it requires the same out-of-band HOLMES_APPROVAL as spec_approve/spec_retire's sealed path (fail-closed): un-sealing an approved T-SPEC removes the code gate's demand, which unguarded would be an approval bypass. Refuses when an APPROVED spec depends on the target — that dependent's parent_digests would silently go stale — naming the blockers. Idempotent: un-sealing a spec that is already draft (never sealed) writes nothing and returns unsealed:false. Written only at the version this act read; a concurrent edit wins and the un-seal is refused for retry. Distinct from spec_retire (which withdraws authority to status:outdated); un-seal keeps the spec alive and editable.",
         inputSchema: {

package/dist/holmes/spec/entity-store.js

@@ -148,10 +148,8 @@ function validUuid(v) { return typeof v === 'string' && UUID.test(v); }
 function locator(v) {
     return typeof v === 'string' && v.length > 0 && !/[\\:\x00]/.test(v) && v.split('/').every(p => p.length > 0 && p !== '.' && p !== '..');
 }
-function recordJson(file) {
-    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
-    if (!bytes)
-        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'An entity record disappeared.');
+/** @implements A-SPEC-701 — the parse, shared, so a caller that already HOLDS the bytes never reads the file again. */
+function parseRecord(bytes) {
     try {
         return JSON.parse(bytes.toString('utf8'));
     }
@@ -159,6 +157,12 @@ function recordJson(file) {
         throw new entity_transaction_1.EntityStoreError('invalid-entity-state', 'Entity state contains malformed JSON.');
     }
 }
+function recordJson(file) {
+    const bytes = (0, entity_transaction_1.readEntityBytes)(file);
+    if (!bytes)
+        throw new entity_transaction_1.EntityStoreError('entity-state-changed', 'An entity record disappeared.');
+    return parseRecord(bytes);
+}
 function validateEntityAdoptionPlan(value) {
     const p = object(value, ['schema', 'operationId', 'workspaceId', 'storeId', 'storeLocator', 'entries']);
     if (p.schema !== 'holmes-entity-adoption/1' || !validUuid(p.operationId) || !validUuid(p.workspaceId) || !validUuid(p.storeId) || !locator(p.storeLocator) || !Array.isArray(p.entries))
@@ -247,9 +251,27 @@ function assertNoPending(bound) {
         const op = (0, entity_transaction_1.entityDirectory)(dir, name);
         // @implements A-SPEC-634 — a pending directory without a journal is an operation that died
         // between taking its locks and publishing; name it, do not fail on the missing record.
-        if (!(0, entity_transaction_1.readEntityBytes)(path.join(op, 'journal.json')))
+        //
+        // @implements A-SPEC-701 — the journal is read ONCE. It used to be read twice (once to see it
+        // exists, once to parse it) while `retireEntityOperation` moves the whole operation directory
+        // with a single rename — so an operation that FINISHED while this lock-free scan was looking
+        // was reported either as "interrupted before its journal existed" (retired before the first
+        // read) or as "An entity record disappeared." (retired between the two). Measured 2026-09-20 on
+        // the Linux CI: one of four racing adopters got the second, a code outside the three that race
+        // calls legal. Both refusals were safe and both were false.
+        //
+        // What separates the two causes of "no journal" is whether the DIRECTORY remains. Retirement
+        // moves it whole, so there is no ordinary path that leaves the directory and takes the journal:
+        // directory present + no journal is A-SPEC-634's dead operation and is still refused by name;
+        // directory gone is an operation that is simply no longer pending. The real write re-runs this
+        // scan under the lock, so skipping a finished operation here cannot admit a conflicting one.
+        const bytes = (0, entity_transaction_1.readEntityBytes)(path.join(op, 'journal.json'));
+        if (!bytes) {
+            if (!(0, entity_transaction_1.entityStat)(op))
+                continue;
             throw new entity_transaction_1.EntityStoreError('recovery-required', 'Operation ' + name + ' was interrupted before its journal existed; inspect entity_store recovery-plan and recover it.');
-        const raw = recordJson(path.join(op, 'journal.json'));
+        }
+        const raw = parseRecord(bytes);
         if (raw?.schema === 'holmes-entity-integration-journal/1') {
             const journal = object(raw, ['schema', 'plan', 'storeOwner', 'sourceOwner']);
             const plan = journal.plan;

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

@@ -230,5 +230,8 @@ function reconcileAdvice(plan) {
     ];
     if (parts.length === 0)
         return '';
-    return parts.join('; ') + (plan.moves.length > 0 ? '; then re-seal with spec_approve, and merge' : '');
+    // @implements A-SPEC-700.2 — name the tool that runs the whole plan under one approval. APPENDED:
+    // the per-move sentence stays, because `spec_renumber` is still how one family is moved by hand.
+    return parts.join('; ') + (plan.moves.length > 0
+        ? '; then re-seal with spec_approve, and merge (spec_reconcile plan → apply runs every move under one approval)' : '');
 }

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

@@ -14,3 +14,12 @@ export interface RemoteAddedSpecs {
 /** 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;
+/**
+ * The local half of the comparison, spelled the way the remote half is: store-relative posix path,
+ * BOM stripped, CRLF folded, `collisionKeyOf` as the identity. Regular files only — a FIFO named
+ * `*.md` blocks `open(2)` forever (doctor round-6), so the type is asked before the read.
+ */
+export declare function collectLocalSpecEntries(specsRoot: string): {
+    entries: IdCollisionEntry[];
+    skipped: number;
+};

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

@@ -1,6 +1,40 @@
 "use strict";
+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.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
+exports.collectLocalSpecEntries = collectLocalSpecEntries;
 // @implements A-SPEC-254.2
 /**
  * The merge-time half of REQ-254: which spec documents did each remote-tracking ref ADD since this
@@ -24,6 +58,8 @@ exports.collectRemoteAddedSpecs = collectRemoteAddedSpecs;
  * 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 fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const spec_parser_1 = require("./spec-parser");
 const id_collision_1 = require("./id-collision");
 const root_1 = require("../project/root");
@@ -146,3 +182,55 @@ function collectRemoteAddedSpecs(root, git = defaultGit) {
     }
     return result;
 }
+// @implements A-SPEC-700.2
+/**
+ * The local half of the comparison, spelled the way the remote half is: store-relative posix path,
+ * BOM stripped, CRLF folded, `collisionKeyOf` as the identity. Regular files only — a FIFO named
+ * `*.md` blocks `open(2)` forever (doctor round-6), so the type is asked before the read.
+ */
+function collectLocalSpecEntries(specsRoot) {
+    const entries = [];
+    let skipped = 0;
+    const walk = (dir) => {
+        let listed;
+        try {
+            listed = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            skipped++;
+            return;
+        }
+        for (const e of listed.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+                continue;
+            }
+            if (!e.name.endsWith('.md'))
+                continue;
+            if (!e.isFile()) {
+                skipped++;
+                continue;
+            }
+            try {
+                const folded = fs.readFileSync(p, 'utf8').replace(/^/, '').replace(/\r\n/g, '\n');
+                const spec = (0, spec_parser_1.parseSpec)(folded);
+                if (!spec.id) {
+                    skipped++;
+                    continue;
+                }
+                entries.push({
+                    file: path.relative(specsRoot, p).split(path.sep).join('/'),
+                    id: spec.id,
+                    approvedDigest: typeof spec.frontmatter.approved_digest === 'string' ? spec.frontmatter.approved_digest : undefined,
+                    contentDigest: (0, id_collision_1.collisionKeyOf)(folded, spec),
+                });
+            }
+            catch {
+                skipped++;
+            }
+        }
+    };
+    walk(specsRoot);
+    return { entries, skipped };
+}

package/package.json

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