@cyber-dash-tech/revela 0.17.1 → 0.17.3

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

@@ -1,4 +1,4 @@
-import { deckPlanHash, upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec, type VisualBrief } from "../decks-state"
+import { deckPlanHash, upsertDeck, upsertSlides, type DeckSpec, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec, type VisualBrief } from "../decks-state"
 import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
 import { getClaimSlideRefs } from "./queries"
 import { computeNarrativeHash } from "./hash"
@@ -15,10 +15,38 @@ export interface CompileDeckPlanResult {
   skipped: boolean
   reason?: string
   narrativeHash: string
+  planHash?: string
+  planArtifactPath?: string
   slideCount: number
   slides: SlideSpec[]
   chapters?: DeckPlanChapter[]
   qualityChecks?: DeckPlanQualityCheck[]
+  renderPlan?: RenderPlanContract
+  planningPacket?: DeckPlanningPacket
+  deckPlanRequirements?: DeckPlanRequirements
+}
+
+export interface DeckPlanningPacket {
+  narrativeHash: string
+  outputPath: string
+  audience: NarrativeStateV1["audience"]
+  decision: NarrativeStateV1["decision"]
+  thesis: NarrativeStateV1["thesis"]
+  centralClaims: NarrativeClaim[]
+  supportingClaims: NarrativeClaim[]
+  evidenceBindings: NarrativeEvidenceBinding[]
+  objections: NarrativeStateV1["objections"]
+  risks: NarrativeStateV1["risks"]
+  researchGaps: NarrativeStateV1["researchGaps"]
+}
+
+export interface DeckPlanRequirements {
+  planArtifactPath: string
+  slidePlanDir: string
+  defaultProfile: string
+  userConfirmations: string[]
+  authoringRules: string[]
+  requiredSections: string[]
 }
 
 export interface DeckPlanChapter {
@@ -27,6 +55,7 @@ export interface DeckPlanChapter {
   slideIndexes: number[]
   claimIds: string[]
   evidenceBindingIds: string[]
+  sourceClaimId?: string
 }
 
 export interface DeckPlanQualityCheck {
@@ -35,7 +64,54 @@ export interface DeckPlanQualityCheck {
   message: string
 }
 
+export type RenderPlanSlideKind = "cover" | "toc" | "chapter-divider" | "claim-framing" | "claim-evidence" | "claim-implication" | "supporting-evidence" | "risk" | "ask" | "content"
+
+export interface RenderPlanSlideMetadata {
+  index: number
+  title: string
+  chapterTitle?: string
+  chapterRole?: DeckPlanChapter["role"]
+  slideKind: RenderPlanSlideKind
+  structural: boolean
+  countsTowardClaimSubstance: boolean
+  requiredComponents: string[]
+  evidenceTraceRequired: boolean
+  claimChapterRequirement?: "divider" | "framing" | "proof" | "implication" | "supporting-evidence" | "risk" | "ask"
+}
+
+export interface RenderPlanChapterRequirement {
+  title: string
+  role: DeckPlanChapter["role"]
+  sourceClaimId?: string
+  slideIndexes: number[]
+  requiredSubstanceSlides: number
+  actualSubstanceSlides: number
+  allowedStructuralSlides: string[]
+}
+
+export interface RenderPlanWritingBatch {
+  label: string
+  chapterTitle: string
+  slideIndexes: number[]
+  instructions: string
+}
+
+export interface RenderPlanContract {
+  sourceAuthority: {
+    meaning: string
+    renderPlan: string
+    state: string
+    htmlIdentity: string
+  }
+  renderRules: string[]
+  htmlIdentityContract: string[]
+  chapterRequirements: RenderPlanChapterRequirement[]
+  chapterWritingBatches: RenderPlanWritingBatch[]
+  slideRenderMetadata: RenderPlanSlideMetadata[]
+}
+
 type VisualIntentKind = "hero" | "toc" | "metric-stat" | "evidence-table" | "comparison-grid" | "risk-matrix" | "steps" | "text-only"
+type ClaimChapterSlideKind = "framing" | "evidence" | "implication"
 
 interface VisualIntent {
   kind: VisualIntentKind
@@ -66,10 +142,8 @@ 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 plan = buildDeckPlan(narrative)
-  const { slides, chapters } = plan
-  const qualityChecks = checkPlanQuality(narrative, slides, chapters)
-  const planCoverage = deckPlanCoverage(narrative, slides)
+  const planningPacket = buildDeckPlanningPacket(narrative, narrativeHash, deck?.outputPath ?? `decks/${slug}.html`)
+  const deckPlanRequirements = buildDeckPlanRequirements(narrativeHash)
   const requiredInputs: Partial<RequiredInputs> = {
     topicClarified: true,
     audienceClarified: Boolean(narrative.audience.primary),
@@ -93,13 +167,12 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
     } as RequiredInputs,
     writeReadiness: deck?.writeReadiness ?? { status: "blocked" as const, blockers: [] },
   })
-  next = upsertSlides(next, slug, slides)
   const plannedDeck = next.decks[slug]
   plannedDeck.planReview = {
     status: "pending",
     narrativeHash,
-    planHash: deckPlanHash(plannedDeck.slides),
-    qualityChecks,
+    planHash: "pending-deck-plan-md",
+    qualityChecks: [],
   }
   plannedDeck.requiredInputs = { ...plannedDeck.requiredInputs, slidePlanConfirmed: false }
   plannedDeck.writeReadiness = { status: "blocked", blockers: [] }
@@ -109,13 +182,13 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
   if (htmlTarget) {
     htmlTarget.data = {
       ...(htmlTarget.data ?? {}),
-      narrativeId: narrative.id,
-      narrativeHash,
-        planQualityChecks: qualityChecks,
-        planChapters: chapters,
-        requiredClaimIds: planCoverage.requiredClaimIds,
-      coveredClaimIds: planCoverage.coveredClaimIds,
-      missingClaimIds: planCoverage.missingClaimIds,
+        narrativeId: narrative.id,
+        narrativeHash,
+        planningPacket,
+        deckPlanRequirements,
+        requiredClaimIds: narrative.claims.filter((claim) => claim.importance === "central").map((claim) => claim.id),
+      coveredClaimIds: [],
+      missingClaimIds: narrative.claims.filter((claim) => claim.importance === "central").map((claim) => claim.id),
       claimSlideRefs: getClaimSlideRefs(next).map((ref) => ({
         claimId: ref.claimId,
         claimText: ref.claimText,
@@ -134,14 +207,169 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
         compiled: true,
         skipped: false,
         narrativeHash,
-        slideCount: slides.length,
-        slides,
-        chapters,
-        qualityChecks,
+        planArtifactPath: "deck-plan/index.md",
+        slideCount: 0,
+        slides: [],
+        chapters: [],
+        qualityChecks: [],
+        planningPacket,
+        deckPlanRequirements,
       },
     }
 }
 
+function buildDeckPlanningPacket(narrative: NarrativeStateV1, narrativeHash: string, outputPath: string): DeckPlanningPacket {
+  return {
+    narrativeHash,
+    outputPath,
+    audience: narrative.audience,
+    decision: narrative.decision,
+    thesis: narrative.thesis,
+    centralClaims: orderedClaims(narrative, (claim) => claim.importance === "central"),
+    supportingClaims: orderedClaims(narrative, (claim) => claim.importance !== "central"),
+    evidenceBindings: narrative.evidenceBindings,
+    objections: narrative.objections,
+    risks: narrative.risks,
+    researchGaps: narrative.researchGaps,
+  }
+}
+
+function buildDeckPlanRequirements(narrativeHash: string): DeckPlanRequirements {
+  return {
+    planArtifactPath: "deck-plan/index.md",
+    slidePlanDir: "deck-plan/slides",
+    defaultProfile: "executive decision deck, usually 12-18 slides unless the user confirms otherwise",
+    userConfirmations: [
+      "Confirm target slide count or acceptable range when it is unclear.",
+      "Confirm audience and decision context when the narrative does not make them explicit.",
+      "Confirm language, emphasis, or visual style only when needed before writing the plan.",
+    ],
+    authoringRules: [
+      "LLM writes deck-plan/index.md and deck-plan/slides/*.md from the planning packet; compileDeckPlan does not generate the final slide list.",
+      "Use 3-5 chapters for normal executive decks.",
+      "Cover every central claim, but group related central claims into chapters instead of giving each claim its own chapter.",
+      "Each substantive chapter should have framing, proof, and implication/boundary coverage.",
+      "Chapter divider or chapter TOC slides may use the toc component as structural wayfinding.",
+      "Do not create filler slides, repeated thesis pages, or generic bridge slides.",
+      "Preserve evidence ids, source trace, supported scope, unsupported scope, caveats, and strength where available.",
+      "Do not render internal labels such as Evidence gap:, Unsupported scope:, Caveat:, Missing Data, or Evidence Boundary in executive body copy.",
+      "Do not infer plan structure from DECKS.json slides[]; it is compatibility cache only.",
+      "Use ## Narrative Links in slide files for [[claim-id]], [[evidence-id]], [[risk-id]], [[objection-id]], or [[gap-id]] references; do not use canonical ## Relations in deck-plan files.",
+    ],
+    requiredSections: [
+      "Source Authority",
+      "Audience / Goal / Decision",
+      "Deck Parameters",
+      "Chapter Map",
+      "Slide Plan",
+      "Evidence Trace",
+      "Boundary / Risk Treatment",
+      "Chapter Writing Batches",
+      "HTML Identity Contract",
+    ],
+  }
+}
+
+export function buildRenderPlanContract(deck: DeckSpec, chapters: DeckPlanChapter[]): RenderPlanContract {
+  return {
+    sourceAuthority: {
+      meaning: "revela-narrative/ canonical narrative state",
+      renderPlan: "deck-plan/ projection workspace plus compileDeckPlan planning packet",
+      state: "DECKS.json compatibility/render state only; slides[] is cached projection data",
+      htmlIdentity: "positive 1-based data-slide-index values, unique and strictly increasing in DOM order",
+    },
+    renderRules: [
+      "Do not infer deck structure, slide count, or chapter substance from DECKS.json slides[].",
+      "Use the compileDeckPlan planning packet plus deck-plan/ projection Markdown as the render-plan contract.",
+      "Render chapter divider slides with the toc component when slideKind is chapter-divider.",
+      "Chapter divider and global TOC slides are structural wayfinding and do not count toward central-claim substance.",
+      "Each central claim chapter needs non-structural framing, proof, and implication/boundary slides unless the current deck-plan projection explicitly says otherwise.",
+      "Generate HTML chapter by chapter, preserving valid HTML and already-written slides after every batch.",
+    ],
+    htmlIdentityContract: [
+      "Every written slide section uses class slide and a positive 1-based data-slide-index.",
+      "data-slide-index values are unique and strictly increase in DOM order.",
+      "Partial chapter-by-chapter artifacts are allowed when written slide identities are self-consistent.",
+      "Do not pad missing planned chapters just to match cached DECKS.json slides[].",
+    ],
+    chapterRequirements: chapters.map((chapter) => {
+      const substanceSlides = chapter.slideIndexes
+        .map((index) => deck.slides.find((slide) => slide.index === index))
+        .filter((slide): slide is SlideSpec => Boolean(slide))
+        .filter((slide) => slideCountsTowardClaimSubstance(slide))
+      return {
+        title: chapter.title,
+        role: chapter.role,
+        sourceClaimId: chapter.sourceClaimId,
+        slideIndexes: chapter.slideIndexes,
+        requiredSubstanceSlides: chapter.sourceClaimId ? 3 : 0,
+        actualSubstanceSlides: substanceSlides.length,
+        allowedStructuralSlides: chapter.sourceClaimId ? ["chapter-divider", "toc"] : ["cover", "toc", "ask"],
+      }
+    }),
+    chapterWritingBatches: chapters.map((chapter, index) => ({
+      label: index === 0 ? "Initial shell and first chapter" : `Chapter batch ${index + 1}`,
+      chapterTitle: chapter.title,
+      slideIndexes: chapter.slideIndexes,
+      instructions: index === 0
+        ? "Create the stable HTML shell, required structural slides, and this first chapter range only."
+        : "Patch exactly this chapter range, preserve previously written slides, and keep the file valid after the patch.",
+    })),
+    slideRenderMetadata: deck.slides.map((slide) => slideRenderMetadata(slide, chapters)),
+  }
+}
+
+function slideRenderMetadata(slide: SlideSpec, chapters: DeckPlanChapter[]): RenderPlanSlideMetadata {
+  const chapter = chapters.find((item) => item.slideIndexes.includes(slide.index))
+  const slideKind = renderPlanSlideKind(slide, chapter)
+  return {
+    index: slide.index,
+    title: slide.title,
+    chapterTitle: chapter?.title,
+    chapterRole: chapter?.role,
+    slideKind,
+    structural: isStructuralRenderPlanSlide(slideKind),
+    countsTowardClaimSubstance: slideCountsTowardClaimSubstance(slide),
+    requiredComponents: slide.components ?? [],
+    evidenceTraceRequired: (slide.evidenceBindingIds?.length ?? 0) > 0 || (slide.evidence?.length ?? 0) > 0,
+    claimChapterRequirement: claimChapterRequirementForSlideKind(slideKind),
+  }
+}
+
+function renderPlanSlideKind(slide: SlideSpec, chapter: DeckPlanChapter | undefined): RenderPlanSlideKind {
+  const chapterSlide = (slide.content?.data as { chapterSlide?: string } | undefined)?.chapterSlide
+  if (slide.index === 1 && slide.components.includes("hero")) return "cover"
+  if (slide.layout === "toc" && chapter?.sourceClaimId) return "chapter-divider"
+  if (slide.layout === "toc") return "toc"
+  if (chapterSlide === "framing") return "claim-framing"
+  if (chapterSlide === "evidence") return "claim-evidence"
+  if (chapterSlide === "implication") return "claim-implication"
+  if (slide.narrativeRole === "risk") return "risk"
+  if (slide.narrativeRole === "ask" || slide.narrativeRole === "close") return "ask"
+  if (slide.narrativeRole === "evidence") return "supporting-evidence"
+  return "content"
+}
+
+function isStructuralRenderPlanSlide(kind: RenderPlanSlideKind): boolean {
+  return kind === "cover" || kind === "toc" || kind === "chapter-divider" || kind === "ask"
+}
+
+function slideCountsTowardClaimSubstance(slide: SlideSpec): boolean {
+  const kind = (slide.content?.data as { chapterSlide?: string } | undefined)?.chapterSlide
+  return kind === "framing" || kind === "evidence" || kind === "implication"
+}
+
+function claimChapterRequirementForSlideKind(kind: RenderPlanSlideKind): RenderPlanSlideMetadata["claimChapterRequirement"] {
+  if (kind === "chapter-divider") return "divider"
+  if (kind === "claim-framing") return "framing"
+  if (kind === "claim-evidence") return "proof"
+  if (kind === "claim-implication") return "implication"
+  if (kind === "supporting-evidence") return "supporting-evidence"
+  if (kind === "risk") return "risk"
+  if (kind === "ask") return "ask"
+  return undefined
+}
+
 function buildDeckPlan(narrative: NarrativeStateV1): { slides: SlideSpec[]; chapters: DeckPlanChapter[] } {
   const slides: SlideSpec[] = []
   const evidenceByClaim = evidenceBindingsByClaim(narrative.evidenceBindings)
@@ -154,9 +382,18 @@ function buildDeckPlan(narrative: NarrativeStateV1): { slides: SlideSpec[]; chap
   slides.push(tocSlide(slides.length + 1, chapters))
 
   for (const claim of centralClaims) {
-    const slide = claimSlide(slides.length + 1, claim, evidenceByClaim.get(claim.id) ?? [])
-    slides.push(slide)
-    assignSlideToChapter(chapters, chapterRoleForClaim(claim), slide)
+    const bindings = evidenceByClaim.get(claim.id) ?? []
+    const chapter = chapters.find((item) => item.sourceClaimId === claim.id)
+    const divider = chapterDividerSlide(slides.length + 1, chapters, chapter ?? chapterForClaimFallback(claim))
+    slides.push(divider)
+    if (chapter) assignSlideToSpecificChapter(chapter, divider)
+    else assignSlideToChapter(chapters, chapterRoleForClaim(claim), divider)
+    for (const kind of ["framing", "evidence", "implication"] as const) {
+      const slide = claimChapterSlide(slides.length + 1, claim, bindings, kind, narrative)
+      slides.push(slide)
+      if (chapter) assignSlideToSpecificChapter(chapter, slide)
+      else assignSlideToChapter(chapters, chapterRoleForClaim(claim), slide)
+    }
   }
   if (supportingClaims.length > 0) {
     const slide = supportingLogicSlide(slides.length + 1, supportingClaims, evidenceByClaim)
@@ -223,6 +460,45 @@ function tocSlide(index: number, chapters: DeckPlanChapter[]): SlideSpec {
   }
 }
 
+function chapterDividerSlide(index: number, chapters: DeckPlanChapter[], chapter: DeckPlanChapter): SlideSpec {
+  const visualIntent = visualIntentForStructuralSlide("toc", "Use a chapter divider as wayfinding before the claim-led chapter; it is structural and does not replace framing, proof, or implication slides.")
+  return {
+    index,
+    title: chapter.title,
+    purpose: `Open the ${chapter.title} chapter with a TOC-style divider before claim substance slides.`,
+    narrativeRole: "context",
+    layout: "toc",
+    qa: false,
+    components: ["toc", "text-panel"],
+    claimIds: chapter.sourceClaimId ? [chapter.sourceClaimId] : [],
+    claimRefs: chapter.sourceClaimId ? [{ claimId: chapter.sourceClaimId, role: "supporting", note: "Structural chapter divider; not counted as claim proof." }] : [],
+    evidenceBindingIds: [],
+    content: {
+      headline: chapter.title,
+      bullets: chapters.map((item) => item.title),
+      data: {
+        activeChapter: chapter.title,
+        chapters: chapters.map((item) => ({ title: item.title, role: item.role, active: item.title === chapter.title })),
+        visualIntent,
+      },
+    },
+    visuals: visualBriefs(index, visualIntent),
+    evidence: [],
+    status: "planned",
+  }
+}
+
+function chapterForClaimFallback(claim: NarrativeClaim): DeckPlanChapter {
+  return {
+    title: claimChapterTitle(claim),
+    role: chapterRoleForClaim(claim),
+    slideIndexes: [],
+    claimIds: [claim.id],
+    evidenceBindingIds: [],
+    sourceClaimId: claim.id,
+  }
+}
+
 function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): SlideSpec {
   const visualIntent = visualIntentForClaim(claim, bindings)
   return {
@@ -247,9 +523,105 @@ function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvi
   }
 }
 
+function claimChapterSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[], kind: ClaimChapterSlideKind, narrative: NarrativeStateV1): SlideSpec {
+  if (kind === "framing") return claimFramingSlide(index, claim, bindings)
+  if (kind === "evidence") return claimEvidenceSlide(index, claim, bindings)
+  return claimImplicationSlide(index, claim, bindings, narrative)
+}
+
+function claimFramingSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): SlideSpec {
+  const visualIntent = visualIntentForStructuralSlide("text-only", "Frame why this central claim deserves a chapter before proof detail; keep evidence boundaries visible.")
+  const notes = internalEvidenceDiagnostics(claim, bindings)
+  return {
+    index,
+    title: `${titleFromClaim(claim)} - framing`,
+    purpose: `Frame the audience context, decision relevance, and evidence boundary for central claim ${claim.id}.`,
+    narrativeRole: claim.kind === "problem" || claim.kind === "opportunity" ? "tension" : claim.kind === "context" ? "context" : "evidence",
+    layout: "two-col",
+    qa: true,
+    components: componentsForVisualIntent(["box", "text-panel"], visualIntent),
+    claimIds: [claim.id],
+    claimRefs: [{ claimId: claim.id, role: "primary", note: claimBoundaryNote(claim) }],
+    evidenceBindingIds: bindings.map((binding) => binding.id),
+    content: {
+      headline: claim.text,
+      bullets: [
+        `Chapter claim: ${claim.text}`,
+        claim.supportedScope ? `What the available evidence supports: ${claim.supportedScope}` : undefined,
+        claim.evidenceRequired ? audienceEvidenceGapBullet(claim, bindings) ?? `Proof base: ${bindings.length} bound evidence item${bindings.length === 1 ? "" : "s"} supports this claim.` : "This framing claim does not require separate proof in the deck plan.",
+      ].filter((item): item is string => Boolean(item)),
+      speakerNotes: notes,
+      data: { visualIntent, chapterSlide: "framing" },
+    },
+    evidence: bindings.map(evidenceRefFromBinding),
+    visuals: visualBriefs(index, visualIntent),
+    status: "planned",
+  }
+}
+
+function claimEvidenceSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): SlideSpec {
+  const visualIntent = visualIntentForClaim(claim, bindings)
+  const notes = internalEvidenceDiagnostics(claim, bindings)
+  return {
+    index,
+    title: `${titleFromClaim(claim)} - proof`,
+    purpose: `Show the specific evidence, source trace, support scope, unsupported scope, caveat, and strength for central claim ${claim.id}.`,
+    narrativeRole: "evidence",
+    layout: "two-col",
+    qa: true,
+    components: claimComponents(claim, bindings, visualIntent),
+    claimIds: [claim.id],
+    claimRefs: [{ claimId: claim.id, role: "evidence", note: claimBoundaryNote(claim) }],
+    evidenceBindingIds: bindings.map((binding) => binding.id),
+    content: {
+      headline: claim.text,
+      bullets: claimBullets(claim, bindings),
+      speakerNotes: notes,
+      data: { visualIntent, chapterSlide: "evidence" },
+    },
+    evidence: bindings.map(evidenceRefFromBinding),
+    visuals: visualBriefs(index, visualIntent),
+    status: "planned",
+  }
+}
+
+function claimImplicationSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[], narrative: NarrativeStateV1): SlideSpec {
+  const relatedRisks = narrative.risks.filter((risk) => risk.claimId === claim.id)
+  const relatedObjections = narrative.objections.filter((objection) => objection.claimId === claim.id)
+  const visualIntent = visualIntentForClaimImplication(claim, relatedRisks.length + relatedObjections.length)
+  const notes = internalEvidenceDiagnostics(claim, bindings)
+  return {
+    index,
+    title: `${titleFromClaim(claim)} - implication`,
+    purpose: `Translate central claim ${claim.id} into decision implication while keeping boundaries and risks explicit.`,
+    narrativeRole: claim.kind === "recommendation" || claim.kind === "ask" ? "recommendation" : relatedRisks.length > 0 || relatedObjections.length > 0 ? "risk" : "evidence",
+    layout: "two-col",
+    qa: true,
+    components: componentsForVisualIntent(["box", "text-panel"], visualIntent),
+    claimIds: [claim.id],
+    claimRefs: [{ claimId: claim.id, role: relatedRisks.length > 0 || relatedObjections.length > 0 ? "risk" : "supporting", note: claimBoundaryNote(claim) }],
+    evidenceBindingIds: bindings.map((binding) => binding.id),
+    content: {
+      headline: `Decision implication: ${claim.text}`,
+      bullets: [
+        ...claimBoundaryBullets(claim),
+        ...relatedRisks.slice(0, 2).map((risk) => risk.mitigation ? `Risk: ${risk.text} Mitigation: ${risk.mitigation}` : `Risk: ${risk.text}`),
+        ...relatedObjections.slice(0, 2).map((objection) => objection.response ? `Objection: ${objection.text} Response: ${objection.response}` : `Objection: ${objection.text}`),
+        relatedRisks.length === 0 && relatedObjections.length === 0 && !claim.unsupportedScope && (claim.caveats ?? []).length === 0 ? "Decision use: no specific limiting condition is recorded for this central claim." : undefined,
+      ].filter((item): item is string => Boolean(item)),
+      speakerNotes: notes,
+      data: { visualIntent, chapterSlide: "implication" },
+    },
+    evidence: bindings.map(evidenceRefFromBinding),
+    visuals: visualBriefs(index, visualIntent),
+    status: "planned",
+  }
+}
+
 function supportingLogicSlide(index: number, claims: NarrativeClaim[], evidenceByClaim: Map<string, NarrativeEvidenceBinding[]>): SlideSpec {
   const supportingBindings = claims.flatMap((claim) => evidenceByClaim.get(claim.id) ?? [])
   const visualIntent = visualIntentForSupportingLogic(claims, supportingBindings)
+  const notes = claims.map((claim) => internalEvidenceDiagnostics(claim, evidenceByClaim.get(claim.id) ?? [])).filter(Boolean).join("\n\n") || undefined
   return {
     index,
     title: "Supporting Logic",
@@ -263,7 +635,8 @@ 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), evidenceGapBullet(claim, evidenceByClaim.get(claim.id) ?? [])]).filter((item): item is string => Boolean(item)).slice(0, 8),
+      bullets: claims.slice(0, 5).flatMap((claim) => [claim.text, ...claimBoundaryBullets(claim), audienceEvidenceGapBullet(claim, evidenceByClaim.get(claim.id) ?? [])]).filter((item): item is string => Boolean(item)).slice(0, 8),
+      speakerNotes: notes,
       data: { visualIntent },
     },
     evidence: supportingBindings.map(evidenceRefFromBinding),
@@ -359,20 +732,27 @@ function deriveChapters(narrative: NarrativeStateV1, centralClaims: NarrativeCla
   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")
+  for (const claim of centralClaims) addClaimChapter(chapters, claim)
+  if (supportingClaims.length > 0 || centralClaims.length === 0 && (claims.some((claim) => claim.kind === "evidence") || narrative.evidenceBindings.length > 0)) addChapter(chapters, "Evidence and proof", "evidence")
+  if (centralClaims.length === 0 && claims.some((claim) => claim.kind === "recommendation" || claim.kind === "ask")) 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)
+    const removableIndex = chapters.findIndex((chapter) => !chapter.sourceClaimId && chapter.role !== "context" && chapter.role !== "ask")
+    if (removableIndex >= 0) chapters.splice(removableIndex, 1)
+    else break
   }
   return chapters
 }
 
+function addClaimChapter(chapters: DeckPlanChapter[], claim: NarrativeClaim): void {
+  const role = chapterRoleForClaim(claim)
+  const title = claimChapterTitle(claim)
+  if (chapters.some((chapter) => chapter.sourceClaimId === claim.id)) return
+  chapters.push({ title, role, slideIndexes: [], claimIds: [], evidenceBindingIds: [], sourceClaimId: claim.id })
+}
+
 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: [] })
