@xenonbyte/da-vinci-workflow 0.1.25 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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
+- `da-vinci check-pen-baseline` to compare project-local `.pen` hashes against external or secondary `.pen` sources before a new session write phase
+- `da-vinci sync-pen-source` to sync the chosen latest `.pen` source back into the project-local baseline and refresh state metadata
+- `pencil-session begin` support for multi-source baseline flags: `--baseline`, `--prefer-source`, and `--sync-preferred-source`
+- new persistence/session/flow regression tests covering baseline divergence detection and explicit source sync recovery
+- `da-vinci bootstrap-project` to scaffold a minimal `.da-vinci/` project spine, seed a workflow-owned project-local `.pen`, and optionally create change-level design artifacts
+- release/doc alignment regression coverage for bootstrap scaffolding, package contents, and repo-head command documentation
+
+### Changed
+- multi-source baseline policy now treats `pencil-session persist` as live-vs-project sync evidence only; cross-source freshness must be explicitly aligned before continuing edits
+- design prompts, skill rules, and workflow docs now require baseline alignment checks when external `.pen` backups are present
+- `pencil-lock` now recovers stale lock files only when the owning project no longer has an active Pencil session, with a short grace window to avoid begin-time races
+- `pencil-session end --force` now records explicit `forceWithoutSync` session metadata, and completion audit now fails when a session was force-closed without final live sync verification
+- `icon-sync` network fetch now follows HTTP redirects (with loop and redirect-limit protections) instead of assuming direct 2xx responses
+- `audit` now suggests `da-vinci bootstrap-project` when required workflow artifacts are missing, instead of failing without a concrete hydration path
+- `supervisor-review` retry backoff now supports `--review-retry-max-delay-ms` so repeated reviewer failures stay bounded
+- `icon-sync` upstream source URLs are now configurable, and `icon-search` score weights are exported as named constants instead of relying on undocumented magic numbers
+- `pencil-session` lifecycle rollback/release failures now preserve structured causes instead of mutating original error messages in place
+- the main CI workflow can now attach the real reviewer bridge smoke job automatically when repository integration variables are enabled, while retaining the local core gate as the always-on baseline
+- README and command-reference docs now document the `0.1.26` bootstrap/reviewer/CI release surface explicitly instead of leaving those changes as repo-head-only notes
+
 ## v0.1.25 - 2026-03-29
 
 ### Added

package/README.md

@@ -28,68 +28,18 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.25`
-
-Release highlights:
-
-- `da-vinci supervisor-review --run-reviewers` now supports configurable parallel reviewer execution and resilient retry backoff (`--review-concurrency`, `--review-retries`, `--review-retry-delay-ms`)
-- added optional `test:supervisor-review-integration` smoke coverage for real `codex exec` review runner flows (enabled via `DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1`)
-- 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
-- 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.1`
+
+Release highlights for `0.2.1`:
+
+- added the execution-chain workflow surfaces: `workflow-status`, `next-step`, `lint-spec`, `scope-check`, `lint-tasks`, `lint-bindings`, `generate-sidecars`, `verify-*`, `diff-spec`, and `scaffold`
+- introduced persisted workflow state plus execution-signal recording so route selection can reuse trusted snapshots while still honoring fresh verify and audit blockers
+- added planning sidecars, diffing, and scaffold generation from bindings to make planning drift and implementation coverage visible from the CLI
+- split CI into core regression, contracts, and workflow e2e lanes so the new workflow-state surfaces are exercised independently
+- expanded regression coverage for workflow-state derivation, persisted-state reuse, planning lints, sidecar generation, verify/scaffold, and audit execution-signal integration
+- fixed `generate-sidecars` so unresolved workflow/change selection returns `BLOCK` instead of a misleading `PASS`
+- fixed `verify-implementation` so test, fixture, and script files do not satisfy implementation coverage heuristics
+- refreshed release and command docs to document the new execution-chain surfaces in both English and Chinese
 
 ## Supported workflow modes
 
@@ -134,6 +84,11 @@ 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
@@ -304,6 +259,14 @@ Placement rules:
 - keep change-specific workflow files in `.da-vinci/changes/<change-id>/`
 - do not scatter `proposal.md`, `tasks.md`, and `verification.md` across the project root
 
+If a repo does not have this scaffold yet, hydrate the minimum project spine first:
+
+```bash
+da-vinci bootstrap-project --project /abs/path/to/project --change <change-id>
+```
+
+That command creates the required project-level files, seeds a default project-local `.pen`, and lays down the minimum change-level design artifacts expected by the current workflow.
+
 ## Checkpoints
 
 Da Vinci uses these checkpoints:
@@ -368,8 +331,12 @@ Rules:
 - complex pages should be decomposed into subpages, states, overlays, and implementation surfaces before Pencil redesign is treated as final
 - the preferred `.pen` path recorded in `design-registry.md` is workflow-owned state, not user-authored config
 - when Pencil work starts, Da Vinci should use or create that exact project-local `.pen` path instead of relying on whichever Pencil document happens to be active
+- in multi-source scenarios (for example project-local `.pen` plus an external backup `.pen`), do not assume the project file is globally latest just because a prior `pencil-session persist` succeeded
+- before a new edit round starts, compare hashes explicitly across sources and confirm source priority
+- if an external source is selected as latest, sync it into the project-local `.pen` before further live edits
 - if Pencil MCP edits a live document but does not materialize the shell-visible project file automatically, the workflow should reconstruct and write the `.pen` file under the registered path before treating the design pass as traceable
 - before `pencil-bindings.md` or implementation tasks are treated as safe, `design-source checkpoint` should confirm that the registered path, the active Pencil source, and the shell-visible `.pen` file converge on the same project-local source
+- in multi-source scenarios (for example external backup `.pen` files), a successful `pencil-session persist` only proves live-vs-project sync for that run; it does not prove the project file is globally latest until cross-source hash alignment is confirmed
 
 Optional visual-adapter policy:
 
@@ -508,7 +475,7 @@ Both modes check the most common workflow-integrity failures in a project:
 - writes `Configured reviewers`, `Executed reviewers`, `Review source`, `Status`, `Issue list`, and `Revision outcome` into `pencil-design.md` when `--write` is provided
 - accepts explicit status input (`--status PASS|WARN|BLOCK`) or can infer a conservative status from current design artifacts
 - for required supervisor gates, prefer `--run-reviewers --write` so configured reviewer skills execute and the record is persisted in one step
-- reviewer execution tuning is available via `--review-concurrency`, `--review-retries`, and `--review-retry-delay-ms` (exponential backoff)
+- reviewer execution tuning is available via `--review-concurrency`, `--review-retries`, `--review-retry-delay-ms`, and `--review-retry-max-delay-ms` (bounded exponential backoff)
 - keeps `design-supervisor review` available as a compatibility alias
 
 When Pencil MCP is active, Da Vinci now also expects an MCP runtime gate record in `pencil-design.md` before terminal completion claims. That runtime gate checks live editor/source convergence separately from filesystem audit.
@@ -518,15 +485,18 @@ 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`
+- 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.
 
 Persistence helpers:
 
 - required wrapper on autonomous runs:
-  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `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 pencil-session end --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`
 - `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
 - `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
@@ -593,13 +563,13 @@ Entry helpers:
 /dv:continue
 ```
 
-## Repo-local forward test
+## Repo-local forward-test reference
 
-A complete repo-local forward test is available at:
+A documentation-first repo-local forward-test reference is available at:
 
 - `examples/greenfield-spec-markupflow/`
 
-That example runs a `greenfield-spec` scenario from:
+That example records a `greenfield-spec` scenario from:
 
 1. design brief
 2. proposal and spec
@@ -610,6 +580,17 @@ That example runs a `greenfield-spec` scenario from:
 7. static HTML delivery
 8. verification
 
+It is not a drop-in `da-vinci audit` fixture. The example keeps its walkthrough artifacts at the repository root for readability; the current audit commands expect a hydrated `.da-vinci/` tree plus persisted session/state metadata.
+
+If you want to turn that example shape into a runnable audit scaffold, start by hydrating a real project tree with `da-vinci bootstrap-project --project <project-path> --change <change-id>`.
+
+For reviewer bridge coverage:
+
+- default CI always runs the core local test gate (`npm run quality:ci:core`)
+- when repository integration variables are enabled, the main CI workflow also runs the real reviewer bridge smoke job
+- the real `codex exec` reviewer smoke remains opt-in via `DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1 npm run test:supervisor-review-integration`
+- `.github/workflows/reviewer-bridge-smoke.yml` provides a dedicated manual/weekly smoke workflow; when enabled, it treats missing integration wiring as a hard failure instead of silently `SKIP`-ing
+
 ## Example requests
 
 ### Greenfield spec

package/README.zh-CN.md

