@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

package/references/layout-hygiene.md

@@ -0,0 +1,117 @@
+# Layout Hygiene
+
+Use this reference when screenshot review or the design checkpoint needs form-factor-specific layout hygiene rules.
+
+This layer is separate from `Visual Assist`.
+
+- visual adapters decide art direction and composition quality
+- layout hygiene decides whether a screen is structurally healthy enough to expand or implement
+
+## Resolution Rule
+
+Apply exactly one primary hygiene profile to each reviewed surface:
+
+1. mobile
+2. tablet
+3. desktop
+4. web
+
+Use the resolved project form factor from `DA-VINCI.md`, `design-brief.md`, or stable codebase signals.
+
+For mixed products:
+
+- apply the dominant profile per surface
+- record surface-specific exceptions in `design-brief.md` or `pencil-design.md`
+
+## Generic Checks
+
+Apply these checks to every reviewed surface:
+
+- no clipped or edge-colliding primary content
+- no unexplained whitespace bands that break the screen's visual balance
+- a clear dominant working surface or anchor
+- aligned top-chrome rhythm across related screens
+- spacing rhythm that does not bunch one region while leaving another region visually empty
+- screenshot review findings must be interpreted, not treated as an automatic pass
+
+## Severity
+
+Use these result levels:
+
+- `PASS`
+  - no blocker-level hygiene failure is present
+- `WARN`
+  - minor spacing, rhythm, or proportion issues exist, but the screen is still structurally coherent
+- `BLOCK`
+  - any blocker-level hygiene failure exists
+  - or screenshot analysis reports hierarchy, spacing, clarity, inconsistency, clipping, or unresolved-placeholder issues and the screen is not revised
+
+## Mobile
+
+Use for phone-first app screens.
+
+Check:
+
+- top inset and safe-area rhythm are respected unless the screen is intentionally full-bleed
+- the first content band does not begin flush against the top edge without a clear chrome strategy
+- the main task area is vertically balanced against top chrome and bottom actions
+- bottom trays and action rows do not crowd the main content
+- header and title start lines are consistent across related screens
+
+Treat as `BLOCK` when:
+
+- top content is visibly pinned to the edge without an intentional full-bleed reason
+- a large unexplained void appears above or within the primary task area
+- a bottom action tray compresses the main task area into an obviously cramped strip
+- related anchor screens use incompatible top-chrome alignment systems
+
+## Tablet
+
+Use for tablet-first flows or tablet-dominant surfaces.
+
+Check:
+
+- panes, canvases, and supporting rails use intentional proportions
+- gutters are consistent across primary and secondary regions
+- the screen is not just a stretched phone layout
+- primary and secondary regions have a clear weight relationship
+
+Treat as `BLOCK` when:
+
+- one side of the screen is heavily compressed while another side is mostly empty without purpose
+- pane ratios feel accidental or unstable
+- the layout is essentially a phone stack widened onto a tablet canvas
+
+## Desktop
+
+Use for desktop software and dense workspaces.
+
+Check:
+
+- toolbar, sidebar, workspace, and inspector edges align to a coherent system
+- the main workspace visibly owns the screen
+- panels feel attached to a layout system instead of floating independently
+- chrome height and content start lines are consistent between related screens
+
+Treat as `BLOCK` when:
+
+- the workspace does not read as the dominant region
+- panels feel like disconnected boxed islands or floating soup
+- top chrome and content starts drift enough to make related screens feel structurally inconsistent
+
+## Web
+
+Use for browser-based product UI and marketing/product hybrids.
+
+Check:
+
+- header plus first viewport content fit within a coherent viewport budget
+- max-width and gutters are disciplined
+- responsive behavior does not collapse hierarchy
+- the first impression is not a generic card pile
+
+Treat as `BLOCK` when:
+
+- header plus hero or workspace visibly overruns the initial viewport without intent
+- gutters or max-width rules drift enough to break hierarchy
+- breakpoint changes turn the screen into a generic stacked-card filler layout

package/references/pencil-design-to-code.md

@@ -10,6 +10,11 @@ Use this priority order:
 2. Pencil data for presentation
 3. screenshots only as a visual check
 
+Exported screenshots are review artifacts only.
+
+- store them under `.da-vinci/changes/<change-id>/exports/`
+- do not treat them as the persisted design source
+
 Do not infer behavior from appearance alone.
 
 ## Read From Pencil
@@ -33,6 +38,7 @@ If the current active Pencil editor does not match the preferred path in `design
 - do not silently continue from the unrelated editor
 - switch to the registered file when possible
 - otherwise reconstruct the registered project-local `.pen` file from MCP-readable document data before implementation depends on it
+- if the editor is still `new` or another unnamed live document, do not describe the project-local `.pen` source as saved yet
 
 ## Visual Adapter Use
 
@@ -58,8 +64,10 @@ When generating or editing Pencil data:
 - use only Pencil-supported properties and layout concepts
 - do not emit web- or CSS-only properties such as `flex` or `margin`
 - prefer smaller, schema-safe batches on anchor screens so errors do not roll back large composition chunks
+- if unsupported-property rollbacks repeat on the same anchor surface, stop treating that pass as stable forward progress until the schema usage is corrected
 - verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
 - keep workflow markdown out of `.da-vinci/designs/`; reserve that directory for `.pen` files only
+- keep screenshot exports out of `.da-vinci/designs/`; write them under `.da-vinci/changes/<change-id>/exports/`
 - after the first approved anchor surfaces, extract a shared primitive family before broad page expansion
 
 ## Map Pencil To Frontend

package/scripts/test-mcp-runtime-gate.js

@@ -0,0 +1,199 @@
+const assert = require("assert/strict");
+const {
+  PASS,
+  WARN,
+  BLOCK,
+  SKIP,
+  evaluateMcpRuntimeGate,
+  formatMcpRuntimeGateSection
+} = require("../lib/mcp-runtime-gate");
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+runTest("healthy completion passes", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/repo/.da-vinci/designs/cipher-redesign.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    claimedAnchorIds: ["GfwiK", "mCZ1G", "V8zfE"],
+    claimedReviewedScreenIds: ["GfwiK", "mCZ1G", "V8zfE"],
+    reviewTargets: ["GfwiK", "mCZ1G", "V8zfE"],
+    liveScreens: [
+      { id: "GfwiK", name: "Splash" },
+      { id: "mCZ1G", name: "Home" },
+      { id: "V8zfE", name: "SafeBox" }
+    ]
+  });
+
+  assert.equal(result.sourceConvergence.status, PASS);
+  assert.equal(result.screenPresence.status, PASS);
+  assert.equal(result.reviewExecution.status, PASS);
+  assert.equal(result.finalStatus, PASS);
+
+  const section = formatMcpRuntimeGateSection({}, result, { timestamp: "2026-03-27T00:00:00.000Z" });
+  assert.match(section, /Final runtime gate status: PASS/);
+  assert.match(section, /Source convergence: PASS/);
+});
+
+runTest("unnamed editor blocks runtime gate", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    activeEditor: "new",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    claimedAnchorIds: ["GfwiK"],
+    claimedReviewedScreenIds: ["GfwiK"],
+    reviewTargets: ["GfwiK"],
+    liveScreens: [{ id: "GfwiK", name: "Splash" }]
+  });
+
+  assert.equal(result.sourceConvergence.status, BLOCK);
+  assert.equal(result.finalStatus, BLOCK);
+});
+
+runTest("live screens without shell-visible pen block source convergence", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/repo/.da-vinci/designs/cipher-redesign.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: false,
+    claimedAnchorIds: ["GfwiK"],
+    claimedReviewedScreenIds: ["GfwiK"],
+    reviewTargets: ["GfwiK"],
+    liveScreens: [{ id: "GfwiK", name: "Splash" }]
+  });
+
+  assert.equal(result.sourceConvergence.status, BLOCK);
+  assert.equal(result.finalStatus, BLOCK);
+});
+
+runTest("missing claimed anchor blocks screen presence", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/repo/.da-vinci/designs/cipher-redesign.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    claimedAnchorIds: ["GfwiK", "mCZ1G"],
+    claimedReviewedScreenIds: ["GfwiK"],
+    reviewTargets: ["GfwiK"],
+    liveScreens: [{ id: "GfwiK", name: "Splash" }]
+  });
+
+  assert.equal(result.screenPresence.status, BLOCK);
+  assert.equal(result.finalStatus, BLOCK);
+});
+
+runTest("ignored review blockers block review execution", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/repo/.da-vinci/designs/cipher-redesign.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    claimedAnchorIds: ["GfwiK"],
+    claimedReviewedScreenIds: ["GfwiK"],
+    reviewTargets: ["GfwiK"],
+    liveScreens: [{ id: "GfwiK", name: "Splash" }],
+    reviewBlockersIgnored: true
+  });
+
+  assert.equal(result.reviewExecution.status, BLOCK);
+  assert.equal(result.finalStatus, BLOCK);
+});
+
+runTest("mcp unavailable warns instead of passing", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: false,
+    activeEditor: "",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true
+  });
+
+  assert.equal(result.sourceConvergence.status, WARN);
+  assert.equal(result.screenPresence.status, WARN);
+  assert.equal(result.reviewExecution.status, WARN);
+  assert.equal(result.finalStatus, WARN);
+});
+
+runTest("first-write phase can skip screen and review checks", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "first_write",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/repo/.da-vinci/designs/cipher-redesign.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    liveScreens: [{ id: "GfwiK", name: "Splash" }]
+  });
+
+  assert.equal(result.sourceConvergence.status, PASS);
+  assert.equal(result.screenPresence.status, SKIP);
+  assert.equal(result.reviewExecution.status, SKIP);
+  assert.equal(result.finalStatus, PASS);
+});
+
+runTest("documented reconciliation downgrades mismatch to warn", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/tmp/other-live.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    documentedReconciliation: true,
+    claimedAnchorIds: ["GfwiK"],
+    claimedReviewedScreenIds: ["GfwiK"],
+    reviewTargets: ["GfwiK"],
+    liveScreens: [{ id: "GfwiK", name: "Splash" }]
+  });
+
+  assert.equal(result.sourceConvergence.status, WARN);
+  assert.equal(result.finalStatus, WARN);
+});
+
+runTest("same basename but different absolute path blocks without reconciliation", () => {
+  const result = evaluateMcpRuntimeGate({
+    phase: "completion",
+    mcpAvailable: true,
+    projectRoot: "/repo",
+    activeEditor: "/tmp/cipher-redesign.pen",
+    registeredPenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenPath: ".da-vinci/designs/cipher-redesign.pen",
+    shellVisiblePenExists: true,
+    claimedAnchorIds: ["GfwiK"],
+    claimedReviewedScreenIds: ["GfwiK"],
+    reviewTargets: ["GfwiK"],
+    liveScreens: [{ id: "GfwiK", name: "Splash" }]
+  });
+
+  assert.equal(result.sourceConvergence.status, BLOCK);
+  assert.equal(result.finalStatus, BLOCK);
+});
+
+console.log("All MCP runtime gate tests passed.");