@cyber-dash-tech/revela 0.12.0 → 0.13.0

package/lib/narrative-state/normalize.ts

@@ -1,9 +1,11 @@
 import type { DeckSpec, DecksState, EvidenceRef, SlideSpec } from "../decks-state"
 import {
   stableClaimId,
+  stableClaimRelationId,
   stableEvidenceId,
   stableNarrativeId,
   stableObjectionId,
+  stableResearchGapId,
   stableRiskId,
 } from "./hash"
 import type {
@@ -11,9 +13,12 @@ import type {
   DecisionIntent,
   NarrativeClaim,
   NarrativeClaimKind,
+  NarrativeClaimRelation,
+  NarrativeClaimRelationType,
   NarrativeEvidenceBinding,
   NarrativeEvidenceStatus,
   NarrativeObjection,
+  NarrativeResearchGap,
   NarrativeRisk,
   NarrativeStateV1,
   NarrativeStatus,
@@ -26,6 +31,7 @@ export function normalizeCanonicalNarrativeState(input: Partial<NarrativeStateV1
   if (!input) return undefined
   const id = input.id?.trim() || stableNarrativeId(seed)
   const claims = dedupeById((input.claims ?? []).map(normalizeClaim).filter((claim): claim is NarrativeClaim => Boolean(claim)))
+  const claimRelations = dedupeById((input.claimRelations ?? []).map((relation) => normalizeClaimRelation(relation, claims)).filter((relation): relation is NarrativeClaimRelation => Boolean(relation)))
   const evidenceBindings = dedupeById((input.evidenceBindings ?? []).map((binding) => normalizeEvidenceBinding(binding, claims)).filter((binding): binding is NarrativeEvidenceBinding => Boolean(binding)))
   return {
     version: 1,
@@ -35,9 +41,11 @@ export function normalizeCanonicalNarrativeState(input: Partial<NarrativeStateV1
     decision: normalizeDecision(input.decision),
     thesis: normalizeThesis(input.thesis),
     claims: claims.map((claim) => ({ ...claim, evidenceStatus: evidenceStatusForClaim(claim, evidenceBindings) })),
+    claimRelations,
     evidenceBindings,
     objections: dedupeById((input.objections ?? []).map(normalizeObjection).filter((objection): objection is NarrativeObjection => Boolean(objection))),
     risks: dedupeById((input.risks ?? []).map(normalizeRisk).filter((risk): risk is NarrativeRisk => Boolean(risk))),
+    researchGaps: dedupeById((input.researchGaps ?? []).map(normalizeResearchGap).filter((gap): gap is NarrativeResearchGap => Boolean(gap))),
     approvals: input.approvals ?? [],
     updatedAt: input.updatedAt || MIGRATED_UPDATED_AT,
   }
@@ -71,9 +79,11 @@ function migrateDeckNarrative(deck: DeckSpec | undefined, seed: string): Narrati
     },
     thesis: migrateThesis(deck),
     claims: withEvidenceStatus,
+    claimRelations: [],
     evidenceBindings,
     objections: (brief?.objections ?? []).map((text) => ({ id: stableObjectionId(text), text, priority: "medium" as const })),
     risks: (brief?.risks ?? []).map((text) => ({ id: stableRiskId(text), text, severity: "medium" as const })),
+    researchGaps: [],
     approvals: [],
     updatedAt: MIGRATED_UPDATED_AT,
   }
@@ -206,6 +216,26 @@ function normalizeClaim(input: Partial<NarrativeClaim>): NarrativeClaim | undefi
   }
 }
 
+function normalizeClaimRelation(input: Partial<NarrativeClaimRelation>, claims: NarrativeClaim[]): NarrativeClaimRelation | undefined {
+  const fromClaimId = clean(input.fromClaimId)
+  const toClaimId = clean(input.toClaimId)
+  if (!fromClaimId || !toClaimId || fromClaimId === toClaimId) return undefined
+  if (!claims.some((claim) => claim.id === fromClaimId) || !claims.some((claim) => claim.id === toClaimId)) return undefined
+  const relation = normalizeClaimRelationType(input.relation)
+  return {
+    id: input.id?.trim() || stableClaimRelationId(fromClaimId, toClaimId, relation),
+    fromClaimId,
+    toClaimId,
+    relation,
+    rationale: clean(input.rationale),
+  }
+}
+
+function normalizeClaimRelationType(input: NarrativeClaimRelationType | undefined): NarrativeClaimRelationType {
+  if (input === "supports" || input === "depends_on" || input === "contrasts_with" || input === "constrains" || input === "answers") return input
+  return "leads_to"
+}
+
 function normalizeEvidenceBinding(input: Partial<NarrativeEvidenceBinding>, claims: NarrativeClaim[]): NarrativeEvidenceBinding | undefined {
   const source = clean(input.source || input.sourcePath || input.findingsFile || input.url)
   const claimId = clean(input.claimId)
@@ -239,6 +269,30 @@ function normalizeRisk(input: Partial<NarrativeRisk>): NarrativeRisk | undefined
   return { id: input.id?.trim() || stableRiskId(text), text, claimId: clean(input.claimId), severity: input.severity ?? "medium", mitigation: clean(input.mitigation) }
 }
 
