@cyber-dash-tech/revela 0.11.0 → 0.13.0

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

@@ -0,0 +1,191 @@
+import type { DecksState } from "../decks-state"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+import { stableResearchGapId } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import { reviewNarrativeState } from "./readiness"
+import type {
+  NarrativeReadinessIssue,
+  NarrativeResearchGap,
+  NarrativeResearchGapStatus,
+  NarrativeResearchGapTargetType,
+  NarrativeStateV1,
+} from "./types"
+
+export interface UpsertResearchGapInput {
+  id?: string
+  targetType?: NarrativeResearchGapTargetType
+  targetId?: string
+  question: string
+  status?: NarrativeResearchGapStatus
+  priority?: "high" | "medium" | "low"
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  createdFromIssueType?: NarrativeReadinessIssue["type"]
+  notes?: string
+}
+
+export interface UpdateResearchGapInput {
+  id: string
+  status?: NarrativeResearchGapStatus
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  notes?: string
+}
+
+export interface ResearchGapMutationResult {
+  created: NarrativeResearchGap[]
+  updated: NarrativeResearchGap[]
+  skipped: Array<{ id?: string; question?: string; reason: string }>
+  gaps: NarrativeResearchGap[]
+}
+
+export interface CloseResearchGapResult {
+  closed: boolean
+  skipped: boolean
+  reason?: string
+  gap?: NarrativeResearchGap
+}
+
+export function deriveResearchGapsFromReadiness(state: DecksState, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const reviewed = reviewNarrativeState(state, { now: options.now })
+  return upsertResearchGapsInState(reviewed.state, gapsFromIssues(reviewed.state.narrative!, reviewed.result.issues), options)
+}
+
+export function upsertResearchGapsInState(state: DecksState, inputs: UpsertResearchGapInput[], options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const now = options.now ?? new Date().toISOString()
+  const narrative = ensureNarrative(state)
+  const existing = new Map((narrative.researchGaps ?? []).map((gap) => [gap.id, gap]))
+  const created: NarrativeResearchGap[] = []
+  const updated: NarrativeResearchGap[] = []
+  const skipped: ResearchGapMutationResult["skipped"] = []
+
+  for (const input of inputs) {
+    const question = clean(input.question)
+    if (!question) {
+      skipped.push({ reason: "question is required" })
+      continue
+    }
+    const targetType = input.targetType ?? "narrative"
+    const targetId = clean(input.targetId)
+    const id = input.id?.trim() || stableResearchGapId([targetType, targetId, question].filter(Boolean).join("|"))
+    const prior = existing.get(id)
+    if (prior?.status === "closed") {
+      skipped.push({ id, question, reason: "matching research gap is already closed" })
+      continue
+    }
+
+    const next: NarrativeResearchGap = {
+      id,
+      targetType,
+      targetId,
+      question,
+      status: input.status ?? prior?.status ?? "open",
+      priority: input.priority ?? prior?.priority ?? "medium",
+      findingsFile: clean(input.findingsFile) || prior?.findingsFile,
+      evidenceBindingIds: mergeIds(prior?.evidenceBindingIds, input.evidenceBindingIds),
+      createdFromIssueType: input.createdFromIssueType ?? prior?.createdFromIssueType,
+      notes: clean(input.notes) || prior?.notes,
+      createdAt: prior?.createdAt ?? now,
+      updatedAt: now,
+      closedAt: input.status === "closed" ? now : prior?.closedAt,
+    }
+    existing.set(id, next)
+    if (prior) updated.push(next)
+    else created.push(next)
+  }
+
+  const gaps = [...existing.values()].sort((a, b) => gapSortValue(a) - gapSortValue(b) || a.question.localeCompare(b.question))
+  state.narrative = { ...narrative, researchGaps: gaps, updatedAt: now }
+  if (created.length > 0) recordResearchGapAction(state, "research.gap_created", created, now)
+  if (updated.length > 0) recordResearchGapAction(state, "research.gap_updated", updated, now)
+  return { state, result: { created, updated, skipped, gaps } }
+}
+
+export function updateResearchGapInState(state: DecksState, input: UpdateResearchGapInput, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const narrative = ensureNarrative(state)
+  const gap = (narrative.researchGaps ?? []).find((item) => item.id === input.id)
+  if (!gap) return { state, result: { created: [], updated: [], skipped: [{ id: input.id, reason: "research gap not found" }], gaps: narrative.researchGaps ?? [] } }
+  return upsertResearchGapsInState(state, [{ ...gap, ...input, question: gap.question, targetType: gap.targetType, targetId: gap.targetId }], options)
+}
+
+export function closeResearchGapInState(state: DecksState, id: string, reason?: string, options: { now?: string } = {}): { state: DecksState; result: CloseResearchGapResult } {
+  const now = options.now ?? new Date().toISOString()
+  const narrative = ensureNarrative(state)
+  const gaps = narrative.researchGaps ?? []
+  const gap = gaps.find((item) => item.id === id)
+  if (!gap) return { state, result: { closed: false, skipped: true, reason: "research gap not found" } }
+  const closed: NarrativeResearchGap = { ...gap, status: "closed", notes: clean(reason) || gap.notes, updatedAt: now, closedAt: now }
+  state.narrative = { ...narrative, researchGaps: gaps.map((item) => item.id === id ? closed : item), updatedAt: now }
+  recordResearchGapAction(state, "research.gap_closed", [closed], now)
+  return { state, result: { closed: true, skipped: false, gap: closed } }
+}
+
+function gapsFromIssues(narrative: NarrativeStateV1, issues: NarrativeReadinessIssue[]): UpsertResearchGapInput[] {
+  return issues.flatMap((issue) => {
+    if (!researchableIssue(issue)) return []
+    const target = targetForIssue(narrative, issue)
+    return [{
+      targetType: target.type,
+      targetId: target.id,
+      question: questionForIssue(issue),
+      priority: issue.severity === "blocker" ? "high" : "medium",
+      status: "open",
+      createdFromIssueType: issue.type,
+      notes: issue.suggestedAction,
+      findingsFile: issue.source?.startsWith("researches/") ? issue.source : undefined,
+    }]
+  })
+}
+
+function researchableIssue(issue: NarrativeReadinessIssue): boolean {
+  return issue.type === "missing_evidence" || issue.type === "weak_evidence" || issue.type === "unsupported_scope" || issue.type === "unhandled_objection" || issue.type === "missing_risk"
+}
+
+function targetForIssue(narrative: NarrativeStateV1, issue: NarrativeReadinessIssue): { type: NarrativeResearchGapTargetType; id?: string } {
+  if (issue.claimId) return { type: "claim", id: issue.claimId }
+  const objection = narrative.objections.find((item) => item.text === issue.claimText)
+  if (objection) return { type: "objection", id: objection.id }
+  if (issue.type === "missing_risk") return { type: "decision", id: narrative.decision.action ? stableResearchGapId(`decision:${narrative.decision.action}`) : undefined }
+  return { type: "narrative", id: narrative.id }
+}
+
+function questionForIssue(issue: NarrativeReadinessIssue): string {
+  if (issue.claimText && issue.type === "missing_evidence") return `Find evidence for claim: ${issue.claimText}`
+  if (issue.claimText && issue.type === "weak_evidence") return `Strengthen evidence for claim: ${issue.claimText}`
+  if (issue.claimText && issue.type === "unsupported_scope") return `Resolve unsupported scope for claim: ${issue.claimText}`
+  if (issue.type === "unhandled_objection") return `Find response or evidence for objection: ${issue.claimText ?? issue.message}`
+  if (issue.type === "missing_risk") return "Identify risk, assumption, caveat, or tradeoff handling for the recommendation."
+  return issue.message
+}
+
+function ensureNarrative(state: DecksState): NarrativeStateV1 {
+  state.narrative = normalizeNarrativeState(state)
+  return state.narrative
+}
+
+function recordResearchGapAction(state: DecksState, type: "research.gap_created" | "research.gap_updated" | "research.gap_closed", gaps: NarrativeResearchGap[], timestamp: string): void {
+  recordWorkspaceAction(state, {
+    type,
+    actor: "revela-decks",
+    timestamp,
+    inputs: { narrativeId: state.narrative?.id },
+    outputs: { gaps: gaps.map((gap) => ({ id: gap.id, status: gap.status, targetType: gap.targetType, targetId: gap.targetId, findingsFile: gap.findingsFile, evidenceBindingIds: gap.evidenceBindingIds })) },
+    status: "success",
+    summary: `${type === "research.gap_created" ? "Created" : type === "research.gap_closed" ? "Closed" : "Updated"} ${gaps.length} research gap${gaps.length === 1 ? "" : "s"}.`,
+    nodeIds: gaps.map((gap) => gap.id),
+  })
+}
+
+function gapSortValue(gap: NarrativeResearchGap): number {
+  const statusValue: Record<NarrativeResearchGapStatus, number> = { open: 0, in_progress: 1, findings_saved: 2, attached: 3, evidence_bound: 4, closed: 5 }
+  const priorityValue = gap.priority === "high" ? 0 : gap.priority === "medium" ? 1 : 2
+  return statusValue[gap.status] * 10 + priorityValue
+}
+
+function mergeIds(existing: string[] | undefined, next: string[] | undefined): string[] {
+  return [...new Set([...(existing ?? []), ...(next ?? [])].map(clean).filter(Boolean))].sort()
+}
+
+function clean(value: string | undefined): string {
+  return value?.trim() ?? ""
+}

package/lib/narrative-state/types.ts

@@ -0,0 +1,172 @@
+export type NarrativeStatus = "draft" | "needs_research" | "needs_user_confirmation" | "ready_for_approval" | "approved"
+
+export type NarrativeClaimKind = "context" | "problem" | "opportunity" | "evidence" | "recommendation" | "risk" | "assumption" | "ask"
+
+export type NarrativeEvidenceStatus = "supported" | "partial" | "weak" | "missing" | "not_required"
+
+export type NarrativeResearchGapStatus = "open" | "in_progress" | "findings_saved" | "attached" | "evidence_bound" | "closed"
+
+export type NarrativeResearchGapTargetType = "claim" | "objection" | "risk" | "decision" | "narrative"
+
+export type NarrativeClaimRelationType = "leads_to" | "supports" | "depends_on" | "contrasts_with" | "constrains" | "answers"
+
+export interface NarrativeStateV1 {
+  version: 1
+  id: string
+  status: NarrativeStatus
+  audience: AudienceIntent
+  decision: DecisionIntent
+  thesis?: NarrativeThesis
+  claims: NarrativeClaim[]
+  claimRelations?: NarrativeClaimRelation[]
+  evidenceBindings: NarrativeEvidenceBinding[]
+  objections: NarrativeObjection[]
+  risks: NarrativeRisk[]
+  researchGaps?: NarrativeResearchGap[]
+  approvals: NarrativeApproval[]
+  updatedAt: string
+}
+
+export interface AudienceIntent {
+  primary: string
+  secondary?: string[]
+  beliefBefore: string
+  beliefAfter: string
+  decisionContext?: string
+  successCriteria?: string[]
+}
+
+export interface DecisionIntent {
+  action: string
+  owner?: string
+  deadline?: string
+  decisionType?: "approve" | "invest" | "prioritize" | "align" | "choose" | "understand" | "other"
+  consequenceOfNoDecision?: string
+}
+
+export interface NarrativeThesis {
+  id: string
+  statement: string
+  confidence: "high" | "medium" | "low"
+  caveat?: string
+}
+
+export interface NarrativeClaim {
+  id: string
+  kind: NarrativeClaimKind
+  text: string
+  importance: "central" | "supporting" | "background"
+  evidenceRequired: boolean
+  evidenceStatus: NarrativeEvidenceStatus
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats?: string[]
+}
+
+export interface NarrativeClaimRelation {
+  id: string
+  fromClaimId: string
+  toClaimId: string
+  relation: NarrativeClaimRelationType
+  rationale?: string
+}
+
+export interface NarrativeEvidenceBinding {
+  id: string
+  claimId: string
+  source: string
+  sourcePath?: string
+  findingsFile?: string
+  quote?: string
+  location?: string
+  url?: string
+  caveat?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength: "strong" | "partial" | "weak"
+}
+
+export interface NarrativeObjection {
+  id: string
+  text: string
+  claimId?: string
+  priority: "high" | "medium" | "low"
+  response?: string
+}
+
+export interface NarrativeRisk {
+  id: string
+  text: string
+  claimId?: string
+  severity: "high" | "medium" | "low"
+  mitigation?: string
+}
+
+export interface NarrativeResearchGap {
+  id: string
+  targetType: NarrativeResearchGapTargetType
+  targetId?: string
+  question: string
+  status: NarrativeResearchGapStatus
+  priority: "high" | "medium" | "low"
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  createdFromIssueType?: NarrativeReadinessIssueType
+  notes?: string
+  createdAt: string
+  updatedAt: string
+  closedAt?: string
+}
+
+export interface NarrativeApproval {
+  id: string
+  narrativeHash: string
+  approvedAt: string
+  approvedBy: "user" | "override"
+  scope: "narrative" | "render_override"
+  note?: string
+}
+
+export type NarrativeReadinessStatus = "blocked" | "needs_research" | "needs_user_confirmation" | "ready_for_approval" | "approved"
+
+export type NarrativeReadinessIssueType =
+  | "missing_audience"
+  | "missing_belief_shift"
+  | "missing_decision"
+  | "missing_thesis"
+  | "claim_chain_gap"
+  | "missing_evidence"
+  | "weak_evidence"
+  | "unsupported_scope"
+  | "unhandled_objection"
+  | "missing_risk"
+  | "approval_missing"
+  | "approval_stale"
+  | "artifact_stale"
+  | "research_findings_unattached"
+  | "research_gap_open"
+
+export interface NarrativeReadinessIssue {
+  type: NarrativeReadinessIssueType
+  severity: "blocker" | "warning"
+  message: string
+  suggestedAction: string
+  claimId?: string
+  claimText?: string
+  source?: string
+}
+
+export interface NarrativeReadinessResult {
+  status: NarrativeReadinessStatus
+  narrativeHash: string
+  reviewedAt: string
+  blockers: string[]
+  warnings: string[]
+  issues: NarrativeReadinessIssue[]
+  approval?: {
+    current: boolean
+    stale: boolean
+    latest?: NarrativeApproval
+  }
+  nextActions: string[]
+}

