@holmes-lab/holmes-kit 0.26.1 → 0.27.0

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/rtm/traced-files.d.ts

@@ -0,0 +1,83 @@
+export interface TracedFilesInput {
+    /** What the scanner returned: repo-relative path and the spec ids the file anchors. */
+    files: readonly {
+        path: string;
+        anchors: readonly string[];
+    }[];
+    /** Ids whose status is `approved`. A draft anchor is not a trace. */
+    approvedIds: Iterable<string>;
+    /** Path prefixes that are not this project's source (vendored trees). Explicit, and echoed back. */
+    exclude?: readonly string[];
+}
+export interface TracedFiles {
+    total: number;
+    traced: number;
+    excluded: number;
+    /** Sorted. */
+    untraced: string[];
+    measurable: boolean;
+    reason?: string;
+    /** One decimal, FLOORED; `null` when not measurable. */
+    tracedPct: number | null;
+}
+export interface AttestProvenance {
+    at: string;
+    specs: string;
+    exclude: string[];
+}
+export interface AttestReport {
+    files: TracedFiles;
+    specs: {
+        total: number;
+        linked: number;
+    };
+    provenance: AttestProvenance;
+}
+export declare const ATTEST_BEGIN = "<!-- holmes-kit:attest:begin -->";
+export declare const ATTEST_END = "<!-- holmes-kit:attest:end -->";
+export declare const ATTEST_SCHEMA = "holmes-attest/1";
+/** Above this many untraced files the text names none and points at `--json`. */
+export declare const UNTRACED_LINE_CAP = 10;
+/**
+ * Backslashes folded, one trailing slash. A prefix that means "everything" is DROPPED: excluding the
+ * whole tree would read as n/a at best and 100% at worst (the same rule A-SPEC-694 pinned for
+ * `cycleIgnore`). Sorted and de-duplicated so the provenance does not depend on how it was typed.
+ */
+export declare function normalizeExcludes(raw: readonly string[] | undefined): string[];
+/** Floored to one decimal: 99.96 must not read as 100 — 100 means every file. */
+export declare function flooredPct(num: number, den: number): number | null;
+export declare function tracedFiles(input: TracedFilesInput): TracedFiles;
+/**
+ * Where and when the number is true. `+dirty` because a commit alone would call an unreproducible
+ * number reproducible. The spec digest covers (id, seal) of every approved spec — that set is what
+ * decides the numerator. No clock anywhere.
+ */
+export declare function attestProvenance(input: {
+    commit?: string;
+    dirty: boolean;
+    approved: readonly {
+        id: string;
+        digest: string;
+    }[];
+    exclude: readonly string[];
+}): AttestProvenance;
+export declare function renderAttestText(r: AttestReport): string;
+export declare function renderAttestJson(r: AttestReport): string;
+/** Self-contained: no href, font, script or fetch. Only the ratio, the percentage and `at` go in. */
+export declare function renderAttestSvg(r: AttestReport): string;
+/** What goes between the markers. Carries the excludes, so the README says how to reproduce it. */
+export declare function renderAttestMarker(r: AttestReport): string;
+/**
+ * Replace what lies between the two markers — and ONLY when each appears exactly once, begin first.
+ * No marker is `no-marker`: the person never asked, so nothing is written. Anything else malformed is
+ * `unbalanced`: a lone begin marker followed by "replace to the end" is this feature's worst failure.
+ * The README's own line ending is kept, so a CRLF file does not become one whole-file diff.
+ */
+export declare function replaceMarkerRegion(readme: string, inner: string): {
+    ok: true;
+    text: string;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: 'no-marker' | 'unbalanced';
+};