@xenonbyte/da-vinci-workflow 0.1.15 → 0.1.16

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

@@ -28,6 +28,9 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
 Inventory the current workspaces, dialogs, overlays, and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -48,8 +51,15 @@ Use Pencil guides only as workspace constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 在通过 screenshot review 之前，先应用桌面端专用的 form-factor layout hygiene 规则。
+在发送非小型 `batch_design` 之前，如果有 shell 能力，先对 Pencil operations 做 preflight。
+如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
+在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
+如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.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/.
 ```
@@ -66,6 +76,9 @@ 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.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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.
 ```
 
@@ -76,8 +89,10 @@ $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.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth.
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
 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>`。
 Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
 ```
 

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

@@ -28,6 +28,9 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current screens and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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 a skin-swap of the old UI, a generic card grid, or a weak mobile hierarchy.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -52,11 +55,18 @@ 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.
 Do not treat screenshot analysis as an automatic pass if it reports hierarchy, spacing, clarity, or inconsistency issues.
 在通过 screenshot review 之前，先应用移动端专用的 form-factor layout hygiene 规则。
+在发送非小型 `batch_design` 之前，如果有 shell 能力，先对 Pencil operations 做 preflight。
+如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 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>`。
+如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
+在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Define shared primitives from the approved anchor surfaces before broad page expansion.
 Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, repeated placeholder templates, or weak visual anchors.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -74,6 +84,9 @@ Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the app 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.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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.
 ```
 
@@ -84,8 +97,10 @@ $da-vinci use continue for this existing mobile-app redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth.
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
 If the redesign is complex, keep the anchor-first flow until the design checkpoint passes.
+如果 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>`。
 Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
 ```
 

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

@@ -28,6 +28,9 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current tablet surfaces and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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 ignores tablet-scale composition or collapses into a stretched phone layout.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -48,8 +51,15 @@ Use Pencil guides only as tablet-layout constraints, not as the design direction
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 在通过 screenshot review 之前，先应用平板端专用的 form-factor layout hygiene 规则。
+在发送非小型 `batch_design` 之前，如果有 shell 能力，先对 Pencil operations 做 preflight。
+如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
+在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
+如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.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 collapses into a stretched phone layout, repeated placeholders, or weak multi-region hierarchy.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -66,6 +76,9 @@ Decompose complex pages 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.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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.
 ```
 
@@ -76,8 +89,10 @@ $da-vinci use continue for this existing tablet-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth.
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
 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>`。
 Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
 ```
 

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

@@ -28,6 +28,9 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current product surfaces and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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 a generic SaaS card grid or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -49,8 +52,15 @@ Use Pencil guides only as responsive layout constraints, not as the design direc
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 在通过 screenshot review 之前，先应用 Web 专用的 form-factor layout hygiene 规则。
+在发送非小型 `batch_design` 之前，如果有 shell 能力，先对 Pencil operations 做 preflight。
+如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
+在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
+如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.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 generic SaaS card grid, repeated placeholder scaffolds, or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -67,6 +77,9 @@ Decompose complex pages 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.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果 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.
 ```
 
@@ -77,8 +90,10 @@ $da-vinci use continue for this existing web-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth.
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
 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>`。
 Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
 ```
 

package/docs/zh-CN/visual-assist-presets/README.md

@@ -13,6 +13,11 @@
 
 - `docs/zh-CN/prompt-presets/`
 
+这些模板本身不负责 workflow completion gate：
+
+- MCP runtime gate 仍然属于工作流 prompt / checkpoint 层
+- `da-vinci audit --mode completion ...` 仍然属于工作流 prompt / checkpoint 层
+
 如果项目对设计质量要求很高，或者之前结果很普通、很丑、太像旧 UI：
 
 - 仍然先选对应场景模板

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

@@ -93,14 +93,20 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 6. 重建或细化 `page-map.md`，把 subpage、overlay、重要 state 一起拆出来
 7. 先写出 anchor surface 的 visual thesis、content plan、interaction thesis 和 structural-delta 说明
 8. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
-9. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
-10. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
-11. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
-12. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
-13. 绑定路由和 Pencil 页面
-14. 生成和 redesign slice 对齐的任务
-15. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
-16. 只有在 completion gate 最终能通过时，才进入实现和验证
+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 快照重新覆盖写回同一路径
+13. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
+14. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
+15. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
+16. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+17. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
+18. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
+19. 绑定路由和 Pencil 页面
+20. 生成和 redesign slice 对齐的任务
+21. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
+22. 只有在 completion gate 最终能通过时，才进入实现和验证
 
 ### 复杂 Android 页面示例
 
@@ -118,10 +124,16 @@ Do not start with broad multi-screen scaffolding.
 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.
 Do not treat screenshot analysis as an automatic pass if it reports hierarchy, spacing, clarity, or inconsistency issues.
+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.
+如果这一轮开始时还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP live 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后要把当前 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>`。
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 Do not report completion if the `.pen` source exists only in memory or only as exported PNGs.
 Do not pass design checkpoint if the result is just a skin-swap of the old UI.
 ```
@@ -162,6 +174,8 @@ Use the visual-adapter preferences declared in DA-VINCI.md.
 If frontend-skill is available, use it as the primary visual adapter.
 If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
+如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到这里。
+如果项目里原本已有 `.pen`，继续设计后要把当前 MCP 快照覆盖写回同一路径。
 ```
 
 ## 复杂重设计的入口辅助示例

package/lib/cli.js

@@ -1,3 +1,4 @@
+const fs = require("fs");
 const {
   VERSION,
   installPlatforms,
@@ -6,6 +7,15 @@ const {
   validateAssets
 } = require("./install");
 const { auditProject, formatAuditReport } = require("./audit");
+const {
+  preflightPencilBatch,
+  formatPencilPreflightReport,
+  readOperations
+} = require("./pencil-preflight");
+const {
+  writePenFromPayloadFiles,
+  snapshotPenFile
+} = require("./pen-persistence");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -67,12 +77,22 @@ function printHelp() {
       "  da-vinci status",
       "  da-vinci validate-assets",
       "  da-vinci audit [project-path]",
+      "  da-vinci preflight-pencil --ops-file <path>",
+      "  da-vinci write-pen --output <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci snapshot-pen --input <path> --output <path>",
       "  da-vinci --version",
       "",
       "Options:",
       "  --platform <value>   codex, claude, gemini, or all",
       "  --home <path>        override HOME for installation targets",
       "  --project <path>     override project path for audit",
+      "  --ops-file <path>    Pencil batch operations file for preflight",
+      "  --input <path>       input .pen file for snapshot-pen",
+      "  --output <path>      output .pen file for write-pen or snapshot-pen",
+      "  --nodes-file <path>  JSON payload from batch_get for write-pen",
+      "  --variables-file <path> JSON payload from get_variables for write-pen",
+      "  --verify-open        reopen the written .pen with Pencil after writing",
+      "  --version <value>    explicit .pen version when writing from MCP payloads",
       "  --mode <value>       integrity or completion",
       "  --change <id>        scope completion audit to one change id"
     ].join("\n")
@@ -138,6 +158,81 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "preflight-pencil") {
+    const opsFile = getOption(argv, "--ops-file");
+    let operations = "";
+
+    if (opsFile) {
+      operations = readOperations(opsFile);
+    } else if (!process.stdin.isTTY) {
+      operations = fs.readFileSync(0, "utf8");
+    } else {
+      throw new Error("`preflight-pencil` requires `--ops-file <path>` or piped stdin input.");
+    }
+
+    const result = preflightPencilBatch(operations);
+    const report = formatPencilPreflightReport(result);
+
+    if (result.status === "FAIL") {
+      throw new Error(report);
+    }
+
+    console.log(report);
+    return;
+  }
+
+  if (command === "write-pen") {
+    const outputPath = getOption(argv, "--output");
+    const nodesFile = getOption(argv, "--nodes-file");
+    const variablesFile = getOption(argv, "--variables-file");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+
+    if (!outputPath || !nodesFile) {
+      throw new Error("`write-pen` requires `--output <path>` and `--nodes-file <path>`.");
+    }
+
+    const result = writePenFromPayloadFiles({
+      outputPath,
+      nodesFile,
+      variablesFile,
+      version,
+      verifyWithPencil
+    });
+
+    console.log(`Wrote .pen file to ${result.outputPath}`);
+    console.log(`Top-level nodes: ${result.document.children.length}`);
+    if (result.verification) {
+      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
+    }
+    return;
+  }
+
+  if (command === "snapshot-pen") {
+    const inputPath = getOption(argv, "--input");
+    const outputPath = getOption(argv, "--output");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+
+    if (!inputPath || !outputPath) {
+      throw new Error("`snapshot-pen` requires `--input <path>` and `--output <path>`.");
+    }
+
+    const result = snapshotPenFile({
+      inputPath,
+      outputPath,
+      version,
+      verifyWithPencil
+    });
+
+    console.log(`Snapshotted ${result.inputPath} to ${result.outputPath}`);
+    console.log(`Top-level nodes: ${result.document.children.length}`);
+    if (result.verification) {
+      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
+    }
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }