@holmes-lab/holmes-kit 0.26.0 → 0.26.2

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,6 +296,104 @@ function createSpecLifecycleHandlers(context) {
             });
             return { ok: true, retired: true, id: a.id, dependents: dependents.map((s) => s.id) };
         },
+        /**
+         * @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: '파일 스토어에 묶인 서버에서만 번호 충돌을 수습할 수 있습니다.' };
+            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 {
+                    approval = approvalRaw ? JSON.parse(approvalRaw) : undefined;
+                }
+                catch {
+                    approval = undefined;
+                }
+                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: `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(', ')}` }),
+                    };
+                // @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 });
+                }
+                new ledger_store_1.FileLedgerStore(path.join(path.resolve(specsRoot, '..', '..'), '.ax', 'ledger')).append({
+                    ts: new Date().toISOString(),
+                    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),
+                });
+                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.
@@ -167,60 +405,7 @@ function createSpecLifecycleHandlers(context) {
             const specsRoot = store.specsRoot;
             if (typeof specsRoot !== 'string')
                 return { ok: false, reason: '파일 스토어에 묶인 서버에서만 리넘버할 수 있습니다.' };
-            const run = (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 plan = (0, renumber_1.planRenumber)({
-                    specs: (0, renumber_1.readSpecsForRenumber)(specsRoot),
-                    sources: (0, renumber_1.readSourcesForRenumber)(projectRoot),
-                    oldBase: String(a.oldBase), newBase: String(a.newBase),
-                });
-                if (plan.refusal)
-                    return { ok: false, reason: plan.refusal };
-                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 };
-            };
+            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[];
@@ -728,20 +733,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/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/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/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.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;