@xenonbyte/da-vinci-workflow 0.1.17 → 0.1.19

package/docs/pencil-rendering-workflow.md

@@ -0,0 +1,279 @@
+# Pencil Rendering Workflow
+
+This document describes the dedicated Pencil rendering lifecycle inside Da Vinci.
+
+Use it when you need the exact rules for:
+
+- seeding a project-local `.pen`
+- editing through Pencil MCP
+- persisting live changes
+- screenshot review
+- runtime gates and filesystem audits
+
+Use [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/dv-command-reference.md) when you need the route-level `dv:` command sequence and rollback behavior across `design`, `tasks`, `build`, and `verify`.
+
+## Rendering Truth Model
+
+Da Vinci treats these as distinct sources:
+
+- live truth: the current Pencil MCP editor
+- disk truth: the registered project-local `.pen`
+- review truth: screenshot exports under `.da-vinci/changes/<change-id>/exports/`
+
+PNG exports are review artifacts only. They are not the design source of truth.
+
+`.da-vinci/designs/` is reserved for `.pen` files only.
+
+## Session Model
+
+Da Vinci now requires the session wrapper on autonomous runs:
+
+- `da-vinci pencil-session begin`
+- `da-vinci pencil-session persist`
+- `da-vinci pencil-session end`
+
+This wrapper exists to make three things mandatory:
+
+- seeded `.pen` ownership
+- 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`:
+
+1. Begin a Pencil session.
+2. Seed the registered project-local `.pen`.
+3. Acquire the global Pencil lock.
+4. Open that exact `.pen` path.
+5. Start Pencil edits.
+
+The workflow should not begin anchor rendering in `new`.
+
+## Resume Path
+
+When the project already has a registered `.pen`:
+
+1. Begin a Pencil session against the existing path.
+2. Reopen that exact `.pen` for continuity.
+3. Perform live MCP edits.
+4. Persist a fresh MCP snapshot back to the same path after material edits.
+
+Da Vinci does not assume live MCP edits were flushed automatically.
+
+## Persistence Rule
+
+Da Vinci does not treat headless interactive `save()` as authoritative persistence truth.
+
+Instead, the persistence step is:
+
+1. read MCP-readable node snapshot data
+2. read MCP-readable variable snapshot data
+3. write the project-local `.pen`
+4. reopen-verify it
+5. compare live snapshot and persisted snapshot hashes
+
+Relevant commands:
+
+- `da-vinci write-pen`
+- `da-vinci check-pen-sync`
+
+`da-vinci snapshot-pen` is disk-to-disk only. It is not the live-edit persistence path.
+
+## Locking Rule
+
+Pencil MCP writes are serialized by a global lock.
+
+Use:
+
+- `da-vinci pencil-lock acquire`
+- `da-vinci pencil-lock release`
+
+or use the session wrapper, which manages the lock for you.
+
+This prevents multiple projects from competing for the same active editor.
+
+## Batch Discipline
+
+Before writing non-trivial `batch_design` payloads:
+
+- run `da-vinci preflight-pencil --ops-file <path>` when shell access is available
+- keep anchor batches small
+- prefer 12 or fewer operations on anchor surfaces
+- if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations
+
+Repeated schema rollbacks are not acceptable forward progress.
+
+## Review Gates
+
+### Screenshot Review
+
+Each approved surface needs explicit screenshot review:
+
+- `PASS`
+- `WARN`
+- `BLOCK`
+
+Each review record must include:
+
+- issue list
+- revision outcome
+
+Self-affirming prose such as "looks good" does not count.
+
+### Layout Hygiene
+
+Each reviewed surface must also satisfy the active form-factor-specific layout-hygiene profile:
+
+- mobile
+- tablet
+- desktop
+- web
+
+This is separate from `Visual Assist`.
+
+### Design Checkpoint
+
+The render output cannot pass if:
+
+- it is a skin-swap
+- it is mostly placeholder scaffolding
+- 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`.
+
+It verifies:
+
+- `design-registry.md` points to one specific `.pen`
+- the active editor matches that `.pen`
+- the shell-visible file exists
+- the registered `.pen` is not still only in memory
+- `.da-vinci/designs/` is not polluted by markdown or PNG files
+
+## MCP Runtime Gate
+
+When Pencil MCP is active, Da Vinci records a runtime gate result in `pencil-design.md`.
+
+It verifies:
+
+- the active editor is not `new`
+- the workflow is not using empty `filePath` after registration
+- claimed anchor ids exist in the active editor
+- reviewed screenshot targets exist in the active editor
+- live snapshot hash matches the persisted snapshot hash at completion stage
+
+## Filesystem Audits
+
+### Integrity Audit
+
+Run during active work:
+
+```text
+da-vinci audit --mode integrity <project-path>
+```
+
+Recommended timing:
+
+- immediately after the first successful Pencil write
+- before broad expansion beyond approved anchor surfaces
+
+### Completion Audit
+
+Run before any terminal completion claim:
+
+```text
+da-vinci audit --mode completion --change <change-id> <project-path>
+```
+
+This audit now also expects `.da-vinci/state/pencil-session.json` to reflect the latest persisted `.pen` hash.
+
+## Preferred Command Chain
+
+Typical autonomous chain:
+
+1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
+2. Pencil MCP edits
+3. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+4. screenshot review + layout hygiene
+5. design checkpoint
+6. design-supervisor review when configured
+7. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+8. `da-vinci audit --mode completion --change <change-id> <project-path>`
+
+## Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Start Pencil work] --> B{Registered .pen exists?}
+    B -- No --> C[pencil-session begin seeds .pen and acquires global lock]
+    B -- Yes --> D[pencil-session begin reopens existing .pen and acquires global lock]
+    C --> E[Preflight non-trivial batch_design payloads]
+    D --> E
+    E --> F[Render or update anchor surface]
+    F --> G{Batch rolled back twice?}
+    G -- Yes --> H[Switch to micro-batches of 6 or fewer ops]
+    G -- No --> I[Capture screenshot and review]
+    H --> F
+    I --> J{Screenshot review and layout hygiene pass?}
+    J -- No --> F
+    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

@@ -74,6 +74,11 @@ Do not default this sequence to `build`.
 
 `build` is still valid, but it is an expert route for workflows that are already implementation-ready.
 
+State rule:
+
+- if design is done but `tasks.md` does not exist yet, the next recommended route should usually be `tasks`, not `build`
+- only recommend `build` as the primary next step once tasks and implementation readiness are already clear
+
 ## Platform Syntax
 
 For ready-to-copy surface-specific starting prompts, see:
@@ -120,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:
@@ -146,6 +154,26 @@ Expected outcome:
 - identified next safe stage
 - one executable continuation prompt
 
+## Example: Existing Product With Flow And Logic Overhaul
+
+Use:
+
+```text
+$da-vinci use intake for this existing product.
+
+This is a large overhaul, not only a UI refresh.
+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.
+```
+
+Expected outcome:
+
+- recommended mode: `overhaul-from-code`
+- one executable main workflow prompt
+- one more conservative planning-first prompt
+- one continuation prompt for later resume
+
 ## Design Rule
 
 These routes are workflow-entry helpers.

package/docs/prompt-presets/README.md

@@ -2,6 +2,9 @@
 
 Use these presets when you want a copy-ready starting prompt for a specific product surface.
 
+These presets primarily target screen-design work once the workflow mode is already clear.
+For broad existing-product rewrites where flows or logic are also changing, prefer `overhaul-from-code` plus `intake`/custom prompt setup first, then reuse the relevant design-oriented preset after `proposal.md`, `migration-contract.md`, and target `specs/` stabilize.
+
 These presets are designed to pair with:
 
 - `docs/visual-assist-presets/`
@@ -14,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:
 
@@ -35,5 +38,83 @@ Each scene preset should now include:
 
 - `Simple redesign`
 - `Complex redesign`
+- `Redesign with reference directory`
 - `Design-only`
 - `Continue`
+
+## `overhaul-from-code` Prompt Templates
+
+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 and migration baseline.
+
+### 1. Intake For A Broad Existing-Product Overhaul
+
+Use when:
+
+- the repo already exists
+- the user knows a large rewrite is needed
+- the new target behavior is not yet stabilized
+
+```text
+$da-vinci use intake for this existing product.
+
+This is a broad overhaul, not only a UI refresh.
+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.
+```
+
+### 2. Breakdown / Spec Stabilization For `overhaul-from-code`
+
+Use when:
+
+- the mode is already clear
+- you need to inventory the old system and define migration boundaries before design
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire/unknown boundaries, and stabilize the new target requirements before broad design.
+
+Current codebase is reference evidence and migration baseline, not the final target behavior truth.
+Create or update:
+- .da-vinci/project-inventory.md
+- .da-vinci/changes/<change-id>/proposal.md
+- .da-vinci/changes/<change-id>/migration-contract.md
+- .da-vinci/changes/<change-id>/specs/
+- .da-vinci/page-map.md
+
+Do not start broad Pencil work until the new proposal, migration contract, target specs, and page map are stable enough to drive design.
+```
+
+### 3. Design Handoff After Overhaul Specs Stabilize
+
+Use when:
+
+- `proposal.md`, `migration-contract.md`, target `specs/`, and `page-map.md` already exist
+- you are ready to produce Pencil-backed overhaul pages
+
+```text
+$da-vinci use overhaul-from-code to design the new target product surfaces from the approved overhaul artifacts.
+
+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 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.
+```
+
+### 4. Continue An Existing `overhaul-from-code` Workflow
+
+Use when:
+
+- the repo already has overhaul artifacts
+- the workflow needs to resume from the current truth state
+
+```text
+$da-vinci use continue for this existing overhaul-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Detect whether the workflow should return to breakdown, continue with design, generate tasks, continue implementation, or verify drift.
+Prefer the artifact-backed next safe stage instead of restarting the overhaul from scratch.
+```

package/docs/prompt-presets/desktop-app.md

@@ -2,6 +2,9 @@
 
 Recommended when the product is a desktop-first tool or workspace.
 
+These prompt variants are primarily for design-heavy `redesign-from-code` work after the workflow mode is already clear.
+If the active mode is `overhaul-from-code`, first stabilize `proposal.md`, `migration-contract.md`, and target `specs/`, then adapt the relevant preset instead of treating it as a direct drop-in.
+
 Pair with:
 
 - `docs/visual-assist-presets/desktop-app.md`
@@ -16,9 +19,65 @@ Use this when the workflow needs:
 
 - Use `Simple redesign` when the desktop surface is narrow, mostly single-workspace, or has limited state branching.
 - Use `Complex redesign` when the product has multiple workspaces, side panels, overlays, inspectors, or materially different states.
+- Use `Redesign with reference directory` when you have a local HTML or mockup directory that should guide desktop composition as a visual reference only.
 - Use `Design-only` when you want the design chain and task readiness without code changes yet.
 - Use `Continue` when the workflow already created artifacts and needs to resume.
 
+## Overhaul From Code
+
+Use these templates when the desktop product already exists, but workspace model, flow logic, navigation, or information architecture are being rewritten rather than only visually refreshed.
+
+### Overhaul Intake
+
+```text
+$da-vinci use intake for this existing desktop product.
+
+This is a broad overhaul, not only a UI refresh.
+Current desktop codebase is reference evidence and migration baseline, not the final target behavior truth.
+We need to redefine flows, workspace structure, interaction model, and selected UI surfaces while preserving only approved integrations, permissions, and constraints.
+Recommend the best Da Vinci mode and generate the best executable next-step prompt.
+```
+
+### Overhaul Breakdown
+
+```text
+$da-vinci use overhaul-from-code to inventory the current desktop product, define preserve/revise/retire/unknown boundaries, and stabilize the new target requirements before broad design.
+
+Current desktop codebase is reference evidence and migration baseline, not the final target behavior truth.
+Create or update:
+- .da-vinci/project-inventory.md
+- .da-vinci/changes/<change-id>/proposal.md
+- .da-vinci/changes/<change-id>/migration-contract.md
+- .da-vinci/changes/<change-id>/specs/
+- .da-vinci/page-map.md
+
+Inventory workspaces, side panels, inspectors, dialogs, overlays, and materially different states before broad Pencil work.
+Do not start broad Pencil work until the new proposal, migration contract, target specs, and page map are stable enough to drive design.
+```
+
+### Overhaul Design
+
+```text
+$da-vinci use overhaul-from-code to design the new target desktop surfaces from the approved overhaul artifacts.
+
+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 desktop 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.
+```
+
+### Overhaul Continue
+
+```text
+$da-vinci use continue for this existing overhaul-from-code desktop workflow.
+
+Use the existing Da Vinci artifacts.
+Detect whether the workflow should return to breakdown, continue with design, generate tasks, continue implementation, or verify drift.
+Prefer the artifact-backed next safe stage instead of restarting the overhaul from scratch.
+```
+
 ## Simple Redesign
 
 ```text
@@ -26,9 +85,11 @@ $da-vinci use redesign-from-code to redesign this existing desktop product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after discovery, anchor surfaces, phase summaries, or task generation; continue through tasks, build, and verify once the corresponding checkpoints pass.
 Inventory the current workspaces, dialogs, overlays, and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+Before the first Pencil edit, require `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not pass design checkpoint if the result is just a boxed-up recolor of the old UI or if workspace hierarchy remains unclear.
@@ -42,6 +103,8 @@ $da-vinci use redesign-from-code to redesign this existing desktop product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after discovery, anchor surfaces, phase summaries, or task generation; continue through tasks, build, and verify once the corresponding checkpoints pass.
 Inventory primary workspaces, side panels, inspectors, dialogs, settings flows, overlays, and materially different states before broad Pencil work.
 Decompose complex screens into primary surfaces, secondary surfaces, overlays, and implementation surfaces.
 Create the required discovery and design-source artifacts in their standard locations before the first anchor surface.
@@ -55,15 +118,48 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Run `da-vinci audit --mode integrity <project-path>` after the first successful Pencil write 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`.
-Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
+If `DA-VINCI.md` configures `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, using screenshots plus Pencil variables and the design theses as inputs. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
 Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not pass design checkpoint if the result is a repeated placeholder scaffold, flat panel soup, or a recolor of the old desktop shell.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+## Redesign With Reference Directory
+
+```text
+$da-vinci use redesign-from-code to redesign this existing desktop product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
+Treat this as full-delivery unless explicitly changed.
+Do not stop after discovery, anchor surfaces, phase summaries, or task generation; continue through tasks, build, and verify once the corresponding checkpoints pass.
+
+Use <reference-directory> as the local HTML design-reference directory.
+Treat that directory as visual reference material only, not as behavior truth, workspace truth, or final design-source truth.
+Inventory which workspaces, side panels, inspectors, dialogs, overlays, and materially different states are covered by the reference directory and which are not before broad Pencil work begins.
+For uncovered states or surfaces, derive the design from the approved anchor surfaces, the project visual contract, and the existing behavior truth.
+
+If browser access is available, open the HTML reference screens in a real browser and wait 3-5 seconds, or until the visual state settles, before judging hierarchy, spacing, styling, or component treatment.
+Do not review the initial unhydrated or partially rendered state.
+If a reference screen visibly changes after load, use the settled state as the visual reference baseline and record that delayed settling was required.
+
+Use the HTML reference screens only as composition and styling input where they are relevant and stable.
+Do not mechanically clone them when they conflict with behavior truth, missing states, or implementation reality.
+
+Design 1-3 anchor surfaces first, review screenshots, then expand.
+For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
+
+Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
+Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
+Persist project-local Pencil files under .da-vinci/designs/.
+```
+
 ## Design-Only
 
 ```text
@@ -71,12 +167,14 @@ $da-vinci use redesign-from-code to redesign this existing desktop product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, and integrations.
+Treat this as design-only, not full-delivery.
 Inventory workspaces, side panels, dialogs, overlays, and important states.
 Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
-Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, and pencil-bindings.md.
+Do not generate `tasks.md` unless the user explicitly changes the delivery intent beyond design-only.
+Before the first Pencil edit, require `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not start code changes yet.
@@ -89,7 +187,7 @@ $da-vinci use continue for this existing desktop-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.