@cyber-dash-tech/revela 0.8.7 → 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

@@ -19,6 +19,7 @@ Goal:
 - 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}
@@ -33,19 +34,23 @@ 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\` plus structured readiness issues for the current workspace deck.
-6. 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.
+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. Numeric claims and strong recommendations should not be unsupported.
+- 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.
 
@@ -54,6 +59,7 @@ Report format:
 - 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.

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 {
@@ -164,6 +170,8 @@ export interface ReadinessIssue {
   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)
 }
@@ -432,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,
@@ -515,14 +567,14 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
       issues.push(blockerIssue(
         "missing_evidence",
         `Slide ${slide.index} has an evidence-sensitive claim without evidence: ${claim}`,
-        "Add a compact evidence reference to slides[].evidence or reframe the claim as an explicit assumption/opinion.",
+        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 quote, page, or URL detail: ${claim}`,
-        "Add quote/page/url details where available so the writing agent can ground the slide more reliably.",
+        `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 },
       ))
     }
@@ -592,7 +644,15 @@ function hasNumericClaim(text: string): boolean {
 }
 
 function hasEvidenceDetail(evidence: EvidenceRef): boolean {
-  return Boolean(evidence.quote?.trim() || evidence.page?.trim() || evidence.url?.trim())
+  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 = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.8.7",
+  "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(),