@@ -30,68 +30,18 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.25`
-
-已发布版本重点：
-
-- `da-vinci supervisor-review --run-reviewers` 现已支持 reviewer 并发执行与失败重试退避（`--review-concurrency`、`--review-retries`、`--review-retry-delay-ms`）
-- 新增可选 `test:supervisor-review-integration` 烟测，用于覆盖真实 `codex exec` 评审执行链路（通过 `DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1` 启用）
-- 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
+- `@xenonbyte/da-vinci-workflow@0.2.1`
+
+`0.2.1` 版本重点：
+
+- 新增 execution-chain CLI surface：`workflow-status`、`next-step`、`lint-spec`、`scope-check`、`lint-tasks`、`lint-bindings`、`generate-sidecars`、`verify-*`、`diff-spec`、`scaffold`
+- 新增持久化 workflow state 与 execution signal 记录，路由判断可以复用可信快照，同时继续尊重最新 verify / audit 阻塞结果
+- 新增 planning sidecar、diff 和基于 bindings 的 scaffold，方便直接从 CLI 看 planning drift 和实现覆盖
+- CI 现已拆成 core regression、contracts、workflow e2e 三条 lane，execution-chain 新流程会被独立回归
+- 回归测试新增覆盖 workflow-state 推导、persisted-state 复用、planning lint、sidecar 生成、verify/scaffold 与 audit execution-signal 集成
+- 修复 `generate-sidecars`：当 workflow / change 无法解析时，返回 `BLOCK`，不再误报 `PASS`
+- 修复 `verify-implementation`：测试文件、fixture 和脚本文件不再被当成真实实现覆盖证据
+- 中英文 README 与命令文档现已同步补充 execution-chain 新表面说明
 
 ## 支持的工作流模式
 
@@ -139,6 +89,11 @@ 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 与当前工件冲突，应该忽略冲突条目并按工件真相继续
@@ -300,6 +255,14 @@ project/
 - 项目内持久化的 Pencil `.pen` 文件默认放在 `.da-vinci/designs/`
 - change 级工件放在 `.da-vinci/changes/<change-id>/`
 
+如果项目还没有这套基础骨架，可以先执行：
+
+```bash
+da-vinci bootstrap-project --project /abs/path/to/project --change <change-id>
+```
+
+这个命令会先生成项目级 `.da-vinci/` 工件、默认项目内 `.pen`，以及当前工作流所要求的最小 change 级设计工件。
+
 ## 设计源规则
 
 - `DA-VINCI.md` 是跨页面视觉一致性的项目级视觉契约
@@ -312,8 +275,12 @@ project/
 - 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
 - `design-registry.md` 里登记的首选 `.pen` 路径属于工作流自动维护的状态，不应该依赖用户手工填写
 - 一旦进入 Pencil 设计，Da Vinci 应该使用或创建这个项目内 `.pen` 路径，而不是继续沿用当前随手打开的 Pencil 文档
+- 在多设计源场景（例如项目内 `.pen` + 外部备份 `.pen`）下，不能因为上一轮 `pencil-session persist` 成功就默认项目内文件一定是全局最新
+- 新一轮编辑前要先做跨源 hash 对齐并明确来源优先级
+- 如果外部源被确认是最新，先把它同步回项目内 `.pen`，再继续 live 编辑
 - 如果 Pencil MCP 修改了 live 文档但没有自动把项目内 `.pen` 文件落到磁盘，工作流应该先把该 `.pen` 文件补写到登记路径，再把这轮设计当成可追踪结果
 - 在进入 `pencil-bindings.md` 和实现任务前，应该先通过 `design-source checkpoint`，确认登记路径、当前设计源和 shell 可见 `.pen` 文件已经收敛成同一个项目级来源
+- 多设计源场景（例如存在外部备份 `.pen`）下，`pencil-session persist` 成功只代表“本轮 live 与项目内 `.pen` 同步”，不等于“项目内文件一定是全局最新”；继续前必须做跨源 hash 对齐
 
 可选 visual adapter 规则：
 
@@ -428,9 +395,9 @@ Context Delta 与 audit 的关系：
 
 - 加上 `--write` 时，会把 `Configured reviewers`、`Executed reviewers`、`Review source`、`Status`、`Issue list`、`Revision outcome` 写入 `pencil-design.md`
 - 可通过 `--status PASS|WARN|BLOCK` 显式指定，也可基于当前设计工件做保守推断
-- 对 required supervisor gate，优先使用 `--run-reviewers --write`，让 reviewer skills 执行与结果持久化一体完成
-- reviewer 执行参数可通过 `--review-concurrency`、`--review-retries`、`--review-retry-delay-ms` 调优（指数退避）
-- `design-supervisor review` 作为兼容别名仍可使用
+- 对 required supervisor gate，优先使用 `--run-reviewers --write`，让配置的 reviewer skill 真正执行并一次落盘
+- reviewer 执行参数可通过 `--review-concurrency`、`--review-retries`、`--review-retry-delay-ms`、`--review-retry-max-delay-ms` 调优（带上限的指数退避）
+- `design-supervisor review` 兼容别名仍然保留
 
 当 Pencil MCP 可用时，Da Vinci 现在还要求在终态完成声明前，把 MCP runtime gate 结果记录到 `pencil-design.md`。这层 gate 负责检查 live editor/source convergence，与 filesystem audit 分工不同。
 在重设计进行中，如果有 shell 能力，应在第一次成功写入 Pencil 后立即运行 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚，则继续配合 `da-vinci preflight-pencil` 和更小的 follow-up batch。
@@ -439,15 +406,18 @@ Context Delta 与 audit 的关系：
 
 - 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
 - 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
+- 多源门禁：如果还存在外部 `.pen` 源，每次新一轮 `pencil-session begin` 前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 不一致，必须先确认来源优先级并把选中的来源同步回 `<project-pen>`
 
 如果是自治运行，session wrapper 只要可用就必须使用。只有 wrapper 确实不可用时，才退回底层 helper。
 
 持久化命令：
 
 - 自治运行必须使用的 session 命令：
-  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `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 pencil-session end --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`
 - `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
 - `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`

package/SKILL.md

@@ -260,6 +260,9 @@ During active Pencil work:
   `da-vinci pencil-session begin --project <project-path> --pen <path>`
   `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
   `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- when multiple `.pen` sources exist (for example external backups), run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before a new `pencil-session begin`
+- if baseline hashes diverge, do not treat the previous `persist` success as global freshness; confirm source priority explicitly (`--prefer-source`) and sync the chosen source into the project-local `.pen` before new edits
+- use `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>` when an external source is selected as latest and must be materialized into the project-local baseline
 - before the first Pencil edit on a redesign pass, begin a Pencil session so the registered project-local `.pen` exists before editing and the global Pencil lock is held for that project
 - acquire the global Pencil lock before MCP write operations on a project and release it after the write phase so two projects do not compete for the same active editor
 - when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically

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/claude/dv/design.md

@@ -22,6 +22,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.
 Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, 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.
 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`.

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/codex/prompts/dv-design.md

@@ -16,6 +16,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.
 Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, 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.
 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`.

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/gemini/dv/design.toml

@@ -15,6 +15,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.
 Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, 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.
 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`.

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,36 @@ 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 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
@@ -47,12 +77,24 @@ These commands do not replace route selection, but they support design execution
 - `da-vinci icon-search --query "<text>" [--family ...] [--top ...] [--aliases ...]`
   - resolve likely `icon_font` names before writing Pencil `batch_design` operations
   - supports mixed EN/ZH terms and optional alias expansion via `~/.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]`
+  - scaffold the minimum `.da-vinci/` workflow spine for a repo that has not been hydrated yet
+  - seeds a workflow-owned project-local `.pen` under `.da-vinci/designs/`
+  - optionally creates the current change-level design artifacts (`design-brief.md`, `design.md`, `pencil-design.md`, `pencil-bindings.md`)
+  - use this before the first strict `audit` run when starting from an empty repo, a doc-first example, or a partially hydrated workspace
+- `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]`
   - persists a structured supervisor-review record (`Configured reviewers`, `Executed reviewers`, `Review source`, `Status`, `Issue list`, `Revision outcome`) in `pencil-design.md`
   - use `--run-reviewers --write` for one-step execution + record persistence through configured reviewer skills
-  - `--review-concurrency`, `--review-retries`, and `--review-retry-delay-ms` control parallelism and retry backoff for reviewer execution
+  - `--review-concurrency`, `--review-retries`, `--review-retry-delay-ms`, and `--review-retry-max-delay-ms` control parallelism plus bounded retry backoff for reviewer execution
   - when `Require Supervisor Review: true`, inferred/manual records are completion-blocking
   - `design-supervisor review` is kept as a compatibility alias that forwards to this command
+- `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>[,<other-pen>...] [--prefer-source <path>]`
+  - compares canonical `.pen` snapshot hashes across project-local and external/secondary sources before a new design round
+  - blocks by default on divergence until source priority is explicit
+  - `--prefer-source <project-pen>` records an explicit decision to keep the project path authoritative
+- `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
+  - copies the selected latest `.pen` source into the project-local `.pen` path and refreshes Da Vinci state metadata
+  - use when external backup is the latest baseline and must be materialized before `pencil-session begin`
 
 Use these utilities during `/dv:design`, especially before anchor-surface icon finalization.
 
@@ -102,6 +144,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