@xenonbyte/da-vinci-workflow 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -1,16 +1,36 @@
 # Changelog
 
-## v0.1.16 - 2026-03-28
+## 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
 - `da-vinci preflight-pencil` as a static preflight for non-trivial Pencil `batch_design` payloads, catching common syntax and schema drift before they hit MCP
 - `da-vinci write-pen` to atomically write a project-local `.pen` from MCP-readable node and variable snapshot data
-- `da-vinci snapshot-pen` to reopen an existing `.pen`, capture a fresh MCP-readable snapshot, and rewrite a canonical project-local `.pen` with reopen verification
+- `da-vinci ensure-pen` to seed or verify a registered project-local `.pen` before live editing starts
+- `da-vinci check-pen-sync` to compare a current live MCP snapshot payload against the persisted project-local `.pen`
+- `da-vinci pencil-lock` to serialize Pencil MCP write access across multiple projects on the same machine
+- `da-vinci pencil-session begin / persist / end / status` as the preferred session-level wrapper for seeded `.pen` ownership, persistence, sync checks, and lock release
+- `scripts/test-pencil-session.js` and `scripts/test-persistence-flows.js` to cover session lifecycle plus new/existing/parallel project flows
 
 ### Changed
 - active Pencil guidance now requires smaller anchor-surface batches, micro-batch fallback after repeated rollbacks, and structured screenshot-review records instead of self-affirming prose
 - design routes, prompt presets, workflow examples, and README guidance now call for `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write during active redesign work
-- project-local `.pen` persistence now treats headless interactive `save()` as non-authoritative; first-run sessions must persist the first approved live MCP snapshot, and resume sessions must overwrite the registered `.pen` from the current snapshot after material live edits
+- project-local `.pen` persistence now treats headless interactive `save()` as non-authoritative; redesign passes should seed the registered `.pen` before the first edit, then persist current live MCP snapshots back to that same path after material edits
+- `da-vinci snapshot-pen` is now documented and treated as a disk-to-disk utility only, not as a live-edit persistence step
+- completion audit now expects `.da-vinci/state/pencil-session.json` plus matching persisted snapshot hashes before completion can pass
 
 ## v0.1.15 - 2026-03-27
 

package/README.md

@@ -21,19 +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.18`
 
 Release highlights:
 
 - project-local `.pen` persistence now uses an MCP-snapshot-to-disk path instead of relying on headless interactive `save()`
+- redesign runs now seed a registered project-local `.pen` before the first Pencil edit and record persisted snapshot hashes for later sync checks
 - `da-vinci write-pen` now atomically writes workflow-owned `.pen` files from MCP-readable node and variable payloads with optional reopen verification
-- `da-vinci snapshot-pen` now rebuilds a canonical local `.pen` from an existing Pencil source and verifies reopen with Pencil
+- `da-vinci ensure-pen` now seeds or verifies a registered project-local `.pen` before live editing starts
+- `da-vinci check-pen-sync` now compares a current live MCP snapshot payload against the persisted project-local `.pen`
+- `da-vinci snapshot-pen` now serves only as a disk-to-disk utility for rebuilding an existing Pencil source and verifying reopen
 - visual-adapter execution now requires explicit runtime declaration of the resolved primary adapter and any unavailable requested adapters
 - cross-platform near-name adapters such as `frontend-skill` and `frontend-design` are now treated as distinct unless the current environment explicitly resolves them
 - complex `redesign-from-code` runs now require a visual thesis, content plan, interaction thesis, and anchor-surface structural-delta notes before broad Pencil generation
@@ -67,7 +71,7 @@ Release highlights:
 
 ## Supported workflow modes
 
-Da Vinci V2 supports four modes.
+Da Vinci currently supports five modes.
 
 ### `greenfield-spec`
 
@@ -81,6 +85,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.
@@ -222,6 +230,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
@@ -239,6 +248,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:
@@ -257,6 +268,7 @@ project/
         └── <change-id>/
             ├── brainstorm.md
             ├── design-brief.md
