@cyber-dash-tech/revela 0.12.0 → 0.13.0

package/lib/commands/brief.ts

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs"
+import { dirname, isAbsolute, join, normalize, resolve } from "path"
+import { readDecksState, writeDecksState } from "../decks-state"
+import { compileExecutiveBrief, DEFAULT_EXECUTIVE_BRIEF_PATH } from "../narrative-state/executive-brief"
+
+export interface BriefArgs {
+  outputPath?: string
+}
+
+export type ParseBriefArgsResult = { ok: true; args: BriefArgs } | { ok: false; error: string }
+
+export function parseBriefArgs(input: string): ParseBriefArgsResult {
+  const value = input.trim()
+  if (!value) return { ok: true, args: {} }
+  if (value.startsWith("--")) return { ok: false, error: "Usage: `/revela brief [workspace-relative-output.md]`" }
+  if (!value.endsWith(".md")) return { ok: false, error: "Executive brief output must be a Markdown file ending in `.md`." }
+  if (isAbsolute(value) || value.split(/[\\/]+/).includes("..")) return { ok: false, error: "Executive brief output must be a safe workspace-relative path." }
+  return { ok: true, args: { outputPath: normalize(value).replace(/\\/g, "/") } }
+}
+
+export async function handleBrief(
+  input: { workspaceRoot: string; outputPath?: string },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  const statePath = join(input.workspaceRoot, "DECKS.json")
+  if (!existsSync(statePath)) {
+    await send("No `DECKS.json` found. Run `/revela init` before rendering an executive brief.")
+    return
+  }
+
+  const state = readDecksState(input.workspaceRoot)
+  const result = compileExecutiveBrief(state, { outputPath: input.outputPath })
+  if (!result.ok) {
+    await send(
+      `**Executive brief not rendered**\n\n${result.reason}\n\n` +
+      (result.narrativeHash ? `Narrative hash: \`${result.narrativeHash}\`\n\n` : "") +
+      "Run `/revela review` and approve the current narrative, or record an explicit render override before retrying."
+    )
+    return
+  }
+
+  const filePath = safeWorkspaceFilePath(input.workspaceRoot, result.outputPath)
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, result.content, "utf-8")
+  writeDecksState(input.workspaceRoot, result.state)
+
+  await send(
+    `**Executive brief rendered**\n\n` +
+    `- Output: \`${result.outputPath}\`\n` +
+    `- Render target: \`${result.target.id}\`\n` +
+    `- Narrative hash: \`${result.narrativeHash}\`\n\n` +
+    "The brief was compiled from canonical narrative state, not from a deck summary."
+  )
+}
+
+function safeWorkspaceFilePath(workspaceRoot: string, outputPath: string): string {
+  const relative = outputPath || DEFAULT_EXECUTIVE_BRIEF_PATH
+  if (isAbsolute(relative) || relative.split(/[\\/]+/).includes("..")) throw new Error("Executive brief output must be a safe workspace-relative path.")
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relative)
+  if (target !== root && !target.startsWith(`${root}/`)) throw new Error("Executive brief output must stay inside the workspace.")
+  return target
+}

package/lib/commands/help.ts

