@cyber-dash-tech/revela 0.10.0 → 0.12.0

package/lib/narrative-state/normalize.ts

@@ -0,0 +1,307 @@
+import type { DeckSpec, DecksState, EvidenceRef, SlideSpec } from "../decks-state"
+import {
+  stableClaimId,
+  stableEvidenceId,
+  stableNarrativeId,
+  stableObjectionId,
+  stableRiskId,
+} from "./hash"
+import type {
+  AudienceIntent,
+  DecisionIntent,
+  NarrativeClaim,
+  NarrativeClaimKind,
+  NarrativeEvidenceBinding,
+  NarrativeEvidenceStatus,
+  NarrativeObjection,
+  NarrativeRisk,
+  NarrativeStateV1,
+  NarrativeStatus,
+  NarrativeThesis,
+} from "./types"
+
+const MIGRATED_UPDATED_AT = "1970-01-01T00:00:00.000Z"
+
+export function normalizeCanonicalNarrativeState(input: Partial<NarrativeStateV1> | undefined, seed = "workspace"): NarrativeStateV1 | undefined {
+  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 evidenceBindings = dedupeById((input.evidenceBindings ?? []).map((binding) => normalizeEvidenceBinding(binding, claims)).filter((binding): binding is NarrativeEvidenceBinding => Boolean(binding)))
+  return {
+    version: 1,
+    id,
+    status: normalizeStatus(input.status),
+    audience: normalizeAudience(input.audience),
+    decision: normalizeDecision(input.decision),
+    thesis: normalizeThesis(input.thesis),
+    claims: claims.map((claim) => ({ ...claim, evidenceStatus: evidenceStatusForClaim(claim, evidenceBindings) })),
+    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))),
+    approvals: input.approvals ?? [],
+    updatedAt: input.updatedAt || MIGRATED_UPDATED_AT,
+  }
+}
+
+export function normalizeNarrativeState(state: DecksState): NarrativeStateV1 {
+  const deck = activeDeck(state)
+  const existing = normalizeCanonicalNarrativeState(state.narrative, deck?.slug ?? state.activeDeck ?? "workspace")
+  if (existing && hasCanonicalNarrativeContent(existing)) return existing
+  return migrateDeckNarrative(deck, state.activeDeck ?? "workspace")
+}
+
+function migrateDeckNarrative(deck: DeckSpec | undefined, seed: string): NarrativeStateV1 {
+  const brief = deck?.narrativeBrief
+  const id = stableNarrativeId(deck?.slug || seed)
+  const claims = migrateClaims(deck)
+  const evidenceBindings = migrateEvidenceBindings(deck, claims)
+  const withEvidenceStatus = claims.map((claim) => ({ ...claim, evidenceStatus: evidenceStatusForClaim(claim, evidenceBindings) }))
+  return {
+    version: 1,
+    id,
+    status: "draft",
+    audience: {
+      primary: clean(deck?.audience),
+      beliefBefore: clean(brief?.audienceBeliefBefore),
+      beliefAfter: clean(brief?.audienceBeliefAfter),
+    },
+    decision: {
+      action: clean(brief?.decisionOrAction),
+      decisionType: inferDecisionType(brief?.decisionOrAction),
+    },
+    thesis: migrateThesis(deck),
+    claims: withEvidenceStatus,
+    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 })),
+    approvals: [],
+    updatedAt: MIGRATED_UPDATED_AT,
+  }
+}
+
+function migrateClaims(deck: DeckSpec | undefined): NarrativeClaim[] {
+  const claims: NarrativeClaim[] = []
+  for (const text of deck?.narrativeBrief?.keyClaims ?? []) {
+    pushClaim(claims, {
+      id: stableClaimId(text),
+      kind: "recommendation",
+      text,
+      importance: "central",
+      evidenceRequired: true,
+      evidenceStatus: "missing",
+    })
+  }
+
+  for (const slide of deck?.slides ?? []) {
+    for (const item of slideClaimTexts(slide)) {
+      pushClaim(claims, {
+        id: stableClaimId(item.text),
+        kind: claimKindFromSlide(slide),
+        text: item.text,
+        importance: item.origin === "title" || item.origin === "purpose" ? "background" : "supporting",
+        evidenceRequired: isEvidenceRequiredText(item.text, slide),
+        evidenceStatus: "missing",
+      })
+    }
+  }
+  return claims
+}
+
+function migrateEvidenceBindings(deck: DeckSpec | undefined, claims: NarrativeClaim[]): NarrativeEvidenceBinding[] {
+  const bindings: NarrativeEvidenceBinding[] = []
+  for (const slide of deck?.slides ?? []) {
+    const slideClaims = slideClaimTexts(slide)
+      .map((item) => claims.find((claim) => claim.text === item.text))
+      .filter((claim): claim is NarrativeClaim => Boolean(claim))
+    const targetClaims = slideClaims.length > 0 ? slideClaims : claims.filter((claim) => claim.importance === "central")
+    for (const evidence of slide.evidence ?? []) {
+      for (const claim of targetClaims) {
+        const binding = evidenceToBinding(evidence, claim.id)
+        if (binding) pushBinding(bindings, binding)
+      }
+    }
+  }
+  return bindings
+}
+
+function evidenceToBinding(evidence: EvidenceRef, claimId: string): NarrativeEvidenceBinding | undefined {
+  const source = clean(evidence.source || evidence.sourcePath || evidence.findingsFile || evidence.url)
+  if (!source) return undefined
+  const seed = [source, evidence.sourcePath, evidence.findingsFile, evidence.quote, evidence.location, evidence.page, evidence.url, evidence.caveat].filter(Boolean).join("|")
+  return {
+    id: stableEvidenceId(claimId, seed),
+    claimId,
+    source,
+    sourcePath: clean(evidence.sourcePath),
+    findingsFile: clean(evidence.findingsFile),
+    quote: clean(evidence.quote),
+    location: clean(evidence.location || evidence.page),
+    url: clean(evidence.url),
+    caveat: clean(evidence.caveat),
+    strength: evidence.quote || evidence.location || evidence.page || evidence.url || evidence.findingsFile || evidence.sourcePath ? "partial" : "weak",
+  }
+}
+
+function slideClaimTexts(slide: SlideSpec): Array<{ origin: string; text: string }> {
+  return [
+    { origin: "title", text: clean(slide.title) },
+    { origin: "purpose", text: clean(slide.purpose) },
+    { origin: "headline", text: clean(slide.content?.headline) },
+    ...(slide.content?.body ?? []).map((text) => ({ origin: "body", text: clean(text) })),
+    ...(slide.content?.bullets ?? []).map((text) => ({ origin: "bullet", text: clean(text) })),
+  ].filter((item) => item.text.length > 0)
+}
+
+function migrateThesis(deck: DeckSpec | undefined): NarrativeThesis | undefined {
+  const statement = clean(deck?.narrativeBrief?.narrativeArc) || clean(deck?.goal)
+  if (!statement) return undefined
+  return { id: `thesis:${stableClaimId(statement).replace(/^claim:/, "")}`, statement, confidence: "medium" }
+}
+
+function normalizeAudience(input: Partial<AudienceIntent> | undefined): AudienceIntent {
+  return {
+    primary: clean(input?.primary),
+    secondary: (input?.secondary ?? []).map(clean).filter(Boolean),
+    beliefBefore: clean(input?.beliefBefore),
+    beliefAfter: clean(input?.beliefAfter),
+    decisionContext: clean(input?.decisionContext),
+    successCriteria: (input?.successCriteria ?? []).map(clean).filter(Boolean),
+  }
+}
+
+function normalizeDecision(input: Partial<DecisionIntent> | undefined): DecisionIntent {
+  return {
+    action: clean(input?.action),
+    owner: clean(input?.owner),
+    deadline: clean(input?.deadline),
+    decisionType: input?.decisionType,
+    consequenceOfNoDecision: clean(input?.consequenceOfNoDecision),
+  }
+}
+
+function normalizeThesis(input: Partial<NarrativeThesis> | undefined): NarrativeThesis | undefined {
+  const statement = clean(input?.statement)
+  if (!statement) return undefined
+  return {
+    id: input?.id?.trim() || `thesis:${stableClaimId(statement).replace(/^claim:/, "")}`,
+    statement,
+    confidence: input?.confidence ?? "medium",
+    caveat: clean(input?.caveat),
+  }
+}
+
+function normalizeClaim(input: Partial<NarrativeClaim>): NarrativeClaim | undefined {
+  const text = clean(input.text)
+  if (!text) return undefined
+  return {
+    id: input.id?.trim() || stableClaimId(text),
+    kind: input.kind ?? "evidence",
+    text,
+    importance: input.importance ?? "supporting",
+    evidenceRequired: input.evidenceRequired ?? true,
+    evidenceStatus: input.evidenceStatus ?? "missing",
+    supportedScope: clean(input.supportedScope),
+    unsupportedScope: clean(input.unsupportedScope),
+    caveats: (input.caveats ?? []).map(clean).filter(Boolean),
+  }
+}
+
+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)
+  if (!source || !claimId || !claims.some((claim) => claim.id === claimId)) return undefined
+  const seed = [source, input.sourcePath, input.findingsFile, input.quote, input.location, input.url, input.caveat].filter(Boolean).join("|")
+  return {
+    id: input.id?.trim() || stableEvidenceId(claimId, seed),
+    claimId,
+    source,
+    sourcePath: clean(input.sourcePath),
+    findingsFile: clean(input.findingsFile),
+    quote: clean(input.quote),
+    location: clean(input.location),
+    url: clean(input.url),
+    caveat: clean(input.caveat),
+    supportScope: clean(input.supportScope),
+    unsupportedScope: clean(input.unsupportedScope),
+    strength: input.strength ?? "weak",
+  }
+}
+
+function normalizeObjection(input: Partial<NarrativeObjection>): NarrativeObjection | undefined {
+  const text = clean(input.text)
+  if (!text) return undefined
+  return { id: input.id?.trim() || stableObjectionId(text), text, claimId: clean(input.claimId), priority: input.priority ?? "medium", response: clean(input.response) }
+}
+
+function normalizeRisk(input: Partial<NarrativeRisk>): NarrativeRisk | undefined {
+  const text = clean(input.text)
+  if (!text) return undefined
+  return { id: input.id?.trim() || stableRiskId(text), text, claimId: clean(input.claimId), severity: input.severity ?? "medium", mitigation: clean(input.mitigation) }
+}
+
+function evidenceStatusForClaim(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): NarrativeEvidenceStatus {
+  if (!claim.evidenceRequired) return "not_required"
+  const claimBindings = bindings.filter((binding) => binding.claimId === claim.id)
+  if (claimBindings.some((binding) => binding.strength === "strong")) return "supported"
+  if (claimBindings.some((binding) => binding.strength === "partial")) return "partial"
+  if (claimBindings.some((binding) => binding.strength === "weak")) return "weak"
+  return "missing"
+}
+
+function claimKindFromSlide(slide: SlideSpec): NarrativeClaimKind {
+  if (slide.narrativeRole === "recommendation") return "recommendation"
+  if (slide.narrativeRole === "risk") return "risk"
+  if (slide.narrativeRole === "ask") return "ask"
+  if (slide.narrativeRole === "tension") return "problem"
+  if (slide.narrativeRole === "context") return "context"
+  return "evidence"
+}
+
+function isEvidenceRequiredText(text: string, slide: SlideSpec): boolean {
+  if (slide.narrativeRole === "ask" || slide.narrativeRole === "close" || slide.narrativeRole === "appendix") return false
+  return /\d|%|\$|market|growth|cagr|tam|risk|recommend|approve|should|must|increase|decrease|增长|市场|风险|建议|投资|批准/i.test(text)
+}
+
+function inferDecisionType(action: string | undefined): DecisionIntent["decisionType"] {
+  const text = clean(action).toLowerCase()
+  if (!text) return undefined
+  if (/approve|批准/.test(text)) return "approve"
+  if (/invest|投资/.test(text)) return "invest"
+  if (/prioriti[sz]e|优先/.test(text)) return "prioritize"
+  if (/align|共识/.test(text)) return "align"
+  if (/choose|select|选择/.test(text)) return "choose"
+  if (/understand|理解/.test(text)) return "understand"
+  return "other"
+}
+
+function normalizeStatus(status: NarrativeStatus | undefined): NarrativeStatus {
+  return status ?? "draft"
+}
+
+function activeDeck(state: DecksState): DeckSpec | undefined {
+  if (state.activeDeck && state.decks[state.activeDeck]) return state.decks[state.activeDeck]
+  const keys = Object.keys(state.decks ?? {})
+  return keys.length === 1 ? state.decks[keys[0]] : undefined
+}
+
+function hasCanonicalNarrativeContent(narrative: NarrativeStateV1): boolean {
+  return Boolean(narrative.audience.primary || narrative.audience.beliefBefore || narrative.audience.beliefAfter || narrative.decision.action || narrative.thesis || narrative.claims.length > 0)
+}
+
+function pushClaim(claims: NarrativeClaim[], claim: NarrativeClaim): void {
+  if (claims.some((item) => item.text === claim.text)) return
+  claims.push(claim)
+}
+
+function pushBinding(bindings: NarrativeEvidenceBinding[], binding: NarrativeEvidenceBinding): void {
+  if (bindings.some((item) => item.id === binding.id)) return
+  bindings.push(binding)
+}
+
+function dedupeById<T extends { id: string }>(items: T[]): T[] {
+  return [...new Map(items.map((item) => [item.id, item])).values()]
+}
+
+function clean(value: string | undefined): string {
+  return value?.trim() ?? ""
+}

