@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.1.20 - 2026-03-29
+
+### Added
+- `scripts/test-audit-context-delta.js` to cover context-delta expectation signals, status mismatch reporting, `supersedes` validation, and timestamp-normalized reference matching
+
+### Changed
+- continue prompt/docs behavior now consistently route from artifact and checkpoint truth first, with contextual deltas used only as auxiliary recovery context
+- context-delta audit expectation signals now trigger on `## Checkpoint Status` and `## MCP Runtime Gate` (or explicit `Context Delta Required` opt-in) instead of broad `## Outcome` matching
+- context-delta mismatch warnings now use neutral status-mismatch wording and include per-checkpoint status history
+- context-delta `supersedes` fields are now validated against earlier entries in the same artifact, including parseable timestamp normalization
+- README, Chinese README, workflow docs, prompt docs, and templates now document automatic context-delta checks plus optional explicit opt-in usage
+
+## v0.1.19 - 2026-03-28
+
+### Added
+- `design-supervisor review` as a documented final style-quality gate that stays distinct from `Preferred adapters`
+- `scripts/test-audit-design-supervisor.js` to cover advisory versus required reviewer branches, missing review records, and malformed review records
+- `scripts/test-pencil-lock.js` to verify blocking lock waits and timeout behavior after removing the old busy-wait loop
+
+### Changed
+- `Visual Assist` guidance now explains `Design-supervisor reviewers`, `Require Supervisor Review`, gate order, gate judging criteria, and per-gate branching in both English and Chinese
+- `visual-assist-presets` for mobile, desktop, web, and tablet now ship three explicit variants: adapter-only, advisory reviewer, and required reviewer signoff
+- completion and integrity audit now treat `Require Supervisor Review: true` as the actual hard-gate switch instead of forcing all configured reviewers into a blocking path
+- design-supervisor review records now require explicit status, issue list, and revision outcome before they count as valid audit evidence
+- Pencil lock waiting now uses blocking sleep via `Atomics.wait(...)` instead of CPU-burning busy waits while preserving the synchronous CLI call graph
+- Chinese `visual-assist-presets` now match the English three-variant structure without extra duplicated configuration blocks
+
 ## v0.1.18 - 2026-03-28
 
 ### Added

package/README.md

@@ -28,10 +28,19 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.18`
+- `@xenonbyte/da-vinci-workflow@0.1.20`
 
 Release highlights:
 
+- 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
@@ -112,6 +121,9 @@ 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
+- `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
 
 ## Visual Assist Quick Start
 
@@ -124,6 +136,17 @@ Recommended default:
 - Preferred adapters:
   - ui-ux-pro-max
   - frontend-skill
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -134,6 +157,8 @@ Recommended default:
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 Use this when:
@@ -149,6 +174,17 @@ Quality-first redesign configuration:
 - Preferred adapters:
   - frontend-skill
   - ui-ux-pro-max
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -160,6 +196,8 @@ Quality-first redesign configuration:
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - true
 ```
 
 Use this when:
@@ -187,6 +225,9 @@ Selection rules:
 - use only Pencil-supported properties; do not rely on web-only props such as `flex` or `margin`
 - keep `Fallback: native-da-vinci` unless you explicitly want missing adapters to block the workflow
 - keep `Require Adapter: false` by default and raise it to `true` only for design-critical work
+- keep `Design-supervisor reviewers` separate from `Preferred adapters`; adapters lead first-pass composition, reviewers judge final style maturity
+- keep `Require Supervisor Review: false` unless reviewer-backed style signoff is itself a delivery requirement
+- `Require Supervisor Review: true` means missing, blocked, or unaccepted reviewer results should block broad expansion, implementation-task handoff, and terminal completion
 - keep `Scope` limited to presentation quality; do not use it to delegate behavior, routes, or state truth
 
 ## Core workflow
@@ -305,6 +346,11 @@ Checkpoint outcomes:
 - `WARN`
 - `BLOCK`
 
+Context delta notes:
+
+- keep concise `Context Delta` entries inside existing change artifacts (`pencil-design.md`, `tasks.md`, `verification.md`)
+- treat contextual deltas as recovery aids, not as a second source of phase truth
+
 ## Execution Policy
 
 Da Vinci is `autonomous-by-default`.
@@ -320,6 +366,7 @@ Default behavior:
 - `PASS` -> continue
 - `WARN` -> record and continue
 - `BLOCK` -> stop only when the blocker cannot be resolved from existing artifacts or local context
+- missing or status-mismatched contextual deltas -> warn and continue
 
 Typical stop conditions:
 
@@ -341,7 +388,7 @@ Rules:
 - `page-map.md` is the source of truth for implementation pages
 - `pencil-bindings.md` is the source of truth for implementation page -> Pencil page mapping
 - in `redesign-from-code`, existing code is behavior truth, not layout truth
-- in `overhaul-from-code`, existing code is reference evidence and migration baseline, not automatic final behavior truth
+- in `overhaul-from-code`, existing code is reference evidence and migration baseline, not the final target behavior truth
 - 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
@@ -441,6 +488,13 @@ da-vinci uninstall --platform codex,claude,gemini
 - `--mode integrity`: a mid-workflow filesystem-truth check for missing baseline artifacts, misplaced exports, polluted `.da-vinci/designs/`, and missing persisted `.pen` sources
 - `--mode completion`: a strict pre-completion gate for one change scope; use `--change <change-id>` and treat any failure as blocking
 
+Context-delta integration in audit:
+
+- missing, incomplete, or status-mismatched contextual delta entries are warning-level signals
+- these warnings improve resume quality but do not introduce new completion failure gates by themselves
+- expectation checks are automatic when an artifact includes `## Checkpoint Status` or `## MCP Runtime Gate`; no manual toggle is needed in normal workflows
+- only add `Context Delta Required: true` (also accepts `yes` / `on` / `1`) for artifacts that intentionally opt in without those headings
+
 Both modes check the most common workflow-integrity failures in a project:
 
 - missing standard Da Vinci artifacts
@@ -456,16 +510,18 @@ Both modes check the most common workflow-integrity failures in a project:
 - warns when anchor-surface batches are too large and should be split before retrying
 
 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.
-During active redesign work, prefer running `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write, then use `da-vinci preflight-pencil` plus smaller follow-up batches if the same anchor surface rolls back twice.
+During active redesign work, run `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write, then use `da-vinci preflight-pencil` plus smaller follow-up batches if the same anchor surface rolls back twice.
 
 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`
 
+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:
 
-- preferred wrapper:
+- required wrapper on autonomous runs:
   - `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>`
@@ -592,6 +648,7 @@ $da-vinci use intake for this existing Android project.
 I need to globally replace the UI.
 Existing Android code is the behavior source of truth.
 HTML references are in /abs/path/to/mockups.
+Treat this as full-delivery unless I explicitly narrow it to design-only.
 ```
 
 ### Continue after inventory and spec work

package/README.zh-CN.md

@@ -30,10 +30,19 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.18`
+- `@xenonbyte/da-vinci-workflow@0.1.20`
 
 已发布版本重点：
 
+- `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 校验
@@ -89,7 +98,7 @@ Da Vinci 当前支持五种模式：
 
 ### `overhaul-from-code`
 
-已有项目，但目标是做系统级大改版；现有代码仍然是迁移基线和参考证据，但不再天然等于新版本的最终行为真相。
+已有项目，但目标是做系统级大改版；现有代码是参考证据和迁移基线，不是新系统最终行为真相。
 
 ### `feature-change`
 
@@ -117,6 +126,9 @@ Da Vinci 当前支持五种模式：
 - `intake` 和 `continue` 通常应该回到主工作流入口，即 `$da-vinci ...` 或 `/da-vinci ...`
 - 它们不应该默认把用户直接导向 `build`
 - `build` 仍然保留，但它是给已经实现就绪的高级直接入口
+- `continue` 的选路应先看工件和 checkpoint 真相，再看上下文补充信息
+- Context Delta 只用于恢复上下文，不是阶段判定真相源
+- 如果 Context Delta 与当前工件冲突，应该忽略冲突条目并按工件真相继续
 
 ## Visual Assist 快速上手
 
@@ -129,6 +141,17 @@ Da Vinci 当前支持五种模式：
 - Preferred adapters:
   - ui-ux-pro-max
   - frontend-skill
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -139,6 +162,8 @@ Da Vinci 当前支持五种模式：
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 适用场景：
@@ -154,6 +179,17 @@ Da Vinci 当前支持五种模式：
 - Preferred adapters:
   - frontend-skill
   - ui-ux-pro-max
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -165,6 +201,8 @@ Da Vinci 当前支持五种模式：
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - true
 ```
 
 适用场景：
@@ -192,6 +230,9 @@ Da Vinci 当前支持五种模式：
 - 只使用 Pencil 支持的属性，不要继续使用 `flex`、`margin` 这类 Web 属性
 - 默认保留 `Fallback: native-da-vinci`
 - `Require Adapter` 默认保持 `false`，只有设计要求很高时再改成 `true`
+- 把 `Design-supervisor reviewers` 和 `Preferred adapters` 分开；adapter 负责首轮设计引导，reviewer 负责最终风格质量把关
+- `Require Supervisor Review` 默认保持 `false`，只有“reviewer 签字本身就是交付门槛”时才改成 `true`
+- `Require Supervisor Review: true` 表示只要缺失、阻断、或未被接受的 reviewer 结果，就不能扩屏、交接实现或宣告完成
 - `Scope` 只管 presentation 质量，不要拿它去定义 behavior、route 或 state truth
 
 ## 核心工作流顺序
@@ -291,7 +332,7 @@ project/
 - `page-map.md` 是实现页面和状态的真相源
 - `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
 - 在 `redesign-from-code` 里，现有代码只是真相行为，不是真相布局
-- 在 `overhaul-from-code` 里，现有代码是参考基线和迁移约束，不是新系统天然的最终行为真相
+- 在 `overhaul-from-code` 里，现有代码是参考证据和迁移基线，不是新系统最终行为真相
 - 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
 - `design-registry.md` 里登记的首选 `.pen` 路径属于工作流自动维护的状态，不应该依赖用户手工填写
 - 一旦进入 Pencil 设计，Da Vinci 应该使用或创建这个项目内 `.pen` 路径，而不是继续沿用当前随手打开的 Pencil 文档
@@ -368,6 +409,13 @@ da-vinci uninstall --platform codex,claude,gemini
 - `--mode integrity`：适合在工作进行中检查文件系统真相，比如基础工件缺失、导出路径错误、`.da-vinci/designs/` 被污染、项目内 `.pen` 没落盘
 - `--mode completion`：适合在宣称完成前做严格检查；配合 `--change <change-id>` 使用，任何失败都应视为阻断
 
+Context Delta 与 audit 的关系：
+
+- Context Delta 缺失、字段不完整或与最新 checkpoint 不一致时，属于告警（`WARN`）
+- 这些告警用于提升续跑质量，不应单独变成新的 completion 失败门槛
+- 当工件包含 `## Checkpoint Status` 或 `## MCP Runtime Gate` 时，期望检查会自动启用，正常流程不需要手动开关
+- 只有在不包含这些标题但仍想启用检查时，才需要写 `Context Delta Required: true`（也支持 `yes` / `on` / `1`）
+
 两种模式都会检查项目里最常见的工作流完整性问题：
 
 - 标准 Da Vinci 工件缺失
