@cyber-dash-tech/revela 0.16.3 → 0.17.0

package/tools/decks.ts

@@ -11,13 +11,14 @@ import {
   writeDecksState,
   workspaceDeckSlug,
   type DeckSpec,
+  type DecksState,
   type NarrativeBrief,
   type RequiredInputs,
   type ResearchAxis,
   type SourceMaterial,
   type SlideSpec,
 } from "../lib/decks-state"
-import { upsertSourceMaterial } from "../lib/source-materials"
+import { classifySourceMaterialIngest, upsertSourceMaterial } from "../lib/source-materials"
 import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 import { applyEvidenceBindings } from "../lib/workspace-state/evidence-status"
 import { attachResearchFindings } from "../lib/workspace-state/research-attachments"
@@ -31,33 +32,81 @@ import {
 import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
 import { backfillSlideClaimRefsFromCoverage } from "../lib/narrative-state/coverage"
 import { closeResearchGapInState, deriveResearchGapsFromReadiness, deriveResearchTargets, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
-import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "../lib/narrative-state/normalize"
-import { narrativeToBrief } from "../lib/narrative-state/project-compat"
-import type { NarrativeStateV1 } from "../lib/narrative-state/types"
+import { evaluateResearchFindingsBinding } from "../lib/narrative-state/research-binding-eval"
+import { stableEvidenceId } from "../lib/narrative-state/hash"
+import { normalizeNarrativeState } from "../lib/narrative-state/normalize"
+import { buildNarrativeVaultInventory, compileNarrativeVault, exportNarrativeStateToVault, formatVaultDiagnosticReport, getNarrativeVaultMigrationHint, hasNarrativeVault, initNarrativeVault, narrativeVaultAuthoringContract, narrativeVaultTimestampMs, removeVaultRelation, runNarrativeMarkdownQa, updateVaultCoreNodes, updateVaultResearchGapNode, upsertVaultClaimNode, upsertVaultEvidenceNode, upsertVaultObjectionNode, upsertVaultRelation, upsertVaultRiskNode, VAULT_MIGRATION_PRESERVED_IN_DECKS_JSON } from "../lib/narrative-vault"
+import { compileCacheMirrorNarrativeVault } from "../lib/narrative-vault/compile-mirror"
 
-function mergeNarrativeInput(current: NarrativeStateV1, input: Partial<NarrativeStateV1>): Partial<NarrativeStateV1> {
+function missingBindableEvidenceFields(input: Record<string, unknown>): string[] {
+  const missing: string[] = []
+  for (const key of ["id", "claimId", "source", "quote", "supportScope", "unsupportedScope", "caveat", "strength"] as const) {
+    if (!String(input[key] ?? "").trim()) missing.push(key)
+  }
+  if (!String(input.sourcePath ?? "").trim() && !String(input.url ?? "").trim() && !String(input.findingsFile ?? "").trim()) missing.push("sourcePath|url|findingsFile")
+  return missing
+}
+
+function exactResearchGapForBinding(state: DecksState, findingsFile: string, claimId: string) {
+  const gaps = state.narrative?.researchGaps ?? []
+  const exact = gaps.filter((gap) => gap.targetType === "claim" && gap.targetId === claimId && gap.findingsFile === findingsFile)
+  if (exact.length === 1) return exact[0]
+  if (exact.length > 1) return undefined
+  const byClaim = gaps.filter((gap) => gap.targetType === "claim" && gap.targetId === claimId && !gap.findingsFile)
+  return byClaim.length === 1 ? byClaim[0] : undefined
+}
+
+function forbiddenVaultCompatibilityAction(action: string, replacement: string): string {
+  return `${action} is a JSON-era compatibility action and is blocked in vault workspaces. Use ${replacement}, or patch the existing Markdown node only for a small read-before-edit repair.`
+}
+
+function researchGapHelperRecovery(action: "updateVaultResearchGap" | "upsertVaultResearchGap", missingFields?: string[]) {
+  const missing = missingFields?.length ? ` Missing fields: ${missingFields.join(", ")}.` : ""
   return {
-    ...current,
-    ...input,
-    id: current.id,
-    version: 1,
-    audience: {
-      ...current.audience,
-      ...(input.audience ?? {}),
+    nextActions: [
+      "If the research gap already exists, read the matching revela-narrative/research-gaps/*.md file and patch only the lifecycle fields.",
+      "If this is a new research gap, provide id, targetType, targetId, question, status, and priority, or create the Markdown node directly after checking narrativeInventory with a ## Relations depends_on wikilink.",
+      "Rerun revela-decks markdownQa and compileNarrativeVault after the repair.",
+    ],
+    examples: {
+      tool: {
+        action,
+        researchGaps: [{ id: "gap-market-size", targetType: "claim", targetId: "claim-market-context", question: "What source supports the market-size claim?", status: "open", priority: "high" }],
+      },
+      markdown: "---\ntype: research-gap\nid: gap-market-size\ntargetType: claim\ntargetId: claim-market-context\nquestion: What source supports the market-size claim?\nstatus: open\npriority: high\n---\nWhat source supports the market-size claim?\n\n## Relations\n\n- depends_on: [[claim-market-context]]\n",
     },
-    decision: {
-      ...current.decision,
-      ...(input.decision ?? {}),
+    message: `Research gap helper could not complete.${missing}`,
+  }
+}
+
+function relationHelperRecovery(action: "upsertVaultRelation" | "removeVaultRelation", missingFields?: string[]) {
+  const missing = missingFields?.length ? ` Missing fields: ${missingFields.join(", ")}.` : ""
+  return {
+    message: `Relation registry helper is disabled in Markdown vault workspaces.${missing}`,
+    nextActions: [
+      "Run narrativeInventory before adding or removing relation edges; reuse existing node ids exactly.",
+      "Patch the source node's ## Relations section with a plain wikilink relation line; do not hand-write relation ids.",
+      "Rerun markdownQa and compileNarrativeVault so compiler-generated relation ids and diagnostics refresh.",
+    ],
+    examples: {
+      tool: { action, note: "Deprecated compatibility action; edit Markdown instead." },
+      markdown: "## Relations\n\n- supports: [[claim-execution-readiness]] - Pilot recommendation is supported by execution framing.\n",
     },
-    thesis: input.thesis ? { ...current.thesis, ...input.thesis } as NarrativeStateV1["thesis"] : current.thesis,
-    claims: input.claims ?? current.claims,
-    claimRelations: input.claimRelations ?? current.claimRelations,
-    evidenceBindings: input.evidenceBindings ?? current.evidenceBindings,
-    objections: input.objections ?? current.objections,
-    risks: input.risks ?? current.risks,
-    researchGaps: input.researchGaps ?? current.researchGaps,
-    approvals: current.approvals,
-    updatedAt: new Date().toISOString(),
+  }
+}
+
+function strictVaultMarkdownQaGate(workspaceRoot: string, strictness: "readiness" | "render", action: string) {
+  if (!hasNarrativeVault(workspaceRoot)) return undefined
+  const markdownQa = runNarrativeMarkdownQa(workspaceRoot, { scope: "full", strictness })
+  if (markdownQa.ok) return undefined
+  return {
+    ok: false,
+    skipped: true,
+    action,
+    reason: `Markdown QA ${strictness} blockers must be repaired before ${action}.`,
+    markdownQa,
+    narrativeInventory: buildNarrativeVaultInventory(workspaceRoot),
+    authoringContract: narrativeVaultAuthoringContract(),
   }
 }
 
@@ -68,7 +117,7 @@ export default tool({
     "It stores workspace narrative state, active deck specs, per-slide content/layout/components, and computes narrative or deck readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "confirmDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "deriveResearchTargets", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
+      .enum(["read", "init", "initNarrativeVault", "narrativeInventory", "vaultInventory", "markdownQa", "upsertDeck", "upsertSlides", "upsertNarrative", "compileNarrativeVault", "exportNarrativeVault", "upsertVaultEvidence", "bindResearchFindings", "updateVaultResearchGap", "upsertVaultResearchGap", "upsertVaultClaim", "upsertVaultObjection", "upsertVaultRisk", "upsertVaultRelation", "removeVaultRelation", "updateVaultCoreNarrative", "compileDeckPlan", "confirmDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "deriveResearchTargets", "evaluateResearchFindings", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
       .describe("Action to perform on DECKS.json."),
     summary: tool.schema.boolean().optional().describe("For read: return a compact summary instead of full state."),
     goal: tool.schema.string().optional().describe("For upsertDeck: deck goal."),
@@ -127,7 +176,7 @@ export default tool({
       })).optional().describe("Canonical claim-to-claim narrative progression relationships. These affect narrative approval hash."),
       evidenceBindings: tool.schema.array(tool.schema.object({
         id: tool.schema.string().optional(),
-        claimId: tool.schema.string().describe("Canonical claim id this evidence supports."),
+        claimId: tool.schema.string().describe("Compatibility fallback claim id this evidence supports; helpers also write a ## Relations supports wikilink."),
         source: tool.schema.string().describe("Source file, URL, research finding, or material name."),
         sourcePath: tool.schema.string().optional(),
         findingsFile: tool.schema.string().optional(),
@@ -165,7 +214,7 @@ export default tool({
         createdFromIssueType: tool.schema.string().optional(),
         notes: tool.schema.string().optional(),
       })).optional(),
-    }).optional().describe("For upsertNarrative: canonical narrative state fields to merge into DECKS.json. Replaces provided arrays, preserves approvals."),
+    }).optional().describe("For initNarrativeVault and targeted vault actions: canonical narrative fields to write into Markdown nodes. upsertNarrative is deprecated."),
     design: tool.schema.string().optional().describe("For upsertDeck: active design name."),
     domain: tool.schema.string().optional().describe("For upsertDeck: active domain name."),
     memory: tool.schema.string().optional().describe("For remember: explicit user or workflow preference to store."),
@@ -249,7 +298,29 @@ export default tool({
       notes: tool.schema.string().optional().describe("Implementation notes for this slide."),
     })).optional().describe("For upsertSlides: complete or partial slide specs."),
     candidateIds: tool.schema.array(tool.schema.string()).optional().describe("For applyEvidenceCandidates: candidate IDs returned by revela-decks review to explicitly bind proposed evidenceDraft records into slide evidence."),
-    findingsFile: tool.schema.string().optional().describe("For attachResearchFindings: workspace-relative researches/{topic}/{axis}.md file to attach to researchPlan."),
+    evidence: tool.schema.object({
+      id: tool.schema.string().describe("For upsertVaultEvidence or bindResearchFindings: canonical evidence binding id."),
+      claimId: tool.schema.string().describe("For upsertVaultEvidence: canonical claim id this evidence supports."),
+      source: tool.schema.string().describe("For upsertVaultEvidence: source name, file, URL, or research finding label."),
+      sourcePath: tool.schema.string().optional(),
+      findingsFile: tool.schema.string().optional(),
+      quote: tool.schema.string().describe("For upsertVaultEvidence: exact quote or snippet supporting the claim."),
+      location: tool.schema.string().optional(),
+      url: tool.schema.string().optional(),
+      caveat: tool.schema.string().describe("For upsertVaultEvidence: evidence limitation that must travel with the claim."),
+      supportScope: tool.schema.string().describe("For upsertVaultEvidence: scope explicitly supported by the evidence."),
+      unsupportedScope: tool.schema.string().describe("For upsertVaultEvidence: scope not supported by the evidence."),
+      strength: tool.schema.enum(["strong", "partial", "weak"]).describe("For upsertVaultEvidence: support strength."),
+    }).optional().describe("For upsertVaultEvidence: canonical evidence node to write under revela-narrative/evidence/*.md. For bindResearchFindings, only id is used as an optional override."),
+    relation: tool.schema.object({
+      id: tool.schema.string().describe("For upsertVaultRelation/removeVaultRelation: stable relation edge id."),
+      from: tool.schema.string().optional().describe("For upsertVaultRelation: source node id, e.g. claim:pilot or evidence:pilot."),
+      to: tool.schema.string().optional().describe("For upsertVaultRelation: target node id, e.g. claim:execution."),
+      type: tool.schema.enum(["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"]).optional().describe("For upsertVaultRelation: canonical relation type."),
+      rationale: tool.schema.string().optional().describe("Optional relation rationale. Do not invent; only preserve explicit semantic rationale."),
+    }).optional().describe("For deprecated upsertVaultRelation/removeVaultRelation compatibility actions. Inline ## Relations in node Markdown are canonical."),
+    relationId: tool.schema.string().optional().describe("For deprecated removeVaultRelation compatibility action."),
+    findingsFile: tool.schema.string().optional().describe("For attachResearchFindings, evaluateResearchFindings, or bindResearchFindings: workspace-relative researches/{topic}/{axis}.md findings file."),
     researchAxis: tool.schema.string().optional().describe("For attachResearchFindings: researchPlan axis to attach the findings file to. Required when filename matching would be ambiguous."),
     researchStatus: tool.schema.enum(["done", "read"]).optional().describe("For attachResearchFindings: optional explicit status to set on the matched research axis."),
     approvalNote: tool.schema.string().optional().describe("For approveNarrative or confirmDeckPlan: optional note explaining the approval, override, or deck plan confirmation."),
@@ -267,10 +338,12 @@ export default tool({
       evidenceBindingIds: tool.schema.array(tool.schema.string()).optional(),
       createdFromIssueType: tool.schema.string().optional(),
       notes: tool.schema.string().optional(),
-    })).optional().describe("For upsertResearchGaps: explicit canonical research gaps to create or update."),
+    })).optional().describe("For upsertVaultResearchGap or legacy upsertResearchGaps: explicit canonical research gaps to create or update."),
     gapStatus: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional().describe("For updateResearchGap: lifecycle status."),
     gapNotes: tool.schema.string().optional().describe("For updateResearchGap/closeResearchGap: notes or close reason."),
     evidenceBindingIds: tool.schema.array(tool.schema.string()).optional().describe("For updateResearchGap: canonical narrative evidence binding ids associated with the gap."),
+    markdownQaScope: tool.schema.enum(["touched", "affected", "full"]).optional().describe("For markdownQa: relation sync scope. Hook usage should stay touched; manual checks usually use full."),
+    markdownQaStrictness: tool.schema.enum(["authoring", "readiness", "render"]).optional().describe("For markdownQa: relation sync strictness. Render/readiness can upgrade relation sync gaps to blockers."),
   },
   async execute(args, context) {
     try {
@@ -280,6 +353,7 @@ export default tool({
 
       if (args.action === "init") {
         const discovered: SourceMaterial[] = []
+        const ingest = classifySourceMaterialIngest(state, (args.sourceMaterials ?? []) as SourceMaterial[], workspaceRoot, narrativeVaultTimestampMs(workspaceRoot))
         for (const material of (args.sourceMaterials ?? []) as SourceMaterial[]) {
           upsertSourceMaterial(state, material, material.status ?? "discovered")
           discovered.push(material)
@@ -295,18 +369,252 @@ export default tool({
           })
         }
         writeDecksState(workspaceRoot, state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, state }, null, 2)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, ingest, state }, null, 2)
       }
 
       if (args.action === "read") {
         const deckKey = state.activeDeck
         if (args.summary) {
           const deck = deckKey ? state.decks[deckKey] : undefined
-          return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, activeDeck: state.activeDeck, deck }, null, 2)
+          const vaultDiagnostics = hasNarrativeVault(workspaceRoot)
+            ? formatVaultDiagnosticReport(compileNarrativeVault(workspaceRoot, { fallbackApprovals: state.narrative?.approvals ?? [] }).diagnostics)
+            : undefined
+          const migration = getNarrativeVaultMigrationHint(workspaceRoot, state)
+          const authoringContract = hasNarrativeVault(workspaceRoot) || migration.available ? narrativeVaultAuthoringContract() : undefined
+          const narrativeInventory = hasNarrativeVault(workspaceRoot) ? buildNarrativeVaultInventory(workspaceRoot) : undefined
+          const markdownQa = hasNarrativeVault(workspaceRoot) ? runNarrativeMarkdownQa(workspaceRoot) : undefined
+          return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, activeDeck: state.activeDeck, deck, vaultDiagnostics, markdownQa, migration, authoringContract, narrativeInventory }, null, 2)
         }
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, state }, null, 2)
       }
 
