@isaacriehm/cairn-core 0.4.3 → 0.6.0

package/dist/mcp/tools/resolve-attention.js

@@ -20,12 +20,17 @@
  * | invalidation_event  | c      | abort — caller archives task (no-op here)   |
  * | drift               | a/b/c  | acknowledged (drift surface not yet active) |
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
+import { writeFileSafe } from "../../fs.js";
+import { createHash } from "node:crypto";
+import { stringify as stringifyYaml } from "yaml";
 import { parseDraftMeta, restoreDec, runDecSourceStrip, } from "../../attention/index.js";
 import { writeInvalidationEvent } from "../../events/index.js";
-import { decisionsDir } from "../../ground/index.js";
-import { writeDecisionsLedger } from "../../ground/ledgers.js";
+import { alignmentPendingDir, archivedConflictsDir, bindDec, bodyContentHash, conflictsDir, decisionsDir, deleteSotCacheEntry, deriveLedgerDecId, deriveLedgerInvId, invariantsDir, parseFrontmatterRecord, readSotBindings, readSotCache, recordDriftEvent, setSotCacheEntry, unbindDec, writeSotBindings, writeSotCache, } from "../../ground/index.js";
+import { tokenize } from "../../text/jaccard.js";
+import { applyStripReplace, formatBareCitation, } from "../../init/source-comments/index.js";
+import { writeDecisionsLedger, writeInvariantsLedger } from "../../ground/ledgers.js";
 import { clearDeferState, writeDeferState, } from "../../hooks/defer.js";
 import { withWriteLock } from "../../lock.js";
 import { logger } from "../../logger.js";
@@ -37,6 +42,12 @@ async function handler(ctx, input) {
     const block = requireBootstrap(ctx.repoRoot);
     if (block !== null)
         return block;
+    // The fourth choice slot is only meaningful for conflict resolution.
+    // Reject `d` on every other kind so the schema's permissive enum
+    // doesn't quietly fall through.
+    if (input.choice === "d" && input.kind !== "conflict") {
+        return mcpError("VALIDATION_FAILED", `choice "d" is only valid for kind=conflict, got kind=${input.kind}`);
+    }
     switch (input.kind) {
         case "decision_draft":
             return resolveDecisionDraft(ctx, input);
@@ -54,6 +65,10 @@ async function handler(ctx, input) {
             return resolveBypass(ctx, input);
         case "review":
             return resolveReview(ctx, input);
+        case "conflict":
+            return resolveConflict(ctx, input);
+        case "alignment_pending":
+            return resolveAlignmentPending(ctx, input);
     }
 }
 function resolveBypass(ctx, input) {
@@ -284,15 +299,776 @@ function resolveBaselineFinding(ctx, input) {
         };
     });
 }
