@xenonbyte/da-vinci-workflow 0.1.25 → 0.1.26

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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,12 +28,15 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.25`
+- `@xenonbyte/da-vinci-workflow@0.1.26`
 
-Release highlights:
+Release highlights for `0.1.26`:
 
-- `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`)
+- `da-vinci bootstrap-project --project <path> [--change <id>]` now scaffolds the minimum `.da-vinci/` artifact spine, seeds a workflow-owned project-local `.pen`, and gives a concrete next-step handoff into `pencil-session begin`
+- audit failures now suggest `da-vinci bootstrap-project` when the project is missing the required `.da-vinci/` structure, reducing “hard fail with no recovery path” friction
+- `da-vinci supervisor-review --run-reviewers` now supports configurable parallel reviewer execution, resilient retry backoff, and capped retry delay (`--review-concurrency`, `--review-retries`, `--review-retry-delay-ms`, `--review-retry-max-delay-ms`)
+- real `codex exec` reviewer smoke remains opt-in, but the main CI workflow can now attach that smoke job automatically when repository integration variables are enabled; the separate `reviewer-bridge-smoke` workflow remains available for manual/weekly runs
+- `icon-sync` now supports configurable source URLs, and `icon-search` exports named scoring weights instead of relying on undocumented magic numbers
 - supervisor-review parsing now explicitly handles legacy Chinese round-attempt headings (for example `## Design-Supervisor Review（第2轮尝试）`) and keeps canonical structured review fallback deterministic
 - `--nodes-file` metadata-payload guard now reports shorter relative file paths when possible, while preserving absolute-path fallback outside current working directory
 - audit parser logic is now split into `lib/audit-parsers.js`, reducing `lib/audit.js` size and making maintenance safer
@@ -85,7 +88,7 @@ Release highlights:
 - 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
+- `da-vinci status` now validates full installed asset sets across Codex, Claude, and Gemini, and flags stale or locally modified copies
 - Claude and Gemini command adapters now use self-contained workflow wording after installation
 - `.npmrc` and `openspec/` are kept local-only and are no longer versioned or shipped in the npm package
 - Node-first install, uninstall, status, and asset validation commands remain the supported distribution path
@@ -304,6 +307,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 +379,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 +523,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 +533,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 +611,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 +628,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,12 +30,15 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.25`
+- `@xenonbyte/da-vinci-workflow@0.1.26`
 
-已发布版本重点：
+`0.1.26` 版本重点：
 
-- `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` 启用）
+- 新增 `da-vinci bootstrap-project --project <path> [--change <id>]`，可快速生成最小 `.da-vinci/` 工件骨架、seed 一个工作流管理的项目内 `.pen`，并给出后续 `pencil-session begin` 的明确下一步
+- audit 现在在缺少 `.da-vinci/` 或关键工件时，会直接提示可执行的 `da-vinci bootstrap-project` 修复命令，不再只报硬错误
+- `da-vinci supervisor-review --run-reviewers` 现已支持 reviewer 并发执行、失败重试退避，以及最大退避封顶（`--review-concurrency`、`--review-retries`、`--review-retry-delay-ms`、`--review-retry-max-delay-ms`）
+- 真实 `codex exec` reviewer bridge 仍然是 opt-in，但主 CI workflow 现在在仓库变量已配置时也能自动挂上 reviewer smoke job；独立的 `reviewer-bridge-smoke` workflow 仍保留给手动/定时烟测
+- `icon-sync` 现在支持可配置的上游 source URL，`icon-search` 评分权重也改成了具名常量，降低后续维护成本
 - supervisor-review 解析现已显式覆盖中文 legacy 轮次标题（例如 `## Design-Supervisor Review（第2轮尝试）`），并保持“优先结构化评审块”的回退策略可预测
 - `--nodes-file` 元数据误传保护现在优先输出更短的相对路径（在 cwd 外仍回退绝对路径），便于日志阅读
 - audit 解析职责已拆分到 `lib/audit-parsers.js`，`lib/audit.js` 体量下降，可维护性更好
@@ -87,11 +90,11 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 - `intake`、`prompt`、`continue` 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
 - 中文配套文档现在刻意只保留 `README.zh-CN.md` 和 `docs/zh-CN/`
 - 资产校验现在覆盖完整的随包文档集合
-- `da-vinci status` 会校验 Codex、Claude、Gemini 的完整安装资产
+- `da-vinci status` 会校验 Codex、Claude、Gemini 的完整安装资产，并标记陈旧或被本地改写的副本
 - Claude 和 Gemini 安装后的命令文案已改为自洽的工作流措辞
 - `.npmrc` 和 `openspec/` 现在只本地保留，不再进入版本管理和 npm 包
 - 安装、卸载、状态、资产校验都通过 Node CLI 提供
-- 仓库内含一个 `greenfield-spec` 的本地 forward test
+- 仓库内含一个 `greenfield-spec` 的本地 forward-test 参考示例（文档优先，不是可直接通过 `da-vinci audit` 的 `.da-vinci/` 审计夹具）
 
 ## 支持的工作流模式
 
@@ -300,6 +303,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 +323,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 +443,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 +454,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/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-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/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/docs/dv-command-reference.md

@@ -47,12 +47,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.
 

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-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

@@ -88,17 +88,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 +123,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

@@ -58,6 +58,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

@@ -49,12 +49,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 的图标定稿前。
 

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-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

@@ -99,17 +99,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 +134,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>`。

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

@@ -60,6 +60,8 @@ Da Vinci 围绕一个固定契约工作：
 
 `DA-VINCI.md` 仍然是项目级工作流和视觉约束文件。
 
+如果你是从空仓库、文档示例、或只水合到一半的工作区开始，先执行 `da-vinci bootstrap-project --project <project-path> --change <change-id>`，再跑严格 audit。这个命令会补齐最小项目骨架，并 seed 一个工作流管理的项目内 `.pen` 基线。
+
 ## 分阶段说明
 
 ### 1. Intake 与 Mode 选择

package/examples/greenfield-spec-markupflow/README.md

@@ -1,6 +1,11 @@
 # MarkupFlow Forward Test
 
-This example is a repo-local end-to-end forward test for Da Vinci.
+This example is a repo-local forward-test reference for Da Vinci.
+
+Important:
+
+- this walkthrough is documentation-first and keeps the narrative artifacts at the repository root for readability
+- it is not intended to pass `da-vinci audit` directly until those artifacts are materialized into the current `.da-vinci/` audit layout with persisted `.pen` session/state metadata
 
 Mode: