@cyber-dash-tech/revela 0.8.8 → 0.9.0

package/README.md

@@ -20,8 +20,8 @@ Enable it for the current session, assign a presentation task, and the agent can
 - injects a presentation-specific system prompt into your current agent with `/revela enable`
 - builds that prompt from 3 layers: core skill, active domain, active design
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
-- uses workspace `DECKS.json` as machine-readable deck memory, slide spec, and prewrite readiness state
-- blocks premature writes to `decks/*.html` until the active deck is marked structurally ready
+- keeps track of deck context, slide structure, sources, and readiness across the current workspace
+- checks for missing context, weak evidence, and incomplete structure before writing `decks/*.html`
 - runs fast design compliance checks whenever the agent writes, patches, or edits `decks/*.html`
 - opens a visual comment editor for existing decks so users can Ctrl/Cmd-click elements and send precise edit requests back to OpenCode
 - exports finished decks to PDF and editable PPTX
@@ -89,7 +89,7 @@ Enable Revela in the current session:
 /revela enable
 ```
 
-Initialize workspace deck memory when starting in a new project:
+Prepare the workspace when starting a new deck project:
 
 ```text
 /revela init
@@ -109,7 +109,7 @@ Then give the agent a deck task:
 Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
 ```
 
-Before the agent writes `decks/humanoid-robotics.html`, it must update `DECKS.json` through the `revela-decks` tool with the active deck, confirmed slide specs, layouts, components, and computed `writeReadiness.status: ready`. You can ask for an explicit readiness check at any time:
+If the task depends on sources, research, or a confirmed slide plan, you can ask Revela to review whether the deck has enough context, structure, and evidence before writing:
 
 ```text
 /revela review
@@ -137,8 +137,8 @@ Disable presentation mode when done:
 /revela enable                   enable presentation mode for this session
 /revela disable                  disable presentation mode
 
-/revela init                     initialize or refresh workspace DECKS.json
-/revela review                   review current deck readiness before writing HTML
+/revela init                     prepare the workspace for a deck project
+/revela review                   check whether context, structure, and evidence are ready
 /revela remember <text>          save an explicit user/workflow preference
 /revela edit                     open visual editor for the only deck in decks/
 
@@ -178,59 +178,22 @@ The enabled or disabled state is session-level only.
 
 ---
 
-## DECKS.json Memory And Readiness Gate
+## Recommended Workflow
 
-Revela uses a workspace-root `DECKS.json` file for cross-session continuity and deck production control. It is intended for tools and the LLM, not manual editing.
+Use Revela as a guided deck-production mode:
 
-It has two jobs:
+1. Enable Revela with `/revela enable`.
+2. Run `/revela init` when starting in a new project or when the workspace has changed significantly.
+3. Choose a design or domain if the default style is not right.
+4. Give the agent a clear deck task: audience, goal, language, number of slides, source requirements, and output path.
+5. Use `/revela review` before writing if the deck needs research, citations, or a confirmed slide plan.
+6. Let the agent write the HTML deck under `decks/`.
+7. Use `/revela edit` for visual comments and targeted revisions.
+8. Export with `/revela pdf <file>` or `/revela pptx <file>`.
 
-- workspace memory: stable project context, source materials, explicit user preferences, deck history, and open questions
-- active deck spec: current deck output path, prerequisites, research plan, per-slide content, layouts, components, evidence, visuals, blockers, and write readiness
+`/revela review` checks for practical readiness problems: unclear audience, missing source material, unfinished research, unsupported claims, weak source trace, incomplete slide structure, missing design/layout information, or lightweight narrative issues such as weak so-what, missing risk/assumption handling, and abrupt transitions. It does not write the final deck.
 