package/lib/prompt-builder.ts

@@ -1,9 +1,14 @@
 /**
- * Prompt builder — assembles the three-layer system prompt.
+ * Prompt builder — assembles Revela system prompts.
  *
- * Layer 1: SKILL.md     — core protocol (conversation flow, HTML rules, quality)
- * Layer 2: DOMAIN.md    — domain knowledge (report structure, terminology)
- * Layer 3: DESIGN.md    — visual style (colors, fonts, animations, layout)
+ * Narrative mode:
+ *   Layer 1: NARRATIVE_SKILL.md — audience/decision/claim/evidence readiness
+ *   Layer 2: DOMAIN.md          — domain reasoning guidance when present
+ *
+ * Deck-render mode:
+ *   Layer 1: SKILL.md           — legacy deck render protocol (HTML rules, quality)
+ *   Layer 2: DOMAIN.md          — domain structure/terminology
+ *   Layer 3: DESIGN.md          — visual style (colors, fonts, animations, layout)
  *
  * When the active DESIGN.md has @section markers, only the global section,
  * layouts section, and a generated component index are injected into the
@@ -37,22 +42,43 @@ import { childLog } from "./log"
 
 const promptLog = childLog("prompt-builder")
 
-/** Path to SKILL.md shipped with this package. */
+export type PromptMode = "narrative" | "deck-render"
+
+export interface BuildPromptOptions {
+  mode?: PromptMode
+  designName?: string
+  domainName?: string
+}
+
+/** Path to deck-render SKILL.md shipped with this package. */
 const SKILL_MD_PATH = resolve(__dirname, "..", "skill", "SKILL.md")