@@ -28,6 +28,8 @@ export async function handleHelp(
     `\`/revela disable\`             — disable Revela mode\n` +
     `\`/revela init\`                — initialize or refresh workspace DECKS.json\n` +
     `\`/revela review\`              — review narrative readiness and approval state\n` +
+    `\`/revela narrative\`           — open read-only narrative workspace map\n` +
+    `\`/revela brief [file.md]\`      — render executive brief from approved narrative\n` +
     `\`/revela deck\`                — start deck handoff from approved narrative\n` +
     `\`/revela deck --review\`       — review deck/artifact readiness before writing HTML\n` +
     `\`/revela refine\`              — open unified Edit/Inspect refinement workspace\n` +

package/lib/commands/narrative.ts

@@ -0,0 +1,160 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { tmpdir } from "os"
+import { join } from "path"
+import { openUrl as defaultOpenUrl } from "../edit/open"
+import { hasDecksState, readDecksState } from "../decks-state"
+import { buildNarrativeMap, formatNarrativeMap } from "../narrative-state/map"
+import { renderNarrativeMapHtmlWithDisplay } from "../narrative-state/map-html"
+import { emptyDisplayModel, type NarrativeViewLanguage, type ValidatedNarrativeDisplayModel } from "../narrative-state/display"
+
+export interface NarrativeArgs {
+  language: NarrativeViewLanguage
+  raw: boolean
+}
+
+export type ParseNarrativeArgsResult = { ok: true; args: NarrativeArgs } | { ok: false; error: string }
+
+export function parseNarrativeArgs(param: string): ParseNarrativeArgsResult {
+  const tokens = param.trim().split(/\s+/).filter(Boolean)
+  let language: NarrativeViewLanguage = "en"
+  let raw = false
+  const languageParts: string[] = []
+  for (const token of tokens) {
+    const normalized = token.toLowerCase()
+    if (normalized === "--raw") {
+      raw = true
+      continue
+    }
+    if (token.startsWith("--") && token.length > 2) {
+      language = normalizeLanguageRequest(token.slice(2))
+      continue
+    }
+    languageParts.push(token)
+  }
+  if (languageParts.length > 0) language = normalizeLanguageRequest(languageParts.join(" "))
+  return { ok: true, args: { language, raw } }
+}
+
+function normalizeLanguageRequest(value: string): NarrativeViewLanguage {
+  const trimmed = value.trim()
+  const normalized = trimmed.toLowerCase()
+  if (["en", "eng", "english"].includes(normalized)) return "en"
+  if (["cn", "zh", "zh-cn", "chinese"].includes(normalized)) return "zh-CN"
+  if (["jp", "ja", "ja-jp", "japanese"].includes(normalized)) return "ja-JP"
+  return trimmed || "en"
+}
+
+export async function handleNarrative(
+  options: { workspaceRoot: string; openBrowser?: boolean; openUrl?: (url: string) => void; language?: NarrativeViewLanguage; display?: ValidatedNarrativeDisplayModel },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    if (!hasDecksState(options.workspaceRoot)) {
+      await send("No `DECKS.json` found. Run `/revela init` first to initialize the narrative workspace.")
+      return
+    }
+
+    const state = readDecksState(options.workspaceRoot)
+    const map = buildNarrativeMap(state)
+    const markdown = formatNarrativeMap(map)
+
+    if (options.openBrowser) {
+      const htmlPath = writeNarrativeMapHtml(map, options.display ?? emptyDisplayModel(options.language ?? "en"))
+      const url = `file://${htmlPath}`
+      try {
+        ;(options.openUrl ?? defaultOpenUrl)(url)
+        await send(`Opened read-only narrative workspace: ${url}\n\n${markdown}`)
+      } catch (e: any) {
+        await send(`Read-only narrative workspace generated but could not open automatically: ${url}\n\n${e.message || String(e)}\n\n${markdown}`)
+      }
+      return
+    }
+
+    await send(markdown)
+  } catch (e: any) {
+    await send(`**Narrative map failed:** ${e.message || String(e)}`)
+  }
+}
+
+export function buildNarrativeViewPrompt(options: { workspaceRoot: string; language: NarrativeViewLanguage }): string {
+  if (!hasDecksState(options.workspaceRoot)) {
+    return "No `DECKS.json` found. Tell the user to run `/revela init` before opening the narrative view. Do not call any tool."
+  }
+
+  const map = buildNarrativeMap(readDecksState(options.workspaceRoot))
+  const projection = {
+    narrativeHash: map.snapshot.narrativeHash,
+    language: options.language,
+    snapshot: map.snapshot,
+    claims: map.claimFlow.map((claim) => ({
+      id: claim.id,
+      kind: claim.kind,
+      importance: claim.importance,
+      evidenceStatus: claim.evidenceStatus,
+      text: claim.text,
+      supportedScope: claim.supportedScope,
+      unsupportedScope: claim.unsupportedScope,
+      evidence: claim.evidence.map((evidence) => ({ source: evidence.source, strength: evidence.strength, findingsFile: evidence.findingsFile, location: evidence.location, quote: evidence.quote, caveat: evidence.caveat, unsupportedScope: evidence.unsupportedScope })),
+    })),
+    relations: map.claimRelations.map((relation) => ({ id: relation.id, fromClaimId: relation.fromClaimId, toClaimId: relation.toClaimId, relation: relation.relation, rationale: relation.rationale, inferred: relation.inferred })),
+    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question })),
+    artifactCoverage: map.artifactCoverage.map((artifact) => ({ type: artifact.type, outputPath: artifact.outputPath, stale: artifact.stale, slideRefs: artifact.slideRefs.map((ref) => ({ claimId: ref.claimId, slideIndex: ref.slideIndex, role: ref.role, match: ref.match, location: ref.location })) })),
+  }
+
+  return `Prepare the read-only Revela narrative UI display model.
+
+Target language request: ${options.language}
+- The language value is passed from the user's /revela narrative arguments. Interpret it as the desired UI/display language.
+- Examples: --cn maps to zh-CN, --jp maps to ja-JP, while --fr, --de, --es, --ko, --Arabic, --Portuguese-BR, or a written language name should be localized normally into that requested language.
+- Default /revela narrative language is en when the user provides no language request.
+
+You must call the \`revela-narrative-view\` tool exactly once.
+
+Hard rules:
+- Do not mutate DECKS.json, deck HTML, evidence, claims, relations, approvals, or artifacts.
+- Do not invent new claims, evidence, relations, slide coverage, source paths, findings files, quotes, or caveats.
+- Preserve every claimId exactly.
+- Preserve every relation endpoint exactly: fromClaimId, toClaimId, relation.
+- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- For inferred relations, do not provide relation displayLabel or displayRationale; inferred relations are unconfirmed order notes, not causal/support/dependency judgments.
+- relation displayRationale may only localize or clarify an existing canonical relation rationale. If relation.rationale is missing or the relation is inferred, do not provide displayRationale; the UI will show the missing or inferred status.
+- Keep source paths, findings files, claim IDs, narrative hash, and numbers unchanged.
+- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- Do not translate claim IDs, relation endpoints, narrative hash, source paths, findings files, URLs, numbers, or quoted/source facts.
+- Use natural business and manufacturing terminology in the target language, not word-by-word machine translation.
+- If a fact is missing, describe it as missing instead of filling it in.
+
+Chinese localization rules when the target language request is Chinese, zh, zh-CN, --cn, 中文, or Simplified Chinese:
+- Use natural business/manufacturing Chinese, not word-by-word machine translation.
+- In manufacturing, industrial AI, automation, and autonomous systems context, translate "autonomy" as "自主化", "自主能力", or "自主系统". Do not translate it as "自治".
+- Translate "autonomous" as "自主的" / "自主化的" where appropriate, not "自治的".
+- Translate "architectural" as "架构层面的", "架构性", or "架构问题" according to context.
+- Slug-like or kebab-case claim text such as "autonomy-is-architectural" should become a readable displayTitle such as "自主化是架构问题" or "自主化必须作为架构问题处理", not a literal token-by-token translation.
+- If the canonical claim text is only a slug, preserve the claimId exactly but write displayTitle as a readable claim title.
+
+Call \`revela-narrative-view\` with:
+- language: ${options.language}
+- narrativeHash: ${map.snapshot.narrativeHash}
+- displayModel.version: 1
+- displayModel.language: ${options.language}
+- displayModel.claimCards only for claim IDs listed below
+- displayModel.relations only for relations listed below
+
+Compact deterministic narrative map:
+
+\`\`\`json
+${JSON.stringify(projection, null, 2)}
+\`\`\``
+}
+
+export function writeNarrativeMapHtml(map: ReturnType<typeof buildNarrativeMap>, display: ValidatedNarrativeDisplayModel = emptyDisplayModel("en")): string {
+  const dir = join(tmpdir(), "revela-narrative")
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${safeFilePart(map.snapshot.narrativeId)}-${map.snapshot.narrativeHash}.html`)
+  writeFileSync(file, renderNarrativeMapHtmlWithDisplay(map, display), "utf-8")
+  return file
+}
+
+function safeFilePart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "narrative"
+}

package/lib/decks-state.ts

@@ -26,6 +26,7 @@ export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
 export type WriteReadinessStatus = "blocked" | "ready" | "written"
 export type NarrativeRole = "context" | "tension" | "evidence" | "recommendation" | "risk" | "ask" | "appendix" | "close"
+export type SlideClaimRefRole = "primary" | "supporting" | "evidence" | "risk" | "objection"
 
 export interface DecksState {
   version: 1
@@ -135,6 +136,9 @@ export interface SlideSpec {
   layout: string
   qa?: boolean
   components: string[]
+  claimIds?: string[]
+  claimRefs?: SlideClaimRef[]
+  evidenceBindingIds?: string[]
   content: {
     headline?: string
     body?: string[]
@@ -148,6 +152,12 @@ export interface SlideSpec {
   notes?: string
 }
 
+export interface SlideClaimRef {
+  claimId: string
+  role: SlideClaimRefRole
+  note?: string
+}
+
 export interface EvidenceRef {
   source: string
   quote?: string
@@ -1478,6 +1488,9 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
       title: slide.title ?? "",
       layout: slide.layout ?? "",
       components: slide.components ?? [],
+      claimIds: normalizeTextList(slide.claimIds),
+      claimRefs: normalizeSlideClaimRefs(slide.claimRefs),
+      evidenceBindingIds: normalizeTextList(slide.evidenceBindingIds),
       content: slide.content ?? {},
       evidence: slide.evidence ?? [],
       status: slide.status ?? "planned",
@@ -1485,6 +1498,26 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
     .sort((a, b) => a.index - b.index)
 }
 
+function normalizeSlideClaimRefs(refs: SlideClaimRef[] | undefined): SlideClaimRef[] {
+  const seen = new Set<string>()
+  const out: SlideClaimRef[] = []
+  for (const ref of refs ?? []) {
+    const claimId = cleanOptionalText(ref.claimId)
+    if (!claimId) continue
+    const role = isSlideClaimRefRole(ref.role) ? ref.role : "supporting"
+    const key = `${claimId}:${role}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const note = cleanOptionalText(ref.note)
+    out.push({ claimId, role, ...(note ? { note } : {}) })
+  }
+  return out
+}
+
+function isSlideClaimRefRole(value: string | undefined): value is SlideClaimRefRole {
+  return value === "primary" || value === "supporting" || value === "evidence" || value === "risk" || value === "objection"
+}
+
 function normalizeNarrativeBrief(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
   if (!brief) return undefined
   const normalized: NarrativeBrief = {

package/lib/edit/prompt.ts

@@ -71,6 +71,9 @@ 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.
+- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, 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.
 - Do not rewrite unrelated slides or broad sections of the deck.
 - Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.

package/lib/inspection-context/compile.ts

@@ -1,6 +1,7 @@
 import type { DeckSpec, DecksState, EvidenceRef, NarrativeBrief, NarrativeRole, SlideSpec, SourceMaterial } from "../decks-state"
+import type { NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "../narrative-state/types"
 
-export type InspectionClaimOrigin = "title" | "headline" | "body" | "bullet" | "purpose"
+export type InspectionClaimOrigin = "narrative" | "title" | "headline" | "body" | "bullet" | "purpose"
 export type InspectionGapType = "missing_evidence" | "weak_evidence"
 export type InspectionEvidenceSupport = "supported" | "weak" | "unknown"
 
@@ -13,6 +14,7 @@ export interface InspectionContext {
   outputPath: string
   narrativeBrief?: NarrativeBrief
   sourceMaterials: InspectionSourceMaterial[]
+  narrative?: InspectionNarrativeStateContext
   slides: InspectionSlideContext[]
   gaps: InspectionGap[]
   appendixCandidates: InspectionAppendixCandidate[]
@@ -20,6 +22,12 @@ export interface InspectionContext {
   riskContext: InspectionNarrativeContext[]
 }
 
+export interface InspectionNarrativeStateContext {
+  id: string
+  status: string
+  claimCount: number
+}
+
 export interface InspectionSourceMaterial extends SourceMaterial {
   linkedEvidenceCount: number
 }
@@ -46,6 +54,7 @@ export interface InspectionSlideText {
 
 export interface InspectionClaimCandidate {
   id: string
+  canonicalClaimId?: string
   slideIndex: number
   slideTitle: string
   origin: InspectionClaimOrigin
@@ -54,9 +63,18 @@ export interface InspectionClaimCandidate {
   evidenceSupport: InspectionEvidenceSupport
   evidence: InspectionEvidenceTrace[]
   gaps: InspectionGap[]
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
 }
 
 export interface InspectionEvidenceTrace extends EvidenceRef {
+  evidenceBindingId?: string
+  claimId?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: NarrativeEvidenceBinding["strength"]
   slideIndex: number
   slideTitle: string
   hasDetail: boolean
@@ -87,12 +105,13 @@ export interface InspectionNarrativeContext {
 
 export function compileInspectionContext(state: DecksState, slug?: string): InspectionContext {
   const deck = activeDeck(state, slug)
+  const narrative = state.narrative
   const evidence = collectEvidence(deck)
   const sourceMaterials = compileSourceMaterials(state.workspace.sourceMaterials ?? [], evidence)
   const slides = deck.slides
     .slice()
     .sort((a, b) => a.index - b.index)
-    .map((slide) => compileSlide(slide))
+    .map((slide) => compileSlide(slide, narrative))
   const gaps = slides.flatMap((slide) => slide.claims.flatMap((claim) => claim.gaps))
 
   return {
@@ -103,6 +122,7 @@ export function compileInspectionContext(state: DecksState, slug?: string): Insp
     language: deck.language,
     outputPath: deck.outputPath,
     narrativeBrief: deck.narrativeBrief,
+    narrative: narrative ? { id: narrative.id, status: narrative.status, claimCount: narrative.claims.length } : undefined,
     sourceMaterials,
     slides,
     gaps,
@@ -118,9 +138,15 @@ function activeDeck(state: DecksState, slug?: string): DeckSpec {
   return state.decks[key]
 }
 
-function compileSlide(slide: SlideSpec): InspectionSlideContext {
+function compileSlide(slide: SlideSpec, narrative: NarrativeStateV1 | undefined): InspectionSlideContext {
   const evidence = slide.evidence.map((item) => compileEvidence(slide, item))
-  const claims = claimCandidates(slide).map((claim, position) => compileClaim(slide, claim, position, evidence))
+  const canonicalClaims = narrative ? canonicalClaimCandidates(slide, narrative, evidence) : []
+  const canonicalText = new Set(canonicalClaims.map((claim) => normalizeText(claim.text)))
+  const heuristicClaims = claimCandidates(slide)
+    .filter((claim) => !canonicalText.has(normalizeText(claim.text)))
+    .map((claim, position) => compileClaim(slide, claim, position, evidence))
+  const claims = [...canonicalClaims, ...heuristicClaims]
+  const claimCaveats = canonicalClaims.flatMap((claim) => claim.caveats)
   return {
     index: slide.index,
     title: slide.title,
@@ -136,7 +162,61 @@ function compileSlide(slide: SlideSpec): InspectionSlideContext {
     },
     claims,
     evidence,
-    caveats: evidence.map((item) => item.caveat).filter((item): item is string => Boolean(item?.trim())),
+    caveats: dedupeText([
+      ...evidence.map((item) => item.caveat).filter((item): item is string => Boolean(item?.trim())),
+      ...claimCaveats,
+    ]),
+  }
+}
+
+function canonicalClaimCandidates(slide: SlideSpec, narrative: NarrativeStateV1, slideEvidence: InspectionEvidenceTrace[]): InspectionClaimCandidate[] {
+  const claimRefs = slide.claimRefs ?? []
+  const metadataClaimIds = new Set([
+    ...claimRefs.map((ref) => ref.claimId),
+    ...(slide.claimIds ?? []),
+  ].filter(Boolean))
+  const evidenceBindingIds = new Set(slide.evidenceBindingIds ?? [])
+  for (const binding of narrative.evidenceBindings) {
+    if (evidenceBindingIds.has(binding.id)) metadataClaimIds.add(binding.claimId)
+  }
+
+  return narrative.claims
+    .filter((claim) => metadataClaimIds.has(claim.id))
+    .map((claim) => compileCanonicalClaim(slide, claim, narrative.evidenceBindings, slideEvidence, evidenceBindingIds))
+}
+
+function compileCanonicalClaim(
+  slide: SlideSpec,
+  claim: NarrativeClaim,
+  bindings: NarrativeEvidenceBinding[],
+  slideEvidence: InspectionEvidenceTrace[],
+  slideEvidenceBindingIds: Set<string>,
+): InspectionClaimCandidate {
+  const allClaimBindings = bindings.filter((binding) => binding.claimId === claim.id)
+  const selectedBindings = allClaimBindings.filter((binding) => slideEvidenceBindingIds.size === 0 || slideEvidenceBindingIds.has(binding.id))
+  const evidenceBindings = selectedBindings.length > 0 ? selectedBindings : allClaimBindings
+  const evidence = evidenceBindings.length > 0
+    ? evidenceBindings.map((binding) => compileEvidenceBinding(slide, binding))
+    : slideEvidence
+  const gaps = canonicalClaimGaps(slide, claim, evidence)
+  return {
+    id: claim.id,
+    canonicalClaimId: claim.id,
+    slideIndex: slide.index,
+    slideTitle: slide.title,
+    origin: "narrative",
+    text: claim.text,
+    evidenceSensitive: claim.evidenceRequired || isEvidenceSensitiveClaim(claim.text),
+    evidenceSupport: narrativeEvidenceSupport(claim, evidence),
+    evidence,
+    gaps,
+    evidenceBindingIds: evidenceBindings.map((binding) => binding.id),
+    supportedScope: claim.supportedScope,
+    unsupportedScope: claim.unsupportedScope,
+    caveats: dedupeText([
+      ...(claim.caveats ?? []),
+      ...evidenceBindings.map((binding) => binding.caveat).filter((item): item is string => Boolean(item?.trim())),
+    ]),
   }
 }
 
@@ -159,7 +239,34 @@ function compileClaim(
     evidenceSupport: evidenceSupport(evidence),
     evidence,
     gaps,
+    evidenceBindingIds: [],
+    caveats: [],
+  }
+}
+
+function canonicalClaimGaps(slide: SlideSpec, claim: NarrativeClaim, evidence: InspectionEvidenceTrace[]): InspectionGap[] {
+  if (!claim.evidenceRequired) return []
+  if (claim.evidenceStatus === "missing" || evidence.length === 0) {
+    return [{
+      type: "missing_evidence",
+      slideIndex: slide.index,
+      slideTitle: slide.title,
+      claimId: claim.id,
+      claimText: claim.text,
+      message: "Canonical narrative claim requires evidence but has no bound evidence trace.",
+    }]
   }
+  if (claim.evidenceStatus === "weak" || evidence.some((item) => !item.hasDetail)) {
+    return [{
+      type: "weak_evidence",
+      slideIndex: slide.index,
+      slideTitle: slide.title,
+      claimId: claim.id,
+      claimText: claim.text,
+      message: "Canonical narrative claim has weak or source-only evidence trace.",
+    }]
+  }
+  return []
 }
 
 function claimGaps(slide: SlideSpec, claimId: string, claimText: string, evidence: InspectionEvidenceTrace[]): InspectionGap[] {
@@ -192,6 +299,12 @@ function evidenceSupport(evidence: InspectionEvidenceTrace[]): InspectionEvidenc
   return "supported"
 }
 
+function narrativeEvidenceSupport(claim: NarrativeClaim, evidence: InspectionEvidenceTrace[]): InspectionEvidenceSupport {
+  if (claim.evidenceStatus === "supported" || claim.evidenceStatus === "not_required") return "supported"
+  if (claim.evidenceStatus === "partial" || claim.evidenceStatus === "weak") return "weak"
+  return evidenceSupport(evidence)
+}
+
 function claimCandidates(slide: SlideSpec): Array<{ origin: InspectionClaimOrigin; text: string }> {
   const claims: Array<{ origin: InspectionClaimOrigin; text: string }> = []
   pushClaim(claims, "title", slide.title)
@@ -218,6 +331,29 @@ function compileEvidence(slide: SlideSpec, evidence: EvidenceRef): InspectionEvi
   }
 }
 
+function compileEvidenceBinding(slide: SlideSpec, binding: NarrativeEvidenceBinding): InspectionEvidenceTrace {
+  const evidence: EvidenceRef = {
+    source: binding.source,
+    sourcePath: binding.sourcePath,
+    findingsFile: binding.findingsFile,
+    quote: binding.quote,
+    location: binding.location,
+    url: binding.url,
+    caveat: binding.caveat,
+  }
+  return {
+    ...evidence,
+    evidenceBindingId: binding.id,
+    claimId: binding.claimId,
+    supportScope: binding.supportScope,
+    unsupportedScope: binding.unsupportedScope,
+    strength: binding.strength,
+    slideIndex: slide.index,
+    slideTitle: slide.title,
+    hasDetail: hasEvidenceDetail(evidence),
+  }
+}
+
 function collectEvidence(deck: DeckSpec): InspectionEvidenceTrace[] {
   return deck.slides.flatMap((slide) => slide.evidence.map((item) => compileEvidence(slide, item)))
 }
@@ -303,6 +439,24 @@ function cleanOptionalText(value: string | undefined): string | undefined {
   return text || undefined
 }
 
+function dedupeText(values: string[]): string[] {
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const value of values) {
+    const cleaned = cleanOptionalText(value)
+    if (!cleaned) continue
+    const key = normalizeText(cleaned)
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(cleaned)
+  }
+  return result
+}
+
+function normalizeText(value: string | undefined): string {
+  return value?.replace(/\s+/g, " ").trim().toLowerCase() ?? ""
+}
+
 const EVIDENCE_SENSITIVE_TERMS = [
   /\bmarket size\b/,
   /\bcagr\b/,

package/lib/inspection-context/project.ts

@@ -50,10 +50,15 @@ export interface InspectionProjectionMatch {
   }
   claim?: {
     id: string
+    canonicalClaimId?: string
     origin: string
     text: string
     evidenceSensitive: boolean
     evidenceSupport: string
+    evidenceBindingIds: string[]
+    supportedScope?: string
+    unsupportedScope?: string
+    caveats: string[]
   }
 }
 
@@ -97,6 +102,8 @@ export interface InspectionAppendixProjection {
 
 export interface InspectionEvidenceProjectionTrace {
   source: string
+  evidenceBindingId?: string
+  claimId?: string
   sourcePath?: string
   findingsFile?: string
   location?: string
@@ -104,6 +111,9 @@ export interface InspectionEvidenceProjectionTrace {
   url?: string
   quote?: string
   caveat?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: string
   extractedTextPath?: string
   extractedManifestPath?: string
   hasDetail: boolean
@@ -163,10 +173,15 @@ export function projectInspectionMatch(
       claim: claim
         ? {
             id: claim.id,
+            canonicalClaimId: claim.canonicalClaimId,
             origin: claim.origin,
             text: truncate(claim.text, 500),
             evidenceSensitive: claim.evidenceSensitive,
             evidenceSupport: claim.evidenceSupport,
+            evidenceBindingIds: claim.evidenceBindingIds,
+            supportedScope: truncateOptional(claim.supportedScope, 280),
+            unsupportedScope: truncateOptional(claim.unsupportedScope, 280),
+            caveats: claim.caveats.map((item) => truncate(item, 280)).slice(0, 8),
           }
         : undefined,
     },
@@ -211,6 +226,8 @@ export function projectInspectionMatch(
 function projectEvidenceTrace(trace: InspectionEvidenceTrace): InspectionEvidenceProjectionTrace {
   return {
     source: truncate(trace.source, 180),
+    evidenceBindingId: truncateOptional(trace.evidenceBindingId, 160),
+    claimId: truncateOptional(trace.claimId, 160),
     sourcePath: truncateOptional(trace.sourcePath, 220),
     findingsFile: truncateOptional(trace.findingsFile, 220),
     location: truncateOptional(trace.location, 120),
@@ -218,6 +235,9 @@ function projectEvidenceTrace(trace: InspectionEvidenceTrace): InspectionEvidenc
     url: truncateOptional(trace.url, 240),
     quote: truncateOptional(trace.quote, 500),
     caveat: truncateOptional(trace.caveat, 280),
+    supportScope: truncateOptional(trace.supportScope, 280),
+    unsupportedScope: truncateOptional(trace.unsupportedScope, 280),
+    strength: trace.strength,
     extractedTextPath: truncateOptional(trace.extractedTextPath, 220),
     extractedManifestPath: truncateOptional(trace.extractedManifestPath, 220),
     hasDetail: trace.hasDetail,