@isaacriehm/cairn-core 0.6.0 → 0.7.1

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

@@ -4,50 +4,47 @@
  * Spec: PLUGIN_ARCHITECTURE §9 (MCP write tools — plugin-era addition).
  *
  * The cairn-attention skill calls this after the operator picks an
- * option. It maps `kind × choice` onto the canonical resolution
- * pathway:
- *
- * | kind                | choice | resolution                                  |
- * |---------------------|--------|---------------------------------------------|
- * | decision_draft      | a      | accept — move `_inbox/<id>.draft.md` → `<id>.md`, status=accepted |
- * | decision_draft      | b      | reject — rename draft to .rejected.md (id reserved forever) |
- * | decision_draft      | c      | edit-pending — return draft body (no write) |
- * | baseline_finding    | a      | triage-now — no-op (skill opens the file)   |
- * | baseline_finding    | b      | suppress — append to baseline/suppressions.yaml |
- * | baseline_finding    | c      | defer — no-op                               |
- * | invalidation_event  | a      | refresh — re-read in-scope DECs/§INVs        |
- * | invalidation_event  | b      | continue-under-old — no-op                  |
- * | invalidation_event  | c      | abort — caller archives task (no-op here)   |
- * | drift               | a/b/c  | acknowledged (drift surface not yet active) |
+ * option. It maps the option (a/b/c/d) to a ground-state write (promote
+ * draft, suppress finding, record resolution event).
  */
 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 { z } from "zod";
+import { bindDec, bodyContentHash, conflictsDir, readSotBindings, readSotCache, recordDriftEvent, setSotCacheEntry, writeSotBindings, writeSotCache, decisionsDir, invariantsDir, writeDecisionsLedger, writeInvariantsLedger, parseFrontmatterRecord, deleteSotCacheEntry, unbindDec, alignmentPendingDir, archivedConflictsDir, deriveLedgerDecId, deriveLedgerInvId, writeFileSafe, } from "@isaacriehm/cairn-state";
 import { writeInvalidationEvent } from "../../events/index.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";
 import { requireBootstrap } from "../bootstrap-guard.js";
-import { mcpError } from "../errors.js";
-import { resolveAttentionInput } from "../schemas.js";
-const log = logger("mcp.resolve-attention");
+import { mcpError } from "./types.js";
+import { parseDraftMeta, runDecSourceStrip, } from "../../attention/source-strip.js";
+import { restoreDec } from "../../attention/restore.js";
+import { tokenize } from "../../text/jaccard.js";
+import { applyStripReplace, formatBareCitation, } from "../../init/source-comments/strip-replace.js";
+import { writeDeferState, clearDeferState } from "../../hooks/defer.js";
+import { logger } from "../../logger.js";
+const log = logger("mcp.tools.resolve-attention");
+const resolveAttentionInput = {
+    kind: z.enum([
+        "decision_draft",
+        "baseline_finding",
+        "invalidation_event",
+        "drift",
+        "bypass",
+        "review",
+        "conflict",
+        "alignment_pending",
+    ]),
+    item_id: z.string(),
+    choice: z.enum(["a", "b", "c", "d"]),
+    rationale: z.string().optional(),
+    defer_hours: z.number().optional(),
+    flagged_items: z.array(z.string()).optional(),
+};
 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);
@@ -55,28 +52,18 @@ async function handler(ctx, input) {
             return resolveBaselineFinding(ctx, input);
         case "invalidation_event":
             return resolveInvalidationEvent(ctx, input);
-        case "drift":
-            return {
-                ok: true,
-                resolved_kind: "drift_acknowledged",
-                note: "drift resolution surface not yet implemented (step 7+); item left in queue",
-            };
         case "bypass":
-            return resolveBypass(ctx, input);
+            return resolveStopSignal(ctx, input, "bypass");
         case "review":
-            return resolveReview(ctx, input);
+            return resolveStopSignal(ctx, input, "review");
         case "conflict":
             return resolveConflict(ctx, input);
         case "alignment_pending":
             return resolveAlignmentPending(ctx, input);
+        default:
+            return mcpError("VALIDATION_FAILED", `unknown kind: ${input.kind}`);
     }
 }
-function resolveBypass(ctx, input) {
-    return resolveStopSignal(ctx, input, "bypass");
-}
-function resolveReview(ctx, input) {
-    return resolveStopSignal(ctx, input, "review");
-}
 /**
  * Shared resolution path for the two Stop-hook surfaces. choice=a/b
  * are kind-specific intents (the calling skill executes them); the
@@ -92,7 +79,6 @@ function resolveStopSignal(ctx, input, kind) {
             const state = writeDeferState(ctx.repoRoot, kind, {
                 flagged_shas: kind === "bypass" ? flagged : [],
                 flagged_task_ids: kind === "review" ? flagged : [],
-                ...(input.defer_hours !== undefined ? { hours: input.defer_hours } : {}),
             });
             return {
                 ok: true,
@@ -133,13 +119,6 @@ async function resolveDecisionDraft(ctx, input) {
     const inboxPath = join(decDir, "_inbox", `${input.item_id}.draft.md`);
     const rejectedPath = join(decDir, "_inbox", `${input.item_id}.rejected.md`);
     const acceptedPath = join(decDir, `${input.item_id}.md`);
-    // Auto-restore: when the draft is missing but the same id sits as a
-    // rejected or already-accepted entry, transparently roll it back to
-    // a draft so the operator's choice (a/b/c) lands in one MCP call
-    // instead of needing an explicit `cairn_attention_restore` first.
-    // Idempotent re-accept on a still-canonical accepted DEC is the same
-    // shape as accepting a fresh draft — rebuild ledger, no double-strip
-    // (already-stripped check inside runDecSourceStrip).
     let autoRestoredFrom = null;
     if (!existsSync(inboxPath)) {
         if (existsSync(rejectedPath) || existsSync(acceptedPath)) {
@@ -160,8 +139,6 @@ async function resolveDecisionDraft(ctx, input) {
         }
     }
     if (input.choice === "c") {
-        // Edit-pending: return the draft body so the skill can hand it to
-        // the operator's editor flow. No state change.
         const body = readFileSync(inboxPath, "utf8");
         const editBase = {
             ok: true,
@@ -174,7 +151,7 @@ async function resolveDecisionDraft(ctx, input) {
             ? editBase
             : { ...editBase, auto_restored_from: autoRestoredFrom };
     }
-    return withWriteLock(ctx.repoRoot, () => {
+    return withWriteLock(ctx.repoRoot, async () => {
         if (input.choice === "a") {
             const acceptedPath = join(decDir, `${input.item_id}.md`);
             mkdirSync(dirname(acceptedPath), { recursive: true });
@@ -182,25 +159,18 @@ async function resolveDecisionDraft(ctx, input) {
             const draftMeta = parseDraftMeta(draft);
             const promoted = promoteDraftStatus(draft);
             writeFileSync(acceptedPath, promoted, "utf8");
-            // Remove the draft after promoting so the inbox stays clean.
-            // The canonical accepted file at <decDir>/<id>.md is the
-            // recoverable copy if the rmSync interrupts.
             try {
                 rmSync(inboxPath, { force: true });
             }
             catch {
-                // ignore — best effort, the accepted file is what matters
+                // ignore
             }
             try {
                 emitEvent(ctx, "decision_accepted", input.item_id, `.cairn/ground/decisions/${input.item_id}.md`);
             }
             catch {
-                // event emission must never roll back the resolution
+                // ignore
             }
-            // Rebuild `.cairn/ground/decisions/decisions.ledger.yaml` from
-            // every accepted DEC on disk. Cairn Lens reads the ledger to
-            // resolve `// DEC-NNNN` citations inline; without this rebuild
-            // the ledger sits empty and lens renders nothing.
             try {
                 writeDecisionsLedger({ repoRoot: ctx.repoRoot });
             }
@@ -226,8 +196,7 @@ async function resolveDecisionDraft(ctx, input) {
                 ? withStrip
                 : { ...withStrip, auto_restored_from: autoRestoredFrom };
         }
-        // choice === "b" — reject. Rename to .rejected.md so scanExistingDecisionIds
-        // keeps the id in the high-water mark and it is never recycled.
+        // choice === "b" — reject.
         renameSync(inboxPath, rejectedPath);
         const rejectedRel = `.cairn/ground/decisions/_inbox/${input.item_id}.rejected.md`;
         try {
@@ -265,9 +234,6 @@ function resolveBaselineFinding(ctx, input) {
     return withWriteLock(ctx.repoRoot, () => {
         const suppressionsPath = join(ctx.repoRoot, ".cairn", "baseline", "suppressions.yaml");
         mkdirSync(dirname(suppressionsPath), { recursive: true });
-        // Empty / missing file → seed the YAML root key so the appended
-        // entries land under a valid `suppressions:` list. statSync may
-        // throw on race; treat any error as "needs header".
         let needsHeader = !existsSync(suppressionsPath);
         if (!needsHeader) {
             try {
@@ -391,20 +357,6 @@ function deleteConflictFile(conflict) {
         /* 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) {
@@ -436,22 +388,15 @@ function rebuildLedgers(repoRoot) {
         writeDecisionsLedger({ repoRoot });
     }
     catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : String(err) }, "decisions ledger rebuild failed after conflict resolution");
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "decisions ledger rebuild failed");
     }
     try {
         writeInvariantsLedger({ repoRoot });
     }
     catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : String(err) }, "invariants ledger rebuild failed after conflict resolution");
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "invariants ledger rebuild failed");
     }
 }
-/**
- * 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);
@@ -473,30 +418,24 @@ function cleanLosersFromSotState(repoRoot, losers) {
     try {
         writeSotBindings(repoRoot, bindings);
     }
-    catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-bindings rewrite failed during conflict resolution cleanup");
+    catch {
+        /* ignore */
     }
     try {
         writeSotCache(repoRoot, cache);
     }
-    catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-cache rewrite failed during conflict resolution cleanup");
+    catch {
+        /* ignore */
     }
 }
-/**
- * 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");
+    catch {
+        /* ignore */
     }
     let cache = readSotCache(repoRoot);
     cache = setSotCacheEntry(cache, mergedId, {
@@ -510,8 +449,8 @@ function bindAndCacheMergedEntity(repoRoot, mergedId, mergedBody) {
     try {
         writeSotCache(repoRoot, cache);
     }
-    catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : String(err) }, "sot-cache rewrite failed for merged entity");
+    catch {
+        /* ignore */
     }
 }
 function loadAlignmentPending(repoRoot, itemId) {
@@ -528,11 +467,8 @@ function loadAlignmentPending(repoRoot, itemId) {
         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) {
@@ -579,7 +515,6 @@ async function resolveAlignmentPending(ctx, input) {
                 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)
@@ -597,10 +532,6 @@ async function resolveAlignmentPending(ctx, input) {
                 };
             }
             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,
@@ -634,7 +565,6 @@ async function resolveAlignmentPending(ctx, input) {
                 };
             }
             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,
@@ -665,7 +595,6 @@ async function resolveAlignmentPending(ctx, input) {
                 };
             }
             if (input.choice === "d") {
-                // Replace — new becomes canonical, existing superseded.
                 const id = emitFreshDec(ctx.repoRoot, {
                     source_file: sourceFile,
                     source_offset: startLine,
@@ -673,7 +602,6 @@ async function resolveAlignmentPending(ctx, input) {
                     captureSuffix: "operator-replace",
                     related: state.existingId,
                 });
-                // Mark existing as superseded.
                 const existingRef = entityRefFor(ctx.repoRoot, state.existingId);
                 const parsed = readEntity(existingRef);
                 if (parsed !== null) {
@@ -744,8 +672,6 @@ async function resolveAlignmentPending(ctx, input) {
                 };
             }
             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,
@@ -822,9 +748,9 @@ function firstLineOf(text) {
 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 mcpError("FILE_NOT_FOUND", `no conflict file for item_id=${input.item_id}`);
     }
-    return withWriteLock(ctx.repoRoot, () => {
+    return withWriteLock(ctx.repoRoot, async () => {
         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") {
@@ -832,7 +758,7 @@ async function resolveConflict(ctx, input) {
             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"})`);
+                return mcpError("VALIDATION_FAILED", `conflict resolution failed: missing entity`);
             }
             recordOrphanDriftEvents(ctx.repoRoot, [{ ref: loser, parsed: loserBefore }]);
             deleteConflictFile(conflict);
@@ -850,7 +776,7 @@ async function resolveConflict(ctx, input) {
                 });
             }
             catch {
-                /* best-effort */
+                /* ignore */
             }
             return {
                 ok: true,
@@ -895,7 +821,7 @@ async function resolveConflict(ctx, input) {
                 });
             }
             catch {
-                /* best-effort */
+                /* ignore */
             }
             return {
                 ok: true,
@@ -908,11 +834,11 @@ async function resolveConflict(ctx, input) {
                 ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
             };
         }
-        // choice === "d" — archive both. Conflict file moves to _archived/.
+        // choice === "d" — archive both.
         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");
+        setSupersededBy(ctx.repoRoot, conflict.aRef, conflict.bRef.id, "archived");
+        setSupersededBy(ctx.repoRoot, conflict.bRef, conflict.aRef.id, "archived");
         recordOrphanDriftEvents(ctx.repoRoot, [
             { ref: conflict.aRef, parsed: aBefore },
             { ref: conflict.bRef, parsed: bBefore },
@@ -938,10 +864,7 @@ async function resolveConflict(ctx, input) {
             });
         }
         catch {
-            /* best-effort */
-        }
-        if (!aOk || !bOk) {
-            log.warn({ aOk, bOk, item_id: input.item_id }, "archive-both: one or both entities missing on disk");
+            /* ignore */
         }
         return {
             ok: true,
@@ -959,13 +882,10 @@ function mergeConflict(repoRoot, conflict, rationale) {
     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})`),
+            error: mcpError("VALIDATION_FAILED", `merge requires both entities present on disk`),
         };
     }
     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"
@@ -1013,20 +933,12 @@ function mergeConflict(repoRoot, conflict, rationale) {
         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)) {
@@ -1038,7 +950,7 @@ function synthesizeMergedId(repoRoot, kind) {
             }
         }
         catch {
-            /* best-effort */
+            /* ignore */
         }
     }
     const seed = `merge-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
@@ -1054,17 +966,11 @@ 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",
     };
-    // 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,
@@ -1074,12 +980,6 @@ function resolveInvalidationEvent(_ctx, input) {
     });
 }
 function promoteDraftStatus(body) {
-    // Frontmatter `status: draft*` → `status: accepted`. Best-effort
-    // regex — covers every draft marker the init pipeline emits:
-    //   - `draft` (legacy / generic)
-    //   - `draft-from-init-docs` (phase 6)
-    //   - `draft-from-source-comment` (phase 7b)
-    //   - `draft-from-rules-merge` (phase 7c)
     return body.replace(/^status:\s*draft(?:-from-[a-z-]+)?\b/m, "status: accepted");
 }
 function emitEvent(ctx, kind, decId, path) {