@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

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

@@ -139,6 +139,7 @@ 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/`
+   - 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 +157,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

package/docs/prompt-presets/README.md

@@ -25,6 +25,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
 - use both together for the strongest result
 
 Each scene preset should now include:

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

@@ -41,11 +41,15 @@ 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.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.
 ```

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

@@ -41,6 +41,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.
@@ -50,9 +51,12 @@ Do not start with broad multi-screen scaffolding.
 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.
 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.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.

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

@@ -41,11 +41,15 @@ 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.
 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.
 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 tablet-layout 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 tablet before passing screenshot review.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.
 ```

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

@@ -42,11 +42,15 @@ Preserve current business logic, routes, permissions, integrations, validations,
 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.
+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 responsive layout 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 web before passing screenshot review.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.
 ```

package/docs/visual-adapters.md

@@ -24,6 +24,11 @@ It must not redefine:
 
 Those still come from requirements, existing code, `page-map.md`, and `pencil-bindings.md`.
 
+Visual adapters also do not replace form-factor-specific layout-hygiene rules.
+
+- adapters shape art direction
+- layout hygiene decides whether a reviewed screen is structurally sound for its form factor
+
 ## Where To Configure It
 
 Configure visual-adapter preferences inside `DA-VINCI.md`.
@@ -49,6 +54,7 @@ Recommended shape:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -71,6 +77,7 @@ Balanced default:
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -95,6 +102,7 @@ Quality-first redesign:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -120,6 +128,7 @@ Use the fields like this:
 - `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
 - `Fallback`
   - what Da Vinci should do if the preferred adapters are unavailable locally

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

@@ -20,6 +20,7 @@ If the project is design-critical or previous outputs were weak, generic, or too
 - consider `Require Adapter: true`
 - 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
 
 Available presets:
 
@@ -33,5 +34,6 @@ 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. keep `Require Adapter: false` unless the project truly must stop without a specific local skill
-5. for complex redesigns, do not treat the preset alone as enough; pair it with anchor-first Pencil generation and screenshot review
+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

package/docs/visual-assist-presets/desktop-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - workspace composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - prefer `ui-ux-pro-max` first for dense app layout decisions
+- replace adapter names with the actual installed names for the current environment when they differ
 - keep section hierarchy stronger than decorative treatment
 - use `frontend-skill` only as a secondary visual-quality helper, not as a marketing-style override
 - if the result looks flat, over-boxed, or too generic, move `frontend-skill` to the first slot and raise the design checkpoint bar

package/docs/visual-assist-presets/mobile-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - mobile page composition
   - hierarchy and spacing
   - touch-first motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - prefer `ui-ux-pro-max` first for app-surface density and control balance
+- replace adapter names with the actual installed names for the current environment when they differ
 - keep motion guidance light and purposeful
 - do not let the adapter turn routine mobile product UI into a marketing page
 - if the output keeps collapsing into generic cards or weak hierarchy, move `frontend-skill` to the first slot and consider `Require Adapter: true`