@cyber-dash-tech/revela 0.8.6 → 0.8.8

package/README.md

@@ -209,6 +209,7 @@ Minimum readiness conditions:
 - 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
@@ -225,6 +226,8 @@ The gate checks:
 - 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.

package/README.zh-CN.md

@@ -208,6 +208,7 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 - 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
@@ -224,6 +225,8 @@ Revela 使用工作区根目录的 `DECKS.json` 做跨会话记忆和 deck 生
 - 每页都有 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` 工具不做门禁。

package/lib/agents/research-prompt.ts

@@ -29,7 +29,7 @@ Given a research brief specifying your topic and axis, you will:
 2. Use \`DECKS.json\` through \`revela-decks\` as the workspace material index when it exists
 3. Run a lightweight workspace freshness check when needed
 4. Search the web for current data, reports, and case studies when the brief requires it
-5. Write all findings to ONE structured file: \`researches/{topic-key}/{axis-name}.md\`
+5. Write all findings to ONE structured file: \`researches/{topic-key}/{axis-name}.md\` with source trace detailed enough for slide-level evidence mapping
 6. Return a brief summary of what you found
 
 ---
@@ -112,18 +112,21 @@ Use **\`revela-research-save\`** to write ONE file with all your findings.
 - \`content\`: structured findings using the four sections below
 - \`sources\`: list of all URLs and filenames used
 
+The primary agent will map your findings into \`DECKS.json\` slide-level evidence.
+Preserve compact source trace so it can do that without rediscovering sources.
+
 ### Findings file format
 
 Use these four sections — omit any that are empty:
 
 \`\`\`markdown
 ## Data
-- {stat or finding} [Source: {url or filename}]
-- {stat or finding} [Source: {url or filename}]
+- {stat or finding} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Quote: "{short exact snippet if available}"; Caveat: {scope/uncertainty if relevant}]
+- {stat or finding} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Quote: "{short exact snippet if available}"; Caveat: {scope/uncertainty if relevant}]
 (5–10 items, most argument-worthy only)
 
 ## Cases
-- **{Company/Entity}**: {1–2 sentence profile with key metrics} [Source: {url}]
+- **{Company/Entity}**: {1–2 sentence profile with key metrics} [Source: {url or filename}; Location: {page/slide/sheet/section if known}; Caveat: {scope/uncertainty if relevant}]
 (2–4 entries max)
 
 ## Images
@@ -136,6 +139,10 @@ Use these four sections — omit any that are empty:
 
 Content rules:
 - Every data point MUST have inline source attribution: \`[Source: {url}]\` or \`[Source: AI knowledge — verify]\` or \`[Source: {filename}]\`
+- For workspace documents, identify the original filename and available page, slide, sheet, or section location. Do not cite only the extracted summary.
+- When extracted materials were used, include \`extractedTextPath\` or \`extractedManifestPath\` when useful for traceability.
+- Preserve compact direct snippets or quotes when available. Do not invent quotes, page references, locations, URLs, or caveats.
+- Include caveats or scope limitations for estimates, rankings, market sizes, forecasts, and conflicting sources.
 - Preserve raw numbers and direct quotes — do not summarize prematurely
 - Use tables for comparative data when 3+ entities are compared
 - Include publication dates where available
@@ -170,6 +177,7 @@ Gaps:
 - **Always** call \`revela-extract-document-materials\` for every selected workspace file before deciding which extracted materials to read next
 - **Avoid** repeated extraction or deep reading for files that are clearly irrelevant to this axis
 - **Always** include source attribution on every data point
+- **Always** preserve source trace: URL or filename, location when available, compact quote/snippet when available, and caveat/scope where relevant
 - **Always** use tables for comparative data (more useful than bullets for presentations)
 - **Preserve** raw data — the primary agent will select what to include in slides
 - **Note** data freshness — include publication dates where available

package/lib/commands/init.ts

@@ -48,8 +48,10 @@ Workflow:
 6. Before extracting or deeply reading a selected document, check \`DECKS.json.workspace.sourceMaterials\`. If the same path has the same fingerprint and valid extraction paths, reuse those paths instead of repeating extraction.
 7. Read only the materials needed to form a conservative workspace memory. Do not exhaustively read every file if the workspace is large.
 8. If this conversation or the workspace contains a concrete deck task or an existing deck artifact, call \`revela-decks\` with action \`upsertDeck\` and later \`upsertSlides\` for explicit deck information. Do not pass or ask for a deck key; the tool uses the workspace folder name internally. Do not mark readiness ready during init.
-9. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. The \`SlideSpec[]\` itself is the worklist; do not create a separate target slide count.
-10. Report what was initialized or updated and list any open questions.
+9. When adopting an existing HTML deck, analyze the artifact and create one conservative \`SlideSpec\` per identifiable slide/page. Record only visible source notes or explicit source information as evidence; do not infer original evidence that is not present in the artifact.
+10. When a read or extracted source material clearly supports a specific slide claim, you may attach compact evidence fields such as \`sourcePath\`, \`location\`, \`extractedTextPath\`, or \`extractedManifestPath\`. Attach extraction cache paths only when they support that specific claim, not to every slide by default.
+11. Treat \`workspace.sourceMaterials\` as a reusable candidate index, not proof by itself. A source material record alone is not slide evidence.
+12. Report what was initialized or updated and list any open questions.
 
 Memory rules:
 - Only write facts supported by workspace files into ${DECKS_STATE_FILE} workspace state, source materials, deck memory, and open questions.

package/lib/commands/review.ts

@@ -18,6 +18,8 @@ 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 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:
 - ${state}
@@ -32,21 +34,33 @@ 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.
-3. 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. 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.
-5. Call \`revela-decks\` action \`review\`. The tool computes and writes \`writeReadiness\` for the current workspace deck.
-6. Briefly report whether the deck is ready. If blocked, list the exact blockers returned by the tool.
+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.
+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.
 
 Minimum conditions for \`ready\`:
 - Topic, audience, slide count, language, and visual style/design are decided.
 - Source materials have been identified or explicitly deemed unnecessary.
 - Research need has been assessed.
 - If research is needed, all relevant findings have been read and reflected in the slide specs.
+- Read or done research findings are mapped into \`slides[].evidence[]\` where they support evidence-sensitive slide claims.
 - 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.
 - The needed design layouts and components have been fetched with \`revela-designs read\`.
 - No unresolved blockers remain.
 
+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.
+- 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.
+
 Rules:
 - Do not write or overwrite \`decks/*.html\` during review.
 - Treat the workspace as one deck project. If the user wants another deck, tell them to use a separate workspace/folder.

package/lib/decks-state.ts

@@ -117,6 +117,12 @@ export interface EvidenceRef {
   quote?: string
   page?: string
   url?: string
+  sourcePath?: string
+  location?: string
+  findingsFile?: string
+  caveat?: string
+  extractedTextPath?: string
+  extractedManifestPath?: string
 }
 
 export interface VisualBrief {
@@ -140,8 +146,32 @@ export interface DeckStateReadinessResult {
   status?: WriteReadinessStatus
   blocker: string
   blockers: string[]
+  warnings: string[]
+  issues: ReadinessIssue[]
+}
+
+export type ReadinessSeverity = "blocker" | "warning"
+
+export type ReadinessIssueType =
+  | "missing_required_input"
+  | "missing_slide_spec"
+  | "research_not_ready"
+  | "missing_evidence"
+  | "weak_evidence"
+  | "source_not_processed"
+
+export interface ReadinessIssue {
+  type: ReadinessIssueType
+  severity: ReadinessSeverity
+  message: string
+  suggestedAction: string
+  slideIndex?: number
+  slideTitle?: string
+  claimText?: string
 }
 
+const SOURCE_TRACE_ACTION = "Add slide evidence with source plus source trace such as findingsFile or sourcePath, and quote, location, url, or caveat where available; otherwise reframe the claim as an explicit assumption/opinion."
+
 export function decksStatePath(workspaceRoot: string): string {
   return join(workspaceRoot, DECKS_STATE_FILE)
 }
@@ -279,11 +309,20 @@ export function reviewDeckState(state: DecksState, slug?: string): { state: Deck
         slug: missing,
         blocker: `Deck ${missing} does not exist in ${DECKS_STATE_FILE}.`,
         blockers: [`Deck ${missing} does not exist in ${DECKS_STATE_FILE}.`],
+        warnings: [],
+        issues: [{
+          type: "missing_slide_spec",
+          severity: "blocker",
+          message: `Deck ${missing} does not exist in ${DECKS_STATE_FILE}.`,
+          suggestedAction: "Create the current workspace deck spec with revela-decks upsertDeck before reviewing readiness.",
+        }],
       },
     }
   }
 
-  const blockers = computeDeckBlockers(deck)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
+  const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   deck.writeReadiness = {
     status: blockers.length === 0 ? "ready" : "blocked",
     blockers,
@@ -300,6 +339,8 @@ export function reviewDeckState(state: DecksState, slug?: string): { state: Deck
       status: deck.writeReadiness.status,
       blocker: blockers.join("; "),
       blockers,
+      warnings,
+      issues,
     },
   }
 }
@@ -321,18 +362,48 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       slug: targetSlug,
       blocker: currentDeckBlocker(normalized),
       blockers: [currentDeckBlocker(normalized)],
+      warnings: [],
+      issues: [{
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message: currentDeckBlocker(normalized),
+        suggestedAction: "Create or select the current workspace deck through revela-decks before writing deck HTML.",
+      }],
     }
   }
 
-  const blockers = computeDeckBlockers(deck)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
+  const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
   if (normalizeDeckPath(deck.outputPath) !== targetPath) {
-    blockers.unshift(`Deck outputPath is ${deck.outputPath || "missing"}, not ${targetPath}`)
+    const message = `Deck outputPath is ${deck.outputPath || "missing"}, not ${targetPath}`
+    blockers.unshift(message)
+    issues.unshift({
+      type: "missing_slide_spec",
+      severity: "blocker",
+      message,
+      suggestedAction: "Update deck.outputPath through revela-decks or write to the reviewed outputPath.",
+    })
   }
   if (deck.writeReadiness.status !== "ready") {
-    blockers.unshift(`Deck writeReadiness is ${deck.writeReadiness.status || "missing"}, not ready`)
+    const message = `Deck writeReadiness is ${deck.writeReadiness.status || "missing"}, not ready`
+    blockers.unshift(message)
+    issues.unshift({
+      type: "missing_slide_spec",
+      severity: "blocker",
+      message,
+      suggestedAction: "Run /revela review and resolve all readiness blockers before writing deck HTML.",
+    })
   }
   if (deck.writeReadiness.blockers.length > 0) {
-    blockers.unshift(`Deck still has readiness blockers: ${deck.writeReadiness.blockers.join("; ")}`)
+    const message = `Deck still has readiness blockers: ${deck.writeReadiness.blockers.join("; ")}`
+    blockers.unshift(message)
+    issues.unshift({
+      type: "missing_slide_spec",
+      severity: "blocker",
+      message,
+      suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela review.",
+    })
   }
 
   return {
@@ -341,6 +412,8 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
     status: deck.writeReadiness.status,
     blocker: blockers.join("; "),
     blockers,
+    warnings,
+    issues,
   }
 }
 
@@ -367,14 +440,58 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
   const compact = {
     sourceOfTruth: DECKS_STATE_FILE,
     activeDeck: activeKey,
-    workspace: state.workspace,
-    deck: active,
+    workspace: compactWorkspaceForPrompt(state.workspace),
+    deck: active ? compactDeckForPrompt(active) : undefined,
   }
   let text = JSON.stringify(compact, null, 2)
   if (text.length > maxChars) text = text.slice(0, maxChars).trimEnd() + "\n[DECKS.json state truncated for prompt size.]"
   return `---\n\n# Revela Workspace State From ${DECKS_STATE_FILE}\n\n\`\`\`json\n${text}\n\`\`\`\n\nRules for this state layer:\n- Treat ${DECKS_STATE_FILE} as the source of truth for the single current deck's specs, slide plan, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- Do not edit ${DECKS_STATE_FILE} directly; use the revela-decks tool.\n- Before writing decks/*.html, the current deck must have writeReadiness.status=ready and a complete slide spec, and its outputPath must match the target file.`
 }
 
