@cyber-dash-tech/revela 0.17.1 → 0.17.3

package/tools/decks.ts

@@ -1,10 +1,12 @@
 import { tool } from "@opencode-ai/plugin"
 import {
+  createEmptyDecksState,
   createDeckSpec,
   confirmDeckPlan,
   DECKS_STATE_FILE,
+  hasDecksState,
   normalizeWorkspaceDeckState,
-  readOrCreateDecksState,
+  readDecksState,
   reviewDeckState,
   upsertDeck,
   upsertSlides,
@@ -30,10 +32,11 @@ import {
   reviewNarrativeState,
 } from "../lib/narrative-state/readiness"
 import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
+import { DECK_PLAN_ARTIFACT_PATH, readDeckPlanArtifact } from "../lib/narrative-state/deck-plan-artifact"
 import { backfillSlideClaimRefsFromCoverage } from "../lib/narrative-state/coverage"
 import { closeResearchGapInState, deriveResearchGapsFromReadiness, deriveResearchTargets, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
 import { evaluateResearchFindingsBinding } from "../lib/narrative-state/research-binding-eval"
-import { stableEvidenceId } from "../lib/narrative-state/hash"
+import { computeNarrativeHash, 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"
@@ -114,10 +117,10 @@ export default tool({
   description:
     `Read and update ${DECKS_STATE_FILE}, Revela's workspace deck state file. ` +
     "Use this tool instead of writing or patching the state file directly. " +
-    "It stores workspace narrative state, active deck specs, per-slide content/layout/components, and computes narrative or deck readiness.",
+    "It stores compatibility/render state, narrative projections, active output paths, cached deck projections, approvals, reviews, artifact coverage, and readiness.",
   args: {
     action: tool.schema
-      .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"])
+      .enum(["read", "init", "initNarrativeVault", "narrativeInventory", "vaultInventory", "markdownQa", "upsertDeck", "upsertSlides", "upsertNarrative", "compileNarrativeVault", "exportNarrativeVault", "upsertVaultEvidence", "bindResearchFindings", "updateVaultResearchGap", "upsertVaultResearchGap", "upsertVaultClaim", "upsertVaultObjection", "upsertVaultRisk", "upsertVaultRelation", "removeVaultRelation", "updateVaultCoreNarrative", "compileDeckPlan", "readDeckPlan", "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."),
@@ -348,7 +351,14 @@ export default tool({
   async execute(args, context) {
     try {
       const workspaceRoot = context.directory ?? process.cwd()
-      let state = normalizeWorkspaceDeckState(readOrCreateDecksState(workspaceRoot), workspaceRoot)
+      const loadState = () => hasDecksState(workspaceRoot) ? readDecksState(workspaceRoot) : createEmptyDecksState()
+      let state = normalizeWorkspaceDeckState(loadState(), workspaceRoot)
+      const persistState = (next: DecksState) => {
+        state = normalizeWorkspaceDeckState(next, workspaceRoot)
+        if (hasDecksState(workspaceRoot)) writeDecksState(workspaceRoot, state)
+        return hasDecksState(workspaceRoot)
+      }
+      const mirrorOptions = (extra: Record<string, unknown> = {}) => hasDecksState(workspaceRoot) ? { state, ...extra } : extra
       const defaultSlug = workspaceDeckSlug(workspaceRoot)
 
       if (args.action === "init") {
@@ -368,8 +378,8 @@ export default tool({
             nodeIds: discovered.map((material) => `source:${material.path}`),
           })
         }
-        writeDecksState(workspaceRoot, state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, ingest, state }, null, 2)
+        const persisted = persistState(state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, ingest, state }, null, 2)
       }
 
       if (args.action === "read") {
@@ -404,7 +414,7 @@ export default tool({
       }
 
       if (args.action === "compileNarrativeVault") {
-        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         const { result, diagnosticReport } = compiled
         const markdownQa = hasNarrativeVault(workspaceRoot) ? runNarrativeMarkdownQa(workspaceRoot) : undefined
         const narrativeInventory = hasNarrativeVault(workspaceRoot) ? buildNarrativeVaultInventory(workspaceRoot) : undefined
@@ -415,7 +425,7 @@ export default tool({
         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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions({ fallbackApprovals: narrative.approvals }))
         return JSON.stringify({
           ok: compiled.result.ok,
           path: "revela-narrative",
@@ -435,7 +445,7 @@ export default tool({
 
       if (args.action === "initNarrativeVault") {
         if (hasNarrativeVault(workspaceRoot)) {
-          const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+          const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
           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, {
@@ -445,7 +455,7 @@ export default tool({
           decision: args.narrative?.decision as any,
           thesis: args.narrative?.thesis as any,
         })
-        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         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)
       }
 
@@ -454,7 +464,7 @@ export default tool({
         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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
       }
 
@@ -495,7 +505,7 @@ export default tool({
             notes: gap.notes,
           })
           : undefined
-        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         return JSON.stringify({
           ok: compiled.result.ok,
           path: mutation.file,
@@ -521,7 +531,7 @@ export default tool({
           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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
       }
 
@@ -544,7 +554,7 @@ export default tool({
           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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         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)
       }
 
@@ -560,7 +570,7 @@ export default tool({
           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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         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)
       }
 
@@ -570,7 +580,7 @@ export default tool({
         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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         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)
       }
 
@@ -583,7 +593,7 @@ export default tool({
           : undefined
         const mutation = upsertVaultClaimNode(workspaceRoot, claim)
         if (!mutation.ok) return JSON.stringify({ ok: false, mutation }, null, 2)
-        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, { state })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         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)
       }
 
@@ -593,7 +603,7 @@ export default tool({
         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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
       }
 
@@ -603,7 +613,7 @@ export default tool({
         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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
       }
 
@@ -611,7 +621,7 @@ export default tool({
         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 })
+        const compiled = compileCacheMirrorNarrativeVault(workspaceRoot, mirrorOptions())
         return JSON.stringify({ ok: compiled.result.ok, path: mutation.file, mutation, diagnostics: compiled.result.diagnostics, diagnosticReport: compiled.diagnosticReport, narrative: compiled.result.narrative }, null, 2)
       }
 
@@ -637,16 +647,16 @@ export default tool({
           researchPlan: (args.researchPlan as ResearchAxis[] | undefined) ?? existing?.researchPlan,
         }
         const next = upsertDeck(state, deckInput)
-        writeDecksState(workspaceRoot, next)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, deck: next.activeDeck ? next.decks[next.activeDeck] : undefined }, null, 2)
+        const persisted = persistState(next)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined }, null, 2)
       }
 
       if (args.action === "upsertSlides") {
         const deckKey = state.activeDeck || defaultSlug
         if (!args.slides) return JSON.stringify({ ok: false, error: "slides are required for upsertSlides" })
         const next = upsertSlides(state, deckKey, args.slides as SlideSpec[])
-        writeDecksState(workspaceRoot, next)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, deck: next.activeDeck ? next.decks[next.activeDeck] : undefined }, null, 2)
+        const persisted = persistState(next)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined }, null, 2)
       }
 
       if (args.action === "upsertNarrative") {
@@ -679,14 +689,15 @@ export default tool({
           summary: `Reviewed deck readiness: ${reviewed.result.ready ? "ready" : "blocked"}.`,
           nodeIds: [`artifact:${reviewed.state.decks[reviewed.result.slug]?.outputPath ?? reviewed.result.slug}`, ...(snapshot ? [snapshot.id] : [])],
         })
-        writeDecksState(workspaceRoot, reviewed.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result }, null, 2)
+        const persisted = persistState(reviewed.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: reviewed.result }, null, 2)
       }
 
       if (args.action === "compileDeckPlan") {
         const qaGate = strictVaultMarkdownQaGate(workspaceRoot, "render", "compileDeckPlan")
         if (qaGate) return JSON.stringify(qaGate, null, 2)
         const compiled = compileDeckPlanFromNarrative(state)
+        const planArtifact = compiled.result.compiled ? { path: DECK_PLAN_ARTIFACT_PATH } : undefined
         if (compiled.result.compiled) {
           recordWorkspaceAction(compiled.state, {
             type: "deck.plan_compiled",
@@ -694,23 +705,44 @@ export default tool({
             inputs: { narrativeId: compiled.state.narrative?.id, activeDeck: compiled.state.activeDeck },
             outputs: {
               narrativeHash: compiled.result.narrativeHash,
+              planArtifactPath: planArtifact?.path,
+              planningPacket: Boolean(compiled.result.planningPacket),
+              deckPlanRequirements: Boolean(compiled.result.deckPlanRequirements),
               slideCount: compiled.result.slideCount,
               outputPath: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck]?.outputPath : undefined,
             },
             status: "success",
-            summary: `Compiled deck plan from canonical narrative with ${compiled.result.slideCount} slide${compiled.result.slideCount === 1 ? "" : "s"}.`,
+            summary: "Prepared deck planning packet and deck-plan authoring requirements from canonical narrative.",
             nodeIds: [compiled.state.narrative?.id, compiled.state.activeDeck ? `artifact:${compiled.state.decks[compiled.state.activeDeck]?.outputPath ?? compiled.state.activeDeck}` : undefined].filter((item): item is string => Boolean(item)),
           })
         }
-        writeDecksState(workspaceRoot, compiled.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: compiled.result, deck: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck] : undefined, narrative: compiled.state.narrative }, null, 2)
+        const persisted = persistState(compiled.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, planArtifact, result: compiled.result, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined, narrative: state.narrative }, null, 2)
+      }
+
+      if (args.action === "readDeckPlan") {
+        const narrative = normalizeNarrativeState(state)
+        const knownNodeIds = new Set([
+          ...narrative.claims.map((claim) => claim.id),
+          ...narrative.evidenceBindings.map((binding) => binding.id),
+          ...narrative.risks.map((risk) => risk.id),
+          ...narrative.objections.map((objection) => objection.id),
+          ...(narrative.researchGaps ?? []).map((gap) => gap.id),
+        ])
+        const read = readDeckPlanArtifact(workspaceRoot, { narrativeHash: computeNarrativeHash(narrative), knownNodeIds })
+        return JSON.stringify({ ok: read.ok, planArtifact: read }, null, 2)
       }
 
       if (args.action === "confirmDeckPlan") {
-        if (args.approvalBy && args.approvalBy !== "user") return JSON.stringify({ ok: false, error: "confirmDeckPlan requires approvalBy=user" })
+        const deck = state.activeDeck ? state.decks[state.activeDeck] : undefined
+        if (!deck) return JSON.stringify({ ok: false, result: { confirmed: false, skipped: true, reason: "Cannot confirm because no current deck exists." } }, null, 2)
+        const narrative = normalizeNarrativeState(state)
+        const narrativeHash = computeNarrativeHash(narrative)
+        const read = readDeckPlanArtifact(workspaceRoot, { narrativeHash })
         const confirmed = confirmDeckPlan(state, {
           approvedBy: "user",
-          note: args.approvalNote,
+          note: args.approvalNote ?? "Deprecated confirmDeckPlan compatibility confirmation; deck-plan/ diagnostics are advisory.",
+          planHash: read.planHash,
         })
         if (confirmed.result.confirmed) {
           recordWorkspaceAction(confirmed.state, {
@@ -723,18 +755,18 @@ export default tool({
               planHash: confirmed.result.planHash,
             },
             status: "success",
-            summary: args.approvalNote?.trim() || "User confirmed the compiled deck plan.",
+            summary: args.approvalNote?.trim() || "Recorded deck-plan compatibility confirmation; deck-plan/ remains user-directed projection state.",
             nodeIds: [confirmed.state.narrative?.id, confirmed.result.slug ? `deck:${confirmed.result.slug}` : undefined].filter((item): item is string => Boolean(item)),
           })
         }
-        writeDecksState(workspaceRoot, confirmed.state)
-        return JSON.stringify({ ok: confirmed.result.confirmed, path: DECKS_STATE_FILE, result: confirmed.result, deck: confirmed.state.activeDeck ? confirmed.state.decks[confirmed.state.activeDeck] : undefined }, null, 2)
+        const persisted = persistState(confirmed.state)
+        return JSON.stringify({ ok: confirmed.result.confirmed, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: confirmed.result, planArtifact: read, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined }, null, 2)
       }
 
       if (args.action === "backfillClaimRefs") {
         const backfilled = backfillSlideClaimRefsFromCoverage(state)
-        writeDecksState(workspaceRoot, backfilled.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: backfilled.result, deck: backfilled.state.activeDeck ? backfilled.state.decks[backfilled.state.activeDeck] : undefined, narrative: backfilled.state.narrative }, null, 2)
+        const persisted = persistState(backfilled.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: backfilled.result, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined, narrative: state.narrative }, null, 2)
       }
 
       if (args.action === "reviewNarrative") {
@@ -742,8 +774,8 @@ export default tool({
         if (qaGate) return JSON.stringify(qaGate, null, 2)
         const reviewed = reviewNarrativeState(state)
         recordNarrativeReviewAction(reviewed.state, reviewed.result)
-        writeDecksState(workspaceRoot, reviewed.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result, narrative: reviewed.state.narrative }, null, 2)
+        const persisted = persistState(reviewed.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: reviewed.result, narrative: state.narrative }, null, 2)
       }
 
       if (args.action === "approveNarrative") {
@@ -755,15 +787,15 @@ export default tool({
           note: args.approvalNote,
         })
         recordNarrativeApprovalAction(approved.state, approved.result)
-        writeDecksState(workspaceRoot, approved.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: approved.result, narrative: approved.state.narrative }, null, 2)
+        const persisted = persistState(approved.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: approved.result, narrative: state.narrative }, null, 2)
       }
 
       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)
+        const persisted = persistState(derived.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: derived.result, narrative: state.narrative }, null, 2)
       }
 
       if (args.action === "deriveResearchTargets") {
@@ -785,8 +817,8 @@ export default tool({
         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)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: upserted.result, narrative: upserted.state.narrative }, null, 2)
+        const persisted = persistState(upserted.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: upserted.result, narrative: state.narrative }, null, 2)
       }
 
       if (args.action === "updateResearchGap") {
@@ -799,16 +831,16 @@ export default tool({
           evidenceBindingIds: args.evidenceBindingIds,
           notes: args.gapNotes,
         })
-        writeDecksState(workspaceRoot, updated.state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: updated.result, narrative: updated.state.narrative }, null, 2)
+        const persisted = persistState(updated.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: updated.result, narrative: state.narrative }, null, 2)
       }
 
       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)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: closed.result, narrative: closed.state.narrative }, null, 2)
