@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/docs/skill-usage.md

@@ -0,0 +1,217 @@
+# Skill Usage Guide
+
+Use this document when you want the operator-facing workflow rather than the lower-level command reference.
+
+This guide focuses on:
+
+- how to enter the Da Vinci workflow the first time
+- how to move between requirement, design, task, and implementation phases
+- how to resume safely after pausing midway
+- how to use the TUI instead of memorizing many CLI surfaces
+
+## Core Rule
+
+Da Vinci should be resumed from artifact truth, not from chat memory.
+
+That means:
+
+- `spec.md` and related requirement artifacts stay the behavior truth
+- the project-local `.pen` stays the design truth
+- `tasks.md`, `verification.md`, and execution signals explain what has or has not been implemented yet
+
+## First Entry
+
+Use these entry helpers:
+
+- `intake`
+  - choose this when the project is complex, the mode is unclear, or there are multiple truth sources
+- `prompt`
+  - choose this when the mode is already known and you only need a good executable starting prompt
+- `continue`
+  - choose this when `DA-VINCI.md` or `.da-vinci/` artifacts already exist and you are resuming work
+
+For Codex, the usual first requests are:
+
+```text
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
+```
+
+Default recommendation:
+
+1. use `intake` on the first pass through a non-trivial project
+2. execute the generated main workflow prompt
+3. when work pauses, come back through `continue`
+
+Do not default directly to `build` unless the project is already implementation-ready.
+
+## Real Workflow
+
+The normal delivery flow is:
+
+1. choose the mode
+2. create or stabilize discovery and scope artifacts
+3. register the preferred project-local `.pen` source
+4. design 1 to 3 anchor surfaces first
+5. reconcile the live Pencil session with the registered `.pen`
+6. write `pencil-bindings.md`
+7. generate or refine `tasks.md`
+8. implement
+9. verify
+
+The artifact spine usually looks like this:
+
+- `DA-VINCI.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/specs/*/spec.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
+
+## Before Implementation
+
+When design is mostly ready and implementation is next, use these checks:
+
+- `da-vinci workflow-status`
+  - confirm the active stage and blockers first
+- `da-vinci next-step`
+  - confirm whether the next move should still be `design`, `tasks`, or `build`
+- `da-vinci lint-spec`
+  - use this when runtime spec quality is still uncertain
+- `da-vinci scope-check`
+  - use this when page/state propagation across planning artifacts looks ambiguous
+
+If you are already inside the project root directory, `--project` is optional because the CLI falls back to `cwd`.
+
+Examples:
+
+```bash
+da-vinci workflow-status
+da-vinci next-step
+da-vinci lint-spec
+da-vinci scope-check
+```
+
+## After Pausing Midway
+
+The safest resume order is:
+
+1. `da-vinci workflow-status [--change <id>] --json`
+2. `da-vinci next-step [--change <id>]`
+3. if spec quality is unclear, run `da-vinci lint-spec`
+4. if planning propagation is unclear, run `da-vinci scope-check`
+5. if planning artifacts changed since the last stable snapshot, run `da-vinci generate-sidecars` and `da-vinci diff-spec`
+6. before terminal completion, run `da-vinci verify-bindings` and `da-vinci verify-coverage`
+
+Resume should follow the artifacts, not old conversation state:
+
+- if design artifacts exist but `tasks.md` does not, resume into `tasks`
+- if `tasks.md` exists but design gates are still unresolved, resume into design cleanup rather than `build`
+- only resume into `build` when implementation readiness is already clear
+
+## How `change-id` Works
+
+`change-id` is the directory name under `.da-vinci/changes/<change-id>/`.
+
+Practical rules:
+
+- if the project only has one non-empty change directory, most workflow commands can infer it automatically
+- if the project has multiple non-empty change directories, pass `--change <id>` explicitly
+- keep one active change per branch when possible to reduce routing friction
+
+Use `da-vinci workflow-status` when you forget which change is active. In multi-change cases it reports the available ids and the latest inferred one for context.
+
+## TUI Quick Start
+
+If remembering many command surfaces is the main friction, use the terminal UI instead of typing commands from memory.
+
+Launch it with either:
+
+```bash
+da-vinci tui
+da-vinci-tui
+```
+
+Or through `npx` without installing globally:
+
+```bash
+npx -p @xenonbyte/da-vinci-workflow da-vinci tui
+npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
+```
+
+The TUI provides:
+
+- command grouping by workflow phase
+- English and Chinese UI descriptions
+- current project path and change-id context at the top
+- preview commands before execution
+- one-key toggles for `--strict`, `--json`, and `--continue-on-error`
+- placeholder-aware editing for commands that still need specific paths like `<pen-path>`
+
+### TUI Phase Map
+
+```mermaid
+flowchart TD
+  A[Launch da-vinci tui] --> B[Set project path and change-id context]
+  B --> C[Routing & Resume<br/>workflow-status / next-step]
+  C --> D{Which phase is active?}
+
+  D --> E[Planning & Drift<br/>lint-spec / scope-check / lint-tasks / lint-bindings / generate-sidecars / diff-spec / scaffold]
+  D --> F[Visual & Review<br/>icon-sync / icon-search / supervisor-review]
+  D --> G[Pen Files & Sync<br/>preflight-pencil / ensure-pen / write-pen / check-pen-sync / check-pen-baseline / sync-pen-source / snapshot-pen]
+  D --> H[Pencil Session<br/>pencil-lock * / pencil-session begin|persist|end|status]
+  D --> I[Verification & Completion<br/>verify-bindings / verify-implementation / verify-structure / verify-coverage / audit]
+  D --> J[Setup & Tooling<br/>install / uninstall / status / validate-assets / bootstrap-project]
+
+  E --> I
+  F --> G
+  G --> H
+  H --> E
+  I --> K{Ready to finish?}
+  K -->|No| C
+  K -->|Yes| L[Completion audit and terminal claim]
+```
+
+Use this as the quick mental model:
+
+- start from `Routing & Resume`
+- move into the phase that matches the current blockers
+- return to `Routing & Resume` whenever the workflow pauses or artifacts changed materially
+- only finish after the verification lane and completion audit are both clear
+
+Main keys:
+
+- `Up/Down` or `j/k`: move selection
+- `Enter` or `r`: run the selected command
+- `h`: inspect parameters for the selected command
+- `m`: edit the preview command first
+- `p`: change project path context
+- `c`: change or clear change-id context
+- `l`: toggle English / Chinese
+- `s`: toggle `--strict`
+- `J`: toggle `--json`
+- `e`: toggle `--continue-on-error`
+- `?`: open help
+- `q`: quit
+
+Recommended TUI usage:
+
+1. launch the TUI from the project root
+2. set or confirm project path and change-id in the header
+3. start with `workflow-status`
+4. run `next-step`
+5. move into `lint-spec` / `scope-check` / `tasks` / `verify-*` as needed
+6. for specialized Pencil commands, press `m` and fill the remaining placeholders before execution
+
+## Practical Shortcuts
+
+- inside the project root, you usually do not need `--project`
+- with one active change, you often do not need `--change`
+- use `workflow-status` and `next-step` as the standard re-entry pair after any pause
+- use the TUI when command recall is the main problem
+- use direct CLI commands when you already know the exact surface and want faster scripting

package/docs/workflow-examples.md

@@ -17,6 +17,16 @@ Common rule:
 - `continue` should pick routes from artifact/checkpoint truth first, then use contextual deltas as auxiliary recovery notes
 - if contextual deltas conflict with current artifacts, ignore them for routing and record the conflict
 
+Execution-chain command bundle (before terminal completion):
+
+- `da-vinci workflow-status --project <path> [--change <id>] --json`
+- `da-vinci next-step --project <path> [--change <id>]`
+- `da-vinci lint-spec|lint-tasks|lint-bindings --project <path> [--change <id>]`
+- `da-vinci scope-check --project <path> [--change <id>]`
+- `da-vinci generate-sidecars --project <path> [--change <id>]`
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>]`
+- `da-vinci diff-spec --project <path> [--change <id>]`
+
 ## 1. `greenfield-spec`
 
 Use when a new project already has a stable requirement set.

