@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

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

@@ -67,13 +67,17 @@
 
 - 有 shell 能力时，先运行 `da-vinci workflow-status --project <path> [--change <id>] --json`
 - 再用 `da-vinci next-step --project <path> [--change <id>]` 作为第一续跑路由信号
+- 如可用，优先读取 `da-vinci next-step --project <path> [--change <id>] --json`，显式获取 discipline marker、execution-profile 与 verification freshness 信息
 - 如果运行时 spec 质量还不确定，进入 `build` 前先运行 `da-vinci lint-spec --project <path> [--change <id>]`
 - 如果页面或状态在规划工件中的传播关系不确定，进入 `build` 前先运行 `da-vinci scope-check --project <path> [--change <id>]`
+- 如果任务拆解质量不确定，进入 `build` 前先运行 `da-vinci lint-tasks --project <path> [--change <id>]`
 - 进入终态前先运行 `da-vinci verify-bindings --project <path> [--change <id>]` 与 `da-vinci verify-coverage --project <path> [--change <id>]`
 - 当规划切片有改动且需要恢复判断时，运行 `da-vinci diff-spec --project <path> [--change <id>]`
 - 先根据工件和 checkpoint 真相决定路由
 - Context Delta 只用于恢复和解释，不用于覆盖选路
 - 如果 Context Delta 与当前工件冲突，选路时忽略冲突内容并标记冲突
+- 如果 design approval discipline marker 缺失、格式错误或过期，路由应停留在 `design` 或 `tasks`，不能直接推进到 `build`
+- 如果提示了 bounded parallel 执行，先运行 `da-vinci worktree-preflight --project <path> [--change <id>]`，再决定是否输出并行 build continuation prompt
 
 ## 默认推荐流程
 
@@ -94,6 +98,7 @@
 
 - 如果设计已经完成，但 `tasks.md` 还不存在，下一步主推荐通常应该是 `tasks`，而不是 `build`
 - 只有任务和实现就绪度都已经明确时，才把 `build` 作为主推荐下一步
+- 在 fresh verification evidence 缺失时，不能输出终态 completion 表述；应明确要求 completion audit
 
 ## 平台语法
 

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

@@ -21,7 +21,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 / save-current-design / end` 的提示词；并明确区分 `saved` / `blocked` / `unavailable`，只有高层保存不可用时才回退到底层 payload 持久化链路
 
 可用模板：
 

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

@@ -120,7 +120,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`。
-在第一次 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 save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 截图导出只能写到 `.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 结果都要视为阻断。
@@ -156,7 +156,7 @@ 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.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 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/.
@@ -190,7 +190,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.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 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` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 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/mobile-app.md

@@ -126,7 +126,7 @@ Use only Pencil-supported properties; do not use web-only props like flex or mar
 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`。
-在第一次 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 save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
@@ -164,7 +164,7 @@ 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.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 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/.
@@ -198,7 +198,7 @@ $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.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 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` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 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>`。

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

@@ -120,7 +120,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`。
-在第一次 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 save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 截图导出只能写到 `.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 结果都要视为阻断。
@@ -156,7 +156,7 @@ 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.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 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/.
@@ -190,7 +190,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.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 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` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 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

@@ -121,7 +121,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`。
-在第一次 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 save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 截图导出只能写到 `.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 结果都要视为阻断。
@@ -157,7 +157,7 @@ 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.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 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/.
@@ -191,7 +191,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.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 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` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 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/skill-usage.md

@@ -85,6 +85,12 @@ $da-vinci use continue for <existing workflow state>
   - 当运行时 spec 质量还不够确定时使用
 - `da-vinci scope-check`
   - 当规划工件之间页面/状态传播关系还不清楚时使用
+- `da-vinci lint-tasks`
+  - 校验 task groups 是否包含 discipline markers、明确文件落点、执行意图与 verification 命令
+- `da-vinci lint-bindings`
+  - 当 `pencil-design.md` 与 `pencil-bindings.md` 同时存在时运行，确保实现落点证据可解析
+- `da-vinci worktree-preflight`
+  - 准备 bounded parallel 执行前先跑，用于判断是否建议启用本地 worktree 隔离
 
 如果你已经在项目根目录里，`--project` 通常可以省略，因为 CLI 默认会回退到当前目录。
 
@@ -95,8 +101,17 @@ da-vinci workflow-status
 da-vinci next-step
 da-vinci lint-spec
 da-vinci scope-check
+da-vinci lint-tasks
 ```
 
+实现阶段不要只靠聊天总结，建议同步写入机器可读证据：
+
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> ...`
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage spec ...`
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage quality ...`
+
+同一 task group 只有在 `spec` review 已是 `PASS` 时，`quality` review 才允许通过。
+
 ## 中途退出后，下次怎么恢复
 
 最稳妥的恢复顺序是：
@@ -107,6 +122,7 @@ da-vinci scope-check
 4. 如果规划传播关系不确定，跑 `da-vinci scope-check`
 5. 如果 planning 工件相对上次稳定状态有变化，跑 `da-vinci generate-sidecars` 和 `da-vinci diff-spec`
 6. 在终态前，跑 `da-vinci verify-bindings` 和 `da-vinci verify-coverage`
+7. 如果要做 completion 表述，确认 `verify-coverage` 的 freshness 仍然有效，并运行 `da-vinci audit --mode completion --change <id> <project-path>`
 
 恢复时应该遵循工件，而不是旧聊天上下文：
 
@@ -146,67 +162,74 @@ npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
 
 TUI 提供这些能力：
 
-- 按工作流阶段对命令分组
-- 中英文双语界面说明
-- 顶部显示当前项目路径和 change-id 上下文
-- 执行前可先看命令预览
-- 一键切换 `--strict`、`--json`、`--continue-on-error`
-- 对 `<pen-path>` 这类还没补具体路径的命令，支持先编辑预览再执行
+- 首屏按场景组织：`安装与卸载`、`当前状态`、`切换工作项`、`设计操作`、`实施前检查`、`验收前检查`、`设置`
+- 常用链路直接做成组合入口（续跑、实施前检查、验收前检查）
+- `设计操作` 聚焦实用设计操作（`保存当前设计稿`、`同步图标库`、`Visual Assist 预设`）
+- `安装与卸载` 提供三个动作：`状态`（查看 `da-vinci status`）、`安装`（一键安装所有支持平台）、`卸载`（一键卸载所有支持平台）
+- 界面中英双语，但 Visual Assist 输出始终使用英文权威源
+- 顶部只保留最小上下文（项目 + change）
+- `设置` 仅保留 `语言` 和 `日志`
+- `设置 > 日志` 提供项目内每日诊断日志（`.da-vinci/logs/YYYY-MM-DD.ndjson`）
 
-### TUI 阶段图
+### TUI 场景图
 
 ```mermaid
 flowchart TD
-  A[启动 da-vinci tui] --> B[设置 project path 和 change-id 上下文]
-  B --> C[选路与续跑<br/>workflow-status / next-step]
-  C --> D{当前处于哪个阶段?}
-
-  D --> E[规划与漂移检查<br/>lint-spec / scope-check / lint-tasks / lint-bindings / generate-sidecars / diff-spec / scaffold]
-  D --> F[视觉与审查<br/>icon-sync / icon-search / supervisor-review]
-  D --> G[Pen 文件与同步<br/>preflight-pencil / ensure-pen / write-pen / check-pen-sync / check-pen-baseline / sync-pen-source / snapshot-pen]
-  D --> H[Pencil 会话<br/>pencil-lock * / pencil-session begin|persist|end|status]
-  D --> I[验证与完成<br/>verify-bindings / verify-implementation / verify-structure / verify-coverage / audit]
-  D --> J[初始化与工具<br/>install / uninstall / status / validate-assets / bootstrap-project]
-
-  E --> I
-  F --> G
-  G --> H
-  H --> E
-  I --> K{可以收尾了吗?}
-  K -->|还不行| C
-  K -->|可以| L[跑 completion audit 并做终态声明]
+  A[启动 da-vinci tui] --> B[设置 project 和 change 上下文]
+  B --> C[安装与卸载<br/>状态 + 一键安装/卸载全部平台]
+  B --> D[当前状态<br/>workflow-status + next-step 总结]
+  B --> E[切换工作项<br/>选择已有 change]
+  B --> F[设计操作<br/>图标同步 + Visual Assist 预设]
+  B --> G[实施前检查<br/>实现前就绪度检查]
+  B --> H[验收前检查<br/>verify-* 链路]
+  B --> I[设置<br/>语言 + 日志]
 ```
 
 你可以把它理解成这四条最实用的规则：
 
-- 先从“选路与续跑”开始
-- 再进入当前 blocker 所在的阶段
-- 只要中途暂停，或者工件发生了实质变化，就回到“选路与续跑”
-- 只有验证链和 completion audit 都通过了，才进入终态
+- 先选“当前时机”对应的场景
+- 优先用场景入口完成常用检查
+- 只要中途暂停或路由不清晰，就进入“当前状态”
+- 只有“验收前检查”通过，才进入终态
+
+Visual Assist 预设映射（`设计操作 > Visual Assist 预设`）：
+
+- `Masterpiece` => `required reviewer signoff`
+- `High Quality` => `advisory reviewer`
+- `Normal` => `adapter-only`
+
+Visual Assist 受控写入规则：
+
+- 先选平台，再从 3 档质量中选择（对应 Variant 1/2/3）
+- 内容来自 `docs/visual-assist-presets/` 的英文权威源
+- 只替换项目根 `DA-VINCI.md` 的 `## Visual Assist`
+- 保留无关章节，避免重复 `## Visual Assist`
 
 主要按键：
 
 - `Up/Down` 或 `j/k`：移动选中项
-- `Enter` 或 `r`：执行当前命令
-- `h`：查看当前命令参数
-- `m`：先编辑预览命令
+- `Enter` 或 `r`：进入当前场景/动作
+- `u/d`：长内容按页上下翻
+- `g/G`：长内容跳到顶部/底部
 - `p`：修改项目路径上下文
 - `c`：修改或清空 change-id 上下文
 - `l`：切换中英文
+- `t`：主题识别不准时，手动切换主题模式
 - `s`：切换 `--strict`
 - `J`：切换 `--json`
 - `e`：切换 `--continue-on-error`
 - `?`：打开帮助
-- `q`：退出
+- `Ctrl-C`：紧急退出
 
 推荐的 TUI 使用顺序：
 
 1. 在项目根目录启动 TUI
-2. 先确认顶部的 project path 和 change-id
-3. 先跑 `workflow-status`
-4. 再跑 `next-step`
-5. 根据情况进入 `lint-spec`、`scope-check`、`tasks`、`verify-*`
-6. 如果是 Pencil 相关特殊命令，按 `m` 先把剩余占位符补全后再执行
+2. 先选当前任务对应的场景
+3. 再确认顶部的 project path 和 change-id
+4. 优先执行场景入口（`切换工作项`、`实施前检查`、`安装与卸载`、`验收前检查`）；需要续跑判断时进入 `当前状态`
+5. 需要管理 Visual Assist 时，进入 `设计操作 > Visual Assist 预设`，完成“平台 + 质量”选择后自动写入
+6. 需要查看安装态时进入 `安装与卸载 > 状态`；需要安装/卸载时进入 `安装与卸载 > 安装/卸载` 一键执行全部平台
+7. 排查问题时到 `设置 > 日志` 查看/复制当天日志；日志只做诊断证据，不替代工件真相
 
 ## 实用简化规则
 

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

@@ -110,17 +110,18 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 11. 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
 12. 如果这一轮开始时还没有登记的项目内 `.pen`，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，先 seed 登记路径并拿到全局锁，再开始第一次 Pencil 编辑
 13. 如果存在外部或历史 `.pen` 备份，在新一轮写入前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 不一致，先把选中的优先来源同步回 `<project-pen>`
-14. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
-15. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
-16. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
-17. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
-18. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
-19. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
-20. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
-21. 绑定路由和 Pencil 页面
-22. 生成和 redesign slice 对齐的任务
-23. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
-24. 只有在 completion gate 最终能通过时，才进入实现和验证
+14. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`
+15. 必须区分 `saved` / `blocked` / `unavailable`，只有 `saved` 才代表保存成功；`unavailable` 时才能回退到底层 payload 持久化链路
+16. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
+17. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
+18. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
+19. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+20. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
+21. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
+22. 绑定路由和 Pencil 页面
+23. 生成和 redesign slice 对齐的任务
+24. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
+25. 只有在 completion gate 最终能通过时，才进入实现和验证
 
 ### 复杂 Android 页面示例
 
@@ -145,7 +146,8 @@ If the same anchor surface rolls back twice, switch to micro-batches of 6 or few
 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 锁。
 如果存在外部或历史 `.pen`，先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 分叉，先确认来源优先级并把选中的来源同步回 `<project-pen>` 再继续。
-如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 live MCP 快照重新覆盖写回同一路径。
+如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci save-current-design --project <project-path>` 保存。
+必须区分 `saved` / `blocked` / `unavailable`；只有 `saved` 才是保存成功，`unavailable` 才能触发底层回退。
 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.
@@ -218,7 +220,7 @@ 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`，先在这里 seed 一个登记好的 `.pen`，再开始第一次 Pencil 编辑，并把后续 live 编辑持续绑定到这个路径。
-如果项目里原本已有 `.pen`，继续设计后要把当前 MCP 快照覆盖写回同一路径。
+如果项目里原本已有 `.pen`，继续设计后优先执行 `da-vinci save-current-design --project <project-path>` 持久化；只有高层保存返回 `unavailable` 时才回退到底层 payload 持久化。
 ```
 
 ## 图标库辅助示例

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

@@ -32,6 +32,12 @@ Da Vinci 围绕一个固定契约工作：
 - 项目内 `.pen` 是设计真相源
 - 实现必须能追溯到这两层
 
+真相与编排边界：
+
+- 选路和 completion 真相来自工件、checkpoint、execution signals 与 `audit`
+- execution profile、worktree preflight 等编排信息始终是 advisory 指导，不替代真相面
+- 编排提示不能覆盖来自工件、checkpoint 或 completion audit 的明确 `BLOCK`
+
 ## 主流程
 
 1. 选择正确的 mode。
@@ -62,6 +68,12 @@ Da Vinci 围绕一个固定契约工作：
   - 显式生成确定性的 planning sidecars，供 diff 和下游工具消费
 - `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
   - 校验从 bindings 到实现与结构覆盖的执行链证据
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> ...`
+  - 按 task group 持久化 implementer 结果包，便于恢复时读取未解决 blocker/concern
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> ...`
+  - 持久化有序两阶段 review 证据（先 `spec` 再 `quality`），并可写回 `verification.md`
+- `da-vinci worktree-preflight --project <path> [--change <id>] [--json]`
+  - 在准备 bounded-parallel 执行前提供 advisory 隔离预检
 - `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
   - 报告 spec/tasks/page-map/bindings sidecars 的规范化差异，支持安全续跑
 
@@ -159,6 +171,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 
 - `design-source checkpoint`
 - 如果启用了 Pencil MCP，则跑 `MCP runtime gate`
+- 发生实质性 live edit 后执行 `da-vinci save-current-design --project <project-path>`（高层绑定源保存路径）
 - 工作中期跑 `da-vinci audit --mode integrity <project-path>`
 - 在现有 change 工件里记录 checkpoint 邻近的 `Context Delta`
 
@@ -168,6 +181,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 - active editor 是正确的设计源
 - shell 上确实有 `.pen`
 - live snapshot 和 persisted snapshot 已同步
+- 高层保存结果被诚实处理（`saved` / `blocked` / `unavailable`）
 - 最近关键执行上下文可恢复，但不会替代工件真相的选路权
 
 ### 6. Mapping
@@ -185,7 +199,11 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 mapping 通过后：
 
 - 生成 `tasks.md`
+- 保持 task group 可解析：包含 discipline markers、文件目标、执行意图、review 意图和 verification 命令
 - 基于 requirements 和 Pencil 数据实现
+- 在大范围实现前，从 `workflow-status` 或 `next-step --json` 查看 `executionProfile`
+- 如果建议 bounded parallel，先跑 `da-vinci worktree-preflight --project <path> [--change <id>]`；隔离未就绪时降级为串行
+- 通过 `task-execution` 与有序 `task-review` 记录每个 task group 的执行与审查证据
 - 验证需求漂移和设计漂移
 
 ### 8. 终态完成
@@ -195,6 +213,7 @@ mapping 通过后：
 - design checkpoint 不再阻塞
 - design-source checkpoint 至少 `PASS`
 - 如果用了 Pencil MCP，runtime gate 结果可接受
+- in-scope 的实现和覆盖结论具备 fresh verification evidence
 - `da-vinci audit --mode completion --change <change-id> <project-path>` 通过
 
 补充说明：

package/examples/greenfield-spec-markupflow/.da-vinci/state/execution-signals/demo__lint-tasks.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "surface": "lint-tasks",
+  "status": "WARN",
+  "advisory": true,
+  "strict": false,
+  "failures": [
+    "Missing `.da-vinci/` directory."
+  ],
+  "warnings": [],
+  "notes": [
+    "lint-tasks defaults to advisory mode; pass `--strict` to block on findings."
+  ],
+  "timestamp": "2026-03-31T16:22:40.193Z",
+  "changeId": "demo"
+}