@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.16

package/docs/zh-CN/mcp-aware-gate-tests.md

@@ -0,0 +1,244 @@
+# MCP-Aware Gate 测试设计
+
+这份文档定义未来 MCP-aware gate 的测试覆盖设计。
+
+它是验证设计，不是测试实现。
+
+## 测试目标
+
+证明 MCP-aware gate：
+
+- 能阻断假的 runtime 完成态
+- 不会取代 filesystem audit
+- 不会把健康的 runtime 设计会话误判成失败
+- 在 runtime 信息不完整时，行为仍然可预测
+
+## 测试层级
+
+测试应覆盖三层。
+
+### 1. Evaluator 单元测试
+
+对纯 runtime-gate evaluator 输入 synthetic snapshot 做测试。
+
+原因：
+
+- 反馈最快
+- 可重复
+- 不依赖真实 Pencil session
+
+### 2. Runtime 集成测试
+
+对 runtime-gate caller 使用真实或 fixture 化的 MCP 响应做测试。
+
+原因：
+
+- 能证明 active editor 和 node 读取确实被正确解释
+
+### 3. 端到端工作流测试
+
+验证 runtime gate 和 filesystem audit 在真实工作流状态下是否能正确协作。
+
+原因：
+
+- 防止 runtime gate 过了，但完成态仍然能说谎
+
+## 核心测试类别
+
+### A. 健康的 runtime source convergence
+
+期望：
+
+- active editor 是有名的项目内 `.pen`
+- 登记的 `.pen` 路径一致
+- shell-visible `.pen` 存在
+- 结果是 `PASS`
+
+### B. Live editor 仍然是 `new`
+
+期望：
+
+- source convergence 为 `BLOCK`
+- 即使 live editor 里有 screen，也不能完成
+
+### C. 登记的 `.pen` 在磁盘上不存在
+
+期望：
+
+- source convergence 或 completion 状态变成 `BLOCK`
+- runtime gate 不能把 live editor 单独当成充分条件
+
+### D. Live screen 存在，但没有持久化
+
+示例：
+
+- active editor 中有 `Splash`、`Home`、`SafeBox`
+- shell-visible `.pen` 不存在
+
+期望：
+
+- runtime gate 能证明 screen 的确存在
+- 但 source convergence 仍然是 `BLOCK`
+
+### E. 声称完成的 anchor id 缺失
+
+示例：
+
+- `pencil-design.md` 声称有 `mCZ1G`
+- 当前 live editor 中没有 `mCZ1G`
+
+期望：
+
+- screen presence 为 `BLOCK`
+
+### F. Screenshot target 缺失
+
+期望：
+
+- review execution 为 `BLOCK`
+
+### G. Review blocker 被忽略
+
+示例：
+
+- screenshot review 已记录 blocker 级 layout-hygiene 问题
+- 但工作流仍然把 anchor 标成 approved
+
+期望：
+
+- review execution 为 `BLOCK`
+
+### H. Source mismatch 但有显式 reconciliation
+
+示例：
+
+- active editor 路径和登记路径不同
+- `pencil-design.md` 中记录了明确 reconciliation
+
+期望：
+
+- 只有在 reconciliation 满足规则时，才允许 `WARN` 或 `PASS`
+
+### I. 还没有新的 Pencil 修改
+
+期望：
+
+- runtime gate 返回 `WARN` 或 partial result
+- 不能伪造 full `PASS`
+
+### J. Pencil MCP 不可用
+
+期望：
+
+- runtime gate 报 unavailable 或 skipped
+- 工作流不能把 runtime gate 视为已通过
+- filesystem audit 仍然可以独立工作
+
+## 必须覆盖的端到端场景
+
+### 场景 1：Cipher 这次真实失败模式
+
+状态：
+
+- active editor 是 `new`
+- live screen 存在
+- `.da-vinci/designs/` 被污染
+- 没有 shell-visible `.pen`
+
+期望：
+
+- runtime gate 阻断完成
+- filesystem completion audit 也失败
+
+### 场景 2：健康的 redesign 完成态
+
+状态：
+
+- active editor 就是登记的 `.pen`
+- anchor ids 存在
+- screenshot review 存在
+- shell-visible `.pen` 存在
+- completion audit 通过
+
+期望：
+
+- runtime gate 通过
+- completion audit 通过
+- 允许终态完成
+
+### 场景 3：runtime 过了，filesystem 没过
+
+状态：
+
+- active editor 正常
+- shell-visible `.pen` 存在
+- 但 `.da-vinci/designs/` 中混入 PNG 或 markdown
+
+期望：
+
+- runtime gate 可以通过
+- filesystem completion audit 失败
+- 不允许终态完成
+
+### 场景 4：filesystem 过了，runtime 没过
+
+状态：
+
+- shell-visible `.pen` 存在
+- 磁盘结构也健康
+- 但 active editor 仍然是 `new` 或指向别处
+
+期望：
+
+- runtime gate 失败
+- 不允许终态完成
+
+## 必须断言的内容
+
+每一条 runtime-gate 测试都应该断言：
+
+- final status
+- 各子层 status
+- 触发的是哪条 blocking condition
+- completion 是否允许继续
+- 工件写入格式是否保持稳定
+
+## 工件记录测试
+
+需要验证 runtime gate 输出：
+
+- 追加到 `pencil-design.md`
+- 不会新增新的工件家族
+- 不会写进 `.da-vinci/designs/`
+- 不会覆盖无关 section
+
+## 回归场景
+
+这些回归必须覆盖：
+
+1. runtime gate 意外退化成 CLI-only audit
+2. runtime gate 静默接受 `new`
+3. runtime gate 把 PNG 当成设计源证据
+4. anchor id 缺失时 runtime gate 仍通过
+5. runtime gate 实际没跑，却被记成通过
+6. runtime gate 输出新的临时 markdown 文件到错误目录
+
+## 建议测试矩阵
+
+最小矩阵：
+
+- form factor：先覆盖 mobile
+- design stage：第一次 Pencil 写入 / anchor approved / terminal completion
+- source state：healthy / `new` / diverged / missing `.pen`
+- screen state：present / missing / stale ids
+- review state：reviewed / missing / blocker ignored
+
+## Exit Criteria
+
+只有以下条件同时满足，才应该认为实现达标：
+
+1. evaluator 单元测试覆盖所有 blocker 分支
+2. 至少有一条 runtime 集成测试证明 live editor 检测可用
+3. Cipher 类失败场景被阻断
+4. 健康 redesign 场景可以通过
+5. runtime gate + filesystem audit 的双层组合，能够阻止假的终态完成

