@cyber-dash-tech/revela 0.16.4 → 0.17.1

package/lib/narrative-vault/inventory.ts

@@ -0,0 +1,392 @@
+import { readNarrativeVaultDocuments } from "./read"
+import { stableVaultRelationId } from "./relations"
+import type { NarrativeClaimRelationType } from "../narrative-state/types"
+import type { VaultDiagnostic, VaultDocument, VaultNodeType, VaultRelation } from "./types"
+
+export interface NarrativeVaultInventoryNode {
+  id: string
+  type: VaultNodeType
+  file: string
+  title: string
+  text: string
+}
+
+export interface NarrativeVaultInventoryClaim extends NarrativeVaultInventoryNode {
+  kind: string
+  importance: string
+  evidenceRequired: boolean
+  evidenceStatus: string
+}
+
+export interface NarrativeVaultInventoryEvidence extends NarrativeVaultInventoryNode {
+  claimId: string
+  source: string
+  sourcePath: string
+  url: string
+  findingsFile: string
+  strength: string
+  quote: string
+}
+
+export interface NarrativeVaultInventoryResearchGap extends NarrativeVaultInventoryNode {
+  targetType: string
+  targetId: string
+  question: string
+  status: string
+  priority: string
+  findingsFile: string
+}
+
+export interface NarrativeVaultInventoryObjection extends NarrativeVaultInventoryNode {
+  claimId: string
+  priority: string
+}
+
+export interface NarrativeVaultInventoryRisk extends NarrativeVaultInventoryNode {
+  claimId: string
+  severity: string
+}
+
+export interface NarrativeVaultInventoryRelation extends VaultRelation {
+  unresolved: boolean
+}
+
+export interface NarrativeVaultRelationCandidate {
+  id: string
+  fromId: string
+  toId: string
+  relation: NarrativeClaimRelationType
+  rationale: string
+  source: "frontmatter"
+}
+
+export interface NarrativeVaultRelationCoverage {
+  danglingEdges: NarrativeVaultInventoryRelation[]
+  unboundEvidence: string[]
+  unboundObjections: string[]
+  unboundRisks: string[]
+  unboundResearchGaps: string[]
+  fallbackOnlyBindings: Array<{ nodeId: string; file: string; field: string; relation: NarrativeClaimRelationType; targetId: string }>
+  isolatedClaims: string[]
+  orphanNodes: string[]
+  inlineRelations: Array<{ file: string; nodeId: string }>
+}
+
+export interface NarrativeVaultInventoryUnresolvedRef {
+  kind: "relation" | "evidenceClaimId" | "gapTarget" | "objectionClaimId" | "riskClaimId"
+  fromId: string
+  targetId: string
+  file: string
+  field?: string
+}
+
+export interface NarrativeVaultInventory {
+  ok: boolean
+  path: "revela-narrative"
+  counts: {
+    claims: number
+    evidence: number
+    researchGaps: number
+    objections: number
+    risks: number
+    relations: number
+    unresolvedRefs: number
+  }
+  claims: NarrativeVaultInventoryClaim[]
+  evidence: NarrativeVaultInventoryEvidence[]
+  researchGaps: NarrativeVaultInventoryResearchGap[]
+  objections: NarrativeVaultInventoryObjection[]
+  risks: NarrativeVaultInventoryRisk[]
+  relations: NarrativeVaultInventoryRelation[]
+  relationCoverage: NarrativeVaultRelationCoverage
+  relationSummary: {
+    inlineEdges: number
+    advisoryCandidates: number
+  }
+  relationCandidates: NarrativeVaultRelationCandidate[]
+  unresolvedRefs: NarrativeVaultInventoryUnresolvedRef[]
+  idHints: {
+    nextClaimIdExamples: string[]
+    nextEvidenceIdExamples: string[]
+    nextResearchGapIdExamples: string[]
+  }
+  diagnostics: VaultDiagnostic[]
+}
+
+export function buildNarrativeVaultInventory(workspaceRoot: string): NarrativeVaultInventory {
+  const { documents, diagnostics } = readNarrativeVaultDocuments(workspaceRoot)
+  const ids = new Set(documents.map((doc) => nodeId(doc)).filter(Boolean))
+  const claimIds = new Set(documents.filter((doc) => nodeType(doc) === "claim").map((doc) => nodeId(doc)).filter(Boolean))
+  const unresolvedRefs: NarrativeVaultInventoryUnresolvedRef[] = []
+  const relations: NarrativeVaultInventoryRelation[] = []
+
+  for (const doc of documents) {
+    const fromId = nodeId(doc)
+    for (const relation of doc.relations) {
+      const unresolved = !ids.has(relation.toId)
+      relations.push({ ...relation, unresolved })
+      if (unresolved) unresolvedRefs.push({ kind: "relation", fromId, targetId: relation.toId, file: relation.file })
+    }
+  }
+
+  const claims: NarrativeVaultInventoryClaim[] = []
+  const evidence: NarrativeVaultInventoryEvidence[] = []
+  const researchGaps: NarrativeVaultInventoryResearchGap[] = []
+  const objections: NarrativeVaultInventoryObjection[] = []
+  const risks: NarrativeVaultInventoryRisk[] = []
+
+  for (const doc of documents) {
+    const id = nodeId(doc)
+    const type = nodeType(doc)
+    if (!id || !type) continue
+    const base = baseNode(doc, id, type)
+    if (type === "claim") {
+      claims.push({
+        ...base,
+        kind: stringField(doc, "kind"),
+        importance: stringField(doc, "importance"),
+        evidenceRequired: booleanField(doc, "evidenceRequired"),
+        evidenceStatus: stringField(doc, "evidenceStatus"),
+      })
+      continue
+    }
+    if (type === "evidence") {
+      const claimId = stringField(doc, "claimId")
+      const inlineClaimId = relationTargetFor(relations, id, "supports", claimIds)
+      if (!claimId && !inlineClaimId) unresolvedRefs.push({ kind: "evidenceClaimId", fromId: id, targetId: claimId, file: doc.relativePath, field: "claimId" })
+      else if (claimId && !claimIds.has(claimId)) unresolvedRefs.push({ kind: "evidenceClaimId", fromId: id, targetId: claimId, file: doc.relativePath, field: "claimId" })
+      evidence.push({
+        ...base,
+        claimId: inlineClaimId || claimId,
+        source: stringField(doc, "source"),
+        sourcePath: stringField(doc, "sourcePath"),
+        url: stringField(doc, "url"),
+        findingsFile: stringField(doc, "findingsFile"),
+        strength: stringField(doc, "strength"),
+        quote: firstText(stringField(doc, "quote") || doc.body),
+      })
+      continue
+    }
+    if (type === "research-gap") {
+      const targetType = stringField(doc, "targetType")
+      const targetId = stringField(doc, "targetId")
+      const inlineTargetId = relationTargetFor(relations, id, "depends_on", ids)
+      if (targetId && !isLooseTargetType(targetType) && !ids.has(targetId)) unresolvedRefs.push({ kind: "gapTarget", fromId: id, targetId, file: doc.relativePath, field: "targetId" })
+      researchGaps.push({
+        ...base,
+        targetType,
+        targetId: inlineTargetId || targetId,
+        question: stringField(doc, "question") || firstText(doc.body),
+        status: stringField(doc, "status"),
+        priority: stringField(doc, "priority"),
+        findingsFile: stringField(doc, "findingsFile"),
+      })
+      continue
+    }
+    if (type === "objection") {
+      const claimId = stringField(doc, "claimId")
+      const inlineClaimId = relationTargetFor(relations, id, "answers", claimIds) || relationTargetFor(relations, id, "contrasts_with", claimIds)
+      if (!claimId && !inlineClaimId) unresolvedRefs.push({ kind: "objectionClaimId", fromId: id, targetId: claimId, file: doc.relativePath, field: "claimId" })
+      else if (claimId && !claimIds.has(claimId)) unresolvedRefs.push({ kind: "objectionClaimId", fromId: id, targetId: claimId, file: doc.relativePath, field: "claimId" })
+      objections.push({ ...base, claimId: inlineClaimId || claimId, priority: stringField(doc, "priority") })
+      continue
+    }
+    if (type === "risk") {
+      const claimId = stringField(doc, "claimId")
+      const inlineClaimId = relationTargetFor(relations, id, "constrains", claimIds)
+      if (!claimId && !inlineClaimId) unresolvedRefs.push({ kind: "riskClaimId", fromId: id, targetId: claimId, file: doc.relativePath, field: "claimId" })
+      else if (claimId && !claimIds.has(claimId)) unresolvedRefs.push({ kind: "riskClaimId", fromId: id, targetId: claimId, file: doc.relativePath, field: "claimId" })
+      risks.push({ ...base, claimId: inlineClaimId || claimId, severity: stringField(doc, "severity") })
+    }
+  }
+
+  const ok = diagnostics.every((diagnostic) => diagnostic.severity !== "error") && unresolvedRefs.length === 0
+  const relationCoverage = buildRelationCoverage(documents, claims, evidence, objections, risks, researchGaps, relations, ids)
+  const relationCandidates = buildRelationCandidates(documents, relations, ids)
+  return {
+    ok,
+    path: "revela-narrative",
+    counts: {
+      claims: claims.length,
+      evidence: evidence.length,
+      researchGaps: researchGaps.length,
+      objections: objections.length,
+      risks: risks.length,
+      relations: relations.length,
+      unresolvedRefs: unresolvedRefs.length,
+    },
+    claims,
+    evidence,
+    researchGaps,
+    objections,
+    risks,
+    relations,
+    relationCoverage,
+    relationSummary: {
+      inlineEdges: relations.length,
+      advisoryCandidates: relationCandidates.length,
+    },
+    relationCandidates,
+    unresolvedRefs,
+    idHints: buildIdHints(ids),
+    diagnostics,
+  }
+}
+
+function buildRelationCandidates(documents: VaultDocument[], relations: NarrativeVaultInventoryRelation[], ids: Set<string>): NarrativeVaultRelationCandidate[] {
+  const candidates: NarrativeVaultRelationCandidate[] = []
+  const addCandidate = (candidate: NarrativeVaultRelationCandidate) => {
+    if (!ids.has(candidate.fromId) || !ids.has(candidate.toId)) return
+    if (relations.some((edge) => edge.fromId === candidate.fromId && edge.toId === candidate.toId && edge.relation === candidate.relation)) return
+    if (candidates.some((edge) => edge.fromId === candidate.fromId && edge.toId === candidate.toId && edge.relation === candidate.relation)) return
+    candidates.push(candidate)
+  }
+
+  for (const doc of documents) {
+    const id = nodeId(doc)
+    const type = nodeType(doc)
+    if (!id || !type) continue
+    if (type === "evidence") {
+      addFrontmatterCandidate(doc, id, "claimId", "supports", "Evidence frontmatter points at this claim.", addCandidate)
+    } else if (type === "objection") {
+      addFrontmatterCandidate(doc, id, "claimId", "answers", "Objection frontmatter points at this claim.", addCandidate)
+    } else if (type === "risk") {
+      addFrontmatterCandidate(doc, id, "claimId", "constrains", "Risk frontmatter points at this claim.", addCandidate)
+    } else if (type === "research-gap") {
+      addFrontmatterCandidate(doc, id, "targetId", "depends_on", "Research gap frontmatter points at this target.", addCandidate)
+    }
+  }
+
+  return candidates.sort((a, b) => a.id.localeCompare(b.id))
+}
+
+function addFrontmatterCandidate(
+  doc: VaultDocument,
+  fromId: string,
+  targetField: string,
+  relation: NarrativeClaimRelationType,
+  rationale: string,
+  addCandidate: (candidate: NarrativeVaultRelationCandidate) => void,
+): void {
+  const toId = stringField(doc, targetField)
+  if (!toId) return
+  addCandidate({ id: candidateRelationId(fromId, relation, toId), fromId, toId, relation, rationale, source: "frontmatter" })
+}
+
+function candidateRelationId(fromId: string, relation: NarrativeClaimRelationType, toId: string): string {
+  return stableVaultRelationId(fromId, relation, toId)
+}
+
+function buildRelationCoverage(
+  documents: VaultDocument[],
+  claims: NarrativeVaultInventoryClaim[],
+  evidence: NarrativeVaultInventoryEvidence[],
+  objections: NarrativeVaultInventoryObjection[],
+  risks: NarrativeVaultInventoryRisk[],
+  researchGaps: NarrativeVaultInventoryResearchGap[],
+  relations: NarrativeVaultInventoryRelation[],
+  ids: Set<string>,
+): NarrativeVaultRelationCoverage {
+  const connected = new Set<string>()
+  for (const relation of relations) {
+    if (ids.has(relation.fromId)) connected.add(relation.fromId)
+    if (ids.has(relation.toId)) connected.add(relation.toId)
+  }
+  const relationToClaim = (id: string, relation: string) => relations.some((edge) => edge.fromId === id && edge.relation === relation && claims.some((claim) => claim.id === edge.toId))
+  const claimLinked = (id: string) => relations.some((edge) => (edge.fromId === id && claims.some((claim) => claim.id === edge.toId)) || (edge.toId === id && claims.some((claim) => claim.id === edge.fromId)))
+  const fallbackOnlyBindings = buildFallbackOnlyBindings(documents, relations, ids)
+  return {
+    danglingEdges: relations.filter((relation) => relation.unresolved),
+    unboundEvidence: evidence.filter((item) => !item.claimId && !relationToClaim(item.id, "supports")).map((item) => item.id),
+    unboundObjections: objections.filter((item) => !item.claimId && !relationToClaim(item.id, "answers") && !relationToClaim(item.id, "contrasts_with")).map((item) => item.id),
+    unboundRisks: risks.filter((item) => !item.claimId && !relationToClaim(item.id, "constrains")).map((item) => item.id),
+    unboundResearchGaps: researchGaps.filter((item) => !item.targetId && !relations.some((edge) => edge.fromId === item.id)).map((item) => item.id),
+    fallbackOnlyBindings,
+    isolatedClaims: claims.filter((claim) => claim.importance === "central" && claims.length > 1 && !claimLinked(claim.id)).map((claim) => claim.id),
+    orphanNodes: [...claims, ...evidence, ...objections, ...risks, ...researchGaps].filter((item) => !connected.has(item.id)).map((item) => item.id),
+    inlineRelations: documents.filter((doc) => doc.relations.length > 0).map((doc) => ({ file: doc.relativePath, nodeId: nodeId(doc) })),
+  }
+}
+
+function buildFallbackOnlyBindings(documents: VaultDocument[], relations: NarrativeVaultInventoryRelation[], ids: Set<string>): NarrativeVaultRelationCoverage["fallbackOnlyBindings"] {
+  const items: NarrativeVaultRelationCoverage["fallbackOnlyBindings"] = []
+  const add = (doc: VaultDocument, field: string, relation: NarrativeClaimRelationType) => {
+    const node = nodeId(doc)
+    const targetId = stringField(doc, field)
+    if (!node || !targetId || !ids.has(targetId)) return
+    if (relations.some((edge) => edge.fromId === node && edge.toId === targetId && edge.relation === relation)) return
+    items.push({ nodeId: node, file: doc.relativePath, field, relation, targetId })
+  }
+  for (const doc of documents) {
+    const type = nodeType(doc)
+    if (type === "evidence") add(doc, "claimId", "supports")
+    else if (type === "objection") add(doc, "claimId", "answers")
+    else if (type === "risk") add(doc, "claimId", "constrains")
+    else if (type === "research-gap") add(doc, "targetId", "depends_on")
+  }
+  return items
+}
+
+function relationTargetFor(relations: NarrativeVaultInventoryRelation[], fromId: string, relation: string, targetIds: Set<string>): string {
+  return relations.find((edge) => edge.fromId === fromId && edge.relation === relation && targetIds.has(edge.toId))?.toId ?? ""
+}
+
+function baseNode(doc: VaultDocument, id: string, type: VaultNodeType): NarrativeVaultInventoryNode {
+  return {
+    id,
+    type,
+    file: doc.relativePath,
+    title: stringField(doc, "title"),
+    text: firstText(doc.body),
+  }
+}
+
+function nodeId(doc: VaultDocument): string {
+  return stringField(doc, "id")
+}
+
+function nodeType(doc: VaultDocument): VaultNodeType | "" {
+  const type = stringField(doc, "type")
+  return isVaultNodeType(type) ? type : ""
+}
+
+function isVaultNodeType(type: string): type is VaultNodeType {
+  return ["index", "audience", "decision", "thesis", "claim", "evidence", "objection", "risk", "research-gap"].includes(type)
+}
+
+function stringField(doc: VaultDocument, key: string): string {
+  const value = doc.frontmatter[key]
+  return typeof value === "string" ? value.trim() : ""
+}
+
+function booleanField(doc: VaultDocument, key: string): boolean {
+  return doc.frontmatter[key] === true
+}
+
+function firstText(markdown: string): string {
+  return markdown
+    .split(/\n+/)
+    .map((line) => line.replace(/^#+\s+/, "").trim())
+    .find((line) => line && !line.startsWith("- ")) ?? ""
+}
+
+function isLooseTargetType(targetType: string): boolean {
+  return !targetType || targetType === "narrative" || targetType === "decision"
+}
+
+function buildIdHints(ids: Set<string>): NarrativeVaultInventory["idHints"] {
+  return {
+    nextClaimIdExamples: [nextAvailableId("claim-market-context", ids), nextAvailableId("claim-recommendation", ids)],
+    nextEvidenceIdExamples: [nextAvailableId("evidence-source-quote", ids), nextAvailableId("evidence-research-finding", ids)],
+    nextResearchGapIdExamples: [nextAvailableId("gap-market-size", ids), nextAvailableId("gap-source-validation", ids)],
+  }
+}
+
+function nextAvailableId(base: string, ids: Set<string>): string {
+  if (!ids.has(base)) return base
+  for (let index = 2; index < 100; index += 1) {
+    const candidate = `${base}-${index}`
+    if (!ids.has(candidate)) return candidate
+  }
+  return `${base}-${Date.now()}`
+}

package/lib/narrative-vault/markdown-qa.ts

@@ -0,0 +1,237 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs"
+import { join } from "path"
+import { readNarrativeVaultDocuments } from "./read"
+import { inspectVaultMarkdown } from "./authoring-guard"
+import { buildNarrativeVaultInventory, type NarrativeVaultInventoryUnresolvedRef } from "./inventory"
+import { narrativeVaultPath } from "./paths"
+import type { VaultDiagnosticDisplay } from "./diagnostic-report"
+import type { VaultDocument } from "./types"
+
+export interface MarkdownQaRepairCard {
+  severity: "error" | "warning"
+  file: string
+  nodeId?: string
+  issueCode: string
+  message: string
+  smallestRepair: string
+  examples?: string[]
+}
+
+export interface MarkdownQaReport {
+  ok: boolean
+  repairCards: MarkdownQaRepairCard[]
+  blockers: MarkdownQaRepairCard[]
+  warnings: MarkdownQaRepairCard[]
+}
+
+export interface MarkdownQaOptions {
+  touched?: string[]
+  scope?: "touched" | "affected" | "full"
+  strictness?: "authoring" | "readiness" | "render"
+}
+
+export function runNarrativeMarkdownQa(workspaceRoot: string, touchedOrOptions?: string[] | MarkdownQaOptions): MarkdownQaReport {
+  const options = Array.isArray(touchedOrOptions) ? { touched: touchedOrOptions, scope: "touched" as const, strictness: "authoring" as const } : touchedOrOptions ?? {}
+  const { documents } = readNarrativeVaultDocuments(workspaceRoot)
+  const scope = options.scope ?? (options.touched ? "touched" : "full")
+  const strictness = options.strictness ?? "authoring"
+  const touchedSet = options.touched ? new Set(options.touched.map(normalizeVaultFile).filter(Boolean)) : undefined
+  const selected = touchedSet ? documents.filter((doc) => touchedSet.has(doc.relativePath)) : documents
+  const inventory = buildNarrativeVaultInventory(workspaceRoot)
+  const repairCards: MarkdownQaRepairCard[] = []
+
+  for (const doc of selected) {
+    repairCards.push(...inspectVaultMarkdown(doc.relativePath, readFileSync(doc.path, "utf-8"))
+      .filter((diagnostic) => !isEvidenceClaimIdCoveredByInlineRelation(doc, diagnostic.code, inventory))
+      .map(cardFromDiagnostic))
+    repairCards.push(...evidenceTraceCards(doc))
+  }
+
+  repairCards.push(...unsupportedRootMarkdownCards(workspaceRoot, touchedSet))
+
+  for (const unresolved of inventory.unresolvedRefs) {
+    if (touchedSet && !touchedSet.has(unresolved.file)) continue
+    repairCards.push(cardFromUnresolved(unresolved))
+  }
+  for (const diagnostic of inventory.diagnostics) {
+    if (touchedSet && diagnostic.file && !touchedSet.has(diagnostic.file)) continue
+    repairCards.push(cardFromDiagnostic({
+      severity: diagnostic.severity,
+      code: diagnostic.code,
+      message: diagnostic.message,
+      file: diagnostic.file,
+      nodeId: diagnostic.nodeId,
+      suggestedFix: diagnostic.code === "unknown_relation_type" ? "Use one of: leads_to, supports, depends_on, contrasts_with, constrains, answers." : "Repair the Markdown node.",
+      suggestedAction: "Repair the Markdown relation line and rerun markdownQa.",
+    }))
+  }
+  if (scope !== "touched") repairCards.push(...relationCoverageCards(inventory, strictness))
+
+  const deduped = dedupeCards(repairCards)
+  const blockers = deduped.filter((card) => card.severity === "error")
+  const warnings = deduped.filter((card) => card.severity === "warning")
+  return { ok: blockers.length === 0, repairCards: deduped, blockers, warnings }
+}
+
+function isEvidenceClaimIdCoveredByInlineRelation(doc: VaultDocument, issueCode: string, inventory: ReturnType<typeof buildNarrativeVaultInventory>): boolean {
+  if (issueCode !== "evidence_claim_id_missing_authoring") return false
+  const id = stringField(doc, "id")
+  if (!id) return false
+  return inventory.relations.some((relation) => relation.fromId === id && relation.relation === "supports" && !relation.unresolved)
+}
+
+function relationCoverageCards(inventory: ReturnType<typeof buildNarrativeVaultInventory>, strictness: NonNullable<MarkdownQaOptions["strictness"]>): MarkdownQaRepairCard[] {
+  const cards: MarkdownQaRepairCard[] = []
+  const severity = strictness === "authoring" ? "warning" : "error"
+  for (const id of inventory.relationCoverage.unboundEvidence) cards.push(relationCoverageCard(severity, id, "unbound_evidence", "Evidence node has no claim-support relation.", "Add `## Relations` with `- supports: [[claim-id]]`, or bind the evidence through bindResearchFindings."))
+  for (const id of inventory.relationCoverage.unboundObjections) cards.push(relationCoverageCard(severity, id, "unbound_objection", "Objection node has no claim relation.", "Add `## Relations` with `- answers: [[claim-id]]` or `- contrasts_with: [[claim-id]]`, or set an explicit claim target if preserving existing shape."))
+  for (const id of inventory.relationCoverage.unboundRisks) cards.push(relationCoverageCard(severity, id, "unbound_risk", "Risk node has no claim relation.", "Add `## Relations` with `- constrains: [[claim-id]]`, or set an explicit claim target if preserving existing shape."))
+  for (const id of inventory.relationCoverage.unboundResearchGaps) cards.push(relationCoverageCard("warning", id, "unbound_research_gap", "Research gap has no target relation or target id.", "Add `## Relations` with `- depends_on: [[target-node-id]]` or a targetId after checking narrativeInventory."))
+  for (const item of inventory.relationCoverage.fallbackOnlyBindings) {
+    cards.push({
+      severity: "warning",
+      file: item.file,
+      nodeId: item.nodeId,
+      issueCode: "frontmatter_binding_without_relation",
+      message: `${item.field} is only expressed in frontmatter; wikilink-first vaults should express this graph edge in ## Relations.`,
+      smallestRepair: `Add \`## Relations\` with \`- ${item.relation}: [[${item.targetId}]]\`; keep frontmatter only as compatibility fallback if needed.`,
+    })
+  }
+  for (const id of inventory.relationCoverage.isolatedClaims) cards.push(relationCoverageCard(strictness === "render" ? "error" : "warning", id, "isolated_central_claim", "Central claim is not connected to the claim-flow graph.", "Add a claim-flow edge in the source node `## Relations`, or downgrade importance if it is background context."))
+  return cards
+}
+
+function relationCoverageCard(severity: "error" | "warning", nodeId: string, issueCode: string, message: string, smallestRepair: string): MarkdownQaRepairCard {
+  return { severity, file: "revela-narrative", nodeId, issueCode, message, smallestRepair }
+}
+
+function cardFromDiagnostic(diagnostic: VaultDiagnosticDisplay): MarkdownQaRepairCard {
+  return {
+    severity: diagnostic.severity,
+    file: diagnostic.file ?? "revela-narrative",
+    nodeId: diagnostic.nodeId,
+    issueCode: diagnostic.code,
+    message: diagnostic.message,
+    smallestRepair: diagnostic.suggestedFix || diagnostic.suggestedAction || "Repair the Markdown node and rerun markdownQa.",
+    examples: examplesFor(diagnostic.code),
+  }
+}
+
+function cardFromUnresolved(ref: NarrativeVaultInventoryUnresolvedRef): MarkdownQaRepairCard {
+  const target = ref.targetId || "<missing>"
+  if (ref.kind === "relation") {
+    return {
+      severity: "error",
+      file: ref.file,
+      nodeId: ref.fromId,
+      issueCode: "broken_relation_target",
+      message: `Relation points to unknown node ${target}.`,
+      smallestRepair: "Create the referenced node or patch the relation wikilink to an existing id from narrativeInventory.",
+      examples: ["- supports: [[claim-existing-id]]"],
+    }
+  }
+  if (ref.kind === "evidenceClaimId") {
+    return {
+      severity: "error",
+      file: ref.file,
+      nodeId: ref.fromId,
+      issueCode: ref.targetId ? "unresolved_evidence_claim_id" : "missing_evidence_claim_id",
+      message: ref.targetId ? `Evidence references unknown claimId ${target}.` : "Evidence is missing a claim-support relation.",
+      smallestRepair: "Add `## Relations` with `- supports: [[claim-id]]` after checking narrativeInventory, or create the missing claim node first.",
+      examples: ["- supports: [[claim-market-context]]"],
+    }
+  }
+  return {
+    severity: "warning",
+    file: ref.file,
+    nodeId: ref.fromId,
+    issueCode: `unresolved_${ref.kind}`,
+    message: `${ref.field ?? "target"} references unknown node ${target}.`,
+    smallestRepair: "Check narrativeInventory and patch the target id, or create the missing target node if intentional.",
+  }
+}
+
+function evidenceTraceCards(doc: VaultDocument): MarkdownQaRepairCard[] {
+  if (stringField(doc, "type") !== "evidence") return []
+  const cards: MarkdownQaRepairCard[] = []
+  const missing: string[] = []
+  if (!hasSource(doc)) missing.push("source|sourcePath|url|findingsFile")
+  if (!stringField(doc, "quote") && !firstBodyLine(doc.body)) missing.push("quote|snippet body")
+  for (const field of ["supportScope", "unsupportedScope", "caveat", "strength"]) {
+    if (!stringField(doc, field)) missing.push(field)
+  }
+  if (missing.length > 0) {
+    cards.push({
+      severity: "warning",
+      file: doc.relativePath,
+      nodeId: stringField(doc, "id"),
+      issueCode: "evidence_trace_fields_missing",
+      message: `Evidence node is missing trace field(s): ${missing.join(", ")}.`,
+      smallestRepair: "Add explicit source trace, quote/snippet, support scope, unsupported scope, caveat, and strength before treating the evidence as strong support.",
+      examples: ["sourcePath: proposal.md", "supportScope: Scope explicitly supported by the quote.", "unsupportedScope: What this evidence does not prove."],
+    })
+  }
+  return cards
+}
+
+function unsupportedRootMarkdownCards(workspaceRoot: string, touchedSet?: Set<string>): MarkdownQaRepairCard[] {
+  const root = narrativeVaultPath(workspaceRoot)
+  if (!existsSync(root) || !statSync(root).isDirectory()) return []
+  const supportedRootFiles = new Set(["index.md", "audience.md", "decision.md", "thesis.md"])
+  const cards: MarkdownQaRepairCard[] = []
+
+  for (const entry of readdirSync(root).sort()) {
+    if (!entry.endsWith(".md") || supportedRootFiles.has(entry)) continue
+    const filePath = join(root, entry)
+    if (!statSync(filePath).isFile()) continue
+    const relativePath = entry.replace(/\\/g, "/")
+    if (touchedSet && !touchedSet.has(relativePath) && !touchedSet.has(`revela-narrative/${relativePath}`)) continue
+    cards.push({
+      severity: "warning",
+      file: relativePath,
+      issueCode: "unsupported_vault_root_markdown",
+      message: "Markdown file is in the vault root but only index.md, audience.md, decision.md, and thesis.md are supported there.",
+      smallestRepair: "Move claim/evidence/objection/risk/research-gap nodes into their supported subdirectory, or remove this unsupported root file if it was temporary.",
+      examples: ["claims/claim-market-context.md", "evidence/evidence-proposal-intent.md", "research-gaps/gap-market-size.md"],
+    })
+  }
+
+  return cards
+}
+
+function normalizeVaultFile(file: string): string {
+  return file.replace(/\\/g, "/").replace(/^revela-narrative\//, "")
+}
+
+function stringField(doc: VaultDocument, key: string): string {
+  const value = doc.frontmatter[key]
+  return typeof value === "string" ? value.trim() : ""
+}
+
+function hasSource(doc: VaultDocument): boolean {
+  return Boolean(stringField(doc, "source") || stringField(doc, "sourcePath") || stringField(doc, "url") || stringField(doc, "findingsFile"))
+}
+
+function firstBodyLine(body: string): string {
+  return body.split(/\n+/).map((line) => line.trim()).find(Boolean) ?? ""
+}
+
+function examplesFor(code: string): string[] | undefined {
+  if (code === "typed_wikilink_target") return ["- supports: [[claim-existing-id]]"]
+  if (code === "invalid_node_type_authoring") return ["type: research-gap"]
+  if (code === "duplicate_stable_heading") return ["Merge duplicate section bodies under one ## Caveats or ## Relations heading."]
+  if (code === "duplicate_frontmatter") return ["Keep exactly one leading --- frontmatter block."]
+  return undefined
+}
+
+function dedupeCards(cards: MarkdownQaRepairCard[]): MarkdownQaRepairCard[] {
+  const seen = new Set<string>()
+  const result: MarkdownQaRepairCard[] = []
+  for (const card of cards) {
+    const key = [card.severity, card.file, card.nodeId ?? "", card.issueCode, card.message].join("\0")
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(card)
+  }
+  return result
+}

package/lib/narrative-vault/markdown.ts

@@ -0,0 +1,34 @@
+export function splitMarkdownSections(body: string): { main: string; sections: Record<string, string> } {
+  const sections: Record<string, string> = {}
+  const lines = body.replace(/\r\n/g, "\n").split("\n")
+  let current = "main"
+  const buffers: Record<string, string[]> = { main: [] }
+  for (const line of lines) {
+    const match = /^##\s+(.+?)\s*$/.exec(line)
+    if (match) {
+      current = normalizeSectionName(match[1])
+      buffers[current] = []
+      continue
+    }
+    buffers[current].push(line)
+  }
+  for (const [key, value] of Object.entries(buffers)) {
+    if (key === "main") continue
+    sections[key] = value.join("\n").trim()
+  }
+  return { main: buffers.main.join("\n").trim(), sections }
+}
+
+export function firstParagraphOrBody(value: string): string {
+  const cleaned = value.trim()
+  if (!cleaned) return ""
+  return cleaned.split(/\n\s*\n/)[0].replace(/\n+/g, " ").trim()
+}
+
+export function parseMarkdownList(section: string): string[] {
+  return section.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim()).filter(Boolean)
+}
+
+export function normalizeSectionName(name: string): string {
+  return name.trim().toLowerCase().replace(/\s+/g, "-")
+}