@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.2.3 - 2026-04-02
+
+### Added
+- scene-first `Design Ops` actions in TUI for managed `save-current-design`, icon sync progress feedback, and platform+quality Visual Assist presets
+- additional TUI/CLI regression coverage for scene ordering, route mapping, and environment-stable `save-current-design` unavailable behavior
+
+### Changed
+- TUI root scenes now keep the documented order (`Install & Uninstall`, `Current Status`, `Switch Work Item`, `Design Ops`, `Pre-Implementation Checks`, `Pre-Acceptance Checks`, `Settings`)
+- `Current Status` route mapping now keeps `/dv:tasks`, `/dv:build`, and bootstrap routes as direct command recommendations instead of forcing mismatched scene actions
+- README (EN/ZH) now documents the updated scene-first behavior and release highlights for `0.2.3`
+
+### Fixed
+- removed stale Advanced-command branches from TUI runtime routing and key handling so only reachable scene navigation paths remain
+- stabilized `save-current-design` unavailable-path CLI testing by isolating PATH during bridge-absent assertions
+
 ## v0.2.2 - 2026-03-31
 
 ### Added

package/README.md

@@ -28,18 +28,15 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.2`
+- `@xenonbyte/da-vinci-workflow@0.2.3`
 
-Release highlights for `0.2.2`:
+Release highlights for `0.2.3`:
 
-- added the built-in terminal TUI via `da-vinci tui` and `da-vinci-tui`, with phase-grouped command discovery, bilingual labels, command previews, and project/change context management
-- added command-parameter help inside the TUI so operators can inspect supported flags and placeholder requirements without leaving the terminal
-- added operator-facing English and Chinese workflow guides that explain first-run routing, implementation handoff, pause/resume rules, and TUI usage
-- expanded release coverage with TUI-specific regression tests plus package-content checks for the dedicated TUI bin and shipped `tui/` assets
-- fixed TUI exit handling so `q` and `Ctrl-C` actually terminate the interactive session instead of leaving stdin resumed in the foreground
-- fixed preview-command editing so unclosed quotes are handled as a recoverable TUI error instead of crashing the process
-- fixed TUI JSON toggling by moving the shortcut to `J`, preserving `j/k` for navigation only
-- fixed TUI child-command execution so relative paths resolve from the active project context selected in the header
+- added scene-first `Design Ops` actions for managed `Save Current Design`, icon sync progress, and Visual Assist platform+quality presets
+- tightened `Current Status` route mapping so `/dv:tasks`, `/dv:build`, and bootstrap routes are no longer forced into unrelated scene actions
+- removed stale hidden Advanced-command UI branches and aligned reachable keyboard/help behavior with scene-only navigation
+- simplified install/uninstall operations to one-click all-platform actions (`Codex`, `Claude Code`, `Gemini`) from the TUI
+- expanded regression coverage for TUI scene order, route mapping, and environment-stable `save-current-design` CLI behavior
 
 ## Supported workflow modes
 
@@ -99,8 +96,18 @@ If the growing CLI surface is the main usability problem, use the built-in termi
 
 - launch with `da-vinci tui` or `da-vinci-tui`
 - use `npx -p @xenonbyte/da-vinci-workflow da-vinci tui` when the package is not installed globally
-- the TUI groups commands by workflow phase, supports English and Chinese descriptions, and lets you launch the selected command after previewing it
-- `p` sets project path context, `c` sets change-id context, `l` toggles language, `m` edits the preview command, and `Enter` runs it
+- the root menu is scene-first: `Install & Uninstall`, `Current Status`, `Switch Work Item`, `Design Ops`, `Pre-Implementation Checks`, `Pre-Acceptance Checks`, `Settings`
+- `Pre-Implementation Checks` is a direct readiness gate for implementation
+- persistent header is intentionally minimal: brand + current project + current change
+- `Design Ops > Save Current Design` persists the current live editor state back to the project-owned `.pen` source
+- `Design Ops > Visual Assist Preset` maps `Masterpiece`/`High Quality`/`Normal` to platform preset variants `Required Supervisor Signoff`/`Advisory Supervisor Review`/`Adapter-Only`
+- `Install & Uninstall` provides three actions: `Status` (show `da-vinci status`), `Install` (install all supported platforms), and `Uninstall` (uninstall all supported platforms)
+- Visual Assist preset output is always English and updates only the `## Visual Assist` block in project-root `DA-VINCI.md` after platform+quality selection (it does not rewrite unrelated sections)
+- `Current Status` now keeps route guidance honest: when `next-step` points to `/dv:tasks`, `/dv:build`, or bootstrap, TUI keeps it as a direct command recommendation instead of forcing a mismatched scene
+- `Settings` now keeps only `Language` and `Logs`
+- `Settings > Logs` shows project-local daily diagnostics from `.da-vinci/logs/YYYY-MM-DD.ndjson`; logs are troubleshooting evidence, not workflow truth
+- it supports English/Chinese chrome, light/dark theme auto-detection, and `t` as a manual fallback
+- `p` sets project context, `c` sets change context, `l` toggles language, `J` toggles `--json`, and `Enter` opens/runs the selected item
 
 Use [docs/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for the operator-facing workflow, resume rules, and TUI guidance.
 
@@ -495,7 +502,8 @@ During active redesign work, run `da-vinci audit --mode integrity <project-path>
 Project-local `.pen` persistence now has two supported paths:
 
 - first-run path: seed the registered project-local `.pen` with `da-vinci ensure-pen --output <path> --verify-open`, open that exact path, then persist later MCP snapshot writes back to the same file
-- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh live MCP snapshot back to that same path and run `da-vinci check-pen-sync`
+- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, then use `da-vinci save-current-design --project <project-path>` after material live edits
+- treat `save-current-design` outcomes explicitly: `saved` means persisted, `blocked` means bound-source contract failure, and `unavailable` means the runtime bridge could not capture a live snapshot
 - multi-source guard: when external `.pen` sources also exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before each new `pencil-session begin`; if hashes diverge, confirm source priority explicitly and sync the chosen source into `<project-pen>` before new edits
 
 On autonomous redesign runs, the session wrapper is required when it is available. Lower-level helpers remain available only when the wrapper truly cannot be used.
@@ -504,8 +512,10 @@ Persistence helpers:
 
 - required wrapper on autonomous runs:
   - `da-vinci pencil-session begin --project <project-path> --pen <path> [--baseline <path>] [--prefer-source <path>] [--sync-preferred-source]`
-  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci save-current-design --project <project-path> [--json] [--continue-on-error]`
   - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- low-level fallback when high-level save reports `unavailable`:
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
 - `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>[,<other-pen>...] [--prefer-source <path>]`
 - `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
 - `da-vinci ensure-pen --output <path> --verify-open`

package/README.zh-CN.md

@@ -30,18 +30,15 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.2`
+- `@xenonbyte/da-vinci-workflow@0.2.3`
 
-`0.2.2` 版本重点：
+`0.2.3` 版本重点：
 
-- 新增内置终端 TUI：可通过 `da-vinci tui` 和 `da-vinci-tui` 启动，按阶段分组浏览命令，支持中英文说明、命令预览以及 project/change 上下文维护
-- 新增 TUI 内的命令参数帮助，可以直接在终端里查看支持的 flag、占位符和必填参数
-- 新增中英文 operator 文档，专门说明第一次如何进入、实现前如何衔接、中途退出后怎么恢复，以及 TUI 怎么配合
-- 回归测试与打包校验现已覆盖 TUI 专项路径，包括独立 bin、`tui/` 目录资产和帮助输出
-- 修复 TUI 退出路径：`q` 和 `Ctrl-C` 现在会真正结束会话，不再把进程留在前台挂住
-- 修复预览命令编辑：未闭合引号现在会显示可恢复错误页，不再直接把 TUI 进程打崩
-- 修复 TUI 的 JSON 切换快捷键冲突：现在使用 `J` 切换 `--json`，`j/k` 只负责移动
-- 修复 TUI 子命令执行目录：相对路径现在会基于当前 header 里选中的项目上下文解析
+- 新增场景化 `设计操作`：支持托管 `保存当前设计稿`、图标库同步进度反馈，以及 Visual Assist 平台+质量预设写入
+- 收紧 `当前状态` 场景映射：`/dv:tasks`、`/dv:build`、bootstrap 不再被错误导向到无关场景
+- 清理已下线的 Advanced 命令路径残留，TUI 键位与帮助文本统一为可达的场景交互
+- `安装与卸载` 统一为一键全平台动作（`Codex`、`Claude Code`、`Gemini`）
+- 补强回归测试：覆盖 TUI 场景顺序、路由映射，以及 `save-current-design` 的环境隔离稳定性
 
 ## 支持的工作流模式
 
@@ -104,8 +101,19 @@ Da Vinci 当前支持五种模式：
 
 - 用 `da-vinci tui` 或 `da-vinci-tui` 启动
 - 没有全局安装时，用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
-- TUI 会按工作流阶段对命令分组，支持中英文说明，并在执行前先给出命令预览
-- `p` 设置项目路径上下文，`c` 设置 change-id 上下文，`l` 切换语言，`m` 编辑预览命令，`Enter` 执行
+- 首屏按场景组织：`安装与卸载`、`当前状态`、`切换工作项`、`设计操作`、`实施前检查`、`验收前检查`、`设置`
+- 顶部信息最小化：只保留品牌、当前项目、当前 change
+- `设计操作 > 保存当前设计稿` 会把当前 live 编辑器状态回写到项目管理的 `.pen` 设计源
+- `提示词模版` 从英文权威源 `docs/prompt-presets/` 取内容，支持预览和复制
+- `mode1..mode5` 分别映射 `Simple redesign`、`Complex redesign`、`Redesign with reference directory`、`Design-only`、`Continue`
+- `设计操作 > Visual Assist 预设` 中 `Masterpiece`/`High Quality`/`Normal` 分别映射平台预设里的 `Required Supervisor Signoff`/`Advisory Supervisor Review`/`Adapter-Only`
+- `安装与卸载` 提供三个动作：`状态`（查看 `da-vinci status`）、`安装`（一键安装所有支持平台）、`卸载`（一键卸载所有支持平台）
+- Visual Assist 预设写入始终输出英文；在完成“平台 + 质量”选择后只更新项目根 `DA-VINCI.md` 的 `## Visual Assist` 区块，不会改写其他章节
+- `当前状态` 现在会保持路由建议真实：当 `next-step` 建议 `/dv:tasks`、`/dv:build` 或 bootstrap 时，TUI 会给出直接命令建议，而不是强行映射到不匹配场景
+- `设置` 现在只保留 `语言` 和 `日志`
+- `设置 > 日志` 读取项目内 `.da-vinci/logs/YYYY-MM-DD.ndjson` 的每日诊断日志；日志是排障证据，不是工作流真相源
+- 支持中英文界面与浅色/深色自动识别，`t` 可手动切换主题
+- `p` 设置项目上下文，`c` 设置 change 上下文，`l` 切语言，`J` 切 `--json`，`Enter` 进入/执行
 
 如果你想看“人到底怎么用这个 skill、暂停后怎么续跑、TUI 怎么配合”的完整说明，直接看 [docs/zh-CN/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
 
@@ -416,7 +424,8 @@ Context Delta 与 audit 的关系：
 项目内 `.pen` 持久化现在分成两条受支持路径：
 
 - 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
-- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
+- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`
+- `save-current-design` 结果必须分开处理：`saved` 才代表已持久化；`blocked` 代表绑定源契约失败；`unavailable` 代表 runtime bridge 无法抓取 live 快照
 - 多源门禁：如果还存在外部 `.pen` 源，每次新一轮 `pencil-session begin` 前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 不一致，必须先确认来源优先级并把选中的来源同步回 `<project-pen>`
 
 如果是自治运行，session wrapper 只要可用就必须使用。只有 wrapper 确实不可用时，才退回底层 helper。
@@ -425,8 +434,10 @@ Context Delta 与 audit 的关系：
 
 - 自治运行必须使用的 session 命令：
   - `da-vinci pencil-session begin --project <project-path> --pen <path> [--baseline <path>] [--prefer-source <path>] [--sync-preferred-source]`
-  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci save-current-design --project <project-path> [--json] [--continue-on-error]`
   - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- 当高层保存返回 `unavailable` 时，才回退到底层链路：
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
 - `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>[,<other-pen>...] [--prefer-source <path>]`
 - `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
 - `da-vinci ensure-pen --output <path> --verify-open`

package/commands/claude/dv/breakdown.md

@@ -7,6 +7,14 @@ Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 
+Before handing requirements off to design when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- run `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- treat command output as the gate; do not replace `BLOCK` or non-zero results with narrative judgment
+- if the primary recommended route is still `/dv:breakdown`, keep refining `proposal.md` and specs instead of forcing design
+- do not move to `/dv:design` until the command-backed checks stop blocking
+
 Focus on:
 - scope
 - pages

package/commands/claude/dv/build.md

@@ -7,6 +7,17 @@ Use the Da Vinci workflow for this request.
 
 Action: `build`
 
+Before broad implementation when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- if the primary recommended route is not `/dv:build`, stop and continue from that route instead of forcing implementation
+- run `da-vinci lint-spec --project <path> [--change <id>]`
+- run `da-vinci scope-check --project <path> [--change <id>]`
+- if `tasks.md` exists, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- treat any `BLOCK` or missing required planning/design artifact as a hard stop before broad implementation
+
 Focus on:
 - requirements-backed behavior
 - Pencil-backed layout and presentation

package/commands/claude/dv/design.md

@@ -20,10 +20,13 @@ Create or update:
 Run the `design checkpoint` before locking implementation tasks.
 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.
-Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci save-current-design`, and `da-vinci pencil-session end`.
 Before the first Pencil edit, require `da-vinci pencil-session begin` so the registered project-local `.pen` is seeded and locked before editing starts.
 When multiple `.pen` sources exist (for example an external backup), run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before `pencil-session begin`. If hashes diverge, confirm source priority explicitly and sync the chosen source into the project-local `.pen` (for example `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`) before continuing edits.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `pencil-session persist` after material edits.
+If a registered project-local `.pen` already exists, reopen it for continuity and use `da-vinci save-current-design --project <project-path>` after material edits.
+Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; never treat `unavailable` as a successful save.
+Use the lower-level `pencil-session persist` payload path only when the high-level save bridge is unavailable.
+The MVP guarantee is bound source-path safety (`registered .pen`, session `penPath`, and active editor path converge), not exact window-instance identity before MCP exposes stable window/editor identifiers.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/commands/claude/dv/tasks.md

@@ -16,4 +16,12 @@ Focus on:
 Create or update:
 - `tasks.md`
 
+Before claiming implementation-ready task planning:
+- re-check that the workflow is still in the `/dv:tasks` lane when route context is stale or unclear
+- run the `task checkpoint`
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not hand off to `build` while task coverage or bindings readiness are still blocking
+
 Run the `task checkpoint` before implementation begins.

package/commands/claude/dv/verify.md

@@ -15,4 +15,13 @@ Check:
 Create or update:
 - `verification.md`
 
+When shell access is available:
+- run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
+
 If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.
+Before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.

package/commands/codex/prompts/dv-breakdown.md

@@ -7,6 +7,14 @@ Use the `da-vinci` skill for this request.
 
 Action: `breakdown`
 
+Before handing requirements off to design when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- run `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- treat command output as the gate; do not replace `BLOCK` or non-zero results with narrative judgment
+- if the primary recommended route is still `/dv:breakdown`, keep refining `proposal.md` and specs instead of forcing design
+- do not move to `/dv:design` until the command-backed checks stop blocking
+
 Output should move the work toward:
 - `proposal.md`
 - `specs/<capability>/spec.md`

package/commands/codex/prompts/dv-build.md

@@ -7,6 +7,17 @@ Use the `da-vinci` skill for this request.
 
 Action: `build`
 
+Before broad implementation when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- if the primary recommended route is not `/dv:build`, stop and continue from that route instead of forcing implementation
+- run `da-vinci lint-spec --project <path> [--change <id>]`
+- run `da-vinci scope-check --project <path> [--change <id>]`
+- if `tasks.md` exists, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- treat any `BLOCK` or missing required planning/design artifact as a hard stop before broad implementation
+
 Implementation rules:
 - requirements decide behavior
 - Pencil decides presentation

package/commands/codex/prompts/dv-design.md

@@ -14,10 +14,13 @@ Output should move the work toward:
 Use Pencil-backed structure as the design source when available.
 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.
-Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci save-current-design`, and `da-vinci pencil-session end`.
 Before the first Pencil edit, require `da-vinci pencil-session begin` so the registered project-local `.pen` is seeded and locked before editing starts.
 When multiple `.pen` sources exist (for example an external backup), run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before `pencil-session begin`. If hashes diverge, confirm source priority explicitly and sync the chosen source into the project-local `.pen` (for example `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`) before continuing edits.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `pencil-session persist` after material edits.
+If a registered project-local `.pen` already exists, reopen it for continuity and use `da-vinci save-current-design --project <project-path>` after material edits.
+Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; never treat `unavailable` as a successful save.
+Use the lower-level `pencil-session persist` payload path only when the high-level save bridge is unavailable.
+The MVP guarantee is bound source-path safety (`registered .pen`, session `penPath`, and active editor path converge), not exact window-instance identity before MCP exposes stable window/editor identifiers.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/commands/codex/prompts/dv-tasks.md

@@ -14,3 +14,11 @@ Tasks must cover:
 - spec-backed behavior
 - Pencil-backed UI work
 - verification work
+
+Before claiming implementation-ready task planning:
+- re-check that the workflow is still in the `/dv:tasks` lane when route context is stale or unclear
+- run the `task checkpoint`
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not hand off to `build` while task coverage or bindings readiness are still blocking

package/commands/codex/prompts/dv-verify.md

@@ -13,4 +13,12 @@ Check:
 - drift between artifacts and code
 
 Update `verification.md` when needed.
+When shell access is available:
+- run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
 If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.
+Before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.

package/commands/gemini/dv/breakdown.toml

@@ -6,6 +6,14 @@ Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 
+Before handing requirements off to design when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- run `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- treat command output as the gate; do not replace `BLOCK` or non-zero results with narrative judgment
+- if the primary recommended route is still `/dv:breakdown`, keep refining `proposal.md` and specs instead of forcing design
+- do not move to `/dv:design` until the command-backed checks stop blocking
+
 Focus on:
 - scope
 - pages

package/commands/gemini/dv/build.toml

@@ -6,6 +6,17 @@ Use the Da Vinci workflow for this request.
 
 Action: `build`
 
+Before broad implementation when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- if the primary recommended route is not `/dv:build`, stop and continue from that route instead of forcing implementation
+- run `da-vinci lint-spec --project <path> [--change <id>]`
+- run `da-vinci scope-check --project <path> [--change <id>]`
+- if `tasks.md` exists, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- treat any `BLOCK` or missing required planning/design artifact as a hard stop before broad implementation
+
 Implementation rules:
 - requirements decide behavior
 - Pencil decides presentation

package/commands/gemini/dv/design.toml

@@ -13,10 +13,13 @@ Create or update:
 Use Pencil-backed page coverage as the source of presentation truth.
 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.
-Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci save-current-design`, and `da-vinci pencil-session end`.
 Before the first Pencil edit, require `da-vinci pencil-session begin` so the registered project-local `.pen` is seeded and locked before editing starts.
 When multiple `.pen` sources exist (for example an external backup), run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before `pencil-session begin`. If hashes diverge, confirm source priority explicitly and sync the chosen source into the project-local `.pen` (for example `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`) before continuing edits.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `pencil-session persist` after material edits.
+If a registered project-local `.pen` already exists, reopen it for continuity and use `da-vinci save-current-design --project <project-path>` after material edits.
+Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; never treat `unavailable` as a successful save.
+Use the lower-level `pencil-session persist` payload path only when the high-level save bridge is unavailable.
+The MVP guarantee is bound source-path safety (`registered .pen`, session `penPath`, and active editor path converge), not exact window-instance identity before MCP exposes stable window/editor identifiers.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/commands/gemini/dv/tasks.toml

@@ -10,4 +10,12 @@ Create or update:
 - `tasks.md`
 
 Tasks must cover spec behavior, Pencil-backed UI work, and verification.
+
+Before claiming implementation-ready task planning:
+- re-check that the workflow is still in the `/dv:tasks` lane when route context is stale or unclear
+- run the `task checkpoint`
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not hand off to `build` while task coverage or bindings readiness are still blocking
 """

package/commands/gemini/dv/verify.toml

@@ -12,5 +12,13 @@ Check:
 - drift between artifacts and code
 
 Update `verification.md` when needed.
+When shell access is available:
+- run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
 If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.
+Before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 """

package/docs/dv-command-reference.md

@@ -99,6 +99,11 @@ These commands do not replace route selection, but they support design execution
 - `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
   - copies the selected latest `.pen` source into the project-local `.pen` path and refreshes Da Vinci state metadata
   - use when external backup is the latest baseline and must be materialized before `pencil-session begin`
+- `da-vinci save-current-design --project <path> [--json] [--continue-on-error]`
+  - runs the high-level bound-source save flow for guided design persistence
+  - requires convergence of registered `.pen`, session `penPath`, and active editor path before persistence
+  - returns one explicit outcome envelope: `saved`, `blocked`, or `unavailable`
+  - `blocked` means save-time source/lock/payload contracts failed; `unavailable` means MCP bridge/runtime capture was not reachable
 
 Use these utilities during `/dv:design`, especially before anchor-surface icon finalization.
 
@@ -172,6 +177,14 @@ For `overhaul-from-code`, this stage may also create:
 
 This is the behavior-truth shaping stage.
 
+Breakdown-stage self-check:
+
+- before handing requirements off to design, run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- run `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- treat command output as the gate; do not replace `BLOCK` or non-zero results with narrative judgment
+- if the primary recommended route is still `/dv:breakdown`, keep refining `proposal.md` and specs instead of forcing `/dv:design`
+
 ### `/dv:design`
 
 Use when:
@@ -210,6 +223,14 @@ This is the implementation-planning stage.
 
 It does not write code.
 
+Task-stage self-check:
+
+- run the `task checkpoint` before handing work off to implementation
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not promote `/dv:build` while task coverage or bindings readiness are still blocking
+
 ### `/dv:build`
 
 Use when:
@@ -225,6 +246,18 @@ Creates or updates:
 
 This is the execution stage.
 
+Build-stage self-check:
+
+- before broad implementation, run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- if the primary recommended route is not `/dv:build`, stop and continue from that route instead of forcing implementation
+- run `da-vinci lint-spec --project <path> [--change <id>]`
+- run `da-vinci scope-check --project <path> [--change <id>]`
+- if `tasks.md` exists, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- treat any `BLOCK` or missing required planning/design artifact as a hard stop before broad implementation
+
 Completion discipline:
 
 - treat `BUILD SUCCESSFUL` as compile-only evidence
@@ -245,6 +278,16 @@ Creates or updates:
 
 This is the truth-reconciliation stage.
 
+Verify-stage self-check:
+
+- when shell access is available, run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
+- before terminal completion, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
+
 ## State-Based Next-Step Rules
 
 These are the intended route recommendations.

package/docs/execution-chain-plan.md

@@ -1,5 +1,9 @@
 # Execution-Chain Upgrade Plan Notes
 
+Historical planning note only.
+
+Use `openspec/changes/execution-chain-upgrade-plan/tasks.md` as the canonical executable task breakdown for this upgrade. This file records the background planning decisions that shaped that OpenSpec change; it is not the source of truth for implementation sequencing or release signoff.
+
 This document records planning decisions required by the execution-chain upgrade.
 
 ## Phase 0 Pre-work Decisions
@@ -24,6 +28,7 @@ The workflow contract must own:
 - route dependencies
 - stage handoff gates
 - status vocabulary (`PASS/WARN/BLOCK`)
+- audit-owned machine-parsed hard-gate fields from `DA-VINCI.md`, `.da-vinci/design-registry.md`, and `pencil-design.md`
 
 ### Compatibility boundaries
 
@@ -83,18 +88,18 @@ Re-baseline rule:
 ### Measurable DoD checks
 
 - Phase 0: inventory, parser ownership, schema boundaries, and test layers documented
-- Phase 1: workflow-status/next-step + prompt-first continue integration + contract tests green
+- Phase 1: workflow-status/next-step + prompt-first continue integration + design-source/runtime/mapping-aware routing + contract tests green
 - Phase 2: lint/scope + deterministic sidecars + advisory/strict semantics tested
 - Phase 3: verify surfaces + task-group metadata + audit wiring tested
 - Phase 4a: persisted state + diff + compatibility hardening tested
 - Phase 4b: constrained scaffold MVP tested
-- Phase 4c: command-asset convergence + docs + release controls tested
+- Phase 4c: command-asset convergence + docs + audit-aligned release controls tested
 
 ### First-release MVP scope
 
 In scope:
 
-- workflow-status/next-step
+- workflow-status/next-step with design-source/runtime/mapping-aware route guards
 - lint-spec/lint-tasks/lint-bindings/scope-check
 - generate-sidecars + diff-spec
 - verify-bindings/verify-implementation/verify-structure/verify-coverage
@@ -121,5 +126,7 @@ Out of scope:
 ### Release criteria and fallback
 
 - release requires core + contracts + e2e lanes green
+- completion or release-ready claims for shipped change scope must also pass `da-vinci audit --mode completion --change <change-id> <project-path>`
+- CI green is necessary but not sufficient when workflow truth or completion semantics disagree with audit
 - stale persisted state always falls back to derived state
 - verify-structure unsupported cases must emit heuristic fallback with confidence

package/docs/mode-use-cases.md

@@ -146,7 +146,8 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 8. create `pencil-design.md`
    - record the generated Pencil screens
    - require `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
-   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current live MCP snapshot through `da-vinci pencil-session persist` after material live edits
+   - if a registered project-local `.pen` already exists, reopen it for continuity, then run `da-vinci save-current-design --project <project-path>` after material live edits
+   - treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to low-level `pencil-session persist --nodes-file/--variables-file` when the high-level bridge is unavailable
    - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`

package/docs/pencil-rendering-workflow.md

@@ -29,7 +29,7 @@ PNG exports are review artifacts only. They are not the design source of truth.
 Da Vinci now requires the session wrapper on autonomous runs:
 
 - `da-vinci pencil-session begin`
-- `da-vinci pencil-session persist`
+- `da-vinci save-current-design`
 - `da-vinci pencil-session end`
 
 This wrapper exists to make three things mandatory:
@@ -75,18 +75,21 @@ When resuming from existing artifacts:
 
 Da Vinci does not treat headless interactive `save()` as authoritative persistence truth.
 
-Instead, the persistence step is:
+Instead, the primary persistence step is:
 
-1. read MCP-readable node snapshot data
-2. read MCP-readable variable snapshot data
-3. write the project-local `.pen`
-4. reopen-verify it
-5. compare live snapshot and persisted snapshot hashes
+1. run `da-vinci save-current-design --project <project-path>`
+2. require one explicit result envelope: `saved`, `blocked`, or `unavailable`
+3. treat only `saved` as persisted success
+4. treat `blocked` as save-time source/lock/payload contract failure
+5. treat `unavailable` as MCP bridge/runtime capture absence (never as a successful save)
 
 Relevant commands:
 
-- `da-vinci write-pen`
-- `da-vinci check-pen-sync`
+- high-level: `da-vinci save-current-design`
+- low-level fallback: `da-vinci pencil-session persist`, `da-vinci write-pen`, `da-vinci check-pen-sync`
+
+The MVP safety guarantee is source-path convergence only: registered `.pen`, session `penPath`, and active editor path must converge.
+Exact window-instance identity remains out of scope until MCP exposes stable window/editor identifiers.
 
 `da-vinci snapshot-pen` is disk-to-disk only. It is not the live-edit persistence path.
 
@@ -251,7 +254,7 @@ Typical autonomous chain:
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
 2. if external/secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before edits; if diverged, sync the preferred source into `<project-pen>` first
 3. Pencil MCP edits
-4. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+4. `da-vinci save-current-design --project <project-path>`
 5. screenshot review + layout hygiene
 6. design checkpoint
 7. design-supervisor review when configured
@@ -278,13 +281,13 @@ flowchart TD
     K -- No --> F
     K -- Yes --> L{Design-supervisor review configured?}
     L -- Yes --> M[Run design-supervisor review on screenshots plus theme inputs]
-    L -- No --> N[pencil-session persist writes live MCP snapshot back to .pen]
+    L -- No --> N[save-current-design persists bound live snapshot back to .pen]
     M --> O{Require Supervisor Review?}
     O -- No --> N
     O -- Yes --> P{Review PASS or accepted WARN?}
     P -- No --> F
     P -- Yes --> N
-    N --> Q[check-pen-sync verifies live hash equals persisted hash]
+    N --> Q[save-current-design returns saved or a terminal blocker/unavailable result]
     Q --> R{design-source checkpoint and runtime gate pass?}
     R -- No --> F
     R -- Yes --> S{More design work needed?}