@@ -381,6 +761,10 @@ function addChapter(chapters: DeckPlanChapter[], title: string, role: DeckPlanCh
 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
+  assignSlideToSpecificChapter(chapter, slide)
+}
+
+function assignSlideToSpecificChapter(chapter: DeckPlanChapter, slide: SlideSpec): void {
   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)
@@ -470,8 +854,36 @@ function visualIntentForRiskObjection(narrative: NarrativeStateV1, bindings: Nar
   }
 }
 
-function visualIntentForStructuralSlide(kind: Extract<VisualIntentKind, "hero" | "toc" | "steps">, rationale: string): VisualIntent {
-  return { kind, component: kind === "toc" ? "toc" : kind === "steps" ? "steps" : "hero", rationale, dataSignals: [], evidenceBindingIds: [] }
+function visualIntentForStructuralSlide(kind: Extract<VisualIntentKind, "hero" | "toc" | "steps" | "text-only">, rationale: string): VisualIntent {
+  return { kind, component: kind === "toc" ? "toc" : kind === "steps" ? "steps" : kind === "text-only" ? "box" : "hero", rationale, dataSignals: [], evidenceBindingIds: [] }
+}
+
+function visualIntentForClaimImplication(claim: NarrativeClaim, relatedBoundaryCount: number): VisualIntent {
+  if (claim.kind === "recommendation" || claim.kind === "ask") {
+    return {
+      kind: "steps",
+      component: "steps",
+      rationale: "Translate the chapter proof into concrete decision gates or actions while preserving evidence boundaries.",
+      dataSignals: [],
+      evidenceBindingIds: [],
+    }
+  }
+  if (relatedBoundaryCount > 0 || claim.unsupportedScope || (claim.caveats ?? []).length > 0) {
+    return {
+      kind: "risk-matrix",
+      component: "data-table",
+      rationale: "Show the decision implication alongside risks, objections, unsupported scope, and caveats so boundaries shape the recommendation.",
+      dataSignals: [],
+      evidenceBindingIds: [],
+    }
+  }
+  return {
+    kind: "text-only",
+    component: "box",
+    rationale: "State the decision implication without inventing risk or ROI detail that is not present in the canonical narrative.",
+    dataSignals: [],
+    evidenceBindingIds: [],
+  }
 }
 
 function componentsForVisualIntent(base: string[], visualIntent: VisualIntent): string[] {
@@ -502,21 +914,27 @@ function numericSignals(text: string): string[] {
 function claimBullets(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): string[] {
   return [
     ...claimBoundaryBullets(claim),
-    ...bindings.slice(0, 2).map((binding) => binding.supportScope ? `Evidence supports: ${binding.supportScope}` : undefined),
-    evidenceGapBullet(claim, bindings),
+    ...bindings.slice(0, 2).map((binding) => binding.supportScope ? `Evidence points to: ${binding.supportScope}` : undefined),
+    audienceEvidenceGapBullet(claim, bindings),
   ].filter((item): item is string => Boolean(item))
 }
 
-function evidenceGapBullet(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): string | undefined {
+function audienceEvidenceGapBullet(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"}.`
+  return claim.evidenceStatus === "missing"
+    ? "Decision boundary: this point needs supporting proof before it can carry the recommendation."
+    : "Decision boundary: current support is incomplete, so use this point as a qualified signal rather than a proven conclusion."
+}
+
+function isAudienceEvidenceGapBullet(text: string): boolean {
+  return text.startsWith("Decision boundary:") && (text.includes("supporting proof") || text.includes("qualified signal"))
 }
 
 function claimBoundaryBullets(claim: NarrativeClaim): string[] {
   return [
-    claim.supportedScope ? `Supported scope: ${claim.supportedScope}` : undefined,
-    claim.unsupportedScope ? `Unsupported scope: ${claim.unsupportedScope}` : undefined,
-    ...(claim.caveats ?? []).map((caveat) => `Caveat: ${caveat}`),
+    claim.supportedScope ? `What the available evidence supports: ${claim.supportedScope}` : undefined,
+    claim.unsupportedScope ? `What this does not yet prove: ${claim.unsupportedScope}` : undefined,
+    ...(claim.caveats ?? []).map((caveat) => `Use with caution: ${caveat}`),
   ].filter((item): item is string => Boolean(item))
 }
 
@@ -525,6 +943,18 @@ function claimBoundaryNote(claim: NarrativeClaim): string | undefined {
   return notes.length > 0 ? notes.join(" ") : undefined
 }
 
+function internalEvidenceDiagnostics(claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): string | undefined {
+  const lines = [
+    claim.supportedScope ? `Supported scope: ${claim.supportedScope}` : undefined,
+    claim.unsupportedScope ? `Unsupported scope: ${claim.unsupportedScope}` : undefined,
+    ...(claim.caveats ?? []).map((caveat) => `Caveat: ${caveat}`),
+    !claim.evidenceRequired ? undefined : bindings.length === 0 ? `Evidence gap: ${claim.evidenceStatus === "missing" ? "no binding yet" : "support remains incomplete"}.` : undefined,
+    ...bindings.map((binding) => binding.caveat ? `Evidence ${binding.id} caveat: ${binding.caveat}` : undefined),
+    ...bindings.map((binding) => binding.unsupportedScope ? `Evidence ${binding.id} unsupported scope: ${binding.unsupportedScope}` : undefined),
+  ].filter((item): item is string => Boolean(item))
+  return lines.length > 0 ? `Internal evidence diagnostics for author/reviewer use only. Do not render these labels as executive-facing body copy.\n${lines.map((line) => `- ${line}`).join("\n")}` : undefined
+}
+
 function dedupeClaimRefs<T extends { claimId: string; role: "risk" | "objection" }>(refs: T[]): T[] {
   const seen = new Set<string>()
   return refs.filter((ref) => {
@@ -551,6 +981,24 @@ function checkPlanQuality(narrative: NarrativeStateV1, slides: SlideSpec[], chap
   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 claimChapters = chapters.filter((chapter) => chapter.sourceClaimId)
+  const centralClaimsWithoutChapter = centralClaimIds.filter((claimId) => !claimChapters.some((chapter) => chapter.sourceClaimId === claimId))
+  const thinClaimChapters = claimChapters.filter((chapter) => nonStructuralClaimSlides(chapter, slides).length < 3)
+  const evidenceInvisibleChapters = claimChapters.filter((chapter) => {
+    const claim = narrative.claims.find((item) => item.id === chapter.sourceClaimId)
+    if (!claim?.evidenceRequired) return false
+    return chapter.evidenceBindingIds.length === 0 && !nonStructuralClaimSlides(chapter, slides).some((slide) => (slide.content.bullets ?? []).some((bullet) => isAudienceEvidenceGapBullet(bullet)))
+  })
+  const paddedClaimChapters = claimChapters.filter((chapter) => nonStructuralClaimSlides(chapter, slides).some((slide) => isFillerSlide(slide)))
+  const boundaryMissingChapters = claimChapters.filter((chapter) => {
+    const claim = narrative.claims.find((item) => item.id === chapter.sourceClaimId)
+    if (!claim) return false
+    const hasBoundary = Boolean(claim.unsupportedScope || (claim.caveats ?? []).length > 0 || narrative.risks.some((risk) => risk.claimId === claim.id) || narrative.objections.some((objection) => objection.claimId === claim.id))
+    if (!hasBoundary) return false
+    const text = nonStructuralClaimSlides(chapter, slides).flatMap((slide) => [slide.content.headline, ...(slide.content.bullets ?? [])]).join("\n")
+    const claimBoundaryVisible = [claim.unsupportedScope, ...(claim.caveats ?? [])].filter(Boolean).some((boundary) => text.includes(boundary!))
+    return !(claimBoundaryVisible || text.includes("Risk:") || text.includes("Objection:"))
+  })
   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 ?? []
@@ -560,6 +1008,31 @@ function checkPlanQuality(narrative: NarrativeStateV1, slides: SlideSpec[], chap
   const risksOrObjectionsVisible = narrative.risks.length === 0 && narrative.objections.length === 0 || slides.some((slide) => slide.narrativeRole === "risk")
 
   return [
+    {
+      id: "claim_chapters_present",
+      status: centralClaimsWithoutChapter.length === 0 ? "pass" : "blocker",
+      message: centralClaimsWithoutChapter.length === 0 ? "Every central claim has a deterministic claim-led chapter." : `Central claims missing claim-led chapters: ${centralClaimsWithoutChapter.join(", ")}`,
+    },
+    {
+      id: "claim_chapters_min_three_slides",
+      status: thinClaimChapters.length === 0 ? "pass" : "blocker",
+      message: thinClaimChapters.length === 0 ? "Every central claim chapter has at least three non-structural slides: framing, proof, and implication/boundary." : `Central claim chapters need at least three non-structural slides: ${thinClaimChapters.map((chapter) => chapter.sourceClaimId).join(", ")}`,
+    },
+    {
+      id: "claim_chapter_evidence_visible",
+      status: evidenceInvisibleChapters.length === 0 ? "pass" : "blocker",
+      message: evidenceInvisibleChapters.length === 0 ? "Evidence-required claim chapters show bound evidence or an explicit evidence gap." : `Evidence-required claim chapters hide evidence gaps: ${evidenceInvisibleChapters.map((chapter) => chapter.sourceClaimId).join(", ")}`,
+    },
+    {
+      id: "claim_chapter_not_padded_by_filler",
+      status: paddedClaimChapters.length === 0 ? "pass" : "blocker",
+      message: paddedClaimChapters.length === 0 ? "Claim chapters may use structural TOC dividers, but are not padded by placeholder, repeated thesis, or generic bridge slides." : `Claim chapters contain filler slides: ${paddedClaimChapters.map((chapter) => chapter.sourceClaimId).join(", ")}`,
+    },
+    {
+      id: "claim_chapter_boundary_visible",
+      status: boundaryMissingChapters.length === 0 ? "pass" : "blocker",
+      message: boundaryMissingChapters.length === 0 ? "Central claim chapter boundaries, risks, objections, and caveats remain visible when recorded." : `Central claim chapters hide recorded boundaries: ${boundaryMissingChapters.map((chapter) => chapter.sourceClaimId).join(", ")}`,
+    },
     {
       id: "chapter_structure_present",
       status: chapters.length >= 3 && chapters.length <= 5 && chapters.every((chapter) => chapter.slideIndexes.length > 0) ? "pass" : "blocker",
@@ -608,6 +1081,17 @@ function checkPlanQuality(narrative: NarrativeStateV1, slides: SlideSpec[], chap
   ]
 }
 
+function nonStructuralClaimSlides(chapter: DeckPlanChapter, slides: SlideSpec[]): SlideSpec[] {
+  const indexes = new Set(chapter.slideIndexes)
+  return slides.filter((slide) => indexes.has(slide.index) && slide.qa && slide.title !== "Decision Ask" && !slide.components.includes("toc"))
+}
+
+function isFillerSlide(slide: SlideSpec): boolean {
+  const text = `${slide.title}\n${slide.purpose}\n${slide.content.headline}\n${(slide.content.bullets ?? []).join("\n")}`.toLowerCase()
+  if (slide.components.includes("hero") && slide.qa) return true
+  return ["section divider", "bridge slide", "repeat thesis", "repeated thesis", "generic overview"].some((marker) => text.includes(marker))
+}
+
 function deckPlanCoverage(narrative: NarrativeStateV1, slides: SlideSpec[]): { requiredClaimIds: string[]; coveredClaimIds: string[]; missingClaimIds: string[] } {
   const requiredClaimIds = narrative.claims
     .filter((claim) => claim.importance === "central" || claim.evidenceRequired)
@@ -627,6 +1111,11 @@ function titleFromClaim(claim: NarrativeClaim): string {
   return words || claim.kind
 }
 
+function claimChapterTitle(claim: NarrativeClaim): string {
+  const title = titleFromClaim(claim)
+  return title.endsWith(".") ? title.slice(0, -1) : title
+}
+
 function hasCurrentApprovalOrOverride(narrative: NarrativeStateV1, narrativeHash: string): boolean {
   return narrative.approvals.some((approval) => approval.narrativeHash === narrativeHash && (approval.scope === "narrative" && approval.approvedBy === "user" || approval.scope === "render_override" || approval.approvedBy === "override"))
 }