+      if (args.action === "narrativeInventory" || args.action === "vaultInventory") {
+        if (!hasNarrativeVault(workspaceRoot)) {
+          const migration = getNarrativeVaultMigrationHint(workspaceRoot, state)
+          return JSON.stringify({ ok: false, path: "revela-narrative", error: "narrativeInventory requires revela-narrative/ to exist. Use initNarrativeVault or exportNarrativeVault first.", migration, authoringContract: migration.available ? narrativeVaultAuthoringContract() : undefined }, null, 2)
+        }
+        const inventory = buildNarrativeVaultInventory(workspaceRoot)
+        return JSON.stringify({ ok: inventory.ok, path: inventory.path, narrativeInventory: inventory, authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+      }
+
+      if (args.action === "markdownQa") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, path: "revela-narrative", error: "markdownQa requires revela-narrative/ to exist. Use initNarrativeVault or exportNarrativeVault first." }, null, 2)
+        const markdownQa = runNarrativeMarkdownQa(workspaceRoot, { scope: args.markdownQaScope ?? "full", strictness: args.markdownQaStrictness ?? "authoring" })
+        return JSON.stringify({ ok: markdownQa.ok, path: "revela-narrative", markdownQa, narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+      }
+
+      if (args.action === "compileNarrativeVault") {
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        const { result, diagnosticReport } = compiled
+        const markdownQa = hasNarrativeVault(workspaceRoot) ? runNarrativeMarkdownQa(workspaceRoot) : undefined
+        const narrativeInventory = hasNarrativeVault(workspaceRoot) ? buildNarrativeVaultInventory(workspaceRoot) : undefined
+        return JSON.stringify({ ok: result.ok, path: DECKS_STATE_FILE, result, diagnosticReport, markdownQa, narrativeInventory }, null, 2)
+      }
+
+      if (args.action === "exportNarrativeVault") {
+        if (hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "revela-narrative/ already exists. Edit Markdown nodes directly or move the existing vault before exporting." })
+        const narrative = state.narrative ?? normalizeNarrativeState(state)
+        const result = exportNarrativeStateToVault(workspaceRoot, narrative)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state, fallbackApprovals: narrative.approvals })
+        return JSON.stringify({
+          ok: compiled.result.ok,
+          path: "revela-narrative",
+          result,
+          files: result.files,
+          diagnostics: compiled.result.diagnostics,
+          diagnosticReport: compiled.diagnosticReport,
+          migrationNote: "Exported canonical narrative nodes to revela-narrative/. Approvals, render targets, reviews, artifact coverage, actions, deck specs, and source material records remain in DECKS.json.",
+          preservedInDecksJson: VAULT_MIGRATION_PRESERVED_IN_DECKS_JSON,
+          nextActions: [
+            "Review diagnosticReport for any source trace, evidence, relation, or approval warnings.",
+            "Edit narrative meaning through targeted vault actions or Markdown nodes, then run compileNarrativeVault.",
+            "Keep approvals, render targets, reviews, artifact coverage, actions, deck specs, and source material records in DECKS.json.",
+          ],
+        }, null, 2)
+      }
+
+      if (args.action === "initNarrativeVault") {
+        if (hasNarrativeVault(workspaceRoot)) {
+          const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+          return JSON.stringify({ ok: true, path: "revela-narrative", created: false, files: [], diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract(), nextActions: ["Inspect narrativeInventory before authoring; reuse existing ids and relation targets.", "Maintain Markdown nodes directly when useful, then run compileNarrativeVault. Use structured vault helpers only when they reduce schema risk."], narrative: compiled.result.narrative }, null, 2)
+        }
+        const result = initNarrativeVault(workspaceRoot, {
+          id: `narrative:${defaultSlug}`,
+          status: args.narrative?.status as any ?? "draft",
+          audience: args.narrative?.audience as any,
+          decision: args.narrative?.decision as any,
+          thesis: args.narrative?.thesis as any,
+        })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: result.path, created: result.created, files: result.files, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract(), nextActions: ["Inspect narrativeInventory before adding claims, evidence, relations, or research gaps; reuse existing ids where possible.", "Maintain Markdown nodes directly when useful. Use structured vault helpers for evidence binding or when they reduce schema risk.", "Treat workspace source material records as candidates until explicit evidence trace is written."], narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertVaultEvidence") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "upsertVaultEvidence requires revela-narrative/ to exist. Use initNarrativeVault first, then write explicit evidence source trace." })
+        if (!args.evidence) return JSON.stringify({ ok: false, error: "evidence is required for upsertVaultEvidence" })
+        const mutation = upsertVaultEvidenceNode(workspaceRoot, args.evidence as any)
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "bindResearchFindings") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "bindResearchFindings requires revela-narrative/ to exist. Use initNarrativeVault first, then evaluateResearchFindings." })
+        if (!args.findingsFile?.trim()) return JSON.stringify({ ok: false, error: "findingsFile is required for bindResearchFindings" })
+        const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, args.findingsFile)
+        if (bindingEval.status !== "bindable" || !bindingEval.claimId || !bindingEval.recommendedEvidenceDraft) {
+          return JSON.stringify({ ok: false, skipped: true, reason: "findings are not safely bindable", bindingEval }, null, 2)
+        }
+        const draft = bindingEval.recommendedEvidenceDraft
+        const evidence = {
+          id: args.evidence?.id?.trim() || stableEvidenceId(bindingEval.claimId, `${bindingEval.findingsFile}:${draft.quote ?? ""}`),
+          claimId: bindingEval.claimId,
+          source: draft.source,
+          sourcePath: draft.sourcePath,
+          findingsFile: draft.findingsFile ?? bindingEval.findingsFile,
+          quote: draft.quote,
+          location: draft.location,
+          url: draft.url,
+          caveat: draft.caveat,
+          supportScope: draft.supportScope,
+          unsupportedScope: draft.unsupportedScope,
+          strength: draft.strength,
+        }
+        const missing = missingBindableEvidenceFields(evidence)
+        if (missing.length > 0) return JSON.stringify({ ok: false, skipped: true, reason: "recommended evidence draft is incomplete", missingFields: missing, bindingEval }, null, 2)
+
+        const mutation = upsertVaultEvidenceNode(workspaceRoot, evidence as any)
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation, bindingEval }, null, 2)
+        const gap = exactResearchGapForBinding(state, bindingEval.findingsFile, bindingEval.claimId)
+        const gapMutation = gap
+          ? updateVaultResearchGapNode(workspaceRoot, {
+            id: gap.id,
+            status: "evidence_bound",
+            findingsFile: bindingEval.findingsFile,
+            evidenceBindingIds: [...new Set([...(gap.evidenceBindingIds ?? []), evidence.id])],
+            notes: gap.notes,
+          })
+          : undefined
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({
+          ok: compiled.result.ok,
+          path: mutation.file,
+          bindingEval,
+          mutation,
+          gapMutation: gapMutation ?? { ok: true, skipped: true, reason: "no exact single research gap matched this findings file and claim" },
+          evidence,
+          diagnostics: compiled.result.diagnostics,
+          diagnosticReport: compiled.diagnosticReport,
+          narrative: compiled.result.narrative,
+        }, null, 2)
+      }
+
+      if (args.action === "updateVaultResearchGap") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "updateVaultResearchGap requires revela-narrative/ to exist. Use updateResearchGap only in compatibility JSON workspaces." })
+        if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for updateVaultResearchGap" })
+        const mutation = updateVaultResearchGapNode(workspaceRoot, {
+          ...(args.researchGaps?.[0] as any ?? {}),
+          id: args.gapId,
+          status: args.gapStatus as any,
+          findingsFile: args.findingsFile,
+          evidenceBindingIds: args.evidenceBindingIds,
+          notes: args.gapNotes,
+        })
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation, recovery: researchGapHelperRecovery("updateVaultResearchGap", mutation.missingFields), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertVaultResearchGap") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "upsertVaultResearchGap requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const gaps = args.researchGaps?.length ? (args.researchGaps as any[]) : [undefined]
+        const mutations = []
+        for (const gap of gaps) {
+          const rawId = gap?.id ?? (gaps.length === 1 ? args.gapId : undefined)
+          const id = typeof rawId === "string" ? rawId.trim() : ""
+          if (!id) return JSON.stringify({ ok: false, error: "gapId or every researchGaps[].id is required for upsertVaultResearchGap", recovery: researchGapHelperRecovery("upsertVaultResearchGap"), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+          const mutation = updateVaultResearchGapNode(workspaceRoot, {
+            ...gap,
+            id,
+            status: args.gapStatus as any ?? gap?.status,
+            findingsFile: args.findingsFile ?? gap?.findingsFile,
+            evidenceBindingIds: args.evidenceBindingIds ?? gap?.evidenceBindingIds,
+            notes: args.gapNotes ?? gap?.notes,
+          })
+          if (!mutation.ok) return JSON.stringify({ ok: false, mutation, recovery: researchGapHelperRecovery("upsertVaultResearchGap", mutation.missingFields), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+          mutations.push(mutation)
+        }
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutations[0]?.file, mutation: mutations[0], mutations, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, authoringContract: narrativeVaultAuthoringContract(), narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertVaultRelation") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "upsertVaultRelation requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const relation = args.relation as any
+        if (!relation?.id) return JSON.stringify({ ok: false, error: "relation.id is required for upsertVaultRelation", recovery: relationHelperRecovery("upsertVaultRelation"), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+        const mutation = upsertVaultRelation(workspaceRoot, {
+          id: relation.id,
+          fromId: relation.from,
+          toId: relation.to,
+          relation: relation.type,
+          rationale: relation.rationale,
+        })
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation, recovery: relationHelperRecovery("upsertVaultRelation", mutation.missingFields), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract(), narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "removeVaultRelation") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "removeVaultRelation requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const relationId = args.relationId?.trim() || (args.relation as any)?.id?.trim()
+        if (!relationId) return JSON.stringify({ ok: false, error: "relationId or relation.id is required for removeVaultRelation", recovery: relationHelperRecovery("removeVaultRelation"), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+        const mutation = removeVaultRelation(workspaceRoot, relationId)
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation, recovery: relationHelperRecovery("removeVaultRelation", mutation.missingFields), narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract() }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrativeInventory: buildNarrativeVaultInventory(workspaceRoot), authoringContract: narrativeVaultAuthoringContract(), narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertVaultClaim") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "upsertVaultClaim requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const claim = (args.narrative?.claims?.[0] as any) ?? undefined
+        if (!claim?.id) return JSON.stringify({ ok: false, error: "narrative.claims[0].id is required for upsertVaultClaim" })
+        const relationHint = args.narrative?.claimRelations?.length
+          ? "upsertVaultClaim does not write graph edges. Add explicit ## Relations lines in the source node after checking narrativeInventory; compileNarrativeVault will generate relation ids."
+          : undefined
+        const mutation = upsertVaultClaimNode(workspaceRoot, claim)
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, relationHint, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertVaultObjection") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "upsertVaultObjection requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const objection = (args.narrative?.objections?.[0] as any) ?? undefined
+        if (!objection?.id) return JSON.stringify({ ok: false, error: "narrative.objections[0].id is required for upsertVaultObjection" })
+        const mutation = upsertVaultObjectionNode(workspaceRoot, objection)
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertVaultRisk") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "upsertVaultRisk requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const risk = (args.narrative?.risks?.[0] as any) ?? undefined
+        if (!risk?.id) return JSON.stringify({ ok: false, error: "narrative.risks[0].id is required for upsertVaultRisk" })
+        const mutation = upsertVaultRiskNode(workspaceRoot, risk)
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
+      }
+
+      if (args.action === "updateVaultCoreNarrative") {
+        if (!hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: "updateVaultCoreNarrative requires revela-narrative/ to exist. Use initNarrativeVault first." })
+        const mutation = updateVaultCoreNodes(workspaceRoot, args.narrative as any ?? {})
+        if (!mutation.ok) return JSON.stringify({ ok: false, mutation }, null, 2)
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
+      }
+
       if (args.action === "upsertDeck") {
         const deckKey = defaultSlug
         const existing = state.decks[deckKey]
@@ -342,45 +650,12 @@ export default tool({
       }
 
       if (args.action === "upsertNarrative") {
-        if (!args.narrative) return JSON.stringify({ ok: false, error: "narrative is required for upsertNarrative" })
-        const current = state.narrative ?? normalizeNarrativeState(state)
-        const merged = mergeNarrativeInput(current, args.narrative as Partial<NarrativeStateV1>)
-        const normalized = normalizeCanonicalNarrativeState(merged, state.activeDeck ?? defaultSlug)
-        if (!normalized) return JSON.stringify({ ok: false, error: "narrative could not be normalized" })
-        state.narrative = normalized
-
-        const deckKey = state.activeDeck
-        if (deckKey && state.decks[deckKey]) {
-          state = upsertDeck(state, {
-            ...state.decks[deckKey],
-            slug: deckKey,
-            audience: normalized.audience.primary || state.decks[deckKey].audience,
-            narrativeBrief: narrativeToBrief(normalized),
-          })
-        }
-
-        recordWorkspaceAction(state, {
-          type: "narrative.upserted",
-          actor: "revela-decks",
-          inputs: { hadExistingNarrative: Boolean(current), providedFields: Object.keys(args.narrative as object) },
-          outputs: {
-            narrativeId: normalized.id,
-            status: normalized.status,
-            claimCount: normalized.claims.length,
-            evidenceBindingCount: normalized.evidenceBindings.length,
-            objectionCount: normalized.objections.length,
-            riskCount: normalized.risks.length,
-          },
-          status: "success",
-          summary: `Updated canonical narrative state with ${normalized.claims.length} claim${normalized.claims.length === 1 ? "" : "s"}.`,
-          nodeIds: [normalized.id],
-        })
-
-        writeDecksState(workspaceRoot, state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, narrative: state.narrative, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined }, null, 2)
+        return JSON.stringify({ ok: false, deprecated: true, error: "upsertNarrative is deprecated. Use initNarrativeVault to create revela-narrative/, then update canonical narrative meaning through structured vault actions such as updateVaultCoreNarrative, upsertVaultClaim, upsertVaultEvidence, upsertVaultObjection, upsertVaultRisk, upsertVaultResearchGap, updateVaultResearchGap, or bindResearchFindings.", authoringContract: narrativeVaultAuthoringContract() })
       }
 
       if (args.action === "review") {
+        const qaGate = strictVaultMarkdownQaGate(workspaceRoot, "render", "review")
+        if (qaGate) return JSON.stringify(qaGate, null, 2)
         const reviewed = reviewDeckState(state, undefined, { workspaceRoot })
         const targetId = activeReviewTargetId(reviewed.state)
         const snapshot = latestReviewSnapshotForTarget(reviewed.state, targetId)
@@ -409,6 +684,8 @@ export default tool({
       }
 
       if (args.action === "compileDeckPlan") {
+        const qaGate = strictVaultMarkdownQaGate(workspaceRoot, "render", "compileDeckPlan")
+        if (qaGate) return JSON.stringify(qaGate, null, 2)
         const compiled = compileDeckPlanFromNarrative(state)
         if (compiled.result.compiled) {
           recordWorkspaceAction(compiled.state, {
@@ -461,6 +738,8 @@ export default tool({
       }
 
       if (args.action === "reviewNarrative") {
+        const qaGate = strictVaultMarkdownQaGate(workspaceRoot, "readiness", "reviewNarrative")
+        if (qaGate) return JSON.stringify(qaGate, null, 2)
         const reviewed = reviewNarrativeState(state)
         recordNarrativeReviewAction(reviewed.state, reviewed.result)
         writeDecksState(workspaceRoot, reviewed.state)
@@ -468,6 +747,8 @@ export default tool({
       }
 
       if (args.action === "approveNarrative") {
+        const qaGate = strictVaultMarkdownQaGate(workspaceRoot, "readiness", "approveNarrative")
+        if (qaGate) return JSON.stringify(qaGate, null, 2)
         const approved = approveNarrativeState(state, {
           approvedBy: args.approvalBy,
           scope: args.approvalScope,
@@ -479,6 +760,7 @@ export default tool({
       }
 
       if (args.action === "deriveResearchGaps") {
+        if (hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: forbiddenVaultCompatibilityAction("deriveResearchGaps", "deriveResearchTargets for read-only target selection, then upsertVaultResearchGap for canonical gap nodes"), authoringContract: narrativeVaultAuthoringContract() })
         const derived = deriveResearchGapsFromReadiness(state)
         writeDecksState(workspaceRoot, derived.state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: derived.result, narrative: derived.state.narrative }, null, 2)
@@ -489,7 +771,18 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result }, null, 2)
       }
 
+      if (args.action === "evaluateResearchFindings") {
+        if (!args.findingsFile?.trim()) return JSON.stringify({ ok: false, error: "findingsFile is required for evaluateResearchFindings" })
+        const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, args.findingsFile)
+        const targets = deriveResearchTargets(state, { workspaceRoot })
+        const vaultDiagnostics = hasNarrativeVault(workspaceRoot)
+          ? formatVaultDiagnosticReport(compileNarrativeVault(workspaceRoot, { fallbackApprovals: state.narrative?.approvals ?? [] }).diagnostics)
+          : undefined
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: { bindingEval, selected: targets.selected, vaultDiagnostics } }, null, 2)
+      }
+
       if (args.action === "upsertResearchGaps") {
+        if (hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: forbiddenVaultCompatibilityAction("upsertResearchGaps", "upsertVaultResearchGap for new or updated research gap nodes"), authoringContract: narrativeVaultAuthoringContract() })
         if (!args.researchGaps?.length) return JSON.stringify({ ok: false, error: "researchGaps are required for upsertResearchGaps" })
         const upserted = upsertResearchGapsInState(state, args.researchGaps as any[])
         writeDecksState(workspaceRoot, upserted.state)
@@ -497,6 +790,7 @@ export default tool({
       }
 
       if (args.action === "updateResearchGap") {
+        if (hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: forbiddenVaultCompatibilityAction("updateResearchGap", "updateVaultResearchGap or upsertVaultResearchGap"), authoringContract: narrativeVaultAuthoringContract() })
         if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for updateResearchGap" })
         const updated = updateResearchGapInState(state, {
           id: args.gapId,
@@ -510,6 +804,7 @@ export default tool({
       }
 
       if (args.action === "closeResearchGap") {
+        if (hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: forbiddenVaultCompatibilityAction("closeResearchGap", "updateVaultResearchGap with gapStatus=closed"), authoringContract: narrativeVaultAuthoringContract() })
         if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for closeResearchGap" })
         const closed = closeResearchGapInState(state, args.gapId, args.gapNotes)
         writeDecksState(workspaceRoot, closed.state)
@@ -517,6 +812,7 @@ export default tool({
       }
 
       if (args.action === "applyEvidenceCandidates") {
+        if (hasNarrativeVault(workspaceRoot)) return JSON.stringify({ ok: false, error: forbiddenVaultCompatibilityAction("applyEvidenceCandidates", "bindResearchFindings for bindable findings or upsertVaultEvidence for explicit evidence source trace"), authoringContract: narrativeVaultAuthoringContract() })
         const candidateIds = args.candidateIds ?? []
         if (candidateIds.length === 0) return JSON.stringify({ ok: false, error: "candidateIds are required for applyEvidenceCandidates" })
         const result = applyEvidenceBindings(workspaceRoot, candidateIds)

package/tools/research-save.ts

@@ -2,6 +2,7 @@ import { tool } from "@opencode-ai/plugin"
 import { mkdirSync, writeFileSync } from "fs"
 import { join } from "path"
 import { hasDecksState, readDecksState, writeDecksState } from "../lib/decks-state"
+import { evaluateResearchFindingsBinding } from "../lib/narrative-state/research-binding-eval"
 import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 
 /**
@@ -100,7 +101,9 @@ export default tool({
           summary: `Saved research findings for ${topicKey}/${fileKey}.`,
           nodeIds: [`finding:${relPath}`],
         })
+        const bindingEval = evaluateResearchFindingsBinding(state, workspaceDir, relPath)
         writeDecksState(workspaceDir, state)
+        return JSON.stringify({ ok: true, path: relPath, bindingEval })
       }
 
       return JSON.stringify({ ok: true, path: relPath })

package/tools/workspace-scan.ts

@@ -15,6 +15,7 @@ const DOC_EXTENSIONS = new Set([
 const EXCLUDE_DIRS = new Set([
   "node_modules", ".git", "dist", ".opencode",
   "researches",  // Exclude revela's own research output
+  "revela-narrative", // Exclude canonical narrative vault source files
   "designs", "domains",  // Exclude revela plugin assets
 ])