@cyber-dash-tech/revela 0.17.6 → 0.17.8

package/lib/runtime/index.ts

@@ -0,0 +1,225 @@
+import { existsSync } from "fs"
+import { resolve } from "path"
+import { activeDesign, activateDesign, getDesignSkillMd, listDesigns, seedBuiltinDesigns } from "../design/designs"
+import { createDeckFoundation as createDeckFoundationShell } from "../deck-html/foundation"
+import { activeDomain, activateDomain, getDomainSkillMd, listDomains, seedBuiltinDomains } from "../domain/domains"
+import { computeNarrativeHash } from "../narrative-state/hash"
+import { compileNarrativeVault } from "../narrative-vault/compile"
+import { runNarrativeMarkdownQa, type MarkdownQaOptions } from "../narrative-vault/markdown-qa"
+import { readDeckPlanArtifact } from "../narrative-state/deck-plan-artifact"
+import { exportToPdf } from "../pdf/export"
+import { exportToPptx } from "../pptx/export"
+import { assertExportQAPassed } from "../qa/export-gate"
+import { formatArtifactQAReport, runArtifactQA } from "../qa/artifact"
+import { extractDesignClasses } from "../design/designs"
+import { recordRenderedArtifact, workspaceRelative } from "../workspace-state/rendered-artifacts"
+export { bindResearchFindings, evaluateResearchFindings, researchSave, researchTargets } from "./research"
+export { reviewDeckOpen, reviewDeckRead } from "./review"
+export { storyRead } from "./story"
+
+export interface RuntimeWorkspaceInput {
+  workspaceRoot?: string
+}
+
+export interface RuntimeFileInput extends RuntimeWorkspaceInput {
+  file: string
+}
+
+export interface RuntimeDeckFoundationInput extends RuntimeWorkspaceInput {
+  outputPath: string
+  title: string
+  language: string
+  designName?: string
+  mode?: "create" | "repair"
+  overwrite?: boolean
+}
+
+export interface RuntimeDesignReadInput {
+  name?: string
+}
+
+export interface RuntimeNameInput {
+  name: string
+}
+
+export function doctor(input: RuntimeWorkspaceInput = {}) {
+  const workspaceRoot = root(input.workspaceRoot)
+  return {
+    ok: true,
+    workspaceRoot,
+    hasNarrativeVault: existsSync(resolve(workspaceRoot, "revela-narrative")),
+    hasDeckPlan: existsSync(resolve(workspaceRoot, "deck-plan")),
+    hasDecksJson: existsSync(resolve(workspaceRoot, "DECKS.json")),
+    activeDesign: safe(activeDesign),
+  }
+}
+
+export function compileNarrative(input: RuntimeWorkspaceInput = {}) {
+  const workspaceRoot = root(input.workspaceRoot)
+  return compileNarrativeVault(workspaceRoot)
+}
+
+export function markdownQa(input: RuntimeWorkspaceInput & MarkdownQaOptions = {}) {
+  const workspaceRoot = root(input.workspaceRoot)
+  return runNarrativeMarkdownQa(workspaceRoot, {
+    scope: input.scope,
+    strictness: input.strictness,
+    touched: input.touched,
+  })
+}
+
+export function readDeckPlan(input: RuntimeWorkspaceInput = {}) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const compiled = compileNarrativeVault(workspaceRoot)
+  const knownNodeIds = compiled.graph ? new Set(compiled.graph.nodes.map((node) => node.id)) : undefined
+  return readDeckPlanArtifact(workspaceRoot, {
+    narrativeHash: compiled.narrative ? computeNarrativeHash(compiled.narrative) : undefined,
+    knownNodeIds,
+  })
+}
+
+export function createDeckFoundation(input: RuntimeDeckFoundationInput) {
+  return createDeckFoundationShell({
+    workspaceRoot: root(input.workspaceRoot),
+    outputPath: input.outputPath,
+    title: input.title,
+    language: input.language,
+    designName: input.designName,
+    mode: input.mode,
+    overwrite: input.overwrite ?? false,
+  })
+}
+
+export async function runDeckQa(input: RuntimeFileInput) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const filePath = resolve(workspaceRoot, input.file)
+  let vocabulary
+  try {
+    vocabulary = extractDesignClasses()
+  } catch {
+    // Design vocabulary is optional.
+  }
+  const report = await runArtifactQA({ workspaceRoot, filePath, vocabulary })
+  return {
+    ok: report.passed,
+    summary: {
+      passed: report.passed,
+      errors: report.hardErrorCount,
+      warnings: report.warningCount,
+    },
+    report,
+    markdown: formatArtifactQAReport(report),
+  }
+}
+
+export async function exportPdf(input: RuntimeFileInput) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const filePath = resolve(workspaceRoot, input.file)
+  await assertExportQAPassed(filePath, { workspaceRoot })
+  const result = await exportToPdf(filePath)
+  recordRenderedArtifact(workspaceRoot, {
+    sourceHtmlPath: workspaceRelative(resolve(workspaceRoot), filePath),
+    outputPath: result.outputPath,
+    type: "pdf",
+    actor: "revela-codex-mcp",
+  })
+  return { ok: true, ...result }
+}
+
+export async function exportPptx(input: RuntimeFileInput & { speakerNotes?: Array<string | null | undefined> }) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const filePath = resolve(workspaceRoot, input.file)
+  await assertExportQAPassed(filePath, { workspaceRoot })
+  const result = await exportToPptx(filePath, { speakerNotes: input.speakerNotes })
+  recordRenderedArtifact(workspaceRoot, {
+    sourceHtmlPath: workspaceRelative(resolve(workspaceRoot), filePath),
+    outputPath: result.outputPath,
+    type: "pptx",
+    actor: "revela-codex-mcp",
+  })
+  return { ok: true, ...result }
+}
+
+export function designList() {
+  seedBuiltinDesigns()
+  return {
+    ok: true,
+    activeDesign: activeDesign(),
+    designs: listDesigns({ includeInternal: false }).map((design) => ({
+      name: design.name,
+      description: design.description,
+      author: design.author,
+      version: design.version,
+    })),
+  }
+}
+
+export function designRead(input: RuntimeDesignReadInput = {}) {
+  seedBuiltinDesigns()
+  const name = input.name || activeDesign()
+  return {
+    ok: true,
+    name,
+    markdown: getDesignSkillMd(name),
+  }
+}
+
+export function designActivate(input: RuntimeNameInput) {
+  seedBuiltinDesigns()
+  activateDesign(requiredName(input, "design"))
+  return {
+    ok: true,
+    activeDesign: activeDesign(),
+  }
+}
+
+export function domainList() {
+  seedBuiltinDomains()
+  return {
+    ok: true,
+    activeDomain: activeDomain(),
+    domains: listDomains().map((domain) => ({
+      name: domain.name,
+      description: domain.description,
+      author: domain.author,
+      version: domain.version,
+    })),
+  }
+}
+
+export function domainRead(input: RuntimeDesignReadInput = {}) {
+  seedBuiltinDomains()
+  const name = input.name || activeDomain()
+  return {
+    ok: true,
+    name,
+    markdown: getDomainSkillMd(name),
+  }
+}
+
+export function domainActivate(input: RuntimeNameInput) {
+  seedBuiltinDomains()
+  activateDomain(requiredName(input, "domain"))
+  return {
+    ok: true,
+    activeDomain: activeDomain(),
+  }
+}
+
+function root(workspaceRoot: string | undefined): string {
+  return resolve(workspaceRoot || process.cwd())
+}
+
+function safe<T>(fn: () => T): T | undefined {
+  try {
+    return fn()
+  } catch {
+    return undefined
+  }
+}
+
+function requiredName(input: RuntimeNameInput, label: string): string {
+  const name = input?.name?.trim()
+  if (!name) throw new Error(`${label} name is required`)
+  return name
+}

package/lib/runtime/research.ts

@@ -0,0 +1,175 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { join, resolve } from "path"
+import { DECKS_STATE_FILE, hasDecksState, readDecksState, readOrCreateDecksState, writeDecksState, type DecksState } from "../decks-state"
+import { stableEvidenceId } from "../narrative-state/hash"
+import { evaluateResearchFindingsBinding } from "../narrative-state/research-binding-eval"
+import { deriveResearchTargets } from "../narrative-state/research-gaps"
+import { compileCacheMirrorNarrativeVault } from "../narrative-vault/compile-mirror"
+import { compileNarrativeVault, formatVaultDiagnosticReport, hasNarrativeVault, updateVaultResearchGapNode, upsertVaultEvidenceNode } from "../narrative-vault"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+
+export interface ResearchSaveInput {
+  topic: string
+  filename: string
+  content: string
+  sources?: string[]
+  workspaceRoot?: string
+}
+
+export interface ResearchFindingsInput {
+  findingsFile: string
+  workspaceRoot?: string
+}
+
+export interface BindResearchFindingsInput extends ResearchFindingsInput {
+  evidenceId?: string
+}
+
+export function researchTargets(input: { workspaceRoot?: string } = {}) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const state = readOrCreateDecksState(workspaceRoot)
+  return { ok: true, path: DECKS_STATE_FILE, result: deriveResearchTargets(state, { workspaceRoot }) }
+}
+
+export function researchSave(input: ResearchSaveInput) {
+  const workspaceRoot = root(input.workspaceRoot)
+  const topicKey = keyify(input.topic || "research")
+  const fileKey = keyify(input.filename || "findings")
+  const topicDir = join(workspaceRoot, "researches", topicKey)
+  const sources = input.sources ?? []
+
+  mkdirSync(topicDir, { recursive: true })
+  const relPath = `researches/${topicKey}/${fileKey}.md`
+  writeFileSync(join(topicDir, `${fileKey}.md`), `${buildFrontmatter(input.topic, fileKey, sources)}\n\n${input.content ?? ""}\n`, "utf-8")
+
+  if (!hasDecksState(workspaceRoot)) return { ok: true, path: relPath }
+
+  const state = readDecksState(workspaceRoot)
+  recordWorkspaceAction(state, {
+    type: "research.findings_saved",
+    actor: "revela-research-save",
+    inputs: { topic: topicKey, axis: fileKey, sourceCount: sources.length },
+    outputs: { path: relPath, sources },
+    summary: `Saved research findings for ${topicKey}/${fileKey}.`,
+    nodeIds: [`finding:${relPath}`],
+  })
+  const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, relPath)
+  writeDecksState(workspaceRoot, state)
+  return { ok: true, path: relPath, bindingEval }
+}
+
+export function evaluateResearchFindings(input: ResearchFindingsInput) {
+  const workspaceRoot = root(input.workspaceRoot)
+  if (!input.findingsFile?.trim()) return { ok: false, error: "findingsFile is required for evaluateResearchFindings" }
+  const state = readOrCreateDecksState(workspaceRoot)
+  const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, input.findingsFile)
+  const targets = deriveResearchTargets(state, { workspaceRoot })
+  const vaultDiagnostics = hasNarrativeVault(workspaceRoot)
+    ? formatVaultDiagnosticReport(compileNarrativeVault(workspaceRoot, { fallbackApprovals: state.narrative?.approvals ?? [] }).diagnostics)
+    : undefined
+  return { ok: true, path: DECKS_STATE_FILE, result: { bindingEval, selected: targets.selected, vaultDiagnostics } }
+}
+
+export function bindResearchFindings(input: BindResearchFindingsInput) {
+  const workspaceRoot = root(input.workspaceRoot)
+  if (!hasNarrativeVault(workspaceRoot)) return { ok: false, error: "bindResearchFindings requires revela-narrative/ to exist. Use initNarrativeVault first, then evaluateResearchFindings." }
+  if (!input.findingsFile?.trim()) return { ok: false, error: "findingsFile is required for bindResearchFindings" }
+
+  const state = readOrCreateDecksState(workspaceRoot)
+  const bindingEval = evaluateResearchFindingsBinding(state, workspaceRoot, input.findingsFile)
+  if (bindingEval.status !== "bindable" || !bindingEval.claimId || !bindingEval.recommendedEvidenceDraft) {
+    return { ok: false, skipped: true, reason: "findings are not safely bindable", bindingEval }
+  }
+
+  const draft = bindingEval.recommendedEvidenceDraft
+  const evidence = {
+    id: input.evidenceId?.trim() || stableEvidenceId(bindingEval.claimId, `${bindingEval.findingsFile}:${draft.quote ?? ""}`),
+    claimId: bindingEval.claimId,
+    source: draft.source,
+    sourcePath: draft.sourcePath,
+    findingsFile: draft.findingsFile ?? bindingEval.findingsFile,
+    quote: draft.quote,
+    location: draft.location,
+    url: draft.url,
+    caveat: draft.caveat,
+    supportScope: draft.supportScope,
+    unsupportedScope: draft.unsupportedScope,
+    strength: draft.strength,
+  }
+  const missing = missingBindableEvidenceFields(evidence)
+  if (missing.length > 0) return { ok: false, skipped: true, reason: "recommended evidence draft is incomplete", missingFields: missing, bindingEval }
+
+  const mutation = upsertVaultEvidenceNode(workspaceRoot, evidence as any)
+  if (!mutation.ok) return { ok: false, mutation, bindingEval }
+
+  const gap = exactResearchGapForBinding(state, bindingEval.findingsFile, bindingEval.claimId)
+  const gapMutation = gap
+    ? updateVaultResearchGapNode(workspaceRoot, {
+      id: gap.id,
+      status: "evidence_bound",
+      findingsFile: bindingEval.findingsFile,
+      evidenceBindingIds: [...new Set([...(gap.evidenceBindingIds ?? []), evidence.id])],
+      notes: gap.notes,
+    })
+    : undefined
+  const compiled = compileCacheMirrorNarrativeVault(workspaceRoot)
+  return {
+    ok: compiled.result.ok,
+    path: mutation.file,
+    bindingEval,
+    mutation,
+    gapMutation: gapMutation ?? { ok: true, skipped: true, reason: "no exact single research gap matched this findings file and claim" },
+    evidence,
+    diagnostics: compiled.result.diagnostics,
+    diagnosticReport: compiled.diagnosticReport,
+    narrative: compiled.result.narrative,
+  }
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+function keyify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function buildFrontmatter(topic: string, axis: string, sources: string[]): string {
+  const lines = [
+    "---",
+    `topic: ${topic}`,
+    `axis: ${axis}`,
+    `date: ${today()}`,
+  ]
+  if (sources.length > 0) {
+    lines.push("sources:")
+    for (const source of sources) lines.push(`  - "${source.replace(/"/g, '\\"')}"`)
+  }
+  lines.push("---")
+  return lines.join("\n")
+}
+
+function missingBindableEvidenceFields(input: Record<string, unknown>): string[] {
+  const missing: string[] = []
+  for (const key of ["id", "claimId", "source", "quote", "supportScope", "unsupportedScope", "caveat", "strength"] as const) {
+    if (!String(input[key] ?? "").trim()) missing.push(key)
+  }
+  if (!String(input.sourcePath ?? "").trim() && !String(input.url ?? "").trim() && !String(input.findingsFile ?? "").trim()) missing.push("sourcePath|url|findingsFile")
+  return missing
+}
+
+function exactResearchGapForBinding(state: DecksState, findingsFile: string, claimId: string) {
+  const gaps = state.narrative?.researchGaps ?? []
+  const exact = gaps.filter((gap) => gap.targetType === "claim" && gap.targetId === claimId && gap.findingsFile === findingsFile)
+  if (exact.length === 1) return exact[0]
+  if (exact.length > 1) return undefined
+  const byClaim = gaps.filter((gap) => gap.targetType === "claim" && gap.targetId === claimId && !gap.findingsFile)
+  return byClaim.length === 1 ? byClaim[0] : undefined
+}
+
+function root(workspaceRoot: string | undefined): string {
+  return resolve(workspaceRoot || process.cwd())
+}

package/lib/runtime/review.ts

@@ -0,0 +1,270 @@
+import { existsSync } from "fs"
+import { resolve } from "path"
+import { DECKS_STATE_FILE, hasDecksState, normalizeWorkspaceDeckState, readDecksState } from "../decks-state"
+import { extractDesignClasses } from "../design/designs"
+import { compileInspectionContext, type InspectionContext } from "../inspection-context/compile"
+import { computeNarrativeHash } from "../narrative-state/hash"
+import { readDeckPlanArtifact } from "../narrative-state/deck-plan-artifact"
+import { compileNarrativeVault } from "../narrative-vault/compile"
+import { formatVaultDiagnosticMarkdown, formatVaultDiagnosticReport } from "../narrative-vault/diagnostic-report"
+import { formatArtifactQAReport, runArtifactQA } from "../qa/artifact"
+import { openRefineDeck } from "../refine/open"
+import { createCodexExecReviewPromptBridge } from "../refine/prompt-bridge"
+import { workspaceRelative } from "../workspace-state/rendered-artifacts"
+
+export interface ReviewDeckReadInput {
+  workspaceRoot?: string
+  file: string
+  format?: "json" | "markdown"
+}
+
+export interface ReviewDeckOpenInput extends ReviewDeckReadInput {
+  bridge?: "codex-exec"
+  openBrowser?: boolean
+  openUrl?: (url: string) => void
+}
+
+export interface ReviewDeckInspectionContextResult {
+  ok: boolean
+  skipped: boolean
+  reason?: string
+  context?: InspectionContext
+}
+
+export async function reviewDeckRead(input: ReviewDeckReadInput): Promise<any> {
+  const workspaceRoot = root(input.workspaceRoot)
+  const requestedFile = input.file?.trim()
+  if (!requestedFile) {
+    return {
+      ok: false,
+      file: "",
+      error: "Missing required file.",
+      diagnostics: [{ severity: "error", code: "missing_file", message: "Provide a workspace-relative or absolute deck HTML file." }],
+    }
+  }
+
+  const filePath = resolve(workspaceRoot, requestedFile)
+  const file = workspaceRelative(workspaceRoot, filePath)
+  if (!existsSync(filePath)) {
+    return {
+      ok: false,
+      file,
+      error: `Deck HTML file not found: ${file}`,
+      diagnostics: [{ severity: "error", code: "file_not_found", message: `Deck HTML file not found: ${file}` }],
+    }
+  }
+
+  const artifactQa = await readArtifactQa(workspaceRoot, filePath)
+  const narrativeRead = readNarrative(workspaceRoot)
+  const deckPlan = readDeckPlan(workspaceRoot, narrativeRead.knownNodeIds, narrativeRead.narrativeHash)
+  const { knownNodeIds: _knownNodeIds, ...narrative } = narrativeRead
+  const inspectionContext = readInspectionContext(workspaceRoot, file)
+  const diagnostics = {
+    artifactQa: artifactQa.summary,
+    deckPlan: summarizeDeckPlan(deckPlan),
+    narrative: narrative.summary,
+    inspectionContext: inspectionContext.ok
+      ? { ok: true, skipped: false }
+      : { ok: false, skipped: true, reason: inspectionContext.reason },
+  }
+  const markdown = input.format === "markdown"
+    ? formatReviewDeckReadMarkdown({ file, artifactQa, deckPlan, narrative, inspectionContext })
+    : undefined
+
+  return {
+    ok: artifactQa.ok,
+    file,
+    artifactQa,
+    deckPlan,
+    narrative,
+    diagnostics,
+    inspectionContext,
+    artifactCoverage: inspectionContext.context?.artifactCoverage ?? [],
+    evidenceTrace: inspectionContext.context?.slides.flatMap((slide) => slide.evidence) ?? narrative.evidenceTrace,
+    markdown,
+  }
+}
+
+export async function reviewDeckOpen(input: ReviewDeckOpenInput): Promise<any> {
+  const workspaceRoot = root(input.workspaceRoot)
+  const requestedFile = input.file?.trim()
+  if (!requestedFile) {
+    return {
+      ok: false,
+      file: "",
+      error: "Missing required file.",
+      diagnostics: [{ severity: "error", code: "missing_file", message: "Provide a workspace-relative or absolute deck HTML file." }],
+    }
+  }
+
+  try {
+    const opened = openRefineDeck(requestedFile, {
+      workspaceRoot,
+      mode: "edit",
+      openBrowser: input.openBrowser,
+      openUrl: input.openUrl,
+      sessionID: `codex-review:${requestedFile}`,
+      promptBridge: createCodexExecReviewPromptBridge(),
+    })
+    return {
+      ok: true,
+      file: opened.deck.file,
+      deck: {
+        slug: opened.deck.slug,
+        file: opened.deck.file,
+        source: opened.deck.source,
+      },
+      bridge: input.bridge ?? "codex-exec",
+      url: opened.url,
+      token: new URL(opened.url).searchParams.get("token"),
+      mode: opened.mode,
+      openedBrowser: opened.openedBrowser,
+      reusedSession: opened.reusedSession,
+      liveSession: opened.liveSession,
+      source: opened.source,
+      stateNote: opened.stateNote,
+      preflightChanged: opened.preflightChanged,
+    }
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e)
+    return {
+      ok: false,
+      file: requestedFile,
+      bridge: input.bridge ?? "codex-exec",
+      error: message,
+      diagnostics: [{ severity: "error", code: "review_open_failed", message }],
+    }
+  }
+}
+
+async function readArtifactQa(workspaceRoot: string, filePath: string) {
+  let vocabulary
+  try {
+    vocabulary = extractDesignClasses()
+  } catch {
+    // Design vocabulary is optional for standalone artifacts.
+  }
+  const report = await runArtifactQA({ workspaceRoot, filePath, vocabulary })
+  return {
+    ok: report.passed,
+    summary: {
+      passed: report.passed,
+      errors: report.hardErrorCount,
+      warnings: report.warningCount,
+    },
+    report,
+    markdown: formatArtifactQAReport(report),
+  }
+}
+
+function readNarrative(workspaceRoot: string): any {
+  if (!existsSync(resolve(workspaceRoot, "revela-narrative"))) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: "No revela-narrative/ vault exists; narrative diagnostics skipped.",
+      summary: { ok: false, skipped: true, reason: "No revela-narrative/ vault exists; narrative diagnostics skipped." },
+      evidenceTrace: [],
+    }
+  }
+
+  const compiled = compileNarrativeVault(workspaceRoot)
+  const report = formatVaultDiagnosticReport(compiled.diagnostics)
+  const narrative = compiled.narrative
+  return {
+    ok: compiled.ok,
+    skipped: false,
+    narrativeHash: narrative ? computeNarrativeHash(narrative) : undefined,
+    summary: report,
+    diagnostics: compiled.diagnostics,
+    diagnosticsMarkdown: formatVaultDiagnosticMarkdown(report),
+    evidenceTrace: narrative?.evidenceBindings.map((binding) => ({
+      id: binding.id,
+      claimId: binding.claimId,
+      source: binding.source,
+      sourcePath: binding.sourcePath,
+      findingsFile: binding.findingsFile,
+      quote: binding.quote,
+      location: binding.location,
+      url: binding.url,
+      supportScope: binding.supportScope,
+      unsupportedScope: binding.unsupportedScope,
+      caveat: binding.caveat,
+      strength: binding.strength,
+    })) ?? [],
+    knownNodeIds: compiled.graph ? new Set(compiled.graph.nodes.map((node) => node.id)) : undefined,
+  }
+}
+
+function readDeckPlan(workspaceRoot: string, knownNodeIds: Set<string> | undefined, narrativeHash: string | undefined) {
+  return readDeckPlanArtifact(workspaceRoot, { knownNodeIds, narrativeHash })
+}
+
+function readInspectionContext(workspaceRoot: string, file: string): ReviewDeckInspectionContextResult {
+  if (!hasDecksState(workspaceRoot)) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: `No ${DECKS_STATE_FILE} exists; legacy inspection context skipped for file-native deck.`,
+    }
+  }
+
+  try {
+    const state = normalizeWorkspaceDeckState(readDecksState(workspaceRoot), workspaceRoot)
+    const slug = Object.entries(state.decks).find(([, deck]) => normalizePath(deck.outputPath) === normalizePath(file))?.[0]
+    if (!slug) {
+      return {
+        ok: false,
+        skipped: true,
+        reason: `No ${DECKS_STATE_FILE} deck outputPath matches ${file}; legacy inspection context skipped.`,
+      }
+    }
+    return { ok: true, skipped: false, context: compileInspectionContext(state, slug) }
+  } catch (e) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: `Could not compile legacy inspection context: ${e instanceof Error ? e.message : String(e)}`,
+    }
+  }
+}
+
+function summarizeDeckPlan(deckPlan: ReturnType<typeof readDeckPlanArtifact>) {
+  return {
+    ok: deckPlan.ok,
+    skipped: !deckPlan.ok && Boolean(deckPlan.reason?.includes("missing")),
+    warnings: deckPlan.warnings?.length ?? 0,
+    reason: deckPlan.reason,
+  }
+}
+
+function formatReviewDeckReadMarkdown(input: {
+  file: string
+  artifactQa: Awaited<ReturnType<typeof readArtifactQa>>
+  deckPlan: ReturnType<typeof readDeckPlanArtifact>
+  narrative: ReturnType<typeof readNarrative>
+  inspectionContext: ReviewDeckInspectionContextResult
+}): string {
+  const lines = [
+    "# Review Deck Read",
+    "",
+    `File: \`${input.file}\``,
+    "",
+    `Artifact QA: ${input.artifactQa.summary.passed ? "passed" : "failed"} (${input.artifactQa.summary.errors} hard error(s), ${input.artifactQa.summary.warnings} warning(s))`,
+    `Deck-plan: ${input.deckPlan.ok ? "read" : `skipped/diagnostic - ${input.deckPlan.reason ?? "not available"}`}`,
+    `Narrative: ${input.narrative.skipped ? input.narrative.reason : input.narrative.summary.summary}`,
+    `Inspection context: ${input.inspectionContext.ok ? "read" : `skipped - ${input.inspectionContext.reason}`}`,
+    "",
+    input.artifactQa.markdown,
+  ]
+  if (!input.narrative.skipped && input.narrative.diagnosticsMarkdown) lines.push("", input.narrative.diagnosticsMarkdown)
+  return lines.join("\n")
+}
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/g, "/").replace(/^\.\/+/, "")
+}
+
+function root(workspaceRoot: string | undefined): string {
+  return resolve(workspaceRoot || process.cwd())
+}