@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v0.2.4 - 2026-04-02
+
+### Changed
+- design-approval freshness gates now compare approval markers against `design.md`, `pencil-design.md`, and `pencil-bindings.md` modification times
+- planning parser verification command extraction now accepts template-standard `da-vinci verify-*` commands in `tasks.md`
+- worktree preflight now degrades to advisory warning and recommends isolation when `git status` is unavailable (including non-git directories)
+- supervisor-review retry normalization now preserves explicit `0` retry configuration instead of silently falling back to defaults
+- Chinese README now includes missing parity sections for checkpoint policy, execution policy, spec granularity, design input collection, repo-local forward-test reference, and current status
+
+### Fixed
+- resolve-change failure envelopes in `task-execution` and `task-review` no longer emit `undefined` when failure arrays are empty
+- `.kongming/` workspace output is now ignored by repository git tracking
+
+## v0.2.3 - 2026-04-02
+
+### Added
+- scene-first `Design Ops` actions in TUI for managed `save-current-design`, icon sync progress feedback, and platform+quality Visual Assist presets
+- additional TUI/CLI regression coverage for scene ordering, route mapping, and environment-stable `save-current-design` unavailable behavior
+
+### Changed
+- TUI root scenes now keep the documented order (`Install & Uninstall`, `Current Status`, `Switch Work Item`, `Design Ops`, `Pre-Implementation Checks`, `Pre-Acceptance Checks`, `Settings`)
+- `Current Status` route mapping now keeps `/dv:tasks`, `/dv:build`, and bootstrap routes as direct command recommendations instead of forcing mismatched scene actions
+- README (EN/ZH) now documents the updated scene-first behavior and release highlights for `0.2.3`
+
+### Fixed
+- removed stale Advanced-command branches from TUI runtime routing and key handling so only reachable scene navigation paths remain
+- stabilized `save-current-design` unavailable-path CLI testing by isolating PATH during bridge-absent assertions
+
 ## v0.2.2 - 2026-03-31
 
 ### Added

package/README.md

@@ -28,18 +28,36 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.2`
+- `@xenonbyte/da-vinci-workflow@0.2.4`
 
-Release highlights for `0.2.2`:
+Release highlights for `0.2.4`:
 
-- 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
+- design-approval stale detection now checks `design.md`, `pencil-design.md`, and `pencil-bindings.md` instead of only one artifact timestamp
+- `lint-tasks` verification command parsing now accepts `da-vinci verify-*` commands from the current task template
+- `worktree-preflight` now warns and recommends isolation when a project is not a git repository (or `git status` cannot be read)
+- `supervisor-review` retry parsing now honors explicit `--review-retries 0` without falling back to default retries
+- `task-execution` and `task-review` resolve-failure messaging now keeps defensive fallback text instead of leaking `undefined`
+
+## Discipline And Orchestration Upgrade
+
+The upgrade specification is tracked by:
+
+- `openspec/changes/discipline-and-orchestration-upgrade/`
+
+Implemented capability set:
+
+- design-approval discipline before implementation handoff
+- stronger `lint-tasks` quality checks for execution readiness
+- bounded orchestration hints (roles, concurrency, review order) derived from workflow state
+- structured implementer and two-stage task-review evidence
+- completion wording discipline backed by fresh verification evidence
+- optional worktree preflight for isolation-sensitive execution
+- structured `task-execution` and `task-review` command surfaces for per-task evidence
+
+This upgrade does **not** replace artifact truth, checkpoint truth, or completion audit authority.
+`workflow-status`, `next-step`, and orchestration outputs remain bounded by the existing contract.
+
+See [docs/discipline-and-orchestration-upgrade.md](/Users/xubo/x-skills/da-vinci/docs/discipline-and-orchestration-upgrade.md) for operator and maintainer guidance, and the OpenSpec change folder for implementation details.
 
 ## Supported workflow modes
 
@@ -87,7 +105,11 @@ Route discipline:
 - 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 worktree-preflight --project <path> [--change <id>]` before bounded-parallel execution to decide whether isolation is recommended
+- use `da-vinci task-execution --project <path> --change <id> --task-group <id> ...` to persist implementer result envelopes (`DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED`)
+- use `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> ...` to persist ordered two-stage review evidence
 - run `da-vinci verify-bindings` / `verify-implementation` / `verify-structure` / `verify-coverage` before terminal completion claims
+- require fresh verification evidence plus `da-vinci audit --mode completion --change <id> <project-path>` before any terminal completion claim
 - 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
@@ -99,8 +121,18 @@ If the growing CLI surface is the main usability problem, use the built-in termi
 
 - launch with `da-vinci tui` or `da-vinci-tui`
 - use `npx -p @xenonbyte/da-vinci-workflow da-vinci tui` when the package is not installed globally
-- the TUI groups commands by workflow phase, supports English and Chinese descriptions, and lets you launch the selected command after previewing it
-- `p` sets project path context, `c` sets change-id context, `l` toggles language, `m` edits the preview command, and `Enter` runs it
+- the root menu is scene-first: `Install & Uninstall`, `Current Status`, `Switch Work Item`, `Design Ops`, `Pre-Implementation Checks`, `Pre-Acceptance Checks`, `Settings`
+- `Pre-Implementation Checks` is a direct readiness gate for implementation
+- persistent header is intentionally minimal: brand + current project + current change
+- `Design Ops > Save Current Design` persists the current live editor state back to the project-owned `.pen` source
+- `Design Ops > Visual Assist Preset` maps `Masterpiece`/`High Quality`/`Normal` to platform preset variants `Required Supervisor Signoff`/`Advisory Supervisor Review`/`Adapter-Only`
+- `Install & Uninstall` provides three actions: `Status` (show `da-vinci status`), `Install` (install all supported platforms), and `Uninstall` (uninstall all supported platforms)
+- Visual Assist preset output is always English and updates only the `## Visual Assist` block in project-root `DA-VINCI.md` after platform+quality selection (it does not rewrite unrelated sections)
+- `Current Status` now keeps route guidance honest: when `next-step` points to `/dv:tasks`, `/dv:build`, or bootstrap, TUI keeps it as a direct command recommendation instead of forcing a mismatched scene
+- `Settings` now keeps only `Language` and `Logs`
+- `Settings > Logs` shows project-local daily diagnostics from `.da-vinci/logs/YYYY-MM-DD.ndjson`; logs are troubleshooting evidence, not workflow truth
+- it supports English/Chinese chrome, light/dark theme auto-detection, and `t` as a manual fallback
+- `p` sets project context, `c` sets change context, `l` toggles language, `J` toggles `--json`, and `Enter` opens/runs the selected item
 
 Use [docs/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for the operator-facing workflow, resume rules, and TUI guidance.
 
@@ -495,7 +527,8 @@ During active redesign work, run `da-vinci audit --mode integrity <project-path>
 Project-local `.pen` persistence now has two supported paths:
 
 - first-run path: seed the registered project-local `.pen` with `da-vinci ensure-pen --output <path> --verify-open`, open that exact path, then persist later MCP snapshot writes back to the same file
-- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh live MCP snapshot back to that same path and run `da-vinci check-pen-sync`
+- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, then use `da-vinci save-current-design --project <project-path>` after material live edits
+- treat `save-current-design` outcomes explicitly: `saved` means persisted, `blocked` means bound-source contract failure, and `unavailable` means the runtime bridge could not capture a live snapshot
 - multi-source guard: when external `.pen` sources also exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before each new `pencil-session begin`; if hashes diverge, confirm source priority explicitly and sync the chosen source into `<project-pen>` before new edits
 
 On autonomous redesign runs, the session wrapper is required when it is available. Lower-level helpers remain available only when the wrapper truly cannot be used.
@@ -504,8 +537,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,36 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.2`
+- `@xenonbyte/da-vinci-workflow@0.2.4`
 
-`0.2.2` 版本重点：
+`0.2.4` 版本重点：
 
-- 新增内置终端 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 里选中的项目上下文解析
+- 设计批准的 stale 检测从单一 `design.md` 扩展为同时检查 `design.md`、`pencil-design.md`、`pencil-bindings.md`
+- `lint-tasks` 的 verification command 解析已支持当前模板里的 `da-vinci verify-*` 命令
+- `worktree-preflight` 在“非 git 仓库”或 `git status` 失败时会返回告警并建议隔离执行
+- `supervisor-review` 现在正确处理显式 `--review-retries 0`，不再错误回退到默认重试
+- `task-execution` / `task-review` 在 resolve-change 失败路径上补强了防御性错误回退，避免输出 `undefined`
+
+## Discipline And Orchestration 升级
+
+该升级的规格与追踪在：
+
+- `openspec/changes/discipline-and-orchestration-upgrade/`
+
+当前已实现能力：
+
+- 在实现交接前增加设计批准纪律闸门
+- 强化 `lint-tasks` 的执行就绪质量检查
+- 基于 workflow state 给出有边界的编排提示（角色、并发、审查顺序）
+- 增加结构化 implementer 结果与两阶段 task review 证据
+- 用 fresh verification evidence 约束 completion 表述
+- 为隔离敏感的执行场景提供可选 worktree preflight
+- 提供结构化 `task-execution` / `task-review` 命令面用于任务级证据落盘
+
+该升级**不会**替代现有 artifact truth、checkpoint truth 和 completion audit 权威。
+`workflow-status`、`next-step` 与 orchestration 输出仍然受现有契约约束。
+
+可先阅读 [docs/discipline-and-orchestration-upgrade.md](/Users/xubo/x-skills/da-vinci/docs/discipline-and-orchestration-upgrade.md) 了解说明，再结合 OpenSpec 目录查看具体实现拆分。
 
 ## 支持的工作流模式
 
@@ -92,7 +110,11 @@ Da Vinci 当前支持五种模式：
 - 有 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 worktree-preflight --project <path> [--change <id>]` 评估是否应启用隔离
+- 用 `da-vinci task-execution --project <path> --change <id> --task-group <id> ...` 记录 implementer 结果包（`DONE`、`DONE_WITH_CONCERNS`、`NEEDS_CONTEXT`、`BLOCKED`）
+- 用 `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> ...` 记录两阶段有序 review 证据
 - 终态前先跑 `da-vinci verify-bindings` / `verify-implementation` / `verify-structure` / `verify-coverage`
+- 任何终态 completion 表述前，必须同时具备 fresh verification evidence 与 `da-vinci audit --mode completion --change <id> <project-path>` 通过
 - 需要显式追踪规划变更时，先 `da-vinci generate-sidecars --project <path> [--change <id>]`，再 `da-vinci diff-spec --project <path> [--change <id>]`
 - `continue` 的选路应先看工件和 checkpoint 真相，再看上下文补充信息
 - Context Delta 只用于恢复上下文，不是阶段判定真相源
@@ -104,8 +126,19 @@ Da Vinci 当前支持五种模式：
 
 - 用 `da-vinci tui` 或 `da-vinci-tui` 启动
 - 没有全局安装时，用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
-- TUI 会按工作流阶段对命令分组，支持中英文说明，并在执行前先给出命令预览
-- `p` 设置项目路径上下文，`c` 设置 change-id 上下文，`l` 切换语言，`m` 编辑预览命令，`Enter` 执行
+- 首屏按场景组织：`安装与卸载`、`当前状态`、`切换工作项`、`设计操作`、`实施前检查`、`验收前检查`、`设置`
+- 顶部信息最小化：只保留品牌、当前项目、当前 change
+- `设计操作 > 保存当前设计稿` 会把当前 live 编辑器状态回写到项目管理的 `.pen` 设计源
+- `提示词模版` 从英文权威源 `docs/prompt-presets/` 取内容，支持预览和复制
+- `mode1..mode5` 分别映射 `Simple redesign`、`Complex redesign`、`Redesign with reference directory`、`Design-only`、`Continue`
+- `设计操作 > Visual Assist 预设` 中 `Masterpiece`/`High Quality`/`Normal` 分别映射平台预设里的 `Required Supervisor Signoff`/`Advisory Supervisor Review`/`Adapter-Only`
+- `安装与卸载` 提供三个动作：`状态`（查看 `da-vinci status`）、`安装`（一键安装所有支持平台）、`卸载`（一键卸载所有支持平台）
+- Visual Assist 预设写入始终输出英文；在完成“平台 + 质量”选择后只更新项目根 `DA-VINCI.md` 的 `## Visual Assist` 区块，不会改写其他章节
+- `当前状态` 现在会保持路由建议真实：当 `next-step` 建议 `/dv:tasks`、`/dv:build` 或 bootstrap 时，TUI 会给出直接命令建议，而不是强行映射到不匹配场景
+- `设置` 现在只保留 `语言` 和 `日志`
+- `设置 > 日志` 读取项目内 `.da-vinci/logs/YYYY-MM-DD.ndjson` 的每日诊断日志；日志是排障证据，不是工作流真相源
+- 支持中英文界面与浅色/深色自动识别，`t` 可手动切换主题
+- `p` 设置项目上下文，`c` 设置 change 上下文，`l` 切语言，`J` 切 `--json`，`Enter` 进入/执行
 
 如果你想看“人到底怎么用这个 skill、暂停后怎么续跑、TUI 怎么配合”的完整说明，直接看 [docs/zh-CN/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
 
@@ -230,6 +263,14 @@ Da Vinci 的默认顺序是：
 - `tasks.md`：任务分组和实施顺序
 - `verification.md`：覆盖度和漂移检查
 
+### Spec 粒度规则
+
+spec 应按能力边界或重设计切片来拆分，不要按“页面数量”机械拆分。
+
+对于范围较大的 `redesign-from-code`，优先拆成多个 `specs/<slice>/spec.md`，不要堆成一个超大的 `ui-refresh/spec.md`。
+
+对于范围较大的 `overhaul-from-code`，优先使用多个 `specs/<slice>/spec.md` + 一个 `migration-contract.md`，不要把“保留行为”和“废弃行为”混在单一重写 spec 里。
+
 ## 工件放置建议
 
 推荐结构：
@@ -274,6 +315,54 @@ da-vinci bootstrap-project --project /abs/path/to/project --change <change-id>
 
 这个命令会先生成项目级 `.da-vinci/` 工件、默认项目内 `.pen`，以及当前工作流所要求的最小 change 级设计工件。
 
+## Checkpoints
+
+Da Vinci 使用以下检查点：
+
+1. `discovery checkpoint`
+2. `spec checkpoint`
+3. `design checkpoint`
+4. `design-source checkpoint`
+5. `mapping checkpoint`
+6. `task checkpoint`
+7. `execution checkpoint`
+
+检查结果：
+
+- `PASS`
+- `WARN`
+- `BLOCK`
+
+Context Delta 记录约束：
+
+- 在已有 change 工件里维护简洁 `Context Delta`（常见是 `pencil-design.md`、`tasks.md`、`verification.md`）
+- Context Delta 仅用于恢复上下文，不是阶段真相源
+
+## Execution Policy
+
+Da Vinci 默认是 `autonomous-by-default`。
+
+这意味着：
+
+- 不会在每个阶段都停下来等待用户确认
+- checkpoint 是内部质量门禁，不是审批门禁
+- 只有遇到真实阻塞才停
+
+默认行为：
+
+- `PASS` -> 继续
+- `WARN` -> 记录并继续
+- `BLOCK` -> 仅在无法从现有工件或本地上下文消解时停止
+- Context Delta 缺失或状态不一致 -> 告警并继续
+
+常见停止条件：
+
+- 用户明确要求暂停
+- 缺失输入会实质改变设计或实现结果
+- 需要外部授权或认证
+- 多个真相源冲突到无法可靠判断
+- 即将执行破坏性、会改变基线的动作
+
 ## 设计源规则
 
 - `DA-VINCI.md` 是跨页面视觉一致性的项目级视觉契约
@@ -333,6 +422,23 @@ da-vinci bootstrap-project --project /abs/path/to/project --change <change-id>
 - 默认把它当成非阻塞增强层
 - 只有用户明确要求必须使用某个 adapter 时，缺失才应阻塞工作流
 
+## 设计输入收集
+
+在 greenfield 项目开始 Pencil 设计前，Da Vinci 应先收集或推断：
+
+- 项目是否已有 `DA-VINCI.md`
+- 目标平台与设备形态（mobile / tablet / desktop / web）
+- 品牌方向、字体方向、色彩风格和密度预期
+- 是否存在必须遵守的设计约束（设计系统、交互约束、无障碍约束）
+- 是否存在外部参考素材（截图、竞品、风格板、历史设计稿）
+- 设计输出是否只交付设计，还是会继续进入实现与验收
+
+如果输入不足以稳定方向：
+
+- 先在 `design-brief.md` 记录待确认项与临时假设
+- 用最小可验证设计面推进，不直接铺开全量页面
+- 在下一轮 checkpoint 明确补齐缺失输入
+
 ## 安装
 
 安装 npm 包：
@@ -416,7 +522,8 @@ Context Delta 与 audit 的关系：
 项目内 `.pen` 持久化现在分成两条受支持路径：
 
 - 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
-- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
+- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`
+- `save-current-design` 结果必须分开处理：`saved` 才代表已持久化；`blocked` 代表绑定源契约失败；`unavailable` 代表 runtime bridge 无法抓取 live 快照
 - 多源门禁：如果还存在外部 `.pen` 源，每次新一轮 `pencil-session begin` 前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 不一致，必须先确认来源优先级并把选中的来源同步回 `<project-pen>`
 
 如果是自治运行，session wrapper 只要可用就必须使用。只有 wrapper 确实不可用时，才退回底层 helper。
@@ -425,8 +532,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`
@@ -495,6 +604,38 @@ $da-vinci use continue for <existing workflow state>
 /dv:continue
 ```
 
+## 仓库内 forward-test 参考
+
+仓库里有一个“文档优先”的 forward-test 参考样例：
+
+- `examples/greenfield-spec-markupflow/`
+
+该样例记录了 `greenfield-spec` 场景从以下阶段推进的完整链路：
+
+1. design brief
+2. proposal 与 spec
+3. page map
+4. Pencil 设计源登记
+5. Pencil 页面绑定
+6. implementation tasks
+7. 静态 HTML 交付
+8. verification
+
+它不是可直接喂给 `da-vinci audit` 的完整 fixture。样例为了可读性把工件放在仓库根；而当前 audit 期望的是完整 `.da-vinci/` 树和持久化状态元数据。
+
+如果你要把样例形态转换成可执行审计的项目骨架，请先运行：
+
+```bash
+da-vinci bootstrap-project --project <project-path> --change <change-id>
+```
+
+reviewer bridge 覆盖策略：
+
+- 默认 CI 始终运行本地核心门禁（`npm run quality:ci:core`）
+- 仅在仓库集成变量可用时，主 CI 才追加真实 reviewer bridge smoke 任务
+- 真实 `codex exec` reviewer smoke 仍是显式 opt-in：`DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1 npm run test:supervisor-review-integration`
+- `.github/workflows/reviewer-bridge-smoke.yml` 提供手动/定时 smoke；启用后会把集成缺线视为失败，而不是静默 `SKIP`
+
 ## 示例请求
 
 ### Greenfield spec
@@ -604,3 +745,17 @@ da-vinci/
 │   └── zh-CN/
 └── references/
 ```
+
+## 当前状态
+
+当前仓库包含：
+
+- Da Vinci skill 本体
+- 三平台命令适配（Codex / Claude / Gemini）
+- 工作流参考文档
+- 可执行示例
+
+下一阶段自然演进方向：
+
+1. 持续补强 install / uninstall / status 的回归覆盖
+2. 在真实项目上做带提交历史的 forward-test（含项目内 `.pen` 设计源）

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,19 @@ 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>]`
+- inspect `executionProfile` and discipline blockers from `da-vinci next-step --project <path> [--change <id>] --json`
+- if profile mode is `bounded_parallel`, run `da-vinci worktree-preflight --project <path> [--change <id>]` and downgrade to serial unless isolation is ready or explicitly accepted
+- 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
@@ -14,10 +27,13 @@ Focus on:
 
 During implementation:
 - run `execution checkpoint` after each top-level task group
+- persist per-task implementer evidence via `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <...> --summary <...>`
+- persist ordered review evidence via `da-vinci task-review --project <path> --change <id> --task-group <id> --stage spec ...` then `--stage quality ...`
 - update source artifacts before continuing if drift is found
 
 Completion discipline:
 - treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
 - do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- do not use terminal completion wording without fresh verification evidence
 - before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
 - if completion audit fails, continue from the minimal unfinished stage instead of exiting

package/commands/claude/dv/continue.md

@@ -23,14 +23,18 @@ 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
+- prefer `da-vinci next-step --project <path> [--change <id>] --json` when available so discipline markers, execution profile hints, and verification freshness are explicit
 - 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
+- if design approval discipline markers are missing, malformed, or stale, keep routing in design/task refinement rather than promoting directly into implementation
 - do not default the user into `/dv:build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
 - only prefer `/dv:build` once task generation and implementation readiness are already clear
 - do not route into `/dv:build` 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
+- if bounded-parallel execution is hinted, include `da-vinci worktree-preflight --project <path> [--change <id>]` before emitting a parallel implementation continuation prompt
+- avoid terminal completion wording unless fresh verification evidence and completion audit requirements are explicit
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

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

@@ -13,7 +13,21 @@ Focus on:
 - Pencil coverage
 - dependency order
 
+Task-plan discipline:
+- include exact file or code-area ownership targets per task group
+- include explicit verification commands, not only abstract verification wording
+- include execution intent hints (`serial`, `bounded_parallel`, or `review_required`) and review intent
+- include parseable discipline markers for design approval, plan self-review, and operator review acknowledgment
+
 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,15 @@ 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
+- require fresh verification evidence in `verify-coverage` and `workflow-status` before any terminal completion wording
+- if task-review evidence is recorded, keep unresolved `WARN/BLOCK` task-review stages open instead of closing the task group
+
 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,11 +7,27 @@ 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>]`
+- inspect `executionProfile` and discipline blockers from `da-vinci next-step --project <path> [--change <id>] --json`
+- if profile mode is `bounded_parallel`, run `da-vinci worktree-preflight --project <path> [--change <id>]` and downgrade to serial unless isolation is ready or explicitly accepted
+- 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
 - run `execution checkpoint` after each top-level task group
+- persist per-task implementer evidence via `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <...> --summary <...>`
+- persist ordered review evidence via `da-vinci task-review --project <path> --change <id> --task-group <id> --stage spec ...` then `--stage quality ...`
 - treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
 - do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- do not use terminal completion wording without fresh verification evidence
 - before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
 - if completion audit fails, continue from the minimal unfinished stage instead of exiting

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

@@ -23,14 +23,18 @@ 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
+- prefer `da-vinci next-step --project <path> [--change <id>] --json` when available so discipline markers, execution profile hints, and verification freshness are explicit
 - 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
+- if design approval discipline markers are missing, malformed, or stale, keep routing in design/task refinement rather than promoting directly into implementation
 - do not default the user into `/prompts:dv-build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/prompts:dv-tasks`
 - only prefer `/prompts:dv-build` once task generation and implementation readiness are already clear
 - do not route into `/prompts:dv-build` 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
+- if bounded-parallel execution is hinted, include `da-vinci worktree-preflight --project <path> [--change <id>]` before emitting a parallel implementation continuation prompt
+- avoid terminal completion wording unless fresh verification evidence and completion audit requirements are explicit
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

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.