@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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,16 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.18`
+- `@xenonbyte/da-vinci-workflow@0.1.19`
 
 Release highlights:
 
+- `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
@@ -124,6 +130,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 +151,8 @@ Recommended default:
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 Use this when:
@@ -149,6 +168,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 +190,8 @@ Quality-first redesign configuration:
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - true
 ```
 
 Use this when:
@@ -187,6 +219,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
@@ -341,7 +376,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
@@ -456,16 +491,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 +629,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,16 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.18`
+- `@xenonbyte/da-vinci-workflow@0.1.19`
 
 已发布版本重点：
 
+- `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 +95,7 @@ Da Vinci 当前支持五种模式：
 
 ### `overhaul-from-code`
 
-已有项目，但目标是做系统级大改版；现有代码仍然是迁移基线和参考证据，但不再天然等于新版本的最终行为真相。
+已有项目，但目标是做系统级大改版；现有代码是参考证据和迁移基线，不是新系统最终行为真相。
 
 ### `feature-change`
 
@@ -129,6 +135,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 +156,8 @@ Da Vinci 当前支持五种模式：
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 适用场景：
@@ -154,6 +173,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 +195,8 @@ Da Vinci 当前支持五种模式：
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - true
 ```
 
 适用场景：
@@ -192,6 +224,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 +326,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 文档
@@ -383,16 +418,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 +539,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
@@ -253,7 +253,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 +277,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 +442,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

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

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

package/docs/dv-command-reference.md

@@ -116,6 +116,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`
@@ -143,7 +143,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 +502,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 +544,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
 

package/docs/pencil-rendering-workflow.md

@@ -26,7 +26,7 @@ PNG exports are review artifacts only. They are not the design source of truth.
 
 ## Session Model
 
-Da Vinci now prefers the session wrapper:
+Da Vinci now requires the session wrapper on autonomous runs:
 
 - `da-vinci pencil-session begin`
 - `da-vinci pencil-session persist`
@@ -38,6 +38,8 @@ This wrapper exists to make three things mandatory:
 - serialized Pencil MCP write access
 - explicit live-to-disk persistence and sync verification
 
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, Da Vinci also runs a final style-quality review after the structural design gates pass. It becomes a blocking gate only when `DA-VINCI.md` sets `Require Supervisor Review: true`.
+
 ## First-Run Path
 
 When the project does not yet have a registered `.pen`:
@@ -89,7 +91,7 @@ Use:
 - `da-vinci pencil-lock acquire`
 - `da-vinci pencil-lock release`
 
-or prefer the session wrapper, which manages the lock for you.
+or use the session wrapper, which manages the lock for you.
 
 This prevents multiple projects from competing for the same active editor.
 
@@ -141,6 +143,41 @@ The render output cannot pass if:
 - it ignores screenshot-review findings
 - it still shows repeated schema-instability
 
+### Design-Supervisor Review
+
+When `DA-VINCI.md` declares `Design-supervisor reviewers`, run a final `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint for the currently approved anchor set.
+
+When `Require Supervisor Review: true`, missing, blocked, or unaccepted review results block broad expansion, implementation-task handoff, and terminal completion. When `Require Supervisor Review: false`, still record the review when configured, but treat it as advisory rather than completion-blocking.
+
+Use it to judge:
+
+- style quality
+- brand distinctiveness
+- cross-screen visual coherence
+- token-to-render alignment
+- whether the approved anchors are strong enough to expand or implement from
+
+Reviewers are separate from `Preferred adapters`.
+
+- adapters lead the design pass
+- reviewers judge the approved result
+
+Recommended inputs:
+
+- reviewed screenshots
+- Pencil `get_variables()` output
+- `visual-thesis.md`
+- `content-plan.md`
+- `interaction-thesis.md`
+
+Record:
+
+- reviewer names
+- review inputs
+- `PASS` / `WARN` / `BLOCK`
+- issue list
+- revision outcome
+
 ## Design-Source Gate
 
 After active Pencil work exists, Da Vinci runs `design-source checkpoint`.
@@ -198,8 +235,10 @@ Typical autonomous chain:
 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. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-6. `da-vinci audit --mode completion --change <change-id> <project-path>`
+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>`
 
 ## Flow Diagram
 
@@ -217,15 +256,24 @@ flowchart TD
     H --> F
     I --> J{Screenshot review and layout hygiene pass?}
     J -- No --> F
-    J -- Yes --> K[pencil-session persist writes live MCP snapshot back to .pen]
-    K --> L[check-pen-sync verifies live hash equals persisted hash]
-    L --> M{design-source checkpoint and runtime gate pass?}
-    M -- No --> F
-    M -- Yes --> N{More design work needed?}
-    N -- Yes --> E
-    N -- No --> O[pencil-session end releases lock]
-    O --> P[completion audit]
-    P --> Q{completion audit pass?}
-    Q -- No --> F
-    Q -- Yes --> R[design complete]
+    J -- Yes --> K{Design checkpoint pass?}
+    K -- No --> F
+    K -- Yes --> L{Design-supervisor review configured?}
+    L -- Yes --> M[Run design-supervisor review on screenshots plus theme inputs]
+    L -- No --> N[pencil-session persist writes live MCP snapshot back to .pen]
+    M --> O{Require Supervisor Review?}
+    O -- No --> N
+    O -- Yes --> P{Review PASS or accepted WARN?}
+    P -- No --> F
+    P -- Yes --> N
+    N --> Q[check-pen-sync verifies live hash equals persisted hash]
+    Q --> R{design-source checkpoint and runtime gate pass?}
+    R -- No --> F
+    R -- Yes --> S{More design work needed?}
+    S -- Yes --> E
+    S -- No --> T[pencil-session end releases lock]
+    T --> U[completion audit]
+    U --> V{completion audit pass?}
+    V -- No --> F
+    V -- Yes --> W[design complete]
 ```

package/docs/prompt-entrypoints.md

@@ -125,6 +125,9 @@ $da-vinci use intake for this existing Android project.
 I need to globally replace the UI.
 Existing code is the behavior source of truth.
 HTML references are in /abs/path/to/mockups.
+Treat the HTML directory as visual reference only, not behavior truth or final design-source 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 HTML directory actually covers and which still need to be inferred from behavior truth.
 ```
 
 Expected outcome:
@@ -159,7 +162,7 @@ Use:
 $da-vinci use intake for this existing product.
 
 This is a large overhaul, not only a UI refresh.
-Current codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, logic, and page structure while preserving selected integrations and constraints.
 Generate the best executable Da Vinci workflow prompt for the next step.
 ```

package/docs/prompt-presets/README.md

@@ -17,7 +17,7 @@ Recommended flow:
 4. copy both into your workflow setup
 5. tighten the prompt further only when the project has unusual truth sources or platform constraints
 6. when Pencil MCP is active, prefer the redesign prompts that explicitly require an MCP runtime gate plus a completion audit before terminal completion claims
-7. for project-local `.pen` persistence, prefer prompts that drive `da-vinci pencil-session begin / persist / end`; fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the wrapper cannot be used
+7. for project-local `.pen` persistence on autonomous runs, require prompts that drive `da-vinci pencil-session begin / persist / end`; fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the wrapper truly cannot be used
 
 Available presets:
 
@@ -38,6 +38,7 @@ Each scene preset should now include:
 
 - `Simple redesign`
 - `Complex redesign`
+- `Redesign with reference directory`
 - `Design-only`
 - `Continue`
 
@@ -45,7 +46,7 @@ Each scene preset should now include:
 
 These are not surface-specific redesign presets.
 
-Use them when the project already exists, but the target flows or logic are being rewritten and the old codebase should be treated as reference evidence plus migration context.
+Use them when the project already exists, but the target flows or logic are being rewritten and the old codebase should be treated as reference evidence and migration baseline.
 
 ### 1. Intake For A Broad Existing-Product Overhaul
 
@@ -59,7 +60,7 @@ Use when:
 $da-vinci use intake for this existing product.
 
 This is a broad overhaul, not only a UI refresh.
-Current codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, logic, page structure, and selected UI surfaces while preserving only the approved integrations, permissions, and constraints.
 Recommend the best Da Vinci mode and generate the best executable next-step prompt.
 ```
@@ -97,7 +98,7 @@ $da-vinci use overhaul-from-code to design the new target product surfaces from
 
 Use the existing .da-vinci/project-inventory.md, proposal.md, migration-contract.md, target specs, page-map.md, DA-VINCI.md, and design-registry.md.
 Treat the new proposal and specs as the target behavior truth.
-Treat the old codebase only as reference evidence and migration context.
+Treat the old codebase only as reference evidence and migration baseline.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 Persist project-local Pencil files under .da-vinci/designs/.
 Run the normal Pencil runtime gate and completion audit before terminal completion claims.