@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.20

package/docs/pencil-rendering-workflow.md

@@ -26,7 +26,7 @@ PNG exports are review artifacts only. They are not the design source of truth.
 
 ## Session Model
 
-Da Vinci now prefers the session wrapper:
+Da Vinci now requires the session wrapper on autonomous runs:
 
 - `da-vinci pencil-session begin`
 - `da-vinci pencil-session persist`
@@ -38,6 +38,8 @@ This wrapper exists to make three things mandatory:
 - serialized Pencil MCP write access
 - explicit live-to-disk persistence and sync verification
 
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, Da Vinci also runs a final style-quality review after the structural design gates pass. It becomes a blocking gate only when `DA-VINCI.md` sets `Require Supervisor Review: true`.
+
 ## First-Run Path
 
 When the project does not yet have a registered `.pen`:
@@ -61,6 +63,14 @@ When the project already has a registered `.pen`:
 
 Da Vinci does not assume live MCP edits were flushed automatically.
 
+## Continuation Recovery Rule
+
+When resuming from existing artifacts:
+
+- choose routing from current artifact and checkpoint truth first
+- use checkpoint-adjacent `Context Delta` notes only as auxiliary recovery context
+- if a contextual delta conflicts with current artifact/checkpoint truth, ignore that conflicting entry and record the conflict before continuing
+
 ## Persistence Rule
 
 Da Vinci does not treat headless interactive `save()` as authoritative persistence truth.
@@ -89,7 +99,7 @@ Use:
 - `da-vinci pencil-lock acquire`
 - `da-vinci pencil-lock release`
 
-or prefer the session wrapper, which manages the lock for you.
+or use the session wrapper, which manages the lock for you.
 
 This prevents multiple projects from competing for the same active editor.
 
@@ -141,6 +151,41 @@ The render output cannot pass if:
 - it ignores screenshot-review findings
 - it still shows repeated schema-instability
 
+### Design-Supervisor Review
+
+When `DA-VINCI.md` declares `Design-supervisor reviewers`, run a final `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint for the currently approved anchor set.
+
+When `Require Supervisor Review: true`, missing, blocked, or unaccepted review results block broad expansion, implementation-task handoff, and terminal completion. When `Require Supervisor Review: false`, still record the review when configured, but treat it as advisory rather than completion-blocking.
+
+Use it to judge:
+
+- style quality
+- brand distinctiveness
+- cross-screen visual coherence
+- token-to-render alignment
+- whether the approved anchors are strong enough to expand or implement from
+
+Reviewers are separate from `Preferred adapters`.
+
+- adapters lead the design pass
+- reviewers judge the approved result
+
+Recommended inputs:
+
+- reviewed screenshots
+- Pencil `get_variables()` output
+- `visual-thesis.md`
+- `content-plan.md`
+- `interaction-thesis.md`
+
+Record:
+
+- reviewer names
+- review inputs
+- `PASS` / `WARN` / `BLOCK`
+- issue list
+- revision outcome
+
 ## Design-Source Gate
 
 After active Pencil work exists, Da Vinci runs `design-source checkpoint`.
@@ -190,6 +235,14 @@ 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.
 
+Context-delta audit expectations are warning-only:
+
+- missing concrete context deltas for checkpoint-bearing artifacts -> `WARN`
+- incomplete context-delta entries -> `WARN`
+- context-delta status mismatch with current checkpoints -> `WARN`
+- a mismatch can indicate stale checkpoint status or stale context-delta notes
+- these warnings improve resume quality but do not create standalone completion blockers
+
 ## Preferred Command Chain
 
 Typical autonomous chain:
@@ -198,8 +251,10 @@ Typical autonomous chain:
 2. Pencil MCP edits
 3. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
 4. screenshot review + layout hygiene
-5. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
-6. `da-vinci audit --mode completion --change <change-id> <project-path>`
+5. design checkpoint
+6. design-supervisor review when configured
+7. `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+8. `da-vinci audit --mode completion --change <change-id> <project-path>`
 
 ## Flow Diagram
 
@@ -217,15 +272,24 @@ flowchart TD
     H --> F
     I --> J{Screenshot review and layout hygiene pass?}
     J -- No --> F
-    J -- Yes --> K[pencil-session persist writes live MCP snapshot back to .pen]
-    K --> L[check-pen-sync verifies live hash equals persisted hash]
-    L --> M{design-source checkpoint and runtime gate pass?}
-    M -- No --> F
-    M -- Yes --> N{More design work needed?}
-    N -- Yes --> E
-    N -- No --> O[pencil-session end releases lock]
-    O --> P[completion audit]
-    P --> Q{completion audit pass?}
-    Q -- No --> F
-    Q -- Yes --> R[design complete]
+    J -- Yes --> K{Design checkpoint pass?}
+    K -- No --> F
+    K -- Yes --> L{Design-supervisor review configured?}
+    L -- Yes --> M[Run design-supervisor review on screenshots plus theme inputs]
+    L -- No --> N[pencil-session persist writes live MCP snapshot back to .pen]
+    M --> O{Require Supervisor Review?}
+    O -- No --> N
+    O -- Yes --> P{Review PASS or accepted WARN?}
+    P -- No --> F
+    P -- Yes --> N
+    N --> Q[check-pen-sync verifies live hash equals persisted hash]
+    Q --> R{design-source checkpoint and runtime gate pass?}
+    R -- No --> F
+    R -- Yes --> S{More design work needed?}
+    S -- Yes --> E
+    S -- No --> T[pencil-session end releases lock]
+    T --> U[completion audit]
+    U --> V{completion audit pass?}
+    V -- No --> F
+    V -- Yes --> W[design complete]
 ```

package/docs/prompt-entrypoints.md

@@ -58,9 +58,16 @@ What it should output:
 
 - detected workflow state
 - missing or weak artifacts
+- contextual recovery notes from recent checkpoint deltas when available
 - one primary continuation prompt
 - one more conservative continuation prompt when useful
 
+Continuation precedence:
+
+- determine routing from artifact and checkpoint truth first
+- use contextual checkpoint deltas only as auxiliary recovery context
+- if contextual deltas conflict with current artifacts, ignore them for routing and note the conflict
+
 ## Default Flow
 
 Use this default sequence:
@@ -125,6 +132,9 @@ $da-vinci use intake for this existing Android project.
 I need to globally replace the UI.
 Existing code is the behavior source of truth.
 HTML references are in /abs/path/to/mockups.
+Treat the HTML directory as visual reference only, not behavior truth or final design-source truth.
+Open the HTML references in a real browser and wait 3-5 seconds, or until the visual state settles, before judging the final styling.
+Inventory which pages and states the HTML directory actually covers and which still need to be inferred from behavior truth.
 ```
 
 Expected outcome:
@@ -159,7 +169,7 @@ Use:
 $da-vinci use intake for this existing product.
 
 This is a large overhaul, not only a UI refresh.
-Current codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, logic, and page structure while preserving selected integrations and constraints.
 Generate the best executable Da Vinci workflow prompt for the next step.
 ```

package/docs/prompt-presets/README.md

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

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

@@ -19,6 +19,7 @@ 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.
 
@@ -32,7 +33,7 @@ Use these templates when the desktop product already exists, but workspace model
 $da-vinci use intake for this existing desktop product.
 
 This is a broad overhaul, not only a UI refresh.
-Current desktop codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+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.
 ```
@@ -61,7 +62,7 @@ $da-vinci use overhaul-from-code to design the new target desktop surfaces from
 
 Use the existing .da-vinci/project-inventory.md, proposal.md, migration-contract.md, target specs, page-map.md, DA-VINCI.md, and design-registry.md.
 Treat the new proposal and specs as the target behavior truth.
-Treat the old desktop codebase only as reference evidence and migration context.
+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.
@@ -74,6 +75,8 @@ $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.
+Determine routing from artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
+If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
 Prefer the artifact-backed next safe stage instead of restarting the overhaul from scratch.
 ```
 
@@ -84,9 +87,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.
@@ -100,6 +105,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.
@@ -113,15 +120,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
@@ -129,12 +169,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.
@@ -147,7 +189,9 @@ $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.
+Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
+If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
+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.

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

@@ -19,6 +19,7 @@ Use this when the workflow needs:
 
 - Use `Simple redesign` when the app surface is small, mostly contained, or has only a few canonical screens.
 - Use `Complex redesign` when the app has multiple activities, fragments, tabs, overlays, or materially different states.
+- Use `Redesign with reference directory` when you have a local HTML or mockup directory that should guide visual composition without becoming the behavior truth.
 - Use `Design-only` when you want the full design chain but do not want code changes yet.
 - Use `Continue` when `.da-vinci/` artifacts already exist and the workflow needs to resume.
 
@@ -32,7 +33,7 @@ Use these templates when the product already exists, but mobile flows, logic, an
 $da-vinci use intake for this existing mobile product.
 
 This is a broad overhaul, not only a UI refresh.
-Current Android or mobile code is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current Android or mobile code is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine mobile flows, states, navigation structure, and selected surfaces while preserving only approved integrations, permissions, and constraints.
 Recommend the best Da Vinci mode and generate the best executable next-step prompt.
 ```
@@ -61,7 +62,7 @@ $da-vinci use overhaul-from-code to design the new target mobile surfaces from t
 
 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 mobile codebase only as reference evidence and migration context.
+Treat the old mobile 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.
@@ -74,6 +75,8 @@ $da-vinci use continue for this existing overhaul-from-code mobile 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.
+Determine routing from artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
+If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
 Prefer the artifact-backed next safe stage instead of restarting the overhaul from scratch.
 ```
 
@@ -84,9 +87,11 @@ $da-vinci use redesign-from-code to redesign this existing mobile app.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions 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 screens 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 a skin-swap of the old UI, a generic card grid, or a weak mobile hierarchy.
@@ -100,6 +105,8 @@ $da-vinci use redesign-from-code to redesign this existing mobile app.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions 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 activities, fragments, tabs, dialogs, bottom sheets, nested flows, overlays, and materially different states before broad Pencil work.
 Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
 Create the required discovery and design-source artifacts in their standard locations before the first anchor surface.
@@ -119,10 +126,11 @@ Use only Pencil-supported properties; do not use web-only props like flex or mar
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Run `da-vinci audit --mode integrity <project-path>` after that 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.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 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.
 Define shared primitives from the approved anchor surfaces before broad page expansion.
@@ -130,6 +138,38 @@ Do not pass design checkpoint if the result is a skin-swap of the old UI, a gene
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+## Redesign With Reference Directory
+
+```text
+$da-vinci use redesign-from-code to redesign this existing mobile app.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve business logic, navigation, permissions, integrations, validations, and state transitions 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, route truth, or final design-source truth.
+Inventory which activities, fragments, tabs, sheets, 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
@@ -137,12 +177,14 @@ $da-vinci use redesign-from-code to redesign this existing mobile app.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior and navigation.
+Treat this as design-only, not full-delivery.
 Inventory screens, tabs, dialogs, bottom sheets, nested flows, 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 app 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.
@@ -155,7 +197,9 @@ $da-vinci use continue for this existing mobile-app 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.
+Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
+If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
+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, keep the anchor-first flow until the design checkpoint passes.
 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.