package/docs/zh-CN/mcp-aware-gate.md

@@ -0,0 +1,249 @@
+# MCP-Aware Gate 设计提案
+
+这份文档定义 Da Vinci 的 MCP-aware runtime gate 设计方向。
+
+它只是一份设计文档，不代表已经开始实现。
+
+## 当前状态
+
+- 设计状态：提案中
+- 可行性状态：已基于真实运行时行为做过部分验证
+- 实现状态：未开始
+
+## 为什么需要它
+
+当前文件系统 `audit` 已经补上了一层重要兜底：
+
+- 能证明项目内 `.pen` 是否真实落盘
+- 能证明 `.da-vinci/designs/` 是否被污染
+- 能证明截图导出是否写错目录
+
+但它证明不了这些 live 运行时事实：
+
+- 当前 active Pencil editor 是否仍然是 `new`
+- 声称完成的 anchor surface 是否真的存在于当前 editor
+- 当前 active editor 和登记的项目内 `.pen` 是否已经收敛
+
+这些事实只存在于 MCP 驱动的设计会话里。
+
+## 已验证的可行性
+
+下面这些事实已经被验证为“当前可读”：
+
+1. 可以通过 MCP 读取 active Pencil editor。
+2. 可以通过 MCP 读取 live 顶层节点。
+3. 可以通过 MCP 读取具体 screen node id。
+4. 可以通过 shell 单独读取项目文件系统状态。
+
+这意味着 Da Vinci 已经可以对比：
+
+- live editor truth
+- live screen truth
+- filesystem truth
+
+这个对比已经足够支持第一版 MCP-aware runtime gate。
+
+## 非目标
+
+这份提案不打算：
+
+- 取代文件系统 `da-vinci audit`
+- 直接把 MCP 状态暴露给 CLI
+- 自动把 live editor 修复成持久化 `.pen`
+- 让实现依赖未验证的 Pencil session 行为
+
+## 设计原则
+
+1. MCP-aware gate 只处理 runtime 真相。
+2. 文件系统 audit 继续作为终态持久化兜底。
+3. runtime gate 只负责阻断假进度，不负责自动修复。
+4. 设计只依赖已经验证过“当前可读”的事实。
+5. 当 Pencil MCP 不可用时，必须能优雅降级。
+
+## 在工作流里的位置
+
+MCP-aware gate 应该插在两个时点：
+
+1. 第一次成功写入 Pencil 之后。
+2. 任何 `design complete` 或 `workflow complete` 声明之前。
+
+它不应该在每一个小操作后都运行。
+
+## 建议的 Gate 分层
+
+### 1. Source Convergence Gate
+
+目的：
+
+- 判断 live editor、登记的 `.pen` 路径和 shell 可见 `.pen` 文件，是否已经足够收敛，可以把设计源视为可追踪
+
+输入：
+
+- MCP 返回的 active Pencil editor 状态
+- `design-registry.md` 中登记的 `.pen` 路径
+- `.da-vinci/designs/` 下 shell 可见的 `.pen` 文件
+
+直接阻断条件：
+
+- active editor 仍然是 `new` 这类未命名 live editor
+- active editor 与登记的项目内设计源不一致，且没有显式记录 reconciliation
+- live Pencil 工作已经发生，但 shell 上仍然没有 `.pen`
+- runtime 会话明显在使用另一个设计源，而不是登记的项目级 `.pen`
+
+结果：
+
+- `PASS`：设计源已收敛
+- `WARN`：设计源暂时延后处理，但仍然可追踪
+- `BLOCK`：设计源不稳定，不能继续
+
+### 2. Screen Presence Gate
+
+目的：
+
+- 确认声称完成的 anchor surface 是否真的存在于当前 live editor 中
+
+输入：
+
+- `pencil-design.md` 中记录的 node id 或 screen id
+- 当前 MCP editor 中的顶层节点或目标节点读取结果
+
+直接阻断条件：
+
+- 声称完成的 anchor screen 在当前 editor 中找不到
+- 截图使用的 node id 在当前 live 文档里不存在
+- 工作流声称完成的 anchor 数量已经超过当前 editor 能解释的范围
+
+结果：
+
+- `PASS`：声称完成的 screen 确实存在
+- `WARN`：命名有漂移，但仍能恢复映射
+- `BLOCK`：设计输出无法追溯到当前 live 文档
+
+### 3. Review Execution Gate
+
+目的：
+
+- 确认 screenshot review 真的是针对当前 live surface 做的，而不是形式化走流程
+
+输入：
+
+- `pencil-design.md` 里记录的 review surface
+- 当前设计会话里实际 review 的 screen id
+- 当前 form factor 对应的 layout hygiene profile
+
+直接阻断条件：
+
+- 一个 surface 被视为已批准，但没有任何 live screenshot review
+- screenshot review 明确出现 blocker 级 layout hygiene 问题，但仍然被标成通过
+- review 记录指向的 screen 在当前 active editor 里根本不存在
+
+结果：
+
+- `PASS`：review 与 live 设计状态一致
+- `WARN`：review 存在，但继续扩张前需要回改
+- `BLOCK`：当前批准结论不可信
+
+## Runtime 输出格式
+
+这层 gate 不应该引入全新的工件类型。
+
+更合理的做法，是把结果追加到 `pencil-design.md` 或同类合法工件里：
+
+```md
+## MCP Runtime Gate
+- Time:
+- Active editor:
+- Registered `.pen` path:
+- Shell-visible `.pen` path:
+- Reviewed screen ids:
+- Source convergence: PASS | WARN | BLOCK
+- Screen presence: PASS | WARN | BLOCK
+- Review execution: PASS | WARN | BLOCK
+- Notes:
+```
+
+这样 runtime 证据仍然附着在当前设计稿，而不是散落成新的临时文件。
+
+## 和 Filesystem Audit 的关系
+
+两者职责不同。
+
+### MCP-aware runtime gate
+
+- 检查 live editor 真相
+- 检查 live screen 真相
+- 在假进度扩散前发现 runtime/source 不收敛
+
+### Filesystem audit
+
+- 检查磁盘上的项目真相
+- 检查目录卫生
+- 检查完成态完整性
+
+建议的终态规则：
+
+- 只有 MCP-aware runtime gate 通过，同时 filesystem completion audit 也通过，才能声明完成
+
+## 为什么不该先做成 CLI 功能
+
+当前 CLI 只能读文件系统。
+
+它没有 MCP transport、没有 session identity，也读不到当前 live Pencil editor。
+
+所以如果一上来把 MCP-aware gate 做成 CLI 功能，会在结构上不可靠。
+
+当前更合理的定位是：
+
+- 作为 agent 执行的 runtime checkpoint
+- 而不是独立 CLI audit mode
+
+## 需要避免的失败方式
+
+1. 把 `new` 当成已经持久化的 `.pen`
+2. 把 PNG 导出当成设计源证据
+3. 把旧 live document 的 node id 继续当成当前 editor 的事实
+4. runtime/source 不一致时静默自我“和解”
+5. 未经明确规则，就把 live editor 自动写回 `.pen`
+
+## 第一版最小实现范围
+
+第一版实现应该非常收敛。
+
+只做：
+
+1. 读取 active editor 状态
+2. 读取声称完成的 anchor screen id
+3. 和 `design-registry.md` 以及 shell-visible `.pen` 做对照
+4. 记录结构化 PASS/WARN/BLOCK 结果
+5. runtime truth 和 filesystem truth 不一致时阻断完成态
+
+不做：
+
+- 自动重建 `.pen`
+- 除 checkpoint 记录外的自动文件修改
+- 新增面向 live runtime 的 CLI 命令
+
+## 仍待解答的问题
+
+这些问题应该在实现设计阶段解决，而不是在当前提案阶段拍板：
+
+1. 由哪个现有命令路由负责调用 runtime gate？
+2. runtime 证据只写进 `pencil-design.md`，还是也同步到 `design-registry.md`？
+3. editor-path mismatch 被 reconciliation 后，应如何记录才不会鼓励漂移？
+4. gate 应该按每个 approved anchor 运行，还是按每轮 design phase 运行？
+
+## 建议
+
+如果继续推进，只建议做一版收敛的 agent 执行型 MCP-aware runtime gate。
+
+不要顺手扩成：
+
+- CLI transport 工程
+- 自动持久化修复
+- 通用 MCP session 管理
+
+当前已经验证过的稳妥路径是：
+
+1. 保留 filesystem `audit` 作为持久化和终态兜底
+2. 增加 runtime MCP-aware gate，专门处理 source convergence 和 live screen presence
+3. 只有两层都通过，才允许终态完成

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

@@ -91,7 +91,8 @@ Da Vinci 应该：
    - 优先登记 `.da-vinci/designs/` 下的本地 `.pen` 路径
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
-   - 确保当前设计真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -112,7 +113,8 @@ Da Vinci 应该：
 5. 生成 `specs/<capability>/spec.md`
 6. 生成 `page-map.md`
 7. 继续到设计、绑定、任务和实现
-   - 把当前设计真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
 
 ## 3. `redesign-from-code`
 
@@ -138,8 +140,10 @@ Da Vinci 应该：
    - 在大规模 anchor 设计前，先写 visual thesis、content plan、interaction thesis 和 structural-delta 说明
    - 先做 1 到 3 个 anchor surface，再扩展更多页面
    - 首轮设计由解析出来的主 visual adapter 主导
-   - 把新的 Pencil 基线真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
    - 在第一次成功写入 Pencil 后，立即验证登记的 `.pen` 路径已经成为 shell 可见文件
+   - 截图导出必须写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -158,13 +162,19 @@ Da Vinci 应该：
 - 对复杂产品，先把 1 到 3 个 anchor surface 做到通过截图审查，再扩展其他页面
 - 对每个 anchor surface，都要说明“新的构图与当前布局结构相比具体改了什么”
 - 只要截图分析指出 hierarchy、spacing、clarity、inconsistency 或 unresolved placeholder 问题，就不能自动判通过
+- 不要把截图审查写成“看起来很好”；必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改
 - 在扩展更多页面前，先从已通过的 anchor surface 中抽出一组 shared primitives
 - 只使用 Pencil 支持的属性，不要继续使用 `flex`、`margin` 这类 Web/CSS 属性
+- 在发送非小型 `batch_design` 之前，如果有 shell 能力，先对 Pencil operations 做 preflight
+- 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
 - 一个实现页如果包含多个 Fragment、多个 tab、多个状态或多个 overlay，应该拆成多个设计 surface
 - `design-registry.md` 里的首选 `.pen` 路径由工作流自动维护，不应该依赖用户手工填写
 - 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
+- 不要把 interactive `save()` 当作可靠的持久化真相；应从当前 MCP 可读快照重建并覆盖项目内 `.pen`
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 - `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
+- 截图 PNG 只是审查产物，不能替代登记好的 `.pen` 设计源
+- 如果当前 Pencil editor 仍然是 `new` 或其他未命名 live document，就不能宣布工作流完成
 
 ## 4. `feature-change`
 
@@ -180,7 +190,8 @@ Da Vinci 应该：
 4. 复用或更新 `design-registry.md`
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
-   - 把更新后的 `.pen` 文件真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
+   - 如果这次改动还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现

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

@@ -13,6 +13,8 @@
 3. 再选和项目复杂度、交付意图匹配的提示词版本
 4. 两者一起放进工作流设置
 5. 只有在项目存在特殊真相源或平台约束时，再继续收紧提示词
+6. 如果 Pencil MCP 可用，优先使用已经明确要求 MCP runtime gate 和 completion audit 的那版 redesign 提示词
+7. 如果项目要把 `.pen` 真正持久化到本地，优先使用已经区分“首次生成快照”和“继续迭代覆盖保存”的那版提示词，不要依赖 interactive `save()`
 
 可用模板：
 
@@ -26,6 +28,7 @@
 - 提示词模板负责定义工作流意图、拆分规则和真相源处理方式
 - `Visual Assist` 模板负责定义 UI 设计增强偏好
 - form factor 专用的 layout hygiene 仍然是独立硬闸门，screen 在通过 screenshot review 前必须应用对应规则
+- MCP runtime gate 和 `da-vinci audit --mode completion ...` 属于工作流 gate，不属于 `Visual Assist` 配置本身
 - 两者一起使用，结果通常更稳
 
 现在每个场景模板里都固定包含：

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/.
 ```
@@ -41,12 +44,22 @@ 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 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 工件写到标准路径。
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 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/.
 ```
@@ -63,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.
 ```
 
@@ -73,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/.
 ```
@@ -41,6 +44,7 @@ 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 activities, fragments, tabs, dialogs, bottom sheets, nested flows, overlays, and materially different states before broad Pencil work.
 Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
+在开始第一个 anchor surface 之前，先把 discovery 和 design-source 工件写到标准路径。
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 State the resolved primary visual adapter explicitly in the log and name any requested adapters that are unavailable.
@@ -51,9 +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/.
@@ -71,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.
 ```
 
@@ -81,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.
 ```