@xenonbyte/da-vinci-workflow 0.1.16 → 0.1.18

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

@@ -2,6 +2,9 @@
 
 适用于平板优先，或强依赖扩展触控区域的产品。
 
+这些提示词变体主要服务于设计驱动的 `redesign-from-code` 场景，前提是 workflow mode 已经明确。
+如果当前 mode 是 `overhaul-from-code`，应该先把 `proposal.md`、`migration-contract.md` 和目标 `specs/` 稳定下来，再按需要改写这个模板，而不是直接原样套用。
+
 建议搭配：
 
 - `docs/zh-CN/visual-assist-presets/tablet-app.md`
@@ -19,6 +22,61 @@
 - `Design-only` 适合先把设计链路和绑定做完，但暂时不改代码。
 - `Continue` 适合已经有 `.da-vinci/` 工件，需要继续推进的项目。
 
+## Overhaul From Code
+
+当平板产品已经存在，但 split-pane 行为、流程逻辑、方向感知结构或页面职责也要一起重写，而不是只做视觉翻新时，用这组模板。
+
+### Overhaul Intake
+
+```text
+$da-vinci use intake for this existing tablet product.
+
+This is a broad overhaul, not only a UI refresh.
+Current tablet codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+We need to redefine flows, orientation-aware structure, page responsibilities, and selected surfaces while preserving only approved integrations, permissions, and constraints.
+Recommend the best Da Vinci mode and generate the best executable next-step prompt.
+```
+
+### Overhaul Breakdown
+
+```text
+$da-vinci use overhaul-from-code to inventory the current tablet product, define preserve/revise/retire/unknown boundaries, and stabilize the new target requirements before broad design.
+
+Current tablet codebase is reference evidence and migration baseline, not the final target behavior truth.
+Create or update:
+- .da-vinci/project-inventory.md
+- .da-vinci/changes/<change-id>/proposal.md
+- .da-vinci/changes/<change-id>/migration-contract.md
+- .da-vinci/changes/<change-id>/specs/
+- .da-vinci/page-map.md
+
+Inventory split-pane regions, sidebars, expanded canvases, dialogs, sheets, orientation-driven changes, and materially different states before broad Pencil work.
+Do not start broad Pencil work until the new proposal, migration contract, target specs, and page map are stable enough to drive design.
+```
+
+### Overhaul Design
+
+```text
+$da-vinci use overhaul-from-code to design the new target tablet surfaces from the approved overhaul artifacts.
+
+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 tablet codebase only as reference evidence and migration context.
+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.
+```
+
+### Overhaul Continue
+
+```text
+$da-vinci use continue for this existing overhaul-from-code tablet workflow.
+
+Use the existing Da Vinci artifacts.
+Detect whether the workflow should return to breakdown, continue with design, generate tasks, continue implementation, or verify drift.
+Prefer the artifact-backed next safe stage instead of restarting the overhaul from scratch.
+```
+
 ## Simple Redesign
 
 ```text
@@ -28,7 +86,7 @@ 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 编辑前，优先执行 `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 ignores tablet-scale composition or collapses into a stretched phone layout.
@@ -55,7 +113,7 @@ 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`。
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+在第一次 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`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
@@ -76,7 +134,7 @@ 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 编辑前，优先执行 `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.
@@ -89,7 +147,7 @@ $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.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
+把登记的项目内 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` 这条底层链路。
 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>`。

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

@@ -2,6 +2,9 @@
 
 适用于浏览器中的产品型界面，或带有 app surface 的 Web 产品。
 
+这些提示词变体主要服务于设计驱动的 `redesign-from-code` 场景，前提是 workflow mode 已经明确。
+如果当前 mode 是 `overhaul-from-code`，应该先把 `proposal.md`、`migration-contract.md` 和目标 `specs/` 稳定下来，再按需要改写这个模板，而不是直接原样套用。
+
 建议搭配：
 
 - `docs/zh-CN/visual-assist-presets/web-app.md`
@@ -19,6 +22,61 @@
 - `Design-only` 适合先把设计链路和绑定做完，但暂时不改代码。
 - `Continue` 适合已经有 `.da-vinci/` 工件，需要继续推进的项目。
 
+## Overhaul From Code
+
+当 Web 产品已经存在，但 routes、流程逻辑、信息架构或认证后产品结构也要一起重写，而不是只做视觉翻新时，用这组模板。
+
+### Overhaul Intake
+
+```text
+$da-vinci use intake for this existing web product.
+
+This is a broad overhaul, not only a UI refresh.
+Current web codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+We need to redefine flows, route structure, page responsibilities, and selected surfaces while preserving only approved integrations, permissions, and constraints.
+Recommend the best Da Vinci mode and generate the best executable next-step prompt.
+```
+
+### Overhaul Breakdown
+
+```text
+$da-vinci use overhaul-from-code to inventory the current web product, define preserve/revise/retire/unknown boundaries, and stabilize the new target requirements before broad design.
+
+Current web codebase is reference evidence and migration baseline, not the final target behavior truth.
+Create or update:
+- .da-vinci/project-inventory.md
+- .da-vinci/changes/<change-id>/proposal.md
+- .da-vinci/changes/<change-id>/migration-contract.md
+- .da-vinci/changes/<change-id>/specs/
+- .da-vinci/page-map.md
+
+Inventory product surfaces, auth surfaces, responsive shells, dialogs, drawers, overlays, and materially different states before broad Pencil work.
+Do not start broad Pencil work until the new proposal, migration contract, target specs, and page map are stable enough to drive design.
+```
+
+### Overhaul Design
+
+```text
+$da-vinci use overhaul-from-code to design the new target web surfaces from the approved overhaul artifacts.
+
+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 web codebase only as reference evidence and migration context.
+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.
+```
+
+### Overhaul Continue
+
+```text
+$da-vinci use continue for this existing overhaul-from-code web workflow.
+
+Use the existing Da Vinci artifacts.
+Detect whether the workflow should return to breakdown, continue with design, generate tasks, continue implementation, or verify drift.
+Prefer the artifact-backed next safe stage instead of restarting the overhaul from scratch.
+```
+
 ## Simple Redesign
 
 ```text
@@ -28,7 +86,7 @@ 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 编辑前，优先执行 `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 a generic SaaS card grid or a recolor of the old interface.
@@ -56,7 +114,7 @@ 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`。
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+在第一次 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`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
@@ -77,7 +135,7 @@ 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 编辑前，优先执行 `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.
@@ -90,7 +148,7 @@ $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.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
+把登记的项目内 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` 这条底层链路。
 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>`。

package/docs/zh-CN/visual-adapters.md

@@ -167,6 +167,12 @@ adapter 选择经验：
 - 在大规模 Pencil 设计前先拆 activities、fragments、tabs、overlays 和明显不同的 states
 - 明确要求 fresh composition，而不是旧 UI 改色或轻微挪位置
 
+对于 `overhaul-from-code`，还应该补三句：
+
+- 重申 existing code 是参考基线和迁移约束，不是新系统自动成立的最终行为真相
+- 在大规模 Pencil 设计前先稳定 `proposal.md`、`migration-contract.md`、目标 `specs/` 和 `page-map.md`
+- 要求 anchor surface 体现新的流程和信息架构，而不是只给旧壳换皮
+
 ## 解析顺序
 
 adapter 的解析顺序建议固定为：
@@ -263,6 +269,12 @@ If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+如果是流程和逻辑也会一起变化的存量系统大改版，应该改用：
+
+```text
+$da-vinci use overhaul-from-code to inventory the current Android product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and then create a new Pencil-backed overhaul plan.
+```
+
 如果是复杂 Android 或多 surface 项目，建议再额外加上：
 
 ```text

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

@@ -127,8 +127,8 @@ 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.
-如果这一轮开始时还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP live 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
-如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+优先在第一次 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>`。
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
@@ -138,7 +138,33 @@ Do not report completion if the `.pen` source exists only in memory or only as e
 Do not pass design checkpoint if the result is just a skin-swap of the old UI.
 ```
 
-## 4. `feature-change`
+## 4. `overhaul-from-code`
+
+适用：
+
+- 现有产品已经存在
+- 但流程、逻辑、信息架构和 UI 都可能被一起重写
+
+示例请求：
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and generate a new Pencil-backed overhaul plan.
+```
+
+预期流程：
+
+1. 先把现有产品盘点成 `project-inventory.md`
+2. 在 `proposal.md` 里定义目标方向、范围和非目标
+3. 创建 `migration-contract.md`，标记 preserve / revise / retire / unknown
+4. 当一个大 spec 过粗时，把 rewrite 拆成多个 `specs/<slice>/spec.md`
+5. 重建 `page-map.md`，描述目标产品，而不是只复制旧 route tree
+6. 再进入 `DA-VINCI.md`、`design-registry.md`、`design-brief.md`、`design.md`
+7. 通过现有 anchor-first 渲染链生成 Pencil overhaul 页面
+8. 绑定目标实现页和 Pencil 页面
+9. 生成和 overhaul slice、migration boundary 对齐的任务
+10. 基于新的 specs 实现和验证，而不是默认继承旧行为
+
+## 5. `feature-change`
 
 适用：
 
@@ -174,7 +200,7 @@ 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`，先在这里 seed 一个登记好的 `.pen`，再开始第一次 Pencil 编辑，并把后续 live 编辑持续绑定到这个路径。
 如果项目里原本已有 `.pen`，继续设计后要把当前 MCP 快照覆盖写回同一路径。
 ```
 
@@ -214,3 +240,4 @@ Continue into full-delivery.
 - `pencil-bindings.md` 追踪实现页面与 Pencil 页面之间的绑定
 - `pencil-design.md` 在需要时记录 adapter 如何影响这次设计稿
 - 工作流默认是 `autonomous-by-default`
+- `overhaul-from-code` 仍然要遵守同一套 `.pen` 持久化、runtime gate 和 completion audit 规则

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

@@ -0,0 +1,233 @@
+# 工作流总览
+
+> 中文配套文档。若与英文原文存在差异，请以 `docs/workflow-overview.md` 为准。
+
+这份文档描述当前 Da Vinci 的完整主工作流。
+
+适合在你需要理解下面这些内容时阅读：
+
+- mode 选择
+- 工件生成顺序
+- Pencil 支撑的设计阶段
+- 页面到设计的绑定
+- 实现与验证
+
+如果你想看 Pencil 渲染、持久化、门禁和审计的专门说明，请看 [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/pencil-rendering-workflow.md)。
+如果你想看逐个 `dv:` 命令的职责、下一步推荐和 `verify` 回退规则，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
+
+## 核心契约
+
+Da Vinci 围绕一个固定契约工作：
+
+- requirements 决定 behavior
+- Pencil 决定 presentation
+- code 同时遵循两者
+
+这意味着：
+
+- requirements 和 specs 是行为真相源
+- 项目内 `.pen` 是设计真相源
+- 实现必须能追溯到这两层
+
+## 主流程
+
+1. 选择正确的 mode。
+2. 生成 discovery 和 scope 工件。
+3. 解析项目内设计源，并登记优先 `.pen` 路径。
+4. 先做 anchor surfaces 并完成设计审查。
+5. 让 live Pencil 会话和登记好的 `.pen` 收敛。
+6. 建立实现页面到 Pencil 页面之间的绑定。
+7. 生成任务。
+8. 实现。
+9. 验证需求漂移和设计漂移。
+
+## 标准工件骨架
+
+根据 mode 的不同，Da Vinci 一般会围绕这组工件推进：
+
+- `.da-vinci/project-inventory.md`
+- `.da-vinci/changes/<change-id>/design-brief.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
+
+`DA-VINCI.md` 仍然是项目级工作流和视觉约束文件。
+
+## 分阶段说明
+
+### 1. Intake 与 Mode 选择
+
+可选 mode：
+
+- `greenfield-spec`
+- `greenfield-brainstorm`
+- `redesign-from-code`
+- `overhaul-from-code`
+- `feature-change`
+
+提示词入口：
+
+- `intake`
+- `prompt`
+- `continue`
+
+### 2. Discovery 与 Scope
+
+在大规模 Pencil 设计前，工作流应该已经明确：
+
+- 产品形态和 form factor
+- 当前 change scope
+- 当前页面与明显不同的状态
+- 项目里是否已经有登记的 `.pen`
+
+对 redesign 工作来说，在 discovery 和 design-source 工件落标准路径前，不允许直接开始大范围 Pencil 生成。
+
+如果是 `overhaul-from-code`，在大规模 Pencil 设计前还必须至少稳定这些工件：
+
+- `project-inventory.md`
+- `proposal.md`
+- `migration-contract.md`
+- 目标 `specs/`
+- `page-map.md`
+- `DA-VINCI.md`
+- `design-registry.md`
+- `design-brief.md`
+- `design.md`
+
+它们共同定义了新的真相源和迁移边界。
+
+### 3. 设计源登记
+
+`design-registry.md` 必须登记一个明确的项目内 `.pen` 路径，位于 `.da-vinci/designs/` 下。
+
+这个路径是工作流状态，不是随意写的占位符。
+
+### 4. Anchor-First 设计
+
+先做 1 到 3 个 anchor surfaces。
+
+每个 anchor 都必须：
+
+- 在 redesign-from-code 下写 structural-delta 说明
+- 如果当前 mode 是 `overhaul-from-code`，还要和已经批准的 `migration-contract.md`、`page-map.md`、新 `specs/` 保持一致
+- 经过 screenshot review
+- 满足当前 form factor 的 layout-hygiene 规则
+- 通过 design checkpoint 才能扩屏
+
+anchor 通过后，再抽 shared primitives，然后再扩更多页面。
+
+### 5. 设计源收敛
+
+在 mapping 或实现被视为安全之前，Da Vinci 会跑：
+
+- `design-source checkpoint`
+- 如果启用了 Pencil MCP，则跑 `MCP runtime gate`
+- 工作中期跑 `da-vinci audit --mode integrity <project-path>`
+
+这些检查用来确认：
+
+- 登记好的 `.pen` 路径是明确的
+- active editor 是正确的设计源
+- shell 上确实有 `.pen`
+- live snapshot 和 persisted snapshot 已同步
+
+### 6. Mapping
+
+`pencil-bindings.md` 用来绑定实现页面和 Pencil 页面。
+
+`mapping checkpoint` 会确保实现不再靠猜：
+
+- 每个实现页面都有 Pencil 页面或明确例外
+- route 名和 Pencil 名能追溯
+- shared layout 和 reusable region 已清楚
+
+### 7. Tasks 与实现
+
+mapping 通过后：
+
+- 生成 `tasks.md`
+- 基于 requirements 和 Pencil 数据实现
+- 验证需求漂移和设计漂移
+
+### 8. 终态完成
+
+在下面这些条件未满足前，不能宣布 `design complete` 或 `workflow complete`：
+
+- design checkpoint 不再阻塞
+- design-source checkpoint 至少 `PASS`
+- 如果用了 Pencil MCP，runtime gate 结果可接受
+- `da-vinci audit --mode completion --change <change-id> <project-path>` 通过
+
+## 门禁与审计
+
+### Design Checkpoint
+
+会拦截：
+
+- anchor 未稳定就扩屏
+- 旧 UI 换皮
+- 大量 placeholder scaffold
+- 视觉锚点很弱
+- 忽略 screenshot review 问题
+
+### Design-Source Checkpoint
+
+确认：
+
+- 登记的 `.pen`
+- 当前 active editor
+- shell 可见 `.pen`
+
+已经收敛为同一个项目级设计源。
+
+### MCP Runtime Gate
+
+确认 live 会话真相：
+
+- 不是 `new`
+- registered `.pen` 存在后没有继续用空 `filePath`
+- claimed anchor id 在 active editor 里真实存在
+- completion 阶段 live snapshot hash 和 persisted hash 一致
+
+### Integrity Audit
+
+`da-vinci audit --mode integrity <project-path>`
+
+在工作中跑，尤其是在第一次成功写入 `.pen` 之后。
+
+### Completion Audit
+
+`da-vinci audit --mode completion --change <change-id> <project-path>`
+
+在任何终态完成声明前跑。
+
+## 流程图
+
+```mermaid
+flowchart TD
+    A[选择 mode 或使用 intake/prompt/continue] --> B[生成 discovery 和 scope 工件]
+    B --> C[在 design-registry.md 中登记项目内 .pen]
+    C --> D[渲染 1 到 3 个 anchor surfaces]
+    D --> E{design checkpoint 通过?}
+    E -- 否 --> D
+    E -- 是 --> F[持久化并收敛项目内 .pen]
+    F --> G{design-source checkpoint 通过?}
+    G -- 否 --> F
+    G -- 是 --> H[运行 MCP runtime gate 和 integrity audit]
+    H --> I{runtime 与 integrity 健康?}
+    I -- 否 --> F
+    I -- 是 --> J[建立 pencil-bindings.md 和 page mapping]
+    J --> K{mapping checkpoint 通过?}
+    K -- 否 --> J
+    K -- 是 --> L[生成任务并实现]
+    L --> M[运行 verification]
+    M --> N{completion audit 通过?}
+    N -- 否 --> F
+    N -- 是 --> O[workflow complete]
+```

package/lib/audit.js

@@ -1,5 +1,7 @@
 const fs = require("fs");
 const path = require("path");
+const { getStandardPenStatePath, readPenState, hashPenDocument, readPenDocument } = require("./pen-persistence");
+const { getSessionStatePath, readSessionState } = require("./pencil-session");
 
 const IMAGE_EXPORT_PATTERN = /\.(png|jpe?g|webp|pdf)$/i;
 
@@ -105,9 +107,12 @@ function resolveScopedChangeDirs(projectRoot, changesDir, options, failures, war
 }
 
 function addMissingArtifacts(projectRoot, artifactPaths, targetList) {
-  for (const artifactPath of artifactPaths) {
+  for (const artifactPath of [...new Set(artifactPaths)]) {
     if (!pathExists(artifactPath)) {
-      targetList.push(`Missing required artifact: ${relativeTo(projectRoot, artifactPath)}`);
+      const message = `Missing required artifact: ${relativeTo(projectRoot, artifactPath)}`;
+      if (!targetList.includes(message)) {
+        targetList.push(message);
+      }
     }
   }
 }
@@ -119,6 +124,7 @@ function auditProject(projectPathInput, options = {}) {
   const designsDir = path.join(daVinciDir, "designs");
   const changesDir = path.join(daVinciDir, "changes");
   const designRegistryPath = path.join(daVinciDir, "design-registry.md");
+  const pencilSessionPath = getSessionStatePath(projectRoot);
 
   const failures = [];
   const warnings = [];
@@ -228,6 +234,64 @@ function auditProject(projectPathInput, options = {}) {
       failures.push(
         `Registered design source is missing on disk: ${relativeTo(projectRoot, registeredPenPath)}`
       );
+      continue;
+    }
+
+    const statePath = getStandardPenStatePath(registeredPenPath);
+    const state = readPenState(registeredPenPath);
+    if (!state) {
+      const message = `Registered design source is missing state metadata: ${relativeTo(projectRoot, statePath)}`;
+      if (mode === "completion") {
+        failures.push(message);
+      } else {
+        warnings.push(message);
+      }
+      continue;
+    }
+
+    const persistedDocument = readPenDocument(registeredPenPath);
+    const currentHash = hashPenDocument(persistedDocument);
+    if (state.snapshotHash !== currentHash) {
+      failures.push(
+        `Registered design source hash does not match its state metadata: ${relativeTo(projectRoot, registeredPenPath)}`
+      );
+    } else {
+      notes.push(
+        `Detected persisted design-source hash for ${relativeTo(projectRoot, registeredPenPath)}.`
+      );
+    }
+  }
+
+  const sessionState = readSessionState(projectRoot);
+  if (registeredPenPaths.length > 0 || penFiles.length > 0) {
+    if (!sessionState) {
+      const message = `Missing Pencil session state: ${relativeTo(projectRoot, pencilSessionPath)}`;
+      if (mode === "completion") {
+        failures.push(message);
+      } else {
+        warnings.push(message);
+      }
+    } else {
+      if (!sessionState.penPath) {
+        failures.push("Pencil session state is missing the bound `.pen` path.");
+      }
+
+      if (mode === "completion" && sessionState.status !== "closed") {
+        failures.push("Completion audit requires the Pencil session to be ended and recorded as `closed`.");
+      }
+
+      if (sessionState.penPath && pathExists(sessionState.penPath)) {
+        const penState = readPenState(sessionState.penPath);
+        const persistedHash = penState && penState.snapshotHash ? String(penState.snapshotHash) : "";
+
+        if (sessionState.lastPersistedHash && persistedHash && sessionState.lastPersistedHash !== persistedHash) {
+          failures.push("Pencil session state hash does not match the current persisted `.pen` state hash.");
+        } else if (persistedHash) {
+          notes.push(
+            `Detected Pencil session state for ${relativeTo(projectRoot, sessionState.penPath)}.`
+          );
+        }
+      }
     }
   }