@cyber-dash-tech/revela 0.9.0 → 0.11.0

package/lib/decks-state.ts

@@ -1,7 +1,24 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
-import { basename, dirname, join, resolve } from "path"
-
-export const DECKS_STATE_FILE = "DECKS.json"
+import { existsSync, readdirSync, readFileSync, statSync } from "fs"
+import { createHash } from "crypto"
+import { basename, join, resolve } from "path"
+import {
+  hasWorkspaceState,
+  readOrCreateWorkspaceState,
+  readWorkspaceState,
+  workspaceStatePath,
+  writeWorkspaceState,
+} from "./workspace-state/repository"
+import { ensureActiveHtmlDeckRenderTarget } from "./workspace-state/render-targets"
+import {
+  activeReviewTargetId,
+  appendReviewSnapshot,
+  createReviewSnapshot,
+  isReviewSnapshotCurrent,
+  latestReviewSnapshotForTarget,
+} from "./workspace-state/review-snapshots"
+import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type WorkspaceAction } from "./workspace-state/types"
+
+export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
 
 export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
@@ -22,6 +39,9 @@ export interface DecksState {
     openQuestions: string[]
   }
   decks: Record<string, DeckSpec>
+  actions: WorkspaceAction[]
+  renderTargets: RenderTarget[]
+  reviews: ReviewSnapshot[]
 }
 
 export interface SourceMaterial {
@@ -161,6 +181,7 @@ export interface DeckStateReadinessResult {
   blockers: string[]
   warnings: string[]
   issues: ReadinessIssue[]
+  evidenceCandidates?: EvidenceBindingCandidate[]
 }
 
 export type ReadinessSeverity = "blocker" | "warning"
@@ -182,16 +203,76 @@ export interface ReadinessIssue {
   slideIndex?: number
   slideTitle?: string
   claimText?: string
+  evidenceCandidates?: EvidenceBindingCandidate[]
+  evidenceCandidateSearch?: EvidenceCandidateSearchDiagnostic
+}
+
+export interface EvidenceBindingCandidate {
+  candidateId: string
+  slideIndex: number
+  slideTitle?: string
+  claimText?: string
+  source: string
+  findingsFile?: string
+  sourcePath?: string
+  location?: string
+  quote?: string
+  caveat?: string
+  supportScope: string[]
+  supportStrength: "partial" | "strong"
+  sourceKind?: "researchPlan" | "researchesFallback"
+  evidenceDraft?: EvidenceRef
+  unsupportedScope?: string[]
+  recommendedRewrite?: string
+}
+
+export interface EvidenceCandidateSearchDiagnostic {
+  queryTokens: string[]
+  researchPlanFindingsSearched: string[]
+  fallbackResearchFilesSearched: string[]
+  fallbackResearchFilesSkipped: string[]
+  nearMisses: EvidenceCandidateNearMiss[]
+}
+
+export interface EvidenceCandidateNearMiss {
+  findingsFile: string
+  sourceKind: "researchPlan" | "researchesFallback"
+  bestScore: number
+  threshold: number
+  supportScope: string[]
+  quote?: string
+  reason: string
+}
+
+export interface ApplyEvidenceCandidatesResult {
+  applied: AppliedEvidenceCandidate[]
+  skipped: SkippedEvidenceCandidate[]
+  nextReviewNeeded: boolean
+}
+
+export interface AppliedEvidenceCandidate {
+  candidateId: string
+  slideIndex: number
+  evidence: EvidenceRef
+}
+
+export interface SkippedEvidenceCandidate {
+  candidateId: string
+  reason: 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 interface ReviewDeckStateOptions {
+  workspaceRoot?: string
+}
+
 export function decksStatePath(workspaceRoot: string): string {
-  return join(workspaceRoot, DECKS_STATE_FILE)
+  return workspaceStatePath(workspaceRoot, DECKS_STATE_FILE)
 }
 
 export function hasDecksState(workspaceRoot: string): boolean {
-  return existsSync(decksStatePath(workspaceRoot))
+  return hasWorkspaceState(workspaceRoot, DECKS_STATE_FILE)
 }
 
 export function createEmptyDecksState(): DecksState {
@@ -204,6 +285,9 @@ export function createEmptyDecksState(): DecksState {
       openQuestions: [],
     },
     decks: {},
+    actions: [],
+    renderTargets: [],
+    reviews: [],
   }
 }
 
@@ -227,6 +311,7 @@ export function normalizeWorkspaceDeckState(state: DecksState, workspaceRoot: st
   delete normalized.decks[existingKey]
   normalized.decks[slug] = deck
   normalized.activeDeck = slug
+  ensureActiveHtmlDeckRenderTarget(normalized)
   return normalized
 }
 
@@ -264,21 +349,15 @@ export function createDeckSpec(input: Partial<DeckSpec> & { slug: string }): Dec
 }
 
 export function readDecksState(workspaceRoot: string): DecksState {
-  const parsed = JSON.parse(readFileSync(decksStatePath(workspaceRoot), "utf-8")) as DecksState
-  return normalizeDecksState(parsed)
+  return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
 }
 
 export function writeDecksState(workspaceRoot: string, state: DecksState): void {
-  const filePath = decksStatePath(workspaceRoot)
-  mkdirSync(dirname(filePath), { recursive: true })
-  writeFileSync(filePath, JSON.stringify(normalizeDecksState(state), null, 2) + "\n", "utf-8")
+  writeWorkspaceState(workspaceRoot, state, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
 }
 
 export function readOrCreateDecksState(workspaceRoot: string): DecksState {
-  if (hasDecksState(workspaceRoot)) return readDecksState(workspaceRoot)
-  const state = createEmptyDecksState()
-  writeDecksState(workspaceRoot, state)
-  return state
+  return readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
 }
 
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
@@ -292,6 +371,7 @@ export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug:
   const next = createDeckSpec({ ...existing, ...input, slug })
   normalized.decks[slug] = next
   normalized.activeDeck = slug
+  ensureActiveHtmlDeckRenderTarget(normalized)
   return normalized
 }
 
@@ -308,10 +388,69 @@ export function upsertSlides(state: DecksState, slug: string, slides: SlideSpec[
   deck.slides = [...byIndex.values()].sort((a, b) => a.index - b.index)
   normalized.decks[key] = deck
   normalized.activeDeck = key
+  ensureActiveHtmlDeckRenderTarget(normalized)
   return normalized
 }
 
-export function reviewDeckState(state: DecksState, slug?: string): { state: DecksState; result: DeckStateReadinessResult } {
+export function applyEvidenceCandidates(state: DecksState, candidateIds: string[], options: ReviewDeckStateOptions = {}): { state: DecksState; result: ApplyEvidenceCandidatesResult } {
+  const normalized = normalizeDecksState(state)
+  const ids = [...new Set(candidateIds.map((id) => id.trim()).filter(Boolean))]
+  const applied: AppliedEvidenceCandidate[] = []
+  const skipped: SkippedEvidenceCandidate[] = []
+  const key = currentDeckKey(normalized)
+  const deck = key ? normalized.decks[key] : undefined
+
+  if (!deck) {
+    return {
+      state: normalized,
+      result: {
+        applied,
+        skipped: ids.map((candidateId) => ({ candidateId, reason: `No active deck exists in ${DECKS_STATE_FILE}.` })),
+        nextReviewNeeded: false,
+      },
+    }
+  }
+
+  const review = reviewDeckState(normalized, deck.slug, options)
+  const byId = new Map((review.result.evidenceCandidates ?? []).map((candidate) => [candidate.candidateId, candidate]))
+  const next = normalizeDecksState(review.state)
+  const nextDeck = next.decks[deck.slug]
+
+  for (const candidateId of ids) {
+    const candidate = byId.get(candidateId)
+    if (!candidate) {
+      skipped.push({ candidateId, reason: "Candidate was not found in the current review result." })
+      continue
+    }
+    if (!candidate.evidenceDraft) {
+      skipped.push({ candidateId, reason: "Candidate has no evidenceDraft to apply." })
+      continue
+    }
+    const slide = nextDeck.slides.find((item) => item.index === candidate.slideIndex)
+    if (!slide) {
+      skipped.push({ candidateId, reason: `Slide ${candidate.slideIndex} no longer exists.` })
+      continue
+    }
+    const evidence = cleanEvidenceRef(candidate.evidenceDraft)
+    if (slide.evidence.some((item) => sameEvidenceRef(item, evidence))) {
+      skipped.push({ candidateId, reason: `Slide ${candidate.slideIndex} already has this evidence record.` })
+      continue
+    }
+    slide.evidence.push(evidence)
+    applied.push({ candidateId, slideIndex: candidate.slideIndex, evidence })
+  }
+
+  return {
+    state: next,
+    result: {
+      applied,
+      skipped,
+      nextReviewNeeded: applied.length > 0,
+    },
+  }
+}
+
+export function reviewDeckState(state: DecksState, slug?: string, options: ReviewDeckStateOptions = {}): { state: DecksState; result: DeckStateReadinessResult } {
   const normalized = normalizeDecksState(state)
   const key = normalizeSlug(slug || currentDeckKey(normalized) || "")
   const deck = key ? normalized.decks[key] : undefined
@@ -335,28 +474,33 @@ export function reviewDeckState(state: DecksState, slug?: string): { state: Deck
     }
   }
 
-  const issues = computeDeckReadinessIssues(deck, normalized.workspace)
+  const issues = computeDeckReadinessIssues(deck, normalized.workspace, options)
   const blockers = issues.filter((issue) => issue.severity === "blocker").map((issue) => issue.message)
   const warnings = issues.filter((issue) => issue.severity === "warning").map((issue) => issue.message)
+  const evidenceCandidates = issues.flatMap((issue) => issue.evidenceCandidates ?? [])
+  const reviewedAt = new Date().toISOString()
   deck.writeReadiness = {
     status: blockers.length === 0 ? "ready" : "blocked",
     blockers,
-    lastReviewedAt: new Date().toISOString(),
+    lastReviewedAt: reviewedAt,
   }
   deck.status = blockers.length === 0 ? "ready" : "blocked"
   normalized.decks[deck.slug] = deck
   normalized.activeDeck = deck.slug
+  const result: DeckStateReadinessResult = {
+    ready: blockers.length === 0,
+    slug: deck.slug,
+    status: deck.writeReadiness.status,
+    blocker: blockers.join("; "),
+    blockers,
+    warnings,
+    issues,
+    evidenceCandidates,
+  }
+  appendReviewSnapshot(normalized, createReviewSnapshot(normalized, { slug: deck.slug, result, reviewedAt }))
   return {
     state: normalized,
-    result: {
-      ready: blockers.length === 0,
-      slug: deck.slug,
-      status: deck.writeReadiness.status,
-      blocker: blockers.join("; "),
-      blockers,
-      warnings,
-      issues,
-    },
+    result,
   }
 }
 
@@ -420,6 +564,38 @@ export function evaluateDeckStateWriteReadiness(state: DecksState, filePath: str
       suggestedAction: "Resolve the stored writeReadiness blockers and rerun /revela review.",
     })
   }
+  if (normalized.reviews.length > 0) {
+    const targetId = activeReviewTargetId(normalized)
+    const snapshot = latestReviewSnapshotForTarget(normalized, targetId)
+    if (!snapshot) {
+      const message = "No review snapshot exists for the active HTML render target"
+      blockers.unshift(message)
+      issues.unshift({
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message,
+        suggestedAction: "Run /revela review so readiness is recorded against the current active render target.",
+      })
+    } else if (!isReviewSnapshotCurrent(normalized, snapshot, deck.slug)) {
+      const message = "Latest review snapshot is stale for the current deck, sources, evidence, narrative state, or render target"
+      blockers.unshift(message)
+      issues.unshift({
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message,
+        suggestedAction: "Run /revela review again after the latest state changes before writing deck HTML.",
+      })
+    } else if (snapshot.status !== "ready") {
+      const message = `Latest review snapshot is ${snapshot.status}, not ready`
+      blockers.unshift(message)
+      issues.unshift({
+        type: "missing_slide_spec",
+        severity: "blocker",
+        message,
+        suggestedAction: "Resolve review blockers and rerun /revela review before writing deck HTML.",
+      })
+    }
+  }
 
   return {
     ready: blockers.length === 0,
@@ -457,10 +633,12 @@ export function buildDecksStatePromptLayer(workspaceRoot: string, maxChars = 140
     activeDeck: activeKey,
     workspace: compactWorkspaceForPrompt(state.workspace),
     deck: active ? compactDeckForPrompt(active) : undefined,
+    renderTargets: state.renderTargets,
+    reviews: compactReviewsForPrompt(state.reviews),
   }
   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.`
+  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, evidence, render targets, and write readiness.\n- The decks map is compatibility storage; operate only on the current workspace deck.\n- ${DECKS_STATE_FILE} deck slides use 1-based \`slides[].index\` values. Render every HTML \`<section class="slide">\` with a matching 1-based \`data-slide-index\` attribute, and do not use 0-based \`data-index\` as slide identity.\n- The active HTML deck is represented as a \`renderTarget\` of type \`html_deck\`; PDF/PPTX exports should be recorded as derived render targets, not as separate deck specs.\n- \`writeReadiness\` is a compatibility projection. When review snapshots exist, deck HTML writes require a current non-stale ready review snapshot for the active HTML render target.\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"] {
@@ -493,6 +671,20 @@ function compactDeckForPrompt(deck: DeckSpec): DeckSpec {
   }
 }
 
+function compactReviewsForPrompt(reviews: ReviewSnapshot[]): ReviewSnapshot[] {
+  return reviews.slice(-5).map((review) => ({
+    id: review.id,
+    targetId: review.targetId,
+    inputHash: review.inputHash,
+    status: review.status,
+    blockers: review.blockers.slice(0, 5),
+    warnings: review.warnings.slice(0, 5),
+    issues: review.issues.slice(0, 10),
+    evidenceCandidates: review.evidenceCandidates?.slice(0, 10),
+    reviewedAt: review.reviewedAt,
+  }))
+}
+
 function compactNarrativeBriefForPrompt(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
   if (!brief) return undefined
   return {
@@ -536,6 +728,9 @@ function normalizeDecksState(input: DecksState): DecksState {
       openQuestions: input.workspace?.openQuestions ?? [],
     },
     decks: {},
+    actions: input.actions ?? [],
+    renderTargets: input.renderTargets ?? [],
+    reviews: input.reviews ?? [],
   }
   for (const [slug, deck] of Object.entries(input.decks ?? {})) {
     const normalizedSlug = normalizeSlug(deck.slug || slug)
@@ -546,6 +741,7 @@ function normalizeDecksState(input: DecksState): DecksState {
     const keys = Object.keys(state.decks)
     if (keys.length === 1) state.activeDeck = keys[0]
   }
+  ensureActiveHtmlDeckRenderTarget(state)
   return state
 }
 
@@ -562,7 +758,7 @@ 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 computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["workspace"]): ReadinessIssue[] {
+function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["workspace"], options: ReviewDeckStateOptions = {}): 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)) {
@@ -592,12 +788,18 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
     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) {
+    if (claim && slide.evidence.length === 0 && !isNavigationSlide(slide)) {
+      const { candidates: evidenceCandidates, search: evidenceCandidateSearch } = findEvidenceBindingCandidates(deck, slide, claim, options)
       issues.push(blockerIssue(
         "missing_evidence",
         `Slide ${slide.index} has an evidence-sensitive claim without evidence: ${claim}`,
         SOURCE_TRACE_ACTION,
-        { ...slideRef, claimText: claim },
+        {
+          ...slideRef,
+          claimText: claim,
+          evidenceCandidates: evidenceCandidates.length > 0 ? evidenceCandidates : undefined,
+          evidenceCandidateSearch,
+        },
       ))
     } else if (claim && slide.evidence.some((item) => !hasEvidenceDetail(item))) {
       issues.push(warningIssue(
@@ -624,6 +826,7 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   const hasNeededResearch = deck.researchPlan.some((axis) => axis.needed && axis.status !== "skipped")
   for (const material of workspace.sourceMaterials ?? []) {
     if (material.status !== "discovered") continue
+    if (isIgnorableSourceMaterial(material.path)) continue
     const message = `Source material ${material.path} has been identified but not extracted, summarized, or researched`
     if (hasNeededResearch) {
       issues.push(blockerIssue(
@@ -643,6 +846,297 @@ function computeDeckReadinessIssues(deck: DeckSpec, workspace: DecksState["works
   return issues
 }
 
+function findEvidenceBindingCandidates(deck: DeckSpec, slide: SlideSpec, claimText: string, options: ReviewDeckStateOptions): { candidates: EvidenceBindingCandidate[]; search?: EvidenceCandidateSearchDiagnostic } {
+  if (!options.workspaceRoot) return { candidates: [] }
+  const queryText = slideSearchText(slide)
+  const queryTokens = meaningfulTokens(queryText)
+  if (queryTokens.length === 0) return { candidates: [] }
+
+  const candidates: EvidenceBindingCandidate[] = []
+  const search: EvidenceCandidateSearchDiagnostic = {
+    queryTokens,
+    researchPlanFindingsSearched: [],
+    fallbackResearchFilesSearched: [],
+    fallbackResearchFilesSkipped: [],
+    nearMisses: [],
+  }
+  const planFindings = new Set<string>()
+  for (const axis of deck.researchPlan) {
+    if (!axis.needed || (axis.status !== "done" && axis.status !== "read") || !axis.findingsFile?.trim()) continue
+    const normalizedFindingsFile = normalizePath(axis.findingsFile)
+    planFindings.add(normalizedFindingsFile)
+    search.researchPlanFindingsSearched.push(normalizedFindingsFile)
+    const findingsPath = safeWorkspacePath(options.workspaceRoot, axis.findingsFile)
+    if (!findingsPath || !existsSync(findingsPath)) continue
+    const text = readTextPrefix(findingsPath, 100_000)
+    if (!text.trim()) continue
+    const result = candidateFromFindingsFile({
+      slide,
+      claimText,
+      queryTokens,
+      findingsFile: normalizedFindingsFile,
+      text,
+      sourceKind: "researchPlan",
+    })
+    if (result.candidate) candidates.push(result.candidate)
+    else if (result.nearMiss) search.nearMisses.push(result.nearMiss)
+  }
+
+  if (candidates.length === 0) {
+    for (const findingsFile of listWorkspaceResearchFindings(options.workspaceRoot, planFindings)) {
+      search.fallbackResearchFilesSearched.push(findingsFile)
+      const findingsPath = safeWorkspacePath(options.workspaceRoot, findingsFile)
+      if (!findingsPath || !existsSync(findingsPath)) {
+        search.fallbackResearchFilesSkipped.push(findingsFile)
+        continue
+      }
+      const text = readTextPrefix(findingsPath, 100_000)
+      if (!text.trim()) {
+        search.fallbackResearchFilesSkipped.push(findingsFile)
+        continue
+      }
+      const result = candidateFromFindingsFile({
+        slide,
+        claimText,
+        queryTokens,
+        findingsFile,
+        text,
+        sourceKind: "researchesFallback",
+      })
+      if (result.candidate) candidates.push(result.candidate)
+      else if (result.nearMiss) search.nearMisses.push(result.nearMiss)
+    }
+  }
+
+  search.nearMisses = search.nearMisses
+    .sort((a, b) => b.bestScore - a.bestScore)
+    .slice(0, 5)
+  return {
+    candidates: candidates
+      .sort((a, b) => b.supportScope.length - a.supportScope.length)
+      .slice(0, 3),
+    search,
+  }
+}
+
+function candidateFromFindingsFile({
+  slide,
+  claimText,
+  queryTokens,
+  findingsFile,
+  text,
+  sourceKind,
+}: {
+  slide: SlideSpec
+  claimText: string
+  queryTokens: string[]
+  findingsFile: string
+  text: string
+  sourceKind: "researchPlan" | "researchesFallback"
+}): { candidate?: EvidenceBindingCandidate; nearMiss?: EvidenceCandidateNearMiss } {
+  const lines = extractFindingsLines(text)
+  let best: { line: string; scope: string[]; score: number } | undefined
+  for (const line of lines) {
+    const normalizedLine = line.toLowerCase()
+    const scope = queryTokens.filter((token) => normalizedLine.includes(token))
+    const phraseScore = importantPhrases(slide).filter((phrase) => normalizedLine.includes(phrase)).length * 2
+    const score = scope.length + phraseScore
+    if (!best || score > best.score) best = { line, scope, score }
+  }
+  if (!best || best.score <= 0) return {}
+
+  const threshold = 2
+  const supportScope = [...new Set(best.scope)].slice(0, 8)
+  if (best.score < threshold) {
+    return {
+      nearMiss: {
+        findingsFile,
+        sourceKind,
+        bestScore: best.score,
+        threshold,
+        supportScope,
+        quote: best.line,
+        reason: `Best matching line scored ${best.score}, below binding threshold ${threshold}.`,
+      },
+    }
+  }
+
+  const sourcePath = extractSourcePath(text)
+  const coverage = supportScope.length / Math.max(1, queryTokens.length)
+  const supportStrength = best.score >= Math.min(5, Math.max(3, queryTokens.length)) && coverage >= 0.5 ? "strong" : "partial"
+  const unsupportedScope = unsupportedClaimScope(slide, best.line).slice(0, 5)
+  const caveats = []
+  if (supportStrength === "partial") {
+    caveats.push("Candidate support is partial. Bind only the matched claim scope; do not use it to support unrelated future-state or recommendation claims on the same slide.")
+  }
+  if (sourceKind === "researchesFallback") {
+    caveats.push("Candidate was discovered from researches/ fallback and is not referenced by researchPlan; confirm relevance before binding it into slide evidence.")
+  }
+  if (unsupportedScope.length > 0) {
+    caveats.push(`Unsupported claim scope: ${unsupportedScope.join("; ")}.`)
+  }
+  const caveat = caveats.length > 0 ? caveats.join(" ") : undefined
+  const evidenceDraft: EvidenceRef = {
+    source: sourcePath || findingsFile,
+    findingsFile,
+    sourcePath,
+    location: "research findings excerpt",
+    quote: best.line,
+    caveat,
+  }
+  return {
+    candidate: {
+      candidateId: evidenceCandidateId(slide.index, findingsFile, best.line, supportScope),
+      slideIndex: slide.index,
+      slideTitle: slide.title,
+      claimText,
+      source: sourcePath || findingsFile,
+      findingsFile,
+      sourcePath,
+      location: "research findings excerpt",
+      quote: best.line,
+      caveat,
+      supportScope,
+      supportStrength,
+      sourceKind,
+      evidenceDraft,
+      unsupportedScope,
+      recommendedRewrite: recommendedEvidenceRewrite(supportScope, unsupportedScope),
+    },
+  }
+}
+
+function unsupportedClaimScope(slide: SlideSpec, supportedLine: string): string[] {
+  const normalizedLine = supportedLine.toLowerCase()
+  const phrases = [slide.purpose, slide.content?.headline, ...(slide.content?.bullets ?? [])]
+    .map((item) => cleanMarkdownText(item ?? ""))
+    .filter((item) => item.length >= 8)
+
+  return [...new Set(phrases.filter((phrase) => {
+    const normalizedPhrase = phrase.toLowerCase()
+    return FUTURE_STATE_SCOPE_PATTERN.test(normalizedPhrase) && !normalizedLine.includes(normalizedPhrase)
+  }))]
+}
+
+function recommendedEvidenceRewrite(supportScope: string[], unsupportedScope: string[]): string | undefined {
+  if (unsupportedScope.length === 0) return undefined
+  const supported = supportScope.length > 0 ? supportScope.join(", ") : "the quoted current-state support"
+  return `Bind this evidence only to the supported scope (${supported}). Reframe unsupported scope as internal synthesis, target-state hypothesis, or a separately sourced claim: ${unsupportedScope.join("; ")}.`
+}
+
+function evidenceCandidateId(slideIndex: number, findingsFile: string, quote: string, supportScope: string[]): string {
+  const hash = createHash("sha1")
+    .update(JSON.stringify({ slideIndex, findingsFile, quote, supportScope }))
+    .digest("hex")
+    .slice(0, 8)
+  return `s${slideIndex}-${hash}`
+}
+
+function cleanEvidenceRef(evidence: EvidenceRef): EvidenceRef {
+  const cleaned: EvidenceRef = { source: cleanMarkdownText(evidence.source) }
+  for (const key of ["quote", "page", "url", "sourcePath", "location", "findingsFile", "caveat", "extractedTextPath", "extractedManifestPath"] as const) {
+    const value = cleanOptionalText(evidence[key])
+    if (value) cleaned[key] = value
+  }
+  return cleaned
+}
+
+function sameEvidenceRef(a: EvidenceRef, b: EvidenceRef): boolean {
+  return normalizeEvidenceComparable(a) === normalizeEvidenceComparable(b)
+}
+
+function normalizeEvidenceComparable(evidence: EvidenceRef): string {
+  const cleaned = cleanEvidenceRef(evidence)
+  return JSON.stringify({
+    source: cleaned.source,
+    findingsFile: cleaned.findingsFile,
+    sourcePath: cleaned.sourcePath,
+    quote: cleaned.quote,
+    location: cleaned.location,
+    caveat: cleaned.caveat,
+  })
+}
+
+function listWorkspaceResearchFindings(workspaceRoot: string, exclude: Set<string>): string[] {
+  const researchRoot = safeWorkspacePath(workspaceRoot, "researches")
+  if (!researchRoot || !existsSync(researchRoot)) return []
+  const files: string[] = []
+  collectMarkdownFiles(researchRoot, files, 0)
+  return files
+    .map((file) => normalizePath(file.slice(resolve(workspaceRoot).length + 1)))
+    .filter((file) => file.startsWith("researches/") && !exclude.has(file))
+    .slice(0, 50)
+}
+
+function collectMarkdownFiles(dir: string, output: string[], depth: number): void {
+  if (depth > 4) return
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry)
+    let stat
+    try {
+      stat = statSync(fullPath)
+    } catch {
+      continue
+    }
+    if (stat.isDirectory()) {
+      collectMarkdownFiles(fullPath, output, depth + 1)
+    } else if (stat.isFile() && entry.endsWith(".md")) {
+      output.push(fullPath)
+    }
+  }
+}
+
+function safeWorkspacePath(workspaceRoot: string, relativePath: string): string | undefined {
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + "/")) return undefined
+  return target
+}
+
+function readTextPrefix(filePath: string, maxChars: number): string {
+  try {
+    return readFileSync(filePath, "utf-8").slice(0, maxChars)
+  } catch {
+    return ""
+  }
+}
+
+function extractFindingsLines(text: string): string[] {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^\s*(?:[-*+]\s+|\d+\.\s+|>\s*)/, "").trim())
+    .filter((line) => line.length >= 24 && !/^---$/.test(line) && !/^#/.test(line))
+    .slice(0, 300)
+}
+
+function extractSourcePath(text: string): string | undefined {
+  const sourceLine = text.split(/\r?\n/).find((line) => /^\s*(?:[-*+]\s*)?(?:source|来源)\s*:/i.test(line))
+  if (!sourceLine) return undefined
+  return cleanMarkdownText(sourceLine.replace(/^\s*(?:[-*+]\s*)?(?:source|来源)\s*:\s*/i, "")) || undefined
+}
+
+function meaningfulTokens(text: string): string[] {
+  const normalized = text.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, " ")
+  const latin = normalized
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 4 && !EVIDENCE_BINDING_STOPWORDS.has(token))
+  const chinese = Array.from(normalized.matchAll(/[\u4e00-\u9fa5]{2,}/g), (match) => match[0])
+  return [...new Set([...latin, ...chinese])].slice(0, 40)
+}
+
+function importantPhrases(slide: SlideSpec): string[] {
+  return [slide.title, slide.content?.headline, ...(slide.content?.bullets ?? [])]
+    .map((item) => item?.trim().toLowerCase())
+    .filter((item): item is string => Boolean(item && item.length >= 8 && item.length <= 80))
+}
+
 function computeNarrativeReadinessIssues(deck: DeckSpec): ReadinessIssue[] {
   const issues: ReadinessIssue[] = []
   const slides = deck.slides.filter((slide) => slide.index > 0).sort((a, b) => a.index - b.index)
@@ -842,6 +1336,25 @@ function hasClearEnding(slides: SlideSpec[]): boolean {
   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 isNavigationSlide(slide: SlideSpec): boolean {
+  const text = slideSearchText(slide)
+  return slide.layout === "toc" || /\b(table of contents|agenda|contents|outline|section guide)\b|目录|议程|大纲/.test(text)
+}
+
+function isIgnorableSourceMaterial(path: string): boolean {
+  const normalized = normalizePath(path).replace(/^\.\//, "")
+  const name = basename(normalized)
+  return Boolean(
+    name.startsWith("~$") ||
+      /^(AGENTS|README(?:\.zh-CN)?|DECKS)\.md$/.test(name) ||
+      name === DECKS_STATE_FILE ||
+      normalized.startsWith("decks/") ||
+      normalized.startsWith("researches/") ||
+      normalized.startsWith("assets/") ||
+      normalized.startsWith(".opencode/"),
+  )
+}
+
 function slideSearchText(slide: SlideSpec): string {
   return [
     slide.title,
@@ -918,6 +1431,36 @@ const EVIDENCE_SENSITIVE_TERMS = [
   /可扩展/,
 ]
 
+const FUTURE_STATE_SCOPE_PATTERN = /\b(20\d{2}|future|target-state|end state|roadmap|pathway|architecture|capabilit(?:y|ies)|autonomy|autonomous|self-organizing|ecosystem|ai manufacturing os|ai brain|digital workers|closed-loop|orchestration)\b|未来|目标态|路线图|架构|能力|自治|自组织|生态|智能体|闭环/
+
+const EVIDENCE_BINDING_STOPWORDS = new Set([
+  "about",
+  "after",
+  "again",
+  "also",
+  "before",
+  "between",
+  "could",
+  "deck",
+  "from",
+  "have",
+  "into",
+  "must",
+  "only",
+  "over",
+  "page",
+  "roadmap",
+  "show",
+  "slide",
+  "that",
+  "their",
+  "there",
+  "this",
+  "through",
+  "with",
+  "would",
+])
+
 function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
   return slides
     .map((slide) => ({