@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 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
+- execution-chain workflow CLI surfaces: `workflow-status`, `next-step`, `lint-spec`, `scope-check`, `lint-tasks`, `lint-bindings`, `generate-sidecars`, `verify-*`, `diff-spec`, and `scaffold`
+- persisted workflow-state snapshots and execution-signal files so route selection can reuse artifact-derived state while still reacting to fresh verify/audit outcomes
+- planning sidecars and normalized spec/page-map/bindings/tasks diff support for drift inspection
+- scaffold generation from `pencil-bindings.md`, plus workflow-state / verify / sidecar / audit execution-signal regression coverage
+- split CI lanes for core regression, contracts, and workflow e2e coverage
+
+### Changed
+- README and Chinese companion docs now document the `0.2.1` execution-chain release surface explicitly
+- `generate-sidecars` now returns `BLOCK` when workflow/change resolution fails instead of emitting a misleading `PASS`
+- `verify-implementation` now ignores tests, fixtures, scripts, and colocated `*.test.*` / `*.spec.*` files when checking implementation coverage heuristics
+
 ## v0.1.26 - 2026-03-31
 
 ### Added

package/README.md

@@ -28,71 +28,18 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.26`
-
-Release highlights for `0.1.26`:
-
-- `da-vinci bootstrap-project --project <path> [--change <id>]` now scaffolds the minimum `.da-vinci/` artifact spine, seeds a workflow-owned project-local `.pen`, and gives a concrete next-step handoff into `pencil-session begin`
-- audit failures now suggest `da-vinci bootstrap-project` when the project is missing the required `.da-vinci/` structure, reducing “hard fail with no recovery path” friction
-- `da-vinci supervisor-review --run-reviewers` now supports configurable parallel reviewer execution, resilient retry backoff, and capped retry delay (`--review-concurrency`, `--review-retries`, `--review-retry-delay-ms`, `--review-retry-max-delay-ms`)
-- real `codex exec` reviewer smoke remains opt-in, but the main CI workflow can now attach that smoke job automatically when repository integration variables are enabled; the separate `reviewer-bridge-smoke` workflow remains available for manual/weekly runs
-- `icon-sync` now supports configurable source URLs, and `icon-search` exports named scoring weights instead of relying on undocumented magic numbers
-- supervisor-review parsing now explicitly handles legacy Chinese round-attempt headings (for example `## Design-Supervisor Review（第2轮尝试）`) and keeps canonical structured review fallback deterministic
-- `--nodes-file` metadata-payload guard now reports shorter relative file paths when possible, while preserving absolute-path fallback outside current working directory
-- audit parser logic is now split into `lib/audit-parsers.js`, reducing `lib/audit.js` size and making maintenance safer
-- recursive file traversal now uses bounded safe scans with depth/count limits and symlink skipping
-- completion/integrity audit now rejects out-of-root `.pen` references from `design-registry.md`
-- `preflight-pencil` sandbox now blocks unsafe runtime tokens, disables dynamic code generation, and reports timeout failures explicitly
-- icon text normalization/tokenization is now shared across `icon-search` and `icon-aliases`, removing duplicated logic and adding parity coverage
-- `da-vinci pencil-session end` now requires live snapshot input (`--nodes-file`) unless `--force` is used, preventing silent session close while live MCP and disk are out of sync
-- `build` route discipline now treats compile success as non-terminal and requires `da-vinci audit --mode completion --change <change-id> <project-path>` before reporting terminal completion
-- `continue` route guidance now blocks `build` recommendation whenever core design gates remain unresolved (missing project-local `.pen`, active session, runtime/design-source BLOCK, or required design-supervisor BLOCK)
-- added regression coverage for session-end sync guards and prompt-level build/continue gate discipline
-- continue-routing and recovery guidance now consistently prioritize artifact/checkpoint truth first, with contextual deltas treated as auxiliary notes only
-- context-delta audit now uses tighter expectation signals, status-mismatch wording, and `supersedes` validation with timestamp normalization
-- context-delta expectation checks are now automatic for checkpoint-bearing artifacts and allow explicit opt-in (`Context Delta Required`) only for edge cases
-- `design-supervisor review` is now a first-class final style-quality gate with explicit advisory versus required behavior controlled by `Require Supervisor Review`
-- `Visual Assist` docs now explain gate order, gate judging criteria, and branching across screenshot review, layout hygiene, design checkpoint, and design-supervisor review
-- `visual-assist-presets` for mobile, desktop, web, and tablet now ship three explicit variants: adapter-only, advisory reviewer, and required reviewer signoff in both English and Chinese
-- completion and integrity audit now respect `Require Supervisor Review: true` as the actual hard-gate switch instead of treating every configured reviewer as automatically blocking
-- design-supervisor review records now require explicit status, issue list, and revision outcome before they count as valid audit evidence
-- Pencil lock waiting now sleeps without busy-spinning, reducing CPU waste while preserving the synchronous CLI/session contract
-- project-local `.pen` persistence now uses an MCP-snapshot-to-disk path instead of relying on headless interactive `save()`
-- redesign runs now seed a registered project-local `.pen` before the first Pencil edit and record persisted snapshot hashes for later sync checks
-- `da-vinci write-pen` now atomically writes workflow-owned `.pen` files from MCP-readable node and variable payloads with optional reopen verification
-- `da-vinci ensure-pen` now seeds or verifies a registered project-local `.pen` before live editing starts
-- `da-vinci check-pen-sync` now compares a current live MCP snapshot payload against the persisted project-local `.pen`
-- `da-vinci snapshot-pen` now serves only as a disk-to-disk utility for rebuilding an existing Pencil source and verifying reopen
-- visual-adapter execution now requires explicit runtime declaration of the resolved primary adapter and any unavailable requested adapters
-- cross-platform near-name adapters such as `frontend-skill` and `frontend-design` are now treated as distinct unless the current environment explicitly resolves them
-- complex `redesign-from-code` runs now require a visual thesis, content plan, interaction thesis, and anchor-surface structural-delta notes before broad Pencil generation
-- screenshot review is now documented as a binding gate; analysis that reports hierarchy, spacing, clarity, or inconsistency issues cannot be treated as an automatic pass
-- form-factor-specific layout hygiene is now documented as a separate hard gate from `Visual Assist`, with blocker conditions for mobile, tablet, desktop, and web review
-- `.da-vinci/designs/` is now documented more strictly as a `.pen`-only directory, and project-local `.pen` persistence must be verified as shell-visible immediately after the first Pencil write
-- multi-surface redesign guidance now requires a shared primitive family to be defined from approved anchor surfaces before broad page expansion
-- Pencil generation guidance now explicitly rejects web-only properties such as `flex` and `margin`
-- visual-adapter resolution now requires the resolved primary adapter to actively lead the first design pass
-- complex redesigns now default to anchor-first Pencil generation: design 1-3 anchor surfaces, review screenshots, then expand
-- design checkpoint now explicitly blocks placeholder-heavy repeated scaffolds and premature broad multi-screen generation
-- prompt presets for mobile, desktop, web, and tablet now include `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue` variants
-- `redesign-from-code` now states explicitly that existing code is behavior truth, not layout truth
-- complex pages are now expected to decompose into subpages, overlays, materially different states, and implementation surfaces before broad Pencil redesign
-- design-checkpoint guidance now explicitly blocks skin-swap redesigns, generic card mosaics, weak visual anchors, and decorative clutter
-- `Visual Assist` docs now include quick-start recommendations and a quality-first configuration for design-critical work
-- visual-adapter configuration is now documented explicitly, including field meanings, resolution order, and fallback behavior
-- ready-to-copy `Visual Assist` presets are now included for mobile, desktop, web, and tablet scenarios
-- the repo-local forward test now shows how `Visual Assist`, adapter resolution, and persisted `.pen` paths should be recorded
-- Codex natural-language usage is now documented explicitly, including `intake`, `prompt`, `continue`, and direct mode entry patterns
-- project-local Pencil `.pen` files are now documented to persist under `.da-vinci/designs/`
-- design registry and artifact templates now record preferred persisted `.pen` paths for project-local reuse
-- prompt-entry helper routes for `intake`, `prompt`, and `continue` are now published across Codex, Claude, and Gemini
-- Chinese companion docs are now intentionally limited to `README.zh-CN.md` and `docs/zh-CN/`
-- asset validation now covers the full shipped documentation set
-- `da-vinci status` now validates full installed asset sets across Codex, Claude, and Gemini, and flags stale or locally modified copies
-- Claude and Gemini command adapters now use self-contained workflow wording after installation
-- `.npmrc` and `openspec/` are kept local-only and are no longer versioned or shipped in the npm package
-- Node-first install, uninstall, status, and asset validation commands remain the supported distribution path
-- repo-local forward-test example for a `greenfield-spec` workflow remains included
+- `@xenonbyte/da-vinci-workflow@0.2.2`
+
+Release highlights for `0.2.2`:
+
+- 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
 
 ## Supported workflow modes
 