+const NARRATIVE_SKILL_MD_PATH = resolve(__dirname, "..", "skill", "NARRATIVE_SKILL.md")
 
 /**
- * Build the combined system prompt and write it to _active-prompt.md.
+ * Build the active system prompt and write it to _active-prompt.md.
+ *
+ * Backward-compatible call form:
+ * - buildPrompt() builds the default narrative prompt.
+ * - buildPrompt("aurora", "general") builds the default narrative prompt with active metadata overrides.
+ *
+ * New call form:
+ * - buildPrompt({ mode: "narrative" }) avoids design/HTML instructions.
+ * - buildPrompt({ mode: "deck-render" }) preserves the legacy deck render prompt.
  *
- * @param designName - Override design (defaults to active)
- * @param domainName - Override domain (defaults to active)
  * @returns The path to the written file.
  */
-export function buildPrompt(designName?: string, domainName?: string): string {
-  const design = designName || activeDesign()
-  const domain = domainName || activeDomain()
-
-  // Layer 1 — SKILL.md
-  const coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
+export function buildPrompt(options?: BuildPromptOptions): string
+export function buildPrompt(designName?: string, domainName?: string): string
+export function buildPrompt(optionsOrDesignName?: BuildPromptOptions | string, legacyDomainName?: string): string {
+  const options = typeof optionsOrDesignName === "object" && optionsOrDesignName !== null
+    ? optionsOrDesignName
+    : { designName: optionsOrDesignName, domainName: legacyDomainName }
+  const mode: PromptMode = options.mode || "narrative"
+  const design = options.designName || activeDesign()
+  const domain = options.domainName || activeDomain()
+
+  // Layer 1 — core skill for the selected prompt mode.
+  const coreSkill = readFileSync(mode === "deck-render" ? SKILL_MD_PATH : NARRATIVE_SKILL_MD_PATH, "utf-8")
 
   // Check for preview.html
   const designDir = join(DESIGNS_DIR, design)
@@ -73,30 +99,37 @@ export function buildPrompt(designName?: string, domainName?: string): string {
     })
   }
 
