@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.16

package/docs/mcp-aware-gate-tests.md

@@ -0,0 +1,244 @@
+# MCP-Aware Gate Test Design
+
+This document defines how to test the future MCP-aware gate implementation.
+
+It is a design for validation coverage, not a test implementation.
+
+## Test Goal
+
+Prove that the MCP-aware gate:
+
+- blocks false runtime completion states
+- does not replace filesystem audit
+- does not misclassify healthy runtime design sessions
+- behaves predictably when MCP runtime facts are incomplete
+
+## Test Layers
+
+The test plan should cover three layers.
+
+### 1. Evaluator unit tests
+
+Test the pure runtime-gate evaluator against synthetic snapshot inputs.
+
+Why:
+
+- fastest feedback
+- deterministic
+- does not depend on a live Pencil session
+
+### 2. Runtime integration tests
+
+Test the runtime-gate caller against real or fixture-backed MCP responses.
+
+Why:
+
+- proves that active editor and node reads are interpreted correctly
+
+### 3. End-to-end workflow tests
+
+Test that runtime gate and filesystem audit cooperate correctly in realistic workflow states.
+
+Why:
+
+- prevents regressions where runtime gate passes but completion still lies
+
+## Core Test Categories
+
+### A. Healthy runtime source convergence
+
+Expected:
+
+- active editor is a named project-local `.pen`
+- registered `.pen` path matches
+- shell-visible `.pen` exists
+- result is `PASS`
+
+### B. Live editor still `new`
+
+Expected:
+
+- source convergence is `BLOCK`
+- completion is blocked even if screens exist in the live editor
+
+### C. Registered `.pen` path missing on disk
+
+Expected:
+
+- source convergence or completion status becomes `BLOCK`
+- runtime gate does not treat the live editor alone as sufficient
+
+### D. Live screens exist but are not persisted
+
+Example:
+
+- active editor contains `Splash`, `Home`, `SafeBox`
+- shell-visible `.pen` does not exist
+
+Expected:
+
+- runtime gate can prove screens exist
+- source convergence is still `BLOCK`
+
+### E. Claimed anchor id missing
+
+Example:
+
+- `pencil-design.md` claims `mCZ1G`
+- current live editor does not contain `mCZ1G`
+
+Expected:
+
+- screen presence is `BLOCK`
+
+### F. Screenshot target missing
+
+Expected:
+
+- review execution is `BLOCK`
+
+### G. Review blockers ignored
+
+Example:
+
+- screenshot review records blocker-level layout-hygiene issues
+- workflow still marks anchor as approved
+
+Expected:
+
+- review execution is `BLOCK`
+
+### H. Source mismatch with explicit reconciliation
+
+Example:
+
+- active editor path and registered path differ
+- `pencil-design.md` records a documented reconciliation
+
+Expected:
+
+- evaluator returns `WARN` or `PASS` only if the reconciliation rules are satisfied
+
+### I. No new Pencil edits yet
+
+Expected:
+
+- runtime gate may return `WARN` or partial result
+- must not fabricate full `PASS`
+
+### J. Pencil MCP unavailable
+
+Expected:
+
+- runtime gate reports unavailable or skipped state
+- workflow does not treat runtime gate as passed
+- filesystem audit remains usable
+
+## Required End-to-End Scenarios
+
+### Scenario 1: Real failure pattern from Cipher
+
+State:
+
+- active editor is `new`
+- live screens exist
+- `.da-vinci/designs/` is polluted
+- no shell-visible `.pen`
+
+Expected:
+
+- runtime gate blocks completion
+- filesystem completion audit also fails
+
+### Scenario 2: Healthy redesign completion
+
+State:
+
+- active editor is the registered `.pen`
+- anchor ids exist
+- screenshot review exists
+- shell-visible `.pen` exists
+- completion audit passes
+
+Expected:
+
+- runtime gate passes
+- completion audit passes
+- terminal completion is allowed
+
+### Scenario 3: Runtime pass, filesystem fail
+
+State:
+
+- active editor is healthy
+- shell-visible `.pen` exists
+- but `.da-vinci/designs/` contains extra PNG or markdown files
+
+Expected:
+
+- runtime gate may pass
+- filesystem completion audit fails
+- terminal completion is blocked
+
+### Scenario 4: Filesystem pass, runtime fail
+
+State:
+
+- shell-visible `.pen` exists
+- files look healthy
+- active editor is still `new` or points elsewhere
+
+Expected:
+
+- runtime gate fails
+- completion is blocked
+
+## Assertions That Must Exist
+
+For every runtime-gate result, tests should assert:
+
+- final status
+- per-layer status
+- which blocking condition fired
+- whether completion would be allowed
+- whether artifact recording shape stays stable
+
+## Artifact Recording Tests
+
+Verify that runtime gate output:
+
+- appends to `pencil-design.md`
+- does not create a new artifact family
+- does not write into `.da-vinci/designs/`
+- does not overwrite unrelated sections
+
+## Regression Cases
+
+These regressions should be covered:
+
+1. runtime gate accidentally behaves like a CLI-only audit
+2. runtime gate silently treats `new` as acceptable
+3. runtime gate treats PNG exports as source evidence
+4. runtime gate passes when anchor ids are missing
+5. runtime gate is skipped but reported as passed
+6. runtime gate writes ad hoc markdown files outside the allowed artifact path
+
+## Recommended Test Matrix
+
+Minimum matrix:
+
+- form factor: mobile first
+- design stage: first Pencil write / approved anchor / terminal completion
+- source state: healthy / `new` / diverged / missing `.pen`
+- screen state: present / missing / stale ids
+- review state: reviewed / missing / blocker ignored
+
+## Exit Criteria
+
+The implementation should not be considered ready unless all of the following are true:
+
+1. evaluator unit tests cover all blocker branches
+2. at least one runtime integration test proves live editor detection works
+3. the Cipher-like failure scenario is blocked
+4. a healthy redesign scenario passes
+5. runtime gate plus filesystem audit together prevent false terminal completion

package/docs/mcp-aware-gate.md

@@ -0,0 +1,246 @@
+# MCP-Aware Gate Proposal
+
+This document defines a proposed MCP-aware runtime gate for Da Vinci.
+
+It is intentionally a design document, not an implementation commitment.
+
+## Status
+
+- Design status: proposed
+- Validation status: partially validated from real runtime observations
+- Implementation status: not started
+
+## Why This Exists
+
+The current filesystem audit closes one important gap:
+
+- it can prove whether the project-local `.pen` file exists on disk
+- it can prove whether `.da-vinci/designs/` is polluted
+- it can prove whether exported screenshots were misplaced
+
+But it cannot prove live MCP state such as:
+
+- whether the active Pencil editor is still `new`
+- whether the claimed anchor surfaces actually exist in the active editor
+- whether the active editor and the registered project-local `.pen` source have converged
+
+Those facts only exist at runtime inside the MCP-backed design session.
+
+## Validated Feasibility
+
+The following facts have already been validated as observable:
+
+1. The active Pencil editor can be read through MCP.
+2. The top-level live nodes can be read through MCP.
+3. Specific screen node ids can be read through MCP.
+4. The shell-visible project state can be read separately through normal filesystem access.
+
+This means Da Vinci can already compare:
+
+- live editor truth
+- live screen truth
+- filesystem truth
+
+That comparison is enough to support a first MCP-aware runtime gate.
+
+## Non-Goals
+
+This proposal does not attempt to:
+
+- replace the filesystem `da-vinci audit`
+- expose MCP state directly through the CLI
+- auto-repair live editor state into a persisted `.pen` file
+- make implementation depend on undocumented Pencil session behavior
+
+## Design Principles
+
+1. MCP-aware gate is runtime-only.
+2. Filesystem audit remains the terminal persistence gate.
+3. Runtime gate blocks false progress; it does not auto-heal state.
+4. The design should only rely on facts already observed to be readable.
+5. The design should degrade cleanly when Pencil MCP is unavailable.
+
+## Placement In The Workflow
+
+The MCP-aware gate should sit in two places:
+
+1. After the first successful Pencil write on a redesign pass.
+2. Before any terminal `design complete` or `workflow complete` claim.
+
+It should not run on every trivial design operation.
+
+## Proposed Gate Layers
+
+### 1. Source Convergence Gate
+
+Purpose:
+
+- determine whether the live editor, registered `.pen` path, and shell-visible `.pen` file agree well enough to treat the design source as traceable
+
+Inputs:
+
+- active Pencil editor state from MCP
+- registered `.pen` path from `design-registry.md`
+- shell-visible `.pen` path under `.da-vinci/designs/`
+
+Blocking conditions:
+
+- active editor is still an unnamed live editor such as `new`
+- active editor does not match the registered project-local source and the mismatch is not explicitly reconciled
+- shell-visible `.pen` file does not exist after live Pencil work has already happened
+- runtime session appears to be using a different source than the registered project-local source
+
+Result:
+
+- `PASS`: source is converged
+- `WARN`: source is intentionally deferred but still traceable
+- `BLOCK`: source of truth is not stable enough to continue
+
+### 2. Screen Presence Gate
+
+Purpose:
+
+- verify that claimed anchor surfaces actually exist in the active live editor
+
+Inputs:
+
+- node ids or screen ids recorded in `pencil-design.md`
+- current top-level or targeted node reads from MCP
+
+Blocking conditions:
+
+- claimed anchor screen cannot be found in the active editor
+- screenshot node id does not resolve in the current live document
+- the design claims more approved anchor surfaces than the current editor can account for
+
+Result:
+
+- `PASS`: claimed screens exist
+- `WARN`: some naming drift exists but mapping is still recoverable
+- `BLOCK`: claimed design output cannot be traced to the live document
+
+### 3. Review Execution Gate
+
+Purpose:
+
+- verify that screenshot review was performed on the live surfaces that are being treated as approved
+
+Inputs:
+
+- reviewed screen ids from `pencil-design.md`
+- screenshot targets used in the current design session
+- resolved form-factor layout hygiene profile
+
+Blocking conditions:
+
+- a surface is treated as approved without any live screenshot review
+- screenshot review flagged blocker-level layout hygiene issues but the workflow still marked the surface as passed
+- review artifacts refer to screens that are not present in the active editor
+
+Result:
+
+- `PASS`: reviewed surfaces match live runtime state
+- `WARN`: review exists but needs follow-up before expansion
+- `BLOCK`: approval claim is not trustworthy
+
+## Runtime Output Shape
+
+The gate should not invent a new artifact family.
+
+Instead, it should append a short runtime section to `pencil-design.md` or another already valid change artifact:
+
+```md
+## MCP Runtime Gate
+- Time:
+- Active editor:
+- Registered `.pen` path:
+- Shell-visible `.pen` path:
+- Reviewed screen ids:
+- Source convergence: PASS | WARN | BLOCK
+- Screen presence: PASS | WARN | BLOCK
+- Review execution: PASS | WARN | BLOCK
+- Notes:
+```
+
+This keeps runtime evidence attached to the design pass instead of scattering it into ad hoc files.
+
+## Relationship To Filesystem Audit
+
+The two systems have different jobs.
+
+### MCP-aware runtime gate
+
+- checks live editor truth
+- checks live screen truth
+- checks runtime/source convergence before false progress spreads
+
+### Filesystem audit
+
+- checks persisted project truth
+- checks directory hygiene
+- checks completion integrity
+
+Expected terminal rule:
+
+- do not report completion unless MCP-aware runtime gate passes and filesystem completion audit passes
+
+## Why This Should Not Be A CLI Feature First
+
+The current CLI can only read filesystem state.
+
+It has no MCP transport, no session identity, and no direct access to the live Pencil editor.
+
+That makes a CLI-only MCP-aware gate structurally unreliable.
+
+For now, the MCP-aware gate should be treated as an agent-executed runtime checkpoint, not a standalone CLI audit mode.
+
+## Failure Modes To Avoid
+
+1. Treating `new` as if it were a persisted `.pen` path.
+2. Treating exported PNG files as design-source evidence.
+3. Treating node ids from an old live document as if they still describe the current active editor.
+4. Silently reconciling runtime/source mismatches without recording that reconciliation.
+5. Auto-writing a `.pen` file from live state without an explicit workflow rule.
+
+## Minimum Viable Implementation Scope
+
+The first implementation should stay narrow.
+
+It should only:
+
+1. read active editor state
+2. read claimed anchor screen ids
+3. compare those facts against `design-registry.md` and the shell-visible `.pen` file
+4. record structured PASS/WARN/BLOCK output
+5. block completion when runtime truth and filesystem truth diverge
+
+It should not:
+
+- attempt automatic reconstruction
+- mutate design files on its own beyond structured checkpoint recording
+- add a new CLI command for live runtime state
+
+## Open Questions
+
+These questions remain open and should be answered during implementation design, not before:
+
+1. Which existing command route should own the runtime gate call?
+2. Should the runtime evidence live in `pencil-design.md` only, or also in `design-registry.md`?
+3. How should a reconciled editor-path mismatch be recorded without encouraging drift?
+4. Should the gate run once per approved anchor or once per design phase?
+
+## Recommendation
+
+Proceed only with a narrow agent-executed MCP-aware runtime gate.
+
+Do not expand it into:
+
+- CLI transport work
+- automatic persistence repair
+- generalized MCP session management
+
+The validated path is:
+
+1. keep filesystem `audit` as the persistence and completion backstop
+2. add a runtime MCP-aware gate for source convergence and live screen presence
+3. require both layers before terminal completion is allowed

package/docs/mode-use-cases.md

@@ -138,7 +138,9 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 
 8. create `pencil-design.md`
    - record the generated Pencil screens
-   - ensure the active design is materialized into the registered `.pen` path under `.da-vinci/designs/`
+   - if no registered project-local `.pen` exists yet, persist the first approved MCP snapshot into the registered `.pen` path under `.da-vinci/designs/`
+   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits
+   - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`
    - map implementation pages to Pencil pages
@@ -156,6 +158,7 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 - `DA-VINCI.md` exists and is stable
 - every core page exists in `page-map.md`
 - every implementation page has a Pencil counterpart or an explicit exception
+- the registered project-local `.pen` file is shell-visible and not just a live editor session
 - `task checkpoint` passes
 
 ### Best fit
@@ -353,8 +356,11 @@ Register the design sources, extract DA-VINCI.md from them, bind covered pages,
 - for complex products, get 1-3 anchor surfaces through screenshot review before expanding the rest of the redesign
 - for each anchor surface, explain briefly how the new composition differs from the current layout grouping
 - do not auto-pass screenshot review if the analysis reports hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues
+- do not record screenshot review as "looks good" without an explicit `PASS`, `WARN`, or `BLOCK`, issue list, and revision outcome
 - define a small shared primitive family from the approved anchor surfaces before broad page expansion
 - use only Pencil-supported properties; do not rely on web-only props such as `flex` or `margin`
+- preflight non-trivial `batch_design` operation strings when shell access is available
+- if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
 
 For redesign work:
 

package/docs/prompt-presets/README.md

@@ -13,6 +13,8 @@ Recommended flow:
 3. choose the prompt variant that matches project complexity and delivery intent
 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 distinguish first-run snapshot creation from resume/overwrite persistence instead of relying on interactive `save()`
 
 Available presets:
 
@@ -26,6 +28,7 @@ Design rule:
 - prompt presets define workflow intent, decomposition rules, and truth-source handling
 - visual-assist presets define UI-design helper preferences
 - form-factor-specific layout hygiene remains a separate hard gate that screenshot review must apply before a screen passes
+- MCP runtime gate and `da-vinci audit --mode completion ...` remain workflow gates, not `Visual Assist` configuration
 - use both together for the strongest result
 
 Each scene preset should now include:

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

@@ -28,6 +28,9 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
 Inventory the current workspaces, dialogs, overlays, and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+If 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.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -41,12 +44,22 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
 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.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as workspace constraints, not as the design direction.
 Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 Apply the form-factor-specific layout hygiene rules for desktop before passing screenshot review.
+Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
+If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
+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`.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/`; if one already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+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.
+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/.
 ```
@@ -63,6 +76,9 @@ 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.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+If 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.
 ```
 
@@ -73,8 +89,10 @@ $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.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Reopen that file for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it.
 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.
 Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
 ```
 

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

@@ -28,6 +28,9 @@ 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.
 Inventory the current screens and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+If 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.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -41,6 +44,7 @@ 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.
 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.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 State the resolved primary visual adapter explicitly in the log and name any requested adapters that are unavailable.
@@ -51,9 +55,18 @@ 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.
 Do not treat screenshot analysis as an automatic pass if it reports hierarchy, spacing, clarity, or inconsistency issues.
 Apply the form-factor-specific layout hygiene rules for mobile before passing screenshot review.
+Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
+If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 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`.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/`; if one already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
 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.
+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.
 Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, repeated placeholder templates, or weak visual anchors.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -71,6 +84,9 @@ 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.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+If 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.
 ```
 
@@ -81,8 +97,10 @@ $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.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Reopen that file for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it.
 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.
 Continue into the next unfinished stage and do not stop at tasks.md when the active intent is full-delivery.
 ```