-`DECKS.json` is the source of truth for workspace memory and deck readiness.
-
-Create or refresh it with:
-
-```text
-/revela init
-```
-
-Review the current deck state with:
-
-```text
-/revela review
-```
-
-`/revela review` does not write the final HTML deck. It reads and updates `DECKS.json` through the `revela-decks` tool, checks what is missing, and sets `writeReadiness.status` to `ready` only when the deck is ready to generate.
-
-Minimum readiness conditions:
-
-- topic, audience, language, visual style/design, and slide plan are decided
-- source materials are identified or explicitly deemed unnecessary
-- research need is assessed
-- needed research findings have been read and reflected in the slide specs
-- evidence-sensitive claims have slide-level evidence with useful source trace when available, such as `findingsFile`, `sourcePath`, `location`, `quote`, `url`, or `caveat`
-- the user has confirmed the slide plan
-- required design layouts and components have been fetched
-- every slide has a title, layout, components, and structured content
-- no blockers remain
-
-The plugin enforces this before deck HTML is written. A write or patch touching `decks/*.html` is allowed only when the matching deck in `DECKS.json` passes the readiness gate. Direct writes or patches to `DECKS.json` are blocked; use `revela-decks` instead.
-
-The gate checks:
-
-- `writeReadiness.status` is `ready`
-- `writeReadiness.blockers` is empty
-- the deck `outputPath` exactly matches the target `decks/*.html` path
-- all `requiredInputs` booleans are true
-- every slide has title, layout, components, and structured content
-- every needed research axis is `done`, `read`, or `skipped`
-
-`/revela review` distinguishes missing evidence from weak source-only evidence. A claim with no evidence remains a blocker; evidence that only names a source is reported as a warning so the agent can add source trace before writing the deck.
-
-If the gate blocks a write, Revela writes a marker file under `.opencode/revela/blocked-writes/` instead of creating or overwriting the deck HTML. This makes the failure visible to the agent while keeping the real deck file untouched.
-
-For `apply_patch`, Revela only checks whether the patch touches `decks/*.html`. If not ready, the whole patch is replaced with a blocked marker patch. The `edit` tool is not gated.
+If Revela blocks a deck write, ask the agent to run `/revela review`, resolve the reported gaps, and try again. This protects the deck file from being overwritten before the plan, evidence, and structure are ready.
 
 To remember long-term preferences, use:
 
