@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.20

package/docs/zh-CN/visual-assist-presets/desktop-app.md

@@ -6,13 +6,57 @@
 - 高密度生产力界面
 - 工具型 workspace
 
-推荐配置：
+从下面三种 `DA-VINCI.md` 配置里选一种。
+
+### 变体 1：只有 adapter，没有 reviewer
+
+适用场景：
+
+- 只想增强桌面 workspace / panel 的构图判断
+- 不需要单独 reviewer 角色
+- 结构性 gate 已经足够
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - workspace composition
+  - hierarchy and spacing
+  - motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+### 变体 2：reviewer 建议性审查
+
+适用场景：
+
+- 希望记录最终桌面端风格质量结论
+- 但默认不希望 review 结果阻断 completion
 
 ```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
   - workspace composition
@@ -24,11 +68,54 @@
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
+```
+
+### 变体 3：reviewer 硬签字
+
+适用场景：
+
+- 桌面产品对外可见，或设计质量要求很高
+- 需要 reviewer 对最终风格质量签字
+- 不允许从普通或泛化结果直接进入实现
+
+```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
+  - workspace composition
+  - hierarchy and spacing
+  - motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+- Require Supervisor Review:
+  - true
 ```
 
+通用说明：
 说明：
 
 - 优先用 `ui-ux-pro-max` 做高密度 app 布局判断
 - 如果当前环境里的 adapter 名不一样，先改成真实可用名称
+- 把 `Design-supervisor reviewers` 和 `Preferred adapters` 分开；reviewers 负责在结构性 gate 通过后判断桌面端最终风格质量
 - `frontend-skill` 更适合作为辅助，不要反过来把工具界面做成营销页
 - 如果结果太平、太盒子化、太像通用后台，就把 `frontend-skill` 调到第一位，并提高 design checkpoint 的要求

package/docs/zh-CN/visual-assist-presets/mobile-app.md

@@ -5,13 +5,58 @@
 - 手机优先的产品
 - 需要更稳的移动端层级和触控判断
 
-推荐配置：
+从下面三种 `DA-VINCI.md` 配置里选一种。
+
+### 变体 1：只有 adapter，没有 reviewer
+
+适用场景：
+
+- 只想增强移动端构图和层级生成
+- 不需要最终 reviewer 角色
+- 结构性 gate 已经足够
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - mobile page composition
+  - hierarchy and spacing
+  - touch-first motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+### 变体 2：reviewer 建议性审查
+
+适用场景：
+
+- 希望有最终移动端风格质量结论
+- 希望把结果记录到 `pencil-design.md`
+- 但默认不希望因为 review 结果阻断交付
 
 ```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
   - mobile page composition
@@ -23,11 +68,53 @@
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
+```
+
+### 变体 3：reviewer 硬签字
+
+适用场景：
+
+- 产品品牌敏感，或面向 premium 用户
+- 移动端风格质量本身就是交付门槛
+- 如果缺 review 或 review 结果不够好，就不允许扩屏或进入实现交接
+
+```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
+  - mobile page composition
+  - hierarchy and spacing
+  - touch-first motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+- Require Supervisor Review:
+  - true
 ```
 
-说明：
+通用说明：
 
 - `ui-ux-pro-max` 更适合移动端 app 表面的密度和平衡
 - 如果当前环境里的 adapter 名不一样，先改成真实可用名称
+- 把 `Design-supervisor reviewers` 和 `Preferred adapters` 分开；reviewers 负责在结构性 gate 通过后判断移动端最终风格质量
 - motion 要轻，不要把普通 app 页面做成营销页
 - 如果结果总是变成泛化卡片堆砌或层级太弱，就把 `frontend-skill` 调到第一位，并考虑把 `Require Adapter` 改成 `true`

package/docs/zh-CN/visual-assist-presets/tablet-app.md

@@ -5,13 +5,57 @@
 - 平板优先界面
 - 需要兼顾触控和更大工作区
 
-推荐配置：
+从下面三种 `DA-VINCI.md` 配置里选一种。
+
+### 变体 1：只有 adapter，没有 reviewer
+
+适用场景：
+
+- 只想增强平板端构图和分区判断
+- 不需要单独 reviewer 角色
+- 常规结构性 gate 已经足够
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- Scope:
+  - visual contract refinement
+  - tablet page composition
+  - hierarchy and spacing
+  - touch-aware motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - false
+```
+
+### 变体 2：reviewer 建议性审查
+
+适用场景：
+
+- 希望记录最终平板端风格质量结论
+- 但默认不希望 review 结果阻断 completion
 
 ```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
   - tablet page composition
@@ -23,11 +67,54 @@
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
+```
+
+### 变体 3：reviewer 硬签字
+
+适用场景：
+
+- 平板体验是旗舰入口，或审查要求很高
+- 最终风格质量必须经过 reviewer 签字
+- 不接受寡淡、过度框线化或弱层级结果直接进入实现
+
+```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
+  - tablet page composition
+  - hierarchy and spacing
+  - touch-aware motion guidance
+  - anchor-surface composition
+  - Pencil design refinement
+- Fallback:
+  - native-da-vinci
+- Require Adapter:
+  - true
+- Require Supervisor Review:
+  - true
 ```
 
-说明：
+通用说明：
 
 - spacing 一般要比手机更舒展，但又不能像桌面端那样过密
 - 如果当前环境里的 adapter 名不一样，先改成真实可用名称
+- 把 `Design-supervisor reviewers` 和 `Preferred adapters` 分开；reviewers 负责在结构性 gate 通过后判断平板端最终风格质量
 - 更适合用 adapter 去辅助分栏、画布区和主次区域的平衡
+- 不要把平板端压缩成手机式长列表堆叠
 - 如果结果还是寡淡或被边框框死，就把 `frontend-skill` 调到第一位，并要求在 Pencil 设计前先写清楚 visual thesis

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

@@ -6,13 +6,57 @@
 - 浏览器里的产品界面
 - 兼具产品性和一定品牌表达的界面
 
-推荐配置：
+从下面三种 `DA-VINCI.md` 配置里选一种。
+
+### 变体 1：只有 adapter，没有 reviewer
+
+适用场景：
+
+- 只想增强 Web 产品的响应式和 workspace 构图
+- 不需要单独 reviewer 角色
+- 结构性 gate 已经足够
+
+```md
+## Visual Assist
+- Preferred adapters:
+  - ui-ux-pro-max
+  - frontend-skill
+- 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
+```
+
+### 变体 2：reviewer 建议性审查
+
+适用场景：
+
+- 希望记录最终 Web 风格质量结论
+- review 结果默认不直接阻断 completion
 
 ```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