@@ -137,10 +84,26 @@ Route discipline:
 - `intake` and `continue` should usually generate a main `$da-vinci ...` or `/da-vinci ...` prompt
 - they should not default the user into `build`
 - `build` remains a direct expert route for workflows that are already implementation-ready
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` and `da-vinci next-step --project <path> [--change <id>]` before selecting continuation route text
+- run `da-vinci lint-spec --project <path> [--change <id>]` before implementation when runtime spec quality is uncertain
+- run `da-vinci scope-check --project <path> [--change <id>]` before implementation when page/state propagation across planning artifacts is uncertain
+- run `da-vinci verify-bindings` / `verify-implementation` / `verify-structure` / `verify-coverage` before terminal completion claims
+- run `da-vinci generate-sidecars --project <path> [--change <id>]` and `da-vinci diff-spec --project <path> [--change <id>]` when planning deltas must be tracked explicitly
 - `continue` should determine route selection from artifact and checkpoint truth first
 - 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 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
+
+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`.

package/README.zh-CN.md

@@ -30,71 +30,18 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.26`
-
-`0.1.26` 版本重点：
-
-- 新增 `da-vinci bootstrap-project --project <path> [--change <id>]`，可快速生成最小 `.da-vinci/` 工件骨架、seed 一个工作流管理的项目内 `.pen`，并给出后续 `pencil-session begin` 的明确下一步
-- audit 现在在缺少 `.da-vinci/` 或关键工件时，会直接提示可执行的 `da-vinci bootstrap-project` 修复命令，不再只报硬错误
-- `da-vinci supervisor-review --run-reviewers` 现已支持 reviewer 并发执行、失败重试退避，以及最大退避封顶（`--review-concurrency`、`--review-retries`、`--review-retry-delay-ms`、`--review-retry-max-delay-ms`）
-- 真实 `codex exec` reviewer bridge 仍然是 opt-in，但主 CI workflow 现在在仓库变量已配置时也能自动挂上 reviewer smoke job；独立的 `reviewer-bridge-smoke` workflow 仍保留给手动/定时烟测
-- `icon-sync` 现在支持可配置的上游 source URL，`icon-search` 评分权重也改成了具名常量，降低后续维护成本
-- supervisor-review 解析现已显式覆盖中文 legacy 轮次标题（例如 `## Design-Supervisor Review（第2轮尝试）`），并保持“优先结构化评审块”的回退策略可预测
-- `--nodes-file` 元数据误传保护现在优先输出更短的相对路径（在 cwd 外仍回退绝对路径），便于日志阅读
-- audit 解析职责已拆分到 `lib/audit-parsers.js`，`lib/audit.js` 体量下降，可维护性更好
-- 递归文件扫描改为安全有界遍历：增加深度/数量上限，并跳过符号链接
-- completion/integrity audit 现在会拦截并忽略 `design-registry.md` 中越出项目根目录的 `.pen` 引用
-- `preflight-pencil` 沙箱增强：拦截危险运行时 token、禁用动态代码生成，并对超时失败给出明确分类
-- `icon-search` 与 `icon-aliases` 现在复用同一套文本归一化/分词逻辑，去掉重复实现并补了一致性回归测试
-- `da-vinci pencil-session end` 现在默认要求提供 live 快照输入（`--nodes-file`）；只有显式 `--force` 才允许跳过，避免 live MCP 与磁盘未同步时被静默关闭
-- `build` 路由现在明确：编译成功不等于流程完成；对外宣布终态前必须通过 `da-vinci audit --mode completion --change <change-id> <project-path>`
-- `continue` 的推荐规则现在会拦截未过设计门禁时的 `build` 选路（缺少项目内 `.pen`、session 未关闭、runtime/design-source BLOCK、required design-supervisor BLOCK）
-- 新增回归测试覆盖：session 结束同步防护，以及 build/continue 提示词级门禁约束
-- `continue` 的选路与恢复规则现已统一：先看工件/checkpoint 真相，再把 Context Delta 当作辅助信息
-- Context Delta 审计规则已强化：触发信号更精确、告警改为状态不一致语义，并补充 `supersedes` 校验与时间归一化
-- checkpoint 相关工件默认自动启用 Context Delta 期望检查；只有少数无 checkpoint 标题的工件才需要显式 `Context Delta Required`
-- `design-supervisor review` 现在成为正式的最终风格质量 gate，并通过 `Require Supervisor Review` 明确区分“建议性”与“硬门槛”
-- `Visual Assist` 文档现在补全了 gate 顺序、每层 gate 怎么审，以及 screenshot review、layout hygiene、design checkpoint、design-supervisor review 之间的分叉规则
-- 移动端、桌面端、Web、平板四套 `visual-assist-presets` 现在都提供三种明确变体：只有 adapter、reviewer 建议性审查、reviewer 硬签字，中英文一致
-- completion / integrity audit 现在真正以 `Require Supervisor Review: true` 作为硬门槛开关，而不是只要配置 reviewer 就一律阻断
-- `design-supervisor review` 记录现在必须有明确状态、问题列表和回改结果，才算有效审查证据
-- Pencil 锁等待现在改成阻塞 sleep，不再 busy wait 空转 CPU，同时保留同步 CLI/session 的调用语义
-- 项目内 `.pen` 持久化现在改为“从 MCP 快照写回磁盘”的正式路径，不再依赖 headless interactive `save()`
-- 重设计流程现在要求在第一次 Pencil 编辑前先 seed 一个登记好的项目内 `.pen`，并记录后续持久化快照 hash 以便做同步校验
-- `da-vinci write-pen` 现在可以把 MCP 可读的节点和变量快照原子写成工作流管理的 `.pen` 文件，并可选地做 reopen 校验
-- `da-vinci ensure-pen` 现在可以在 live 编辑开始前 seed 或校验登记好的项目内 `.pen`
-- `da-vinci check-pen-sync` 现在可以把当前 live MCP 快照和已持久化的项目内 `.pen` 做同步比对
-- `da-vinci snapshot-pen` 现在只作为 disk-to-disk 工具，用来从已有 Pencil 源重建规范化 `.pen` 并验证重新打开结果
-- visual adapter 的执行现在要求在运行时明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
-- `frontend-skill`、`frontend-design` 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
-- 复杂 `redesign-from-code` 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
-- screenshot review 现在被明确强调为硬闸门；只要分析指出 hierarchy、spacing、clarity 或 inconsistency 问题，就不能自动判通过
-- form factor 专用的 layout hygiene 现在被定义成独立于 `Visual Assist` 的硬闸门，mobile、tablet、desktop、web 都有各自的 blocker 条件
-- `.da-vinci/designs/` 现在更明确只用于放 `.pen` 文件，而且第一次 Pencil 写入后就要验证对应 `.pen` 已经成为 shell 可见文件
-- 多 surface 重设计现在要求先从已通过的 anchor surface 中抽出 shared primitive family，再扩展更多页面
-- Pencil 生成规则现在明确拒绝 `flex`、`margin` 这类 Web 属性
-- visual adapter 解析现在要求“解析出来的主 adapter 必须真正主导首轮设计”，而不是只登记在工件里
-- 复杂重设计现在默认采用 anchor-first 的 Pencil 生成策略：先做 1 到 3 个 anchor surface，截图审查后再扩展
-- design checkpoint 现在会明确拦截大量空占位、重复模板和过早的大批量多页面脚手架
-- 移动端、桌面端、Web、平板的提示词模板现在都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
-- `redesign-from-code` 现在明确写清：现有代码只是真相行为，不是真相布局
-- 复杂页面现在明确要求在大规模 Pencil 重设计前拆成 subpage、overlay、明显不同 state 和 implementation surface
-- design checkpoint 现在明确会拦截旧 UI 换皮、通用卡片拼贴、弱视觉锚点和装饰性噪音
-- `Visual Assist` 文档现在补了快速上手建议和“设计质量优先”配置
-- visual adapter 的配置字段、解析顺序和回退行为现在有单独文档说明
-- 现在提供按移动端、桌面端、Web、平板拆分的 `Visual Assist` 可复制模板
-- 仓库内的 forward test 示例现在展示了 `Visual Assist`、adapter 解析结果和 `.pen` 持久化记录方式
-- Codex 的自然语言用法现在有单独文档，明确说明 `intake`、`prompt`、`continue` 和直接 mode 调用方式
-- 项目内 Pencil `.pen` 文件现在明确约定默认持久化到 `.da-vinci/designs/`
-- 设计源登记和工件模板现在会记录项目内优先使用的 `.pen` 路径
-- `intake`、`prompt`、`continue` 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
-- 中文配套文档现在刻意只保留 `README.zh-CN.md` 和 `docs/zh-CN/`
-- 资产校验现在覆盖完整的随包文档集合
-- `da-vinci status` 会校验 Codex、Claude、Gemini 的完整安装资产，并标记陈旧或被本地改写的副本
-- Claude 和 Gemini 安装后的命令文案已改为自洽的工作流措辞
-- `.npmrc` 和 `openspec/` 现在只本地保留，不再进入版本管理和 npm 包
-- 安装、卸载、状态、资产校验都通过 Node CLI 提供
-- 仓库内含一个 `greenfield-spec` 的本地 forward-test 参考示例（文档优先，不是可直接通过 `da-vinci audit` 的 `.da-vinci/` 审计夹具）
+- `@xenonbyte/da-vinci-workflow@0.2.2`
+
+`0.2.2` 版本重点：
+
+- 新增内置终端 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 里选中的项目上下文解析
 
 ## 支持的工作流模式
 
