@cyber-dash-tech/revela 0.8.8 → 0.8.9

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/commands/review.ts

@@ -18,7 +18,7 @@ Goal:
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, and production status.
 - 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 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 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:
@@ -35,12 +35,12 @@ 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.
 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.
+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.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
@@ -51,6 +51,7 @@ 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.
 - The needed design layouts and components have been fetched with \`revela-designs read\`.
 - No unresolved blockers remain.
 
@@ -58,6 +59,7 @@ 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.
 - 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.
 

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
@@ -96,6 +97,7 @@ export interface SlideSpec {
   index: number
   title: string
   purpose?: string
+  narrativeRole?: NarrativeRole
   layout: string
   qa?: boolean
   components: string[]
@@ -159,6 +161,7 @@ export type ReadinessIssueType =
   | "missing_evidence"
   | "weak_evidence"
   | "source_not_processed"
+  | "narrative_gap"
 
 export interface ReadinessIssue {
   type: ReadinessIssueType
@@ -580,6 +583,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 +617,89 @@ 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
+
+  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 blockerIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
   return { type, severity: "blocker", message, suggestedAction, ...extra }
 }
@@ -634,6 +722,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))

package/package.json

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

package/skill/SKILL.md

@@ -292,15 +292,17 @@ slide plan to the user **before writing any HTML**.
 
 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
@@ -319,7 +321,7 @@ Then ask:
 
 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 `upsertSlides` with the confirmed per-slide content, narrativeRole, layout, components, and evidence.
 - Keep write readiness blocked until Phase 5 calls `revela-decks review` and the tool returns ready.
 
 ---

package/tools/decks.ts

@@ -75,6 +75,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."),