@cyber-dash-tech/revela 0.16.4 → 0.17.0

package/lib/narrative-state/research-binding-eval.ts

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync } from "fs"
+import { resolve, sep } from "path"
+import type { DecksState } from "../decks-state"
+import { normalizeNarrativeState } from "./normalize"
+import type { NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "./types"
+
+export type EvidenceBindingFailureReason =
+  | "missing_quote"
+  | "unclear_source"
+  | "over_broad_claim"
+  | "weak_source"
+  | "unsupported_scope"
+  | "caveat_conflict"
+  | "source_mismatch"
+  | "context_only_finding"
+
+export interface EvidenceBindingDiagnostic {
+  findingsFile: string
+  bindable: boolean
+  failureReasons: EvidenceBindingFailureReason[]
+  explicit: {
+    source: boolean
+    quoteOrSnippet: boolean
+    supportScope: boolean
+    unsupportedScope: boolean
+    caveat: boolean
+    strength: boolean
+  }
+}
+
+export type ResearchFindingsBindingStatus = "bindable" | "needs_fields" | "not_relevant" | "unsafe"
+
+export interface ResearchFindingsBindingEval {
+  findingsFile: string
+  status: ResearchFindingsBindingStatus
+  claimId?: string
+  claimText?: string
+  diagnostic?: EvidenceBindingDiagnostic
+  missingFields: Array<"source" | "quoteOrSnippet" | "supportScope" | "unsupportedScope" | "caveat" | "strength" | "claimId">
+  failureReasons: EvidenceBindingFailureReason[]
+  recommendedEvidenceDraft?: Partial<NarrativeEvidenceBinding>
+  nextAction: string
+}
+
+export function evaluateResearchFindingsBinding(state: DecksState, workspaceRoot: string | undefined, findingsFile: string): ResearchFindingsBindingEval {
+  const normalizedFile = normalizeResearchFindingsPath(findingsFile)
+  if (!normalizedFile) return unsafeEval(findingsFile, "Use a workspace-relative researches/**/*.md findings file before evaluating evidence binding.")
+
+  const text = readWorkspaceText(workspaceRoot, normalizedFile)
+  if (text === undefined) return unsafeEval(normalizedFile, "Save the findings file inside the workspace before evaluating evidence binding.")
+
+  const narrative = normalizeNarrativeState(state)
+  const diagnostic = evidenceBindingDiagnosticFromText(normalizedFile, text)
+  const claim = resolveClaimForFindings(narrative, normalizedFile, text)
+  const explicitClaimId = extractField(text, ["claimId", "claim id"])
+  const missingFields = missingExplicitFields(diagnostic)
+  const failureReasons = [...diagnostic.failureReasons]
+
+  if (explicitClaimId && !claim) {
+    return {
+      findingsFile: normalizedFile,
+      status: "unsafe",
+      claimId: explicitClaimId,
+      diagnostic,
+      missingFields,
+      failureReasons: [...new Set([...failureReasons, "source_mismatch" as const])],
+      nextAction: `Do not bind ${normalizedFile}: claimId ${explicitClaimId} does not exist in the canonical narrative.`,
+    }
+  }
+
+  if (!claim) {
+    return {
+      findingsFile: normalizedFile,
+      status: diagnostic.failureReasons.includes("context_only_finding") ? "not_relevant" : "needs_fields",
+      diagnostic,
+      missingFields: [...missingFields, "claimId"],
+      failureReasons,
+      nextAction: "Identify the exact canonical claimId this findings file supports before writing evidence/*.md.",
+    }
+  }
+
+  if (!diagnostic.bindable) {
+    return {
+      findingsFile: normalizedFile,
+      status: "needs_fields",
+      claimId: claim.id,
+      claimText: claim.text,
+      diagnostic,
+      missingFields,
+      failureReasons,
+      nextAction: `Do not bind yet. Fill missing fields for ${claim.id}: ${missingFields.join(", ") || "none"}.`,
+    }
+  }
+
+  return {
+    findingsFile: normalizedFile,
+    status: "bindable",
+    claimId: claim.id,
+    claimText: claim.text,
+    diagnostic,
+    missingFields,
+    failureReasons,
+    recommendedEvidenceDraft: buildEvidenceDraft(normalizedFile, text, claim),
+    nextAction: `Write a canonical evidence node in revela-narrative/evidence/ for ${claim.id}, preserving source trace, quote, scopes, caveat, and strength.`,
+  }
+}
+
+export function evidenceBindingDiagnostic(workspaceRoot: string | undefined, findingsFile: string): EvidenceBindingDiagnostic | undefined {
+  const text = readWorkspaceText(workspaceRoot, findingsFile)
+  if (text === undefined) return undefined
+  return evidenceBindingDiagnosticFromText(findingsFile, text)
+}
+
+function evidenceBindingDiagnosticFromText(findingsFile: string, text: string): EvidenceBindingDiagnostic {
+  const explicit = {
+    source: hasSourceTrace(text),
+    quoteOrSnippet: hasQuoteOrSnippet(text),
+    supportScope: hasField(text, ["support scope", "supported scope", "supports", "support"]),
+    unsupportedScope: hasField(text, ["unsupported scope", "unsupported", "not supported", "gaps"]),
+    caveat: hasField(text, ["caveat", "limitation", "limits", "boundary"]),
+    strength: hasField(text, ["strength", "support strength", "evidence strength"]),
+  }
+  const failureReasons: EvidenceBindingFailureReason[] = []
+  if (!explicit.quoteOrSnippet) failureReasons.push("missing_quote")
+  if (!explicit.source) failureReasons.push("unclear_source")
+  if (!explicit.supportScope || !explicit.unsupportedScope) failureReasons.push("unsupported_scope")
+  if (!explicit.caveat) failureReasons.push("caveat_conflict")
+  if (!explicit.strength) failureReasons.push("weak_source")
+  if (looksContextOnly(text, explicit)) failureReasons.push("context_only_finding")
+  return { findingsFile, bindable: failureReasons.length === 0, failureReasons, explicit }
+}
+
+function resolveClaimForFindings(narrative: NarrativeStateV1, findingsFile: string, text: string): NarrativeClaim | undefined {
+  const explicitClaimId = extractField(text, ["claimId", "claim id"])
+  if (explicitClaimId) return narrative.claims.find((claim) => claim.id === explicitClaimId)
+  const gap = (narrative.researchGaps ?? []).find((item) => item.findingsFile === findingsFile && item.targetType === "claim" && item.targetId)
+  if (gap?.targetId) return narrative.claims.find((claim) => claim.id === gap.targetId)
+  return undefined
+}
+
+function buildEvidenceDraft(findingsFile: string, text: string, claim: NarrativeClaim): Partial<NarrativeEvidenceBinding> {
+  const source = extractSource(text) ?? findingsFile
+  const draft: Partial<NarrativeEvidenceBinding> = {
+    claimId: claim.id,
+    source,
+    findingsFile,
+    quote: extractQuote(text),
+    supportScope: extractField(text, ["support scope", "supported scope", "support"]),
+    unsupportedScope: extractField(text, ["unsupported scope", "unsupported", "not supported"]),
+    caveat: extractField(text, ["caveat", "limitation", "limits", "boundary"]),
+    strength: normalizeStrength(extractField(text, ["strength", "support strength", "evidence strength"])),
+  }
+  if (/^https?:\/\//i.test(source)) draft.url = source
+  else draft.sourcePath = source
+  return draft
+}
+
+function unsafeEval(findingsFile: string, nextAction: string): ResearchFindingsBindingEval {
+  return {
+    findingsFile,
+    status: "unsafe",
+    missingFields: ["source", "quoteOrSnippet", "supportScope", "unsupportedScope", "caveat", "strength", "claimId"],
+    failureReasons: ["source_mismatch"],
+    nextAction,
+  }
+}
+
+function missingExplicitFields(diagnostic: EvidenceBindingDiagnostic): ResearchFindingsBindingEval["missingFields"] {
+  const missing: ResearchFindingsBindingEval["missingFields"] = []
+  if (!diagnostic.explicit.source) missing.push("source")
+  if (!diagnostic.explicit.quoteOrSnippet) missing.push("quoteOrSnippet")
+  if (!diagnostic.explicit.supportScope) missing.push("supportScope")
+  if (!diagnostic.explicit.unsupportedScope) missing.push("unsupportedScope")
+  if (!diagnostic.explicit.caveat) missing.push("caveat")
+  if (!diagnostic.explicit.strength) missing.push("strength")
+  return missing
+}
+
+function normalizeResearchFindingsPath(filePath: string | undefined): string | undefined {
+  const normalized = normalizePath(filePath ?? "").replace(/^\.\//, "")
+  if (!normalized || normalized.startsWith("../") || normalized.startsWith("/")) return undefined
+  if (!normalized.startsWith("researches/") || !normalized.endsWith(".md")) return undefined
+  return normalized
+}
+
+function readWorkspaceText(workspaceRoot: string | undefined, relativePath: string): string | undefined {
+  if (!workspaceRoot) return undefined
+  const root = resolve(workspaceRoot)
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + sep)) return undefined
+  if (!existsSync(target)) return undefined
+  return readFileSync(target, "utf-8")
+}
+
+function hasSourceTrace(text: string): boolean {
+  return /^sources:\s*$/im.test(text)
+    || /\[source:\s*[^\]]+\]/i.test(text)
+    || /^\s*-?\s*source:\s*\S+/im.test(text)
+    || /^\s*source\s+(path|url):\s*\S+/im.test(text)
+}
+
+function hasQuoteOrSnippet(text: string): boolean {
+  return hasField(text, ["quote", "snippet"])
+    || /["“][^"”]{20,}["”]/.test(text)
+    || /^>\s*\S.{20,}/m.test(text)
+}
+
+function hasField(text: string, labels: string[]): boolean {
+  return labels.some((label) => new RegExp(`(^|\\n)\\s*(?:[-*]\\s*)?${escapeRegex(label)}\\s*[:：]\\s*\\S`, "i").test(text)
+    || new RegExp(`^##+\\s+.*${escapeRegex(label)}`, "im").test(text))
+}
+
+function looksContextOnly(text: string, explicit: EvidenceBindingDiagnostic["explicit"]): boolean {
+  return /^##+\s+data\b/im.test(text) && !explicit.quoteOrSnippet && (!explicit.supportScope || !explicit.caveat)
+}
+
+function extractField(text: string, labels: string[]): string | undefined {
+  for (const label of labels) {
+    const match = text.match(new RegExp(`(^|\\n)\\s*(?:[-*]\\s*)?${escapeRegex(label)}\\s*[:：]\\s*([^\\n]+)`, "i"))
+    const value = match?.[2]?.trim()
+    if (value) return value
+  }
+  return undefined
+}
+
+function extractSource(text: string): string | undefined {
+  const yamlSource = text.match(/^sources:\s*\n\s*-\s*["']?([^"'\n]+)["']?\s*$/im)?.[1]?.trim()
+  if (/^https?:\/\//i.test(yamlSource ?? "")) return yamlSource
+  const bracket = text.match(/\[source:\s*([^\]]+)\]/i)?.[1]?.trim()
+  if (bracket) return bracket
+  return extractField(text, ["source", "source url", "source path"])
+}
+
+function extractQuote(text: string): string | undefined {
+  const field = extractField(text, ["quote", "snippet"])
+  if (field) return trimQuote(field)
+  const quoted = text.match(/["“]([^"”]{20,})["”]/)?.[1]?.trim()
+  if (quoted) return quoted
+  return text.match(/^>\s*(\S.{20,})/m)?.[1]?.trim()
+}
+
+function normalizeStrength(value: string | undefined): NarrativeEvidenceBinding["strength"] | undefined {
+  const normalized = value?.toLowerCase()
+  if (normalized?.includes("strong")) return "strong"
+  if (normalized?.includes("partial")) return "partial"
+  if (normalized?.includes("weak")) return "weak"
+  return undefined
+}
+
+function trimQuote(value: string): string {
+  return value.replace(/^["“]/, "").replace(/["”]$/, "").trim()
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/")
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}

package/lib/narrative-state/research-gaps.ts

@@ -1,7 +1,6 @@
-import { existsSync, readFileSync } from "fs"
-import { resolve, sep } from "path"
 import type { DecksState } from "../decks-state"
 import { recordWorkspaceAction } from "../workspace-state/actions"
+import { evidenceBindingDiagnostic, type EvidenceBindingDiagnostic, type EvidenceBindingFailureReason } from "./research-binding-eval"
 import { stableResearchGapId } from "./hash"
 import { normalizeNarrativeState } from "./normalize"
 import { reviewNarrativeState } from "./readiness"
@@ -24,15 +23,7 @@ export type ResearchTargetKind =
   | "unattached_findings"
   | "claim_chain_gap"
 
-export type EvidenceBindingFailureReason =
-  | "missing_quote"
-  | "unclear_source"
-  | "over_broad_claim"
-  | "weak_source"
-  | "unsupported_scope"
-  | "caveat_conflict"
-  | "source_mismatch"
-  | "context_only_finding"
+export type { EvidenceBindingDiagnostic, EvidenceBindingFailureReason } from "./research-binding-eval"
 
 export interface ResearchTarget {
   id: string
@@ -56,20 +47,6 @@ export interface ResearchTargetsResult {
   selected?: ResearchTarget
 }
 
-export interface EvidenceBindingDiagnostic {
-  findingsFile: string
-  bindable: boolean
-  failureReasons: EvidenceBindingFailureReason[]
-  explicit: {
-    source: boolean
-    quoteOrSnippet: boolean
-    supportScope: boolean
-    unsupportedScope: boolean
-    caveat: boolean
-    strength: boolean
-  }
-}
-
 export interface UpsertResearchGapInput {
   id?: string
   targetType?: NarrativeResearchGapTargetType
@@ -325,69 +302,6 @@ function targetsFromUnattachedFindings(state: DecksState, narrative: NarrativeSt
   })
 }
 
-function evidenceBindingDiagnostic(workspaceRoot: string | undefined, findingsFile: string): EvidenceBindingDiagnostic | undefined {
-  const text = readWorkspaceText(workspaceRoot, findingsFile)
-  if (text === undefined) return undefined
-
-  const explicit = {
-    source: hasSourceTrace(text),
-    quoteOrSnippet: hasQuoteOrSnippet(text),
-    supportScope: hasField(text, ["support scope", "supported scope", "supports", "support"]),
-    unsupportedScope: hasField(text, ["unsupported scope", "unsupported", "not supported", "gaps"]),
-    caveat: hasField(text, ["caveat", "limitation", "limits", "boundary"]),
-    strength: hasField(text, ["strength", "support strength", "evidence strength"]),
-  }
-  const failureReasons: EvidenceBindingFailureReason[] = []
-  if (!explicit.quoteOrSnippet) failureReasons.push("missing_quote")
-  if (!explicit.source) failureReasons.push("unclear_source")
-  if (!explicit.supportScope || !explicit.unsupportedScope) failureReasons.push("unsupported_scope")
-  if (!explicit.caveat) failureReasons.push("caveat_conflict")
-  if (!explicit.strength) failureReasons.push("weak_source")
-  if (looksContextOnly(text, explicit)) failureReasons.push("context_only_finding")
-
-  return {
-    findingsFile,
-    bindable: failureReasons.length === 0,
-    failureReasons,
-    explicit,
-  }
-}
-
-function readWorkspaceText(workspaceRoot: string | undefined, relativePath: string): string | undefined {
-  if (!workspaceRoot) return undefined
-  const root = resolve(workspaceRoot)
-  const target = resolve(root, relativePath)
-  if (target !== root && !target.startsWith(root + sep)) return undefined
-  if (!existsSync(target)) return undefined
-  return readFileSync(target, "utf-8")
-}
-
-function hasSourceTrace(text: string): boolean {
-  return /^sources:\s*$/im.test(text)
-    || /\[source:\s*[^\]]+\]/i.test(text)
-    || /^\s*-?\s*source:\s*\S+/im.test(text)
-    || /^\s*source\s+(path|url):\s*\S+/im.test(text)
-}
-
-function hasQuoteOrSnippet(text: string): boolean {
-  return hasField(text, ["quote", "snippet"])
-    || /["“][^"”]{20,}["”]/.test(text)
-    || /^>\s*\S.{20,}/m.test(text)
-}
-
-function hasField(text: string, labels: string[]): boolean {
-  return labels.some((label) => new RegExp(`(^|\\n)\\s*(?:[-*]\\s*)?${escapeRegex(label)}\\s*[:：]\\s*\\S`, "i").test(text)
-    || new RegExp(`^##+\\s+.*${escapeRegex(label)}`, "im").test(text))
-}
-
-function looksContextOnly(text: string, explicit: EvidenceBindingDiagnostic["explicit"]): boolean {
-  return /^##+\s+data\b/im.test(text) && !explicit.quoteOrSnippet && (!explicit.supportScope || !explicit.caveat)
-}
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-}
-
 function claimTarget(kind: Extract<ResearchTargetKind, "missing_evidence" | "weak_evidence" | "unsupported_scope">, claim: NarrativeClaim, priority: "high" | "medium", reason: string): ResearchTarget {
   return {
     id: `claim:${kind}:${claim.id}`,

package/lib/narrative-vault/authoring-contract.ts

@@ -0,0 +1,127 @@
+export interface NarrativeVaultAuthoringContract {
+  role: string
+  standardSession: string[]
+  allowedActions: string[]
+  forbiddenCompatibilityActions: string[]
+  validNodeTypes: string[]
+  idConvention: {
+    rule: string
+    examples: string[]
+    avoid: string[]
+  }
+  relationSyntax: {
+    rule: string
+    examples: string[]
+    avoid: string[]
+  }
+  structuredTemplates: {
+    claim: Record<string, unknown>
+    evidence: Record<string, unknown>
+    researchGap: Record<string, unknown>
+  }
+  markdownRepairPolicy: string[]
+}
+
+export function narrativeVaultAuthoringContract(): NarrativeVaultAuthoringContract {
+  return {
+    role: "Markdown authoring guide. The LLM may maintain revela-narrative/**/*.md knowledge nodes directly; structured actions are optional safety helpers, not the primary authoring model.",
+    standardSession: [
+      "read(summary:true)",
+      "narrativeInventory before authoring ids or relations",
+      "edit Markdown nodes or use an optional targeted helper",
+      "markdown QA / compileNarrativeVault after authoring",
+      "report remaining blockers, evidence gaps, and unsupported scope",
+    ],
+    allowedActions: [
+      "initNarrativeVault",
+      "updateVaultCoreNarrative",
+      "upsertVaultClaim",
+      "upsertVaultEvidence",
+      "bindResearchFindings",
+      "upsertVaultObjection",
+      "upsertVaultRisk",
+      "upsertVaultResearchGap",
+      "updateVaultResearchGap",
+      "compileNarrativeVault",
+    ],
+    forbiddenCompatibilityActions: [
+      "upsertNarrative",
+      "upsertResearchGaps",
+      "deriveResearchGaps",
+      "updateResearchGap",
+      "closeResearchGap",
+      "applyEvidenceCandidates",
+    ],
+    validNodeTypes: ["index", "audience", "decision", "thesis", "claim", "evidence", "objection", "risk", "research-gap"],
+    idConvention: {
+      rule: "New vault nodes use plain stable ids without type prefixes or colons. Keep legacy ids when editing existing nodes, but do not generate new ids such as claim:foo.",
+      examples: ["claim-belief-change-purpose", "evidence-proposal-intent", "gap-market-size", "risk-overclaiming"],
+      avoid: ["claim:belief-change-purpose", "evidence:proposal:intent", "researchGap-market-size"],
+    },
+    relationSyntax: {
+      rule: "Relation lines are the primary graph source. Use a relation label and a plain node-id wikilink; frontmatter claimId/targetId/evidenceBindingIds are compatibility fallback only.",
+      examples: ["- supports: [[claim-belief-change-purpose]]", "- depends_on: [[evidence-proposal-intent]]"],
+      avoid: ["[[claim:claim-belief-change-purpose]]", "[[evidence:evidence-proposal-intent]]"],
+    },
+    structuredTemplates: {
+      claim: {
+        action: "upsertVaultClaim",
+        narrative: {
+          claims: [{
+            id: "claim-belief-change-purpose",
+            kind: "recommendation",
+            text: "Audience belief change is the central purpose of the artifact.",
+            importance: "central",
+            evidenceRequired: true,
+            evidenceStatus: "partial",
+            supportedScope: "What current sources explicitly support.",
+            unsupportedScope: "What still requires research or user confirmation.",
+            caveats: ["Do not overclaim beyond available source trace."],
+          }],
+          claimRelations: [{
+            fromClaimId: "claim-belief-change-purpose",
+            toClaimId: "claim-recommendation",
+            relation: "supports",
+            rationale: "Belief change frames the recommendation.",
+          }],
+        },
+      },
+      evidence: {
+        action: "upsertVaultEvidence",
+        evidence: {
+          id: "evidence-proposal-intent",
+          claimId: "claim-belief-change-purpose",
+          source: "proposal.md",
+          sourcePath: "proposal.md",
+          quote: "Exact quote or snippet from the source.",
+          location: "section or line reference when known",
+          supportScope: "Scope explicitly supported by the quote.",
+          unsupportedScope: "Scope not supported by this evidence.",
+          caveat: "Limitation that travels with this evidence.",
+          strength: "partial",
+          relationMarkdown: "## Relations\n\n- supports: [[claim-belief-change-purpose]]",
+        },
+      },
+      researchGap: {
+        action: "upsertVaultResearchGap",
+        gapId: "gap-market-size",
+        researchGaps: [{
+          id: "gap-market-size",
+          targetType: "claim",
+          targetId: "claim-market-size",
+          question: "What source can support the market-size claim?",
+          status: "open",
+          priority: "high",
+          createdFromIssueType: "missing_evidence",
+          relationMarkdown: "## Relations\n\n- depends_on: [[evidence-proposal-intent]]",
+        }],
+      },
+    },
+    markdownRepairPolicy: [
+      "Use direct Markdown patches only for small repairs after reading the existing node.",
+      "Do not delete and recreate existing vault nodes to fix schema.",
+      "Do not append a second frontmatter block.",
+      "Do not duplicate stable headings such as Evidence, Caveats, Relations, Response, Mitigation, or Notes.",
+    ],
+  }
+}

package/lib/narrative-vault/authoring-guard.ts

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import type { VaultDiagnosticDisplay } from "./diagnostic-report"
+
+const VALID_TYPES = new Set(["index", "audience", "decision", "thesis", "claim", "evidence", "objection", "risk", "research-gap"])
+const STABLE_HEADINGS = ["Evidence", "Caveats", "Relations", "Response", "Mitigation", "Notes"]
+
+export interface VaultAuthoringGuardReport {
+  ok: boolean
+  blockers: VaultDiagnosticDisplay[]
+  warnings: VaultDiagnosticDisplay[]
+}
+
+export function runVaultAuthoringGuard(workspaceRoot: string, touched: string[]): VaultAuthoringGuardReport {
+  const diagnostics: VaultDiagnosticDisplay[] = []
+  for (const relativePath of [...new Set(touched)].sort()) {
+    const filePath = join(workspaceRoot, relativePath)
+    if (!existsSync(filePath)) continue
+    const text = readFileSync(filePath, "utf-8")
+    diagnostics.push(...inspectVaultMarkdown(relativePath.replace(/\\/g, "/"), text))
+  }
+
+  const blockers = diagnostics.filter((diagnostic) => diagnostic.severity === "error")
+  const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === "warning")
+  return { ok: blockers.length === 0, blockers, warnings }
+}
+
+export function inspectVaultMarkdown(file: string, text: string): VaultDiagnosticDisplay[] {
+  const diagnostics: VaultDiagnosticDisplay[] = []
+  const type = extractFrontmatterField(text, "type")
+  const nodeId = extractFrontmatterField(text, "id")
+
+  if (countYamlFences(text) > 2) {
+    diagnostics.push(display({
+      severity: "error",
+      code: "duplicate_frontmatter",
+      file,
+      nodeId,
+      message: "Vault Markdown contains more than one frontmatter block, usually caused by appending a replacement document instead of replacing the old one.",
+      suggestedFix: "Keep one leading frontmatter block and merge the intended fields/body into the existing document.",
+      suggestedAction: "Read the file, remove the duplicated frontmatter/body, and rerun compileNarrativeVault.",
+    }))
+  }
+
+  if (type && !VALID_TYPES.has(type)) {
+    diagnostics.push(display({
+      severity: "error",
+      code: "invalid_node_type_authoring",
+      file,
+      nodeId,
+      message: `Unsupported vault node type \`${type}\` in frontmatter.`,
+      suggestedFix: type === "researchGap" || type === "research_gap"
+        ? "Use `type: \"research-gap\"` for research gap nodes."
+        : "Use a supported node type: index, audience, decision, thesis, claim, evidence, objection, risk, or research-gap.",
+      suggestedAction: "Patch only the type frontmatter line and rerun compileNarrativeVault.",
+    }))
+  }
+
+  if (type === "evidence" && !extractFrontmatterField(text, "claimId")) {
+    diagnostics.push(display({
+      severity: "error",
+      code: "evidence_claim_id_missing_authoring",
+      file,
+      nodeId,
+      message: "Evidence nodes must declare claimId before they can become canonical support.",
+      suggestedFix: "Add `claimId` pointing to an existing claim id, or keep the material as research/findings until support is explicit.",
+      suggestedAction: "Patch the evidence frontmatter and rerun compileNarrativeVault.",
+    }))
+  }
+
+  for (const heading of STABLE_HEADINGS) {
+    const count = countHeading(text, heading)
+    if (count > 1) {
+      diagnostics.push(display({
+        severity: "error",
+        code: "duplicate_stable_heading",
+        file,
+        nodeId,
+        message: `Vault Markdown contains ${count} \`## ${heading}\` sections.`,
+        suggestedFix: `Merge content into a single \`## ${heading}\` section instead of appending a duplicate heading.`,
+        suggestedAction: "Read the file, merge duplicate sections in place, and rerun compileNarrativeVault.",
+      }))
+    }
+  }
+
+  for (const match of text.matchAll(/\[\[([A-Za-z][\w-]*):([^\]]+)\]\]/g)) {
+    if (!match[2].startsWith(`${match[1]}-`) && !match[2].startsWith(`${match[1]}:`)) continue
+    diagnostics.push(display({
+      severity: "error",
+      code: "typed_wikilink_target",
+      file,
+      nodeId,
+      message: `Relation target \`[[${match[1]}:${match[2]}]]\` mixes type metadata into the wikilink id.`,
+      suggestedFix: `Use standard node-id wikilinks, for example \`[[${match[2]}]]\`, and keep relation type in the list prefix such as \`supports:\`.`,
+      suggestedAction: "Patch the Relations wikilinks to target node ids directly and rerun compileNarrativeVault.",
+    }))
+  }
+
+  return diagnostics
+}
+
+function display(diagnostic: VaultDiagnosticDisplay): VaultDiagnosticDisplay {
+  return diagnostic
+}
+
+function countYamlFences(text: string): number {
+  return text.split(/\r?\n/).filter((line) => line.trim() === "---").length
+}
+
+function countHeading(text: string, heading: string): number {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const pattern = new RegExp(`^##\\s+${escaped}\\s*$`, "gim")
+  return [...text.matchAll(pattern)].length
+}
+
+function extractFrontmatterField(text: string, field: string): string | undefined {
+  const frontmatter = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/)
+  if (!frontmatter) return undefined
+  const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const match = frontmatter[1].match(new RegExp(`^${escaped}:\\s*["']?([^"'\\r\\n]+)["']?\\s*$`, "m"))
+  return match?.[1]?.trim()
+}