package/docs/workflow-overview.md

@@ -13,6 +13,8 @@ Use it when you need the high-level delivery chain:
 Use [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/pencil-rendering-workflow.md) when you need the lower-level Pencil session, persistence, gate, and audit details.
 Use [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/dv-command-reference.md) when you need route-by-route `dv:` command behavior, next-step recommendations, and verify rollback handling.
 Use [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/constraint-files.md) when you need a single map for project constraint files, hard-gate fields, and advisory guidance sections.
+Use [execution-chain-migration.md](/Users/xubo/x-skills/da-vinci/docs/execution-chain-migration.md) for sidecar, enforcement, persisted-state fallback, and scaffold migration guidance.
+Use [skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for an operator-facing guide to starting, pausing, resuming, and using the TUI.
 
 ## Core Contract
 
@@ -40,6 +42,30 @@ This means:
 8. Implement.
 9. Verify requirement drift and design drift.
 
+## Workflow-State Surfaces
+
+Use these command surfaces to inspect route readiness before selecting the next `dv:` stage:
+
+- `da-vinci workflow-status --project <path> [--change <id>] [--json]`
+  - summarizes current stage, blockers, handoff gates, and route recommendation from artifact truth plus selected audit-visible evidence
+- `da-vinci next-step --project <path> [--change <id>] [--json]`
+  - emits the first continuation action from the same derived workflow-state model
+- `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
+  - validates runtime `spec.md` schema quality before implementation planning or execution
+  - default behavior is advisory; `--strict` is explicit opt-in for blocking behavior
+- `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
+  - validates page and state propagation across proposal, page-map, runtime specs, pencil-design, and tasks
+  - emits a machine-readable page/state coverage matrix for later verify and status consumers
+- `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
+  - explicitly generates deterministic planning sidecars used by diff and downstream tooling
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
+  - validates execution-chain evidence from bindings through implementation and structural coverage
+- `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
+  - reports normalized planning deltas for spec/tasks/page-map/bindings sidecars to support safe continuation
+
+These surfaces do not replace `da-vinci audit --mode integrity|completion`.
+`audit` remains the formal integrity and completion truth surface.
+
 ## Standard Artifact Spine
 
 Depending on mode, Da Vinci typically builds this spine:

package/docs/zh-CN/dv-command-reference.md

@@ -39,6 +39,40 @@ Da Vinci 期望它们遵循工作流状态。
 
 这些命令不会替代 `dv:` 选路，但能显著提升设计执行质量：
 
+- `da-vinci tui [--project <path>] [--change <id>] [--lang en|zh]`
+  - 打开面向工作流的终端 UI，按阶段组织命令，并在执行前先展示生成出的 CLI 预览
+  - 也可以用独立 bin `da-vinci-tui`，或在没全局安装时用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
+  - 当真正难记的是命令面而不是流程本身时，优先用它
+- `da-vinci workflow-status --project <path> [--change <id>] [--json]`
+  - 从工件和 checkpoint 真相推导当前 workflow 阶段
+  - 报告 blocker、warning、handoff gate 状态，以及主推荐路由
+  - 它和 `audit` 职责不同：它负责选路，不是终态审计真相
+- `da-vinci next-step --project <path> [--change <id>] [--json]`
+  - 基于同一套 workflow-state 推导，给出 route-first 的续跑建议
+  - 在自由扫描工件之前，优先把它作为第一路由信号
+- `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
+  - 校验 Da Vinci 运行时 `spec.md` 的核心章节（`Behavior`、`States`、`Inputs`、`Outputs`、`Acceptance`、`Edge Cases`）
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+  - 不会把 OpenSpec 规划用的 `ADDED Requirements` 结构当成运行时 spec 合法结构
+- `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
+  - 检查 proposal、page-map、运行时 spec、pencil-design 状态和 tasks 之间的 scope 传播一致性
+  - 输出页面与状态两条线的机器可读覆盖矩阵
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+- `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
+  - 校验顶层 task groups、编号顺序、verification 动作和 behavior 覆盖提示
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+- `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
+  - 校验实现到 Pencil 的映射是否可解析、source 形态是否合理、实现落点是否可定位
+  - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
+- `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
+  - 显式生成确定性的 planning sidecars：`spec.index.json`、`tasks.index.json`、`page-map.index.json`、`bindings.index.json`
+  - sidecar 只允许通过这个命令写入；lint/status/verify 不应静默重写
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
+  - 校验代码落点、计划状态实现证据、以及绑定驱动的结构一致性
+  - `verify-structure` 会明确报告是 markup-backed 还是 heuristic fallback，并给出置信度
+- `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
+  - 比较规范化 planning sidecars，报告新增/删除/修改的规划项
+  - 在同一 surface 下提供 spec 差异以及 tasks/page-map/bindings 摘要差异
 - `da-vinci icon-sync`
   - 同步官方图标名（Material Symbols、Lucide、Feather、Phosphor）到 `~/.da-vinci/icon-catalog.json`
   - 默认是用户级范围（当前 HOME），同一用户可跨项目复用
@@ -116,6 +150,7 @@ Da Vinci 期望它们遵循工作流状态。
 
 重要规则：
 
+- 有 shell 能力时，先跑 `da-vinci workflow-status --project <path> [--change <id>] --json`，再用 `da-vinci next-step --project <path> [--change <id>]` 作为第一选路信号
 - 如果设计已经有了，但 `tasks.md` 还没有，`continue` 通常应该把你送到 `tasks`
 - 这时候不应该把 `build` 当成同级主推荐
 - 选路必须先基于工件和 checkpoint 真相，再参考 Context Delta

package/docs/zh-CN/execution-chain-migration.md

@@ -0,0 +1,46 @@
+# Execution-Chain 升级迁移指南
+
+当你要在已有项目上启用 execution-chain 升级能力时，使用这份指南。
+
+## 1. Sidecar 生成生命周期
+
+Planning sidecar 是显式工件，不是隐式副产物。
+
+- 用 `da-vinci generate-sidecars --project <path> [--change <id>]` 生成
+- sidecar 写入 `.da-vinci/changes/<change-id>/sidecars/`
+- lint/status/verify 不应静默改写 sidecar
+- proposal/spec/page-map/tasks/bindings 有实质改动后应重新生成
+
+## 2. Advisory 与 Strict 推广策略
+
+默认策略：
+
+- `lint-spec`、`scope-check`、`lint-tasks`、`lint-bindings` 默认 advisory（`WARN` 不硬阻断）
+- 传 `--strict` 才把 warning 升级为阻断退出
+- 只有在 warning 基线稳定后，才在 CI 打开 strict
+
+Audit 集成：
+
+- integrity audit 把 planning-signal 的 `BLOCK` 当 warning 级信号
+- completion audit 把 verification-signal 的 `BLOCK` 当 failure 级信号
+
+## 3. 持久化工作流状态回退
+
+`workflow-status` 只有在以下条件全部满足时才会使用 `.da-vinci/state/workflow.json`：
+
+- schema 版本可识别
+- change 条目存在
+- 时间戳未过期
+- 指纹与当前工件真相一致
+
+任一条件不满足时，会自动回退到基于工件的派生状态，并记录 reconciliation 说明。
+
+## 4. Scaffold 约束
+
+`da-vinci scaffold` 是 MVP 脚手架能力，约束如下：
+
+- 输出只用于 TODO 标记和人工审阅
+- 不是最终代码生成
+- MVP 不做多框架扩展
+- scaffold 边界来自 `pencil-bindings.md` 映射
+- 接受前需跑 `verify-bindings`、`verify-implementation`、`verify-structure`

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

@@ -65,6 +65,12 @@
 
 继续规则优先级：
 
+- 有 shell 能力时，先运行 `da-vinci workflow-status --project <path> [--change <id>] --json`
+- 再用 `da-vinci next-step --project <path> [--change <id>]` 作为第一续跑路由信号
+- 如果运行时 spec 质量还不确定，进入 `build` 前先运行 `da-vinci lint-spec --project <path> [--change <id>]`
+- 如果页面或状态在规划工件中的传播关系不确定，进入 `build` 前先运行 `da-vinci scope-check --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 与当前工件冲突，选路时忽略冲突内容并标记冲突
@@ -80,6 +86,8 @@
 
 默认不要把这个流程改成 `build`。
 
+如果真正的阻力变成“命令太多记不住”，就启动 `da-vinci tui`，直接在终端 UI 里按阶段选择命令，而不是手动记每个 CLI surface。
+
 `build` 仍然有效，但它更适合已经明确进入实现阶段的高级直接调用。
 
 状态规则：

package/docs/zh-CN/skill-usage.md

@@ -0,0 +1,217 @@
+# Skill 使用说明
+
+这份文档面向真正操作 Da Vinci 的人，而不是底层命令参考。
+
+重点讲四件事：
+
+- 第一次怎么进入 Da Vinci 工作流
+- 需求、设计、任务、实现几段之间怎么衔接
+- 中途退出后下次怎么安全恢复
+- 如果不想记太多命令，怎么用 TUI
+
+## 核心规则
+
+Da Vinci 应该根据工件真相恢复，而不是根据聊天记忆恢复。
+
+也就是说：
+
+- `spec.md` 以及相关需求工件是行为真相
+- 项目内 `.pen` 是设计真相
+- `tasks.md`、`verification.md` 和 execution signals 负责说明哪些东西已经实现、哪些还没实现
+
+## 第一次进入时怎么选入口
+
+这三个入口各有分工：
+
+- `intake`
+  - 适合项目复杂、mode 不明确、或有多个真相源的情况
+- `prompt`
+  - 适合 mode 已明确，只需要一条高质量起始提示词的情况
+- `continue`
+  - 适合仓库里已经有 `DA-VINCI.md` 或 `.da-vinci/`，需要恢复推进的情况
+
+对 Codex，最常见的起手式是：
+
+```text
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
+```
+
+默认建议：
+
+1. 第一次进入复杂项目时先用 `intake`
+2. 执行生成出来的主工作流提示词
+3. 如果中途停下，下次回来用 `continue`
+
+除非项目已经明显 implementation-ready，否则不要默认直接跳到 `build`。
+
+## 实际流程怎么走
+
+正常交付顺序通常是：
+
+1. 选择 mode
+2. 补 discovery 和 scope 工件
+3. 登记首选项目内 `.pen`
+4. 先做 1 到 3 个 anchor surfaces
+5. 让 live Pencil 会话和登记 `.pen` 收敛
+6. 写 `pencil-bindings.md`
+7. 生成或整理 `tasks.md`
+8. 实现
+9. 验证
+
+常见工件骨架一般是：
+
+- `DA-VINCI.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/specs/*/spec.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
+
+## 进入实现前怎么衔接
+
+当设计大体完成，接下来准备实现时，建议按这个顺序看：
+
+- `da-vinci workflow-status`
+  - 先确认当前阶段和 blocker
+- `da-vinci next-step`
+  - 再确认下一步到底应该是 `design`、`tasks` 还是 `build`
+- `da-vinci lint-spec`
+  - 当运行时 spec 质量还不够确定时使用
+- `da-vinci scope-check`
+  - 当规划工件之间页面/状态传播关系还不清楚时使用
+
+如果你已经在项目根目录里，`--project` 通常可以省略，因为 CLI 默认会回退到当前目录。
+
+例如：
+
+```bash
+da-vinci workflow-status
+da-vinci next-step
+da-vinci lint-spec
+da-vinci scope-check
+```
+
+## 中途退出后，下次怎么恢复
+
+最稳妥的恢复顺序是：
+
+1. `da-vinci workflow-status [--change <id>] --json`
+2. `da-vinci next-step [--change <id>]`
+3. 如果 spec 质量不确定，跑 `da-vinci lint-spec`
+4. 如果规划传播关系不确定，跑 `da-vinci scope-check`
+5. 如果 planning 工件相对上次稳定状态有变化，跑 `da-vinci generate-sidecars` 和 `da-vinci diff-spec`
+6. 在终态前，跑 `da-vinci verify-bindings` 和 `da-vinci verify-coverage`
+
+恢复时应该遵循工件，而不是旧聊天上下文：
+
+- 如果设计工件已经有了，但 `tasks.md` 还没有，下一步应该回到 `tasks`
+- 如果 `tasks.md` 已存在，但设计 gate 还没过，不要直接进 `build`
+- 只有实现就绪度已经明确时，才把 `build` 当主恢复路径
+
+## `change-id` 到底是什么
+
+`change-id` 就是 `.da-vinci/changes/<change-id>/` 这个目录名。
+
+实际使用规则：
+
+- 如果项目里只有一个非空 change 目录，多数工作流命令都能自动推断
+- 如果项目里有多个非空 change 目录，就显式传 `--change <id>`
+- 尽量一条分支只维护一个 active change，这样续跑成本最低
+
+如果你忘了当前活跃 change 是哪个，先跑 `da-vinci workflow-status`。在多 change 场景下，它会告诉你可用的 ids，还会给一个“仅供参考”的最新推断值。
+
+## TUI 快速上手
+
+如果真正的痛点是不想记那么多命令面，就直接用终端 TUI。
+
+启动方式：
+
+```bash
+da-vinci tui
+da-vinci-tui
+```
+
+如果没有全局安装，也可以直接用 `npx`：
+
+```bash
+npx -p @xenonbyte/da-vinci-workflow da-vinci tui
+npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
+```
+
+TUI 提供这些能力：
+
+- 按工作流阶段对命令分组
+- 中英文双语界面说明
+- 顶部显示当前项目路径和 change-id 上下文
+- 执行前可先看命令预览
+- 一键切换 `--strict`、`--json`、`--continue-on-error`
+- 对 `<pen-path>` 这类还没补具体路径的命令，支持先编辑预览再执行
+
+### 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 并做终态声明]
+```
+
+你可以把它理解成这四条最实用的规则：
+
+- 先从“选路与续跑”开始
+- 再进入当前 blocker 所在的阶段
+- 只要中途暂停，或者工件发生了实质变化，就回到“选路与续跑”
+- 只有验证链和 completion audit 都通过了，才进入终态
+
+主要按键：
+
+- `Up/Down` 或 `j/k`：移动选中项
+- `Enter` 或 `r`：执行当前命令
+- `h`：查看当前命令参数
+- `m`：先编辑预览命令
+- `p`：修改项目路径上下文
+- `c`：修改或清空 change-id 上下文
+- `l`：切换中英文
+- `s`：切换 `--strict`
+- `J`：切换 `--json`
+- `e`：切换 `--continue-on-error`
+- `?`：打开帮助
+- `q`：退出
+
+推荐的 TUI 使用顺序：
+
+1. 在项目根目录启动 TUI
+2. 先确认顶部的 project path 和 change-id
+3. 先跑 `workflow-status`
+4. 再跑 `next-step`
+5. 根据情况进入 `lint-spec`、`scope-check`、`tasks`、`verify-*`
+6. 如果是 Pencil 相关特殊命令，按 `m` 先把剩余占位符补全后再执行
+
+## 实用简化规则
+
+- 在项目根目录里，通常不需要写 `--project`
+- 只有一个 active change 时，通常也不需要写 `--change`
+- 每次暂停回来，默认先跑 `workflow-status` 和 `next-step`
+- 觉得命令太散时，用 TUI
+- 已经很清楚要跑哪条命令、而且在写脚本时，直接用 CLI 更快

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

@@ -19,6 +19,16 @@
 - `continue` 选路先看工件/checkpoint 真相，再把 Context Delta 当作辅助恢复信息
 - 如果 Context Delta 与当前工件冲突，选路时应忽略冲突内容并记录冲突
 
+execution-chain 命令组合（终态前建议）：
+
+- `da-vinci workflow-status --project <path> [--change <id>] --json`
+- `da-vinci next-step --project <path> [--change <id>]`
+- `da-vinci lint-spec|lint-tasks|lint-bindings --project <path> [--change <id>]`
+- `da-vinci scope-check --project <path> [--change <id>]`
+- `da-vinci generate-sidecars --project <path> [--change <id>]`
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>]`
+- `da-vinci diff-spec --project <path> [--change <id>]`
+
 ## 1. `greenfield-spec`
 
 适用：

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

@@ -15,6 +15,8 @@
 如果你想看 Pencil 渲染、持久化、门禁和审计的专门说明，请看 [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/pencil-rendering-workflow.md)。
 如果你想看逐个 `dv:` 命令的职责、下一步推荐和 `verify` 回退规则，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
 如果你想看约束文件总览（哪些字段是硬门禁、哪些是指导项），请看 [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/constraint-files.md)。
+如果你想看 sidecar、enforcement、persisted-state 回退和 scaffold 约束，请看 [execution-chain-migration.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/execution-chain-migration.md)。
+如果你想看更偏操作手册的说明，比如第一次怎么进、暂停后怎么续跑、TUI 怎么用，请看 [skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
 
 ## 核心契约
 
@@ -42,6 +44,30 @@ Da Vinci 围绕一个固定契约工作：
 8. 实现。
 9. 验证需求漂移和设计漂移。
 
+## Workflow-State 命令面
+
+在选择下一步 `dv:` 路由前，可先使用这些命令判断当前阶段就绪度：
+
+- `da-vinci workflow-status --project <path> [--change <id>] [--json]`
+  - 从工件真相和部分 audit 可见证据推导阶段、blocker、handoff gate 与路由建议
+- `da-vinci next-step --project <path> [--change <id>] [--json]`
+  - 基于同一 workflow-state 模型，给出优先续跑动作
+- `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
+  - 在进入实现规划或实现前，校验运行时 `spec.md` 结构质量
+  - 默认 advisory；显式 `--strict` 才会把发现升级为阻断
+- `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
+  - 校验 proposal、page-map、运行时 spec、pencil-design、tasks 之间页面/状态传播是否一致
+  - 输出页面和状态的机器可读覆盖矩阵，供后续 verify/status 消费
+- `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
+  - 显式生成确定性的 planning sidecars，供 diff 和下游工具消费
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
+  - 校验从 bindings 到实现与结构覆盖的执行链证据
+- `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
+  - 报告 spec/tasks/page-map/bindings sidecars 的规范化差异，支持安全续跑
+
+这些命令不替代 `da-vinci audit --mode integrity|completion`。
+`audit` 仍是 integrity/completion 的正式真相面。
+
 ## 标准工件骨架
 
 根据 mode 的不同，Da Vinci 一般会围绕这组工件推进：