@cyber-dash-tech/revela 0.14.0 → 0.15.1

package/skill/NARRATIVE_SKILL.md

@@ -1,64 +1,142 @@
 ---
 name: revela-narrative
-description: Build trusted narrative readiness before rendering deck artifacts
+description: Build trusted narrative state before rendering communication artifacts
 compatibility: opencode
 ---
 
 # Revela — Narrative Workspace
 
-You help the user turn source materials, research, and intent into a trusted communication narrative before any deck is rendered.
+You help the user turn source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.
 
-Default mode is narrative-first. Do not generate HTML slides, choose visual layouts, fetch design components, or ask for slide count unless the user explicitly enters a deck-render workflow.
+Decks are important, but they are render targets. The durable source of truth is the canonical narrative state: audience, decision, thesis, claims, evidence boundaries, objections, risks, research gaps, approval provenance, and artifact coverage.
 
-## Core Job
+Default mode is narrative-first. Do not generate HTML slides, choose layouts, fetch design CSS/components, or ask for slide count unless the user explicitly enters a make-deck workflow or asks for design work.
 
-Build and review the narrative state around:
-- primary audience and stakeholder context
-- audience belief before and desired belief after
-- decision or action required
-- thesis or central recommendation
-- central claims and their evidence boundaries
-- objections, risks, assumptions, caveats, and unsupported scope
-- narrative approval state and whether approval is stale
+## Workflow Model
+
+Use the same phase semantics whether the user invokes a slash command or asks in normal chat:
+
+- `Init` discovers local workspace materials, captures intent, initializes or refreshes `DECKS.json`, and creates conservative narrative state only from explicit user statements or source traces.
+- `Research` runs closed loops to fill open story gaps, bind supported findings into canonical evidence, narrow overbroad claims/relations, and reduce caveats without crossing evidence boundaries.
+- `Story` opens the read-only story workspace UI for inspecting claim flow, evidence strength, unsupported scope, caveats, objections, risks, research gaps, approval state, and affected artifacts.
+- `Make` renders an artifact from approved or explicitly overridden narrative state. Supported 0.15 targets are deck and executive brief.
+- `Refine` is the post-artifact workspace for reading, inspection, and targeted editing. Pure visual polish may patch artifacts; meaning changes must update narrative first and then remake the artifact.
+
+Public command surface:
+
+- `/revela init`
+- `/revela research`
+- `/revela story`
+- `/revela make deck`
+- `/revela make brief`
+- `/revela refine`
+- `/revela design`
+
+Compatibility aliases:
+
+- `/revela review` means a legacy story readiness report
+- `/revela narrative` means `/revela story`
+- `/revela deck` means `/revela make deck`
+- `/revela brief` means `/revela make brief`
 
 ## Workspace State
 
 Use `DECKS.json` as Revela's current compatibility workspace-state file. Do not write or patch it directly.
 
 Use `revela-decks` for state operations:
+
 - `read` to inspect current workspace state
 - `init` to register discovered source material candidates during workspace initialization
-- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, and risks
-- `upsertDeck` or `upsertSlides` only when explicitly needed by a deck/artifact workflow prompt
-- `reviewNarrative` to run deterministic narrative readiness
+- `upsertNarrative` to preserve canonical audience, decision, thesis, claims, evidence bindings, objections, risks, and research gaps
+- `reviewNarrative` to run deterministic story readiness
+- `deriveResearchGaps`, `upsertResearchGaps`, `updateResearchGap`, and `closeResearchGap` to manage research gap lifecycle
+- `attachResearchFindings` to attach saved findings to research state
+- `applyEvidenceCandidates` only when selected candidates should become canonical support
 - `approveNarrative` only when the user explicitly approves or requests an override
+- `compileDeckPlan`, `upsertDeck`, `upsertSlides`, and `review` only inside make-deck or artifact-readiness workflows
+
+Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, workspace scans, extraction cache paths, or saved research actions as narrative approval or proof by themselves.
+
+## Init Rules
+
+During init:
+
+- scan local workspace materials before asking broad questions
+- reuse `workspace.sourceMaterials` and extraction cache when fingerprints match
+- extract or read only relevant local materials; do not exhaustively process large workspaces
+- derive claims, evidence bindings, caveats, unsupported scope, source paths, quotes/snippets, pages, sheets, or slide references only when explicit support exists
+- ask the smallest missing intent questions after local evidence has been considered
+- do not require slide count, design choice, layout choice, output path, or visual style unless the user explicitly asks to make an artifact immediately
+
+## Research Rules
+
+During research:
+
+- start from open research gaps, unsupported central claims, objections, risks, and decision questions
+- run multiple review/search/bind/narrow/re-review loops when useful, stopping when no public evidence can improve the state or after the workflow limit
+- avoid generic internet research when workspace evidence already supports the claim
+- delegate external web search to the `revela-research` subagent
+- save findings through `revela-research-save`
+- treat `/revela research` as permission to attach findings and bind clearly supported evidence without item-by-item user confirmation
+- use `applyEvidenceCandidates` or `upsertNarrative` to create canonical evidence bindings when claim id, quote/snippet, source, support scope, unsupported scope, caveat, and strength are explicit
+- narrow overbroad claim scope or relation rationale when the narrower wording preserves strategic meaning and better matches the evidence
+- preserve source path, URL, location/page/sheet/slide, quote/snippet, support scope, unsupported scope, and caveat
+- keep missing or partial evidence visible instead of filling it with model assumptions; classify remaining caveats as internal-data-needed, not-publicly-researchable, source-quality-limit, or still-open
 