@@ -142,10 +89,26 @@ Da Vinci 当前支持五种模式：
 - `intake` 和 `continue` 通常应该回到主工作流入口，即 `$da-vinci ...` 或 `/da-vinci ...`
 - 它们不应该默认把用户直接导向 `build`
 - `build` 仍然保留，但它是给已经实现就绪的高级直接入口
+- 有 shell 能力时，优先先跑 `da-vinci workflow-status --project <path> [--change <id>] --json` 与 `da-vinci next-step --project <path> [--change <id>]` 再决定 continue 的路由文本
+- 如果运行时 spec 质量不确定，进入实现前先跑 `da-vinci lint-spec --project <path> [--change <id>]`
+- 如果页面/状态在规划工件之间的传播关系不确定，进入实现前先跑 `da-vinci scope-check --project <path> [--change <id>]`
+- 终态前先跑 `da-vinci verify-bindings` / `verify-implementation` / `verify-structure` / `verify-coverage`
+- 需要显式追踪规划变更时，先 `da-vinci generate-sidecars --project <path> [--change <id>]`，再 `da-vinci diff-spec --project <path> [--change <id>]`
 - `continue` 的选路应先看工件和 checkpoint 真相，再看上下文补充信息
 - Context Delta 只用于恢复上下文，不是阶段判定真相源
 - 如果 Context Delta 与当前工件冲突，应该忽略冲突条目并按工件真相继续
 