-  // Layer 3 — DESIGN.md: marker-aware or full-text fallback
-  const designSkill = buildDesignLayer(design)
+  // Layer 3 — DESIGN.md: deck-render only. Narrative mode must not inject
+  // visual CSS, layout catalogs, component indexes, or HTML skeleton rules.
+  const designSkill = mode === "deck-render" ? buildDesignLayer(design) : ""
 
   // Assemble header
-  const header =
-    `<!-- Active design: ${design} -->\n` +
-    `<!-- Active domain: ${domain} -->\n` +
-    `<!-- Design files: ${designDir}/ -->\n` +
-    `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
-    `${previewLine}\n\n`
-
-  // Three-layer concatenation: Header → SKILL → Domain → Design
+  const header = mode === "deck-render"
+    ? `<!-- Revela prompt mode: deck-render -->\n` +
+      `<!-- Active design: ${design} -->\n` +
+      `<!-- Active domain: ${domain} -->\n` +
+      `<!-- Design files: ${designDir}/ -->\n` +
+      `<!--   - DESIGN.md — metadata + style instructions (injected below) -->\n` +
+      `${previewLine}\n\n`
+    : `<!-- Revela prompt mode: narrative -->\n` +
+      `<!-- Active domain: ${domain} -->\n` +
+      `<!-- Design layer intentionally omitted in narrative mode. Use deck-render mode before writing deck artifacts. -->\n\n`
+
+  // Concatenation: Header → Skill → Domain → Design (deck-render only)
   const parts = [header, coreSkill]
   if (domainSkill) {
     parts.push(`\n\n---\n\n${domainSkill}`)
   }
-  parts.push(`\n\n---\n\n${designSkill}`)
+  if (designSkill) {
+    parts.push(`\n\n---\n\n${designSkill}`)
+  }
 
   const prompt = parts.join("")
 
   // Write to _active-prompt.md
   mkdirSync(CONFIG_DIR, { recursive: true })
   writeFileSync(ACTIVE_PROMPT_FILE, prompt, "utf-8")
-  promptLog.info("prompt rebuilt", { design, domain, bytes: prompt.length })
+  promptLog.info("prompt rebuilt", { mode, design, domain, bytes: prompt.length })
 
   return ACTIVE_PROMPT_FILE
 }

package/lib/workspace-state/evidence-status.ts

@@ -40,15 +40,25 @@ export interface EvidenceStatusMatch {
   slideIndex?: number
   slideTitle?: string
   claimId?: string
+  canonicalClaimId?: string
   claimText?: string
   claimEvidenceSensitive?: boolean
   claimEvidenceSupport?: string
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
 }
 
 export interface EvidenceStatusEvidence extends EvidenceRef {
   slideIndex: number
   slideTitle: string
   hasDetail: boolean
+  evidenceBindingId?: string
+  claimId?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: "strong" | "partial" | "weak"
 }
 
 export interface EvidenceStatusGap {
@@ -159,9 +169,14 @@ function projectMatch(match: InspectionElementMatch): EvidenceStatusMatch {
     slideIndex: match.slide?.index,
     slideTitle: match.slide?.title,
     claimId: match.claim?.id,
+    canonicalClaimId: match.claim?.canonicalClaimId,
     claimText: match.claim?.text,
     claimEvidenceSensitive: match.claim?.evidenceSensitive,
     claimEvidenceSupport: match.claim?.evidenceSupport,
+    evidenceBindingIds: match.claim?.evidenceBindingIds ?? [],
+    supportedScope: match.claim?.supportedScope,
+    unsupportedScope: match.claim?.unsupportedScope,
+    caveats: match.claim?.caveats ?? [],
   }
 }
 
@@ -235,7 +250,12 @@ function relevantSearchDiagnostics(issues: ReadinessIssue[], match: InspectionEl
 
 function actionTraceForMatch(actions: WorkspaceAction[], match: InspectionElementMatch): EvidenceStatusActionTrace[] {
   const slideNodeId = match.slide ? `slide:${match.slide.index}` : undefined
-  const evidenceKeys = new Set(match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile].filter((value): value is string => Boolean(value))))
+  const evidenceKeys = new Set([
+    match.claim?.id,
+    match.claim?.canonicalClaimId,
+    ...(match.claim?.evidenceBindingIds ?? []),
+    ...match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile, item.evidenceBindingId, item.claimId]),
+  ].filter((value): value is string => Boolean(value)))
   return actions
     .filter((action) => actionRelevantToMatch(action, slideNodeId, evidenceKeys))
     .slice(-12)