@cyber-dash-tech/revela 0.14.0 → 0.15.1

package/plugin.ts

@@ -23,6 +23,7 @@ import { seedBuiltinDomains } from "./lib/domain/domains"
 import { buildPrompt } from "./lib/prompt-builder"
 import { ACTIVE_PROMPT_FILE } from "./lib/config"
 import { ctx } from "./lib/ctx"
+import { formatCommandIntentSystemBlock, setPendingCommandIntent, takePendingCommandIntent } from "./lib/command-intent"
 import { preRead } from "./lib/read-hooks"
 import { postRead } from "./lib/read-hooks"
 import { extractPdfText } from "./lib/read-hooks/extractors/pdf"
@@ -48,9 +49,8 @@ import { buildPptxNotesPrompt, handlePptx, parsePptxArgs, resolvePptxDeck } from
 import { handleEdit } from "./lib/commands/edit"
 import { handleInspect } from "./lib/commands/inspect"
 import { handleRefine } from "./lib/commands/refine"
-import { formatDeckHtmlContractReport, validateDeckHtmlContract } from "./lib/deck-html/contract"
-import { ensureEditableDeckOpenForChange } from "./lib/edit/open"
-import { hasLiveEditorSessionForFile } from "./lib/edit/server"
+import { formatArtifactQAReport, runArtifactQA } from "./lib/qa/artifact"
+import { ensureRefineDeckOpenForChange } from "./lib/refine/open"
 import { handleDesignsPreview } from "./lib/commands/designs-preview"
 import {
   parseDesignsNewArgs,
@@ -59,8 +59,9 @@ import {
   buildDesignsEditPrompt,
 } from "./lib/commands/designs-new"
 import { buildInitPrompt } from "./lib/commands/init"
+import { buildResearchPrompt } from "./lib/commands/research"
 import { handleBrief, parseBriefArgs } from "./lib/commands/brief"
-import { buildNarrativeViewPrompt, handleNarrative, parseNarrativeArgs } from "./lib/commands/narrative"
+import { buildNarrativeViewPrompt, handleNarrative, parseNarrativeArgs, parseStoryArgs } from "./lib/commands/narrative"
 import { parseRememberArgs, buildRememberPrompt } from "./lib/commands/remember"
 import { buildDeckPrompt, buildDeckReviewPrompt, buildReviewPrompt } from "./lib/commands/review"
 import {
@@ -71,7 +72,6 @@ import {
 } from "./lib/decks-memory"
 import {
   buildDecksStatePromptLayer,
-  checkDeckStateWriteReadiness,
   DECKS_STATE_FILE,
   extractDecksStateTargetsFromPatch,
   hasDecksState,
@@ -96,7 +96,6 @@ import pptxTool from "./tools/pptx"
 import createEditTool from "./tools/edit"
 import { RESEARCH_PROMPT, RESEARCH_AGENT_SIGNATURE } from "./lib/agents/research-prompt"
 import { NARRATIVE_REVIEWER_PROMPT, NARRATIVE_REVIEWER_SIGNATURE } from "./lib/agents/narrative-reviewer-prompt"
-import { formatReport, runComplianceQA } from "./lib/qa"
 import { extractDesignClasses } from "./lib/design/designs"
 import { log, childLog } from "./lib/log"
 
@@ -152,53 +151,29 @@ const server: Plugin = (async (pluginCtx) => {
   const client = pluginCtx.client
   const workspaceRoot = pluginCtx.directory
   const blockedDeckWrites = new Map<string, string>()
-  const blockedDeckPatches = new Map<string, string>()
+  const blockedPatches = new Map<string, string>()
 
-  async function appendComplianceReport(filePath: string, output: any): Promise<void> {
-    if (!isDeckHtmlPath(filePath)) return
+  async function runPostWriteArtifactQA(filePath: string, output: any): Promise<boolean> {
+    if (!isDeckHtmlPath(filePath)) return true
 
     try {
       let vocabulary
       try {
         vocabulary = extractDesignClasses()
       } catch {
-        // Design may not be installed or may have no markers — skip compliance.
+        // Design may not be installed or may have no markers — skip compliance vocabulary.
       }
 
-      const report = runComplianceQA(filePath, vocabulary)
-      if (report.totalIssues === 0) return
-
-      appendToolResult(
-        output,
-        "---\n\n**[revela design compliance]** Static check completed:\n\n" +
-        formatReport(report)
-      )
-    } catch (e) {
-      childLog("compliance").warn("static compliance failed", {
-        filePath,
-        error: e instanceof Error ? e.message : String(e),
-      })
-    }
-  }
-
-  async function appendDeckHtmlContractReport(filePath: string, output: any): Promise<void> {
-    if (!isDeckHtmlPath(filePath)) return
-
-    try {
-      const report = validateDeckHtmlContract(workspaceRoot, filePath)
-      if (report.status === "valid" || report.status === "skipped") return
-
-      appendToolResult(
-        output,
-        "---\n\n**[revela deck HTML contract]** Slide identity check failed:\n\n" +
-        formatDeckHtmlContractReport(report) +
-        "\n\nFix every `<section class=\"slide\">` to use the matching 1-based `data-slide-index` from DECKS.json before inspection or export."
-      )
+      const report = await runArtifactQA({ workspaceRoot, filePath, vocabulary })
+      appendToolResult(output, "---\n\n" + formatArtifactQAReport(report))
+      return report.passed
     } catch (e) {
-      childLog("deck-contract").warn("deck HTML contract report failed", {
+      childLog("artifact-qa").warn("post-write artifact QA failed", {
         filePath,
         error: e instanceof Error ? e.message : String(e),
       })
+      appendToolResult(output, "---\n\n## Artifact QA: FAILED\n\nError running artifact QA: " + (e instanceof Error ? e.message : String(e)))
+      return false
     }
   }
 
@@ -206,17 +181,38 @@ const server: Plugin = (async (pluginCtx) => {
     return input?.sessionID ?? input?.session?.id ?? input?.context?.sessionID ?? ""
   }
 
-  function ensureEditorOpenAfterDeckChange(filePath: string, sessionID: string): void {
+  function queueWorkflowCommand(input: {
+    sessionID: string
+    name: string
+    mode: "narrative" | "deck-render"
+    visibleText: string
+    hiddenPrompt: string
+    output: any
+  }): void {
+    ctx.enabled = true
+    buildPrompt({ mode: input.mode })
+    setPendingCommandIntent({
+      sessionID: input.sessionID,
+      name: input.name,
+      mode: input.mode,
+      visibleText: input.visibleText,
+      hiddenPrompt: input.hiddenPrompt,
+    })
+    input.output.parts.length = 0
+    input.output.parts.push({ type: "text", text: input.visibleText } as any)
+  }
+
+  function ensureRefineOpenAfterDeckChange(filePath: string, sessionID: string): void {
     if (!isDeckHtmlPath(filePath) || !sessionID) return
 
     try {
-      ensureEditableDeckOpenForChange("", {
+      ensureRefineDeckOpenForChange("", {
         client,
         sessionID,
         workspaceRoot,
       })
     } catch (e) {
-      childLog("edit").warn("failed to ensure visual editor after deck change", {
+      childLog("refine").warn("failed to ensure Refine after deck change", {
         filePath,
         error: e instanceof Error ? e.message : String(e),
       })
@@ -239,7 +235,7 @@ const server: Plugin = (async (pluginCtx) => {
       opencodeConfig.command ??= {}
       opencodeConfig.command["revela"] = {
         template: "",
-        description: "Revela — AI slide deck generator (enable/disable, manage designs & domains)",
+        description: "Revela — narrative artifact workspace (init, research, story, make, refine, design)",
       }
 
       // Register the research subagent.
@@ -329,12 +325,14 @@ const server: Plugin = (async (pluginCtx) => {
         throw new Error("__REVELA_DISABLE_HANDLED__")
       }
       if (sub === "init") {
-        buildPrompt({ mode: "narrative" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildInitPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "init",
+          mode: "narrative",
+          visibleText: "Initialize Revela workspace.",
+          hiddenPrompt: buildInitPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
         return
       }
       if (sub === "remember") {
@@ -343,28 +341,74 @@ const server: Plugin = (async (pluginCtx) => {
           await send(parsed.error)
           throw new Error("__REVELA_REMEMBER_USAGE_HANDLED__")
         }
-        buildPrompt({ mode: "narrative" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildRememberPrompt({ memory: parsed.memory, exists: hasDecksState(workspaceRoot) }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "remember",
+          mode: "narrative",
+          visibleText: "Remember Revela workspace preference.",
+          hiddenPrompt: buildRememberPrompt({ memory: parsed.memory, exists: hasDecksState(workspaceRoot) }),
+          output,
+        })
+        return
+      }
+      if (sub === "research") {
+        if (param) {
+          await send("`/revela research` does not accept arguments yet. Add the research question in normal chat, or run it to work from open story gaps.")
+          throw new Error("__REVELA_RESEARCH_USAGE_HANDLED__")
+        }
+        queueWorkflowCommand({
+          sessionID,
+          name: "research",
+          mode: "narrative",
+          visibleText: "Research Revela story gaps.",
+          hiddenPrompt: buildResearchPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
         return
       }
       if (sub === "review") {
         if (param) {
-          await send("`/revela review` no longer accepts a deck name. It reviews the current workspace narrative. Use `/revela deck --review` for deck/artifact readiness.")
+          await send("`/revela review` no longer accepts a deck name. It is a compatibility alias for `/revela story`. Use `/revela make deck --review` for deck/artifact readiness.")
           throw new Error("__REVELA_REVIEW_USAGE_HANDLED__")
         }
-        buildPrompt({ mode: "narrative" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "review",
+          mode: "narrative",
+          visibleText: "Review Revela story readiness.",
+          hiddenPrompt: buildReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
+        return
+      }
+      if (sub === "story") {
+        const parsed = parseStoryArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_STORY_USAGE_HANDLED__")
+        }
+        queueWorkflowCommand({
+          sessionID,
+          name: "story",
+          mode: "narrative",
+          visibleText: "Open Revela story workspace.",
+          hiddenPrompt: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
+          output,
+        })
         return
       }
       if (sub === "narrative") {
+        if (!param) {
+          queueWorkflowCommand({
+            sessionID,
+            name: "narrative",
+            mode: "narrative",
+            visibleText: "Open Revela story workspace.",
+            hiddenPrompt: buildNarrativeViewPrompt({ workspaceRoot, language: "en" }),
+            output,
+          })
+          return
+        }
         const parsed = parseNarrativeArgs(param)
         if (!parsed.ok) {
           await send(parsed.error)
@@ -374,12 +418,14 @@ const server: Plugin = (async (pluginCtx) => {
           await handleNarrative({ workspaceRoot, openBrowser: true, language: parsed.args.language }, send)
           throw new Error("__REVELA_NARRATIVE_HANDLED__")
         }
-        buildPrompt({ mode: "narrative" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "narrative view",
+          mode: "narrative",
+          visibleText: "Open read-only Revela narrative map.",
+          hiddenPrompt: buildNarrativeViewPrompt({ workspaceRoot, language: parsed.args.language }),
+          output,
+        })
         return
       }
       if (sub === "brief") {
@@ -391,26 +437,62 @@ const server: Plugin = (async (pluginCtx) => {
         await handleBrief({ workspaceRoot, outputPath: parsed.args.outputPath }, send)
         throw new Error("__REVELA_BRIEF_HANDLED__")
       }
+      if (sub === "make") {
+        const target = args[1]?.toLowerCase() ?? ""
+        const makeParam = args.slice(2).join(" ")
+        if (target === "deck") {
+          if (makeParam && makeParam !== "--review") {
+            await send("Usage: `/revela make deck` starts approved-narrative deck handoff; `/revela make deck --review` reviews deck/artifact readiness.")
+            throw new Error("__REVELA_MAKE_DECK_USAGE_HANDLED__")
+          }
+          queueWorkflowCommand({
+            sessionID,
+            name: makeParam ? "make deck --review" : "make deck",
+            mode: "deck-render",
+            visibleText: makeParam ? "Review Revela deck artifact readiness." : "Make Revela deck from approved story.",
+            hiddenPrompt: makeParam
+              ? buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot })
+              : buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+            output,
+          })
+          return
+        }
+        if (target === "brief") {
+          const parsed = parseBriefArgs(makeParam)
+          if (!parsed.ok) {
+            await send(parsed.error.replace("/revela brief", "/revela make brief"))
+            throw new Error("__REVELA_MAKE_BRIEF_USAGE_HANDLED__")
+          }
+          await handleBrief({ workspaceRoot, outputPath: parsed.args.outputPath }, send)
+          throw new Error("__REVELA_MAKE_BRIEF_HANDLED__")
+        }
+        await send("Usage: `/revela make deck [--review]` or `/revela make brief [workspace-relative-output.md]`.")
+        throw new Error("__REVELA_MAKE_USAGE_HANDLED__")
+      }
       if (sub === "deck") {
         if (param && param !== "--review") {
-          await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness.")
+          await send("Usage: `/revela deck` starts approved-narrative deck handoff; `/revela deck --review` reviews deck/artifact readiness. These are compatibility aliases for `/revela make deck`.")
           throw new Error("__REVELA_DECK_USAGE_HANDLED__")
         }
         if (!param) {
-          buildPrompt({ mode: "deck-render" })
-          output.parts.length = 0
-          output.parts.push({
-            type: "text",
-            text: buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-          } as any)
+          queueWorkflowCommand({
+            sessionID,
+            name: "deck",
+            mode: "deck-render",
+            visibleText: "Make Revela deck from approved story.",
+            hiddenPrompt: buildDeckPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+            output,
+          })
           return
         }
-        buildPrompt({ mode: "deck-render" })
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: "deck --review",
+          mode: "deck-render",
+          visibleText: "Review Revela deck artifact readiness.",
+          hiddenPrompt: buildDeckReviewPrompt({ exists: hasDecksState(workspaceRoot), workspaceRoot }),
+          output,
+        })
         return
       }
       if (sub === "refine") {
@@ -423,7 +505,7 @@ const server: Plugin = (async (pluginCtx) => {
       }
       if (sub === "edit") {
         if (param) {
-          await send("`/revela edit` is deprecated and does not accept a target. Use `/revela refine` for the unified refinement workspace.")
+          await send("`/revela edit` has been removed. Use `/revela refine` for the unified reading, inspection, and editing workspace.")
           throw new Error("__REVELA_EDIT_USAGE_HANDLED__")
         }
         await handleEdit({ client, sessionID, workspaceRoot }, send)
@@ -457,17 +539,94 @@ const server: Plugin = (async (pluginCtx) => {
         await handleDesignsAdd(param, send)
         throw new Error("__REVELA_DESIGNS_ADD_HANDLED__")
       }
+      if (sub === "design") {
+        const designAction = args[1]?.toLowerCase() ?? "list"
+        const designParam = args.slice(2).join(" ")
+        if (designAction === "list") {
+          if (designParam) {
+            await send("Usage: `/revela design list`.")
+            throw new Error("__REVELA_DESIGN_LIST_USAGE_HANDLED__")
+          }
+          await handleDesignsList(send)
+          throw new Error("__REVELA_DESIGN_LIST_HANDLED__")
+        }
+        if (designAction === "use") {
+          if (!designParam) {
+            await send("Usage: `/revela design use <name>`.")
+            throw new Error("__REVELA_DESIGN_USE_USAGE_HANDLED__")
+          }
+          await handleDesignsActivate(designParam, send)
+          throw new Error("__REVELA_DESIGN_USE_HANDLED__")
+        }
+        if (designAction === "add") {
+          if (!designParam) {
+            await send("Usage: `/revela design add <url|github:user/repo|local-path>`.")
+            throw new Error("__REVELA_DESIGN_ADD_USAGE_HANDLED__")
+          }
+          await handleDesignsAdd(designParam, send)
+          throw new Error("__REVELA_DESIGN_ADD_HANDLED__")
+        }
+        if (designAction === "rm" || designAction === "remove") {
+          if (!designParam) {
+            await send("Usage: `/revela design rm <name>`.")
+            throw new Error("__REVELA_DESIGN_RM_USAGE_HANDLED__")
+          }
+          await handleDesignsRemove(designParam, send)
+          throw new Error("__REVELA_DESIGN_RM_HANDLED__")
+        }
+        if (designAction === "preview") {
+          await handleDesignsPreview(designParam, send)
+          throw new Error("__REVELA_DESIGN_PREVIEW_HANDLED__")
+        }
+        if (designAction === "new") {
+          const parsed = parseDesignsNewArgs(designParam)
+          if (!parsed.ok) {
+            await send(parsed.error.replaceAll("/revela designs-new", "/revela design new"))
+            throw new Error("__REVELA_DESIGN_NEW_USAGE_HANDLED__")
+          }
+          queueWorkflowCommand({
+            sessionID,
+            name: `design new ${parsed.name}`,
+            mode: "deck-render",
+            visibleText: `Create Revela design ${parsed.name}.`,
+            hiddenPrompt: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
+            output,
+          })
+          return
+        }
+        if (designAction === "edit") {
+          const parsed = parseDesignsEditArgs(designParam)
+          if (!parsed.ok) {
+            await send(parsed.error.replaceAll("/revela designs-edit", "/revela design edit"))
+            throw new Error("__REVELA_DESIGN_EDIT_USAGE_HANDLED__")
+          }
+          queueWorkflowCommand({
+            sessionID,
+            name: `design edit ${parsed.name}`,
+            mode: "deck-render",
+            visibleText: `Edit Revela design ${parsed.name}.`,
+            hiddenPrompt: buildDesignsEditPrompt({ name: parsed.name }),
+            output,
+          })
+          return
+        }
+        await send("Usage: `/revela design [list|use <name>|new <name>|edit <name>|preview [name]|add <source>|rm <name>]`.")
+        throw new Error("__REVELA_DESIGN_USAGE_HANDLED__")
+      }
       if (sub === "designs-new") {
         const parsed = parseDesignsNewArgs(param)
         if (!parsed.ok) {
           await send(parsed.error)
           throw new Error("__REVELA_DESIGNS_NEW_USAGE_HANDLED__")
         }
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: `designs-new ${parsed.name}`,
+          mode: "deck-render",
+          visibleText: `Create Revela design ${parsed.name}.`,
+          hiddenPrompt: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
+          output,
+        })
         return
       }
       if (sub === "designs-edit") {
@@ -476,11 +635,14 @@ const server: Plugin = (async (pluginCtx) => {
           await send(parsed.error)
           throw new Error("__REVELA_DESIGNS_EDIT_USAGE_HANDLED__")
         }
-        output.parts.length = 0
-        output.parts.push({
-          type: "text",
-          text: buildDesignsEditPrompt({ name: parsed.name }),
-        } as any)
+        queueWorkflowCommand({
+          sessionID,
+          name: `designs-edit ${parsed.name}`,
+          mode: "deck-render",
+          visibleText: `Edit Revela design ${parsed.name}.`,
+          hiddenPrompt: buildDesignsEditPrompt({ name: parsed.name }),
+          output,
+        })
         return
       }
       if (sub === "designs-preview") {
@@ -508,8 +670,14 @@ const server: Plugin = (async (pluginCtx) => {
         if (args.notes) {
           try {
             const deck = resolvePptxDeck(workspaceRoot, args.filePath)
-            output.parts.length = 0
-            output.parts.push({ type: "text", text: buildPptxNotesPrompt(deck) } as any)
+            queueWorkflowCommand({
+              sessionID,
+              name: "pptx --notes",
+              mode: "deck-render",
+              visibleText: "Export Revela deck to PPTX with speaker notes.",
+              hiddenPrompt: buildPptxNotesPrompt(deck),
+              output,
+            })
             return
           } catch (e) {
             const msg = e instanceof Error ? e.message : String(e)
@@ -633,6 +801,11 @@ const server: Plugin = (async (pluginCtx) => {
             error: e instanceof Error ? e.message : String(e),
           })
         }
+        const sessionID = extractSessionID(input)
+        const commandIntent = takePendingCommandIntent(sessionID)
+        if (commandIntent) {
+          prompt += "\n\n" + formatCommandIntentSystemBlock(commandIntent)
+        }
         if (output.system.length > 0) {
           output.system[output.system.length - 1] += "\n\n" + prompt
         } else {
@@ -651,7 +824,7 @@ const server: Plugin = (async (pluginCtx) => {
 
     // ── Pre-tool processing ────────────────────────────────────────────────
     // - read: intercept DOCX/PPTX/XLSX before read executes.
-    // - write/apply_patch: gate decks/*.html on DECKS.json readiness.
+    // - write/apply_patch: protect DECKS.json, but do not block deck HTML edits.
     "tool.execute.before": async (input, output) => {
       log.info("[hook] tool.execute.before fired", { tool: input.tool, enabled: ctx.enabled, isResearch: ctx.isResearchAgent })
       if (!ctx.enabled) return
@@ -676,32 +849,6 @@ Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSl
           childLog("decks-state").warn("blocked direct DECKS.json write", { filePath, blockedPath })
           return
         }
-        if (!isDeckHtmlPath(filePath)) return
-        if (hasLiveEditorSessionForFile(workspaceRoot, filePath)) return
-
-        const readiness = checkDeckStateWriteReadiness(workspaceRoot, filePath) ?? {
-          ready: false,
-          slug: basename(filePath, ".html") || "deck",
-          blocker: `No ${DECKS_STATE_FILE} exists. Use revela-decks init/upsertDeck/upsertSlides/review before writing deck HTML.`,
-          blockers: [`No ${DECKS_STATE_FILE} exists.`],
-        }
-        if (readiness.ready) return
-
-        const blockedDir = join(workspaceRoot, ".opencode", "revela", "blocked-writes")
-        mkdirSync(blockedDir, { recursive: true })
-        const blockedPath = join(blockedDir, `${readiness.slug}.blocked.md`)
-        ;(output.args as any).filePath = blockedPath
-        ;(output.args as any).content = `# Revela Blocked Deck Write
-
-The attempted write to \`${filePath}\` was blocked.
-
-Reason: ${readiness.blocker}
-
-Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FILE}, then write only after the matching deck has \`writeReadiness.status\` set to \`ready\` and no blockers.
-`
-        blockedDeckWrites.set(filePath, readiness.blocker)
-        childLog("decks-memory").warn("blocked deck write", { filePath, blockedPath, blocker: readiness.blocker })
-        return
       }
 
       if (input.tool === "apply_patch") {
@@ -726,49 +873,10 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
 +Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSlides\`, or \`review\`.
 *** End Patch`
           setPatchTextArg(args, blockedPatch)
-          blockedDeckPatches.set(blockedRelativePath, blocker)
+          blockedPatches.set(blockedRelativePath, blocker)
           childLog("decks-state").warn("blocked direct DECKS.json patch", { targets: stateTargets, blockedPath: blockedRelativePath })
           return
         }
-
-        const targets = extractDeckHtmlTargetsFromPatch(patchText)
-        if (targets.length === 0) return
-        if (targets.every((target) => hasLiveEditorSessionForFile(workspaceRoot, target))) return
-
-        const blocked = targets
-          .map((target) => ({
-            target,
-            readiness: checkDeckStateWriteReadiness(workspaceRoot, target) ?? {
-              ready: false,
-              slug: basename(target, ".html") || "deck",
-              blocker: `No ${DECKS_STATE_FILE} exists. Use revela-decks init/upsertDeck/upsertSlides/review before patching deck HTML.`,
-              blockers: [`No ${DECKS_STATE_FILE} exists.`],
-            },
-          }))
-          .find((item) => !item.readiness.ready)
-        if (!blocked) return
-
-        const blockedDir = join(workspaceRoot, ".opencode", "revela", "blocked-writes")
-        mkdirSync(blockedDir, { recursive: true })
-        const blockedRelativePath = `.opencode/revela/blocked-writes/${blocked.readiness.slug}-${Date.now()}.blocked.md`
-        const blockedPatch = `*** Begin Patch
-*** Add File: ${blockedRelativePath}
-+# Revela Blocked Deck Patch
-+
-+The attempted patch touching \`${blocked.target}\` was blocked.
-+
-+Reason: ${blocked.readiness.blocker}
-+
-+Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FILE}, then patch only after the matching deck has \`writeReadiness.status\` set to \`ready\` and no blockers.
-*** End Patch`
-        setPatchTextArg(args, blockedPatch)
-        blockedDeckPatches.set(blockedRelativePath, blocked.readiness.blocker)
-        childLog("decks-memory").warn("blocked deck patch", {
-          target: blocked.target,
-          blockedPath: blockedRelativePath,
-          blocker: blocked.readiness.blocker,
-        })
-        return
       }
 
       if (input.tool === "read") {
@@ -788,7 +896,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
     // PDF: extract text, remove base64. Images: jimp compress.
     //
     // Also reports writes/patches blocked by the DECKS.json prewrite gate and
-    // runs lightweight static design compliance after successful deck changes.
+    // runs artifact QA before opening Refine after successful deck changes.
     "tool.execute.after": async (input, output) => {
       if (!ctx.enabled) return
 
@@ -805,7 +913,7 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
         return
       }
 
-      // ── Report blocked deck writes and run static compliance ──────────
+      // ── Report blocked state writes and run artifact QA ───────────────
       if (input.tool === "write") {
         const filePath: string = input.args?.filePath ?? ""
         const blockedReason = blockedDeckWrites.get(filePath)
@@ -819,20 +927,19 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
           )
           return
         }
-        await appendComplianceReport(filePath, output)
-        await appendDeckHtmlContractReport(filePath, output)
-        ensureEditorOpenAfterDeckChange(filePath, extractSessionID(input))
+        const qaPassed = await runPostWriteArtifactQA(filePath, output)
+        if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }
 
-      if (input.tool === "apply_patch" && blockedDeckPatches.size > 0) {
-        const [blockedPath, blockedReason] = blockedDeckPatches.entries().next().value ?? []
-        if (blockedPath) blockedDeckPatches.delete(blockedPath)
+      if (input.tool === "apply_patch" && blockedPatches.size > 0) {
+        const [blockedPath, blockedReason] = blockedPatches.entries().next().value ?? []
+        if (blockedPath) blockedPatches.delete(blockedPath)
         appendToolResult(
           output,
-          "---\n\n**[revela prewrite gate]** Deck HTML patch was blocked.\n\n" +
+          "---\n\n**[revela prewrite gate]** Patch was blocked.\n\n" +
           `${blockedReason}\n\n` +
-          "Run `/revela review` or complete the same DECKS.json review workflow before patching the deck."
+          "Use the `revela-decks` tool for controlled workspace state changes."
         )
         return
       }
@@ -841,18 +948,16 @@ Next step: use \`revela-decks\` or \`/revela review\` to update ${DECKS_STATE_FI
         const patchText = extractPatchTextArg(input.args as Record<string, unknown>)
         const targets = patchText ? extractDeckHtmlTargetsFromPatch(patchText) : []
         for (const target of targets) {
-          await appendComplianceReport(target, output)
-          await appendDeckHtmlContractReport(target, output)
-          ensureEditorOpenAfterDeckChange(target, extractSessionID(input))
+          const qaPassed = await runPostWriteArtifactQA(target, output)
+          if (qaPassed) ensureRefineOpenAfterDeckChange(target, extractSessionID(input))
         }
         return
       }
 
       if (input.tool === "edit") {
         const filePath = extractEditFilePath(input.args)
-        await appendComplianceReport(filePath, output)
-        await appendDeckHtmlContractReport(filePath, output)
-        ensureEditorOpenAfterDeckChange(filePath, extractSessionID(input))
+        const qaPassed = await runPostWriteArtifactQA(filePath, output)
+        if (qaPassed) ensureRefineOpenAfterDeckChange(filePath, extractSessionID(input))
         return
       }
     },