@xenonbyte/da-vinci-workflow 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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
+- `overhaul-from-code` as a fifth workflow mode for broad existing-product rewrites where the current codebase remains migration evidence, but new `proposal.md` and `specs/` become the target behavior truth
+- `migration-contract.md` as a first-class change artifact for preserve / revise / retire / unknown decisions in overhaul work
+- `docs/dv-command-reference.md` and `docs/zh-CN/dv-command-reference.md` to explain route responsibilities, stateful next-step recommendations, and verify rollback behavior
+
+### Changed
+- intake, mode guides, prompt recipes, workflow examples, and natural-language usage now distinguish `overhaul-from-code` from `redesign-from-code` instead of forcing large product rewrites into UI-only redesign semantics
+- workflow, checkpoint, and design-input guidance now require overhaul runs to stabilize `proposal.md`, `migration-contract.md`, target `specs/`, and `page-map.md` before broad Pencil generation
+- visual-adapter and Pencil design guidance now explain how `overhaul-from-code` keeps current code as reference evidence while using the new truth sources to drive design and implementation
+- prompt preset docs now include dedicated `overhaul-from-code` intake, breakdown, design, and continue templates for mobile, desktop, web, and tablet surfaces
+- page-mapping, checkpoint, and command-reference docs now explain how to recover when bindings still exist but either implementation or the design source is missing
+
 ## v0.1.17 - 2026-03-28
 
 ### Added

package/README.md

@@ -21,16 +21,23 @@ This workflow is intended for:
 - 0-to-1 product delivery
 - brainstorm-to-product delivery
 - redesign from existing code
+- large existing-product overhauls where flows and logic also change
 - scoped feature delivery on an existing product
 
 ## Current release
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.16`
+- `@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
@@ -70,7 +77,7 @@ Release highlights:
 
 ## Supported workflow modes
 
-Da Vinci V2 supports four modes.
+Da Vinci currently supports five modes.
 
 ### `greenfield-spec`
 
@@ -84,6 +91,10 @@ Use when the project is new but the inputs come from multiple rounds of rough pr
 
 Use when an existing project already has routes, pages, and UI, and the goal is a broad redesign or UI replacement.
 
+### `overhaul-from-code`
+
+Use when an existing project is undergoing a broad system-level rewrite and current code is still valuable as migration evidence, but no longer the complete target behavior truth.
+
 ### `feature-change`
 
 Use when an existing product needs a scoped requirement change, page addition, or page update.
@@ -119,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
@@ -129,6 +151,8 @@ Recommended default:
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 Use this when:
@@ -144,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
@@ -155,6 +190,8 @@ Quality-first redesign configuration:
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - true
 ```
 
 Use this when:
@@ -182,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
@@ -225,6 +265,7 @@ Depending on the mode, the workflow may use these artifacts:
 - `project-inventory.md`: current routes, pages, and UI patterns from an existing codebase
 - `DA-VINCI.md`: project-level visual contract for theme, palette, typography direction, component tone, and page-consistency rules
 - `design-brief.md`: form factor, style, density, brand constraints, and layout preferences
+- `migration-contract.md`: preserve / revise / retire / unknown boundaries for existing-system overhaul work
 - `design-registry.md`: project-level `.pen` source inventory
 - `.da-vinci/designs/`: project-local persisted Pencil sources such as `project-baseline.pen` or change-specific `.pen` files
 - `page-map.md`: canonical page list and page responsibilities
@@ -242,6 +283,8 @@ Use specs as capability or redesign-slice boundaries, not as page counters.
 
 For broad `redesign-from-code` work, prefer multiple `specs/<slice>/spec.md` files over one oversized `ui-refresh/spec.md`.
 
+For broad `overhaul-from-code` work, prefer multiple `specs/<slice>/spec.md` files plus one `migration-contract.md` over one oversized rewrite spec that mixes preserved and retired system behavior.
+
 ## Artifact placement
 
 Recommended project layout:
@@ -260,6 +303,7 @@ project/
         └── <change-id>/
             ├── brainstorm.md
             ├── design-brief.md
+            ├── migration-contract.md
             ├── proposal.md
             ├── design.md
             ├── pencil-design.md
@@ -332,6 +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 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
@@ -446,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>`
@@ -562,6 +609,12 @@ $da-vinci use greenfield-brainstorm to turn several product ideas into a page ma
 $da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan
 ```
 
+### Overhaul from code
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and generate a Pencil-backed overhaul plan
+```
+
 ### Feature change
 
 ```text
@@ -576,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
@@ -587,13 +641,25 @@ Use the existing Da Vinci artifacts.
 Continue into full-delivery.
 ```
 