+const CONFLICT_ID_RE = /^(DEC|INV)-[0-9a-f]{7,}$/;
+const CONFLICT_PAIR_RE = /^((DEC|INV)-[0-9a-f]{7,})__((DEC|INV)-[0-9a-f]{7,})$/;
+function entityRefFor(repoRoot, id) {
+    if (id.startsWith("INV-")) {
+        const abs = join(invariantsDir(repoRoot), `${id}.md`);
+        return { id, kind: "INV", abs, rel: `.cairn/ground/invariants/${id}.md` };
+    }
+    const abs = join(decisionsDir(repoRoot), `${id}.md`);
+    return { id, kind: "DEC", abs, rel: `.cairn/ground/decisions/${id}.md` };
+}
+function parseConflictFile(repoRoot, itemId) {
+    if (!CONFLICT_PAIR_RE.test(itemId))
+        return null;
+    const dir = conflictsDir(repoRoot);
+    const filename = `${itemId}.md`;
+    const abs = join(dir, filename);
+    if (!existsSync(abs))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(abs, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const { fm, body } = parseFrontmatterRecord(raw);
+    const aId = String(fm["a_id"] ?? itemId.split("__")[0] ?? "");
+    const bId = String(fm["b_id"] ?? itemId.split("__")[1] ?? "");
+    if (!CONFLICT_ID_RE.test(aId) || !CONFLICT_ID_RE.test(bId))
+        return null;
+    return {
+        abs,
+        rel: `.cairn/ground/conflicts/${filename}`,
+        filename,
+        aRef: entityRefFor(repoRoot, aId),
+        bRef: entityRefFor(repoRoot, bId),
+        fm,
+        body,
+    };
+}
+function readEntity(ref) {
+    if (!existsSync(ref.abs))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(ref.abs, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const { fm, body } = parseFrontmatterRecord(raw);
+    return { fm, body, raw };
+}
+function writeEntity(ref, fm, body) {
+    const content = `---\n${stringifyYaml(fm).trimEnd()}\n---\n${body.startsWith("\n") ? body : `\n${body}`}`;
+    writeFileSync(ref.abs, content, "utf8");
+}
+function setSupersededBy(repoRoot, loser, winnerId, status) {
+    const parsed = readEntity(loser);
+    if (parsed === null)
+        return false;
+    parsed.fm["status"] = status;
+    if (status === "superseded")
+        parsed.fm["superseded_by"] = winnerId;
+    parsed.fm["verified-at"] = new Date().toISOString();
+    writeEntity(loser, parsed.fm, parsed.body);
+    return true;
+}
+function setSupersedes(loser, winner) {
+    const parsed = readEntity(winner);
+    if (parsed === null)
+        return false;
+    parsed.fm["supersedes"] = loser.id;
+    parsed.fm["verified-at"] = new Date().toISOString();
+    writeEntity(winner, parsed.fm, parsed.body);
+    return true;
+}
+function moveConflictToArchive(repoRoot, conflict) {
+    const archDir = archivedConflictsDir(repoRoot);
+    mkdirSync(archDir, { recursive: true });
+    const archAbs = join(archDir, conflict.filename);
+    renameSync(conflict.abs, archAbs);
+    return `.cairn/ground/conflicts/_archived/${conflict.filename}`;
+}
+function deleteConflictFile(conflict) {
+    try {
+        rmSync(conflict.abs, { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Plan §5.4.1 — losing-side prose stays in its source file
+ * post-resolution; the doc / CLAUDE.md / AGENTS.md narrative is
+ * preserved as-is. The original sot_path entry is now bound to a
+ * superseded / archived id, so phase 5b's next walk would re-emit a
+ * fresh DEC with the same content-addressed id (loop). Recording an
+ * `orphan_path` drift event surfaces the prose to the operator's
+ * attention queue so they can pick: re-cite the winner manually,
+ * promote it to a fresh DEC, or delete the orphan paragraph.
+ *
+ * The drift event includes `dec_id` pointing at the just-superseded
+ * entity so the attention surface can render context (which side won,
+ * what the orphan body looks like).
+ */
+function recordOrphanDriftEvents(repoRoot, refs) {
+    const ts = new Date().toISOString();
+    for (const { ref, parsed } of refs) {
+        if (parsed === null)
+            continue;
+        const sotKind = parsed.fm["sot_kind"];
+        if (sotKind !== "path")
+            continue;
+        const sotPath = String(parsed.fm["sot_path"] ?? "");
+        if (sotPath.length === 0 || sotPath === "ledger")
+            continue;
+        try {
+            recordDriftEvent(repoRoot, {
+                ts,
+                kind: "orphan_path",
+                path: sotPath,
+                detail: `Conflict resolution superseded ${ref.id}; losing-side prose still lives at ${sotPath}.`,
+                severity: "soft",
+                dec_id: ref.id,
+            });
+        }
+        catch (err) {
+            log.warn({ err: err instanceof Error ? err.message : String(err) }, "orphan_path drift event write failed");
+        }
+    }
+}
+function rebuildLedgers(repoRoot) {
+    try {
+        writeDecisionsLedger({ repoRoot });
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "decisions ledger rebuild failed after conflict resolution");
+    }
+    try {
+        writeInvariantsLedger({ repoRoot });
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "invariants ledger rebuild failed after conflict resolution");
+    }
+}
+/**
+ * Drop superseded / archived losers from sot-bindings + sot-cache so
+ * Layer A's pre-filter doesn't pick them as candidates and phase 5b
+ * doesn't loop on a path bound to a now-superseded id. The orphan_path
+ * drift event (recorded separately for sot_kind="path" losers) remains
+ * the operator-facing surface to recover the orphaned prose.
+ */
+function cleanLosersFromSotState(repoRoot, losers) {
+    let bindings = readSotBindings(repoRoot);
+    let cache = readSotCache(repoRoot);
+    let mutated = false;
+    for (const loser of losers) {
+        const nextBindings = unbindDec(bindings, loser.id);
+        if (nextBindings !== bindings) {
+            bindings = nextBindings;
+            mutated = true;
+        }
+        const nextCache = deleteSotCacheEntry(cache, loser.id);
+        if (nextCache !== cache) {
+            cache = nextCache;
+            mutated = true;
+        }
+    }
+    if (!mutated)
+        return;
+    try {
+        writeSotBindings(repoRoot, bindings);
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-bindings rewrite failed during conflict resolution cleanup");
+    }
+    try {
+        writeSotCache(repoRoot, cache);
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-cache rewrite failed during conflict resolution cleanup");
+    }
+}
+/**
+ * Bind + cache a merged entity that was just written to ground. Mirrors
+ * the bind/cache wiring in `emitFreshDec` so Layer A's pre-filter sees
+ * the merged DEC as a Tier-2 candidate immediately, instead of waiting
+ * for the next SessionStart drain to rebuild sot-cache.
+ */
+function bindAndCacheMergedEntity(repoRoot, mergedId, mergedBody) {
+    let bindings = readSotBindings(repoRoot);
+    bindings = bindDec(bindings, mergedId, "ledger");
+    try {
+        writeSotBindings(repoRoot, bindings);
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-bindings rewrite failed for merged entity");
+    }
+    let cache = readSotCache(repoRoot);
+    cache = setSotCacheEntry(cache, mergedId, {
+        dec_id: mergedId,
+        sot_path: "ledger",
+        body_hash: bodyContentHash(mergedBody),
+        tokens: Array.from(tokenize(mergedBody, { codeAware: true })),
+        shingles: [],
+        mtime_ms: Date.now(),
+    });
+    try {
+        writeSotCache(repoRoot, cache);
+    }
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-cache rewrite failed for merged entity");
+    }
+}
+function loadAlignmentPending(repoRoot, itemId) {
+    const dir = alignmentPendingDir(repoRoot);
+    const filename = `${itemId}.md`;
+    const abs = join(dir, filename);
+    if (!existsSync(abs))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(abs, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const { fm, body } = parseFrontmatterRecord(raw);
+    // Block prose lives between the first ```/``` fence pair under the
+    // "## Block ..." heading. Pick the first fenced block.
+    const blockMatch = body.match(/##\s+Block[^\n]*\n+```\n([\s\S]*?)\n```/);
+    const blockProse = blockMatch?.[1]?.trim() ?? "";
+    // Existing entity body (tier2-ambiguous only) lives in a second fenced block.
+    const existingId = typeof fm["existing_id"] === "string" ? fm["existing_id"] : null;
+    let existingBody = null;
+    if (existingId !== null) {
+        const existingMatch = body.match(/##\s+Existing\s+\S+[^\n]*\n+```\n([\s\S]*?)\n```/);
+        existingBody = existingMatch?.[1]?.trim() ?? null;
+    }
+    return {
+        abs,
+        rel: `.cairn/ground/alignment-pending/${filename}`,
+        filename,
+        fm,
+        blockProse,
+        existingId,
+        existingBody,
+    };
+}
+function buildPendingReplaceItem(fm, rawProse, replacement) {
+    const file = typeof fm["source_file"] === "string" ? fm["source_file"] : null;
+    const startOffset = typeof fm["start_offset"] === "number" ? fm["start_offset"] : null;
+    const endOffset = typeof fm["end_offset"] === "number" ? fm["end_offset"] : null;
+    if (file === null || startOffset === null || endOffset === null)
+        return null;
+    return {
+        blockId: typeof fm["slug"] === "string" ? `pending:${fm["slug"]}` : "pending:unknown",
+        file,
+        startOffset,
+        endOffset,
+        replacement,
+        expectedRaw: typeof fm["raw"] === "string" ? fm["raw"] : rawProse,
+    };
+}
+async function resolveAlignmentPending(ctx, input) {
+    const state = loadAlignmentPending(ctx.repoRoot, input.item_id);
+    if (state === null) {
+        return mcpError("FILE_NOT_FOUND", `no alignment-pending file for item_id=${input.item_id}`);
+    }
+    const kind = String(state.fm["kind"] ?? "");
+    const lang = typeof state.fm["lang"] === "string" ? state.fm["lang"] : "unknown";
+    const sourceFile = typeof state.fm["source_file"] === "string" ? state.fm["source_file"] : "";
+    const startLine = typeof state.fm["start_line"] === "number" ? state.fm["start_line"] : 0;
+    return withWriteLock(ctx.repoRoot, () => {
+        if (kind === "tier2-ambiguous") {
+            if (state.existingId === null) {
+                return mcpError("VALIDATION_FAILED", "tier2-ambiguous pending entry missing existing_id");
+            }
+            if (input.choice === "a") {
+                // Same — cite existing.
+                const replacement = formatBareCitation(lang, state.existingId);
+                const item = buildPendingReplaceItem(state.fm, state.blockProse, replacement);
+                if (item !== null)
+                    applyStripReplace({
+                        repoRoot: ctx.repoRoot,
+                        items: [item],
+                        dirtyDecisions: { [item.file]: "overwrite" },
+                    });
+                rmSync(state.abs, { force: true });
+                return {
+                    ok: true,
+                    resolved_kind: "alignment_cite",
+                    item_id: input.item_id,
+                    existing_id: state.existingId,
+                };
+            }
+            if (input.choice === "b") {
+                // Augments — emit sibling DEC linked via `related`. Source gets
+                // both cites stacked. (Operator-driven augments emit a DEC
+                // sibling; constraint augments still flow through the Layer A
+                // delta classifier on a future Write.)
+                const id = emitOperatorAugmentSibling(ctx.repoRoot, {
+                    source_file: sourceFile,
+                    source_offset: startLine,
+                    existingId: state.existingId,
+                    delta: state.blockProse,
+                    rationale: input.rationale ?? "",
+                });
+                const replacement = formatBareCitation(lang, state.existingId) +
+                    "\n" +
+                    formatBareCitation(lang, id);
+                const item = buildPendingReplaceItem(state.fm, state.blockProse, replacement);
+                if (item !== null)
+                    applyStripReplace({
+                        repoRoot: ctx.repoRoot,
+                        items: [item],
+                        dirtyDecisions: { [item.file]: "overwrite" },
+                    });
+                rmSync(state.abs, { force: true });
+                try {
+                    writeDecisionsLedger({ repoRoot: ctx.repoRoot });
+                }
+                catch {
+                    /* best-effort */
+                }
+                return {
+                    ok: true,
+                    resolved_kind: "alignment_augments",
+                    item_id: input.item_id,
+                    existing_id: state.existingId,
+                    new_id: id,
+                };
+            }
+            if (input.choice === "c") {
+                // New decision — emit fresh DEC, source carries new cite only.
+                const id = emitFreshDec(ctx.repoRoot, {
+                    source_file: sourceFile,
+                    source_offset: startLine,
+                    body: state.blockProse,
+                    captureSuffix: "operator-new",
+                    related: null,
+                });
+                const replacement = formatBareCitation(lang, id);
+                const item = buildPendingReplaceItem(state.fm, state.blockProse, replacement);
+                if (item !== null)
+                    applyStripReplace({
+                        repoRoot: ctx.repoRoot,
+                        items: [item],
+                        dirtyDecisions: { [item.file]: "overwrite" },
+                    });
+                rmSync(state.abs, { force: true });
+                try {
+                    writeDecisionsLedger({ repoRoot: ctx.repoRoot });
+                }
+                catch {
+                    /* best-effort */
+                }
+                return {
+                    ok: true,
+                    resolved_kind: "alignment_new",
+                    item_id: input.item_id,
+                    new_id: id,
+                };
+            }
+            if (input.choice === "d") {
+                // Replace — new becomes canonical, existing superseded.
+                const id = emitFreshDec(ctx.repoRoot, {
+                    source_file: sourceFile,
+                    source_offset: startLine,
+                    body: state.blockProse,
+                    captureSuffix: "operator-replace",
+                    related: state.existingId,
+                });
+                // Mark existing as superseded.
+                const existingRef = entityRefFor(ctx.repoRoot, state.existingId);
+                const parsed = readEntity(existingRef);
+                if (parsed !== null) {
+                    parsed.fm["status"] = "superseded";
+                    parsed.fm["superseded_by"] = id;
+                    parsed.fm["verified-at"] = new Date().toISOString();
+                    writeEntity(existingRef, parsed.fm, parsed.body);
+                }
+                const replacement = formatBareCitation(lang, id);
+                const item = buildPendingReplaceItem(state.fm, state.blockProse, replacement);
+                if (item !== null)
+                    applyStripReplace({
+                        repoRoot: ctx.repoRoot,
+                        items: [item],
+                        dirtyDecisions: { [item.file]: "overwrite" },
+                    });
+                rmSync(state.abs, { force: true });
+                try {
+                    writeDecisionsLedger({ repoRoot: ctx.repoRoot });
+                    writeInvariantsLedger({ repoRoot: ctx.repoRoot });
+                }
+                catch {
+                    /* best-effort */
+                }
+                return {
+                    ok: true,
+                    resolved_kind: "alignment_replace",
+                    item_id: input.item_id,
+                    new_id: id,
+                    superseded_id: state.existingId,
+                };
+            }
+        }
+        if (kind === "tier3-ambiguous") {
+            if (input.choice === "a" || input.choice === "b") {
+                const isInv = input.choice === "b";
+                const id = emitFreshDec(ctx.repoRoot, {
+                    source_file: sourceFile,
+                    source_offset: startLine,
+                    body: state.blockProse,
+                    captureSuffix: isInv ? "operator-constraint" : "operator-decision",
+                    related: null,
+                    asInv: isInv,
+                });
+                const replacement = formatBareCitation(lang, id);
+                const item = buildPendingReplaceItem(state.fm, state.blockProse, replacement);
+                if (item !== null)
+                    applyStripReplace({
+                        repoRoot: ctx.repoRoot,
+                        items: [item],
+                        dirtyDecisions: { [item.file]: "overwrite" },
+                    });
+                rmSync(state.abs, { force: true });
+                try {
+                    if (isInv)
+                        writeInvariantsLedger({ repoRoot: ctx.repoRoot });
+                    else
+                        writeDecisionsLedger({ repoRoot: ctx.repoRoot });
+                }
+                catch {
+                    /* best-effort */
+                }
+                return {
+                    ok: true,
+                    resolved_kind: isInv ? "alignment_constraint" : "alignment_decision",
+                    item_id: input.item_id,
+                    new_id: id,
+                };
+            }
+            if (input.choice === "c" || input.choice === "d") {
+                // Descriptive / none-of-these — drop the pending file. Source
+                // stays untouched (operator's narrative preserved).
+                rmSync(state.abs, { force: true });
+                return {
+                    ok: true,
+                    resolved_kind: input.choice === "c" ? "alignment_descriptive" : "alignment_skip",
+                    item_id: input.item_id,
+                };
+            }
+        }
+        return mcpError("VALIDATION_FAILED", `unsupported alignment_pending kind=${kind} or choice=${input.choice}`);
+    });
+}
+function emitFreshDec(repoRoot, args) {
+    const isInv = args.asInv === true;
+    const inputs = {
+        source_file: args.source_file,
+        source_offset: args.source_offset,
+        capture_source: `layer-a-resolve-${args.captureSuffix}`,
+    };
+    const id = isInv ? deriveLedgerInvId(inputs) : deriveLedgerDecId(inputs);
+    const dir = isInv ? invariantsDir(repoRoot) : decisionsDir(repoRoot);
+    const abs = join(dir, `${id}.md`);
+    const trimmed = args.body.trim();
+    const now = new Date().toISOString();
+    const fm = {
+        id,
+        title: firstLineOf(trimmed),
+        type: isInv ? "invariant" : "adr",
+        status: isInv ? "active" : "accepted",
+        audience: "dual",
+        generated: now,
+        "verified-at": now,
+        sot_kind: "ledger",
+        sot_path: "ledger",
+        sot_content_hash: bodyContentHash(trimmed),
+        capture_source: `layer-a-resolve-${args.captureSuffix}`,
+        source_file: args.source_file,
+    };
+    if (!isInv) {
+        fm["decided_at"] = now;
+        fm["decided_by"] = "cairn-resolve-attention";
+    }
+    if (args.related !== null)
+        fm["related"] = args.related;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(abs, `---\n${stringifyYaml(fm).trimEnd()}\n---\n\n${trimmed}\n`, "utf8");
+    let bindings = readSotBindings(repoRoot);
+    bindings = bindDec(bindings, id, "ledger");
+    writeSotBindings(repoRoot, bindings);
+    let cache = readSotCache(repoRoot);
+    cache = setSotCacheEntry(cache, id, {
+        dec_id: id,
+        sot_path: "ledger",
+        body_hash: bodyContentHash(trimmed),
+        tokens: Array.from(tokenize(trimmed, { codeAware: true })),
+        shingles: [],
+        mtime_ms: Date.now(),
+    });
+    writeSotCache(repoRoot, cache);
+    return id;
+}
+function emitOperatorAugmentSibling(repoRoot, args) {
+    return emitFreshDec(repoRoot, {
+        source_file: args.source_file,
+        source_offset: args.source_offset,
+        body: args.delta,
+        captureSuffix: `operator-augments-${args.existingId}`,
+        related: args.existingId,
+    });
+}
+function firstLineOf(text) {
+    const first = text.split("\n").find((l) => l.trim().length > 0) ?? "";
+    return first.replace(/^[#*\-\s>]+/, "").trim().slice(0, 120) || "(untitled)";
+}
+async function resolveConflict(ctx, input) {
+    const conflict = parseConflictFile(ctx.repoRoot, input.item_id);
+    if (conflict === null) {
+        return mcpError("FILE_NOT_FOUND", `no conflict file for item_id=${input.item_id} (expected .cairn/ground/conflicts/${input.item_id}.md)`);
+    }
+    return withWriteLock(ctx.repoRoot, () => {
+        const winner = input.choice === "a" ? conflict.aRef : conflict.bRef;
+        const loser = input.choice === "a" ? conflict.bRef : conflict.aRef;
+        if (input.choice === "a" || input.choice === "b") {
+            const loserBefore = readEntity(loser);
+            const winnerOk = setSupersedes(loser, winner);
+            const loserOk = setSupersededBy(ctx.repoRoot, loser, winner.id, "superseded");
+            if (!winnerOk || !loserOk) {
+                return mcpError("VALIDATION_FAILED", `conflict resolution failed: missing entity (winner=${winnerOk ? "ok" : "missing"}, loser=${loserOk ? "ok" : "missing"})`);
+            }
+            recordOrphanDriftEvents(ctx.repoRoot, [{ ref: loser, parsed: loserBefore }]);
+            deleteConflictFile(conflict);
+            cleanLosersFromSotState(ctx.repoRoot, [loser]);
+            rebuildLedgers(ctx.repoRoot);
+            try {
+                writeInvalidationEvent(ctx.repoRoot, {
+                    kind: "conflict_resolved_supersede",
+                    refs: [
+                        { kind: winner.kind === "DEC" ? "decision" : "invariant", id: winner.id },
+                        { kind: loser.kind === "DEC" ? "decision" : "invariant", id: loser.id },
+                    ],
+                    path: winner.rel,
+                    source: { session_id: ctx.sessionId ?? null, tool: "cairn_resolve_attention" },
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+            return {
+                ok: true,
+                resolved_kind: "conflict_supersede",
+                item_id: input.item_id,
+                winner_id: winner.id,
+                loser_id: loser.id,
+                winner_path: winner.rel,
+                loser_path: loser.rel,
+                ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+            };
+        }
+        if (input.choice === "c") {
+            const aBefore = readEntity(conflict.aRef);
+            const bBefore = readEntity(conflict.bRef);
+            const merge = mergeConflict(ctx.repoRoot, conflict, input.rationale);
+            if ("error" in merge)
+                return merge.error;
+            recordOrphanDriftEvents(ctx.repoRoot, [
+                { ref: conflict.aRef, parsed: aBefore },
+                { ref: conflict.bRef, parsed: bBefore },
+            ]);
+            deleteConflictFile(conflict);
+            cleanLosersFromSotState(ctx.repoRoot, [conflict.aRef, conflict.bRef]);
+            rebuildLedgers(ctx.repoRoot);
+            try {
+                writeInvalidationEvent(ctx.repoRoot, {
+                    kind: "conflict_resolved_merge",
+                    refs: [
+                        { kind: "decision", id: merge.mergedId },
+                        {
+                            kind: conflict.aRef.kind === "DEC" ? "decision" : "invariant",
+                            id: conflict.aRef.id,
+                        },
+                        {
+                            kind: conflict.bRef.kind === "DEC" ? "decision" : "invariant",
+                            id: conflict.bRef.id,
+                        },
+                    ],
+                    path: merge.mergedRel,
+                    source: { session_id: ctx.sessionId ?? null, tool: "cairn_resolve_attention" },
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+            return {
+                ok: true,
+                resolved_kind: "conflict_merge",
+                item_id: input.item_id,
+                merged_id: merge.mergedId,
+                merged_path: merge.mergedRel,
+                superseded_a: conflict.aRef.id,
+                superseded_b: conflict.bRef.id,
+                ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+            };
+        }
+        // choice === "d" — archive both. Conflict file moves to _archived/.
+        const aBefore = readEntity(conflict.aRef);
+        const bBefore = readEntity(conflict.bRef);
+        const aOk = setSupersededBy(ctx.repoRoot, conflict.aRef, conflict.bRef.id, "archived");
+        const bOk = setSupersededBy(ctx.repoRoot, conflict.bRef, conflict.aRef.id, "archived");
+        recordOrphanDriftEvents(ctx.repoRoot, [
+            { ref: conflict.aRef, parsed: aBefore },
+            { ref: conflict.bRef, parsed: bBefore },
+        ]);
+        const archivedRel = moveConflictToArchive(ctx.repoRoot, conflict);
+        cleanLosersFromSotState(ctx.repoRoot, [conflict.aRef, conflict.bRef]);
+        rebuildLedgers(ctx.repoRoot);
+        try {
+            writeInvalidationEvent(ctx.repoRoot, {
+                kind: "conflict_resolved_archive",
+                refs: [
+                    {
+                        kind: conflict.aRef.kind === "DEC" ? "decision" : "invariant",
+                        id: conflict.aRef.id,
+                    },
+                    {
+                        kind: conflict.bRef.kind === "DEC" ? "decision" : "invariant",
+                        id: conflict.bRef.id,
+                    },
+                ],
+                path: archivedRel,
+                source: { session_id: ctx.sessionId ?? null, tool: "cairn_resolve_attention" },
+            });
+        }
+        catch {
+            /* best-effort */
+        }
+        if (!aOk || !bOk) {
+            log.warn({ aOk, bOk, item_id: input.item_id }, "archive-both: one or both entities missing on disk");
+        }
+        return {
+            ok: true,
+            resolved_kind: "conflict_archive",
+            item_id: input.item_id,
+            a_id: conflict.aRef.id,
+            b_id: conflict.bRef.id,
+            archived_path: archivedRel,
+            ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+        };
+    });
+}
+function mergeConflict(repoRoot, conflict, rationale) {
+    const a = readEntity(conflict.aRef);
+    const b = readEntity(conflict.bRef);
+    if (a === null || b === null) {
+        return {
+            error: mcpError("VALIDATION_FAILED", `merge requires both entities present on disk (a=${a !== null}, b=${b !== null})`),
+        };
+    }
+    const now = new Date().toISOString();
+    // Merged entity inherits the kind of A (the freshly captured side).
+    // Mixed DEC/INV merges produce a DEC by convention — the merged
+    // entity carries combined narrative, not a single hard constraint.
+    const mergedKind = conflict.aRef.kind === "INV" && conflict.bRef.kind === "INV" ? "INV" : "DEC";
+    const mergedId = synthesizeMergedId(repoRoot, mergedKind);
+    const mergedRel = mergedKind === "DEC"
+        ? `.cairn/ground/decisions/${mergedId}.md`
+        : `.cairn/ground/invariants/${mergedId}.md`;
+    const mergedAbs = join(repoRoot, mergedRel);
+    const titleA = String(a.fm["title"] ?? conflict.aRef.id);
+    const titleB = String(b.fm["title"] ?? conflict.bRef.id);
+    const mergedTitle = `Merged: ${titleA} + ${titleB}`;
+    const mergedBody = [
+        "",
+        `# ${mergedId} — ${mergedTitle}`,
+        "",
+        `## ${conflict.aRef.id} (one side of the merge)`,
+        "",
+        a.body.trim(),
+        "",
+        `## ${conflict.bRef.id} (other side of the merge)`,
+        "",
+        b.body.trim(),
+        "",
+        "## Merge rationale",
+        "",
+        rationale !== undefined && rationale.trim().length > 0
+            ? rationale.trim()
+            : "(operator merged both sides via cairn-attention conflict resolution)",
+        "",
+    ].join("\n");
+    const mergedFm = {
+        id: mergedId,
+        title: mergedTitle,
+        type: mergedKind === "DEC" ? "adr" : "invariant",
+        status: mergedKind === "DEC" ? "accepted" : "active",
+        audience: "dual",
+        generated: now,
+        "verified-at": now,
+        sot_kind: "ledger",
+        sot_path: "ledger",
+        sot_content_hash: bodyContentHash(mergedBody),
+        capture_source: "conflict-merge",
+        related: `${conflict.aRef.id},${conflict.bRef.id}`,
+    };
+    if (mergedKind === "DEC") {
+        mergedFm["decided_at"] = now;
+        mergedFm["decided_by"] = "cairn-conflict-merge";
+    }
+    writeFileSafe(mergedAbs, `---\n${stringifyYaml(mergedFm).trimEnd()}\n---\n${mergedBody}`);
+    // Both old entries get superseded_by → new merged id.
+    setSupersededBy(repoRoot, conflict.aRef, mergedId, "superseded");
+    setSupersededBy(repoRoot, conflict.bRef, mergedId, "superseded");
+    // Bind + cache the merged entity so Layer A picks it up on the next
+    // PostToolUse without waiting for SessionStart drain.
+    bindAndCacheMergedEntity(repoRoot, mergedId, mergedBody);
+    return { mergedId, mergedRel };
+}
+function synthesizeMergedId(repoRoot, kind) {
+    // Content-addressed style — derive from the timestamp + a counter so
+    // re-runs in the same millisecond don't collide. We don't have the
+    // verbatim merged-body hash easily reachable here without circular
+    // dependencies; the timestamp gives us a stable-enough seed since
+    // merges are operator-driven and infrequent.
+    const dir = kind === "DEC" ? decisionsDir(repoRoot) : invariantsDir(repoRoot);
+    const existing = new Set();
+    if (existsSync(dir)) {
+        try {
+            for (const e of readdirSync(dir, { withFileTypes: true })) {
+                if (e.isFile() && e.name.endsWith(".md")) {
+                    existing.add(e.name.replace(/\.md$/, ""));
+                }
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    const seed = `merge-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
+    let candidate = `${kind}-${hashHex(seed).slice(0, 7)}`;
+    let suffix = 0;
+    while (existing.has(candidate)) {
+        suffix += 1;
+        candidate = `${kind}-${hashHex(`${seed}-${suffix}`).slice(0, 7)}`;
+    }
+    return candidate;
+}
+function hashHex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
 function resolveInvalidationEvent(_ctx, input) {
     // Per spec §7: A=refresh, B=continue-under-old, C=abort. The marker
     // stamping + scope refresh happens in the calling skill, since it
     // owns the session id. This tool just acknowledges the resolution
     // so the skill can record it.
-    const map = { a: "refresh", b: "continue_under_old", c: "abort" };
+    const map = {
+        a: "refresh",
+        b: "continue_under_old",
+        c: "abort",
+    };
+    // The "d" slot is filtered out for non-conflict kinds in the top
+    // dispatcher, so this cast is safe.
+    const choice = input.choice;
     return Promise.resolve({
         ok: true,
-        resolved_kind: `invalidation_${map[input.choice]}`,
+        resolved_kind: `invalidation_${map[choice]}`,
         item_id: input.item_id,
         ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
     });