+            ├── migration-contract.md
             ├── proposal.md
             ├── design.md
             ├── pencil-design.md
@@ -329,6 +341,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
 - 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
@@ -447,15 +460,23 @@ During active redesign work, prefer running `da-vinci audit --mode integrity <pr
 
 Project-local `.pen` persistence now has two supported paths:
 
-- first-run path: if no registered project-local `.pen` exists yet, let the first approved anchor surface happen in the live editor, then persist that approved MCP snapshot under `.da-vinci/designs/`
-- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it
+- 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`
 
 Persistence helpers:
 
+- preferred wrapper:
+  - `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>`
+- `da-vinci ensure-pen --output <path> --verify-open`
 - `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
-- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`
+- `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open` (disk-to-disk only)
+- `da-vinci pencil-lock acquire --project <project-path>` / `da-vinci pencil-lock release --project <project-path>`
 
 Do not treat headless interactive `save()` as authoritative persistence truth until the underlying Pencil behavior is proven reliable again.
+Completion audit now also expects `.da-vinci/state/pencil-session.json` to reflect the latest persisted `.pen` hash, so autonomous runs should prefer the `pencil-session` wrapper.
 
 Installation targets:
 
@@ -551,6 +572,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,13 +603,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/`
@@ -594,8 +633,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,19 +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.18`
 
 已发布版本重点：
 
 - 项目内 `.pen` 持久化现在改为“从 MCP 快照写回磁盘”的正式路径，不再依赖 headless interactive `save()`
+- 重设计流程现在要求在第一次 Pencil 编辑前先 seed 一个登记好的项目内 `.pen`，并记录后续持久化快照 hash 以便做同步校验
 - `da-vinci write-pen` 现在可以把 MCP 可读的节点和变量快照原子写成工作流管理的 `.pen` 文件，并可选地做 reopen 校验
-- `da-vinci snapshot-pen` 现在可以从现有 Pencil 源重建一个规范化的本地 `.pen`，并验证重新打开结果
+- `da-vinci ensure-pen` 现在可以在 live 编辑开始前 seed 或校验登记好的项目内 `.pen`
+- `da-vinci check-pen-sync` 现在可以把当前 live MCP 快照和已持久化的项目内 `.pen` 做同步比对
+- `da-vinci snapshot-pen` 现在只作为 disk-to-disk 工具，用来从已有 Pencil 源重建规范化 `.pen` 并验证重新打开结果
 - visual adapter 的执行现在要求在运行时明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
 - `frontend-skill`、`frontend-design` 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
 - 复杂 `redesign-from-code` 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
@@ -69,7 +73,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 ## 支持的工作流模式
 
-Da Vinci V2 支持四种模式：
+Da Vinci 当前支持五种模式：
 
 ### `greenfield-spec`
 
@@ -83,6 +87,10 @@ Da Vinci V2 支持四种模式：
 
 已有项目，代码和行为已存在，目标是做广泛或全局的 UI 重设计。
 
+### `overhaul-from-code`
+
+已有项目，但目标是做系统级大改版；现有代码仍然是迁移基线和参考证据，但不再天然等于新版本的最终行为真相。
+
 ### `feature-change`
 
 已有项目，只做某个功能、页面、流程的局部修改。
