@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.16

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
 
@@ -57,9 +63,19 @@ 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`
+- preflight non-trivial `batch_design` operation strings before sending them to Pencil when shell access is available
 - prefer smaller, schema-safe batches on anchor screens so errors do not roll back large composition chunks
+- prefer 12 or fewer operations on anchor surfaces; after two failed batches on the same anchor, drop to micro-batches of 6 or fewer operations until a clean pass lands
+- if unsupported-property rollbacks repeat on the same anchor surface, stop treating that pass as stable forward progress until the schema usage is corrected
+- after any rolled-back batch or structure-changing edit, refresh the live node structure before descendant-targeted follow-up operations
 - verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+- do not treat headless interactive `save()` as authoritative persistence; write the project-local `.pen` from MCP-readable snapshot data instead
+- if no registered project-local `.pen` existed at the start of the session, let the first approved anchor surface happen in the live editor, then persist that first approved MCP snapshot under `.da-vinci/designs/`
+- if a registered project-local `.pen` already existed, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically
+- use `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open` when you already have MCP-readable snapshot payloads and need an atomic project-local `.pen` write
+- use `da-vinci snapshot-pen --input <path> --output <path> --verify-open` when a project-local `.pen` already exists and you need to re-canonicalize it from a fresh MCP-readable snapshot
 - 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/fixtures/complex-sample.pen

@@ -0,0 +1,295 @@
+{
+  "version": "2.9",
+  "variables": {
+    "surface-bg": {
+      "type": "color",
+      "value": "#F4EFE7"
+    },
+    "surface-panel": {
+      "type": "color",
+      "value": "#FFFDF8"
+    },
+    "surface-border": {
+      "type": "color",
+      "value": "#D7CCBC"
+    },
+    "deck-fill": {
+      "type": "color",
+      "value": "#17304A"
+    },
+    "deck-fill-deep": {
+      "type": "color",
+      "value": "#10263A"
+    },
+    "surface-ink": {
+      "type": "color",
+      "value": "#132033"
+    },
+    "surface-muted": {
+      "type": "color",
+      "value": "#5D6673"
+    },
+    "accent-amber": {
+      "type": "color",
+      "value": "#C98A2B"
+    }
+  },
+  "children": [
+    {
+      "type": "frame",
+      "id": "healthy",
+      "x": 0,
+      "y": 0,
+      "name": "Diagnostics Console / Healthy",
+      "width": 420,
+      "fill": "$surface-bg",
+      "layout": "vertical",
+      "gap": 18,
+      "padding": [
+        18,
+        18,
+        24,
+        18
+      ],
+      "children": [
+        {
+          "type": "frame",
+          "id": "deckHealthy",
+          "name": "Command Deck",
+          "width": "fill_container",
+          "fill": [
+            {
+              "type": "gradient",
+              "gradientType": "linear",
+              "enabled": true,
+              "rotation": 180,
+              "size": {
+                "height": 1
+              },
+              "colors": [
+                {
+                  "color": "$deck-fill",
+                  "position": 0
+                },
+                {
+                  "color": "$deck-fill-deep",
+                  "position": 1
+                }
+              ]
+            },
+            "#FFFFFF12"
+          ],
+          "cornerRadius": 26,
+          "effect": {
+            "type": "shadow",
+            "shadowType": "outer",
+            "color": "#0B16231F",
+            "offset": {
+              "x": 0,
+              "y": 14
+            },
+            "blur": 28
+          },
+          "layout": "vertical",
+          "gap": 14,
+          "padding": 22,
+          "children": [
+            {
+              "type": "text",
+              "id": "healthyEyebrow",
+              "name": "heroEyebrow",
+              "content": "Diagnostics",
+              "fill": "$accent-amber",
+              "fontFamily": "Inter",
+              "fontSize": 12,
+              "fontWeight": "700",
+              "letterSpacing": 1.4
+            },
+            {
+              "type": "text",
+              "id": "healthyTitle",
+              "name": "heroTitle",
+              "content": "Healthy runway",
+              "fill": "#FFFDF8",
+              "fontFamily": "Inter",
+              "fontSize": 28,
+              "fontWeight": "700",
+              "textGrowth": "fixed-width",
+              "width": "fill_container"
+            }
+          ]
+        },
+        {
+          "type": "frame",
+          "id": "panelHealthy",
+          "name": "Runway Panel",
+          "width": "fill_container",
+          "fill": "$surface-panel",
+          "cornerRadius": 24,
+          "stroke": {
+            "fill": "$surface-border",
+            "thickness": 1
+          },
+          "layout": "vertical",
+          "gap": 12,
+          "padding": 18,
+          "children": [
+            {
+              "type": "text",
+              "id": "panelHealthyTitle",
+              "name": "panelTitle",
+              "content": "Launch blocking scenarios",
+              "fill": "$surface-ink",
+              "fontFamily": "Inter",
+              "fontSize": 24,
+              "fontWeight": "700",
+              "textGrowth": "fixed-width",
+              "width": "fill_container"
+            },
+            {
+              "type": "text",
+              "id": "panelHealthyBody",
+              "name": "panelBody",
+              "content": "Routine and high-risk controls are separated so the dangerous path always reads clearly.",
+              "fill": "$surface-muted",
+              "fontFamily": "Inter",
+              "fontSize": 14,
+              "fontWeight": "normal",
+              "lineHeight": 1.45,
+              "textGrowth": "fixed-width",
+              "width": "fill_container"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "frame",
+      "id": "degraded",
+      "x": 500,
+      "y": 0,
+      "name": "Diagnostics Console / Degraded",
+      "width": 420,
+      "fill": "$surface-bg",
+      "layout": "vertical",
+      "gap": 18,
+      "padding": [
+        18,
+        18,
+        24,
+        18
+      ],
+      "children": [
+        {
+          "type": "frame",
+          "id": "deckDegraded",
+          "name": "Command Deck",
+          "width": "fill_container",
+          "fill": [
+            {
+              "type": "gradient",
+              "gradientType": "linear",
+              "enabled": true,
+              "rotation": 180,
+              "size": {
+                "height": 1
+              },
+              "colors": [
+                {
+                  "color": "$deck-fill",
+                  "position": 0
+                },
+                {
+                  "color": "$deck-fill-deep",
+                  "position": 1
+                }
+              ]
+            },
+            "#FFFFFF12"
+          ],
+          "cornerRadius": 26,
+          "effect": {
+            "type": "shadow",
+            "shadowType": "outer",
+            "color": "#0B16231F",
+            "offset": {
+              "x": 0,
+              "y": 14
+            },
+            "blur": 28
+          },
+          "layout": "vertical",
+          "gap": 14,
+          "padding": 22,
+          "children": [
+            {
+              "type": "text",
+              "id": "degradedEyebrow",
+              "name": "heroEyebrow",
+              "content": "Diagnostics",
+              "fill": "$accent-amber",
+              "fontFamily": "Inter",
+              "fontSize": 12,
+              "fontWeight": "700",
+              "letterSpacing": 1.4
+            },
+            {
+              "type": "text",
+              "id": "degradedTitle",
+              "name": "heroTitle",
+              "content": "Degraded runway",
+              "fill": "#FFFDF8",
+              "fontFamily": "Inter",
+              "fontSize": 28,
+              "fontWeight": "700",
+              "textGrowth": "fixed-width",
+              "width": "fill_container"
+            }
+          ]
+        },
+        {
+          "type": "frame",
+          "id": "panelDegraded",
+          "name": "Runway Panel",
+          "width": "fill_container",
+          "fill": "$surface-panel",
+          "cornerRadius": 24,
+          "stroke": {
+            "fill": "$surface-border",
+            "thickness": 1
+          },
+          "layout": "vertical",
+          "gap": 12,
+          "padding": 18,
+          "children": [
+            {
+              "type": "text",
+              "id": "panelDegradedTitle",
+              "name": "panelTitle",
+              "content": "Signal drift detected",
+              "fill": "$surface-ink",
+              "fontFamily": "Inter",
+              "fontSize": 24,
+              "fontWeight": "700",
+              "textGrowth": "fixed-width",
+              "width": "fill_container"
+            },
+            {
+              "type": "text",
+              "id": "panelDegradedBody",
+              "name": "panelBody",
+              "content": "Telemetry stays legible while the top surface shifts the operator toward the corrective lane.",
+              "fill": "$surface-muted",
+              "fontFamily": "Inter",
+              "fontSize": 14,
+              "fontWeight": "normal",
+              "lineHeight": 1.45,
+              "textGrowth": "fixed-width",
+              "width": "fill_container"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

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.");

package/scripts/test-pen-persistence.js

@@ -0,0 +1,110 @@
+const assert = require("assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  buildPenDocument,
+  writePenFromPayloadFiles,
+  snapshotPenFile
+} = require("../lib/pen-persistence");
+
+const fixturePath = path.join(__dirname, "fixtures", "complex-sample.pen");
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+function createTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-pen-persistence-"));
+}
+
+runTest("buildPenDocument preserves fixture structure", () => {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+  const document = buildPenDocument({
+    version: fixture.version,
+    nodes: { nodes: fixture.children },
+    variables: { variables: fixture.variables }
+  });
+
+  assert.deepEqual(document, fixture);
+});
+
+runTest("writePenFromPayloadFiles writes and reopens a complex sample", () => {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+  const tempDir = createTempDir();
+  const nodesFile = path.join(tempDir, "nodes.json");
+  const variablesFile = path.join(tempDir, "variables.json");
+  const outputPath = path.join(tempDir, "written.pen");
+
+  fs.writeFileSync(nodesFile, JSON.stringify({ nodes: fixture.children }, null, 2));
+  fs.writeFileSync(variablesFile, JSON.stringify({ variables: fixture.variables }, null, 2));
+
+  const result = writePenFromPayloadFiles({
+    outputPath,
+    nodesFile,
+    variablesFile,
+    version: fixture.version,
+    verifyWithPencil: true
+  });
+
+  const written = JSON.parse(fs.readFileSync(outputPath, "utf8"));
+  assert.deepEqual(written, fixture);
+  assert.deepEqual(result.verification.topLevelIds, fixture.children.map((node) => node.id));
+});
+
+runTest("snapshotPenFile round-trips a complex sample", () => {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+  const tempDir = createTempDir();
+  const outputPath = path.join(tempDir, "snapshotted.pen");
+
+  const result = snapshotPenFile({
+    inputPath: fixturePath,
+    outputPath,
+    verifyWithPencil: true
+  });
+
+  const written = JSON.parse(fs.readFileSync(outputPath, "utf8"));
+  assert.deepEqual(written, fixture);
+  assert.deepEqual(result.verification.topLevelIds, fixture.children.map((node) => node.id));
+});
+
+runTest("truncated nodes payload is rejected", () => {
+  const tempDir = createTempDir();
+  const nodesFile = path.join(tempDir, "nodes.json");
+  const outputPath = path.join(tempDir, "bad.pen");
+
+  fs.writeFileSync(
+    nodesFile,
+    JSON.stringify(
+      {
+        nodes: [
+          {
+            type: "frame",
+            id: "bad",
+            children: "..."
+          }
+        ]
+      },
+      null,
+      2
+    )
+  );
+
+  assert.throws(
+    () =>
+      writePenFromPayloadFiles({
+        outputPath,
+        nodesFile,
+        version: "2.9"
+      }),
+    /truncated/i
+  );
+});
+
+console.log("All .pen persistence tests passed.");