@cyber-dash-tech/revela 0.16.3 → 0.17.0

package/lib/decks-state.ts

@@ -20,7 +20,8 @@ import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type Work
 import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
 import { computeNarrativeHash } from "./narrative-state/hash"
 import { getArtifactClaimRefs } from "./narrative-state/queries"
-import type { NarrativeStateV1 } from "./narrative-state/types"
+import type { NarrativeApproval, NarrativeStateV1 } from "./narrative-state/types"
+import { hasNarrativeVault, loadNarrativeFromPreferredSource } from "./narrative-vault"
 
 export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
 
@@ -34,6 +35,7 @@ export interface DecksState {
   version: 1
   activeDeck?: string
   narrative?: NarrativeStateV1
+  narrativeApprovals?: NarrativeApproval[]
   workspace: {
     brief?: string
     sourceMaterials: SourceMaterial[]
@@ -55,6 +57,7 @@ export interface SourceMaterial {
   type?: string
   size?: number
   fingerprint?: string
+  lastModified?: string
   status?: "discovered" | "extracted" | "summarized" | "researched"
   extraction?: {
     manifestPath?: string
@@ -483,15 +486,37 @@ export function confirmDeckPlan(state: DecksState, options: ConfirmDeckPlanOptio
 }
 
 export function readDecksState(workspaceRoot: string): DecksState {
-  return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
+  return applyPreferredNarrativeSource(workspaceRoot, readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative }))
 }
 
 export function writeDecksState(workspaceRoot: string, state: DecksState): void {
-  writeWorkspaceState(workspaceRoot, state, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
+  const vault = hasNarrativeVault(workspaceRoot)
+  writeWorkspaceState(workspaceRoot, prepareStateForWrite(workspaceRoot, state), { fileName: DECKS_STATE_FILE, normalize: vault ? normalizeDecksState : normalizeDecksStateWithNarrative })
 }
 
 export function readOrCreateDecksState(workspaceRoot: string): DecksState {
-  return readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
+  return applyPreferredNarrativeSource(workspaceRoot, readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative }))
+}
+
+function applyPreferredNarrativeSource(workspaceRoot: string, state: DecksState): DecksState {
+  const normalized = normalizeDecksStateWithNarrative(state)
+  const loaded = loadNarrativeFromPreferredSource(workspaceRoot, normalized.narrative, narrativeApprovalsForHydration(normalized))
+  if (loaded.source !== "vault" || !loaded.narrative) return normalized
+  return normalizeDecksStateWithNarrative({ ...normalized, narrative: loaded.narrative, narrativeApprovals: loaded.narrative.approvals })
+}
+
+function prepareStateForWrite(workspaceRoot: string, state: DecksState): DecksState {
+  const normalized = normalizeDecksStateWithNarrative(state)
+  if (!hasNarrativeVault(workspaceRoot)) return normalized
+  const loaded = loadNarrativeFromPreferredSource(workspaceRoot, normalized.narrative, narrativeApprovalsForHydration(normalized))
+  const narrativeApprovals = loaded.narrative?.approvals ?? narrativeApprovalsForHydration(normalized)
+  const prepared = normalizeDecksStateWithNarrative({ ...normalized, narrative: loaded.narrative ?? normalized.narrative, narrativeApprovals })
+  const { narrative: _narrative, ...withoutNarrative } = prepared
+  return withoutNarrative as DecksState
+}
+
+function narrativeApprovalsForHydration(state: DecksState): NarrativeApproval[] {
+  return state.narrativeApprovals ?? state.narrative?.approvals ?? []
 }
 
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
@@ -859,6 +884,7 @@ function normalizeDecksState(input: DecksState): DecksState {
     version: 1,
     activeDeck: input.activeDeck ? normalizeSlug(input.activeDeck) : undefined,
     narrative: normalizeCanonicalNarrativeState(input.narrative, input.activeDeck || "workspace"),
+    narrativeApprovals: normalizeNarrativeApprovals([...(input.narrativeApprovals ?? []), ...(input.narrative?.approvals ?? [])]),
     workspace: {
       brief: input.workspace?.brief,
       sourceMaterials: input.workspace?.sourceMaterials ?? [],
@@ -890,9 +916,17 @@ function normalizeDecksState(input: DecksState): DecksState {
 function normalizeDecksStateWithNarrative(input: DecksState): DecksState {
   const state = normalizeDecksState(input)
   if (!state.narrative && currentDeckKey(state)) state.narrative = normalizeNarrativeState(state)
+  if (state.narrative && state.narrativeApprovals && state.narrativeApprovals.length > 0) {
+    state.narrative = { ...state.narrative, approvals: normalizeNarrativeApprovals([...state.narrative.approvals, ...state.narrativeApprovals]) ?? [] }
+  }
   return state
 }
 
+function normalizeNarrativeApprovals(approvals: NarrativeApproval[]): NarrativeApproval[] | undefined {
+  const normalized = [...new Map(approvals.filter((approval) => approval?.id).map((approval) => [approval.id, approval])).values()]
+  return normalized.length > 0 ? normalized : undefined
+}
+
 function normalizeDeckPlanReview(input: DeckPlanReview | undefined): DeckPlanReview | undefined {
   if (!input || !input.narrativeHash || !input.planHash) return undefined
   return {

package/lib/edit/prompt.ts

@@ -75,7 +75,7 @@ Instructions:
 - Make the smallest targeted change that satisfies the user's comment.
 - If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
 - Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
-- Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through ${"`revela-decks`"} action ${"`upsertNarrative`"}, then reviewed/approved or explicitly overridden before updating the deck projection.
+- Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through targeted ${"`revela-decks`"} vault actions (${"`initNarrativeVault`"} if needed, then ${"`updateVaultCoreNarrative`"}, ${"`upsertVaultClaim`"}, ${"`upsertVaultEvidence`"}, ${"`upsertVaultObjection`"}, or ${"`upsertVaultRisk`"}), with manual Markdown edits plus ${"`compileNarrativeVault`"} only for unsupported node changes. Then the narrative must be reviewed/approved or explicitly overridden before updating the deck projection.
 - Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, runtime JavaScript fixes, or deck HTML contract fixes may remain an artifact-level edit.
 - If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.

package/lib/hook-notifications.ts

@@ -0,0 +1,53 @@
+import type { ArtifactQAReport } from "./qa/artifact"
+import type { AutoCompileNarrativeVaultResult } from "./narrative-vault/auto-compile"
+
+export function formatMarkdownQaUserNotice(result: AutoCompileNarrativeVaultResult): string | undefined {
+  if (result.ok) return undefined
+
+  const lines = ["**Markdown QA blocked**"]
+  lines.push(`Touched: ${result.touched.length > 0 ? result.touched.map((file) => `\`${file}\``).join(", ") : "unknown"}`)
+
+  const blockers = result.markdownQa?.blockers ?? []
+  if (blockers.length > 0) {
+    lines.push("Top repair(s):")
+    for (const card of blockers.slice(0, 3)) {
+      const location = [card.file, card.nodeId].filter(Boolean).join(" / ")
+      lines.push(`- \`${card.issueCode}\`${location ? ` (${location})` : ""}: ${card.smallestRepair}`)
+    }
+    if (blockers.length > 3) lines.push(`- ... ${blockers.length - 3} more`)
+  } else if (result.error) {
+    lines.push(`Hook error: ${result.error}`)
+  } else {
+    lines.push("Compile diagnostics are blocking the vault. See the tool output for details.")
+  }
+
+  return lines.join("\n")
+}
+
+export function formatArtifactQaUserNotice(report: ArtifactQAReport): string | undefined {
+  if (report.passed) return undefined
+
+  const lines = ["**Artifact QA failed**"]
+  lines.push(`File: \`${report.file}\``)
+  lines.push(`Hard errors: ${report.hardErrorCount}; warnings: ${report.warningCount}`)
+  if (report.sections.length > 0) {
+    lines.push("Top issue area(s):")
+    for (const section of report.sections.slice(0, 3)) lines.push(`- ${firstLine(section)}`)
+    if (report.sections.length > 3) lines.push(`- ... ${report.sections.length - 3} more`)
+  }
+  lines.push("Fix the reported artifact issues before treating the deck as ready.")
+  return lines.join("\n")
+}
+
+export function formatStateGateUserNotice(kind: "write" | "patch", reason: string): string {
+  return [
+    "**Revela state gate blocked a direct DECKS.json edit**",
+    `Operation: ${kind}`,
+    `Reason: ${reason}`,
+    "Use the `revela-decks` tool for controlled workspace state changes.",
+  ].join("\n")
+}
+
+function firstLine(text: string): string {
+  return text.split(/\r?\n/).map((line) => line.trim()).find(Boolean)?.replace(/^#+\s*/, "") ?? "See report details."
+}

package/lib/narrative-state/render-plan.ts

@@ -17,9 +17,18 @@ export interface CompileDeckPlanResult {
   narrativeHash: string
   slideCount: number
   slides: SlideSpec[]
+  chapters?: DeckPlanChapter[]
   qualityChecks?: DeckPlanQualityCheck[]
 }
 
+export interface DeckPlanChapter {
+  title: string
+  role: "context" | "tension" | "evidence" | "recommendation" | "risk" | "ask"
+  slideIndexes: number[]
+  claimIds: string[]
+  evidenceBindingIds: string[]
+}
+
 export interface DeckPlanQualityCheck {
   id: string
   status: "pass" | "warning" | "blocker"
@@ -47,8 +56,9 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
   const deckKey = state.activeDeck ?? Object.keys(state.decks)[0]
   const deck = deckKey ? state.decks[deckKey] : undefined
   const slug = deck?.slug ?? state.activeDeck ?? "deck"
-  const slides = buildSlides(narrative)
-  const qualityChecks = checkPlanQuality(narrative, slides)
+  const plan = buildDeckPlan(narrative)
+  const { slides, chapters } = plan
+  const qualityChecks = checkPlanQuality(narrative, slides, chapters)
   const planCoverage = deckPlanCoverage(narrative, slides)
   const requiredInputs: Partial<RequiredInputs> = {
     topicClarified: true,
@@ -91,8 +101,9 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
       ...(htmlTarget.data ?? {}),
       narrativeId: narrative.id,
       narrativeHash,
-      planQualityChecks: qualityChecks,
-      requiredClaimIds: planCoverage.requiredClaimIds,
+        planQualityChecks: qualityChecks,
+        planChapters: chapters,
+        requiredClaimIds: planCoverage.requiredClaimIds,
       coveredClaimIds: planCoverage.coveredClaimIds,
       missingClaimIds: planCoverage.missingClaimIds,
       claimSlideRefs: getClaimSlideRefs(next).map((ref) => ({
@@ -115,33 +126,45 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
         narrativeHash,
         slideCount: slides.length,
         slides,
+        chapters,
         qualityChecks,
       },
     }
 }
 
-function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
+function buildDeckPlan(narrative: NarrativeStateV1): { slides: SlideSpec[]; chapters: DeckPlanChapter[] } {
   const slides: SlideSpec[] = []
   const evidenceByClaim = evidenceBindingsByClaim(narrative.evidenceBindings)
   const centralClaims = orderedClaims(narrative, (claim) => claim.importance === "central")
   const supportingClaims = orderedClaims(narrative, (claim) => claim.importance !== "central")
-  const chapters = deriveChapters(narrative, centralClaims, supportingClaims)
+  const chapters = deriveChapters(narrative, centralClaims, supportingClaims).map((chapter) => ({ ...chapter }))
 
   slides.push(coverSlide(slides.length + 1, narrative))
+  assignSlideToChapter(chapters, "context", slides[slides.length - 1])
   slides.push(tocSlide(slides.length + 1, chapters))
 
   for (const claim of centralClaims) {
-    slides.push(claimSlide(slides.length + 1, claim, evidenceByClaim.get(claim.id) ?? []))
+    const slide = claimSlide(slides.length + 1, claim, evidenceByClaim.get(claim.id) ?? [])
+    slides.push(slide)
+    assignSlideToChapter(chapters, chapterRoleForClaim(claim), slide)
+  }
+  if (supportingClaims.length > 0) {
+    const slide = supportingLogicSlide(slides.length + 1, supportingClaims, evidenceByClaim)
+    slides.push(slide)
+    assignSlideToChapter(chapters, "evidence", slide)
   }
-  if (supportingClaims.length > 0) slides.push(supportingLogicSlide(slides.length + 1, supportingClaims, evidenceByClaim))
 
   if (narrative.risks.length > 0 || narrative.objections.length > 0) {
-    slides.push(riskObjectionSlide(slides.length + 1, narrative))
+    const slide = riskObjectionSlide(slides.length + 1, narrative, evidenceByClaim)
+    slides.push(slide)
+    assignSlideToChapter(chapters, "risk", slide)
   }
 
-  slides.push(decisionAskSlide(slides.length + 1, narrative))
+  const decisionSlide = decisionAskSlide(slides.length + 1, narrative)
+  slides.push(decisionSlide)
+  assignSlideToChapter(chapters, "ask", decisionSlide)
 
-  return slides
+  return { slides, chapters }
 }
 
 function coverSlide(index: number, narrative: NarrativeStateV1): SlideSpec {
@@ -166,7 +189,7 @@ function coverSlide(index: number, narrative: NarrativeStateV1): SlideSpec {
   }
 }
 
-function tocSlide(index: number, chapters: string[]): SlideSpec {
+function tocSlide(index: number, chapters: DeckPlanChapter[]): SlideSpec {
   return {
     index,
     title: "Storyline",
@@ -177,7 +200,8 @@ function tocSlide(index: number, chapters: string[]): SlideSpec {
     components: ["toc", "text-panel"],
     content: {
       headline: "How the decision story is organized",
-      bullets: chapters,
+      bullets: chapters.map((chapter) => chapter.title),
+      data: { chapters: chapters.map((chapter) => ({ title: chapter.title, role: chapter.role })) },
     },
     evidence: [],
     status: "planned",
@@ -220,19 +244,20 @@ function supportingLogicSlide(index: number, claims: NarrativeClaim[], evidenceB
     evidenceBindingIds: supportingBindings.map((binding) => binding.id),
     content: {
       headline: "Supporting claims and boundaries",
-      bullets: claims.slice(0, 5).flatMap((claim) => [claim.text, ...claimBoundaryBullets(claim)]).slice(0, 8),
+      bullets: claims.slice(0, 5).flatMap((claim) => [claim.text, ...claimBoundaryBullets(claim), evidenceGapBullet(claim, evidenceByClaim.get(claim.id) ?? [])]).filter((item): item is string => Boolean(item)).slice(0, 8),
     },
     evidence: supportingBindings.map(evidenceRefFromBinding),
     status: "planned",
   }
 }
 
-function riskObjectionSlide(index: number, narrative: NarrativeStateV1): SlideSpec {
+function riskObjectionSlide(index: number, narrative: NarrativeStateV1, evidenceByClaim: Map<string, NarrativeEvidenceBinding[]>): SlideSpec {
   const challengedClaimRefs = [
     ...narrative.risks.map((risk) => risk.claimId ? { claimId: risk.claimId, role: "risk" as const } : undefined).filter((ref): ref is { claimId: string; role: "risk" } => Boolean(ref)),
     ...narrative.objections.map((objection) => objection.claimId ? { claimId: objection.claimId, role: "objection" as const } : undefined).filter((ref): ref is { claimId: string; role: "objection" } => Boolean(ref)),
   ]
   const challengedClaimIds = [...new Set(challengedClaimRefs.map((ref) => ref.claimId))]
+  const challengedBindings = challengedClaimIds.flatMap((claimId) => evidenceByClaim.get(claimId) ?? [])
   return {
     index,
     title: "Risks And Objections",
@@ -243,6 +268,7 @@ function riskObjectionSlide(index: number, narrative: NarrativeStateV1): SlideSp
     components: ["box", "text-panel"],
     claimIds: challengedClaimIds,
     claimRefs: dedupeClaimRefs(challengedClaimRefs),
+    evidenceBindingIds: challengedBindings.map((binding) => binding.id),
     content: {
       headline: "What could break the recommendation",
       bullets: [
@@ -250,7 +276,7 @@ function riskObjectionSlide(index: number, narrative: NarrativeStateV1): SlideSp
         ...narrative.objections.slice(0, 3).map((objection) => objection.response ? `${objection.text} Response: ${objection.response}` : objection.text),
       ],
     },
-    evidence: [],
+    evidence: challengedBindings.map(evidenceRefFromBinding),
     status: "planned",
   }
 }
@@ -302,22 +328,51 @@ function orderedClaims(narrative: NarrativeStateV1, predicate: (claim: Narrative
     .sort((a, b) => (relationScore.get(b.id) ?? 0) - (relationScore.get(a.id) ?? 0) || (sourceOrder.get(a.id) ?? 0) - (sourceOrder.get(b.id) ?? 0))
 }
 
-function deriveChapters(narrative: NarrativeStateV1, centralClaims: NarrativeClaim[], supportingClaims: NarrativeClaim[]): string[] {
-  const chapters: string[] = []
-  addUnique(chapters, narrative.audience.decisionContext ? "Decision context" : "Context and belief shift")
-  if (hasClaimKind([...centralClaims, ...supportingClaims], ["problem", "opportunity"])) addUnique(chapters, "Tension and opportunity")
-  if (centralClaims.some((claim) => claim.kind === "evidence") || supportingClaims.some((claim) => claim.kind === "evidence")) addUnique(chapters, "Evidence and proof")
-  if (centralClaims.some((claim) => claim.kind === "recommendation" || claim.kind === "ask") || narrative.decision.action) addUnique(chapters, "Recommendation and decision")
-  if (narrative.risks.length > 0 || narrative.objections.length > 0 || centralClaims.some((claim) => claim.unsupportedScope || (claim.caveats ?? []).length > 0)) addUnique(chapters, "Risks and boundaries")
-  addUnique(chapters, "Decision ask")
-  if (chapters.length < 3) addUnique(chapters, "Evidence and proof")
-  return chapters.slice(0, 5)
+function deriveChapters(narrative: NarrativeStateV1, centralClaims: NarrativeClaim[], supportingClaims: NarrativeClaim[]): DeckPlanChapter[] {
+  const claims = [...centralClaims, ...supportingClaims]
+  const chapters: DeckPlanChapter[] = []
+  addChapter(chapters, narrative.audience.decisionContext ? "Decision context" : "Context and belief shift", "context")
+  if (hasClaimKind(claims, ["problem", "opportunity"])) addChapter(chapters, "Tension and opportunity", "tension")
+  if (claims.some((claim) => claim.kind === "evidence") || narrative.evidenceBindings.length > 0) addChapter(chapters, "Evidence and proof", "evidence")
+  if (claims.some((claim) => claim.kind === "recommendation" || claim.kind === "ask") || narrative.decision.action) addChapter(chapters, "Recommendation and decision", "recommendation")
+  if (narrative.risks.length > 0 || narrative.objections.length > 0 || centralClaims.some((claim) => claim.unsupportedScope || (claim.caveats ?? []).length > 0)) addChapter(chapters, "Risks and boundaries", "risk")
+  addChapter(chapters, "Decision ask", "ask")
+  if (chapters.length < 3) addChapter(chapters, "Evidence and proof", "evidence")
+  while (chapters.length > 5) {
+    const tensionIndex = chapters.findIndex((chapter) => chapter.role === "tension")
+    if (tensionIndex >= 0) chapters.splice(tensionIndex, 1)
+    else chapters.splice(Math.max(1, chapters.length - 2), 1)
+  }
+  return chapters
+}
+
+function addChapter(chapters: DeckPlanChapter[], title: string, role: DeckPlanChapter["role"]): void {
+  if (chapters.some((chapter) => chapter.role === role || chapter.title === title)) return
+  chapters.push({ title, role, slideIndexes: [], claimIds: [], evidenceBindingIds: [] })
+}
+
+function assignSlideToChapter(chapters: DeckPlanChapter[], role: DeckPlanChapter["role"], slide: SlideSpec): void {
+  const chapter = chapters.find((item) => item.role === role) ?? chapters.find((item) => item.role === "evidence") ?? chapters[chapters.length - 1]
+  if (!chapter) return
+  chapter.slideIndexes.push(slide.index)
+  for (const claimId of slide.claimIds ?? []) addUnique(chapter.claimIds, claimId)
+  for (const ref of slide.claimRefs ?? []) addUnique(chapter.claimIds, ref.claimId)
+  for (const bindingId of slide.evidenceBindingIds ?? []) addUnique(chapter.evidenceBindingIds, bindingId)
 }
 
 function addUnique(items: string[], item: string): void {
   if (!items.includes(item)) items.push(item)
 }
 
+function chapterRoleForClaim(claim: NarrativeClaim): DeckPlanChapter["role"] {
+  if (claim.kind === "problem" || claim.kind === "opportunity") return "tension"
+  if (claim.kind === "recommendation") return "recommendation"
+  if (claim.kind === "ask") return "ask"
+  if (claim.kind === "risk" || claim.kind === "assumption") return "risk"
+  if (claim.kind === "context") return "context"
+  return "evidence"
+}
+
 function hasClaimKind(claims: NarrativeClaim[], kinds: NarrativeClaim["kind"][]): boolean {
   return claims.some((claim) => kinds.includes(claim.kind))
 }
@@ -332,9 +387,15 @@ function claimBullets(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[
   return [
     ...claimBoundaryBullets(claim),
     ...bindings.slice(0, 2).map((binding) => binding.supportScope ? `Evidence supports: ${binding.supportScope}` : undefined),
+    evidenceGapBullet(claim, bindings),
   ].filter((item): item is string => Boolean(item))
 }
 
+function evidenceGapBullet(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): string | undefined {
+  if (!claim.evidenceRequired || bindings.length > 0) return undefined
+  return `Evidence gap: ${claim.evidenceStatus === "missing" ? "no binding yet" : "support remains incomplete"}.`
+}
+
 function claimBoundaryBullets(claim: NarrativeClaim): string[] {
   return [
     claim.supportedScope ? `Supported scope: ${claim.supportedScope}` : undefined,
@@ -370,13 +431,29 @@ function evidenceRefFromBinding(binding: NarrativeEvidenceBinding): EvidenceRef
   }
 }
 
-function checkPlanQuality(narrative: NarrativeStateV1, slides: SlideSpec[]): DeckPlanQualityCheck[] {
+function checkPlanQuality(narrative: NarrativeStateV1, slides: SlideSpec[], chapters: DeckPlanChapter[]): DeckPlanQualityCheck[] {
   const coverage = deckPlanCoverage(narrative, slides)
   const centralClaimIds = narrative.claims.filter((claim) => claim.importance === "central").map((claim) => claim.id)
   const missingCentralClaims = centralClaimIds.filter((claimId) => coverage.missingClaimIds.includes(claimId))
   const incompatibleComponents = [...new Set(slides.flatMap((slide) => slide.components).filter((component) => component === "card"))]
+  const toc = slides.find((slide) => slide.components.includes("toc"))
+  const tocBullets = toc?.content.bullets ?? []
+  const chapterTitles = chapters.map((chapter) => chapter.title)
+  const evidenceRequiredWithoutBindings = narrative.claims.filter((claim) => claim.evidenceRequired && !narrative.evidenceBindings.some((binding) => binding.claimId === claim.id))
+  const invisibleEvidenceGaps = evidenceRequiredWithoutBindings.filter((claim) => coverage.missingClaimIds.includes(claim.id))
+  const risksOrObjectionsVisible = narrative.risks.length === 0 && narrative.objections.length === 0 || slides.some((slide) => slide.narrativeRole === "risk")
 
   return [
+    {
+      id: "chapter_structure_present",
+      status: chapters.length >= 3 && chapters.length <= 5 && chapters.every((chapter) => chapter.slideIndexes.length > 0) ? "pass" : "blocker",
+      message: chapters.length >= 3 && chapters.length <= 5 && chapters.every((chapter) => chapter.slideIndexes.length > 0) ? `Deck plan includes ${chapters.length} deterministic chapters with slide ranges.` : "Deck plan must include 3-5 deterministic chapters, each mapped to at least one slide.",
+    },
+    {
+      id: "toc_matches_chapters",
+      status: chapterTitles.length > 0 && chapterTitles.every((title) => tocBullets.includes(title)) ? "pass" : "blocker",
+      message: chapterTitles.length > 0 && chapterTitles.every((title) => tocBullets.includes(title)) ? "TOC headings match the deterministic chapter plan." : "TOC headings do not match the deterministic chapter plan.",
+    },
     {
       id: "toc_present",
       status: slides.some((slide) => slide.components.includes("toc")) ? "pass" : "blocker",
@@ -397,6 +474,16 @@ function checkPlanQuality(narrative: NarrativeStateV1, slides: SlideSpec[]): Dec
       status: narrative.claims.some((claim) => claim.importance === "central" && (claim.unsupportedScope || (claim.caveats ?? []).length > 0)) ? "warning" : "pass",
       message: narrative.claims.some((claim) => claim.importance === "central" && (claim.unsupportedScope || (claim.caveats ?? []).length > 0)) ? "Central claim boundaries are visible and should remain explicit in the rendered artifact." : "No unsupported central claim boundaries were found.",
     },
+    {
+      id: "evidence_required_claims_have_evidence_or_visible_gap",
+      status: invisibleEvidenceGaps.length === 0 ? evidenceRequiredWithoutBindings.length > 0 ? "warning" : "pass" : "blocker",
+      message: invisibleEvidenceGaps.length > 0 ? `Evidence-required claims missing from planned slides: ${invisibleEvidenceGaps.map((claim) => claim.id).join(", ")}` : evidenceRequiredWithoutBindings.length > 0 ? `Evidence gaps remain visible for claims: ${evidenceRequiredWithoutBindings.map((claim) => claim.id).join(", ")}` : "Every evidence-required claim has at least one evidence binding.",
+    },
+    {
+      id: "risk_or_objection_visible",
+      status: risksOrObjectionsVisible ? "pass" : "warning",
+      message: risksOrObjectionsVisible ? "Risks and objections are visible when present." : "Narrative risks or objections exist but no risk/objection slide is planned.",
+    },
     {
       id: "simplified_design_grammar",
       status: incompatibleComponents.length === 0 ? "pass" : "blocker",