@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.19

package/docs/visual-assist-presets/web-app.md

@@ -9,7 +9,15 @@ Use this when the UI needs:
 - stronger marketing-to-product bridge than a pure desktop tool
 - responsive layout judgment
 
-Recommended `DA-VINCI.md` block:
+Choose one of these `DA-VINCI.md` blocks.
+
+### Variant 1: Adapter-Only
+
+Use when:
+
+- the product wants stronger responsive workspace composition
+- no separate reviewer role is required
+- normal structural gates are sufficient
 
 ```md
 ## Visual Assist
@@ -29,10 +37,88 @@ Recommended `DA-VINCI.md` block:
   - false
 ```
 
-Notes:
+### Variant 2: Advisory Supervisor Review
+
+Use when:
+
+- the project wants a final web style-quality readout
+- the reviewer outcome should be recorded but not block completion by default
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - responsive motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+- Require Supervisor Review:
+  - false
+```
+
+### Variant 3: Required Supervisor Signoff
+
+Use when:
+
+- the web product is brand-critical or highly visible
+- style quality must be signed off before expansion or implementation
+- weak generic SaaS output would invalidate the redesign
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
+- Scope:
+  - visual contract refinement
+  - page composition
+  - hierarchy and spacing
+  - responsive motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+- Require Supervisor Review:
+  - true
+```
+
+Notes for all variants:
 
 - keep `ui-ux-pro-max` first for product surfaces, dashboards, and operational UI
 - replace adapter names with the actual installed names for the current environment when they differ
+- keep `Design-supervisor reviewers` separate from `Preferred adapters`; reviewers judge the final web style quality after the structural gates pass
 - if the project is more brand-led than tool-led, swap the order and put `frontend-skill` first
 - do not let responsive polish erase product clarity
 - if the output feels like generic SaaS filler, switch `frontend-skill` to first and tighten the visual direction in `DA-VINCI.md`

package/docs/workflow-examples.md

@@ -84,8 +84,8 @@ Expected flow:
 8. create new or updated Pencil pages from fresh composition rather than a recolor of the old UI, preferring persistence under `.da-vinci/designs/`
 9. preflight non-trivial `batch_design` operation strings before sending them to Pencil, and keep anchor-surface batches small
 10. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
-11. prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
-12. during live design work, prefer `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
+11. require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
+12. during live design work, use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
 13. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
 14. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
 15. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
@@ -103,6 +103,8 @@ Expected flow:
 $da-vinci use redesign-from-code to redesign this existing Android app.
 
 Existing code is the behavior source of truth, not the layout truth.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after anchor-surface summaries, phase summaries, or tasks.md once the corresponding checkpoints pass.
 Inventory activities, fragments, tabs, dialogs, bottom sheets, nested flows, and important states.
 Decompose complex screens into separate design surfaces before Pencil work.
 Use frontend-skill explicitly as the primary visual reasoning source.
@@ -116,7 +118,7 @@ Do not treat screenshot analysis as an automatic pass if it reports hierarchy, s
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
-Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
 If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `da-vinci pencil-session persist`.
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Run `da-vinci audit --mode integrity <project-path>` after that first successful Pencil write before broad expansion continues.
@@ -214,6 +216,7 @@ $da-vinci use intake for this existing Android project.
 I need to globally replace the UI.
 Existing code is the behavior source of truth.
 HTML references are in /abs/path/to/mockups.
+Treat this as full-delivery unless I explicitly narrow it to design-only.
 ```
 
 When the project already has artifacts and needs to resume:

package/docs/workflow-overview.md

@@ -117,6 +117,7 @@ Anchor surfaces must:
 - go through screenshot review
 - satisfy the active form-factor layout-hygiene profile
 - pass the design checkpoint before broad expansion
+- run `design-supervisor review` when `DA-VINCI.md` configures `Design-supervisor reviewers`, and treat it as blocking only when `Require Supervisor Review: true`
 
 After anchor approval, the workflow extracts shared primitives before broad page expansion.
 
@@ -174,6 +175,17 @@ Blocks:
 - weak visual anchors
 - ignored screenshot-review findings
 
+### Design-Supervisor Review
+
+When configured in `DA-VINCI.md`, this is the final style-quality gate after screenshot review, layout hygiene, and design checkpoint.
+
+It checks:
+
+- brand distinctiveness
+- cross-screen coherence
+- token-to-render alignment
+- whether the approved anchors are visually strong enough to expand or implement from
+
 ### Design-Source Checkpoint
 
 Confirms:

package/docs/zh-CN/codex-natural-language-usage.md

@@ -136,6 +136,8 @@ I need to globally replace the UI.
 Existing Android code is the behavior source of truth.
 UI reference directory: /abs/path/to/mockups
 Treat the HTML files there as presentation references only, not behavior truth.
+Open the HTML references in a real browser and wait 3-5 seconds, or until the visual state settles, before judging the final styling.
+Inventory which pages and states the reference directory actually covers and which still need to be inferred from behavior truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inspect the real codebase first and determine whether the UI stack is Jetpack Compose, XML, or mixed.
 Inventory all activities, fragments, composable destinations, nav graphs, dialogs, bottom sheets, tabs, nested flows, shared shells, subpages, and important states.

package/docs/zh-CN/dv-command-reference.md

@@ -118,6 +118,7 @@ Da Vinci 期望它们遵循工作流状态。
 - anchor-first 设计
 - screenshot review
 - layout hygiene
+- 配置时执行 design-supervisor review
 - `.pen` 持久化
 - design checkpoint
 - design-source checkpoint

package/docs/zh-CN/mode-use-cases.md

@@ -54,7 +54,7 @@ project/
 
 4. `overhaul-from-code`
    - 现有项目
-   - 当前代码仍然是迁移基线和参考证据
+   - 当前代码是参考证据和迁移基线
    - 流程、逻辑、信息架构或 UI 都要被大范围重写
 
 5. `feature-change`
@@ -176,7 +176,7 @@ Da Vinci 应该：
 - `design-registry.md` 里的首选 `.pen` 路径由工作流自动维护，不应该依赖用户手工填写
 - 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
 - 不要把 interactive `save()` 当作可靠的持久化真相；应先 seed 项目内 `.pen`，然后从当前 MCP 可读快照重建并覆盖它，并通过 `da-vinci check-pen-sync` 做同步校验
-- 如果支持 CLI，优先走 `da-vinci pencil-session begin / persist / end`，不要再手拼 `ensure-pen + write-pen + lock`
+- 如果支持 CLI，自治运行必须走 `da-vinci pencil-session begin / persist / end`，不要再手拼 `ensure-pen + write-pen + lock`
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 - `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
 - 截图 PNG 只是审查产物，不能替代登记好的 `.pen` 设计源
@@ -188,7 +188,7 @@ Da Vinci 应该：
 
 - 已有产品，但不是单纯换 UI
 - 旧系统里有一部分逻辑、流程或结构需要被整体重写
-- 现有代码仍然重要，但不再天然等于新系统最终行为真相
+- 现有代码是参考证据和迁移基线，不是新系统最终行为真相
 
 Da Vinci 应该：
 
@@ -218,7 +218,7 @@ Da Vinci 应该：
 它和 `redesign-from-code` 的区别：
 
 - `redesign-from-code` 默认保留旧代码行为真相
-- `overhaul-from-code` 默认把旧代码当成参考基线和迁移上下文
+- `overhaul-from-code` 默认把旧代码当成参考证据和迁移基线
 - `redesign-from-code` 更偏向广泛 UI 重设计
 - `overhaul-from-code` 更偏向存量系统上的产品级重构
 
@@ -236,7 +236,7 @@ Da Vinci 应该：
 4. 复用或更新 `design-registry.md`
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
-   - 优先通过 `da-vinci pencil-session begin` 开始这轮设计，让登记路径先 seed 好并拿到锁
+   - 必须通过 `da-vinci pencil-session begin` 开始这轮设计，让登记路径先 seed 好并拿到锁
    - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`

package/docs/zh-CN/pencil-rendering-workflow.md

@@ -28,7 +28,7 @@ PNG 只是审查产物，不是设计真相源。
 
 ## 会话模型
 
-Da Vinci 现在优先使用这组 session wrapper：
+Da Vinci 现在要求自治运行使用这组 session wrapper：
 
 - `da-vinci pencil-session begin`
 - `da-vinci pencil-session persist`
@@ -40,6 +40,8 @@ Da Vinci 现在优先使用这组 session wrapper：
 - 串行化的 Pencil MCP 写权限
 - 明确的 live-to-disk 持久化和同步校验
 
+如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，Da Vinci 还会在结构性设计 gate 通过后运行一层最终风格质量审查。只有同时设置 `Require Supervisor Review: true` 时，它才是阻断性的硬门槛。
+
 ## 首次运行路径
 
 如果项目里还没有登记好的 `.pen`：
@@ -91,7 +93,7 @@ Pencil MCP 的写操作通过全局锁串行化。
 - `da-vinci pencil-lock acquire`
 - `da-vinci pencil-lock release`
 
-或者直接优先用 session wrapper，让它自动管理锁。
+或者直接使用 session wrapper，让它自动管理锁。
 
 这套锁的目的，是防止多个项目抢同一个 active editor。
 
@@ -143,6 +145,41 @@ Pencil MCP 的写操作通过全局锁串行化。
 - 忽略 screenshot review 里的问题
 - 仍然有明显 schema 不稳定
 
+### Design-Supervisor Review
+
+如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，就在 screenshot review、layout hygiene 和 design checkpoint 之后，对当前已批准的 anchor 集合再做一层 `design-supervisor review`。
+
+如果 `Require Supervisor Review: true`，那么缺失、`BLOCK`、或未被接受的 `WARN` 都会阻断后续扩屏、实现交接和终态完成。若 `Require Supervisor Review: false`，则在配置了 reviewers 时仍应记录这层 review，但它是建议性的，不直接阻断 completion。
+
+它主要判断：
+
+- 风格质量
+- 品牌感和识别度
+- 多个 anchor 之间的视觉一致性
+- token/theme 与最终画面的匹配程度
+- 当前 anchor 是否足够成熟，能继续扩屏或进入实现规划
+
+reviewers 和 `Preferred adapters` 是两套职责：
+
+- adapters 负责引导设计生成
+- reviewers 负责判断最终结果是否够格
+
+建议输入：
+
+- reviewed screenshots
+- Pencil `get_variables()` 输出
+- `visual-thesis.md`
+- `content-plan.md`
+- `interaction-thesis.md`
+
+记录内容：
+
+- reviewer 名称
+- review inputs
+- `PASS` / `WARN` / `BLOCK`
+- issue list
+- revision outcome
+
 ## 设计源门禁
 
 active Pencil 工作一旦存在，就要跑 `design-source checkpoint`。
@@ -200,8 +237,10 @@ da-vinci audit --mode completion --change <change-id> <project-path>
 2. Pencil MCP 编辑
 3. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
 4. screenshot review + layout hygiene
-5. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-6. `da-vinci audit --mode completion --change <change-id> <project-path>`
+5. design checkpoint
+6. 如果配置了，就执行 design-supervisor review
+7. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+8. `da-vinci audit --mode completion --change <change-id> <project-path>`
 
 ## 流程图
 
@@ -219,15 +258,24 @@ flowchart TD
     H --> F
     I --> J{Screenshot review 与 layout hygiene 通过?}
     J -- 否 --> F
-    J -- 是 --> K[pencil-session persist 把 live MCP 快照写回 .pen]
-    K --> L[check-pen-sync 校验 live hash 与 persisted hash 一致]
-    L --> M{design-source checkpoint 和 runtime gate 通过?}
-    M -- 否 --> F
-    M -- 是 --> N{是否还要继续设计?}
-    N -- 是 --> E
-    N -- 否 --> O[pencil-session end 释放锁]
-    O --> P[completion audit]
-    P --> Q{completion audit 通过?}
-    Q -- 否 --> F
-    Q -- 是 --> R[design complete]
+    J -- 是 --> K{design checkpoint 通过?}
+    K -- 否 --> F
+    K -- 是 --> L{是否配置了 design-supervisor review?}
+    L -- 是 --> M[执行 design-supervisor review，结合 screenshots 与 theme inputs]
+    L -- 否 --> N[pencil-session persist 把 live MCP 快照写回 .pen]
+    M --> O{是否要求 Supervisor Review?}
+    O -- 否 --> N
+    O -- 是 --> P{review 为 PASS 或已接受 WARN?}
+    P -- 否 --> F
+    P -- 是 --> N
+    N --> Q[check-pen-sync 校验 live hash 与 persisted hash 一致]
+    Q --> R{design-source checkpoint 和 runtime gate 通过?}
+    R -- 否 --> F
+    R -- 是 --> S{是否还要继续设计?}
+    S -- 是 --> E
+    S -- 否 --> T[pencil-session end 释放锁]
+    T --> U[completion audit]
+    U --> V{completion audit 通过?}
+    V -- 否 --> F
+    V -- 是 --> W[design complete]
 ```

package/docs/zh-CN/prompt-entrypoints.md

@@ -118,6 +118,9 @@ $da-vinci use intake for this existing Android project.
 I need to globally replace the UI.
 Existing code is the behavior source of truth.
 HTML references are in /abs/path/to/mockups.
+Treat the HTML directory as visual reference only, not behavior truth or final design-source truth.
+Open the HTML references in a real browser and wait 3-5 seconds, or until the visual state settles, before judging the final styling.
+Inventory which pages and states the HTML directory actually covers and which still need to be inferred from behavior truth.
 ```
 
 预期输出：
@@ -126,6 +129,8 @@ HTML references are in /abs/path/to/mockups.
 - 一条主执行提示词
 - 一条更保守的 planning-first 版本
 - 一条后续 continue 提示词
+- 主执行提示词应在用户未明确要求 `design-only` 时，把 `full-delivery` 写清楚
+- 主执行提示词不应允许流程停在 anchor-surface 总结或 `tasks.md`
 
 ## 示例：现有产品但流程和逻辑也要一起重做
 
@@ -133,7 +138,7 @@ HTML references are in /abs/path/to/mockups.
 $da-vinci use intake for this existing product.
 
 This is a large overhaul, not only a UI refresh.
-Current codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, logic, and page structure while preserving selected integrations and constraints.
 Generate the best executable Da Vinci workflow prompt for the next step.
 ```

package/docs/zh-CN/prompt-presets/README.md

@@ -17,7 +17,7 @@
 4. 两者一起放进工作流设置
 5. 只有在项目存在特殊真相源或平台约束时，再继续收紧提示词
 6. 如果 Pencil MCP 可用，优先使用已经明确要求 MCP runtime gate 和 completion audit 的那版 redesign 提示词
-7. 如果项目要把 `.pen` 真正持久化到本地，优先使用要求 `da-vinci pencil-session begin / persist / end` 的提示词；只有 wrapper 不可用时再退回 `ensure-pen + write-pen + check-pen-sync`
+7. 如果项目要在自治运行里把 `.pen` 真正持久化到本地，必须使用要求 `da-vinci pencil-session begin / persist / end` 的提示词；只有 wrapper 确实不可用时再退回 `ensure-pen + write-pen + check-pen-sync`
 
 可用模板：
 
@@ -38,6 +38,7 @@
 
 - `Simple redesign`
 - `Complex redesign`
+- `Redesign with reference directory`
 - `Design-only`
 - `Continue`
 
@@ -45,7 +46,7 @@
 
 这组模板不是按 surface 划分的 redesign 预设。
 
-它们用于：项目已经存在，但目标流程或逻辑要重写，旧代码只能作为参考证据和迁移上下文，不能再默认当成最终行为真相。
+它们用于：项目已经存在，但目标流程或逻辑要重写，旧代码只能作为参考证据和迁移基线，不能再默认当成最终行为真相。
 
 ### 1. 进入大改版的 intake 提示词
 
@@ -59,7 +60,7 @@
 $da-vinci use intake for this existing product.
 
 This is a broad overhaul, not only a UI refresh.
-Current codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, logic, page structure, and selected UI surfaces while preserving only the approved integrations, permissions, and constraints.
 Recommend the best Da Vinci mode and generate the best executable next-step prompt.
 ```
@@ -97,7 +98,7 @@ $da-vinci use overhaul-from-code to design the new target product surfaces from
 
 Use the existing .da-vinci/project-inventory.md, proposal.md, migration-contract.md, target specs, page-map.md, DA-VINCI.md, and design-registry.md.
 Treat the new proposal and specs as the target behavior truth.
-Treat the old codebase only as reference evidence and migration context.
+Treat the old codebase only as reference evidence and migration baseline.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 Persist project-local Pencil files under .da-vinci/designs/.
 Run the normal Pencil runtime gate and completion audit before terminal completion claims.

package/docs/zh-CN/prompt-presets/desktop-app.md

@@ -19,6 +19,7 @@
 
 - `Simple redesign` 适合 workspace 不多、状态分支有限、结构相对收敛的项目。
 - `Complex redesign` 适合多工作区、多侧栏、多 inspector、多 overlays、状态变化明显的项目。
+- `Redesign with reference directory` 适合你手里有本地 HTML 或设计参考目录，但这些文件只能作为桌面视觉参考、不能当行为真相的项目。
 - `Design-only` 适合先把设计链路和绑定做完，但暂时不改代码。
 - `Continue` 适合已经有 `.da-vinci/` 工件，需要继续推进的项目。
 
@@ -32,7 +33,7 @@
 $da-vinci use intake for this existing desktop product.
 
 This is a broad overhaul, not only a UI refresh.
-Current desktop codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current desktop codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, workspace structure, interaction model, and selected UI surfaces while preserving only approved integrations, permissions, and constraints.
 Recommend the best Da Vinci mode and generate the best executable next-step prompt.
 ```
@@ -61,7 +62,7 @@ $da-vinci use overhaul-from-code to design the new target desktop surfaces from
 
 Use the existing .da-vinci/project-inventory.md, proposal.md, migration-contract.md, target specs, page-map.md, DA-VINCI.md, and design-registry.md.
 Treat the new proposal and specs as the target behavior truth.
-Treat the old desktop codebase only as reference evidence and migration context.
+Treat the old desktop codebase only as reference evidence and migration baseline.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 Persist project-local Pencil files under .da-vinci/designs/.
 Run the normal Pencil runtime gate and completion audit before terminal completion claims.
@@ -84,9 +85,11 @@ $da-vinci use redesign-from-code to redesign this existing desktop product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after discovery, anchor surfaces, phase summaries, or task generation; continue through tasks, build, and verify once the corresponding checkpoints pass.
 Inventory the current workspaces, dialogs, overlays, and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有全局 Pencil 锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有全局 Pencil 锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not pass design checkpoint if the result is just a boxed-up recolor of the old UI or if workspace hierarchy remains unclear.
@@ -100,6 +103,8 @@ $da-vinci use redesign-from-code to redesign this existing desktop product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after discovery, anchor surfaces, phase summaries, or task generation; continue through tasks, build, and verify once the corresponding checkpoints pass.
 Inventory primary workspaces, side panels, inspectors, dialogs, settings flows, overlays, and materially different states before broad Pencil work.
 Decompose complex screens into primary surfaces, secondary surfaces, overlays, and implementation surfaces.
 在开始第一个 anchor surface 之前，先把 discovery 和 design-source 工件写到标准路径。
@@ -113,15 +118,48 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，必须执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
+如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，就在 screenshot review、layout hygiene 和 design checkpoint 之后再做 `design-supervisor review`，输入要同时包含 screenshots、Pencil variables 和设计 thesis。若 `Require Supervisor Review: true`，那么缺失、`BLOCK`、或未被接受的 review 结果都要视为阻断。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not pass design checkpoint if the result is a repeated placeholder scaffold, flat panel soup, or a recolor of the old desktop shell.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+## Redesign With Reference Directory
+
+```text
+$da-vinci use redesign-from-code to redesign this existing desktop product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after discovery, anchor surfaces, phase summaries, or task generation; continue through tasks, build, and verify once the corresponding checkpoints pass.
+
+Use <reference-directory> as the local HTML design-reference directory.
+Treat that directory as visual reference material only, not as behavior truth, workspace truth, or final design-source truth.
+Before broad Pencil work begins, inventory which workspaces, side panels, inspectors, dialogs, overlays, and materially different states are covered by the reference directory and which are not.
+For uncovered states or surfaces, derive the design from the approved anchor surfaces, the project visual contract, and the existing behavior truth.
+
+If browser access is available, open the HTML reference screens in a real browser and wait 3-5 seconds, or until the visual state settles, before judging hierarchy, spacing, styling, or component treatment.
+Do not review the initial unhydrated or partially rendered state.
+If a reference screen visibly changes after load, use the settled state as the visual reference baseline and record that delayed settling was required.
+
+Use the HTML reference screens only as composition and styling input where they are relevant and stable.
+Do not mechanically clone them when they conflict with behavior truth, missing states, or implementation reality.
+
+Design 1-3 anchor surfaces first, review screenshots, then expand.
+For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
+
+Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
+Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
 ## Design-Only
 
 ```text
@@ -129,12 +167,14 @@ $da-vinci use redesign-from-code to redesign this existing desktop product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, and integrations.
+Treat this as design-only, not full-delivery.
 Inventory workspaces, side panels, dialogs, overlays, and important states.
 Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
-Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
+Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, and pencil-bindings.md.
+不要生成 `tasks.md`，除非用户明确把这轮交付意图从 `design-only` 提升到更后续的阶段。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not start code changes yet.
@@ -147,7 +187,7 @@ $da-vinci use continue for this existing desktop-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后再执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。