@xenonbyte/da-vinci-workflow 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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
+- built-in terminal TUI surfaces via `da-vinci tui` and `da-vinci-tui`, with phase-grouped command discovery, bilingual labels, previewable execution, and project/change context controls
+- in-TUI command parameter help so operators can inspect supported flags, placeholders, and required inputs before editing a preview command
+- operator-facing English and Chinese workflow guides covering first-run routing, implementation handoff, pause/resume recovery, and TUI usage
+- TUI regression coverage plus package-content checks for the dedicated TUI bin and shipped `tui/` assets
+
+### Changed
+- README and Chinese companion docs now document the `0.2.2` TUI/operator release surface explicitly
+- TUI child commands now execute from the active project context selected in the header instead of always inheriting the original launch cwd
+
+### Fixed
+- `q` and `Ctrl-C` now fully terminate the TUI session instead of clearing the screen while leaving stdin resumed in the foreground
+- preview-command editing now treats unclosed quotes as a recoverable TUI error instead of crashing the process
+- the TUI JSON shortcut now uses `J`, preserving lowercase `j/k` for navigation without unreachable toggle branches
+
 ## v0.2.1 - 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.1`
+- `@xenonbyte/da-vinci-workflow@0.2.3`
 
-Release highlights for `0.2.1`:
+Release highlights for `0.2.3`:
 
-- added the execution-chain workflow surfaces: `workflow-status`, `next-step`, `lint-spec`, `scope-check`, `lint-tasks`, `lint-bindings`, `generate-sidecars`, `verify-*`, `diff-spec`, and `scaffold`
-- introduced persisted workflow state plus execution-signal recording so route selection can reuse trusted snapshots while still honoring fresh verify and audit blockers
-- added planning sidecars, diffing, and scaffold generation from bindings to make planning drift and implementation coverage visible from the CLI
-- split CI into core regression, contracts, and workflow e2e lanes so the new workflow-state surfaces are exercised independently
-- expanded regression coverage for workflow-state derivation, persisted-state reuse, planning lints, sidecar generation, verify/scaffold, and audit execution-signal integration
-- fixed `generate-sidecars` so unresolved workflow/change selection returns `BLOCK` instead of a misleading `PASS`
-- fixed `verify-implementation` so test, fixture, and script files do not satisfy implementation coverage heuristics
-- refreshed release and command docs to document the new execution-chain surfaces in both English and Chinese
+- 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
 
@@ -93,6 +90,27 @@ Route discipline:
 - contextual checkpoint deltas are auxiliary recovery notes only and must not override routing
 - if contextual deltas conflict with current artifacts, ignore them for routing and record the conflict
 
+## TUI Quick Start
+
+If the growing CLI surface is the main usability problem, use the built-in terminal UI instead of memorizing commands.
+
+- 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 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.
+
 ## Visual Assist Quick Start
 
 Use `Visual Assist` when the project wants optional help from local UI-design skills such as `frontend-skill` or `ui-ux-pro-max`.
@@ -484,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.
@@ -493,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.1`
+- `@xenonbyte/da-vinci-workflow@0.2.3`
 
-`0.2.1` 版本重点：
+`0.2.3` 版本重点：
 
-- 新增 execution-chain CLI surface：`workflow-status`、`next-step`、`lint-spec`、`scope-check`、`lint-tasks`、`lint-bindings`、`generate-sidecars`、`verify-*`、`diff-spec`、`scaffold`
-- 新增持久化 workflow state 与 execution signal 记录，路由判断可以复用可信快照，同时继续尊重最新 verify / audit 阻塞结果
-- 新增 planning sidecar、diff 和基于 bindings 的 scaffold，方便直接从 CLI 看 planning drift 和实现覆盖
-- CI 现已拆成 core regression、contracts、workflow e2e 三条 lane，execution-chain 新流程会被独立回归
-- 回归测试新增覆盖 workflow-state 推导、persisted-state 复用、planning lint、sidecar 生成、verify/scaffold 与 audit execution-signal 集成
-- 修复 `generate-sidecars`：当 workflow / change 无法解析时，返回 `BLOCK`，不再误报 `PASS`
-- 修复 `verify-implementation`：测试文件、fixture 和脚本文件不再被当成真实实现覆盖证据
-- 中英文 README 与命令文档现已同步补充 execution-chain 新表面说明
+- 新增场景化 `设计操作`：支持托管 `保存当前设计稿`、图标库同步进度反馈，以及 Visual Assist 平台+质量预设写入
+- 收紧 `当前状态` 场景映射：`/dv:tasks`、`/dv:build`、bootstrap 不再被错误导向到无关场景
+- 清理已下线的 Advanced 命令路径残留，TUI 键位与帮助文本统一为可达的场景交互
+- `安装与卸载` 统一为一键全平台动作（`Codex`、`Claude Code`、`Gemini`）
+- 补强回归测试：覆盖 TUI 场景顺序、路由映射，以及 `save-current-design` 的环境隔离稳定性
 
 ## 支持的工作流模式
 
@@ -98,6 +95,28 @@ Da Vinci 当前支持五种模式：
 - Context Delta 只用于恢复上下文，不是阶段判定真相源
 - 如果 Context Delta 与当前工件冲突，应该忽略冲突条目并按工件真相继续
 
+## TUI 快速上手
+
+如果真正的痛点是 CLI 面太多、不想记命令，就直接用内置终端 TUI。
+
+- 用 `da-vinci tui` 或 `da-vinci-tui` 启动
+- 没有全局安装时，用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
+- 首屏按场景组织：`安装与卸载`、`当前状态`、`切换工作项`、`设计操作`、`实施前检查`、`验收前检查`、`设置`
+- 顶部信息最小化：只保留品牌、当前项目、当前 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)。
+
 ## Visual Assist 快速上手
 
 当项目想借助本地 UI 设计 skill，例如 `frontend-skill` 或 `ui-ux-pro-max`，来提升设计质量时，就配置 `Visual Assist`。
@@ -405,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。
@@ -414,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/bin/da-vinci-tui.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/cli");
+
+runCli(["tui", ...process.argv.slice(2)]).catch((error) => {
+  console.error(error.message || String(error));
+  process.exit(1);
+});

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

@@ -37,6 +37,10 @@ These helpers exist to select or resume the correct route. They are not substitu
 
 These commands do not replace route selection, but they support design execution quality:
 
+- `da-vinci tui [--project <path>] [--change <id>] [--lang en|zh]`
+  - opens a workflow-oriented terminal UI that groups commands by phase and lets you run them after previewing the generated CLI
+  - use `da-vinci-tui` as the dedicated bin alias, or `npx -p @xenonbyte/da-vinci-workflow da-vinci tui` without a global install
+  - useful when the command surface is harder to remember than the workflow itself
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - derives the current workflow stage from artifact and checkpoint truth
   - reports blockers, warnings, handoff-gate state, and one primary route recommendation
@@ -95,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.
 
@@ -168,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:
@@ -206,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:
@@ -221,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
@@ -241,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`