@xenonbyte/da-vinci-workflow 0.1.25 → 0.2.1

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/pencil-rendering-workflow.md

@@ -196,6 +196,7 @@ It verifies:
 - the active editor matches that `.pen`
 - the shell-visible file exists
 - the registered `.pen` is not still only in memory
+- when external or secondary `.pen` files exist, baseline hash alignment and source-priority confirmation are explicitly recorded before a new edit round
 - `.da-vinci/designs/` is not polluted by markdown or PNG files
 
 ## MCP Runtime Gate
@@ -248,13 +249,14 @@ Context-delta audit expectations are warning-only:
 Typical autonomous chain:
 
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
-2. Pencil MCP edits
-3. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-4. screenshot review + layout hygiene
-5. design checkpoint
-6. design-supervisor review when configured
-7. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-8. `da-vinci audit --mode completion --change <change-id> <project-path>`
+2. if external/secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before edits; if diverged, sync the preferred source into `<project-pen>` first
+3. Pencil MCP edits
+4. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+5. screenshot review + layout hygiene
+6. design checkpoint
+7. design-supervisor review when configured
+8. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+9. `da-vinci audit --mode completion --change <change-id> <project-path>`
 
 ## Flow Diagram
 

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

package/docs/prompt-presets/README.md

@@ -1,7 +1,11 @@
 # Prompt Presets
 
+## Template Notes
+
 Use these presets when you want a copy-ready starting prompt for a specific product surface.
 
+This section explains what each preset family is for, when to use it, and how it should pair with `Visual Assist` plus workflow gates.
+
 These presets primarily target screen-design work once the workflow mode is already clear.
 For broad existing-product rewrites where flows or logic are also changing, prefer `overhaul-from-code` plus `intake`/custom prompt setup first, then reuse the relevant design-oriented preset after `proposal.md`, `migration-contract.md`, and target `specs/` stabilize.
 

package/docs/visual-assist-presets/README.md

@@ -1,7 +1,11 @@
 # Visual Assist Presets
 
+## Template Notes
+
 Use these presets as starting points for the `## Visual Assist` section inside `DA-VINCI.md`.
 
+This section explains the intent of each preset family, how the variants differ, and which workflow responsibilities must stay outside the preset itself.
+
 Each preset is intentionally conservative:
 
 - one primary adapter direction

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.
@@ -88,17 +98,18 @@ Expected flow:
 10. for functional icons, run `da-vinci icon-sync` then `da-vinci icon-search --query "<intent>"` to pick `icon_font` names before writing icon nodes
 11. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
 12. require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
-13. during live design work, use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
-14. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
-15. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
-16. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
-17. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-18. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
-19. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
-20. bind routes and pages to Pencil screens
-21. generate tasks aligned to the redesign slices
-22. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
-23. build and verify only after the completion gate can eventually pass
+13. when external or secondary `.pen` sources exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before the new session write phase; if diverged, sync the chosen source into `<project-pen>` first
+14. during live design work, use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
+15. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+16. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
+17. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
+18. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+19. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
+20. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
+21. bind routes and pages to Pencil screens
+22. generate tasks aligned to the redesign slices
+23. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+24. build and verify only after the completion gate can eventually pass
 
 ### Complex Android example
 
@@ -122,6 +133,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
+When external or secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` first; if hashes diverge, sync the preferred source into `<project-pen>` before editing.
 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 `da-vinci pencil-session persist`.
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Run `da-vinci audit --mode integrity <project-path>` after that first successful Pencil write before broad expansion continues.

package/docs/workflow-overview.md

@@ -13,6 +13,7 @@ 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.
 
 ## Core Contract
 
@@ -40,6 +41,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:
@@ -58,6 +83,8 @@ Depending on mode, Da Vinci typically builds this spine:
 
 `DA-VINCI.md` remains the project-level workflow and visual contract file.
 
+If you are starting from an empty repo, a documentation-first example, or a half-hydrated workspace, run `da-vinci bootstrap-project --project <project-path> --change <change-id>` before the first strict audit. That command creates the minimum project spine plus a workflow-owned project-local `.pen` baseline.
+
 ## Phase Breakdown
 
 ### 1. Intake And Mode Selection

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

@@ -39,6 +39,36 @@ Da Vinci 期望它们遵循工作流状态。
 
 这些命令不会替代 `dv:` 选路，但能显著提升设计执行质量：
 
+- `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），同一用户可跨项目复用
@@ -49,12 +79,24 @@ Da Vinci 期望它们遵循工作流状态。
 - `da-vinci icon-search --query "<关键词>" [--family ...] [--top ...] [--aliases ...]`
   - 在写 Pencil `batch_design` 前先收敛可用的 `icon_font` 名称
   - 支持中英文混合词，并可通过 `~/.da-vinci/icon-aliases.json` 做语义扩展
-- `da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status ...] [--issue-list ...] [--revision-outcome ...] [--write]`
+- `da-vinci bootstrap-project --project <path> [--change <id>] [--force]`
+  - 给还没水合完成的仓库补齐最小 `.da-vinci/` 工作流骨架
+  - 会在 `.da-vinci/designs/` 下 seed 一个工作流管理的项目内 `.pen`
+  - 传 `--change <id>` 时会顺手创建当前 change 所需的最小设计工件（`design-brief.md`、`design.md`、`pencil-design.md`、`pencil-bindings.md`）
+  - 适合从空仓库、文档示例、或只做了一半的工作区开始时，先补齐 audit 所需的基础工件
+- `da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--review-retry-max-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status ...] [--issue-list ...] [--revision-outcome ...] [--write]`
   - 持久化结构化 supervisor review 记录（`Configured reviewers`、`Executed reviewers`、`Review source`、`Status`、`Issue list`、`Revision outcome`）到 `pencil-design.md`
   - 推荐直接用 `--run-reviewers --write` 一步完成 reviewer skills 执行与记录落盘
-  - 通过 `--review-concurrency`、`--review-retries`、`--review-retry-delay-ms` 可调 reviewer 并发与重试退避
+  - 通过 `--review-concurrency`、`--review-retries`、`--review-retry-delay-ms`、`--review-retry-max-delay-ms` 可调 reviewer 并发与有上限的重试退避
   - 当 `Require Supervisor Review: true` 时，`manual/inferred` 记录会被 completion 阻断
   - `design-supervisor review` 作为兼容别名保留，并会转发到该命令
+- `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>[,<other-pen>...] [--prefer-source <path>]`
+  - 在新一轮设计前比较项目内/外部（或次要）`.pen` 的 canonical snapshot hash
+  - 默认在 hash 分叉时阻断，直到来源优先级被显式确认
+  - `--prefer-source <project-pen>` 可记录“继续以项目内路径为准”的显式决策
+- `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
+  - 把被选中的最新 `.pen` 来源同步到项目内 `.pen` 路径，并刷新 Da Vinci state 元数据
+  - 当外部备份是最新基线时，在 `pencil-session begin` 前先执行
 
 建议在 `/dv:design` 阶段使用，尤其是在 anchor surface 的图标定稿前。
 
@@ -104,6 +146,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/pencil-rendering-workflow.md

@@ -198,6 +198,7 @@ active Pencil 工作一旦存在，就要跑 `design-source checkpoint`。
 - active editor 是否就是这个 `.pen`
 - shell 上是否真的存在这个 `.pen`
 - 登记的 `.pen` 是否还停留在“只有内存，没有磁盘”
+- 如果存在外部或次要 `.pen`，是否在新一轮编辑前显式完成了基线 hash 对齐和来源优先级确认
 - `.da-vinci/designs/` 是否被 markdown 或 PNG 污染
 
 ## MCP Runtime Gate
@@ -250,13 +251,14 @@ Context Delta 相关审计期望都是告警级：
 典型自治流程：
 
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
-2. Pencil MCP 编辑
-3. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-4. screenshot review + layout hygiene
-5. design checkpoint
-6. 如果配置了，就执行 design-supervisor review
-7. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-8. `da-vinci audit --mode completion --change <change-id> <project-path>`
+2. 如果存在外部/次要 `.pen`，在编辑前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若分叉，先把优先来源同步回 `<project-pen>`
+3. Pencil MCP 编辑
+4. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+5. screenshot review + layout hygiene
+6. design checkpoint
+7. 如果配置了，就执行 design-supervisor review
+8. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+9. `da-vinci audit --mode completion --change <change-id> <project-path>`
 
 ## 流程图
 

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 与当前工件冲突，选路时忽略冲突内容并标记冲突

package/docs/zh-CN/prompt-presets/README.md

@@ -1,7 +1,11 @@
-# 场景提示词模板
+# 场景提示词模版说明
+
+## 模版说明
 
 这些模板用于在不同产品形态下，快速拿到可直接执行的起始提示词。
 
+这部分主要说明每类模板适合什么场景、应该怎么搭配使用，以及它和 `Visual Assist`、workflow gate 之间的边界。
+
 这些模板主要服务于 screen 设计阶段。
 如果是存量系统的大改版，且流程或逻辑也会一起变化，应该先用 `overhaul-from-code` 搭配 `intake` 或自定义提示词把 `proposal.md`、`migration-contract.md` 和目标 `specs/` 稳定下来，再复用对应的设计模板。
 

package/docs/zh-CN/visual-assist-presets/README.md

@@ -1,7 +1,11 @@
-# Visual Assist 场景模板
+# Visual Assist 场景模版说明
+
+## 模版说明
 
 这些模板用于作为 `DA-VINCI.md` 里 `## Visual Assist` 的起始配置。
 
+这部分主要说明每类模板的用途、不同变体的差别，以及哪些 workflow gate 仍然必须放在模板外单独处理。
+
 每个模板都刻意保持保守：
 
 - 一个主要 adapter 方向

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`
 
 适用：
@@ -99,17 +109,18 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 10. 对功能性图标，先运行 `da-vinci icon-sync` 再运行 `da-vinci icon-search --query "<意图词>"`，先选定 `icon_font` 名称再写图标节点
 11. 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
 12. 如果这一轮开始时还没有登记的项目内 `.pen`，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，先 seed 登记路径并拿到全局锁，再开始第一次 Pencil 编辑
-13. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
-14. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
-15. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
-16. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
-17. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
-18. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
-19. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
-20. 绑定路由和 Pencil 页面
-21. 生成和 redesign slice 对齐的任务
-22. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
-23. 只有在 completion gate 最终能通过时，才进入实现和验证
+13. 如果存在外部或历史 `.pen` 备份，在新一轮写入前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 不一致，先把选中的优先来源同步回 `<project-pen>`
+14. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
+15. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
+16. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
+17. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
+18. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+19. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
+20. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
+21. 绑定路由和 Pencil 页面
+22. 生成和 redesign slice 对齐的任务
+23. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
+24. 只有在 completion gate 最终能通过时，才进入实现和验证
 
 ### 复杂 Android 页面示例
 
@@ -133,6 +144,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，这样会先 seed 登记好的 `.pen` 并持有全局 Pencil 锁。
+如果存在外部或历史 `.pen`，先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 分叉，先确认来源优先级并把选中的来源同步回 `<project-pen>` 再继续。
 如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 live MCP 快照重新覆盖写回同一路径。
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。