@cyber-dash-tech/revela 0.10.0 → 0.12.0

package/lib/narrative-state/render-plan.ts

@@ -0,0 +1,207 @@
+import { upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec } from "../decks-state"
+import { computeNarrativeHash } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import { narrativeToBrief } from "./project-compat"
+import type { NarrativeClaim, NarrativeEvidenceBinding, NarrativeStateV1 } from "./types"
+
+export interface CompileDeckPlanOptions {
+  now?: string
+}
+
+export interface CompileDeckPlanResult {
+  compiled: boolean
+  skipped: boolean
+  reason?: string
+  narrativeHash: string
+  slideCount: number
+  slides: SlideSpec[]
+}
+
+export function compileDeckPlanFromNarrative(state: DecksState, options: CompileDeckPlanOptions = {}): { state: DecksState; result: CompileDeckPlanResult } {
+  const narrative = normalizeNarrativeState(state)
+  const narrativeHash = computeNarrativeHash(narrative)
+  const approval = hasCurrentApprovalOrOverride(narrative, narrativeHash)
+  if (!approval) {
+    return {
+      state: { ...state, narrative },
+      result: {
+        compiled: false,
+        skipped: true,
+        reason: "narrative must be approved or explicitly overridden before compiling a deck plan",
+        narrativeHash,
+        slideCount: 0,
+        slides: [],
+      },
+    }
+  }
+
+  const deckKey = state.activeDeck ?? Object.keys(state.decks)[0]
+  const deck = deckKey ? state.decks[deckKey] : undefined
+  const slug = deck?.slug ?? state.activeDeck ?? "deck"
+  const slides = buildSlides(narrative)
+  const requiredInputs: Partial<RequiredInputs> = {
+    topicClarified: true,
+    audienceClarified: Boolean(narrative.audience.primary),
+    languageDecided: Boolean(deck?.language),
+    sourceMaterialsIdentified: (state.workspace.sourceMaterials ?? []).length > 0 || narrative.evidenceBindings.length > 0,
+    researchNeedAssessed: true,
+    researchFindingsRead: narrative.evidenceBindings.some((binding) => Boolean(binding.findingsFile)),
+    slidePlanConfirmed: false,
+    designLayoutsFetched: false,
+  }
+  let next = upsertDeck({ ...state, narrative }, {
+    ...deck,
+    slug,
+    goal: deck?.goal || narrative.thesis?.statement || narrative.decision.action,
+    audience: narrative.audience.primary || deck?.audience,
+    outputPath: deck?.outputPath,
+    narrativeBrief: narrativeToBrief(narrative),
+    requiredInputs: {
+      ...(deck?.requiredInputs ?? {}),
+      ...requiredInputs,
+    } as RequiredInputs,
+    writeReadiness: deck?.writeReadiness ?? { status: "blocked" as const, blockers: [] },
+  })
+  next = upsertSlides(next, slug, slides)
+  next.narrative = { ...narrative, updatedAt: options.now ?? narrative.updatedAt }
+
+  return {
+    state: next,
+    result: {
+      compiled: true,
+      skipped: false,
+      narrativeHash,
+      slideCount: slides.length,
+      slides,
+    },
+  }
+}
+
+function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
+  const slides: SlideSpec[] = []
+  const centralClaims = narrative.claims.filter((claim) => claim.importance === "central")
+  const supportingClaims = narrative.claims.filter((claim) => claim.importance !== "central")
+  const evidenceByClaim = new Map<string, NarrativeEvidenceBinding[]>()
+  for (const binding of narrative.evidenceBindings) {
+    const list = evidenceByClaim.get(binding.claimId) ?? []
+    list.push(binding)
+    evidenceByClaim.set(binding.claimId, list)
+  }
+
+  slides.push({
+    index: slides.length + 1,
+    title: "Decision Context",
+    purpose: "Frame the audience belief shift and decision required before presenting the recommendation.",
+    narrativeRole: "context",
+    layout: "cover",
+    qa: false,
+    components: [],
+    content: {
+      headline: narrative.thesis?.statement || narrative.decision.action || "Narrative context",
+      body: [
+        narrative.audience.beliefBefore ? `Before: ${narrative.audience.beliefBefore}` : "Before belief needs confirmation.",
+        narrative.audience.beliefAfter ? `After: ${narrative.audience.beliefAfter}` : "After belief needs confirmation.",
+      ],
+      bullets: narrative.decision.action ? [`Decision: ${narrative.decision.action}`] : [],
+    },
+    evidence: [],
+    status: "planned",
+  })
+
+  for (const claim of centralClaims) slides.push(claimSlide(slides.length + 1, claim, evidenceByClaim.get(claim.id) ?? []))
+  if (supportingClaims.length > 0) {
+    slides.push({
+      index: slides.length + 1,
+      title: "Supporting Logic",
+      purpose: "Connect supporting claims to the central recommendation without overloading the main proof slides.",
+      narrativeRole: "evidence",
+      layout: "card-grid",
+      qa: true,
+      components: ["card"],
+      content: {
+        headline: "Supporting claims and boundaries",
+        bullets: supportingClaims.slice(0, 5).map((claim) => claim.text),
+      },
+      evidence: supportingClaims.flatMap((claim) => (evidenceByClaim.get(claim.id) ?? []).map(evidenceRefFromBinding)),
+      status: "planned",
+    })
+  }
+
+  if (narrative.risks.length > 0 || narrative.objections.length > 0) {
+    slides.push({
+      index: slides.length + 1,
+      title: "Risks And Objections",
+      purpose: "Make caveats and stakeholder objections visible before asking for a decision.",
+      narrativeRole: "risk",
+      layout: "two-col",
+      qa: true,
+      components: ["card"],
+      content: {
+        headline: "What could break the recommendation",
+        bullets: [
+          ...narrative.risks.slice(0, 3).map((risk) => risk.mitigation ? `${risk.text} Mitigation: ${risk.mitigation}` : risk.text),
+          ...narrative.objections.slice(0, 3).map((objection) => objection.response ? `${objection.text} Response: ${objection.response}` : objection.text),
+        ],
+      },
+      evidence: [],
+      status: "planned",
+    })
+  }
+
+  slides.push({
+    index: slides.length + 1,
+    title: "Decision Ask",
+    purpose: "Close with the explicit decision or action requested from the audience.",
+    narrativeRole: "ask",
+    layout: "closing",
+    qa: false,
+    components: [],
+    content: {
+      headline: narrative.decision.action || "Confirm the decision",
+      bullets: narrative.decision.consequenceOfNoDecision ? [`If no decision: ${narrative.decision.consequenceOfNoDecision}`] : [],
+    },
+    evidence: [],
+    status: "planned",
+  })
+
+  return slides
+}
+
+function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvidenceBinding[]): SlideSpec {
+  return {
+    index,
+    title: titleFromClaim(claim),
+    purpose: `Prove or bound this ${claim.importance} ${claim.kind} claim for the audience.`,
+    narrativeRole: claim.kind === "risk" || claim.kind === "assumption" ? "risk" : claim.kind === "ask" ? "ask" : claim.kind === "recommendation" ? "recommendation" : "evidence",
+    layout: "two-col",
+    qa: true,
+    components: ["card"],
+    content: {
+      headline: claim.text,
+      bullets: [claim.supportedScope, claim.unsupportedScope ? `Unsupported scope: ${claim.unsupportedScope}` : undefined, ...(claim.caveats ?? [])].filter((item): item is string => Boolean(item)),
+    },
+    evidence: bindings.map(evidenceRefFromBinding),
+    status: "planned",
+  }
+}
+
+function evidenceRefFromBinding(binding: NarrativeEvidenceBinding): EvidenceRef {
+  return {
+    source: binding.source,
+    quote: binding.quote,
+    url: binding.url,
+    sourcePath: binding.sourcePath,
+    location: binding.location,
+    findingsFile: binding.findingsFile,
+    caveat: binding.caveat || binding.unsupportedScope,
+  }
+}
+
+function titleFromClaim(claim: NarrativeClaim): string {
+  const words = claim.text.split(/\s+/).filter(Boolean).slice(0, 6).join(" ")
+  return words || claim.kind
+}
+
+function hasCurrentApprovalOrOverride(narrative: NarrativeStateV1, narrativeHash: string): boolean {
+  return narrative.approvals.some((approval) => approval.narrativeHash === narrativeHash && (approval.scope === "narrative" && approval.approvedBy === "user" || approval.scope === "render_override" || approval.approvedBy === "override"))
+}

package/lib/narrative-state/types.ts

@@ -0,0 +1,139 @@
+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 interface NarrativeStateV1 {
+  version: 1
+  id: string
+  status: NarrativeStatus
+  audience: AudienceIntent
+  decision: DecisionIntent
+  thesis?: NarrativeThesis
+  claims: NarrativeClaim[]
+  evidenceBindings: NarrativeEvidenceBinding[]
+  objections: NarrativeObjection[]
+  risks: NarrativeRisk[]
+  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 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 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"
+
+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/qa/export-gate.ts

@@ -1,6 +1,13 @@
 import { formatReport, runQA } from "./index"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
+
+export interface ExportQAGateOptions {
+  workspaceRoot?: string
+}
+
+export async function assertExportQAPassed(filePath: string, options: ExportQAGateOptions = {}): Promise<void> {
+  if (options.workspaceRoot) assertDeckHtmlContractValid(options.workspaceRoot, filePath)
 
-export async function assertExportQAPassed(filePath: string): Promise<void> {
   const report = await runQA(filePath)
   if (report.totalIssues === 0) return
 

package/lib/refine/open.ts

@@ -2,6 +2,7 @@ import { existsSync } from "fs"
 import { ACTIVE_PROMPT_FILE } from "../config"
 import { ctx } from "../ctx"
 import { seedBuiltinDesigns } from "../design/designs"
+import { assertDeckHtmlContractValid } from "../deck-html/contract"
 import { seedBuiltinDomains } from "../domain/domains"
 import { ensureEditableDeckState } from "../edit/deck-state"
 import { openUrl } from "../edit/open"
@@ -33,6 +34,7 @@ export interface OpenRefineDeckOptions {
 export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
   const deck = resolveEditableDeck(options.workspaceRoot, target)
   const preflight = ensureEditableDeckState(options.workspaceRoot, deck)
+  assertDeckHtmlContractValid(options.workspaceRoot, deck.absoluteFile)
   const mode = options.mode ?? "edit"
 
   ctx.enabled = true
@@ -57,7 +59,7 @@ export function openRefineDeck(target: string, options: OpenRefineDeckOptions):
   return {
     deck,
     url,
-    source: deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
+    source: deck.source === "render-target" ? "render target" : deck.source === "decks-state" ? "DECKS.json" : deck.source === "file-path" ? "file path" : "fallback path",
     stateNote: preflight.changed ? "Deck state was prepared in DECKS.json for refinement." : "Deck state already points to this refinement target.",
     preflightChanged: preflight.changed,
     reusedSession: session.reused,

package/lib/workspace-state/actions.ts

@@ -0,0 +1,71 @@
+import { createHash } from "crypto"
+import type { DecksState } from "../decks-state"
+import type { WorkspaceAction, WorkspaceActionType } from "./types"
+
+export const MAX_WORKSPACE_ACTIONS = 500
+
+export interface WorkspaceActionInput {
+  type: WorkspaceActionType
+  actor?: string
+  inputs?: Record<string, unknown>
+  outputs?: Record<string, unknown>
+  status?: WorkspaceAction["status"]
+  summary?: string
+  nodeIds?: string[]
+  timestamp?: string
+}
+
+export function recordWorkspaceAction(state: DecksState, input: WorkspaceActionInput): DecksState {
+  const actions = state.actions ?? []
+  const timestamp = input.timestamp ?? new Date().toISOString()
+  const action: WorkspaceAction = {
+    id: workspaceActionId(input.type, timestamp, actions.length, input),
+    type: input.type,
+    timestamp,
+    status: input.status ?? "success",
+    ...(input.actor ? { actor: input.actor } : {}),
+    ...(input.inputs ? { inputs: compactActionPayload(input.inputs) } : {}),
+    ...(input.outputs ? { outputs: compactActionPayload(input.outputs) } : {}),
+    ...(input.summary ? { summary: input.summary } : {}),
+    ...(input.nodeIds && input.nodeIds.length > 0 ? { nodeIds: [...new Set(input.nodeIds)].sort() } : {}),
+  }
+
+  state.actions = [...actions, action].slice(-MAX_WORKSPACE_ACTIONS)
+  return state
+}
+
+export function compactActionPayload(input: Record<string, unknown>): Record<string, unknown> {
+  const output: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(input)) {
+    const compacted = compactActionValue(value)
+    if (compacted !== undefined) output[key] = compacted
+  }
+  return output
+}
+
+export function workspaceActionId(type: WorkspaceActionType, timestamp: string, sequence: number, input: Omit<WorkspaceActionInput, "timestamp">): string {
+  return `action:${timestamp}:${type}:${stableHash(JSON.stringify({ sequence, input: compactActionPayload(input as Record<string, unknown>) }))}`
+}
+
+function compactActionValue(value: unknown): unknown {
+  if (value === undefined || value === null) return undefined
+  if (typeof value === "string") {
+    const trimmed = value.trim()
+    if (!trimmed) return undefined
+    return trimmed.length > 500 ? `${trimmed.slice(0, 500).trimEnd()}... [truncated]` : trimmed
+  }
+  if (typeof value === "number" || typeof value === "boolean") return value
+  if (Array.isArray(value)) {
+    const items = value.map(compactActionValue).filter((item) => item !== undefined)
+    return items.length > 0 ? items.slice(0, 50) : undefined
+  }
+  if (typeof value === "object") {
+    const compacted = compactActionPayload(value as Record<string, unknown>)
+    return Object.keys(compacted).length > 0 ? compacted : undefined
+  }
+  return undefined
+}
+
+function stableHash(value: string): string {
+  return createHash("sha1").update(value).digest("hex").slice(0, 10)
+}

package/lib/workspace-state/compat.ts

@@ -0,0 +1,10 @@
+import type { DecksState } from "../decks-state"
+import type { DecksStateV1Projection, WorkspaceState } from "./types"
+
+export function isDecksStateV1(state: WorkspaceState): state is DecksState {
+  return state.version === 1
+}
+
+export function asDecksStateV1Projection(state: DecksState): DecksStateV1Projection {
+  return state
+}