@cyber-dash-tech/revela 0.8.9 → 0.9.0

package/lib/agents/narrative-reviewer-prompt.ts

@@ -0,0 +1,143 @@
+/**
+ * Revela Narrative Reviewer — system prompt
+ *
+ * Injected via plugin config hook into the `revela-narrative-reviewer` subagent.
+ * The NARRATIVE_REVIEWER_SIGNATURE is used by the system.transform hook to
+ * detect this agent and skip injecting the SKILL+DESIGN deck-writing prompt.
+ */
+
+export const NARRATIVE_REVIEWER_SIGNATURE = "[[REVELA-NARRATIVE-REVIEWER]]"
+
+export const NARRATIVE_REVIEWER_PROMPT = `${NARRATIVE_REVIEWER_SIGNATURE}
+
+# Revela Narrative Reviewer
+
+You are a specialized read-only narrative reviewer for Revela.
+Your sole job is to run a fixed narrative rubric against the narrative brief and
+slide-plan alignment for a workspace deck. You do NOT write state, generate
+slides, rewrite the deck, or decide authoritative write readiness.
+
+---
+
+## Mission
+
+Given a review brief from the primary agent, assess whether the current deck's
+\`narrativeBrief\`, slide plan, narrative roles, and evidence references pass the
+fixed rubric below.
+
+Prefer repeatability over creativity. You are not a brainstorming partner, copy
+editor, or slide-polish agent. Do not search for optional improvements when the
+rubric passes.
+
+---
+
+## Allowed Context
+
+- Use \`revela-decks\` action \`read\` to inspect \`DECKS.json\`.
+- Read existing workspace files only when the primary brief points to them or when
+  they are referenced by slide evidence, \`sourceMaterials\`, or research findings.
+- You may read existing \`researches/{topic}/*.md\` files when they are referenced
+  by \`slides[].evidence[]\` or \`researchPlan[].findingsFile\`.
+- Treat \`revela-decks review\` as the authoritative readiness gate owned by the
+  primary agent and tool layer. Your critique is advisory only.
+
+---
+
+## Hard Boundaries
+
+- NEVER write, patch, or edit any file.
+- NEVER call \`revela-decks\` actions \`init\`, \`upsertDeck\`, \`upsertSlides\`, \`review\`, or \`remember\`.
+- NEVER call \`revela-research-save\`, \`revela-media-save\`, or any asset-writing tool.
+- NEVER generate, write, patch, or edit \`decks/*.html\`.
+- NEVER use \`websearch\` or \`webfetch\`; critique only from existing workspace state and files.
+- NEVER invent evidence, quotes, page references, URLs, stakeholder beliefs, objections, or risks.
+- NEVER claim the deck is ready or blocked. Only the primary agent reports readiness from \`revela-decks review\`.
+
+---
+
+## Review Method
+
+1. Read the current deck state with \`revela-decks\` action \`read\`.
+2. Inspect \`narrativeBrief\`, deck goal, audience, required decision/action, slide titles, purposes, narrative roles, content, and evidence references.
+3. Read referenced research findings only when needed to evaluate overclaim or support concerns.
+4. Run the rubric in the exact order below.
+5. Produce only rubric-tied findings with stable IDs. If all checks pass, output exactly \`Findings: none\`.
+
+---
+
+## Stable Rubric
+
+Evaluate only these checks, in this order:
+
+1. \`NB-001\` Narrative brief completeness
+   - Trigger only when a substantial decision deck lacks enough \`narrativeBrief\` fields to evaluate story intent.
+   - Relevant fields: \`audienceBeliefBefore\`, \`audienceBeliefAfter\`, \`decisionOrAction\`, \`narrativeArc\`, \`keyClaims\`, \`objections\`, and \`risks\`.
+
+2. \`AB-001\` Audience belief shift not reflected
+   - Trigger only when \`audienceBeliefBefore\` or \`audienceBeliefAfter\` is present but the opener/early context or close/ask does not reflect that belief shift.
+
+3. \`KC-001\` Key claim not represented in slides
+   - Trigger only when a \`narrativeBrief.keyClaims[]\` item has no clear corresponding slide content or role.
+
+4. \`OBJ-001\` Objection not handled
+   - Trigger only when \`narrativeBrief.objections[]\` exists but no slide addresses the objection, caveat, risk, tradeoff, or response.
+
+5. \`RISK-001\` Risk or assumption not carried
+   - Trigger only when \`narrativeBrief.risks[]\` exists but no slide carries the risk, assumption, caveat, or tradeoff.
+
+6. \`ASK-001\` Decision/action not reflected in ask
+   - Trigger only when \`narrativeBrief.decisionOrAction\` exists but the ending, close, recommendation, or ask does not make the action concrete enough for the audience.
+
+7. \`EV-001\` Recommendation overreaches evidence
+   - Trigger only when a recommendation, investment conclusion, or strong claim is materially stronger than the recorded slide evidence or cited research findings.
+
+8. \`FLOW-001\` Declared narrative arc is broken
+   - Trigger only when the slide sequence materially violates \`narrativeBrief.narrativeArc\` or jumps from context to ask/recommendation without sufficient tension, evidence, or risk handling.
+
+Do not create new IDs. Do not rename IDs. Do not output duplicate findings for the
+same root issue; choose the first matching rubric ID in the order above.
+
+---
+
+## Stability Rules
+
+- Do not brainstorm optional improvements.
+- Do not suggest copy edits, slide polish, stronger phrasing, or extra examples unless tied to one stable rubric ID.
+- Do not output a finding just because something could be clearer. Output only when the current deck state fails a rubric check.
+- Do not introduce new advisory suggestions after a prior issue appears addressed by the current slide specs.
+- Do not change IDs or severity between runs for the same underlying issue.
+- If all rubric checks pass, write exactly \`Findings: none\` and stop after the required closing line.
+
+---
+
+## Output Format
+
+Start exactly with:
+
+\`Narrative review complete.\`
+
+Then include:
+
+\`Findings:\`
+
+If all rubric checks pass, write exactly:
+
+\`Findings: none\`
+
+For each rubric finding, use this structure:
+- \`id\`: one of \`NB-001\`, \`AB-001\`, \`KC-001\`, \`OBJ-001\`, \`RISK-001\`, \`ASK-001\`, \`EV-001\`, or \`FLOW-001\`
+- \`severity\`: \`advisory\` or \`risk\`
+- \`area\`: one of \`narrativeBrief\`, \`keyClaim\`, \`objection\`, \`risk\`, \`decisionAction\`, \`audienceBelief\`, \`evidenceOverreach\`, or \`flow\`
+- \`finding\`: concise description of the narrative issue
+- \`briefField\`: related \`narrativeBrief\` field, or \`none\`
+- \`slideRefs\`: slide indexes/titles involved, or \`none\`
+- \`evidenceConcern\`: evidence/source concern if any, or \`none\`
+- \`suggestedAction\`: specific next improvement
+
+Do not include general praise, a summary of strengths, or optional pre-write
+improvements outside the finding structure.
+
+End exactly with:
+
+\`No direct state changes were made.\`
+`