+        const persisted = persistState(closed.state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, result: closed.result, narrative: state.narrative }, null, 2)
       }
 
       if (args.action === "applyEvidenceCandidates") {
@@ -835,8 +867,8 @@ export default tool({
         const preferenceType = args.preferenceType ?? "user"
         const list = state.workspace.preferences[preferenceType]
         if (!list.some((entry) => entry.trim().toLowerCase() === memory.toLowerCase())) list.push(memory)
-        writeDecksState(workspaceRoot, state)
-        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, preferenceType, memory }, null, 2)
+        const persisted = persistState(state)
+        return JSON.stringify({ ok: true, path: persisted ? DECKS_STATE_FILE : undefined, persisted, preferenceType, memory }, null, 2)
       }
 
       return JSON.stringify({ ok: false, error: `Unsupported action: ${args.action}` })

package/tools/narrative-view.ts

@@ -1,14 +1,12 @@
 import { tool } from "@opencode-ai/plugin"
-import { hasDecksState, readDecksState } from "../lib/decks-state"
-import { buildNarrativeMap } from "../lib/narrative-state/map"
 import { validateNarrativeDisplayModel, type NarrativeDisplayModel, type NarrativeViewLanguage } from "../lib/narrative-state/display"
-import { writeNarrativeMapHtml } from "../lib/commands/narrative"
+import { loadStoryMap, writeNarrativeMapHtml } from "../lib/commands/narrative"
 import { openUrl } from "../lib/edit/open"
 
 export default tool({
   description:
     "Render Revela's read-only narrative claim-flow UI from the current deterministic narrative map plus an optional localized display model. " +
-    "This tool validates display IDs against DECKS.json, opens a local HTML view, and never mutates workspace state.",
+    "This tool validates display IDs against the file-native narrative vault, opens a local HTML view, and never mutates workspace state.",
   args: {
     language: tool.schema.string().describe("UI language request from /revela story or /revela narrative. May be any language tag or language name, such as en, zh-CN, fr, de, Korean, Arabic, or Portuguese-BR."),
     narrativeHash: tool.schema.string().optional().describe("Narrative hash from the prompt projection. Used to detect stale display prompts."),
@@ -79,11 +77,10 @@ export default tool({
   async execute(args, context) {
     const workspaceRoot = context.directory ?? process.cwd()
     try {
-      if (!hasDecksState(workspaceRoot)) {
-        return JSON.stringify({ ok: false, error: "No DECKS.json found. Run /revela init first." })
-      }
       const language = args.language as NarrativeViewLanguage
-      const map = buildNarrativeMap(readDecksState(workspaceRoot))
+      const loaded = loadStoryMap(workspaceRoot)
+      if (!loaded.ok) return JSON.stringify({ ok: false, error: loaded.error, diagnostics: loaded.diagnosticsReport, diagnosticsMarkdown: loaded.diagnosticsMarkdown })
+      const map = loaded.map
       const stalePrompt = Boolean(args.narrativeHash && args.narrativeHash !== map.snapshot.narrativeHash)
       const display = validateNarrativeDisplayModel(map, args.displayModel as NarrativeDisplayModel | undefined, language)
       const htmlPath = writeNarrativeMapHtml(map, display)
@@ -92,8 +89,9 @@ export default tool({
       return JSON.stringify({ ok: true, url, path: htmlPath, narrativeHash: map.snapshot.narrativeHash, stalePrompt, fallback: false }, null, 2)
     } catch (e: any) {
       try {
-        const language = (args.language ?? "en") as NarrativeViewLanguage
-        const map = buildNarrativeMap(readDecksState(workspaceRoot))
+        const loaded = loadStoryMap(workspaceRoot)
+        if (!loaded.ok) return JSON.stringify({ ok: false, fallback: false, error: e.message || String(e), fallbackError: loaded.error, diagnostics: loaded.diagnosticsReport, diagnosticsMarkdown: loaded.diagnosticsMarkdown })
+        const map = loaded.map
         const htmlPath = writeNarrativeMapHtml(map)
         const url = `file://${htmlPath}`
         openUrl(url)