-Never treat `writeReadiness.status`, old review snapshots, existing `decks/*.html`, or saved research actions as narrative approval.
+## Story Rules
 
-## Narrative Review Rules
+When the user invokes `/revela story`, open the read-only story workspace UI. Do not turn that command into a blocking readiness report.
 
-When reviewing, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
+When the user invokes `/revela review` or explicitly asks for a readiness report, call `revela-decks` action `reviewNarrative` and report the tool result as authoritative.
 
 Use this report shape:
+
 - `Narrative readiness: <status>`
 - `Narrative hash: <hash>` when available
 - blockers first, with issue type, claim text when available, and suggested next action
 - warnings second, as residual risks
+- research gaps and unattached findings as next work
 - approval state last, clearly distinguishing `ready_for_approval`, `approved`, stale approval, and render override
 
 If evidence is missing, say what is missing and what should happen next. Do not invent quotes, sources, page locations, URLs, caveats, or research findings.
 
-If research findings were saved but not attached or bound, describe them as unattached research state, not proof.
-
 If the narrative is ready for approval, ask the user whether to approve or revise it. Do not approve automatically.
 
+## Make Rules
+
+For `/revela make deck` and compatible deck handoff:
+
+- switch to deck-render mode through the command workflow
+- check narrative readiness and current approval before compiling deck specs
+- use `compileDeckPlan` as the canonical narrative-to-deck planning path
+- run the deck/artifact gate with `revela-decks review` before writing HTML
+- fetch design layouts/components only after narrative handoff is valid
+- keep the HTML deck contract valid: one `<section class="slide">` per slide, canonical 1-based `data-slide-index`, and matching `DECKS.json` slide specs
+
+For `/revela make brief`, render the executive brief from canonical narrative state and graph-backed claim/evidence relationships, not from a deck summary.
+
+If story readiness, approval, evidence, or artifact blockers remain, report the blocker and suggest `/revela review`, `/revela research`, or a targeted user answer. Do not bypass with invented state.
+
+## Refine Rules
+
+Use `/revela refine` for post-artifact reading, inspection, and editing.
+
+- Reading should explain source, support strength, caveat, unsupported scope, narrative purpose, related risks/objections, research gaps, and artifact coverage.
+- Pure artifact polish may stay artifact-level: layout, typography, spacing, crop, visual hierarchy, export mechanics, and deck contract fixes.
+- Meaning-changing edits must update canonical narrative first, then run story readiness/approval or explicit override, then remake affected artifacts.
+- `/revela edit` has been removed; use `/revela refine`. Deprecated `/revela inspect` routes to Refine.
+
+## Design Surface
+
+Use `/revela design` for visual-system work: list/use/new/edit/preview/install/remove designs.
+
+Do not inject design CSS, layout catalogs, component indexes, chart rules, or deck HTML skeletons during init, research, or story. Fetch design context only for make-deck or explicit design-authoring workflows.
+
 ## Boundaries
 
 - Do not write or overwrite `decks/*.html` in narrative mode.
-- Do not call `revela-decks review` in narrative mode; that is the deck/artifact gate.
-- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks.
-- Do not fetch design CSS, layouts, components, chart rules, or HTML skeletons in narrative mode.
+- Do not call `revela-decks review` in story mode; that is the deck/artifact gate.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks or the active workflow requires it with clear support.
 - Do not store secrets, credentials, tokens, or sensitive personal information.
 - Do not infer long-term user preferences from one-off tasks.
-
-When the user wants deck/artifact readiness, direct them to `/revela deck --review`. When they want to render a deck, wait for the explicit deck workflow.
+- If source support is missing, keep the gap visible instead of making the claim sound proven.

package/skill/SKILL.md

@@ -374,7 +374,7 @@ After the user confirms the slide plan, update `DECKS.json` through `revela-deck
 3. Call `revela-designs` tool with `action: "read"` and `component` set to ALL component
    names you plan to use (comma-separated, e.g. `component: "card,stat-card,evidence-list"`).
 4. Use `revela-decks` action `upsertDeck` to mark `requiredInputs.designLayoutsFetched` complete.
-5. Run `/revela review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
+5. Run `/revela make deck --review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
 6. Use `revela-decks` action `read` and confirm `writeReadiness.status` is `ready` with no blockers.
 7. Generate HTML that **exactly matches** the fetched examples — copy the HTML structure verbatim.
 
@@ -460,16 +460,11 @@ deck HTML writes or patches. If the tool result reports compliance issues, fix
 them immediately by removing the offending classes and replacing them with the
 closest component from the Component Index.
 
-Do not run `revela-qa` after writing or editing HTML unless the user explicitly
-asks for diagnostics. PDF/PPTX export commands run hard-error pre-export QA
-automatically and will report overflow issues that must be fixed before exporting.
-
-### Inline Editing
-
-**Always include inline editing** in every generated presentation. The complete
-reference implementation is provided in the active design's `@design:foundation`
-section. Follow it exactly — pay attention to the hover-delay pattern, editable
-element selector list, and `window.getEditedHTML()` definition.
+Deck HTML writes and patches automatically run Artifact QA. If hard errors are
+reported, fix them immediately with the smallest patch; Refine opens only after
+hard errors pass. Do not add deck-local inline editing JavaScript, `contenteditable`
+handlers, `editable` classes, or `window.getEditedHTML()` implementations. Post-
+artifact editing belongs in `/revela refine`, not inside generated deck HTML.
 
 ### Image Rules
 

package/tools/decks.ts

@@ -1,6 +1,7 @@
 import { tool } from "@opencode-ai/plugin"
 import {
   createDeckSpec,
+  confirmDeckPlan,
   DECKS_STATE_FILE,
   normalizeWorkspaceDeckState,
   readOrCreateDecksState,
@@ -67,7 +68,7 @@ export default tool({
     "It stores workspace narrative state, active deck specs, per-slide content/layout/components, and computes narrative or deck readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "confirmDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
       .describe("Action to perform on DECKS.json."),
     summary: tool.schema.boolean().optional().describe("For read: return a compact summary instead of full state."),
     goal: tool.schema.string().optional().describe("For upsertDeck: deck goal."),
@@ -251,8 +252,8 @@ export default tool({
     findingsFile: tool.schema.string().optional().describe("For attachResearchFindings: workspace-relative researches/{topic}/{axis}.md file to attach to researchPlan."),
     researchAxis: tool.schema.string().optional().describe("For attachResearchFindings: researchPlan axis to attach the findings file to. Required when filename matching would be ambiguous."),
     researchStatus: tool.schema.enum(["done", "read"]).optional().describe("For attachResearchFindings: optional explicit status to set on the matched research axis."),
-    approvalNote: tool.schema.string().optional().describe("For approveNarrative: optional note explaining the approval or override."),
-    approvalBy: tool.schema.enum(["user", "override"]).optional().describe("For approveNarrative: use override only for explicit render overrides, not normal strategic approval."),
+    approvalNote: tool.schema.string().optional().describe("For approveNarrative or confirmDeckPlan: optional note explaining the approval, override, or deck plan confirmation."),
+    approvalBy: tool.schema.enum(["user", "override"]).optional().describe("For approveNarrative or confirmDeckPlan: use override only for explicit render overrides, not normal strategic approval or deck plan confirmation."),
     approvalScope: tool.schema.enum(["narrative", "render_override"]).optional().describe("For approveNarrative: narrative approval or explicit render override scope."),
     gapId: tool.schema.string().optional().describe("For updateResearchGap/closeResearchGap: canonical research gap id."),
     researchGaps: tool.schema.array(tool.schema.object({
@@ -428,6 +429,31 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: compiled.result, deck: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck] : undefined, narrative: compiled.state.narrative }, null, 2)
       }
 
+      if (args.action === "confirmDeckPlan") {
+        if (args.approvalBy && args.approvalBy !== "user") return JSON.stringify({ ok: false, error: "confirmDeckPlan requires approvalBy=user" })
+        const confirmed = confirmDeckPlan(state, {
+          approvedBy: "user",
+          note: args.approvalNote,
+        })
+        if (confirmed.result.confirmed) {
+          recordWorkspaceAction(confirmed.state, {
+            type: "deck.plan_confirmed",
+            actor: "revela-decks",
+            inputs: { activeDeck: state.activeDeck, approvalBy: "user" },
+            outputs: {
+              slug: confirmed.result.slug,
+              narrativeHash: confirmed.result.narrativeHash,
+              planHash: confirmed.result.planHash,
+            },
+            status: "success",
+            summary: args.approvalNote?.trim() || "User confirmed the compiled deck plan.",
+            nodeIds: [confirmed.state.narrative?.id, confirmed.result.slug ? `deck:${confirmed.result.slug}` : undefined].filter((item): item is string => Boolean(item)),
+          })
+        }
+        writeDecksState(workspaceRoot, confirmed.state)
+        return JSON.stringify({ ok: confirmed.result.confirmed, path: DECKS_STATE_FILE, result: confirmed.result, deck: confirmed.state.activeDeck ? confirmed.state.decks[confirmed.state.activeDeck] : undefined }, null, 2)
+      }
+
       if (args.action === "backfillClaimRefs") {
         const backfilled = backfillSlideClaimRefsFromCoverage(state)
         writeDecksState(workspaceRoot, backfilled.state)

package/tools/narrative-view.ts

@@ -10,7 +10,7 @@ export default tool({
     "Render Revela's read-only narrative claim-flow UI from the current deterministic narrative map plus an optional localized display model. " +
     "This tool validates display IDs against DECKS.json, opens a local HTML view, and never mutates workspace state.",
   args: {
-    language: tool.schema.string().describe("UI language request from /revela narrative. May be any language tag or language name, such as en, zh-CN, fr, de, Korean, Arabic, or Portuguese-BR."),
+    language: tool.schema.string().describe("UI language request from /revela story or /revela narrative. May be any language tag or language name, such as en, zh-CN, fr, de, Korean, Arabic, or Portuguese-BR."),
     narrativeHash: tool.schema.string().optional().describe("Narrative hash from the prompt projection. Used to detect stale display prompts."),
     displayModel: tool.schema.object({
       version: tool.schema.number().describe("Must be 1."),

package/tools/qa.ts

@@ -1,7 +1,7 @@
 /**
  * tools/qa.ts
  *
- * revela-qa — Hard-error quality assurance for generated slide HTML files.
+ * revela-qa — Artifact quality assurance for generated slide HTML files.
  *
  * Exposed as a manual diagnostic tool. Export commands run pre-export QA automatically.
  */
@@ -9,15 +9,16 @@
 import { tool } from "@opencode-ai/plugin"
 import { resolve } from "path"
 import { existsSync } from "fs"
-import { runQA, formatReport } from "../lib/qa"
+import { extractDesignClasses } from "../lib/design/designs"
+import { formatArtifactQAReport, runArtifactQA } from "../lib/qa/artifact"
 
 export default tool({
   description:
-    "Run hard-error checks on a generated slide HTML file. " +
+    "Run artifact QA on a generated slide HTML file. " +
     "Opens the file in a headless browser and measures actual rendered geometry. " +
-    "Checks for element overflow. " +
+    "Checks deck contract, component compliance, exact 1920x1080 canvas, scrollbars, element overflow, text overflow, and content/evidence density warnings. " +
     "Returns a structured report with specific issues and fix instructions. " +
-    "Normally PDF/PPTX export commands run this automatically; call it directly only for explicit diagnostics.",
+    "Deck writes and PDF/PPTX export commands run QA automatically; call it directly for explicit diagnostics.",
   args: {
     file: tool.schema
       .string()
@@ -39,20 +40,25 @@ export default tool({
     }
 
     try {
-      const report = await runQA(filePath)
-      const formatted = formatReport(report)
+      let vocabulary
+      try {
+        vocabulary = extractDesignClasses()
+      } catch {
+        // Design may not be installed or may have no markers.
+      }
+      const report = await runArtifactQA({ workspaceRoot: directory || process.cwd(), filePath, vocabulary })
+      const formatted = formatArtifactQAReport(report)
 
       // Prepend a compact JSON summary for programmatic use if needed
       const jsonSummary = JSON.stringify({
-        totalIssues: report.totalIssues,
-        errors: report.errorCount,
+        passed: report.passed,
+        errors: report.hardErrorCount,
         warnings: report.warningCount,
-        slidesWithIssues: report.slides.filter((s) => s.issues.length > 0).map((s) => s.index + 1),
       })
 
       return `<!-- QA Summary: ${jsonSummary} -->\n\n${formatted}`
     } catch (err: any) {
-      return `Error running hard-error QA: ${err?.message ?? String(err)}\n\nMake sure Chrome is installed at /Applications/Google Chrome.app`
+      return `Error running artifact QA: ${err?.message ?? String(err)}\n\nMake sure Chrome is installed at /Applications/Google Chrome.app`
     }
   },
 })