package/lib/commands/review.ts

@@ -15,10 +15,12 @@ export function buildReviewPrompt({
 
 Goal:
 - Use ${DECKS_STATE_FILE} as the source of truth for whether the current workspace deck is ready to be written to \`decks/*.html\`.
-- Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, and production status.
+- Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, production status, and the 0.9 narrative compiler brief when available.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.
-- Treat this as an evidence and lightweight narrative readiness review, not only a checklist review: unsupported numbers, market sizing, recommendations, competitor comparisons, technical assertions, investment conclusions, weak so-what, missing risk/assumption handling, or abrupt narrative transitions should be made visible before writing.
+- Treat this as an evidence and Narrative Compiler readiness review, not only a checklist review: unsupported numbers, market sizing, recommendations, competitor comparisons, technical assertions, investment conclusions, missing audience belief change, unclear decision/action, unproven key claims, unhandled objections, weak so-what, missing risk/assumption handling, or abrupt narrative transitions should be made visible before writing.
+- For substantial decision decks, use the read-only Task subagent \`revela-narrative-reviewer\` for independent rubric-based critique of narrative brief and slide-plan alignment. Do not self-certify semantic narrative quality in the primary agent.
+- Treat \`revela-narrative-reviewer\` findings as advisory critique only. Do not represent them as \`revela-decks\` readiness issues, blockers, or authoritative \`writeReadiness\`.
 - Treat source trace mapping as part of evidence readiness: when research findings have been read, relevant findings should appear in slide-level \`slides[].evidence[]\` records rather than only in raw research files.
 
 Current state:
@@ -33,14 +35,16 @@ Workspace boundary rules:
 
 Workflow:
 1. Call \`revela-decks\` with action \`read\` for the current workspace deck.
-2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, and researchPlan. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
+2. If no current deck exists but the conversation contains enough deck context, call \`revela-decks\` action \`upsertDeck\` with goal, outputPath, theme, requiredInputs, researchPlan, and narrativeBrief if the story intent is clear. Do not invent or ask for a deck key; the tool uses the workspace folder name internally.
 3. If \`researchPlan[].status\` is \`done\` or \`read\` and \`researchPlan[].findingsFile\` exists, verify that evidence-sensitive slide claims are backed by compact \`slides[].evidence[]\` records that reference the relevant findings file or source material where known.
 4. If a user-confirmed slide plan is available, call \`revela-decks\` action \`upsertSlides\` with every slide's title, purpose, narrativeRole, layout, components, structured content, evidence, visuals, and status. Use only lightweight narrativeRole values that are clear from the plan: \`context\`, \`tension\`, \`evidence\`, \`recommendation\`, \`risk\`, \`ask\`, \`appendix\`, or \`close\`.
 5. Prefer evidence records with \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, \`caveat\`, \`extractedTextPath\`, or \`extractedManifestPath\` when those fields are known from research files or extracted workspace materials.
 6. Do not invent quotes, page references, locations, URLs, caveats, or extraction paths. If source trace is missing, preserve the blocker or warning and report exactly what trace is needed.
 7. Only set requiredInputs fields true when explicit conversation state, files read, research findings read, selected design, fetched layouts/components, or user confirmation supports them. Do not infer completion.
-8. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
-9. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible.
+8. For substantial decision decks, preserve a compact \`narrativeBrief\` through \`upsertDeck\` when the conversation or confirmed plan supports it. Do not invent stakeholder beliefs, objections, or risks; leave gaps visible if unknown.
+9. For substantial decision decks, launch the Task subagent with \`subagent_type: "revela-narrative-reviewer"\` after deck/slides are up to date. Ask it to read the current \`DECKS.json\`, run only its fixed rubric, use stable finding IDs, return \`Findings: none\` when all checks pass, and avoid optional pre-write improvements. Do not ask it to write state, call \`revela-decks review\`, or produce HTML.
+10. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` plus structured readiness issues for the current workspace deck.
+11. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool. If warnings exist, list them after blockers as residual risks; separate evidence/source warnings from narrative warnings when possible. If the reviewer returned findings, include them in a separate \`Narrative reviewer notes\` section and label them advisory.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -52,6 +56,7 @@ Minimum conditions for \`ready\`:
 - ${DECKS_STATE_FILE} contains per-slide specs with content, layout, components, and evidence where applicable.
 - Evidence-sensitive slide claims have compact evidence references with source trace where available. Numeric claims and strong recommendations should not be unsupported or source-only when trace exists.
 - Multi-slide decision decks have a practical narrative flow: context/tension before evidence, recommendations after support, risk or assumption handling when recommending action, and a clear so-what or ask at the end. Narrative gaps are normally warnings, not hard blockers.
+- Substantial decision decks should have a compact \`narrativeBrief\` that states the intended audience belief change, required decision/action, key claims, likely objections, and risks/assumptions. Missing fields are narrative warnings, not hard blockers.
 - The needed design layouts and components have been fetched with \`revela-designs read\`.
 - No unresolved blockers remain.
 
@@ -61,6 +66,7 @@ Report format:
 - If warnings exist but the deck is otherwise ready, say the deck can be written but note the residual risks.
 - Report \`narrative_gap\` warnings as story-structure risks such as weak so-what, missing risk/assumption handling, conclusion before support, missing audience framing, or abrupt transition.
 - Do not invent evidence or silently downgrade blockers. Use the tool result as authoritative.
+- Do not convert \`revela-narrative-reviewer\` advisory findings into tool readiness issues. Keep them separate from \`revela-decks review\` blockers and warnings, and preserve the reviewer's stable finding IDs when reporting them.
 - When reporting weak evidence, say whether the missing trace is \`findingsFile\`, \`sourcePath\`, \`location\`, \`quote\`, \`url\`, or \`caveat\` if that is clear from the reviewed materials.
 
 Rules:

package/lib/decks-state.ts

@@ -58,6 +58,7 @@ export interface DeckSpec {
   audience?: string
   language?: string
   outputPath: string
+  narrativeBrief?: NarrativeBrief
   theme: {
     design?: string
     domain?: string
@@ -73,6 +74,16 @@ export interface DeckSpec {
   }
 }
 
+export interface NarrativeBrief {
+  audienceBeliefBefore?: string
+  audienceBeliefAfter?: string
+  decisionOrAction?: string
+  narrativeArc?: string
+  keyClaims: string[]
+  objections: string[]
+  risks: string[]
+}
+
 export interface RequiredInputs {
   topicClarified: boolean
   audienceClarified: boolean
@@ -242,6 +253,7 @@ export function createDeckSpec(input: Partial<DeckSpec> & { slug: string }): Dec
     audience: input.audience,
     language: input.language,
     outputPath: normalizeDeckPath(input.outputPath || `decks/${slug}.html`),
+    narrativeBrief: normalizeNarrativeBrief(input.narrativeBrief),
     theme: input.theme ?? {},
     requiredInputs: defaultRequiredInputs(input.requiredInputs),
     researchPlan: input.researchPlan ?? [],
@@ -468,6 +480,7 @@ function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksSta
 function compactDeckForPrompt(deck: DeckSpec): DeckSpec {
   return {
     ...deck,
+    narrativeBrief: compactNarrativeBriefForPrompt(deck.narrativeBrief),
     slides: deck.slides.map((slide) => ({
       ...slide,
       content: {
@@ -480,6 +493,19 @@ function compactDeckForPrompt(deck: DeckSpec): DeckSpec {
   }
 }
 
+function compactNarrativeBriefForPrompt(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
+  if (!brief) return undefined
+  return {
+    audienceBeliefBefore: truncatePromptText(brief.audienceBeliefBefore),
+    audienceBeliefAfter: truncatePromptText(brief.audienceBeliefAfter),
+    decisionOrAction: truncatePromptText(brief.decisionOrAction),
+    narrativeArc: truncatePromptText(brief.narrativeArc),
+    keyClaims: brief.keyClaims.map((claim) => truncatePromptText(claim)).filter(Boolean) as string[],
+    objections: brief.objections.map((objection) => truncatePromptText(objection)).filter(Boolean) as string[],
+    risks: brief.risks.map((risk) => truncatePromptText(risk)).filter(Boolean) as string[],
+  }
+}
+
 function compactEvidenceForPrompt(evidence: EvidenceRef): EvidenceRef {
   return {
     ...evidence,
@@ -621,6 +647,53 @@ function computeNarrativeReadinessIssues(deck: DeckSpec): ReadinessIssue[] {
   const issues: ReadinessIssue[] = []
   const slides = deck.slides.filter((slide) => slide.index > 0).sort((a, b) => a.index - b.index)
   if (slides.length === 0) return issues
+  const decisionOriented = isDecisionOrientedDeck(deck, slides)
+
+  if (decisionOriented && !hasNarrativeBriefContent(deck.narrativeBrief)) {
+    issues.push(warningIssue(
+      "narrative_gap",
+      "Narrative brief is missing for a decision-oriented deck",
+      "Add a 0.9 narrativeBrief with audience belief before/after, decisionOrAction, narrativeArc, keyClaims, objections, and risks so review can compile the deck against explicit story intent.",
+    ))
+  }
+
+  if (decisionOriented && deck.narrativeBrief) {
+    if (!deck.narrativeBrief.audienceBeliefAfter?.trim()) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Narrative brief is missing the intended audience belief after the deck",
+        "Set narrativeBrief.audienceBeliefAfter so the deck can be reviewed against the belief change it is meant to create.",
+      ))
+    }
+    if (!deck.narrativeBrief.decisionOrAction?.trim() && slides.some((slide) => isAskSlide(slide) || isRecommendationSlide(slide))) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Narrative brief is missing the decision or action the deck should drive",
+        "Set narrativeBrief.decisionOrAction so recommendation and ask slides have an explicit communication target.",
+      ))
+    }
+    if (deck.narrativeBrief.keyClaims.length === 0 && slides.some(isRecommendationSlide)) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Narrative brief has no key claims for the recommendation to prove",
+        "Add narrativeBrief.keyClaims that capture the main claims the deck must support with slide evidence.",
+      ))
+    }
+    if (deck.narrativeBrief.objections.length === 0 && slides.some((slide) => isAskSlide(slide) || isRecommendationSlide(slide))) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Narrative brief has no stakeholder objections to handle",
+        "Add likely objections or questions to narrativeBrief.objections so the story can anticipate resistance before the ask.",
+      ))
+    }
+    if (deck.narrativeBrief.risks.length === 0 && slides.some(isRecommendationSlide)) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Narrative brief has no risks, assumptions, or tradeoffs for the recommendation",
+        "Add risks, assumptions, caveats, or tradeoffs to narrativeBrief.risks so the recommendation does not overclaim certainty.",
+      ))
+    }
+  }
 
   if (slides.length >= 4 && slides.every((slide) => !slide.narrativeRole)) {
     issues.push(warningIssue(
@@ -700,6 +773,26 @@ function computeNarrativeReadinessIssues(deck: DeckSpec): ReadinessIssue[] {
   return issues
 }
 
+function isDecisionOrientedDeck(deck: DeckSpec, slides: SlideSpec[]): boolean {
+  return Boolean(
+    deck.narrativeBrief?.decisionOrAction?.trim() ||
+      slides.some((slide) => isAskSlide(slide) || isRecommendationSlide(slide)) ||
+      /\b(decision|approve|approval|recommend(?:ation)?|go\/?no-go|action)\b|决策|批准|建议|行动/.test(deck.goal.toLowerCase()),
+  )
+}
+
+function hasNarrativeBriefContent(brief: NarrativeBrief | undefined): boolean {
+  return Boolean(
+    brief?.audienceBeliefBefore?.trim() ||
+      brief?.audienceBeliefAfter?.trim() ||
+      brief?.decisionOrAction?.trim() ||
+      brief?.narrativeArc?.trim() ||
+      brief?.keyClaims.length ||
+      brief?.objections.length ||
+      brief?.risks.length,
+  )
+}
+
 function blockerIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
   return { type, severity: "blocker", message, suggestedAction, ...extra }
 }
@@ -839,6 +932,38 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
     .sort((a, b) => a.index - b.index)
 }
 
+function normalizeNarrativeBrief(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
+  if (!brief) return undefined
+  const normalized: NarrativeBrief = {
+    audienceBeliefBefore: cleanOptionalText(brief.audienceBeliefBefore),
+    audienceBeliefAfter: cleanOptionalText(brief.audienceBeliefAfter),
+    decisionOrAction: cleanOptionalText(brief.decisionOrAction),
+    narrativeArc: cleanOptionalText(brief.narrativeArc),
+    keyClaims: normalizeTextList(brief.keyClaims),
+    objections: normalizeTextList(brief.objections),
+    risks: normalizeTextList(brief.risks),
+  }
+  if (
+    !normalized.audienceBeliefBefore &&
+    !normalized.audienceBeliefAfter &&
+    !normalized.decisionOrAction &&
+    !normalized.narrativeArc &&
+    normalized.keyClaims.length === 0 &&
+    normalized.objections.length === 0 &&
+    normalized.risks.length === 0
+  ) return undefined
+  return normalized
+}
+
+function normalizeTextList(values: string[] | undefined): string[] {
+  return [...new Set((values ?? []).map(cleanOptionalText).filter(Boolean) as string[])]
+}
+
+function cleanOptionalText(value: string | undefined): string | undefined {
+  const text = String(value ?? "").trim()
+  return text || undefined
+}
+
 function hasSlideContent(slide: SlideSpec): boolean {
   const content = slide.content ?? {}
   return Boolean(

package/package.json

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

package/plugin.ts

@@ -87,6 +87,7 @@ import pdfTool from "./tools/pdf"
 import pptxTool from "./tools/pptx"
 import createEditTool from "./tools/edit"
 import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research-prompt"
+import { NARRATIVE_REVIEWER_PROMPT, NARRATIVE_REVIEWER_SIGNATURE } from "./lib/agents/narrative-reviewer-prompt"
 import { formatReport, runComplianceQA } from "./lib/qa"
 import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
@@ -204,7 +205,7 @@ const server: Plugin = (async (pluginCtx) => {
   }
 
   return {
-    // ── Register /revela command + revela-research subagent ───────────────
+    // ── Register /revela command + Revela subagents ───────────────────────
     config: async (opencodeConfig) => {
       opencodeConfig.command ??= {}
       opencodeConfig.command["revela"] = {
@@ -235,6 +236,24 @@ const server: Plugin = (async (pluginCtx) => {
       // Give revela-research explicit websearch allow (overrides global deny below)
       ;(opencodeConfig.agent["revela-research"].permission as any).websearch = "allow"
 
+      // Register the read-only narrative reviewer subagent.
+      // It can inspect workspace state and referenced files, but cannot write or browse.
+      opencodeConfig.agent["revela-narrative-reviewer"] = {
+        description: "Revela narrative reviewer — read-only critique of narrative brief and slide-plan alignment",
+        mode: "subagent",
+        prompt: NARRATIVE_REVIEWER_PROMPT,
+        permission: {
+          edit: "deny",
+          bash: {
+            "*": "deny",
+            "ls *": "allow",
+            "ls": "allow",
+          },
+          webfetch: "deny",
+          websearch: "deny",
+        } as any,
+      }
+
       // Block websearch for the primary agent globally.
       // permission.ask hook is not triggered by OpenCode (no R.trigger call in binary).
       // tool.execute.before throw is swallowed (trigger().catch(()=>{})).
@@ -481,7 +500,7 @@ const server: Plugin = (async (pluginCtx) => {
 
     // ── Inject three-layer prompt when enabled ─────────────────────────────
     // Skip injection for:
-    //   1. revela-research subagent (has its own research-focused prompt)
+    //   1. Revela subagents (they have focused prompts)
     //   2. OpenCode internal agents (title, summary, compaction)
     "experimental.chat.system.transform": async (input, output) => {
       if (!ctx.enabled) return
@@ -498,6 +517,10 @@ const server: Plugin = (async (pluginCtx) => {
         }
         ctx.isResearchAgent = false
 
+        // Skip revela-narrative-reviewer subagent — it is read-only critique,
+        // not a deck-writing agent and not a research agent.
+        if (systemText.includes(NARRATIVE_REVIEWER_SIGNATURE)) return
+
         // Skip OpenCode internal system agents (title generator, summary, compaction)
         if (INTERNAL_AGENT_SIGNATURES.some((sig) => systemText.includes(sig))) return
 

package/skill/SKILL.md

@@ -83,6 +83,7 @@ Create or update the active deck in `DECKS.json` through `revela-decks` actions
 `upsertDeck` and `upsertSlides`. Keep the deck spec current as work progresses:
 - `goal` — purpose and decision/context
 - `audience`, `language`, `outputPath`, and `theme`
+- `narrativeBrief` — for substantial decision decks, the 0.9 compiler brief: audience belief before/after, decisionOrAction, narrativeArc, keyClaims, objections, and risks
 - `requiredInputs` — checklist state for prewrite readiness
 - `researchPlan` — axes, status, and findings files
 - `slides` — confirmed per-slide title, purpose, layout, components, content, evidence, visuals, and status
@@ -200,6 +201,26 @@ state updates. Do not write temporary hypotheses, unsupported conclusions,
 secrets, or inferred user preferences. User and workflow preferences require
 explicit user intent to remember.
 
+#### Narrative Review via `revela-narrative-reviewer`
+
+`revela-narrative-reviewer` is a read-only OpenCode subagent, **not a tool**.
+Launch it through the Task tool with `subagent_type: "revela-narrative-reviewer"`
+when a substantial decision deck needs independent rubric-based critique of the
+Narrative Compiler brief and slide-plan alignment.
+
+Use it after the narrative brief and slide specs are recorded in `DECKS.json`,
+and before treating narrative quality as reviewed. The primary agent should not
+self-certify semantic narrative quality. `revela-decks review` remains the
+authoritative write-readiness gate; reviewer findings are advisory notes only.
+The reviewer uses stable finding IDs such as `NB-001`, `KC-001`, `ASK-001`, and
+`EV-001`. If the fixed rubric passes, it should return `Findings: none` rather
+than inventing optional improvements.
+
+The reviewer may read `DECKS.json`, slide specs, evidence refs, and existing
+`researches/{workspace-key}/*.md` files referenced by the deck. It must not write
+state, call `upsertDeck`, call `upsertSlides`, call `revela-decks review`, use
+websearch/webfetch, or generate/edit HTML.
+
 #### AI Knowledge and User Questions
 
 Use AI knowledge only to fill remaining gaps around verified sources. Mark it
@@ -213,6 +234,8 @@ already checked and what specific missing information is needed.
 
 - **NEVER** use `websearch` directly from the primary agent; delegate web research to `revela-research` subagents
 - **NEVER** call `revela-research` as a tool; use Task with `subagent_type: "revela-research"`
+- **NEVER** call `revela-narrative-reviewer` as a tool; use Task with `subagent_type: "revela-narrative-reviewer"`
+- **NEVER** present `revela-narrative-reviewer` findings as authoritative `revela-decks review` blockers or readiness issues
 - **NEVER** collapse distinct research axes into one broad agent brief when parallel focused briefs would be clearer
 - **ALWAYS** use `revela-decks` action `read` before deciding what research is needed
 - **ALWAYS** read each `researches/{workspace-key}/{axis}.md` after agents complete
@@ -287,8 +310,17 @@ core rules and the visual design below.
 
 ### Phase 4 — Presentation Plan
 
-After all research is complete and findings have been read, present a detailed
-slide plan to the user **before writing any HTML**.
+After all research is complete and findings have been read, present a compact narrative brief
+and a detailed slide plan to the user **before writing any HTML**.
+
+For substantial decision decks, first summarize the Narrative Compiler brief:
+- Audience belief before: what the audience currently believes, assumes, or does not yet understand
+- Audience belief after: what the audience should believe or understand after the deck
+- Decision/action: the approval, decision, behavior, or next step the deck should drive
+- Narrative arc: the intended story path, such as context -> tension -> evidence -> recommendation -> risk -> ask
+- Key claims: the main claims the deck must prove
+- Likely objections: stakeholder resistance or questions the story should handle
+- Risks/assumptions: caveats, tradeoffs, or uncertainty that should travel with the recommendation
 
 Format the plan as a markdown table:
 
@@ -320,8 +352,9 @@ Then ask:
 - On change request → update the table and ask again
 
 After the user confirms the slide plan, update `DECKS.json` through `revela-decks`:
-- Call `upsertDeck` to mark completed `requiredInputs` only when explicitly satisfied.
+- Call `upsertDeck` to preserve `narrativeBrief` when available and mark completed `requiredInputs` only when explicitly satisfied.
 - Call `upsertSlides` with the confirmed per-slide content, narrativeRole, layout, components, and evidence.
+- For substantial decision decks, use Task with `subagent_type: "revela-narrative-reviewer"` for read-only rubric-based critique of narrativeBrief and slide-plan alignment. Ask for stable finding IDs and `Findings: none` when the rubric passes; do not ask the reviewer to write state, determine readiness, or brainstorm optional improvements.
 - Keep write readiness blocked until Phase 5 calls `revela-decks review` and the tool returns ready.
 
 ---

package/tools/decks.ts

@@ -10,6 +10,7 @@ import {
   writeDecksState,
   workspaceDeckSlug,
   type DeckSpec,
+  type NarrativeBrief,
   type RequiredInputs,
   type ResearchAxis,
   type SourceMaterial,
@@ -31,6 +32,15 @@ export default tool({
     audience: tool.schema.string().optional().describe("For upsertDeck: deck audience."),
     language: tool.schema.string().optional().describe("For upsertDeck: deck language."),
     outputPath: tool.schema.string().optional().describe("For upsertDeck: target output path, normally decks/{workspace-name}.html."),
+    narrativeBrief: tool.schema.object({
+      audienceBeliefBefore: tool.schema.string().optional().describe("What the audience currently believes, assumes, or does not yet understand."),
+      audienceBeliefAfter: tool.schema.string().optional().describe("What the audience should believe or understand after the deck."),
+      decisionOrAction: tool.schema.string().optional().describe("The decision, approval, action, or behavioral change the deck is meant to drive."),
+      narrativeArc: tool.schema.string().optional().describe("Compact story arc, such as context -> tension -> evidence -> recommendation -> ask."),
+      keyClaims: tool.schema.array(tool.schema.string()).optional().describe("Main claims the deck must prove or communicate."),
+      objections: tool.schema.array(tool.schema.string()).optional().describe("Likely stakeholder objections or questions the narrative should handle."),
+      risks: tool.schema.array(tool.schema.string()).optional().describe("Risks, assumptions, caveats, or tradeoffs that should travel with the narrative."),
+    }).optional().describe("For upsertDeck: 0.9 Narrative Compiler brief used to review story intent before writing."),
     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."),
@@ -140,6 +150,7 @@ export default tool({
           audience: args.audience ?? existing?.audience,
           language: args.language ?? existing?.language,
           outputPath: args.outputPath ?? existing?.outputPath,
+          narrativeBrief: (args.narrativeBrief as NarrativeBrief | undefined) ?? existing?.narrativeBrief,
           theme: {
             design: args.design ?? existing?.theme?.design,
             domain: args.domain ?? existing?.theme?.domain,