+### Continue after overhaul planning
+
+```text
+$da-vinci use continue for this existing overhaul-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue from proposal, migration-contract, and target specs into design or implementation.
+```
+
 ## Workflow examples
 
 See:
 
 - `docs/prompt-entrypoints.md`
+- `docs/dv-command-reference.md`
 - `docs/prompt-presets/`
   - includes `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue` variants in each surface file
+- `docs/workflow-overview.md`
+- `docs/pencil-rendering-workflow.md`
 - `docs/codex-natural-language-usage.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
@@ -605,8 +671,11 @@ See:
 Chinese companion documents are included in this repository:
 
 - `README.zh-CN.md`
+- `docs/zh-CN/dv-command-reference.md`
 - `docs/zh-CN/prompt-presets/`
   - each surface file also includes `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue`
+- `docs/zh-CN/workflow-overview.md`
+- `docs/zh-CN/pencil-rendering-workflow.md`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/README.zh-CN.md

@@ -23,16 +23,23 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 - 0 到 1 的产品交付
 - 从 brainstorming 走向可实施产品
 - 基于现有代码做全局 UI 重设计
+- 基于现有代码做流程、逻辑和 UI 一起变化的大改版
 - 在现有产品上做范围明确的 feature-change
 
 ## 当前发布状态
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.16`
+- `@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 校验
@@ -72,7 +79,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 ## 支持的工作流模式
 
-Da Vinci V2 支持四种模式：
+Da Vinci 当前支持五种模式：
 
 ### `greenfield-spec`
 
@@ -86,6 +93,10 @@ Da Vinci V2 支持四种模式：
 
 已有项目，代码和行为已存在，目标是做广泛或全局的 UI 重设计。
 
+### `overhaul-from-code`
+
+已有项目，但目标是做系统级大改版；现有代码是参考证据和迁移基线，不是新系统最终行为真相。
+
 ### `feature-change`
 
 已有项目，只做某个功能、页面、流程的局部修改。
@@ -124,6 +135,17 @@ Da Vinci V2 支持四种模式：
 - 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 +156,8 @@ Da Vinci V2 支持四种模式：
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 适用场景：
@@ -149,6 +173,17 @@ Da Vinci V2 支持四种模式：
 - 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 +195,8 @@ Da Vinci V2 支持四种模式：
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - true
 ```
 
 适用场景：
@@ -187,6 +224,9 @@ Da Vinci V2 支持四种模式：
 - 只使用 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
 
 ## 核心工作流顺序
@@ -230,6 +270,7 @@ Da Vinci 的默认顺序是：
 - `project-inventory.md`：现有代码库里的路由、页面、UI 结构盘点
 - `DA-VINCI.md`：项目级视觉契约
 - `design-brief.md`：设计方向、形态、密度、品牌和限制条件
+- `migration-contract.md`：存量系统在大改版中哪些保留、修改、废弃、待确认的边界
 - `design-registry.md`：项目级 `.pen` 设计源登记
 - `.da-vinci/designs/`：项目内持久化的 Pencil 设计源，例如 `project-baseline.pen` 或按 change 保存的 `.pen` 文件
 - `page-map.md`：页面、职责、状态和共享区域
@@ -259,6 +300,7 @@ project/
         └── <change-id>/
             ├── brainstorm.md
             ├── design-brief.md
+            ├── migration-contract.md
             ├── proposal.md
             ├── design.md
             ├── pencil-design.md