@@ -24,11 +68,54 @@
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
+```
+
+### 变体 3：reviewer 硬签字
+
+适用场景：
+
+- Web 产品是品牌关键或高曝光入口
+- 最终风格质量必须经过 reviewer 签字
+- 不允许用泛化 SaaS 风格直接进入实现
+
+```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
 ```
 
+通用说明：
 说明：
 
 - 如果是典型 product UI，优先 `ui-ux-pro-max`
 - 如果当前环境里的 adapter 名不一样，先改成真实可用名称
+- 把 `Design-supervisor reviewers` 和 `Preferred adapters` 分开；reviewers 负责在结构性 gate 通过后判断 Web 最终风格质量
 - 如果页面更偏品牌表达或强视觉，可以把 `frontend-skill` 放前面
 - 如果结果像很普通的 SaaS 模板，就把 `frontend-skill` 提到第一位，并把 `DA-VINCI.md` 的视觉方向写得更具体

package/docs/zh-CN/workflow-examples.md

@@ -16,6 +16,8 @@
 
 - `intake` 和 `continue` 通常应该回到主工作流入口
 - 不应默认把用户导向 `build`
+- `continue` 选路先看工件/checkpoint 真相，再把 Context Delta 当作辅助恢复信息
+- 如果 Context Delta 与当前工件冲突，选路时应忽略冲突内容并记录冲突
 
 ## 1. `greenfield-spec`
 
@@ -95,8 +97,8 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 8. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
 9. 在把 operations 发给 Pencil 前，先对非小型 `batch_design` 做 preflight，并保持 anchor-surface 批次足够小
 10. 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
-11. 如果这一轮开始时还没有登记的项目内 `.pen`，先允许第一个通过审查的 live anchor surface 在内存里完成，然后立即把该 MCP 快照持久化到 `.da-vinci/designs/`
-12. 如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但发生了实质性 live edit 后，必须把当前 MCP 快照重新覆盖写回同一路径
+11. 如果这一轮开始时还没有登记的项目内 `.pen`，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，先 seed 登记路径并拿到全局锁，再开始第一次 Pencil 编辑
+12. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
 13. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
 14. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
 15. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
@@ -114,6 +116,8 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 $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.
@@ -127,7 +131,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.
-优先在第一次 Pencil 编辑前执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，这样会先 seed 登记好的 `.pen` 并持有全局 Pencil 锁。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，这样会先 seed 登记好的 `.pen` 并持有全局 Pencil 锁。
 如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 live MCP 快照重新覆盖写回同一路径。
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
@@ -214,6 +218,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.
 ```
 
 如果工件已经存在，需要继续：

package/docs/zh-CN/workflow-overview.md

@@ -119,6 +119,7 @@ Da Vinci 围绕一个固定契约工作：
 - 经过 screenshot review
 - 满足当前 form factor 的 layout-hygiene 规则
 - 通过 design checkpoint 才能扩屏
+- 如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，还要运行 `design-supervisor review`；只有 `Require Supervisor Review: true` 时，它才是阻断性的最终风格质量 gate
 
 anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 
@@ -129,6 +130,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 - `design-source checkpoint`
 - 如果启用了 Pencil MCP，则跑 `MCP runtime gate`
 - 工作中期跑 `da-vinci audit --mode integrity <project-path>`
+- 在现有 change 工件里记录 checkpoint 邻近的 `Context Delta`
 
 这些检查用来确认：
 
@@ -136,6 +138,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 - active editor 是正确的设计源
 - shell 上确实有 `.pen`
 - live snapshot 和 persisted snapshot 已同步
+- 最近关键执行上下文可恢复，但不会替代工件真相的选路权
 
 ### 6. Mapping
 
@@ -164,6 +167,10 @@ mapping 通过后：
 - 如果用了 Pencil MCP，runtime gate 结果可接受
 - `da-vinci audit --mode completion --change <change-id> <project-path>` 通过
 
+补充说明：
+
+- Context Delta 的告警用于提升续跑质量，本身不会单独形成新的 completion 阻断
+
 ## 门禁与审计
 
 ### Design Checkpoint
@@ -176,6 +183,17 @@ mapping 通过后：
 - 视觉锚点很弱
 - 忽略 screenshot review 问题
 
+### Design-Supervisor Review
+
+当 `DA-VINCI.md` 里配置了它时，这是一道位于 screenshot review、layout hygiene 和 design checkpoint 之后的最终风格质量 gate。
+
+它会判断：
+
+- 品牌感和识别度
+- 多个 screen 之间的视觉一致性
+- token/theme 与最终画面的匹配程度
+- 当前 anchor 是否足够成熟，能继续扩屏或进入实现
+
 ### Design-Source Checkpoint
 
 确认：
@@ -207,6 +225,11 @@ mapping 通过后：
 
 在任何终态完成声明前跑。
 
+audit 中对 Context Delta 的处理：
+
+- 缺失、字段不完整、或过期冲突都属于告警级信号
+- 选路和完成真相仍以工件、checkpoint、runtime gate 与文件系统审计为准
+
 ## 流程图
 
 ```mermaid