@@ -383,16 +431,18 @@ da-vinci uninstall --platform codex,claude,gemini
 - 当 anchor-surface 批次太大时给出拆批警告，避免继续大块回滚
 
 当 Pencil MCP 可用时，Da Vinci 现在还要求在终态完成声明前，把 MCP runtime gate 结果记录到 `pencil-design.md`。这层 gate 负责检查 live editor/source convergence，与 filesystem audit 分工不同。
-在重设计进行中，建议在第一次成功写入 Pencil 后立即运行 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚，则继续配合 `da-vinci preflight-pencil` 和更小的 follow-up batch。
+在重设计进行中，如果有 shell 能力，应在第一次成功写入 Pencil 后立即运行 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚，则继续配合 `da-vinci preflight-pencil` 和更小的 follow-up batch。
 
 项目内 `.pen` 持久化现在分成两条受支持路径：
 
 - 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
 - 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
 
-推荐使用的持久化命令：
+如果是自治运行，session wrapper 只要可用就必须使用。只有 wrapper 确实不可用时，才退回底层 helper。
+
+持久化命令：
 
-- 优先使用封装好的 session 命令：
+- 自治运行必须使用的 session 命令：
   - `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>`
@@ -502,6 +552,7 @@ $da-vinci use intake for this existing Android project.
 I need to globally replace the UI.
 Existing Android code is the behavior source of truth.
 HTML references are in /abs/path/to/mockups.
+Treat this as full-delivery unless I explicitly narrow it to design-only.
 ```
 
 ### 已有工件后继续推进

package/SKILL.md

@@ -16,7 +16,7 @@ Keep these rules fixed:
 - Tasks decide implementation order.
 - Code must follow both requirements and Pencil data.
 - Existing code is behavior truth, not layout truth, during `redesign-from-code`.
-- Existing code is reference evidence and migration baseline, not default final behavior truth, during `overhaul-from-code`.
+- Existing code is reference evidence and migration baseline, not the final target behavior truth, during `overhaul-from-code`.
 - When requirements and Pencil drift apart, stop and update the source artifacts before continuing implementation.
 
 ## Execution Policy
@@ -136,8 +136,11 @@ Use these helper actions when the user needs help entering or resuming the workf
      - detected workflow state
      - gaps or blockers
      - one executable continuation prompt
+     - contextual recovery notes from recent checkpoint deltas when consistent with current artifacts
    - do not restart discovery if the artifacts already provide enough truth
    - do not default to `build` unless the project is clearly implementation-ready
+   - determine route selection from artifact and checkpoint truth first; contextual deltas are auxiliary and must not override routing
+   - if contextual deltas conflict with current artifacts, ignore them for routing and record the conflict
 
 ## V2 Mode Selection
 
@@ -253,7 +256,7 @@ During active Pencil work:
 - when shell access is available, preflight non-trivial `batch_design` operation strings before sending them to Pencil
 - prefer 12 or fewer operations on anchor-surface batches; if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
 - do not rely on headless interactive `save()` as the persistence truth; when live MCP edits exist, persist project-local `.pen` files from MCP-readable document snapshots
-- prefer the session wrapper commands:
+- use the session wrapper commands on autonomous runs:
   `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>`
@@ -277,6 +280,10 @@ During active Pencil work:
 - exported screenshots are review artifacts only; place them under `.da-vinci/changes/<change-id>/exports/` and never treat them as a substitute for the project-local `.pen` source
 - screenshot review is binding: if the review calls out hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues, revise the screen before treating the checkpoint as `PASS`
 - screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the concrete issue list and revision outcome; phrases such as "looks good" do not count as review evidence
+- if `DA-VINCI.md` declares `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint for the approved anchor set
+- keep `Design-supervisor reviewers` separate from `Preferred adapters`; adapters lead the design pass, reviewers judge whether the final style quality is strong enough to expand or implement
+- when `design-supervisor review` is active, review screenshots together with Pencil theme variables, `visual-thesis.md`, `content-plan.md`, and `interaction-thesis.md`, then record an explicit `PASS`, `WARN`, or `BLOCK` plus issue list and revision outcome in `pencil-design.md`
+- if `DA-VINCI.md` sets `Require Supervisor Review: true`, treat missing, blocked, or unaccepted `design-supervisor review` as a blocker before broad expansion, implementation-task handoff, or terminal completion
 
 ## Load References On Demand
 
@@ -438,7 +445,7 @@ If the active mode is `redesign-from-code`:
 If the active mode is `overhaul-from-code`:
 
 - inventory current routes, pages, modules, key flows, integrations, and permission boundaries before redefining the target product
-- treat existing code as reference evidence and migration baseline rather than default final behavior truth
+- treat existing code as reference evidence and migration baseline rather than the final target behavior truth
 - classify current system areas into `preserve`, `revise`, `retire`, and `unknown` in `migration-contract.md`
 - stabilize new `proposal.md` and `specs/` before broad Pencil design or implementation
 - update `page-map.md` to reflect the new target page set, not only the old route tree
@@ -727,6 +734,7 @@ Checkpoint handling:
 - `PASS`: continue automatically
 - `WARN`: record the issue and continue automatically
 - `BLOCK`: stop, report the blocker, and ask only if the blocker cannot be resolved from existing artifacts
+- contextual-delta issues: warn and continue; do not treat missing/stale contextual notes as standalone blockers
 
 ## Drift Policy
 

package/commands/claude/dv/continue.md

@@ -15,11 +15,15 @@ Focus on:
 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 `/da-vinci continue ...` prompt
 - one more conservative continuation prompt when useful
 
 Route discipline:
 - do not restart discovery if the current artifacts already contain enough truth
+- determine route selection from artifact and checkpoint truth before reading contextual deltas
+- 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
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
 - only prefer `/dv:build` once task generation and implementation readiness are already clear

package/commands/claude/dv/design.md

@@ -20,10 +20,11 @@ Create or update:
 Run the `design checkpoint` before locking implementation tasks.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
-Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+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.
 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, then record the reviewers, inputs, status, issue list, and revision outcome in `pencil-design.md`. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
 Before reporting `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.

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

@@ -15,11 +15,15 @@ Goal:
 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 `$da-vinci continue ...` prompt
 - one more conservative continuation prompt when useful
 
 Route discipline:
 - do not restart discovery if the current artifacts already contain enough truth
+- determine route selection from artifact and checkpoint truth before reading contextual deltas
+- 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
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/prompts:dv-tasks`
 - only prefer `/prompts:dv-build` once task generation and implementation readiness are already clear

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

@@ -14,10 +14,11 @@ Output should move the work toward:
 Use Pencil-backed structure as the design source when available.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
-Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+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.
 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, then record the reviewers, inputs, status, issue list, and revision outcome in `pencil-design.md`. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
 Before claiming `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.

package/commands/gemini/dv/continue.toml

@@ -14,11 +14,15 @@ Focus on:
 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 `/da-vinci continue ...` prompt
 - one more conservative continuation prompt when useful
 
 Route discipline:
 - do not restart discovery if the current artifacts already contain enough truth
+- determine route selection from artifact and checkpoint truth before reading contextual deltas
+- 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
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
 - only prefer `/dv:build` once task generation and implementation readiness are already clear

package/commands/gemini/dv/design.toml

@@ -13,11 +13,12 @@ Create or update:
 Use Pencil-backed page coverage as the source of presentation truth.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
-Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+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.
 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, then record the reviewers, inputs, status, issue list, and revision outcome in `pencil-design.md`. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
 Before reporting `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.
 """

package/docs/codex-natural-language-usage.md

@@ -53,6 +53,7 @@ Use this when:
 - `DA-VINCI.md` already exists
 - `.da-vinci/` artifacts already exist
 - the workflow paused and needs to resume
+- route selection should come from artifact/checkpoint truth first, then contextual deltas
 
 ### Run a mode directly
 
@@ -135,6 +136,8 @@ I need to globally replace the UI.
 Existing Android code is the behavior source of truth.
 UI reference directory: /abs/path/to/mockups
 Treat the HTML files there as presentation references only, not behavior truth.
+Open the HTML references in a real browser and wait 3-5 seconds, or until the visual state settles, before judging the final styling.
+Inventory which pages and states the reference directory actually covers and which still need to be inferred from behavior truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inspect the real codebase first and determine whether the UI stack is Jetpack Compose, XML, or mixed.
 Inventory all activities, fragments, composable destinations, nav graphs, dialogs, bottom sheets, tabs, nested flows, shared shells, subpages, and important states.
@@ -149,6 +152,8 @@ $da-vinci use continue for this existing redesign-from-code workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Existing code remains the behavior source of truth.
+Determine route progression from current artifacts and checkpoints first.
+Use contextual checkpoint deltas only as auxiliary recovery notes.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Do not stop at tasks.md.
 Continue into implementation and verification.

package/docs/dv-command-reference.md

@@ -73,6 +73,7 @@ Outputs:
 
 - detected workflow state
 - missing or weak artifacts
+- contextual recovery notes from recent checkpoint deltas when consistent with current artifacts
 - one primary continuation prompt
 - one conservative continuation prompt when useful
 
@@ -80,6 +81,8 @@ Important continuation rule:
 
 - 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
+- if contextual deltas conflict with current artifacts, ignore those deltas for route selection and report the conflict
 
 ### `/dv:breakdown`
 
@@ -116,6 +119,7 @@ This stage includes:
 - anchor-first design
 - screenshot review
 - layout hygiene
+- design-supervisor review when configured
 - `.pen` persistence
 - design checkpoint
 - design-source checkpoint

package/docs/mode-use-cases.md

@@ -63,7 +63,7 @@ Choose the mode by project start condition:
 
 4. `overhaul-from-code`
    - project already exists
-   - current code is still migration evidence
+   - current code is reference evidence and migration baseline
    - flows, logic, information architecture, or UI are being broadly redefined
 
 5. `feature-change`
@@ -82,6 +82,8 @@ Common rule:
 
 - `intake` and `continue` should normally lead back to the main workflow entry
 - they should not default the user into `build` unless the project is already implementation-ready
+- `continue` should determine route selection from artifact/checkpoint truth first, then use contextual deltas as auxiliary recovery notes
+- if contextual deltas conflict with current artifacts, ignore those deltas for routing and record the conflict
 
 ---
 
@@ -143,7 +145,7 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 
 8. create `pencil-design.md`
    - record the generated Pencil screens
-   - prefer `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
+   - require `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
    - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current live MCP snapshot through `da-vinci pencil-session persist` after material live edits
    - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
@@ -502,7 +504,7 @@ Goal:
 
 ```text
 $da-vinci use overhaul-from-code to overhaul this existing product.
-Treat current code as migration evidence and reference baseline, not automatic final behavior truth.
+Treat current code as reference evidence and migration baseline, not the final target behavior truth.
 Inventory the current system, define preserve/revise/retire/unknown boundaries, rewrite the target flows and specs, then generate Pencil-backed design work and implementation tasks.
 ```
 
@@ -544,7 +546,7 @@ Inventory the current system, define preserve/revise/retire/unknown boundaries,
 ### Where this mode differs from `redesign-from-code`
 
 - `redesign-from-code` keeps old code as behavior truth
-- `overhaul-from-code` treats old code as reference baseline and migration context
+- `overhaul-from-code` treats old code as reference evidence and migration baseline
 - `redesign-from-code` is mainly for broad UI replacement
 - `overhaul-from-code` is for broad product rewrites on top of an existing system