+## TUI 快速上手
+
+如果真正的痛点是 CLI 面太多、不想记命令，就直接用内置终端 TUI。
+
+- 用 `da-vinci tui` 或 `da-vinci-tui` 启动
+- 没有全局安装时，用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
+- TUI 会按工作流阶段对命令分组，支持中英文说明，并在执行前先给出命令预览
+- `p` 设置项目路径上下文，`c` 设置 change-id 上下文，`l` 切换语言，`m` 编辑预览命令，`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`。

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/continue.md

@@ -20,8 +20,13 @@ Output should include:
 - one more conservative continuation prompt when useful
 
 Route discipline:
+- treat this route as prompt-first orchestration; do not assume a standalone CLI `continue` command exists
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before deciding the primary continuation route
+- use `da-vinci next-step --project <path> [--change <id>]` as the first routing signal
+- run `da-vinci scope-check --project <path> [--change <id>]` when page/state propagation looks ambiguous
 - do not restart discovery if the current artifacts already contain enough truth
 - determine route selection from artifact and checkpoint truth before reading contextual deltas
+- if workflow-status or next-step output is missing, stale, or unavailable, fall back to artifact scanning and checkpoint evidence
 - use contextual deltas as auxiliary recovery context only; they must not override route selection
 - if contextual deltas conflict with current artifacts, ignore them for routing and call out the conflict
 - do not default the user into `/dv:build` unless the project is clearly implementation-ready

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

@@ -7,7 +7,7 @@ Use the `da-vinci` skill for this request.
 
 Action: `continue`
 
-Goal:
+Focus on:
 - inspect existing workflow artifacts first
 - detect the current workflow phase
 - generate the best executable continuation prompt
@@ -20,8 +20,13 @@ Output should include:
 - one more conservative continuation prompt when useful
 
 Route discipline:
+- treat this route as prompt-first orchestration; do not assume a standalone CLI `continue` command exists
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before deciding the primary continuation route
+- use `da-vinci next-step --project <path> [--change <id>]` as the first routing signal
+- run `da-vinci scope-check --project <path> [--change <id>]` when page/state propagation looks ambiguous
 - do not restart discovery if the current artifacts already contain enough truth
 - determine route selection from artifact and checkpoint truth before reading contextual deltas
+- if workflow-status or next-step output is missing, stale, or unavailable, fall back to artifact scanning and checkpoint evidence
 - use contextual deltas as auxiliary recovery context only; they must not override route selection
 - if contextual deltas conflict with current artifacts, ignore them for routing and call out the conflict
 - do not default the user into `/prompts:dv-build` unless the project is clearly implementation-ready

package/commands/gemini/dv/continue.toml

@@ -19,8 +19,13 @@ Output should include:
 - one more conservative continuation prompt when useful
 
 Route discipline:
+- treat this route as prompt-first orchestration; do not assume a standalone CLI `continue` command exists
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before deciding the primary continuation route
+- use `da-vinci next-step --project <path> [--change <id>]` as the first routing signal
+- run `da-vinci scope-check --project <path> [--change <id>]` when page/state propagation looks ambiguous
 - do not restart discovery if the current artifacts already contain enough truth
 - determine route selection from artifact and checkpoint truth before reading contextual deltas
+- if workflow-status or next-step output is missing, stale, or unavailable, fall back to artifact scanning and checkpoint evidence
 - use contextual deltas as auxiliary recovery context only; they must not override route selection
 - if contextual deltas conflict with current artifacts, ignore them for routing and call out the conflict
 - do not default the user into `/dv:build` unless the project is clearly implementation-ready

package/commands/templates/dv-continue.shared.md

@@ -0,0 +1,33 @@
+# Da Vinci Continue
+
+{{USE_LINE}}
+
+Action: `continue`
+
+Focus on:
+- inspect existing workflow artifacts first
+- detect the current workflow phase
+- generate the best executable continuation prompt
+
+Output should include:
+- detected workflow state
+- missing or weak artifacts
+- contextual recovery notes from recent checkpoint deltas when they are consistent with current artifacts
+- one primary `{{PROMPT_PREFIX}}` prompt
+- one more conservative continuation prompt when useful
+
+Route discipline:
+- treat this route as prompt-first orchestration; do not assume a standalone CLI `continue` command exists
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before deciding the primary continuation route
+- use `da-vinci next-step --project <path> [--change <id>]` as the first routing signal
+- run `da-vinci scope-check --project <path> [--change <id>]` when page/state propagation looks ambiguous
+- do not restart discovery if the current artifacts already contain enough truth
+- determine route selection from artifact and checkpoint truth before reading contextual deltas
+- if workflow-status or next-step output is missing, stale, or unavailable, fall back to artifact scanning and checkpoint evidence
+- use contextual deltas as auxiliary recovery context only; they must not override route selection
+- if contextual deltas conflict with current artifacts, ignore them for routing and call out the conflict
+- do not default the user into `{{BUILD_ROUTE}}` unless the project is clearly implementation-ready
+- if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `{{TASKS_ROUTE}}`
+- only prefer `{{BUILD_ROUTE}}` once task generation and implementation readiness are already clear
+- do not route into `{{BUILD_ROUTE}}` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
+- continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

package/docs/dv-command-reference.md

@@ -37,6 +37,40 @@ 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
+  - keep this distinct from `audit`: route guidance is not completion truth
+- `da-vinci next-step --project <path> [--change <id>] [--json]`
+  - provides a route-first continuation summary from the same derived workflow state
+  - use this as the first continuation signal before free-form artifact scanning
+- `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
+  - validates Da Vinci runtime `spec.md` schema sections (`Behavior`, `States`, `Inputs`, `Outputs`, `Acceptance`, `Edge Cases`)
+  - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
+  - explicitly does not treat OpenSpec planning `ADDED Requirements` structure as runtime-spec validity
+- `da-vinci scope-check --project <path> [--change <id>] [--strict] [--json]`
+  - checks proposal, page-map, runtime specs, pencil-design states, and tasks for scope propagation gaps
+  - emits a machine-readable coverage matrix for pages and states
+  - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
+- `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
+  - validates top-level task groups, ordering, verification actions, and behavior-to-task coverage hints
+  - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
+- `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
+  - validates implementation-to-Pencil mappings for parseability, source shape, and implementation landings
+  - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
+- `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
+  - explicitly generates deterministic planning sidecars: `spec.index.json`, `tasks.index.json`, `page-map.index.json`, `bindings.index.json`
+  - this is the only write surface for planning sidecars; lint/status/verify surfaces should not silently rewrite them
+- `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
+  - verifies code landings, planned-state implementation evidence, and structural consistency against bindings
+  - `verify-structure` reports whether checks used markup-backed analysis or heuristic fallback and exposes confidence
+- `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
+  - compares normalized planning sidecars and reports added/removed/modified requirement planning items
+  - includes normalized spec deltas plus broader planning summaries (tasks/page-map/bindings) under one surface
 - `da-vinci icon-sync`
   - sync official icon names (Material Symbols, Lucide, Feather, Phosphor) into `~/.da-vinci/icon-catalog.json`
   - default scope is user-level (current HOME), reusable across projects for the same user
@@ -114,6 +148,7 @@ Outputs:
 
 Important continuation rule:
 
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` first and use `da-vinci next-step --project <path> [--change <id>]` as the first route signal
 - if design exists but `tasks.md` does not, continuation should usually point to `tasks`
 - it should not promote `build` as a co-equal next step yet
 - route selection should be derived from artifact and checkpoint truth before contextual deltas are consulted

package/docs/execution-chain-migration.md

@@ -0,0 +1,46 @@
+# Execution-Chain Migration Guide
+
+Use this guide when enabling the execution-chain upgrade surfaces on existing projects.
+
+## 1. Sidecar Generation Lifecycle
+
+Planning sidecars are explicit artifacts, not hidden by-products.
+
+- generate with `da-vinci generate-sidecars --project <path> [--change <id>]`
+- sidecars are written under `.da-vinci/changes/<change-id>/sidecars/`
+- lint, status, and verify commands must not silently rewrite sidecars
+- regenerate sidecars after meaningful proposal/spec/page-map/tasks/bindings changes
+
+## 2. Advisory vs Strict Rollout
+
+Default policy:
+
+- `lint-spec`, `scope-check`, `lint-tasks`, `lint-bindings` are advisory (`WARN` without hard exit)
+- pass `--strict` to promote warnings to blocking command exits
+- promote strict mode in CI only after warning baselines stabilize
+
+Audit integration:
+
+- integrity audit treats planning-signal `BLOCK` as warning-level advisory evidence
+- completion audit treats verification-signal `BLOCK` as failure-level evidence
+
+## 3. Persisted Workflow State Fallback
+
+`workflow-status` uses `.da-vinci/state/workflow.json` only when:
+
+- state schema version is supported
+- change entry exists
+- state timestamp is fresh
+- fingerprint matches current artifact truth
+
+If any check fails, Da Vinci falls back to derived state from artifacts and records reconciliation notes.
+
+## 4. Scaffold Constraints
+
+`da-vinci scaffold` is an MVP skeleton generator with strict constraints:
+
+- output is TODO-marked and reviewable only
+- output is not final code generation
+- no multi-framework expansion in the MVP
+- scaffold boundaries come from `pencil-bindings.md` mappings
+- verify scaffold output with `verify-bindings`, `verify-implementation`, and `verify-structure` before acceptance

package/docs/execution-chain-plan.md

@@ -0,0 +1,125 @@
+# Execution-Chain Upgrade Plan Notes
+
+This document records planning decisions required by the execution-chain upgrade.
+
+## Phase 0 Pre-work Decisions
+
+### Workflow inventory summary
+
+Canonical workflow definitions currently live across:
+
+- `SKILL.md`
+- `references/` (`modes`, `checkpoints`, `artifact-templates`)
+- command assets (`commands/*/dv/*`)
+- CLI surfaces (`lib/cli.js`)
+- workflow tests (`scripts/test-mode-consistency.js`, workflow-state tests)
+
+### Canonical contract concepts
+
+The workflow contract must own:
+
+- modes
+- required artifacts
+- checkpoints
+- route dependencies
+- stage handoff gates
+- status vocabulary (`PASS/WARN/BLOCK`)
+
+### Compatibility boundaries
+
+Existing projects can adopt upgrades without mandatory rewrites when:
+
+- sidecars are optional until explicitly generated
+- persisted workflow state is optional and falls back to derived state
+- legacy artifact headings remain parseable
+
+### Sequencing rules
+
+- scaffolding is downstream from verification-backed planning decisions
+- persisted write-back is downstream from derived read-model stability
+- prompt-first `continue` remains route orchestration, not standalone CLI continuation
+
+### Schema boundary
+
+- OpenSpec planning specs define this upgrade itself
+- Da Vinci runtime artifacts (`spec.md`, `tasks.md`, `pencil-bindings.md`, etc.) remain independent runtime schemas
+
+### Runtime section inventory
+
+- `spec.md`: `Behavior`, `States`, `Inputs`, `Outputs`, `Acceptance`, `Edge Cases`
+- `page-map.md`: canonical pages and states-per-page
+- `tasks.md`: top-level task groups and checklist execution items
+- `pencil-bindings.md`: implementation -> design mappings
+- `verification.md`: requirement/design/binding/outcome evidence
+
+### Parser ownership strategy
+
+- heading and section primitives stay in `audit-parsers.js`
+- runtime planning parsers live in `planning-parsers.js`
+- runtime spec parser lives in `artifact-parsers.js`
+
+### Test layering strategy
+
+- unit: parser and envelope tests
+- integration: command-level fixture tests (`lint-*`, `scope-check`, `verify-*`, sidecars, diff)
+- contract: workflow-contract and generated command-asset checks
+- backward compatibility: fixtures missing sidecars/workflow state/new template metadata
+
+### Phase-level estimates and re-baseline rule
+
+- Phase 1: 1-2 weeks
+- Phase 2: 1-2 weeks
+- Phase 3: 1-2 weeks
+- Phase 4a: 1-2 weeks
+- Phase 4b: 1-2 weeks
+- Phase 4c: 1-2 weeks
+
+Re-baseline rule:
+
+- if phase-exit DoD misses by >20%, freeze scope expansion and re-estimate remaining phases before adding new surfaces
+
+## DoD and MVP Mapping
+
+### 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 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
+
+### First-release MVP scope
+
+In scope:
+
+- workflow-status/next-step
+- lint-spec/lint-tasks/lint-bindings/scope-check
+- generate-sidecars + diff-spec
+- verify-bindings/verify-implementation/verify-structure/verify-coverage
+- persisted workflow-state fallback
+- constrained scaffold skeleton output
+
+Out of scope:
+
+- multi-framework scaffold generation
+- autonomous production code generation from `.pen` without review
+
+### CI and validation mapping
+
+- core regression lane: `npm run quality:ci:core`
+- workflow e2e lane: `npm run quality:ci:e2e`
+- reviewer bridge lane: `npm run quality:reviewer-bridge-smoke` (opt-in)
+- contract lane: `npm run quality:ci:contracts`
+
+### Promotion rules
+
+- MVP -> full rollout promotion requires all phase DoD checks green for two consecutive CI cycles
+- advisory-to-strict promotion for planning lint requires warning baseline review and owner signoff
+
+### Release criteria and fallback
+
+- release requires core + contracts + e2e lanes green
+- stale persisted state always falls back to derived state
+- verify-structure unsupported cases must emit heuristic fallback with confidence

package/docs/prompt-entrypoints.md

@@ -64,6 +64,12 @@ What it should output:
 
 Continuation precedence:
 
+- when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before route selection
+- use `da-vinci next-step --project <path> [--change <id>]` as the first continuation routing signal
+- run `da-vinci lint-spec --project <path> [--change <id>]` when runtime spec quality is uncertain before routing into `build`
+- run `da-vinci scope-check --project <path> [--change <id>]` when page or state propagation across planning artifacts is uncertain
+- run `da-vinci verify-bindings --project <path> [--change <id>]` and `da-vinci verify-coverage --project <path> [--change <id>]` before terminal completion routing
+- run `da-vinci diff-spec --project <path> [--change <id>]` after planning edits when continuation must reason about changed requirement slices
 - determine routing from artifact and checkpoint truth first
 - use contextual checkpoint deltas only as auxiliary recovery context
 - if contextual deltas conflict with current artifacts, ignore them for routing and note the conflict
@@ -79,6 +85,8 @@ Use this default sequence:
 
 Do not default this sequence to `build`.
 
+If command recall becomes the main friction, launch `da-vinci tui` and use the grouped workflow surfaces from the terminal UI instead of memorizing each CLI surface manually.
+
 `build` is still valid, but it is an expert route for workflows that are already implementation-ready.
 
 State rule: