@xenonbyte/da-vinci-workflow 0.1.18 → 0.1.20

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

@@ -19,6 +19,7 @@ Use this when the workflow needs:
 
 - Use `Simple redesign` when the tablet surface is limited, mostly single-flow, or only lightly adapted from a phone layout.
 - Use `Complex redesign` when the product has split panes, orientation changes, expanded canvases, overlays, or many materially different surfaces.
+- Use `Redesign with reference directory` when you have a local HTML or mockup directory that should guide tablet composition as a visual reference only.
 - Use `Design-only` when you want the design chain and bindings but no code changes yet.
 - Use `Continue` when the workflow already created artifacts and needs to resume.
 
@@ -32,7 +33,7 @@ Use these templates when the tablet product already exists, but split-pane behav
 $da-vinci use intake for this existing tablet product.
 
 This is a broad overhaul, not only a UI refresh.
-Current tablet codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current tablet codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, orientation-aware structure, page responsibilities, 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 tablet 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 tablet codebase only as reference evidence and migration context.
+Treat the old tablet 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 tablet 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 tablet product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, 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 tablet surfaces 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 ignores tablet-scale composition or collapses into a stretched phone layout.
@@ -100,6 +105,8 @@ $da-vinci use redesign-from-code to redesign this existing tablet product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, 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 split-pane regions, sidebars, expanded canvases, dialogs, sheets, orientation-driven changes, and materially different states before broad Pencil work.
 Decompose complex pages into multi-region surfaces, overlays, materially different states, 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 collapses into a stretched phone layout, repeated placeholders, or weak multi-region hierarchy.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+## Redesign With Reference Directory
+
+```text
+$da-vinci use redesign-from-code to redesign this existing tablet product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current behavior, 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 split-pane regions, sidebars, expanded canvases, dialogs, sheets, orientation-driven changes, 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 tablet product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, permissions, integrations, and state transitions.
+Treat this as design-only, not full-delivery.
 Inventory split-pane regions, sidebars, dialogs, sheets, orientation changes, and important states.
 Decompose complex pages 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 tablet-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/web-app.md

@@ -19,6 +19,7 @@ Use this when the workflow needs:
 
 - Use `Simple redesign` when the web product has a limited product surface or only a few major pages.
 - Use `Complex redesign` when the product mixes marketing, auth, onboarding, app surfaces, dialogs, drawers, and materially different states.
+- Use `Redesign with reference directory` when you have a local HTML or mockup directory that should guide visual treatment without becoming route or behavior truth.
 - Use `Design-only` when you want the design chain and bindings but no code changes yet.
 - Use `Continue` when the workflow already has artifacts and needs to resume.
 
@@ -32,7 +33,7 @@ Use these templates when the web product already exists, but routes, flow logic,
 $da-vinci use intake for this existing web product.
 
 This is a broad overhaul, not only a UI refresh.
-Current web codebase is important reference evidence and migration baseline, but it should not be treated as the final target behavior truth.
+Current web codebase is reference evidence and migration baseline, not the final target behavior truth.
 We need to redefine flows, route structure, page responsibilities, 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 web surfaces from the
 
 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 web codebase only as reference evidence and migration context.
+Treat the old web 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 web 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 web product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current business logic, routes, 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 product surfaces 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 generic SaaS card grid or a recolor of the old interface.
@@ -100,6 +105,8 @@ $da-vinci use redesign-from-code to redesign this existing web product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current business logic, routes, 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 responsive product surfaces, marketing surfaces, authenticated areas, settings pages, dialogs, drawers, overlays, and materially different states before broad Pencil work.
 Separate marketing-style surfaces from product-workflow surfaces when they require different visual treatment.
 Decompose complex pages into subpages, overlays, materially different states, and implementation surfaces.
@@ -114,15 +121,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 generic SaaS card grid, repeated placeholder scaffolds, or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
 
+## Redesign With Reference Directory
+
+```text
+$da-vinci use redesign-from-code to redesign this existing web product.
+
+Existing code is the behavior source of truth, not the layout truth.
+Preserve current business logic, routes, 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 routes, auth surfaces, dialogs, drawers, overlays, responsive shells, 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
@@ -130,12 +170,14 @@ $da-vinci use redesign-from-code to redesign this existing web product.
 
 Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, routes, permissions, integrations, and state transitions.
+Treat this as design-only, not full-delivery.
 Inventory product surfaces, marketing surfaces, overlays, and important states.
 Decompose complex pages 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.
@@ -148,7 +190,9 @@ $da-vinci use continue for this existing web-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/visual-adapters.md

@@ -49,6 +49,17 @@ Recommended shape:
 - Preferred adapters:
   - frontend-skill
   - ui-ux-pro-max
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -60,6 +71,8 @@ Recommended shape:
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 Use `Require Adapter: true` only when the workflow must stop if the preferred adapter is unavailable locally.
@@ -73,6 +86,17 @@ Balanced default:
 - Preferred adapters:
   - ui-ux-pro-max
   - frontend-skill
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -83,6 +107,8 @@ Balanced default:
   - native-da-vinci
 - Require Adapter:
   - false
+- Require Supervisor Review:
+  - false
 ```
 
 Use this when:
@@ -97,6 +123,17 @@ Quality-first redesign:
 - Preferred adapters:
   - frontend-skill
   - ui-ux-pro-max
+- Design-supervisor reviewers:
+  - frontend-skill
+  - ui-ux-pro-max
+- Design-supervisor review mode:
+  - screenshot-and-theme
+- Design-supervisor review inputs:
+  - screenshots
+  - pencil variables
+  - visual thesis
+  - content plan
+  - interaction thesis
 - Scope:
   - visual contract refinement
   - page composition
@@ -108,6 +145,8 @@ Quality-first redesign:
   - native-da-vinci
 - Require Adapter:
   - true
+- Require Supervisor Review:
+  - false
 ```
 
 Use this when:
@@ -116,6 +155,78 @@ Use this when:
 - the previous redesign attempt produced generic card grids, weak anchors, or a skin-swap of the old UI
 - you would rather stop than silently continue without a strong local design helper
 
+## Gate Order And Branching
+
+`Visual Assist` participates in the design flow, but it does not replace the workflow gates.
+
+The review order is:
+
+1. screenshot review
+2. layout hygiene
+3. design checkpoint
+4. design-supervisor review when configured
+
+Each layer has a different job:
+
+- screenshot review
+  - checks whether the reviewed surface has obvious hierarchy, spacing, clarity, or consistency problems
+- layout hygiene
+  - checks whether the screen is structurally healthy for its form factor
+- design checkpoint
+  - checks whether the approved anchor set is strong enough to expand from
+- design-supervisor review
+  - checks whether the final style quality is mature enough to expand or implement from
+
+How each gate judges:
+
+- screenshot review
+  - review the exported or captured surface itself
+  - require an explicit `PASS` / `WARN` / `BLOCK`
+  - require an issue list and revision outcome
+  - treat unresolved hierarchy, spacing, clarity, consistency, or placeholder issues as a stop signal before expansion
+- layout hygiene
+  - review the same surface against form-factor-specific structural rules
+  - check top chrome alignment, edge pressure, clipping, region balance, density, and footer/body conflict
+  - block when the screen is structurally unhealthy even if the style direction looks promising
+- design checkpoint
+  - review the approved anchor set, not just one isolated screenshot
+  - block skin-swaps of the old UI, generic card mosaics, repeated placeholder scaffolds, and weak visual anchors
+  - only pass when the anchor set is strong enough to define shared primitives and support broad page expansion
+- design-supervisor review
+  - review screenshots plus the configured theme and thesis inputs
+  - require reviewer names, explicit status, issue list, and revision outcome in `pencil-design.md`
+  - use this gate to judge final style maturity, brand fit, and genericness risk after the structural gates have already passed
+
+Branching rules:
+
+- if `Design-supervisor reviewers` are omitted
+  - no supervisor review runs
+  - the workflow still depends on the structural gates above
+- if reviewers are configured and `Require Supervisor Review: false`
+  - run and record supervisor review
+  - the review is advisory
+  - missing or weak reviewer results should not silently override the earlier structural gates
+- if reviewers are configured and `Require Supervisor Review: true`
+  - supervisor review becomes a hard gate
+  - missing review, `BLOCK`, or unaccepted `WARN` should stop broad expansion, implementation-task handoff, and terminal completion
+
+Result branching by gate:
+
+- screenshot review `BLOCK`
+  - revise the reviewed surface before layout hygiene or broader expansion continues
+- layout hygiene `BLOCK`
+  - revise structure for the target form factor before treating the screen as approved
+- design checkpoint `BLOCK`
+  - stop broad generation and reset from the anchor set instead of layering more screens on top
+- design-supervisor review `WARN` with `Require Supervisor Review: false`
+  - record the warning and decide whether to refine before expansion
+- design-supervisor review `WARN` with `Require Supervisor Review: true`
+  - treat as blocking unless the warning is explicitly accepted and the acceptance is recorded
+- design-supervisor review `BLOCK`
+  - stop expansion, task handoff, and terminal completion until the visual-quality issues are resolved
+
+Reviewer outcomes never override blocker-level screenshot-review or layout-hygiene failures.
+
 ## What Each Field Means
 
 Use the fields like this:
@@ -125,22 +236,82 @@ Use the fields like this:
   - order matters
   - if multiple listed skills are available, Da Vinci should still resolve one primary adapter
   - do not assume cross-platform equivalence between near-name adapters such as `frontend-skill` and `frontend-design`; resolve the actual installed adapter names for the current environment
+  - typical use:
+    - put `ui-ux-pro-max` first for dense product surfaces
+    - put `frontend-skill` first when art direction and composition quality matter more
+- `Design-supervisor reviewers`
+  - the priority list of local skills you want Da Vinci to use for final style-quality review after structural design gates pass
+  - keep this distinct from `Preferred adapters` even when the same installed skill appears in both lists
+  - reviewers judge the approved result; they do not lead first-pass composition
+  - omit this field when the project does not need a final reviewer role
+- `Design-supervisor review mode`
+  - how the final review should evaluate the work
+  - use `screenshot-and-theme` when reviewers should inspect screenshots plus Pencil variables and design theses together
+  - recommended default: `screenshot-and-theme`
+- `Design-supervisor review inputs`
+  - the evidence reviewers must use
+  - prefer screenshots, Pencil variables, `visual-thesis.md`, `content-plan.md`, and `interaction-thesis.md`
+  - minimum useful set:
+    - screenshots
+    - Pencil variables
+  - full recommended set:
+    - screenshots
+    - Pencil variables
+    - `visual-thesis.md`
+    - `content-plan.md`
+    - `interaction-thesis.md`
 - `Scope`
   - the only areas where adapters are allowed to influence the workflow
   - keep this limited to presentation-quality work such as composition, spacing, and Pencil refinement
   - include anchor-surface composition when the redesign depends on a strong first-pass visual direction
   - do not use this field to delegate behavior, routes, or state truth
+  - good scope entries:
+    - visual contract refinement
+    - page or workspace composition
+    - hierarchy and spacing
+    - anchor-surface composition
+    - Pencil design refinement
 - `Fallback`
   - what Da Vinci should do if the preferred adapters are unavailable locally
   - `native-da-vinci` means continue with the built-in rules instead of stopping
+  - keep `native-da-vinci` unless the team has a documented alternate fallback policy
 - `Require Adapter`
   - whether adapter availability is a hard requirement
   - `false` means adapter use is optional and should not block delivery
   - `true` means the workflow should stop if no acceptable adapter is available
+  - keep this `false` for most work
+- `Require Supervisor Review`
+  - whether `design-supervisor review` is a hard gate
+  - when `true`, missing, blocked, or unaccepted review results should block broad expansion, implementation-task handoff, and terminal completion
+  - keep it `false` unless the project explicitly requires a reviewer-backed style signoff
+  - this field only matters when `Design-supervisor reviewers` are configured
+  - `false` means the review still runs when configured, but remains advisory
+  - `true` means the review becomes a delivery gate
+
+## Recommended Combinations
+
+Use these combinations:
+
+- adapter-only
+  - `Preferred adapters`: set
+  - `Design-supervisor reviewers`: omit
+  - `Require Adapter`: `false`
+  - `Require Supervisor Review`: omit
+- balanced with advisory reviewer
+  - `Preferred adapters`: set
+  - `Design-supervisor reviewers`: set
+  - `Require Adapter`: `false`
+  - `Require Supervisor Review`: `false`
+- high-control redesign with hard reviewer signoff
+  - `Preferred adapters`: set
+  - `Design-supervisor reviewers`: set
+  - `Require Adapter`: `true` or `false` depending on adapter strictness
+  - `Require Supervisor Review`: `true`
 
 Recommended default:
 
 - use `Require Adapter: false`
+- use `Require Supervisor Review: false`
 - use `Fallback: native-da-vinci`
 - keep `Scope` narrowly focused on visual-quality decisions
 
@@ -167,7 +338,7 @@ For `redesign-from-code`, also do this:
 
 For `overhaul-from-code`, also do this:
 
-- restate that existing code is reference evidence and migration baseline, not automatic final behavior truth
+- restate that existing code is reference evidence and migration baseline, not the final target behavior truth
 - stabilize `proposal.md`, `migration-contract.md`, target `specs/`, and `page-map.md` before broad Pencil work
 - make sure anchor surfaces express the new flow and information architecture instead of cosmetically repainting the legacy shell
 
@@ -238,6 +409,13 @@ For complex redesigns:
 - define a small shared primitive family from the approved anchor surfaces before broad page expansion
 - if the output is still placeholder-heavy or repetitious, mark `design checkpoint` as `BLOCK` and reset from the anchor surfaces instead of layering more screens on top
 
+If `Design-supervisor reviewers` are configured:
+
+- run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint on the approved anchor set
+- if `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before expansion or implementation handoff
+- do not let reviewers override blocker-level layout-hygiene or screenshot-review failures
+- record reviewer names, inputs, `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome in `pencil-design.md`
+
 Record the outcome in `pencil-design.md`.
 
 Recommended fields:

package/docs/visual-assist-presets/README.md

@@ -5,10 +5,20 @@ Use these presets as starting points for the `## Visual Assist` section inside `
 Each preset is intentionally conservative:
 
 - one primary adapter direction
+- one separate reviewer direction
 - one fallback direction
 - clear scope boundaries
 - non-blocking behavior by default
 
+Each surface preset should now be read as a family of three variants:
+
+- adapter-only
+  - use when the project wants design-generation help but no final reviewer role
+- advisory reviewer
+  - use when the project wants a recorded final style readout but does not want review status to block completion
+- required reviewer signoff
+  - use when the project needs reviewer-backed style approval before broad expansion or implementation handoff
+
 Use them together with:
 
 - `docs/prompt-presets/`
@@ -23,6 +33,7 @@ If the project is design-critical or previous outputs were weak, generic, or too
 - keep the same preset family
 - move `frontend-skill` to the first slot
 - consider `Require Adapter: true`
+- consider `Require Supervisor Review: true` only when the project truly needs reviewer-backed style signoff
 - raise the design checkpoint bar before broad Pencil generation
 - switch to anchor-first generation: design 1-3 anchor surfaces, review screenshots, then expand
 - update `Preferred adapters` to the actual installed names for the current environment instead of assuming cross-platform aliases
@@ -37,8 +48,20 @@ Available presets:
 How to use them:
 
 1. choose the preset closest to the product surface
-2. copy the `## Visual Assist` block into `DA-VINCI.md`
-3. adjust adapter order only if the project clearly needs a different visual bias
-4. replace adapter names with the actual installed names for the current environment when they differ
-5. keep `Require Adapter: false` unless the project truly must stop without a specific local skill
-6. for complex redesigns, do not treat the preset alone as enough; pair it with anchor-first Pencil generation and screenshot review
+2. choose the correct variant inside that preset:
+   - adapter-only
+   - advisory reviewer
+   - required reviewer signoff
+3. copy the selected `## Visual Assist` block into `DA-VINCI.md`
+4. adjust adapter order only if the project clearly needs a different visual bias
+5. replace adapter names with the actual installed names for the current environment when they differ
+6. keep `Require Adapter: false` unless the project truly must stop without a specific local skill
+7. keep `Design-supervisor reviewers` separate from `Preferred adapters`, even if the same installed skill appears in both lists
+8. keep `Require Supervisor Review: false` unless the project truly needs reviewer-backed style signoff
+9. for complex redesigns, do not treat the preset alone as enough; pair it with anchor-first Pencil generation, screenshot review, and `design-supervisor review` when configured
+
+Variant-selection rule of thumb:
+
+- choose adapter-only for routine product work where structural gates are enough
+- choose advisory reviewer for most redesigns where you want stronger quality feedback recorded
+- choose required reviewer signoff only when visual quality itself is a delivery gate