package/lib/narrative-state/project-compat.ts

@@ -0,0 +1,14 @@
+import type { NarrativeBrief } from "../decks-state"
+import type { NarrativeStateV1 } from "./types"
+
+export function narrativeToBrief(narrative: NarrativeStateV1): NarrativeBrief {
+  return {
+    audienceBeliefBefore: narrative.audience.beliefBefore || undefined,
+    audienceBeliefAfter: narrative.audience.beliefAfter || undefined,
+    decisionOrAction: narrative.decision.action || undefined,
+    narrativeArc: narrative.thesis?.statement,
+    keyClaims: narrative.claims.filter((claim) => claim.importance === "central").map((claim) => claim.text),
+    objections: narrative.objections.map((objection) => objection.text),
+    risks: narrative.risks.map((risk) => risk.text),
+  }
+}

package/lib/narrative-state/readiness.ts

@@ -0,0 +1,289 @@
+import type { DecksState } from "../decks-state"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+import { computeNarrativeHash, stableHash } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import type {
+  NarrativeApproval,
+  NarrativeClaim,
+  NarrativeReadinessIssue,
+  NarrativeReadinessResult,
+  NarrativeReadinessStatus,
+  NarrativeStateV1,
+} from "./types"
+
+interface NarrativeApprovalState {
+  current: boolean
+  stale: boolean
+  latest?: NarrativeApproval
+}
+
+export interface ReviewNarrativeOptions {
+  now?: string
+}
+
+export interface ApproveNarrativeOptions {
+  now?: string
+  approvedBy?: "user" | "override"
+  scope?: "narrative" | "render_override"
+  note?: string
+}
+
+export interface ApproveNarrativeResult {
+  approved: boolean
+  skipped: boolean
+  reason?: string
+  narrativeHash: string
+  approval?: NarrativeApproval
+  readiness: NarrativeReadinessResult
+}
+
+export function reviewNarrativeState(state: DecksState, options: ReviewNarrativeOptions = {}): { state: DecksState; result: NarrativeReadinessResult } {
+  const next: DecksState = { ...state, narrative: normalizeNarrativeState(state) }
+  const result = computeNarrativeReadiness(next.narrative!, next, options)
+  next.narrative = { ...next.narrative!, status: narrativeStatusFromReadiness(result.status), updatedAt: options.now ?? next.narrative!.updatedAt }
+  return { state: next, result }
+}
+
+export function approveNarrativeState(state: DecksState, options: ApproveNarrativeOptions = {}): { state: DecksState; result: ApproveNarrativeResult } {
+  const now = options.now ?? new Date().toISOString()
+  const reviewed = reviewNarrativeState(state, { now })
+  const narrative = reviewed.state.narrative!
+  const scope = options.scope ?? "narrative"
+  const approvedBy = options.approvedBy ?? "user"
+  const override = approvedBy === "override" || scope === "render_override"
+  const blocking = reviewed.result.issues.filter((issue) => issue.severity === "blocker")
+  const incomplete = blocking.some((issue) => issue.type !== "approval_missing" && issue.type !== "approval_stale")
+
+  if (incomplete && !override) {
+    return {
+      state: reviewed.state,
+      result: {
+        approved: false,
+        skipped: true,
+        reason: "narrative has unresolved readiness blockers; use an explicit override to record a render override",
+        narrativeHash: reviewed.result.narrativeHash,
+        readiness: reviewed.result,
+      },
+    }
+  }
+
+  const approval: NarrativeApproval = {
+    id: `approval:${stableHash(`${reviewed.result.narrativeHash}:${now}:${scope}:${approvedBy}`)}`,
+    narrativeHash: reviewed.result.narrativeHash,
+    approvedAt: now,
+    approvedBy,
+    scope,
+    note: clean(options.note),
+  }
+  const approvals = dedupeApprovals([...(narrative.approvals ?? []), approval])
+  const updatedNarrative: NarrativeStateV1 = {
+    ...narrative,
+    approvals,
+    status: scope === "narrative" && approvedBy === "user" ? "approved" : narrative.status,
+    updatedAt: now,
+  }
+  const next: DecksState = { ...reviewed.state, narrative: updatedNarrative }
+  const readiness = computeNarrativeReadiness(updatedNarrative, next, { now })
+  next.narrative = { ...updatedNarrative, status: narrativeStatusFromReadiness(readiness.status) }
+  return {
+    state: next,
+    result: {
+      approved: true,
+      skipped: false,
+      narrativeHash: reviewed.result.narrativeHash,
+      approval,
+      readiness,
+    },
+  }
+}
+
+export function recordNarrativeReviewAction(state: DecksState, result: NarrativeReadinessResult): void {
+  recordWorkspaceAction(state, {
+    type: "review.performed",
+    actor: "revela-decks",
+    inputs: { kind: "narrative", narrativeId: state.narrative?.id },
+    outputs: {
+      kind: "narrative",
+      status: result.status,
+      narrativeHash: result.narrativeHash,
+      blockerCount: result.blockers.length,
+      warningCount: result.warnings.length,
+      issueCount: result.issues.length,
+      approvalCurrent: result.approval?.current ?? false,
+      approvalStale: result.approval?.stale ?? false,
+    },
+    status: "success",
+    summary: `Reviewed narrative readiness: ${result.status}.`,
+    nodeIds: state.narrative ? [state.narrative.id] : [],
+  })
+}
+
+export function recordNarrativeApprovalAction(state: DecksState, result: ApproveNarrativeResult): void {
+  recordWorkspaceAction(state, {
+    type: "narrative.approved",
+    actor: "revela-decks",
+    inputs: { narrativeId: state.narrative?.id, approvedBy: result.approval?.approvedBy, scope: result.approval?.scope },
+    outputs: {
+      approved: result.approved,
+      skipped: result.skipped,
+      reason: result.reason,
+      narrativeHash: result.narrativeHash,
+      approvalId: result.approval?.id,
+    },
+    status: result.skipped ? "skipped" : "success",
+    summary: result.skipped ? `Skipped narrative approval: ${result.reason ?? "not approved"}.` : `Recorded narrative ${result.approval?.scope ?? "narrative"} approval.`,
+    nodeIds: [state.narrative?.id, result.approval?.id].filter((item): item is string => Boolean(item)),
+  })
+}
+
+function computeNarrativeReadiness(narrative: NarrativeStateV1, state: DecksState, options: ReviewNarrativeOptions): NarrativeReadinessResult {
+  const now = options.now ?? new Date().toISOString()
+  const narrativeHash = computeNarrativeHash(narrative)
+  const issues: NarrativeReadinessIssue[] = []
+  const add = (issue: NarrativeReadinessIssue) => issues.push(issue)
+
+  if (!narrative.audience.primary) add(blocker("missing_audience", "Primary audience is missing.", "Define the primary audience before reviewing the narrative."))
+  if (!narrative.audience.beliefBefore || !narrative.audience.beliefAfter) add(blocker("missing_belief_shift", "Audience belief shift is incomplete.", "Add both beliefBefore and beliefAfter so the narrative has a persuasion target."))
+  if (!narrative.decision.action) add(blocker("missing_decision", "Decision or action is missing.", "Define the decision, approval, alignment, or action this narrative should drive."))
+  if (isDecisionOriented(narrative) && !narrative.thesis?.statement) add(blocker("missing_thesis", "Decision-oriented narrative has no thesis.", "Add a compact thesis that carries the recommendation and evidence boundary."))
+
+  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."))
+
+  for (const claim of narrative.claims) {
+    if (!claim.evidenceRequired) continue
+    if (claim.evidenceStatus === "missing" && claim.importance === "central") add(claimIssue("missing_evidence", "blocker", claim, "Central claim lacks evidence.", "Bind source-backed evidence or revise the claim scope before approval."))
+    else if (claim.evidenceStatus === "missing") add(claimIssue("missing_evidence", "warning", claim, "Supporting claim lacks evidence.", "Bind evidence or mark the claim as not evidence-required if it is purely framing."))
+    else if (claim.evidenceStatus === "weak" || claim.evidenceStatus === "partial") add(claimIssue("weak_evidence", "warning", claim, `Claim evidence is ${claim.evidenceStatus}.`, "Add stronger source trace, caveats, or narrow the claim to the supported scope."))
+    if (claim.unsupportedScope) add(claimIssue("unsupported_scope", "warning", claim, "Claim has unsupported scope.", "Keep unsupported scope visible or revise the claim before rendering."))
+  }
+
+  for (const binding of narrative.evidenceBindings) {
+    if (binding.unsupportedScope) {
+      const claim = narrative.claims.find((item) => item.id === binding.claimId)
+      add({
+        type: "unsupported_scope",
+        severity: "warning",
+        message: "Evidence binding records unsupported scope.",
+        suggestedAction: "Preserve the unsupported scope caveat or add separate evidence before expanding the claim.",
+        claimId: binding.claimId,
+        claimText: claim?.text,
+        source: binding.source,
+      })
+    }
+  }
+
+  if (hasRecommendation(narrative) && !hasRiskHandling(narrative)) add(blocker("missing_risk", "Recommendation narrative lacks risk, assumption, or caveat handling.", "Add a risk, assumption, caveat, or tradeoff before approval."))
+  for (const objection of narrative.objections) {
+    if (objection.priority === "high" && !objection.response) add({
+      type: "unhandled_objection",
+      severity: "blocker",
+      message: "High-priority objection has no response.",
+      suggestedAction: "Add a response, evidence boundary, or fallback framing for this objection.",
+      claimId: objection.claimId,
+      claimText: objection.text,
+    })
+  }
+
+  for (const action of state.actions ?? []) {
+    if (action.type !== "research.findings_saved") continue
+    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({
+      type: "research_findings_unattached",
+      severity: "warning",
+      message: `Research findings are saved but not attached: ${path}`,
+      suggestedAction: "Attach the findings to a research axis or bind specific evidence before treating them as canonical support.",
+      source: path,
+    })
+  }
+
+  const approval = approvalState(narrative, narrativeHash)
+  if (!approval.current) add({
+    type: approval.stale ? "approval_stale" : "approval_missing",
+    severity: "warning",
+    message: approval.stale ? "Latest narrative approval is stale." : "Narrative is not approved yet.",
+    suggestedAction: approval.stale ? "Review changes and approve the current narrative hash." : "Ask the user to approve the narrative before deck handoff.",
+  })
+
+  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 status = readinessStatus(issues, approval.current)
+  return {
+    status,
+    narrativeHash,
+    reviewedAt: now,
+    blockers,
+    warnings,
+    issues,
+    approval,
+    nextActions: nextActions(issues, approval.current),
+  }
+}
+
+function readinessStatus(issues: NarrativeReadinessIssue[], approvalCurrent: boolean): NarrativeReadinessStatus {
+  const blockers = issues.filter((issue) => issue.severity === "blocker")
+  if (blockers.some((issue) => issue.type === "missing_evidence" || issue.type === "unsupported_scope")) return "needs_research"
+  if (blockers.length > 0) return "blocked"
+  if (issues.some((issue) => issue.type === "missing_audience" || issue.type === "missing_belief_shift" || issue.type === "missing_decision" || issue.type === "missing_thesis" || issue.type === "claim_chain_gap")) return "needs_user_confirmation"
+  return approvalCurrent ? "approved" : "ready_for_approval"
+}
+
+function narrativeStatusFromReadiness(status: NarrativeReadinessStatus): NarrativeStateV1["status"] {
+  if (status === "blocked") return "needs_user_confirmation"
+  if (status === "needs_research") return "needs_research"
+  return status
+}
+
+function approvalState(narrative: NarrativeStateV1, narrativeHash: string): NarrativeApprovalState {
+  const narrativeApprovals = [...(narrative.approvals ?? [])].filter((approval) => approval.scope === "narrative" && approval.approvedBy === "user")
+  const latest = narrativeApprovals[narrativeApprovals.length - 1]
+  return { current: Boolean(latest && latest.narrativeHash === narrativeHash), stale: Boolean(latest && latest.narrativeHash !== narrativeHash), latest }
+}
+
+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))
+  const approvalIssue = issues.find((issue) => issue.type === "approval_missing" || issue.type === "approval_stale")
+  if (!approvalCurrent && approvalIssue) return [approvalIssue.suggestedAction]
+  return unique(issues.slice(0, 3).map((issue) => issue.suggestedAction))
+}
+
+function isDecisionOriented(narrative: NarrativeStateV1): boolean {
+  return Boolean(narrative.decision.action || narrative.decision.decisionType && narrative.decision.decisionType !== "understand" || narrative.claims.some((claim) => claim.kind === "recommendation" || claim.kind === "ask"))
+}
+
+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 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)
+}
+
+function blocker(type: NarrativeReadinessIssue["type"], message: string, suggestedAction: string): NarrativeReadinessIssue {
+  return { type, severity: "blocker", message, suggestedAction }
+}
+
+function warning(type: NarrativeReadinessIssue["type"], message: string, suggestedAction: string): NarrativeReadinessIssue {
+  return { type, severity: "warning", message, suggestedAction }
+}
+
+function claimIssue(type: NarrativeReadinessIssue["type"], severity: "blocker" | "warning", claim: NarrativeClaim, message: string, suggestedAction: string): NarrativeReadinessIssue {
+  return { type, severity, message, suggestedAction, claimId: claim.id, claimText: claim.text }
+}
+
+function dedupeApprovals(approvals: NarrativeApproval[]): NarrativeApproval[] {
+  return [...new Map(approvals.map((approval) => [approval.id, approval])).values()]
+}
+
+function unique(items: string[]): string[] {
+  return [...new Set(items.filter(Boolean))]
+}
+
+function clean(value: string | undefined): string | undefined {
+  const trimmed = value?.trim()
+  return trimmed || undefined
+}