@cyber-dash-tech/revela 0.11.0 → 0.13.0

package/lib/workspace-state/graph.ts

@@ -1,5 +1,6 @@
 import { createHash } from "crypto"
 import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, ResearchAxis, SlideSpec, SourceMaterial } from "../decks-state"
+import type { NarrativeClaimRelation, NarrativeEvidenceBinding, NarrativeResearchGap, NarrativeStateV1 } from "../narrative-state/types"
 import { renderTargetId } from "./render-targets"
 import type { GraphEdge, GraphEdgeType, GraphNode, GraphNodeType, RenderTarget, WorkspaceGraph } from "./types"
 
@@ -19,7 +20,7 @@ export function projectWorkspaceGraph(state: DecksState, options: ProjectWorkspa
   for (const material of state.workspace.sourceMaterials ?? []) addSourceMaterial(builder, material)
   for (const axis of deck.researchPlan ?? []) addResearchFinding(builder, axis)
 
-  const narrativeId = addNarrative(builder, deck)
+  const narrativeId = addNarrative(builder, state, deck)
   for (const slide of deck.slides.slice().sort((a, b) => a.index - b.index)) addSlide(builder, slide)
   for (const slide of deck.slides.slice().sort((a, b) => a.index - b.index)) addSlideClaimsAndEvidence(builder, slide)
   const targets = renderTargetsForDeck(state, deck)
@@ -84,7 +85,9 @@ function addResearchFinding(builder: GraphBuilder, axis: ResearchAxis): void {
   })
 }
 