+function compactWorkspaceForPrompt(workspace: DecksState["workspace"]): DecksState["workspace"] {
+  return {
+    brief: truncatePromptText(workspace.brief),
+    sourceMaterials: workspace.sourceMaterials.map((source) => ({
+      ...source,
+      summary: truncatePromptText(source.summary),
+      bestUsedFor: truncatePromptText(source.bestUsedFor),
+    })),
+    preferences: workspace.preferences,
+    deckMemory: workspace.deckMemory,
+    openQuestions: workspace.openQuestions.map((question) => truncatePromptText(question)).filter(Boolean) as string[],
+  }
+}
+
+function compactDeckForPrompt(deck: DeckSpec): DeckSpec {
+  return {
+    ...deck,
+    slides: deck.slides.map((slide) => ({
+      ...slide,
+      content: {
+        ...slide.content,
+        speakerNotes: truncatePromptText(slide.content.speakerNotes),
+      },
+      evidence: slide.evidence.map(compactEvidenceForPrompt),
+      notes: truncatePromptText(slide.notes),
+    })),
+  }
+}
+
+function compactEvidenceForPrompt(evidence: EvidenceRef): EvidenceRef {
+  return {
+    ...evidence,
+    source: truncatePromptText(evidence.source, 180) ?? evidence.source,
+    quote: truncatePromptText(evidence.quote, 320),
+    caveat: truncatePromptText(evidence.caveat, 220),
+  }
+}
+
+function truncatePromptText(text: string | undefined, maxLength = 400): string | undefined {
+  if (!text) return undefined
+  if (text.length <= maxLength) return text
+  return `${text.slice(0, maxLength).trimEnd()}... [truncated]`
+}
+
 function normalizeDecksState(input: DecksState): DecksState {
   const state: DecksState = {
     version: 1,
@@ -416,31 +533,170 @@ function currentDeckBlocker(state: DecksState): string {
   return `${DECKS_STATE_FILE} contains multiple deck records and no activeDeck. Select one current deck explicitly or move extra decks to separate workspaces.`
 }
 
-function computeDeckBlockers(deck: DeckSpec): string[] {
-  const blockers: string[] = []
-  if (!deck.goal.trim()) blockers.push("Deck goal is missing")
-  if (!isDeckHtmlPath(deck.outputPath)) blockers.push(`outputPath must be decks/*.html, got ${deck.outputPath || "missing"}`)
+function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["workspace"]): ReadinessIssue[] {
+  const issues: ReadinessIssue[] = []
+  if (!deck.goal.trim()) issues.push(blockerIssue("missing_slide_spec", "Deck goal is missing", "Set the deck goal through revela-decks upsertDeck."))
+  if (!isDeckHtmlPath(deck.outputPath)) {
+    issues.push(blockerIssue(
+      "missing_slide_spec",
+      `outputPath must be decks/*.html, got ${deck.outputPath || "missing"}`,
+      "Set outputPath to the target decks/*.html file through revela-decks upsertDeck.",
+    ))
+  }
 
   for (const [key, value] of Object.entries(deck.requiredInputs) as Array<[keyof RequiredInputs, boolean]>) {
-    if (value !== true) blockers.push(`requiredInputs.${key} is not true`)
+    if (value !== true) {
+      issues.push(blockerIssue(
+        "missing_required_input",
+        `requiredInputs.${key} is not true`,
+        `Complete and explicitly record requiredInputs.${key} before writing the deck.`,
+      ))
+    }
   }
 
-  if (deck.slides.length === 0) blockers.push("slides are missing")
+  if (deck.slides.length === 0) issues.push(blockerIssue("missing_slide_spec", "slides are missing", "Add the confirmed slide plan through revela-decks upsertSlides."))
   for (const slide of deck.slides) {
-    if (!slide.title.trim()) blockers.push(`Slide ${slide.index} title is missing`)
-    if (!slide.layout.trim()) blockers.push(`Slide ${slide.index} layout is missing`)
-    if (slide.components.length === 0) blockers.push(`Slide ${slide.index} components are missing`)
-    if (!hasSlideContent(slide)) blockers.push(`Slide ${slide.index} content is missing`)
+    const slideRef = { slideIndex: slide.index, slideTitle: slide.title }
+    if (!slide.title.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} title is missing`, "Add a slide title to the slide spec.", slideRef))
+    if (!slide.layout.trim()) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} layout is missing`, "Fetch and record the intended design layout for this slide.", slideRef))
+    if (slide.components.length === 0) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} components are missing`, "Record the design components needed for this slide.", slideRef))
+    if (!hasSlideContent(slide)) issues.push(blockerIssue("missing_slide_spec", `Slide ${slide.index} content is missing`, "Add structured headline/body/bullets/data content to the slide spec.", slideRef))
+
+    const claim = findEvidenceSensitiveClaim(slide)
+    if (claim && slide.evidence.length === 0) {
+      issues.push(blockerIssue(
+        "missing_evidence",
+        `Slide ${slide.index} has an evidence-sensitive claim without evidence: ${claim}`,
+        SOURCE_TRACE_ACTION,
+        { ...slideRef, claimText: claim },
+      ))
+    } else if (claim && slide.evidence.some((item) => !hasEvidenceDetail(item))) {
+      issues.push(warningIssue(
+        "weak_evidence",
+        `Slide ${slide.index} evidence for a high-risk claim has no source trace detail: ${claim}`,
+        "Add source trace detail to this evidence record: findingsFile or sourcePath plus quote, location, url, or caveat where available so the writing agent can ground the slide reliably.",
+        { ...slideRef, claimText: claim },
+      ))
+    }
   }
 
   for (const axis of deck.researchPlan) {
     if (axis.needed && axis.status !== "done" && axis.status !== "read" && axis.status !== "skipped") {
-      blockers.push(`Research axis ${axis.axis || "unnamed"} is needed but ${axis.status}`)
+      issues.push(blockerIssue(
+        "research_not_ready",
+        `Research axis ${axis.axis || "unnamed"} is needed but ${axis.status}`,
+        "Complete, read, or explicitly skip this research axis before writing the deck.",
+      ))
+    }
+  }
+
+  const hasNeededResearch = deck.researchPlan.some((axis) => axis.needed && axis.status !== "skipped")
+  for (const material of workspace.sourceMaterials ?? []) {
+    if (material.status !== "discovered") continue
+    const message = `Source material ${material.path} has been identified but not extracted, summarized, or researched`
+    if (hasNeededResearch) {
+      issues.push(blockerIssue(
+        "source_not_processed",
+        message,
+        "Extract, summarize, research, or explicitly exclude this source before writing evidence-backed slides.",
+      ))
+    } else {
+      issues.push(warningIssue(
+        "source_not_processed",
+        message,
+        "Consider extracting or excluding this source if it may support the deck narrative.",
+      ))
     }
   }
-  return blockers
+
+  return issues
+}
+
+function blockerIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
+  return { type, severity: "blocker", message, suggestedAction, ...extra }
+}
+
+function warningIssue(type: ReadinessIssueType, message: string, suggestedAction: string, extra: Partial<ReadinessIssue> = {}): ReadinessIssue {
+  return { type, severity: "warning", message, suggestedAction, ...extra }
+}
+
+function findEvidenceSensitiveClaim(slide: SlideSpec): string | undefined {
+  const candidates = [
+    slide.title,
+    slide.purpose,
+    slide.content?.headline,
+    ...(slide.content?.body ?? []),
+    ...(slide.content?.bullets ?? []),
+  ]
+    .map((item) => item?.trim())
+    .filter((item): item is string => Boolean(item))
+
+  return candidates.find(isEvidenceSensitiveClaim)
+}
+
+function isEvidenceSensitiveClaim(text: string): boolean {
+  const normalized = text.toLowerCase()
+  return hasNumericClaim(normalized) || EVIDENCE_SENSITIVE_TERMS.some((pattern) => pattern.test(normalized))
+}
+
+function hasNumericClaim(text: string): boolean {
+  return /(?:[$¥€£]\s?\d|\d+(?:\.\d+)?\s?(?:%|x|倍|万|亿|m|mn|million|b|bn|billion|k|千|年|months?|days?|users?|customers?|revenue|margin|cagr|tam|sam|som)\b|\b20\d{2}\b)/i.test(text)
 }
 
+function hasEvidenceDetail(evidence: EvidenceRef): boolean {
+  return Boolean(
+    evidence.quote?.trim() ||
+      evidence.page?.trim() ||
+      evidence.location?.trim() ||
+      evidence.url?.trim() ||
+      evidence.findingsFile?.trim() ||
+      evidence.sourcePath?.trim() ||
+      evidence.extractedTextPath?.trim()
+  )
+}
+
+const EVIDENCE_SENSITIVE_TERMS = [
+  /\bmarket size\b/,
+  /\bcagr\b/,
+  /\btam\b/,
+  /\bsam\b/,
+  /\bsom\b/,
+  /\brecommend(?:ation|ed)?\b/,
+  /\bshould\b/,
+  /\bmust\b/,
+  /\bgo\/?no-go\b/,
+  /\bvs\.?\b/,
+  /\bbetter than\b/,
+  /\boutperform\b/,
+  /\bleading\b/,
+  /\bcompetitor\b/,
+  /\bmarket leader\b/,
+  /\binvest(?:ment)?\b/,
+  /\brevenue\b/,
+  /\bmargin\b/,
+  /\bcost\b/,
+  /\brisk\b/,
+  /\blatency\b/,
+  /\baccuracy\b/,
+  /\bscalable\b/,
+  /\barchitecture\b/,
+  /市场规模/,
+  /增长/,
+  /领先/,
+  /超过/,
+  /竞品/,
+  /建议/,
+  /必须/,
+  /投资/,
+  /收入/,
+  /利润/,
+  /成本/,
+  /风险/,
+  /性能/,
+  /架构/,
+  /可扩展/,
+]
+
 function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
   return slides
     .map((slide) => ({

package/package.json

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

package/tools/decks.ts

@@ -86,10 +86,16 @@ export default tool({
       }).describe("Structured slide content."),
       evidence: tool.schema.array(tool.schema.object({
         source: tool.schema.string().describe("Source file, URL, or research note."),
-        quote: tool.schema.string().optional(),
-        page: tool.schema.string().optional(),
-        url: tool.schema.string().optional(),
-      })).optional().describe("Evidence references for this slide."),
+        quote: tool.schema.string().optional().describe("Compact quote or snippet supporting the slide claim."),
+        page: tool.schema.string().optional().describe("Legacy page reference; prefer location for new page/slide/sheet/section references."),
+        url: tool.schema.string().optional().describe("Source URL when available."),
+        sourcePath: tool.schema.string().optional().describe("Workspace source file path when the evidence came from a local material."),
+        location: tool.schema.string().optional().describe("Generic page, slide, sheet, section, or other source location reference."),
+        findingsFile: tool.schema.string().optional().describe("researches/{topic}/{axis}.md findings file that records the supporting evidence."),
+        caveat: tool.schema.string().optional().describe("Scope, uncertainty, or limitation that should travel with this evidence."),
+        extractedTextPath: tool.schema.string().optional().describe("Reusable extracted text cache path when this evidence came from extracted materials."),
+        extractedManifestPath: tool.schema.string().optional().describe("Reusable extracted materials manifest path when available."),
+      })).optional().describe("Compact evidence references and source trace for this slide."),
       visuals: tool.schema.array(tool.schema.object({
         id: tool.schema.string().optional(),
         purpose: tool.schema.string().optional(),