@@ -238,7 +201,7 @@ To remember long-term preferences, use:
 /revela remember Prefer concise Chinese consulting-style decks.
 ```
 
-Do not use `remember` for temporary checklist state; temporary state belongs in the active deck spec in `DECKS.json`.
+Do not use `remember` for temporary checklist state; use it only for durable user or workflow preferences.
 
 ---
 
@@ -607,7 +570,7 @@ The editor opens in your browser. Use `Ctrl`/`Cmd` + click to reference deck ele
 
 LLM tool equivalent: `revela-edit` with no target. This lets the agent open the same editor when you say things like “I want to edit the deck”.
 
-`/revela edit` prepares minimal `DECKS.json` state for the existing HTML deck if needed, so the normal deck write gate can still protect `decks/*.html` while allowing targeted edits.
+For existing decks, `/revela edit` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
 
 ---
 

package/README.zh-CN.md

@@ -20,8 +20,8 @@ Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使
 - 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
 - prompt 由 3 层组成：核心 skill、当前 domain、当前 design
 - 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取和嵌入素材缓存提取
-- 使用工作区 `DECKS.json` 保存机器可读的 deck 记忆、逐页规格和写入前 readiness 状态
-- 在 active deck 结构化 ready 前，阻止过早写入 `decks/*.html`
+- 在当前工作区持续跟踪 deck 背景、页面结构、来源材料和 readiness
+- 写入 `decks/*.html` 前检查是否缺上下文、证据或结构
 - agent 每次写入、patch 或 edit `decks/*.html` 时自动执行快速 design compliance 检查
 - 为已有 deck 打开可视化评论编辑器，用户可以 Ctrl/Cmd + 点击元素，并把精确修改意见发回 OpenCode
 - 支持导出成 PDF 和可编辑 PPTX
@@ -88,7 +88,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 /revela enable
 ```
 
-在新项目里可以先初始化工作区 deck 状态：
+在新项目里可以先准备工作区：
 
 ```text
 /revela init
@@ -108,7 +108,7 @@ export { default } from "/absolute/path/to/revela/index.ts";
 Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
 ```
 
-在 agent 写入 `decks/humanoid-robotics.html` 之前，它必须通过 `revela-decks` 工具更新 `DECKS.json`：记录 active deck、已确认的逐页规格、layout、component，并由工具计算出 `writeReadiness.status: ready`。你也可以随时显式触发 readiness 检查：
+如果任务依赖来源材料、调研或已确认的 slide plan，可以先让 Revela 检查上下文、结构和证据是否足够：
 
 ```text
 /revela review
@@ -136,8 +136,8 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 /revela enable                   为当前会话启用演示文稿模式
 /revela disable                  关闭演示文稿模式
 
-/revela init                     初始化或刷新工作区 DECKS.json
-/revela review                   写 HTML 前检查当前 deck readiness
+/revela init                     为当前 deck 项目准备工作区
+/revela review                   检查上下文、结构和证据是否 ready
 /revela remember <text>          保存明确的用户/工作流偏好
 /revela edit                     打开 decks/ 下唯一 deck 的可视化编辑器
 
@@ -177,59 +177,22 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 ---
 
-## DECKS.json 记忆与写入门禁
+## 推荐使用流程
 
-Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生产控制。它主要给工具和 LLM 使用，不建议人工直接编辑。
+把 Revela 当成一个有检查环节的 deck 生产模式：
 
-它有两个职责：
+1. 用 `/revela enable` 启用 Revela。
+2. 新项目或工作区明显变化时，运行 `/revela init`。
+3. 如果默认风格不合适，先选择 design 或 domain。
+4. 给 agent 一个清楚的 deck 任务：受众、目标、语言、页数、来源要求和输出路径。
+5. 如果 deck 需要调研、引用或已确认的 slide plan，写作前先运行 `/revela review`。
+6. 让 agent 把 HTML deck 写到 `decks/` 下。
+7. 用 `/revela edit` 做可视化评论和精准修改。
+8. 用 `/revela pdf <file>` 或 `/revela pptx <file>` 导出。
 
-- 工作区记忆：稳定项目背景、源材料、明确用户偏好、历史 deck 和开放问题
-- active deck 规格：当前 deck 输出路径、前置条件、research plan、逐页内容、layout、component、证据、视觉需求、blocker 和 write readiness
+`/revela review` 检查的是实际生产问题：受众是否清楚、是否缺来源材料、调研是否完成、关键 claim 是否有证据、source trace 是否太弱、页面结构是否完整、design/layout 信息是否齐全，以及轻量叙事问题，例如 so-what 不清晰、缺少风险/假设处理或转场突兀。它不会写最终 deck。
 
-`DECKS.json` 是工作区记忆和 deck readiness 的 source of truth。
-
-创建或刷新：
-
-```text
-/revela init
-```
-
-检查当前 deck 状态：
-
-```text
-/revela review
-```
-
-`/revela review` 不会写最终 HTML deck。它通过 `revela-decks` 工具读取并更新 `DECKS.json`，检查缺失项，并且只有在 deck 真的可以生成时才把 `writeReadiness.status` 设为 `ready`。
-
-最小 readiness 条件：
-
-- topic、audience、language、visual style/design 和 slide plan 已确定
-- source materials 已识别，或明确不需要源材料
-- research need 已评估
-- 需要调研时，相关 findings 已读取并反映到逐页规格中
-- evidence-sensitive claim 尽量带有逐页 evidence 和可用 source trace，例如 `findingsFile`、`sourcePath`、`location`、`quote`、`url` 或 `caveat`
-- 用户已确认 slide plan
-- 需要的 design layouts 和 components 已获取
-- 每页都有 title、layout、components 和结构化 content
-- 没有 unresolved blockers
-
-插件会在写 deck HTML 前强制检查这些条件。任何触碰 `decks/*.html` 的 `write` 或 `apply_patch`，只有在 `DECKS.json` 里匹配的 deck 通过 readiness gate 后才允许执行。直接写入或 patch `DECKS.json` 会被阻止；必须使用 `revela-decks` 工具更新状态。
-
-门禁会检查：
-
-- `writeReadiness.status` 是 `ready`
-- `writeReadiness.blockers` 为空
-- deck `outputPath` 精确匹配目标 `decks/*.html` 路径
-- 所有 `requiredInputs` 布尔值都是 true
-- 每页都有 title、layout、components 和结构化 content
-- 每个 needed research axis 都是 `done`、`read` 或 `skipped`
-
-`/revela review` 会区分缺失 evidence 和较弱的 source-only evidence。完全没有 evidence 的 claim 仍是 blocker；只写了 source 名称但缺少 source trace 的 evidence 会作为 warning 报告，方便 agent 在写 deck 前补足溯源信息。
-
-如果门禁阻止写入，Revela 会在 `.opencode/revela/blocked-writes/` 下写一个 marker 文件，而不是创建或覆盖真实 HTML deck。这样 agent 能看到失败原因，同时真实 deck 文件不会被污染。
-
-对 `apply_patch`，Revela 只检查 patch 是否触碰 `decks/*.html`。如果未 ready，整个 patch 会被替换成 blocked marker patch。`edit` 工具不做门禁。
+如果 Revela 阻止写入 deck，直接让 agent 运行 `/revela review`，根据报告补齐缺口后再写。这样可以避免在计划、证据或结构还不完整时覆盖真实 deck 文件。
 
 记住长期偏好请使用：
 
@@ -237,7 +200,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 /revela remember 我偏好中文、咨询风格、每页只表达一个核心观点。
 ```
 
-不要用 `remember` 保存临时 checklist 状态；临时状态应该保存在 `DECKS.json` 的 active deck spec 中。
+不要用 `remember` 保存临时 checklist 状态；它只适合保存长期用户偏好或工作流偏好。
 
 ---
 
@@ -572,7 +535,7 @@ Revela 0.8 中 `/revela edit` 不接受 target。如果 `decks/` 下正好有一
 
 对应的 LLM tool：`revela-edit`，不需要 target。因此当你说“我要编辑这个 deck”时，agent 也可以主动打开同一个编辑器。
 
-如果已有 HTML deck 缺少 `DECKS.json` 状态，`/revela edit` 会自动准备最小 deck state，让正常的 `decks/*.html` 写入门禁仍然生效，同时允许后续精准修改。
+对于已有 HTML deck，`/revela edit` 会自动准备必要的最小项目上下文，让后续精准修改仍然经过正常安全检查。
 
 ---
 

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-readiness review, not only a checklist review: unsupported numbers, market sizing, recommendations, competitor comparisons, technical assertions, or investment conclusions 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, layout, components, structured content, evidence, visuals, and status.
+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.
+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.
@@ -51,6 +55,8 @@ Minimum conditions for \`ready\`:
 - The user has confirmed the slide plan.
 - ${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.
 
@@ -58,7 +64,9 @@ Report format:
 - Start with \`Ready: yes/no\`.
 - If blocked, list each blocker with slide index/title when the tool provides it, the issue type, and the suggested next action.
 - 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

@@ -6,6 +6,7 @@ export const DECKS_STATE_FILE = "DECKS.json"
 export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
 export type WriteReadinessStatus = "blocked" | "ready" | "written"
+export type NarrativeRole = "context" | "tension" | "evidence" | "recommendation" | "risk" | "ask" | "appendix" | "close"
 
 export interface DecksState {
   version: 1
@@ -57,6 +58,7 @@ export interface DeckSpec {
   audience?: string
   language?: string
   outputPath: string
+  narrativeBrief?: NarrativeBrief
   theme: {
     design?: string
     domain?: string
@@ -72,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
@@ -96,6 +108,7 @@ export interface SlideSpec {
   index: number
   title: string
   purpose?: string
+  narrativeRole?: NarrativeRole
   layout: string
   qa?: boolean
   components: string[]
@@ -159,6 +172,7 @@ export type ReadinessIssueType =
   | "missing_evidence"
   | "weak_evidence"
   | "source_not_processed"
+  | "narrative_gap"
 
 export interface ReadinessIssue {
   type: ReadinessIssueType
@@ -239,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 ?? [],
@@ -465,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: {
@@ -477,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,
@@ -580,6 +609,8 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
     }
   }
 
+  issues.push(...computeNarrativeReadinessIssues(deck))
+
   for (const axis of deck.researchPlan) {
     if (axis.needed && axis.status !== "done" && axis.status !== "read" && axis.status !== "skipped") {
       issues.push(blockerIssue(
@@ -612,6 +643,156 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   return issues
 }
 
+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(
+      "narrative_gap",
+      "No slide narrativeRole values are recorded for a multi-slide deck",
+      "Add lightweight narrativeRole values such as context, tension, evidence, recommendation, risk, ask, appendix, or close to improve story-structure review.",
+    ))
+  }
+
+  if (slides.length >= 4 && deck.audience?.trim() && slides.every(hasWeakNarrativePurpose)) {
+    issues.push(warningIssue(
+      "narrative_gap",
+      `Slide purposes do not clearly frame the story for the audience: ${deck.audience}`,
+      "Rewrite slide purpose fields to explain what this audience should understand, believe, decide, or do after each slide.",
+    ))
+  }
+
+  const firstRecommendationIndex = slides.findIndex(isRecommendationSlide)
+  if (firstRecommendationIndex >= 0) {
+    const recommendation = slides[firstRecommendationIndex]
+    const priorSlides = slides.slice(0, firstRecommendationIndex)
+    const earlyBoundary = Math.max(1, Math.ceil(slides.length * 0.3))
+    if (firstRecommendationIndex < earlyBoundary && !priorSlides.some(hasEvidenceOrTensionRole)) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        `Slide ${recommendation.index} presents a recommendation before context, tension, or evidence has been established`,
+        "Consider moving the recommendation later or adding preceding context, tension, or evidence slides so the conclusion does not arrive before support.",
+        { slideIndex: recommendation.index, slideTitle: recommendation.title },
+      ))
+    }
+
+    if (!slides.some(hasRiskOrAssumptionHandling)) {
+      issues.push(warningIssue(
+        "narrative_gap",
+        "Recommendation has no visible risk, assumption, caveat, or tradeoff handling",
+        "Add a risk/assumption/tradeoff slide or make the relevant caveats explicit before writing a decision-oriented recommendation deck.",
+        { slideIndex: recommendation.index, slideTitle: recommendation.title },
+      ))
+    }
+  }
+
+  if (slides.length >= 4 && !hasClearEnding(slides)) {
+    const last = slides[slides.length - 1]
+    issues.push(warningIssue(
+      "narrative_gap",
+      "Deck may end without a clear so-what, ask, or closing takeaway",
+      "Use the final slide or final section to state the decision, action request, recommendation, or closing takeaway explicitly.",
+      { slideIndex: last.index, slideTitle: last.title },
+    ))
+  }
+
+  const firstAskIndex = slides.findIndex(isAskSlide)
+  if (firstAskIndex === 0 && slides.length > 2) {
+    const ask = slides[firstAskIndex]
+    issues.push(warningIssue(
+      "narrative_gap",
+      `Slide ${ask.index} asks for action before the deck has established the case`,
+      "Consider moving the ask later or opening with context before requesting a decision or action.",
+      { slideIndex: ask.index, slideTitle: ask.title },
+    ))
+  } else if (firstAskIndex > 0) {
+    const contextIndex = slides.findIndex((slide) => slide.narrativeRole === "context")
+    if (contextIndex >= 0 && contextIndex < firstAskIndex) {
+      const bridgeSlides = slides.slice(contextIndex + 1, firstAskIndex)
+      if (!bridgeSlides.some((slide) => hasEvidenceOrTensionRole(slide) || isRecommendationSlide(slide))) {
+        const ask = slides[firstAskIndex]
+        issues.push(warningIssue(
+          "narrative_gap",
+          `Slide ${ask.index} jumps from context to ask without evidence, tension, or recommendation in between`,
+          "Add an evidence, tension, or recommendation bridge before the ask so the narrative transition is easier to follow.",
+          { slideIndex: ask.index, slideTitle: ask.title },
+        ))
+      }
+    }
+  }
+
+  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 }
 }
@@ -634,6 +815,46 @@ function findEvidenceSensitiveClaim(slide: SlideSpec): string | undefined {
   return candidates.find(isEvidenceSensitiveClaim)
 }
 
+function isRecommendationSlide(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "recommendation" || /\b(recommend(?:ation|ed)?|should|must|go\/?no-go)\b|建议|必须/.test(slideSearchText(slide))
+}
+
+function isAskSlide(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "ask" || /\b(ask|decision|approve|approval|next step|action required|call to action)\b|请求|决策|批准|下一步|行动/.test(slideSearchText(slide))
+}
+
+function hasEvidenceOrTensionRole(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "evidence" || slide.narrativeRole === "tension"
+}
+
+function hasRiskOrAssumptionHandling(slide: SlideSpec): boolean {
+  return slide.narrativeRole === "risk" || /\b(risk|assumption|caveat|trade-?off|constraint|limitation|uncertainty)\b|风险|假设|取舍|限制|不确定|前提/.test(slideSearchText(slide))
+}
+
+function hasWeakNarrativePurpose(slide: SlideSpec): boolean {
+  const purpose = slide.purpose?.trim().toLowerCase()
+  if (!purpose) return true
+  return /^(explain|show|introduce|present|describe|overview|clarify)\b/.test(purpose) || /^(说明|展示|介绍|呈现|概述)/.test(purpose)
+}
+
+function hasClearEnding(slides: SlideSpec[]): boolean {
+  const finalSlides = slides.slice(-2)
+  return finalSlides.some((slide) => slide.narrativeRole === "recommendation" || slide.narrativeRole === "ask" || slide.narrativeRole === "close" || /\b(so what|takeaway|recommend(?:ation)?|decision|ask|next step|conclusion|close)\b|结论|建议|决策|请求|下一步|收尾|总结/.test(slideSearchText(slide)))
+}
+
+function slideSearchText(slide: SlideSpec): string {
+  return [
+    slide.title,
+    slide.purpose,
+    slide.content?.headline,
+    ...(slide.content?.body ?? []),
+    ...(slide.content?.bullets ?? []),
+  ]
+    .filter((item): item is string => Boolean(item))
+    .join("\n")
+    .toLowerCase()
+}
+
 function isEvidenceSensitiveClaim(text: string): boolean {
   const normalized = text.toLowerCase()
   return hasNumericClaim(normalized) || EVIDENCE_SENSITIVE_TERMS.some((pattern) => pattern.test(normalized))
@@ -711,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.8",
+  "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,20 +310,31 @@ 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:
 
-| # | Title | Content Summary | Layout | Components |
-|---|-------|-----------------|--------|------------|
-| 1 | Cover | Topic title, subtitle, presenter, date | `cover` | `gradient-text`, `deco-blob`, `accent-line` |
-| 2 | Table of Contents | 5 chapter headings | `toc` | `toc-list` |
-| 3 | Market Background | Key problem, 3 pain points, $4.2B TAM | `two-col` | `evidence-list`, `card` |
-| 4 | Key Metrics | Growth 85%, TAM $12B, NPS 72 | `stats` | `stat-card ×3`, `gradient-text` |
+| # | Title | Narrative Role | Content Summary | Layout | Components |
+|---|-------|----------------|-----------------|--------|------------|
+| 1 | Cover | `context` | Topic title, subtitle, presenter, date | `cover` | `gradient-text`, `deco-blob`, `accent-line` |
+| 2 | Table of Contents | `context` | 5 chapter headings | `toc` | `toc-list` |
+| 3 | Market Background | `tension` | Key problem, 3 pain points, $4.2B TAM | `two-col` | `evidence-list`, `card` |
+| 4 | Key Metrics | `evidence` | Growth 85%, TAM $12B, NPS 72 | `stats` | `stat-card ×3`, `gradient-text` |
 
 Rules for filling the table:
 - **Layout**: use the exact layout name from the Layout Index (e.g. `cover`, `two-col`, `card-grid`, `stats`)
+- **Narrative Role**: use one lightweight role when clear: `context`, `tension`, `evidence`,
+  `recommendation`, `risk`, `ask`, `appendix`, or `close`
 - **Components**: list component names from the Component Index — no CSS details
   (e.g. `card ×3`, `stat-card`, `evidence-list`, `step-flow`, `quote-block`)
 - **Content Summary**: 1 sentence of actual content — specific numbers, key points, or
@@ -318,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 `upsertSlides` with the confirmed per-slide content, layout, components, and evidence.
+- 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."),
@@ -75,6 +85,7 @@ export default tool({
       index: tool.schema.number().describe("1-based slide index."),
       title: tool.schema.string().describe("Slide title."),
       purpose: tool.schema.string().optional().describe("Narrative purpose of this slide."),
+      narrativeRole: tool.schema.enum(["context", "tension", "evidence", "recommendation", "risk", "ask", "appendix", "close"]).optional().describe("Lightweight narrative role for review guidance."),
       layout: tool.schema.string().describe("Design layout name."),
       qa: tool.schema.boolean().optional().describe("Whether the slide is marked QA-relevant deck metadata."),
       components: tool.schema.array(tool.schema.string()).describe("Design components used by this slide."),
@@ -139,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,