-function addNarrative(builder: GraphBuilder, deck: DeckSpec): string | undefined {
+function addNarrative(builder: GraphBuilder, state: DecksState, deck: DeckSpec): string | undefined {
+  if (hasCanonicalNarrative(state.narrative)) return addCanonicalNarrative(builder, state.narrative, deck)
+
   const brief = deck.narrativeBrief
   if (!hasNarrativeBrief(brief)) return undefined
 
@@ -122,6 +125,135 @@ function addNarrative(builder: GraphBuilder, deck: DeckSpec): string | undefined
   return narrativeId
 }
 
+function addCanonicalNarrative(builder: GraphBuilder, narrative: NarrativeStateV1, deck: DeckSpec): string {
+  addNode(builder, {
+    id: narrative.id,
+    type: "narrativeIntent",
+    label: narrative.thesis?.statement || deck.goal || narrative.id,
+    data: compactData({
+      status: narrative.status,
+      goal: deck.goal,
+      audience: narrative.audience.primary || deck.audience,
+      language: deck.language,
+      beliefBefore: narrative.audience.beliefBefore,
+      beliefAfter: narrative.audience.beliefAfter,
+      decisionOrAction: narrative.decision.action,
+      thesis: narrative.thesis?.statement,
+    }),
+  })
+
+  for (const claim of narrative.claims) {
+    addNode(builder, {
+      id: claim.id,
+      type: "claim",
+      label: claim.text,
+      data: compactData({
+        text: claim.text,
+        kind: claim.kind,
+        importance: claim.importance,
+        evidenceRequired: claim.evidenceRequired,
+        evidenceStatus: claim.evidenceStatus,
+        supportedScope: claim.supportedScope,
+        unsupportedScope: claim.unsupportedScope,
+        caveats: claim.caveats,
+        source: "canonicalNarrative",
+      }),
+    })
+    addEdge(builder, "contains", narrative.id, claim.id)
+  }
+
+  for (const binding of narrative.evidenceBindings) {
+    const supportId = addNarrativeEvidenceSupportNode(builder, binding)
+    addEdge(builder, "supports", supportId, binding.claimId, compactData({
+      strength: binding.strength,
+      source: binding.source,
+      quote: binding.quote,
+      url: binding.url,
+      sourcePath: binding.sourcePath,
+      location: binding.location,
+      findingsFile: binding.findingsFile,
+      caveat: binding.caveat,
+      supportScope: binding.supportScope,
+      unsupportedScope: binding.unsupportedScope,
+    }))
+  }
+
+  for (const relation of narrative.claimRelations ?? []) addClaimRelation(builder, relation)
+
+  for (const objection of narrative.objections) {
+    addNode(builder, {
+      id: objection.id,
+      type: "objection",
+      label: objection.text,
+      data: compactData({ text: objection.text, priority: objection.priority, response: objection.response }),
+    })
+    addEdge(builder, "contains", narrative.id, objection.id)
+    addEdge(builder, "challenges", objection.id, objection.claimId || narrative.id)
+  }
+
+  for (const risk of narrative.risks) {
+    addNode(builder, {
+      id: risk.id,
+      type: "risk",
+      label: risk.text,
+      data: compactData({ text: risk.text, severity: risk.severity, mitigation: risk.mitigation }),
+    })
+    addEdge(builder, "contains", narrative.id, risk.id)
+    addEdge(builder, "constrained_by", risk.claimId || narrative.id, risk.id)
+  }
+
+  for (const gap of narrative.researchGaps ?? []) addResearchGap(builder, narrative, gap)
+
+  return narrative.id
+}
+
+function addClaimRelation(builder: GraphBuilder, relation: NarrativeClaimRelation): void {
+  addEdge(builder, graphEdgeTypeForClaimRelation(relation.relation), relation.fromClaimId, relation.toClaimId, compactData({
+    relationId: relation.id,
+    relation: relation.relation,
+    rationale: relation.rationale,
+    source: "canonicalNarrative",
+  }))
+}
+
+function graphEdgeTypeForClaimRelation(relation: NarrativeClaimRelation["relation"]): GraphEdgeType {
+  if (relation === "constrains") return "constrained_by"
+  if (relation === "supports") return "supports"
+  return relation
+}
+
+function addResearchGap(builder: GraphBuilder, narrative: NarrativeStateV1, gap: NarrativeResearchGap): void {
+  addNode(builder, {
+    id: gap.id,
+    type: "researchGap",
+    label: gap.question,
+    data: compactData({
+      question: gap.question,
+      status: gap.status,
+      priority: gap.priority,
+      targetType: gap.targetType,
+      targetId: gap.targetId,
+      findingsFile: gap.findingsFile,
+      evidenceBindingIds: gap.evidenceBindingIds,
+      createdFromIssueType: gap.createdFromIssueType,
+      notes: gap.notes,
+    }),
+  })
+  addEdge(builder, "contains", narrative.id, gap.id)
+  addEdge(builder, "derived_from", gap.id, gapTargetNodeId(narrative, gap))
+  if (gap.findingsFile) addEdge(builder, "derived_from", gap.id, findingNodeId(gap.findingsFile), { status: gap.status })
+  for (const evidenceId of gap.evidenceBindingIds ?? []) {
+    const binding = narrative.evidenceBindings.find((item) => item.id === evidenceId)
+    if (binding) addEdge(builder, "derived_from", gap.id, binding.claimId, { evidenceBindingId: evidenceId })
+  }
+}
+
+function gapTargetNodeId(narrative: NarrativeStateV1, gap: NarrativeResearchGap): string {
+  if (gap.targetId) return gap.targetId
+  if (gap.targetType === "narrative" || gap.targetType === "decision") return narrative.id
+  return narrative.id
+}
+
 function addSlide(builder: GraphBuilder, slide: SlideSpec): void {
   addNode(builder, {
     id: slideNodeId(slide.index),
@@ -222,6 +354,29 @@ function addEvidenceSupportNode(builder: GraphBuilder, evidence: EvidenceRef): s
   return id
 }
 
+function addNarrativeEvidenceSupportNode(builder: GraphBuilder, binding: NarrativeEvidenceBinding): string {
+  if (binding.findingsFile?.trim()) {
+    const id = findingNodeId(binding.findingsFile)
+    addNode(builder, {
+      id,
+      type: "finding",
+      label: binding.findingsFile,
+      data: compactData({ findingsFile: binding.findingsFile, source: binding.source, quote: binding.quote, location: binding.location, caveat: binding.caveat }),
+    })
+    return id
+  }
+
+  const sourceKey = binding.sourcePath || binding.source || binding.url || "unknown-narrative-evidence-source"
+  const id = sourceNodeId(sourceKey)
+  addNode(builder, {
+    id,
+    type: "source",
+    label: sourceKey,
+    data: compactData({ source: binding.source, sourcePath: binding.sourcePath, url: binding.url }),
+  })
+  return id
+}
+
 function addArtifact(builder: GraphBuilder, deck: DeckSpec, target: RenderTarget, narrativeId: string | undefined, targets: RenderTarget[]): void {
   const artifactId = artifactNodeId(target.outputPath ?? deck.outputPath)
   addNode(builder, {
@@ -248,9 +403,11 @@ function renderTargetsForDeck(state: DecksState, deck: DeckSpec): RenderTarget[]
   const deckOutputPath = normalizePath(deck.outputPath)
   const htmlTargetId = renderTargetId("html_deck", deckOutputPath)
   const htmlArtifactId = artifactNodeId(deckOutputPath)
+  const narrativeId = state.narrative?.id
   const targets = (state.renderTargets ?? []).filter((target) => {
     if (target.id === htmlTargetId) return true
     if (target.type === "html_deck") return normalizePath(target.outputPath ?? "") === deckOutputPath
+    if (narrativeId && target.sourceNodeIds.includes(narrativeId)) return true
     const data = target.data ?? {}
     return data.sourceTargetId === htmlTargetId ||
       data.sourceOutputPath === deckOutputPath ||
@@ -308,6 +465,21 @@ function hasNarrativeBrief(brief: NarrativeBrief | undefined): boolean {
   )
 }
 
+function hasCanonicalNarrative(narrative: NarrativeStateV1 | undefined): narrative is NarrativeStateV1 {
+  return Boolean(
+    narrative?.audience.primary?.trim() ||
+      narrative?.audience.beliefBefore?.trim() ||
+      narrative?.audience.beliefAfter?.trim() ||
+      narrative?.decision.action?.trim() ||
+      narrative?.thesis?.statement?.trim() ||
+      narrative?.claims.length ||
+      narrative?.evidenceBindings.length ||
+      narrative?.objections.length ||
+      narrative?.risks.length ||
+      narrative?.researchGaps?.length,
+  )
+}
+
 function hasEvidenceDetail(evidence: EvidenceRef): boolean {
   return Boolean(
     evidence.quote?.trim() ||

package/lib/workspace-state/types.ts

@@ -50,6 +50,7 @@ export type GraphNodeType =
   | "risk"
   | "slide"
   | "artifact"
+  | "researchGap"
 
 export interface GraphEdge {
   id: string
@@ -64,6 +65,10 @@ export type GraphEdgeType =
   | "extracted_as"
   | "produced"
   | "supports"
+  | "leads_to"
+  | "depends_on"
+  | "contrasts_with"
+  | "answers"
   | "appears_in"
   | "challenges"
   | "constrained_by"
@@ -88,14 +93,21 @@ export type WorkspaceActionType =
   | "source.extracted"
   | "research.findings_saved"
   | "research.findings_attached"
+  | "research.gap_created"
+  | "research.gap_updated"
+  | "research.gap_closed"
+  | "narrative.upserted"
+  | "deck.plan_compiled"
+  | "artifact.coverage_backfilled"
   | "evidence.candidate_generated"
   | "evidence.binding_applied"
+  | "narrative.approved"
   | "review.performed"
   | "artifact.rendered"
 
 export interface RenderTarget {
   id: string
-  type: "html_deck" | "pdf" | "pptx" | "brief" | "appendix" | "qa_view" | "interactive_page"
+  type: "html_deck" | "pdf" | "pptx" | "brief" | "executive_brief" | "appendix" | "qa_view" | "interactive_page"
   outputPath?: string
   sourceNodeIds: string[]
   artifactVersion?: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",

package/plugin.ts

@@ -59,8 +59,10 @@ import {
   buildDesignsEditPrompt,
 } from "./lib/commands/designs-new"
 import { buildInitPrompt } from "./lib/commands/init"
+import { handleBrief, parseBriefArgs } from "./lib/commands/brief"
+import { buildNarrativeViewPrompt, handleNarrative, parseNarrativeArgs } from "./lib/commands/narrative"
 import { parseRememberArgs, buildRememberPrompt } from "./lib/commands/remember"
-import { buildReviewPrompt } from "./lib/commands/review"
+import { buildDeckPrompt, buildDeckReviewPrompt, buildReviewPrompt } from "./lib/commands/review"
 import {
   extractDeckHtmlTargetsFromPatch,
   extractPatchTextArg,
@@ -85,6 +87,7 @@ import researchImagesListTool from "./tools/research-images-list"
 import researchSaveTool from "./tools/research-save"
 import inspectionContextTool from "./tools/inspection-context"
 import inspectionResultTool from "./tools/inspection-result"
+import narrativeViewTool from "./tools/narrative-view"
 import workspaceScanTool from "./tools/workspace-scan"
 import extractDocumentMaterialsTool from "./tools/extract-document-materials"
 import qaTool from "./tools/qa"
@@ -326,6 +329,7 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DISABLE_HANDLED__")
       }
       if (sub === "init") {
+        buildPrompt({ mode: "narrative" })
         output.parts.length = 0
         output.parts.push({
           type: "text",
@@ -339,6 +343,7 @@ const server: Plugin = (async (pluginCtx) => {
           await send(parsed.error)
           throw new Error("__REVELA_REMEMBER_USAGE_HANDLED__")
         }
+        buildPrompt({ mode: "narrative" })
         output.parts.length = 0
         output.parts.push({
           type: "text",
@@ -348,9 +353,10 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "review") {
         if (param) {
-          await send("`/revela review` no longer accepts a deck name. It reviews the current workspace deck.")
+          await send("`/revela review` no longer accepts a deck name. It reviews the current workspace narrative. Use `/revela deck --review` for deck/artifact readiness.")
           throw new Error("__REVELA_REVIEW_USAGE_HANDLED__")
         }
+        buildPrompt({ mode: "narrative" })
         output.parts.length = 0
         output.parts.push({
           type: "text",
@@ -358,6 +364,55 @@ const server: Plugin = (async (pluginCtx) => {
         } as any)
         return
       }
+      if (sub === "narrative") {
+        const parsed = parseNarrativeArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_NARRATIVE_USAGE_HANDLED__")
+        }
+        if (parsed.args.raw) {
+          await handleNarrative({ workspaceRoot, openBrowser: true, language: parsed.args.language }, send)
+          throw new Error("__REVELA_NARRATIVE_HANDLED__")
+        }
+        buildPrompt({ mode: "narrative" })
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
+        } as any)
+        return
+      }
+      if (sub === "brief") {
+        const parsed = parseBriefArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_BRIEF_USAGE_HANDLED__")
+        }
+        await handleBrief({ workspaceRoot, outputPath: parsed.args.outputPath }, send)
+        throw new Error("__REVELA_BRIEF_HANDLED__")
+      }
+      if (sub === "deck") {
+        if (param && param !== "--review") {
+          await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness.")
+          throw new Error("__REVELA_DECK_USAGE_HANDLED__")
+        }
+        if (!param) {
+          buildPrompt({ mode: "deck-render" })
+          output.parts.length = 0
+          output.parts.push({
+            type: "text",
+            text: buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          } as any)
+          return
+        }
+        buildPrompt({ mode: "deck-render" })
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+        } as any)
+        return
+      }
       if (sub === "refine") {
         if (param) {
           await send("`/revela refine` does not accept a target. It opens the only HTML deck in `decks/`.")
@@ -482,6 +537,7 @@ const server: Plugin = (async (pluginCtx) => {
       "revela-research-save": researchSaveTool,
       "revela-inspection-context": inspectionContextTool,
       "revela-inspection-result": inspectionResultTool,
+      "revela-narrative-view": narrativeViewTool,
       "revela-workspace-scan": workspaceScanTool,
       "revela-extract-document-materials": extractDocumentMaterialsTool,
       "revela-qa": qaTool,

package/skill/NARRATIVE_SKILL.md

@@ -0,0 +1,64 @@
+---
+name: revela-narrative
+description: Build trusted narrative readiness before rendering deck artifacts
+compatibility: opencode
+---
+
+# Revela — Narrative Workspace
+
+You help the user turn source materials, research, and intent into a trusted communication narrative before any deck is rendered.
+
+Default mode is narrative-first. Do not generate HTML slides, choose visual layouts, fetch design components, or ask for slide count unless the user explicitly enters a deck-render workflow.
+
+## Core Job
+
+Build and review the narrative state around:
+- primary audience and stakeholder context
+- audience belief before and desired belief after
+- decision or action required
+- thesis or central recommendation
+- central claims and their evidence boundaries
+- objections, risks, assumptions, caveats, and unsupported scope
+- narrative approval state and whether approval is stale
+
+## Workspace State
+
+Use `DECKS.json` as Revela's current compatibility workspace-state file. Do not write or patch it directly.
+
+Use `revela-decks` for state operations:
+- `read` to inspect current workspace state
+- `init` to register discovered source material candidates during workspace initialization
+- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, and risks
+- `upsertDeck` or `upsertSlides` only when explicitly needed by a deck/artifact workflow prompt
+- `reviewNarrative` to run deterministic narrative readiness
+- `approveNarrative` only when the user explicitly approves or requests an override
+
+Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, or saved research actions as narrative approval.
+
+## Narrative Review Rules
+
+When reviewing, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
+
+Use this report shape:
+- `Narrative readiness: <status>`
+- `Narrative hash: <hash>` when available
+- blockers first, with issue type, claim text when available, and suggested next action
+- warnings second, as residual risks
+- approval state last, clearly distinguishing `ready_for_approval`, `approved`, stale approval, and render override
+
+If evidence is missing, say what is missing and what should happen next. Do not invent quotes, sources, page locations, URLs, caveats, or research findings.
+
+If research findings were saved but not attached or bound, describe them as unattached research state, not proof.
+
+If the narrative is ready for approval, ask the user whether to approve or revise it. Do not approve automatically.
+
+## Boundaries
+
+- Do not write or overwrite `decks/*.html` in narrative mode.
+- Do not call `revela-decks review` in narrative mode; that is the deck/artifact gate.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks.
+- Do not fetch design CSS, layouts, components, chart rules, or HTML skeletons in narrative mode.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+- Do not infer long-term user preferences from one-off tasks.
+
+When the user wants deck/artifact readiness, direct them to `/revela deck --review`. When they want to render a deck, wait for the explicit deck workflow.