@cyber-dash-tech/revela 0.4.3 → 0.5.0

package/plugin.ts

@@ -15,8 +15,8 @@
  */
 
 import type { Plugin } from "@opencode-ai/plugin"
-import { existsSync, readFileSync } from "fs"
-import { extname, basename } from "path"
+import { existsSync, mkdirSync, readFileSync } from "fs"
+import { extname, basename, join } from "path"
 import { tmpdir } from "os"
 import { seedBuiltinDesigns } from "./lib/design/designs"
 import { seedBuiltinDomains } from "./lib/domain/domains"
@@ -52,6 +52,26 @@ import {
   parseDesignsEditArgs,
   buildDesignsEditPrompt,
 } from "./lib/commands/designs-new"
+import { buildInitPrompt } from "./lib/commands/init"
+import { parseRememberArgs, buildRememberPrompt } from "./lib/commands/remember"
+import { buildReviewPrompt } from "./lib/commands/review"
+import {
+  buildDecksMemoryLayer,
+  extractDeckHtmlTargetsFromPatch,
+  extractPatchTextArg,
+  hasDecksMemory,
+  isDeckHtmlPath,
+  setPatchTextArg,
+} from "./lib/decks-memory"
+import {
+  buildDecksStatePromptLayer,
+  checkDeckStateWriteReadiness,
+  DECKS_STATE_FILE,
+  extractDecksStateTargetsFromPatch,
+  hasDecksState,
+  isDecksStatePath,
+} from "./lib/decks-state"
+import decksTool from "./tools/decks"
 import designsAuthorTool from "./tools/designs-author"
 import designsTool from "./tools/designs"
 import domainsTool from "./tools/domains"
@@ -103,6 +123,9 @@ async function sendIgnoredMessage(
 
 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>()
 
   // ── Startup: seed + build initial prompt ────────────────────────────────
   try {
@@ -191,6 +214,35 @@ const server: Plugin = (async (pluginCtx) => {
         await handleDisable(send)
         throw new Error("__REVELA_DISABLE_HANDLED__")
       }
+      if (sub === "init") {
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildInitPrompt({ exists: hasDecksState(workspaceRoot), legacyExists: hasDecksMemory(workspaceRoot), workspaceRoot }),
+        } as any)
+        return
+      }
+      if (sub === "remember") {
+        const parsed = parseRememberArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_REMEMBER_USAGE_HANDLED__")
+        }
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildRememberPrompt({ memory: parsed.memory, exists: hasDecksState(workspaceRoot), legacyExists: hasDecksMemory(workspaceRoot) }),
+        } as any)
+        return
+      }
+      if (sub === "review") {
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildReviewPrompt({ slug: param || undefined, exists: hasDecksState(workspaceRoot), legacyExists: hasDecksMemory(workspaceRoot), workspaceRoot }),
+        } as any)
+        return
+      }
       if (sub === "designs" && !param) {
         await handleDesignsList(send)
         throw new Error("__REVELA_DESIGNS_LIST_HANDLED__")
@@ -268,6 +320,7 @@ const server: Plugin = (async (pluginCtx) => {
 
     // ── LLM tools: designs, domains, research, document materials, qa ─────
     tool: {
+      "revela-decks": decksTool,
       "revela-designs": designsTool,
       "revela-designs-author": designsAuthorTool,
       "revela-domains": domainsTool,
@@ -354,7 +407,23 @@ const server: Plugin = (async (pluginCtx) => {
         // Skip OpenCode internal system agents (title generator, summary, compaction)
         if (INTERNAL_AGENT_SIGNATURES.some((sig) => systemText.includes(sig))) return
 
-        const prompt = readFileSync(ACTIVE_PROMPT_FILE, "utf-8")
+        let prompt = readFileSync(ACTIVE_PROMPT_FILE, "utf-8")
+        try {
+          const stateLayer = buildDecksStatePromptLayer(workspaceRoot)
+          if (stateLayer) prompt += "\n\n" + stateLayer
+        } catch (e) {
+          childLog("decks-state").warn("failed to load DECKS.json state", {
+            error: e instanceof Error ? e.message : String(e),
+          })
+        }
+        try {
+          const memoryLayer = buildDecksMemoryLayer(workspaceRoot)
+          if (memoryLayer) prompt += "\n\n" + memoryLayer
+        } catch (e) {
+          childLog("decks-memory").warn("failed to load DECKS.md memory", {
+            error: e instanceof Error ? e.message : String(e),
+          })
+        }
         if (output.system.length > 0) {
           output.system[output.system.length - 1] += "\n\n" + prompt
         } else {
@@ -371,21 +440,135 @@ const server: Plugin = (async (pluginCtx) => {
       }
     },
 
-    // ── Pre-read: intercept binary files before read executes ──────────────
-    // Handles DOCX/PPTX/XLSX — read tool would Effect.fail on these.
-    // Extracts text → writes temp .txt → redirects args.filePath.
+    // ── Pre-tool processing ────────────────────────────────────────────────
+    // - read: intercept DOCX/PPTX/XLSX before read executes.
+    // - write/apply_patch: gate decks/*.html on DECKS.json readiness.
     "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
 
-      if (input.tool !== "read") return
-      try {
-        await preRead(output.args)
-      } catch (e) {
-        childLog("preRead").warn("extraction failed", {
-          filePath: (output.args as any)?.filePath,
-          error: e instanceof Error ? e.message : String(e),
+      if (input.tool === "write") {
+        const filePath: string = (output.args as any)?.filePath ?? ""
+        if (isDecksStatePath(filePath)) {
+          const blockedDir = join(workspaceRoot, ".opencode", "revela", "blocked-writes")
+          mkdirSync(blockedDir, { recursive: true })
+          const blockedPath = join(blockedDir, "DECKS-json-direct-write.blocked.md")
+          const blocker = `${DECKS_STATE_FILE} is a controlled Revela state file. Use the revela-decks tool instead of write/apply_patch.`
+          ;(output.args as any).filePath = blockedPath
+          ;(output.args as any).content = `# Revela Blocked State Write
+
+The attempted write to \`${filePath}\` was blocked.
+
+Reason: ${blocker}
+
+Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSlides\`, or \`review\`.
+`
+          blockedDeckWrites.set(filePath, blocker)
+          childLog("decks-state").warn("blocked direct DECKS.json write", { filePath, blockedPath })
+          return
+        }
+        if (!isDeckHtmlPath(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") {
+        const args = output.args as Record<string, unknown>
+        const patchText = extractPatchTextArg(args)
+        if (!patchText) return
+
+        const stateTargets = extractDecksStateTargetsFromPatch(patchText)
+        if (stateTargets.length > 0) {
+          const blockedDir = join(workspaceRoot, ".opencode", "revela", "blocked-writes")
+          mkdirSync(blockedDir, { recursive: true })
+          const blockedRelativePath = `.opencode/revela/blocked-writes/DECKS-json-direct-patch-${Date.now()}.blocked.md`
+          const blocker = `${DECKS_STATE_FILE} is a controlled Revela state file. Use the revela-decks tool instead of write/apply_patch.`
+          const blockedPatch = `*** Begin Patch
+*** Add File: ${blockedRelativePath}
++# Revela Blocked State Patch
++
++The attempted patch touching \`${stateTargets.join(", ")}\` was blocked.
++
++Reason: ${blocker}
++
++Next step: use \`revela-decks\` with action \`init\`, \`upsertDeck\`, \`upsertSlides\`, or \`review\`.
+*** End Patch`
+          setPatchTextArg(args, blockedPatch)
+          blockedDeckPatches.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
+
+        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") {
+        try {
+          await preRead(output.args)
+        } catch (e) {
+          childLog("preRead").warn("extraction failed", {
+            filePath: (output.args as any)?.filePath,
+            error: e instanceof Error ? e.message : String(e),
+          })
+        }
       }
     },
 
@@ -413,8 +596,19 @@ const server: Plugin = (async (pluginCtx) => {
       // ── Auto layout QA after writing decks/*.html ─────────────────────
       if (input.tool === "write") {
         const filePath: string = input.args?.filePath ?? ""
+        const blockedReason = blockedDeckWrites.get(filePath)
+        if (blockedReason) {
+          blockedDeckWrites.delete(filePath)
+          const existing = (output as any).result ?? ""
+          ;(output as any).result =
+            (existing ? existing + "\n\n" : "") +
+            "---\n\n**[revela state gate]** Write was blocked.\n\n" +
+            `${blockedReason}\n\n` +
+            "Use the `revela-decks` tool or complete the DECKS.json review workflow instead."
+          return
+        }
         // Only trigger for HTML files inside a decks/ directory
-        if (!filePath.match(/decks\/[^/]+\.html$/)) return
+        if (!isDeckHtmlPath(filePath)) return
 
         try {
           // Extract design's allowed class vocabulary for compliance checking
@@ -444,6 +638,18 @@ const server: Plugin = (async (pluginCtx) => {
         }
         return
       }
+
+      if (input.tool === "apply_patch" && blockedDeckPatches.size > 0) {
+        const [blockedPath, blockedReason] = blockedDeckPatches.entries().next().value ?? []
+        if (blockedPath) blockedDeckPatches.delete(blockedPath)
+        const existing = (output as any).result ?? ""
+        ;(output as any).result =
+          (existing ? existing + "\n\n" : "") +
+          "---\n\n**[revela prewrite gate]** Deck HTML patch was blocked.\n\n" +
+          `${blockedReason}\n\n` +
+          "Run `/revela review` or complete the same DECKS.json review workflow before patching the deck."
+        return
+      }
     },
   }
 }) satisfies Plugin

package/skill/SKILL.md

@@ -36,38 +36,57 @@ If the user's first message already answers most of these, skip what's clear and
 only ask about what's missing. If the message is detailed enough, proceed directly
 to Phase 1.5.
 
-Once you have the user's answers, **derive the deck slug** from the topic:
-lowercase, hyphens, no spaces (e.g. "AI Investment Shift" → `ai-investment-shift`).
-Tell the user: "I'll save this deck as `decks/{slug}.html`." They can correct the
-name at this point.
-
-### Phase 1.5 — Deck Initialization & Resume Check
-
-After confirming the deck slug, check whether this deck has been worked on before:
-
-1. Run `ls researches/{slug}/` (or `glob researches/{slug}/*.md`).
-2. **If the directory does not exist (new deck):** proceed to Phase 2.
-3. **If research files already exist (resuming):** list the files and ask the user:
-
-   > 我发现 `researches/{slug}/` 下已有以下研究文件：
-   > - `market-data.md`
-   > - `competitor-profile.md`
-   > - _(etc.)_
-   >
-   > 你想：
-   > a. 直接使用现有研究，跳到幻灯片计划阶段
-   > b. 补充某些方向的研究（请告诉我哪些方向）
-   > c. 全部重新研究
-
-   Then act based on the user's reply:
-   - **a** → skip Phase 3, go directly to Phase 4 (read existing files first)
-   - **b** → run research agents only for the specified axes, then Phase 4
-   - **c** → proceed to Phase 2 normally (full research)
-
-All subsequent file paths in this session use the confirmed slug:
+Once you have the user's answers, form a concise **Research Brief** before doing
+research or writing HTML. The brief should capture:
+- user goal and decision/context the deck must support
+- audience and language
+- working thesis or angle, if one has emerged
+- key questions the deck must answer
+- known workspace sources from `DECKS.json`, user attachments, or visible files
+- desired output shape, slide count, and visual direction
+
+If the brief is unclear, ask 1–3 targeted clarification questions. Do not force
+the user to provide a research topic command; the working topic emerges from the
+conversation.
+
+### Phase 1.5 — Project State, Working Slug & Active Deck
+
+Before research, use the `revela-decks` tool with action `read` or `init` to
+inspect `DECKS.json`. Treat it as the source of truth for project context,
+source material index, explicit user preferences, prior deck history, active
+deck specs, per-slide content/layout/components, write readiness, and open
+questions. Do not write or patch `DECKS.json` directly.
+
+Derive a **working slug** from the Research Brief: lowercase, hyphens, no spaces
+(e.g. "AI Investment Shift" → `ai-investment-shift`). The slug is only a file
+path handle for this deck/research cache; the user does not need to supply it as
+a command. Tell the user: "I'll save this deck as `decks/{slug}.html`." They can
+correct the name at this point.
+
+Check whether this deck has been worked on before:
+1. Run `glob researches/{slug}/*.md`.
+2. If research files already exist, list them and ask whether to reuse, supplement,
+   or replace the existing research.
+3. If the user chooses reuse, read the existing files before Phase 4.
+4. If the user chooses supplement or replace, use the existing files to avoid
+   duplicate work and proceed through Phase 3 only for missing or stale axes.
+
+All subsequent file paths in this session use the working slug:
 - Slides file: `decks/{slug}.html`
 - Research dir: `researches/{slug}/`
 
+Create or update the active deck in `DECKS.json` through `revela-decks` actions
+`upsertDeck` and `upsertSlides`. Keep the deck spec current as work progresses:
+- `goal` — purpose and decision/context
+- `audience`, `language`, `slideCount`, `outputPath`, and `theme`
+- `requiredInputs` — checklist state for prewrite readiness
+- `researchPlan` — axes, status, and findings files
+- `slides` — confirmed per-slide title, purpose, layout, components, content, evidence, visuals, and status
+- `writeReadiness` — computed by `revela-decks review`, never manually set by the LLM
+
+Do not store temporary Active Deck checklist state in `User Preferences` or
+`Workflow Preferences`.
+
 ### Phase 2 — Select Design
 
 Once you have the user's answers (especially topic, audience, and visual style),
@@ -99,151 +118,90 @@ Do not proceed to Phase 3 until the user has replied to the design question.
 
 ---
 
-### Phase 3 — Research-First Protocol (自主调研)
-
-**Always execute this phase — regardless of whether the user mentions reference
-files.** Your job is to proactively gather all available information before
-writing a single slide.
-
-#### Execution Model — Parallel, Not Sequential
-
-Research layers are **NOT** a sequential fallback chain where you stop once
-"enough" data is collected. Execute them as parallel workstreams:
-
-```
-┌─────────────────────────────────────────────┐
-│  LAUNCH TOGETHER (as your first action):    │
-│                                             │
-│  ┌──────────────┐  ┌─────────────────────┐  │
-│  │ Layer 1      │  │ Layer 2             │  │
-│  │ Workspace    │  │ Research agents     │  │
-│  │ scan         │  │ (parallel per axis) │  │
-│  └──────────────┘  └─────────────────────┘  │
-│                                             │
-│  After both complete:                       │
-│  ┌──────────────┐                           │
-│  │ Layer 3      │  AI knowledge fills gaps  │
-│  └──────────────┘                           │
-│                                             │
-│  Only if still missing:                     │
-│  ┌──────────────┐                           │
-│  │ Layer 4      │  Ask the user             │
-│  └──────────────┘                           │
-└─────────────────────────────────────────────┘
-```
-
-**Layer 1 and Layer 2 launch in parallel as the FIRST action after Phase 2.**
-Do not wait for Layer 1 results before launching Layer 2. Do not use Layer 3
-(AI knowledge) as an excuse to skip Layer 2.
+### Phase 3 — Conversation-Driven Research Protocol (自主调研)
 
----
+Research is gated by the Research Brief. Do not launch research just because a
+phase says so; launch it when the deck needs facts, numbers, case studies,
+competitive profiles, market data, external validation, or image/source leads
+that are not already available in the conversation and `DECKS.json`.
 
-#### Layer 1 — Workspace Documents
+If the deck is simple, internal, or fully specified by the user, you may proceed
+to Phase 4 without new research. If the brief is too vague to research, ask the
+user 1–3 focused questions before launching agents.
 
-Scan the workspace for reference documents using the built-in file tools
-(`ls`, `glob`). Look for files with extensions:
-`.pdf`, `.xlsx`, `.xls`, `.docx`, `.doc`, `.pptx`, `.ppt`, `.csv`
-and images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`
+#### Research Brief Before Agents
 
-Use the `read` tool to read each relevant file. The Revela plugin transparently
-extracts text from binary formats (PDF, Excel, Word, PowerPoint) — just call
-`read` normally on any file type.
+Before starting research agents, write a brief for yourself with:
+- working slug for `researches/{slug}/`
+- user goal and audience
+- thesis or decision the deck should support
+- key questions and time period
+- relevant `DECKS.json` sourceMaterials or user-provided files
+- axes to research and desired output for each axis
 
----
+You do not need to ask the user to approve the slug unless the filename matters.
 
-#### Layer 2 — Deep Research via Research Agents (MANDATORY)
+#### Deep Research via `revela-research` Subagents
 
-**This layer is mandatory whenever the `@revela-research` subagent (Task tool
-with `subagent_type: "revela-research"`) is available.** It is the primary
-research workhorse — not an optional enhancement.
+`revela-research` is an OpenCode subagent, **not a tool**. Launch it through the
+Task tool with `subagent_type: "revela-research"`. Do not write or imply a
+`revela-research(...)` tool call.
 
-The research agent searches the web using `websearch` for broad discovery and
-`webfetch` for depth on specific pages, reads workspace documents, and writes
-structured findings to a single file `researches/{slug}/{axis-name}.md`
-in the workspace. Use the deck slug confirmed in Phase 1.5 — do not invent a
-different slug at this point.
+Decompose the Research Brief into independent axes before launching agents. Each
+axis gets one focused subagent brief. When multiple axes are needed, launch all
+agents in a single message with parallel Task tool calls.
 
-##### Parallelization Rule
+Each subagent brief must specify:
+- shared working slug for `researches/{slug}/`
+- axis filename, such as `market-data`, `competitor-profile`, or `technology-trends`
+- the research question, time period, geography, and evidence standard
+- relevant `DECKS.json` sourceMaterials or user files to prioritize
+- whether web research is needed and what types of sources are preferred
 
-Decompose the topic into **independent research axes** before launching agents.
-Each axis gets its own dedicated agent with a focused brief. Launch ALL agents
-in a single message (parallel Task tool calls).
+The subagent writes exactly one file through `revela-research-save`:
+`researches/{slug}/{axis-name}.md`.
 
-**How to decompose:** Look at what the presentation needs to cover. Each major
-entity, comparison dimension, or macro question is a separate axis. Decompose
-based on topic breadth and the depth each axis warrants — a narrow topic may
-need 2 axes; a complex comparison may need 4 or more. Typical decompositions:
+#### Workspace Memory and Freshness
 
-| Topic type | Example axes |
-|---|---|
-| Company comparison | Company A data, Company B data, market context |
-| Industry analysis | Market sizing, competitive landscape, technology trends, regulatory |
-| Investment thesis | Opportunity metrics, risk factors, comparable deals, macro trends |
-| Product strategy | User research, competitor features, technology feasibility, go-to-market |
+Use `revela-decks` action `read` before scanning from scratch. Its
+`workspace.sourceMaterials` state is the workspace material index created by
+`/revela init`. Use it to choose candidate files and avoid repeated deep reading.
 
-Launch ALL agents in a single message (parallel Task tool calls).
+Use `revela-workspace-scan` or file tools as a freshness check when needed:
+- discover files added after `/revela init`
+- verify that listed source files still exist
+- find user-provided attachments or topic-specific files not in `DECKS.json`
 
-Each agent's brief should specify:
-- The deck slug from Phase 1.5 (e.g. `ai-investment-shift`) — all agents share the same slug
-- The axis name for their file (e.g. `anthropic-profile`, `openai-challenges`, `market-trends`)
-- What to research and what time period to focus on
-- An explicit instruction to use `websearch` (e.g. "Use the websearch tool to find relevant market reports, news, and data for this axis.")
+Avoid repeated expensive work. Only call `revela-extract-document-materials` or
+deep-read files that are relevant to the current Research Brief.
 
-##### After Agents Complete
+#### After Agents Complete
 
-List and read the findings files: `ls researches/{slug}/`, then `read`
-each `.md` file. Each file contains structured `## Data`, `## Cases`,
-`## Images`, and `## Gaps` sections — use these directly as slide material.
-Cross-reference agent findings with workspace documents (Layer 1). Flag any
-contradictions. Once all findings are read, proceed to Phase 4 to present the
-slide plan.
+List and read the findings files in `researches/{slug}/`. Each file contains
+structured `## Data`, `## Cases`, `## Images`, and `## Gaps` sections. Use these
+directly as slide material, cross-reference them with workspace documents, and
+flag contradictions.
 
-**Anti-pattern — NEVER do this:**
-- Do NOT use `websearch` directly — it is blocked by the Revela plugin;
-  use research agents instead.
-- Do NOT run a few quick searches, decide "that's enough data", and skip the
-  research agent. The agent's job is deep, systematic research — ad-hoc
-  fetches cannot replace it.
+After research is complete, use `revela-decks` only for stable, cross-session
+state updates. Do not write temporary hypotheses, unsupported conclusions,
+secrets, or inferred user preferences. User and workflow preferences require
+explicit user intent to remember.
 
----
+#### AI Knowledge and User Questions
 
-#### Layer 3 — AI Knowledge (Supplementary)
+Use AI knowledge only to fill remaining gaps around verified sources. Mark it
+with `[Source: AI 公开知识，建议核实]` and never present it as verified fact.
 
-After Layer 1 and Layer 2 results are in, use your training data to fill
-remaining gaps: industry context, historical background, technical explanations.
-
-**Critical:** Always mark AI-sourced information with
-`[Source: AI 公开知识，建议核实]`. Never present AI knowledge as verified fact.
-
-This layer is supplementary — it adds context around the hard data from
-Layers 1 and 2. It must never be the primary source for quantitative claims
-(market size, revenue, growth rates, etc.).
-
----
-
-#### Layer 4 — Ask the User (Last Resort Only)
-
-Only ask the user for information that Layers 1, 2, and 3 cannot cover.
-When asking, first report what you already know:
-
-> 我已从 workspace 文档和在线调研中获取了以下信息：
-> [brief list of covered topics with source counts]
->
-> 以下关键信息我无法从现有资料中获取，需要您补充：
-> 1. [specific missing item]
-> 2. [specific missing item]
-
----
+Ask the user only for information that `DECKS.json`, workspace files, research
+agents, and AI knowledge cannot cover. When asking, briefly state what you have
+already checked and what specific missing information is needed.
 
 #### Rules
 
-- **NEVER** ask the user for information that exists in workspace documents
-- **NEVER** skip workspace scanning — even if the user's message seems self-contained
-- **NEVER** ask "do you have reference files?" — just scan and find out
-- **NEVER** use `websearch` — it is blocked; delegate to research agents instead
-- **NEVER** collapse multiple research axes into a single agent call
-- **ALWAYS** launch research agents as your first action (parallel with workspace scan)
-- **ALWAYS** decompose the topic into independent axes before launching agents
+- **NEVER** use `websearch` directly from the primary agent; delegate web research to `revela-research` subagents
+- **NEVER** call `revela-research` as a tool; use Task with `subagent_type: "revela-research"`
+- **NEVER** collapse distinct research axes into one broad agent brief when parallel focused briefs would be clearer
+- **ALWAYS** use `revela-decks` action `read` before deciding what research is needed
 - **ALWAYS** read each `researches/{slug}/{axis}.md` after agents complete
 - Use the `read` tool for all file types — binary formats are handled transparently
 ---
@@ -327,6 +285,11 @@ Then ask:
 - On confirmation → proceed to Phase 5
 - On change request → update the table and ask again
 
+After the user confirms the slide plan, update `DECKS.json` through `revela-decks`:
+- Call `upsertDeck` to mark completed `requiredInputs` only when explicitly satisfied.
+- Call `upsertSlides` with the confirmed per-slide content, layout, components, and evidence.
+- Keep write readiness blocked until Phase 5 calls `revela-decks review` and the tool returns ready.
+
 ---
 
 ### Phase 5 — Generate
@@ -338,9 +301,13 @@ Then ask:
    you plan to use (comma-separated, e.g. `layout: "cover,two-col,stats,card-grid"`).
 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. Generate HTML that **exactly matches** the fetched examples — copy the HTML structure verbatim.
+4. Use `revela-decks` action `upsertDeck` to mark `requiredInputs.designLayoutsFetched` complete.
+5. Run `/revela review {slug}` 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.
 
-**NEVER skip steps 2–3. NEVER generate HTML from memory or prior knowledge of the design.**
+**NEVER skip steps 2–6. NEVER generate HTML from memory or prior knowledge of the design.**
+**NEVER write `decks/*.html` while `DECKS.json` says `writeReadiness.status` is `blocked`.**
 
 Once the fetch is complete, generate the complete HTML file in one shot.
 
@@ -356,6 +323,9 @@ After generating, briefly tell the user:
 - How to navigate (arrow keys / swipe)
 - One line invitation to request changes
 
+Then use `revela-decks` to record written/QA status when available. Preserve
+stable decisions in deck memory when useful.
+
 For change requests: re-generate the **entire** file (don't patch). Apply the
 change and silently overwrite the same `decks/{slug}.html` filename.