@@ -227,6 +235,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`：页面、职责、状态和共享区域
@@ -256,6 +265,7 @@ project/
         └── <change-id>/
             ├── brainstorm.md
             ├── design-brief.md
+            ├── migration-contract.md
             ├── proposal.md
             ├── design.md
             ├── pencil-design.md
@@ -281,6 +291,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 文档
@@ -376,16 +387,23 @@ da-vinci uninstall --platform codex,claude,gemini
 
 项目内 `.pen` 持久化现在分成两条受支持路径：
 
-- 首次运行路径：如果当前还没有登记的项目内 `.pen`，先允许第一个通过审查的 anchor surface 在 live editor 里完成，然后把这个 MCP 快照持久化到 `.da-vinci/designs/`
-- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 MCP 快照重新持久化回同一路径，而不是假设 interactive `save()` 已经刷回磁盘
+- 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
+- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
 
 推荐使用的持久化命令：
 
+- 优先使用封装好的 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>`
+- `da-vinci ensure-pen --output <path> --verify-open`
 - `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
-- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`
+- `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`（仅限 disk-to-disk）
+- `da-vinci pencil-lock acquire --project <project-path>` / `da-vinci pencil-lock release --project <project-path>`
 
 在 Pencil 底层 `save()` 语义再次被证明可靠之前，不要把 headless interactive `save()` 当作权威持久化真相。
-在重设计进行中，建议在第一次成功写入 Pencil 后立刻跑一次 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚两次，就配合 `da-vinci preflight-pencil` 改成更小的后续批次。
+completion audit 现在还会检查 `.da-vinci/state/pencil-session.json` 是否记录了最新的 `.pen` hash，所以自治运行优先走 `pencil-session` 封装。
 
 安装目标：
 
@@ -464,6 +482,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
@@ -489,14 +513,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`
@@ -506,8 +542,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 default final 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,12 +253,21 @@ 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
-- when no registered project-local `.pen` exists yet, let the first anchor work happen in the live editor, then persist the first complete MCP snapshot to the registered `.pen` path before broad expansion continues
-- when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming live edits were flushed automatically
+- prefer the session wrapper commands:
+  `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>`
+- before the first Pencil edit on a redesign pass, begin a Pencil session so the registered project-local `.pen` exists before editing and the global Pencil lock is held for that project
+- acquire the global Pencil lock before MCP write operations on a project and release it after the write phase so two projects do not compete for the same active editor
+- when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically
+- `da-vinci snapshot-pen` is a disk-to-disk utility for rebuilding an existing `.pen`; do not use it as live-edit persistence
 - use `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open` to atomically write the registered project-local `.pen` from MCP snapshot data
+- after writing the project-local `.pen`, run `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>` before treating the disk source as current
+- completion audit expects a recorded Pencil session state under `.da-vinci/state/pencil-session.json`; do not bypass the session wrapper on autonomous runs
 - after the first successful Pencil write, verify that the registered project-local `.pen` path exists as a shell-visible file before treating the design source as persistent
 - after the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` when shell access is available before broad expansion continues
 - after the first successful Pencil write, run the MCP runtime gate when Pencil MCP is available and record the result in `pencil-design.md`
+- if the workflow already has a registered `.pen`, do not send Pencil write operations with an empty `filePath`
 - do not treat an unnamed live editor such as `new` as a persisted project design source; reconcile it to the registered project-local `.pen` path before the design pass is considered traceable
 - use only Pencil-supported properties; do not emit web- or CSS-only layout properties such as `flex` or `margin`
 - if unsupported Pencil properties cause repeated rolled-back batches on the same anchor surface, treat that pass as unstable and fix the schema usage before expanding further
@@ -369,6 +402,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`
@@ -396,6 +435,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 default final 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.
@@ -429,6 +477,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.
@@ -689,3 +755,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,8 +20,9 @@ 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.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+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.
+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.

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

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

@@ -14,8 +14,9 @@ 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.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+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.
+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.

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

@@ -24,4 +24,5 @@ Output should include:
 Route discipline:
 - do not default the user into `/prompts:dv-build`
 - `intake` should usually produce a main workflow prompt, not a build-only prompt
-- prefer `redesign-from-code` or `feature-change` when the request starts from an existing project
+- 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/gemini/da-vinci.toml

@@ -24,6 +24,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/gemini/dv/continue.toml

@@ -20,5 +20,7 @@ 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/gemini/dv/design.toml

@@ -13,8 +13,9 @@ 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.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+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.
+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.

package/commands/gemini/dv/intake.toml

@@ -23,4 +23,6 @@ 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
 """