+function normalizeResearchGap(input: Partial<NarrativeResearchGap>): NarrativeResearchGap | undefined {
+  const question = clean(input.question)
+  if (!question) return undefined
+  const targetType = input.targetType ?? "narrative"
+  const targetId = clean(input.targetId)
+  const now = clean(input.updatedAt) || clean(input.createdAt) || MIGRATED_UPDATED_AT
+  const status = input.status ?? "open"
+  return {
+    id: input.id?.trim() || stableResearchGapId([targetType, targetId, question].filter(Boolean).join("|")),
+    targetType,
+    targetId,
+    question,
+    status,
+    priority: input.priority ?? "medium",
+    findingsFile: clean(input.findingsFile),
+    evidenceBindingIds: (input.evidenceBindingIds ?? []).map(clean).filter(Boolean),
+    createdFromIssueType: input.createdFromIssueType,
+    notes: clean(input.notes),
+    createdAt: clean(input.createdAt) || now,
+    updatedAt: now,
+    closedAt: status === "closed" ? clean(input.closedAt) || now : clean(input.closedAt),
+  }
+}
+
 function evidenceStatusForClaim(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): NarrativeEvidenceStatus {
   if (!claim.evidenceRequired) return "not_required"
   const claimBindings = bindings.filter((binding) => binding.claimId === claim.id)

package/lib/narrative-state/queries.ts

@@ -0,0 +1,433 @@
+import type { DeckSpec, DecksState, EvidenceRef, SlideClaimRefRole, SlideSpec } from "../decks-state"
+import { projectWorkspaceGraph } from "../workspace-state/graph"
+import { artifactNodeIdForRenderTarget } from "../workspace-state/render-targets"
+import type { GraphEdge, RenderTarget } from "../workspace-state/types"
+import { computeNarrativeHash } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import type { NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "./types"
+
+export interface ClaimEvidenceBoard {
+  version: 1
+  claims: Record<NarrativeClaim["evidenceStatus"], ClaimEvidenceRecord[]>
+}
+
+export interface ClaimEvidenceRecord {
+  id: string
+  text: string
+  kind: NarrativeClaim["kind"]
+  importance: NarrativeClaim["importance"]
+  evidenceRequired: boolean
+  evidenceStatus: NarrativeClaim["evidenceStatus"]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
+  evidence: ClaimEvidenceBindingRecord[]
+}
+
+export interface ClaimEvidenceBindingRecord {
+  id: string
+  claimId: string
+  source: string
+  findingsFile?: string
+  sourcePath?: string
+  quote?: string
+  location?: string
+  url?: string
+  caveat?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength: NarrativeEvidenceBinding["strength"]
+}
+
+export interface SourceClaimIndexRecord {
+  sourceKey: string
+  source: string
+  findingsFile?: string
+  sourcePath?: string
+  url?: string
+  claims: Array<{
+    claimId: string
+    claimText: string
+    evidenceId: string
+    strength: NarrativeEvidenceBinding["strength"]
+    supportScope?: string
+    unsupportedScope?: string
+    caveat?: string
+  }>
+}
+
+export interface ObjectionRiskClaimIndex {
+  objections: Array<{
+    id: string
+    text: string
+    claimId?: string
+    claimText?: string
+    priority: "high" | "medium" | "low"
+    response?: string
+  }>
+  risks: Array<{
+    id: string
+    text: string
+    claimId?: string
+    claimText?: string
+    severity: "high" | "medium" | "low"
+    mitigation?: string
+  }>
+}
+
+export interface ArtifactClaimRef {
+  artifactId: string
+  type: RenderTarget["type"]
+  outputPath?: string
+  contractStatus?: RenderTarget["contractStatus"]
+  sourceNodeIds: string[]
+  claimIds: string[]
+  narrativeIds: string[]
+  slideRefs: ClaimSlideRef[]
+  coverageStatus: "current" | "stale" | "partial" | "missing"
+  affectedClaimIds: string[]
+  missingClaimIds: string[]
+  staleReasons: string[]
+  stale: boolean
+  staleReason?: string
+  note?: string
+}
+
+export interface ClaimSlideRef {
+  claimId: string
+  claimText: string
+  slideIndex: number
+  slideTitle: string
+  match: "content" | "evidence" | "metadata"
+  role: SlideClaimRefRole
+  location: string
+}
+
+export function getClaimEvidenceBoard(state: DecksState): ClaimEvidenceBoard {
+  const narrative = canonicalNarrative(state)
+  const evidenceByClaim = groupEvidenceByClaim(narrative.evidenceBindings)
+  const claims: ClaimEvidenceBoard["claims"] = {
+    supported: [],
+    partial: [],
+    weak: [],
+    missing: [],
+    not_required: [],
+  }
+
+  for (const claim of narrative.claims) {
+    claims[claim.evidenceStatus].push({
+      id: claim.id,
+      text: claim.text,
+      kind: claim.kind,
+      importance: claim.importance,
+      evidenceRequired: claim.evidenceRequired,
+      evidenceStatus: claim.evidenceStatus,
+      supportedScope: claim.supportedScope,
+      unsupportedScope: claim.unsupportedScope,
+      caveats: claim.caveats ?? [],
+      evidence: evidenceByClaim.get(claim.id) ?? [],
+    })
+  }
+
+  for (const group of Object.values(claims)) group.sort((a, b) => claimSortValue(a) - claimSortValue(b) || a.text.localeCompare(b.text))
+  return { version: 1, claims }
+}
+
+export function getSourceClaimIndex(state: DecksState): SourceClaimIndexRecord[] {
+  const narrative = canonicalNarrative(state)
+  const claimTextById = new Map(narrative.claims.map((claim) => [claim.id, claim.text]))
+  const grouped = new Map<string, SourceClaimIndexRecord>()
+
+  for (const binding of narrative.evidenceBindings) {
+    const sourceKey = binding.findingsFile || binding.sourcePath || binding.url || binding.source
+    if (!sourceKey) continue
+    const existing = grouped.get(sourceKey) ?? {
+      sourceKey,
+      source: binding.source,
+      findingsFile: binding.findingsFile,
+      sourcePath: binding.sourcePath,
+      url: binding.url,
+      claims: [],
+    }
+    existing.claims.push({
+      claimId: binding.claimId,
+      claimText: claimTextById.get(binding.claimId) ?? binding.claimId,
+      evidenceId: binding.id,
+      strength: binding.strength,
+      supportScope: binding.supportScope,
+      unsupportedScope: binding.unsupportedScope,
+      caveat: binding.caveat,
+    })
+    grouped.set(sourceKey, existing)
+  }
+
+  return [...grouped.values()]
+    .map((item) => ({ ...item, claims: item.claims.sort((a, b) => a.claimText.localeCompare(b.claimText)) }))
+    .sort((a, b) => a.sourceKey.localeCompare(b.sourceKey))
+}
+
+export function getObjectionRiskClaimIndex(state: DecksState): ObjectionRiskClaimIndex {
+  const narrative = canonicalNarrative(state)
+  const claimTextById = new Map(narrative.claims.map((claim) => [claim.id, claim.text]))
+  return {
+    objections: narrative.objections.map((objection) => ({
+      id: objection.id,
+      text: objection.text,
+      claimId: objection.claimId,
+      claimText: objection.claimId ? claimTextById.get(objection.claimId) : undefined,
+      priority: objection.priority,
+      response: objection.response,
+    })),
+    risks: narrative.risks.map((risk) => ({
+      id: risk.id,
+      text: risk.text,
+      claimId: risk.claimId,
+      claimText: risk.claimId ? claimTextById.get(risk.claimId) : undefined,
+      severity: risk.severity,
+      mitigation: risk.mitigation,
+    })),
+  }
+}
+
+export function getArtifactClaimRefs(state: DecksState): ArtifactClaimRef[] {
+  const narrative = canonicalNarrative(state)
+  const narrativeHash = computeNarrativeHash(narrative)
+  const deck = maybeActiveDeck(state)
+  const slideRefs = deck ? getClaimSlideRefs({ ...state, narrative }, deck) : []
+  const slideClaimIds = [...new Set(slideRefs.map((ref) => ref.claimId))].sort()
+  const rendersFromByArtifact = deck ? rendersFromIndex(projectWorkspaceGraph({ ...state, narrative }).edges) : new Map<string, string[]>()
+  const claimIds = new Set(narrative.claims.map((claim) => claim.id))
+  const requiredClaimIds = narrative.claims
+    .filter((claim) => claim.importance === "central" || claim.evidenceRequired)
+    .map((claim) => claim.id)
+  const narrativeIds = new Set([narrative.id])
+  const htmlCoverageByPath = new Map<string, ClaimSlideRef[]>()
+
+  return (state.renderTargets ?? [])
+    .map((target) => {
+      const artifactId = artifactNodeIdForRenderTarget(target)
+      const rendersFrom = rendersFromByArtifact.get(artifactId) ?? []
+      const targetSlideRefs = claimSlideRefsForTarget(target, slideRefs, htmlCoverageByPath)
+      const artifactClaimIds = [...new Set([...target.sourceNodeIds, ...rendersFrom, ...targetSlideRefs.map((ref) => ref.claimId), ...slideClaimIds].filter((id) => claimIds.has(id)))].sort()
+      const artifactNarrativeIds = [...new Set([...target.sourceNodeIds, ...rendersFrom].filter((id) => narrativeIds.has(id)))].sort()
+      const missingClaimIds = requiredClaimIds.filter((id) => !artifactClaimIds.includes(id)).sort()
+      const coverage = coverageState(target, narrativeHash, artifactClaimIds, missingClaimIds, artifactNarrativeIds)
+      if (target.type === "html_deck" && target.outputPath) htmlCoverageByPath.set(target.outputPath, targetSlideRefs)
+      return {
+        artifactId,
+        type: target.type,
+        outputPath: target.outputPath,
+        contractStatus: target.contractStatus,
+        sourceNodeIds: target.sourceNodeIds ?? [],
+        claimIds: artifactClaimIds,
+        narrativeIds: artifactNarrativeIds,
+        slideRefs: targetSlideRefs,
+        coverageStatus: coverage.status,
+        affectedClaimIds: coverage.affectedClaimIds,
+        missingClaimIds,
+        staleReasons: coverage.reasons,
+        stale: coverage.status === "stale",
+        staleReason: coverage.reasons[0],
+        note: coverage.note,
+      }
+    })
+    .sort((a, b) => artifactSortValue(a.type) - artifactSortValue(b.type) || (a.outputPath ?? a.artifactId).localeCompare(b.outputPath ?? b.artifactId))
+}
+
+export function getClaimSlideRefs(state: DecksState, deck: DeckSpec = activeDeck(state)): ClaimSlideRef[] {
+  const narrative = canonicalNarrative(state)
+  const bindingsByClaim = groupRawEvidenceByClaim(narrative.evidenceBindings)
+  const refs: ClaimSlideRef[] = []
+  const seen = new Set<string>()
+  for (const claim of narrative.claims) {
+    for (const slide of deck.slides ?? []) {
+      const explicitRef = slide.claimRefs?.find((ref) => ref.claimId === claim.id)
+      if (explicitRef) {
+        pushSlideRef(refs, seen, claim, slide, "metadata", `claimRefs:${explicitRef.role}`, explicitRef.role)
+        continue
+      }
+      if (slide.claimIds?.includes(claim.id)) {
+        pushSlideRef(refs, seen, claim, slide, "metadata", "claimIds", "primary")
+        continue
+      }
+      if (slideEvidenceBindingIdsMatch(slide.evidenceBindingIds ?? [], bindingsByClaim.get(claim.id) ?? [])) {
+        pushSlideRef(refs, seen, claim, slide, "metadata", "evidenceBindingIds", "evidence")
+        continue
+      }
+      const contentMatch = slideContentMatch(slide, claim.text)
+      if (contentMatch) pushSlideRef(refs, seen, claim, slide, "content", contentMatch, "primary")
+      else if (slideEvidenceMatches(slide.evidence ?? [], bindingsByClaim.get(claim.id) ?? [])) pushSlideRef(refs, seen, claim, slide, "evidence", "evidence", "evidence")
+    }
+  }
+  return refs.sort((a, b) => a.slideIndex - b.slideIndex || a.claimText.localeCompare(b.claimText) || a.location.localeCompare(b.location))
+}
+
+function canonicalNarrative(state: DecksState): NarrativeStateV1 {
+  return state.narrative ?? normalizeNarrativeState(state)
+}
+
+function activeDeck(state: DecksState): DeckSpec {
+  const key = state.activeDeck || (Object.keys(state.decks).length === 1 ? Object.keys(state.decks)[0] : undefined)
+  if (!key || !state.decks[key]) throw new Error("No active deck is available for narrative artifact coverage.")
+  return state.decks[key]
+}
+
+function maybeActiveDeck(state: DecksState): DeckSpec | undefined {
+  const key = state.activeDeck || (Object.keys(state.decks).length === 1 ? Object.keys(state.decks)[0] : undefined)
+  return key ? state.decks[key] : undefined
+}
+
+function groupEvidenceByClaim(bindings: NarrativeEvidenceBinding[]): Map<string, ClaimEvidenceBindingRecord[]> {
+  const grouped = new Map<string, ClaimEvidenceBindingRecord[]>()
+  for (const binding of bindings) {
+    grouped.set(binding.claimId, [...(grouped.get(binding.claimId) ?? []), {
+      id: binding.id,
+      claimId: binding.claimId,
+      source: binding.source,
+      findingsFile: binding.findingsFile,
+      sourcePath: binding.sourcePath,
+      quote: binding.quote,
+      location: binding.location,
+      url: binding.url,
+      caveat: binding.caveat,
+      supportScope: binding.supportScope,
+      unsupportedScope: binding.unsupportedScope,
+      strength: binding.strength,
+    }])
+  }
+  return grouped
+}
+
+function groupRawEvidenceByClaim(bindings: NarrativeEvidenceBinding[]): Map<string, NarrativeEvidenceBinding[]> {
+  const grouped = new Map<string, NarrativeEvidenceBinding[]>()
+  for (const binding of bindings) grouped.set(binding.claimId, [...(grouped.get(binding.claimId) ?? []), binding])
+  return grouped
+}
+
+function slideContentMatch(slide: SlideSpec, claimText: string): string | undefined {
+  const claim = normalizeText(claimText)
+  if (!claim) return undefined
+  const candidates: Array<[string, string | undefined]> = [
+    ["title", slide.title],
+    ["purpose", slide.purpose],
+    ["headline", slide.content?.headline],
+    ["speakerNotes", slide.content?.speakerNotes],
+    ...((slide.content?.body ?? []).map((item, index) => [`body:${index + 1}`, item] as [string, string])),
+    ...((slide.content?.bullets ?? []).map((item, index) => [`bullet:${index + 1}`, item] as [string, string])),
+  ]
+  for (const [location, value] of candidates) {
+    const normalized = normalizeText(value)
+    if (!normalized) continue
+    if (normalized === claim || normalized.includes(claim) || claim.includes(normalized)) return location
+  }
+  return undefined
+}
+
+function slideEvidenceMatches(evidence: EvidenceRef[], bindings: NarrativeEvidenceBinding[]): boolean {
+  return evidence.some((item) => bindings.some((binding) => evidenceMatchesBinding(item, binding)))
+}
+
+function slideEvidenceBindingIdsMatch(ids: string[], bindings: NarrativeEvidenceBinding[]): boolean {
+  const slideIds = new Set(ids)
+  return bindings.some((binding) => slideIds.has(binding.id))
+}
+
+function evidenceMatchesBinding(evidence: EvidenceRef, binding: NarrativeEvidenceBinding): boolean {
+  return Boolean(
+    evidence.findingsFile && evidence.findingsFile === binding.findingsFile ||
+      evidence.sourcePath && evidence.sourcePath === binding.sourcePath ||
+      evidence.url && evidence.url === binding.url ||
+      evidence.quote && binding.quote && normalizeText(evidence.quote) === normalizeText(binding.quote) ||
+      evidence.source && normalizeText(evidence.source) === normalizeText(binding.source),
+  )
+}
+
+function pushSlideRef(refs: ClaimSlideRef[], seen: Set<string>, claim: NarrativeClaim, slide: SlideSpec, match: ClaimSlideRef["match"], location: string, role: SlideClaimRefRole): void {
+  const key = `${claim.id}:${slide.index}:${match}:${location}:${role}`
+  if (seen.has(key)) return
+  seen.add(key)
+  refs.push({ claimId: claim.id, claimText: claim.text, slideIndex: slide.index, slideTitle: slide.title, match, role, location })
+}
+
+function claimSlideRefsForTarget(target: RenderTarget, currentHtmlRefs: ClaimSlideRef[], htmlCoverageByPath: Map<string, ClaimSlideRef[]>): ClaimSlideRef[] {
+  const stored = parseStoredClaimSlideRefs(target)
+  if (stored.length > 0) return stored
+  if (target.type === "html_deck") return currentHtmlRefs
+  const sourceOutputPath = typeof target.data?.sourceOutputPath === "string" ? target.data.sourceOutputPath : undefined
+  if (sourceOutputPath) return htmlCoverageByPath.get(sourceOutputPath) ?? currentHtmlRefs
+  return currentHtmlRefs
+}
+
+function parseStoredClaimSlideRefs(target: RenderTarget): ClaimSlideRef[] {
+  const value = target.data?.claimSlideRefs
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item): ClaimSlideRef[] => {
+    if (!item || typeof item !== "object") return []
+    const record = item as Partial<ClaimSlideRef>
+    if (!record.claimId || !record.claimText || typeof record.slideIndex !== "number" || !record.slideTitle) return []
+    return [{
+      claimId: record.claimId,
+      claimText: record.claimText,
+      slideIndex: record.slideIndex,
+      slideTitle: record.slideTitle,
+      match: record.match ?? "metadata",
+      role: record.role ?? "supporting",
+      location: record.location ?? "metadata",
+    }]
+  }).sort((a, b) => a.slideIndex - b.slideIndex || a.claimText.localeCompare(b.claimText))
+}
+
+function coverageState(
+  target: RenderTarget,
+  narrativeHash: string,
+  artifactClaimIds: string[],
+  missingClaimIds: string[],
+  artifactNarrativeIds: string[],
+): { status: ArtifactClaimRef["coverageStatus"]; reasons: string[]; affectedClaimIds: string[]; note?: string } {
+  const targetHash = typeof target.data?.narrativeHash === "string" ? target.data.narrativeHash : undefined
+  const reasons: string[] = []
+  if (targetHash && targetHash !== narrativeHash) reasons.push("Narrative hash changed after this artifact coverage was recorded.")
+  if (!targetHash) reasons.push("Artifact does not record the narrative hash used for coverage.")
+  if (artifactClaimIds.length === 0) reasons.push("No claim-to-slide coverage is recorded or inferred for this artifact.")
+  if (missingClaimIds.length > 0) reasons.push(`Artifact does not cover ${missingClaimIds.length} central or evidence-required claim${missingClaimIds.length === 1 ? "" : "s"}.`)
+  if (artifactNarrativeIds.length === 0 && target.type !== "pdf" && target.type !== "pptx") reasons.push("Artifact is not linked to the current canonical narrative.")
+
+  if (targetHash && targetHash !== narrativeHash) {
+    return {
+      status: "stale",
+      reasons,
+      affectedClaimIds: artifactClaimIds.length > 0 ? artifactClaimIds : missingClaimIds,
+      note: undefined,
+    }
+  }
+  if (artifactClaimIds.length === 0) return { status: "missing", reasons, affectedClaimIds: [], note: reasons[0] }
+  if (!targetHash || missingClaimIds.length > 0) return { status: "partial", reasons, affectedClaimIds: missingClaimIds, note: reasons[0] }
+  return { status: "current", reasons: [], affectedClaimIds: [], note: undefined }
+}
+
+function rendersFromIndex(edges: GraphEdge[]): Map<string, string[]> {
+  const grouped = new Map<string, string[]>()
+  for (const edge of edges) {
+    if (edge.type !== "renders_from" || !edge.from.startsWith("artifact:")) continue
+    grouped.set(edge.from, [...(grouped.get(edge.from) ?? []), edge.to])
+  }
+  return grouped
+}
+
+function claimSortValue(claim: Pick<ClaimEvidenceRecord, "importance">): number {
+  if (claim.importance === "central") return 0
+  if (claim.importance === "supporting") return 1
+  return 2
+}
+
+function artifactSortValue(type: RenderTarget["type"]): number {
+  if (type === "html_deck") return 0
+  if (type === "pdf") return 1
+  if (type === "pptx") return 2
+  if (type === "executive_brief" || type === "brief") return 3
+  return 3
+}
+
+function normalizeText(value: string | undefined): string {
+  return value?.replace(/\s+/g, " ").trim().toLowerCase() ?? ""
+}

package/lib/narrative-state/readiness.ts

@@ -150,6 +150,8 @@ function computeNarrativeReadiness(narrative: NarrativeStateV1, state: DecksStat
   const centralClaims = narrative.claims.filter((claim) => claim.importance === "central")
   if (isDecisionOriented(narrative) && centralClaims.length === 0) add(blocker("claim_chain_gap", "Decision-oriented narrative has no central claims.", "Add one to three central claims that the narrative must prove."))
   if (centralClaims.length > 4) add(warning("claim_chain_gap", "Narrative has many central claims.", "Tighten the claim chain to the few claims the audience must believe."))
+  if (needsClaimRelations(narrative)) add(warning("claim_chain_gap", "Narrative claim progression is not explicit.", "Add claimRelations so the narrative flow shows how claims lead to, support, constrain, or answer each other."))
+  for (const relationIssue of claimRelationIssues(narrative)) add(relationIssue)
 
   for (const claim of narrative.claims) {
     if (!claim.evidenceRequired) continue
@@ -191,7 +193,8 @@ function computeNarrativeReadiness(narrative: NarrativeStateV1, state: DecksStat
     const path = typeof action.outputs?.path === "string" ? action.outputs.path : undefined
     if (!path) continue
     const attached = Object.values(state.decks ?? {}).some((deck) => deck.researchPlan.some((axis) => axis.findingsFile === path))
-    if (!attached) add({
+    const boundToNarrative = narrative.evidenceBindings.some((binding) => binding.findingsFile === path)
+    if (!attached && !boundToNarrative && !isVisualOrMediaFindings(action.inputs?.axis, path)) add({
       type: "research_findings_unattached",
       severity: "warning",
       message: `Research findings are saved but not attached: ${path}`,
@@ -200,6 +203,20 @@ function computeNarrativeReadiness(narrative: NarrativeStateV1, state: DecksStat
     })
   }
 
+  for (const gap of narrative.researchGaps ?? []) {
+    if (gap.status === "closed" || gap.status === "evidence_bound") continue
+    add({
+      type: "research_gap_open",
+      severity: "warning",
+      message: `Research gap is ${gap.status}: ${gap.question}`,
+      suggestedAction: gap.status === "open" || gap.status === "in_progress"
+        ? "Save findings, attach them to the research plan, and bind evidence before closing the gap."
+        : "Bind specific evidence from the findings before treating the gap as resolved.",
+      claimId: gap.targetType === "claim" ? gap.targetId : undefined,
+      source: gap.findingsFile,
+    })
+  }
+
   const approval = approvalState(narrative, narrativeHash)
   if (!approval.current) add({
     type: approval.stale ? "approval_stale" : "approval_missing",
@@ -243,6 +260,11 @@ function approvalState(narrative: NarrativeStateV1, narrativeHash: string): Narr
   return { current: Boolean(latest && latest.narrativeHash === narrativeHash), stale: Boolean(latest && latest.narrativeHash !== narrativeHash), latest }
 }
 
+function isVisualOrMediaFindings(axis: unknown, path: string): boolean {
+  const value = `${typeof axis === "string" ? axis : ""} ${path}`.toLowerCase()
+  return /(^|[-_/\s])(image|images|media|asset|assets|visual|visuals|logo|logos|screenshot|screenshots)([-_/\s.]|$)/.test(value)
+}
+
 function nextActions(issues: NarrativeReadinessIssue[], approvalCurrent: boolean): string[] {
   const blockers = issues.filter((issue) => issue.severity === "blocker")
   if (blockers.length > 0) return unique(blockers.map((issue) => issue.suggestedAction))
@@ -259,6 +281,54 @@ function hasRecommendation(narrative: NarrativeStateV1): boolean {
   return narrative.claims.some((claim) => claim.kind === "recommendation" || claim.kind === "ask") || /recommend|approve|invest|prioriti[sz]e|建议|批准|投资|优先/i.test(narrative.decision.action)
 }
 
+function needsClaimRelations(narrative: NarrativeStateV1): boolean {
+  if (!isDecisionOriented(narrative)) return false
+  if ((narrative.claimRelations ?? []).length > 0) return false
+  const flowClaims = narrative.claims.filter((claim) => claim.importance === "central" || claim.kind === "recommendation" || claim.kind === "ask")
+  return flowClaims.length > 1
+}
+
+function claimRelationIssues(narrative: NarrativeStateV1): NarrativeReadinessIssue[] {
+  const issues: NarrativeReadinessIssue[] = []
+  const claimsById = new Map(narrative.claims.map((claim) => [claim.id, claim]))
+  for (const relation of narrative.claimRelations ?? []) {
+    const fromClaim = claimsById.get(relation.fromClaimId)
+    const toClaim = claimsById.get(relation.toClaimId)
+    if (!relation.rationale?.trim()) {
+      issues.push({
+        type: "claim_chain_gap",
+        severity: "warning",
+        message: "Claim relation lacks objective causal rationale.",
+        suggestedAction: "Add a factual causal bridge explaining what the source claim establishes and why the target claim follows within the evidence boundary.",
+        claimId: relation.toClaimId,
+        claimText: toClaim?.text,
+      })
+    }
+    if (relationMayOverextendEvidence(relation.relation) && fromClaim && toClaim && weakSourceForCausalBridge(fromClaim, toClaim)) {
+      issues.push({
+        type: "claim_chain_gap",
+        severity: "warning",
+        message: "Claim relation may overextend the source claim's evidence boundary.",
+        suggestedAction: "Narrow the target claim, add stronger evidence, or rewrite the relation rationale so it objectively reflects the supported scope.",
+        claimId: relation.toClaimId,
+        claimText: toClaim?.text,
+      })
+    }
+  }
+  return issues
+}
+
+function relationMayOverextendEvidence(relation: string): boolean {
+  return relation === "supports" || relation === "leads_to" || relation === "depends_on"
+}
+
+function weakSourceForCausalBridge(fromClaim: NarrativeClaim, toClaim: NarrativeClaim): boolean {
+  if (!fromClaim.evidenceRequired) return false
+  const targetNeedsObjectiveBridge = toClaim.importance === "central" || toClaim.kind === "recommendation" || toClaim.kind === "ask"
+  if (!targetNeedsObjectiveBridge) return false
+  return fromClaim.evidenceStatus === "missing" || fromClaim.evidenceStatus === "weak" || fromClaim.evidenceStatus === "partial" || Boolean(fromClaim.unsupportedScope)
+}
+
 function hasRiskHandling(narrative: NarrativeStateV1): boolean {
   return narrative.risks.length > 0 || narrative.claims.some((claim) => claim.kind === "risk" || claim.kind === "assumption" || claim.caveats?.length || claim.unsupportedScope) || narrative.evidenceBindings.some((binding) => binding.caveat || binding.unsupportedScope)
 }