@@ -284,6 +326,7 @@ project/
 - `page-map.md` 是实现页面和状态的真相源
 - `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
 - 在 `redesign-from-code` 里，现有代码只是真相行为，不是真相布局
+- 在 `overhaul-from-code` 里，现有代码是参考证据和迁移基线，不是新系统最终行为真相
 - 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
 - `design-registry.md` 里登记的首选 `.pen` 路径属于工作流自动维护的状态，不应该依赖用户手工填写
 - 一旦进入 Pencil 设计，Da Vinci 应该使用或创建这个项目内 `.pen` 路径，而不是继续沿用当前随手打开的 Pencil 文档
@@ -375,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>`
@@ -474,6 +519,12 @@ $da-vinci use greenfield-brainstorm to turn several product ideas into a page ma
 $da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan
 ```
 
+### Overhaul from code
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and generate a Pencil-backed overhaul plan
+```
+
 ### Feature change
 
 ```text
@@ -488,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.
 ```
 
 ### 已有工件后继续推进
@@ -499,14 +551,26 @@ Use the existing Da Vinci artifacts.
 Continue into full-delivery.
 ```
 
+### 大改版场景继续推进
+
+```text
+$da-vinci use continue for this existing overhaul-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue from proposal, migration-contract, and target specs into design or implementation.
+```
+
 ## 文档导航
 
 英文文档：
 
 - `docs/codex-natural-language-usage.md`
+- `docs/dv-command-reference.md`
 - `docs/prompt-entrypoints.md`
 - `docs/prompt-presets/`
   - 每个场景文件都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
+- `docs/workflow-overview.md`
+- `docs/pencil-rendering-workflow.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
@@ -516,8 +580,11 @@ Continue into full-delivery.
 中文文档：
 
 - `README.zh-CN.md`
+- `docs/zh-CN/dv-command-reference.md`
 - `docs/zh-CN/prompt-presets/`
   - 每个场景文件也都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
+- `docs/zh-CN/workflow-overview.md`
+- `docs/zh-CN/pencil-rendering-workflow.md`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/SKILL.md

@@ -16,6 +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 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
@@ -75,6 +76,25 @@ Do not stop merely because:
 
 Those are warnings unless they prevent safe implementation of the current in-scope work.
 
+## Next-Step Recommendation Discipline
+
+When Da Vinci reports a "next recommended step" or offers route suggestions, make the recommendation stateful rather than listing every possible command as if they were equally valid.
+
+Use this order:
+
+- if discovery or design-source artifacts are still missing, recommend the missing discovery or design work first
+- if design is still blocking, recommend `design`
+- if design is ready enough for implementation planning but `.da-vinci/changes/<change-id>/tasks.md` does not exist yet, recommend `tasks`
+- if `tasks.md` exists and `task checkpoint` is at least `PASS` or an explicitly accepted `WARN`, recommend `build`
+- if implementation is already underway or complete enough to check drift, recommend `verify`
+
+Hard rules:
+
+- do not present `build` as a co-equal next step when `tasks.md` does not exist yet
+- do not present `build` as the primary next step immediately after design completion unless task generation is already done and implementation readiness is clear
+- if design is complete but more in-scope surfaces still need design work, `design` may remain an optional branch, but `tasks` stays the primary next step before `build`
+- if multiple commands are shown, clearly mark only one as the primary next step for the current workflow state
+
 ## Invocation Model
 
 Canonical workflow name is `da-vinci`.
@@ -134,7 +154,10 @@ Supported modes:
 3. `redesign-from-code`
    - use when an existing product already has code and the UI must be redesigned globally or broadly
 
-4. `feature-change`
+4. `overhaul-from-code`
+   - use when an existing product needs a broad system-level rewrite where flows, logic, information architecture, and UI may all change
+
+5. `feature-change`
    - use when an existing product needs a scoped requirement change, page addition, or page update
 
 If the user does not specify a mode:
@@ -142,6 +165,7 @@ If the user does not specify a mode:
 - choose `greenfield-spec` for new projects with clear requirements
 - choose `greenfield-brainstorm` for exploratory new product ideation
 - choose `redesign-from-code` for broad UI replacement on existing code
+- choose `overhaul-from-code` for broad existing-project rewrites where old code is no longer the full behavior truth
 - choose `feature-change` for incremental product work
 
 ## Design Input Collection
@@ -229,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>`
@@ -253,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
 
@@ -378,6 +406,12 @@ Use these minimum flows:
 
 For broad refreshes, treat `.da-vinci/changes/<change-id>/specs/` as a redesign-slice directory, not as a single-file location.
 
+### `overhaul-from-code`
+
+`.da-vinci/project-inventory` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/migration-contract` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` -> `.da-vinci/changes/<change-id>/pencil-bindings` -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
+
+For broad overhauls, treat `.da-vinci/changes/<change-id>/specs/` as an overhaul-slice directory and keep `migration-contract.md` singular for preserve/revise/retire decisions.
+
 ### `feature-change`
 
 `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` for affected pages -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` delta -> `.da-vinci/changes/<change-id>/pencil-bindings` delta -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
@@ -405,6 +439,15 @@ If the active mode is `redesign-from-code`:
 - default to fresh visual composition unless the user explicitly asks to preserve the current layout skeleton
 - partition specs by redesign slice when one oversized `ui-refresh` spec would hide important implementation boundaries
 
+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 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
+- route verify failures back to `migration-contract.md`, `page-map.md`, or specs when overhaul truth is still unstable
+
 ## Spec Partitioning Rules
 
 Do not default to one oversized `ui-refresh` spec for broad redesign work.
@@ -438,6 +481,24 @@ One redesign spec is acceptable when the refresh is mostly cosmetic, narrow, or
 
 Do not split page-by-page unless the product is unusually fragmented. Prefer implementable redesign slices over raw page counts.
 
+For `overhaul-from-code`:
+
+- keep one overall `proposal.md`
+- keep one `migration-contract.md`
+- keep one project-level `DA-VINCI.md`
+- keep one project-level `project-inventory.md`
+- keep one project-level `design-registry.md`
+- keep one project-level `page-map.md`
+- split `specs/` by overhaul slice when the rewrite spans multiple implementation or migration boundaries
+
+Preferred overhaul slices:
+
+- `shell-and-navigation`
+- `core-flows`
+- `account-and-settings`
+- `legacy-migration`
+- `admin-or-restricted`
+
 ## Design Source Rules
 
 Use `design-registry.md` as the project-level inventory of `.pen` sources.
@@ -698,3 +759,4 @@ After meaningful work, report:
 5. blockers or drift
 
 Keep updates concise and operational.
+Make `next recommended step` follow the state rules above; do not list `build` next to `tasks` as if they were equivalent when task generation has not happened yet.

package/commands/claude/da-vinci.md

@@ -22,6 +22,7 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
+- After design but before `tasks.md` exists, prefer `/dv:tasks` as the next route; treat `/dv:build` as implementation-ready only.
 - If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
 - Keep `.da-vinci/designs/` reserved for `.pen` files only.
 - On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.

package/commands/claude/dv/continue.md

@@ -21,4 +21,6 @@ Output should include:
 Route discipline:
 - do not restart discovery if the current artifacts already contain enough truth
 - 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
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

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

@@ -24,3 +24,5 @@ Output should include:
 Route discipline:
 - do not default the user into `/dv:build`
 - `intake` should usually produce a main workflow prompt, not a build-only prompt
+- prefer `redesign-from-code`, `overhaul-from-code`, or `feature-change` when the request starts from an existing project
+- prefer `overhaul-from-code` when an existing project is redefining flows or logic rather than only replacing UI

package/commands/codex/prompts/da-vinci.md

@@ -21,6 +21,7 @@ Available routes:
 
 Important:
 - Treat `/prompts:*` as action selectors in Codex.
+- After design but before `tasks.md` exists, prefer `/prompts:dv-tasks` as the next route; treat `/prompts:dv-build` as implementation-ready only.
 - If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
 - Keep `.da-vinci/designs/` reserved for `.pen` files only.
 - On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.

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

@@ -21,4 +21,6 @@ Output should include:
 Route discipline:
 - do not restart discovery if the current artifacts already contain enough truth
 - 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
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine