@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

package/lib/mcp-runtime-gate.js

@@ -0,0 +1,342 @@
+const path = require("path");
+
+const PASS = "PASS";
+const WARN = "WARN";
+const BLOCK = "BLOCK";
+const SKIP = "SKIP";
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value.filter(Boolean) : [];
+}
+
+function normalizeLiveScreens(liveScreens) {
+  return normalizeArray(liveScreens).map((screen) => ({
+    id: screen && screen.id ? String(screen.id) : "",
+    name: screen && screen.name ? String(screen.name) : ""
+  }));
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function getScreenIds(liveScreens) {
+  return unique(normalizeLiveScreens(liveScreens).map((screen) => screen.id).filter(Boolean));
+}
+
+function getScreenNames(liveScreens) {
+  return unique(normalizeLiveScreens(liveScreens).map((screen) => screen.name).filter(Boolean));
+}
+
+function normalizeEditorName(activeEditor) {
+  return typeof activeEditor === "string" ? activeEditor.trim() : "";
+}
+
+function normalizeRegisteredPath(registeredPenPath) {
+  return typeof registeredPenPath === "string" ? registeredPenPath.trim() : "";
+}
+
+function resolveProjectPath(projectRoot, targetPath) {
+  if (!targetPath) {
+    return "";
+  }
+
+  if (path.isAbsolute(targetPath)) {
+    return path.normalize(targetPath);
+  }
+
+  if (!projectRoot) {
+    return "";
+  }
+
+  return path.normalize(path.resolve(projectRoot, targetPath));
+}
+
+function isUnnamedEditor(activeEditor) {
+  const normalized = normalizeEditorName(activeEditor).toLowerCase();
+  return normalized === "" || normalized === "new";
+}
+
+function matchesRegisteredPath(activeEditor, registeredPenPath, projectRoot) {
+  const editor = normalizeEditorName(activeEditor);
+  const registered = normalizeRegisteredPath(registeredPenPath);
+
+  if (!editor || !registered) {
+    return false;
+  }
+
+  const resolvedEditor = resolveProjectPath(projectRoot, editor);
+  const resolvedRegistered = resolveProjectPath(projectRoot, registered);
+
+  if (resolvedEditor && resolvedRegistered) {
+    return resolvedEditor === resolvedRegistered;
+  }
+
+  const editorHasPathSeparators = editor.includes("/") || editor.includes("\\");
+  if (editorHasPathSeparators) {
+    return false;
+  }
+
+  return path.basename(editor) === path.basename(registered);
+}
+
+function missingIds(expectedIds, actualIds) {
+  const actualSet = new Set(actualIds);
+  return unique(expectedIds).filter((id) => !actualSet.has(id));
+}
+
+function derivePhase(snapshot) {
+  return snapshot.phase || "completion";
+}
+
+function evaluateSourceConvergence(snapshot) {
+  const notes = [];
+  const activeEditor = normalizeEditorName(snapshot.activeEditor);
+  const registeredPenPath = normalizeRegisteredPath(snapshot.registeredPenPath);
+  const projectRoot = typeof snapshot.projectRoot === "string" ? snapshot.projectRoot.trim() : "";
+  const shellVisiblePenExists = Boolean(snapshot.shellVisiblePenExists);
+  const documentedReconciliation = Boolean(snapshot.documentedReconciliation);
+  const noNewPencilEditsYet = Boolean(snapshot.noNewPencilEditsYet);
+
+  if (Boolean(snapshot.mcpAvailable) === false) {
+    return {
+      status: WARN,
+      notes: ["Pencil MCP is unavailable, so runtime source convergence could not be fully checked."]
+    };
+  }
+
+  if (isUnnamedEditor(activeEditor)) {
+    return {
+      status: BLOCK,
+      notes: ["Active Pencil editor is still an unnamed live document such as `new`."]
+    };
+  }
+
+  if (!registeredPenPath) {
+    return {
+      status: BLOCK,
+      notes: ["No registered project-local `.pen` path was provided for runtime comparison."]
+    };
+  }
+
+  if (!shellVisiblePenExists) {
+    return {
+      status: BLOCK,
+      notes: ["The registered project-local `.pen` file is not shell-visible on disk."]
+    };
+  }
+
+  if (!matchesRegisteredPath(activeEditor, registeredPenPath, projectRoot)) {
+    if (documentedReconciliation) {
+      return {
+        status: WARN,
+        notes: [
+          "Active Pencil editor does not match the registered project-local `.pen` path, but a documented reconciliation was provided."
+        ]
+      };
+    }
+
+    return {
+      status: BLOCK,
+      notes: ["Active Pencil editor does not match the registered project-local `.pen` path."]
+    };
+  }
+
+  if (noNewPencilEditsYet) {
+    notes.push("No new Pencil edits were recorded yet; source convergence is only provisionally confirmed.");
+    return {
+      status: WARN,
+      notes
+    };
+  }
+
+  return {
+    status: PASS,
+    notes: ["Active Pencil editor matches the registered project-local `.pen` source and the file exists on disk."]
+  };
+}
+
+function evaluateScreenPresence(snapshot) {
+  const phase = derivePhase(snapshot);
+  const claimedAnchorIds = normalizeArray(snapshot.claimedAnchorIds);
+  const claimedReviewedScreenIds = normalizeArray(snapshot.claimedReviewedScreenIds);
+  const reviewTargets = normalizeArray(snapshot.reviewTargets);
+  const liveIds = getScreenIds(snapshot.liveScreens);
+
+  if (Boolean(snapshot.mcpAvailable) === false) {
+    return {
+      status: WARN,
+      notes: ["Pencil MCP is unavailable, so live screen presence could not be fully checked."]
+    };
+  }
+
+  if (phase === "first_write" && claimedAnchorIds.length === 0 && claimedReviewedScreenIds.length === 0 && reviewTargets.length === 0) {
+    return {
+      status: SKIP,
+      notes: ["No anchor or review ids were declared yet, so screen-presence checks were skipped at first-write stage."]
+    };
+  }
+
+  const missingAnchorIds = missingIds(claimedAnchorIds, liveIds);
+  const missingReviewedIds = missingIds(claimedReviewedScreenIds, liveIds);
+  const missingReviewTargets = missingIds(reviewTargets, liveIds);
+
+  const notes = [];
+  if (missingAnchorIds.length > 0) {
+    notes.push(`Missing claimed anchor ids in the active editor: ${missingAnchorIds.join(", ")}`);
+  }
+  if (missingReviewedIds.length > 0) {
+    notes.push(`Missing claimed reviewed screen ids in the active editor: ${missingReviewedIds.join(", ")}`);
+  }
+  if (missingReviewTargets.length > 0) {
+    notes.push(`Missing screenshot target ids in the active editor: ${missingReviewTargets.join(", ")}`);
+  }
+
+  if (notes.length > 0) {
+    return {
+      status: BLOCK,
+      notes
+    };
+  }
+
+  if (claimedAnchorIds.length === 0 && claimedReviewedScreenIds.length === 0 && reviewTargets.length === 0) {
+    return {
+      status: WARN,
+      notes: ["No claimed anchor, reviewed, or screenshot target ids were provided for runtime verification."]
+    };
+  }
+
+  return {
+    status: PASS,
+    notes: ["Claimed anchor surfaces and review targets resolve in the active live editor."]
+  };
+}
+
+function evaluateReviewExecution(snapshot) {
+  const phase = derivePhase(snapshot);
+  const claimedReviewedScreenIds = normalizeArray(snapshot.claimedReviewedScreenIds);
+  const reviewTargets = normalizeArray(snapshot.reviewTargets);
+  const reviewBlockersIgnored = Boolean(snapshot.reviewBlockersIgnored);
+  const broadExpansionRequested = Boolean(snapshot.broadExpansionRequested);
+
+  if (Boolean(snapshot.mcpAvailable) === false) {
+    return {
+      status: WARN,
+      notes: ["Pencil MCP is unavailable, so runtime review execution could not be fully checked."]
+    };
+  }
+
+  if (phase === "first_write") {
+    return {
+      status: SKIP,
+      notes: ["Screenshot review is not required at first-write stage."]
+    };
+  }
+
+  if (claimedReviewedScreenIds.length === 0 && reviewTargets.length === 0) {
+    if (phase === "completion" || broadExpansionRequested) {
+      return {
+        status: BLOCK,
+        notes: ["No reviewed screen ids or screenshot targets were recorded for a stage that requires runtime review evidence."]
+      };
+    }
+
+    return {
+      status: WARN,
+      notes: ["No reviewed screen ids or screenshot targets were recorded yet."]
+    };
+  }
+
+  if (reviewBlockersIgnored) {
+    return {
+      status: BLOCK,
+      notes: ["Screenshot review recorded blocker-level issues that were ignored while the surface was still treated as approved."]
+    };
+  }
+
+  return {
+    status: PASS,
+    notes: ["Runtime review evidence exists for the approved surfaces."]
+  };
+}
+
+function combineStatuses(statuses) {
+  if (statuses.includes(BLOCK)) {
+    return BLOCK;
+  }
+  if (statuses.includes(WARN)) {
+    return WARN;
+  }
+  if (statuses.every((status) => status === SKIP)) {
+    return WARN;
+  }
+  return PASS;
+}
+
+function evaluateMcpRuntimeGate(snapshot = {}) {
+  const sourceConvergence = evaluateSourceConvergence(snapshot);
+  const screenPresence = evaluateScreenPresence(snapshot);
+  const reviewExecution = evaluateReviewExecution(snapshot);
+
+  const finalStatus = combineStatuses([
+    sourceConvergence.status,
+    screenPresence.status === SKIP ? PASS : screenPresence.status,
+    reviewExecution.status === SKIP ? PASS : reviewExecution.status
+  ]);
+
+  return {
+    phase: derivePhase(snapshot),
+    sourceConvergence,
+    screenPresence,
+    reviewExecution,
+    finalStatus,
+    activeEditor: normalizeEditorName(snapshot.activeEditor),
+    registeredPenPath:
+      typeof snapshot.registeredPenPath === "string" ? snapshot.registeredPenPath.trim() : "",
+    shellVisiblePenPath:
+      typeof snapshot.shellVisiblePenPath === "string" ? snapshot.shellVisiblePenPath.trim() : "",
+    shellVisiblePenExists: Boolean(snapshot.shellVisiblePenExists),
+    claimedAnchorIds: normalizeArray(snapshot.claimedAnchorIds),
+    claimedReviewedScreenIds: normalizeArray(snapshot.claimedReviewedScreenIds),
+    reviewTargets: normalizeArray(snapshot.reviewTargets),
+    liveScreenIds: getScreenIds(snapshot.liveScreens),
+    liveScreenNames: getScreenNames(snapshot.liveScreens)
+  };
+}
+
+function formatMcpRuntimeGateSection(snapshot, result, options = {}) {
+  const timestamp = options.timestamp || new Date().toISOString();
+  const notes = [
+    ...result.sourceConvergence.notes,
+    ...result.screenPresence.notes,
+    ...result.reviewExecution.notes
+  ];
+
+  return [
+    "## MCP Runtime Gate",
+    `- Time: ${timestamp}`,
+    `- Phase: ${result.phase}`,
+    `- Active editor: ${result.activeEditor || "(unavailable)"}`,
+    `- Registered \`.pen\` path: ${result.registeredPenPath || "(missing)"}`,
+    `- Shell-visible \`.pen\` path: ${result.shellVisiblePenPath || "(missing)"}`,
+    `- Shell-visible \`.pen\` exists: ${result.shellVisiblePenExists ? "yes" : "no"}`,
+    `- Claimed anchor ids: ${result.claimedAnchorIds.length > 0 ? result.claimedAnchorIds.join(", ") : "(none)"}`,
+    `- Reviewed screen ids: ${result.claimedReviewedScreenIds.length > 0 ? result.claimedReviewedScreenIds.join(", ") : "(none)"}`,
+    `- Screenshot target ids: ${result.reviewTargets.length > 0 ? result.reviewTargets.join(", ") : "(none)"}`,
+    `- Live screen ids: ${result.liveScreenIds.length > 0 ? result.liveScreenIds.join(", ") : "(none)"}`,
+    `- Source convergence: ${result.sourceConvergence.status}`,
+    `- Screen presence: ${result.screenPresence.status}`,
+    `- Review execution: ${result.reviewExecution.status}`,
+    `- Final runtime gate status: ${result.finalStatus}`,
+    `- Notes: ${notes.length > 0 ? notes.join(" | ") : "none"}`
+  ].join("\n");
+}
+
+module.exports = {
+  PASS,
+  WARN,
+  BLOCK,
+  SKIP,
+  evaluateMcpRuntimeGate,
+  formatMcpRuntimeGateSection
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"
@@ -21,7 +21,8 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
-    "validate-assets": "node scripts/validate-assets.js"
+    "validate-assets": "node scripts/validate-assets.js",
+    "test:mcp-runtime-gate": "node scripts/test-mcp-runtime-gate.js"
   },
   "engines": {
     "node": ">=18"

package/references/artifact-templates.md

@@ -36,6 +36,7 @@ project/
             ├── pencil-bindings.md
             ├── tasks.md
             ├── verification.md
+            ├── exports/
             └── specs/
                 └── <capability>/spec.md
 ```
@@ -175,8 +176,8 @@ Use this structure:
 
 Field meaning:
 
-- `Preferred adapters`: desired local-skill priority order
-- `Scope`: allowed presentation-quality influence areas only
+- `Preferred adapters`: desired local-skill priority order using adapter names that actually exist in the current environment
+- `Scope`: allowed presentation-quality influence areas only, including anchor-surface composition when redesign quality matters
 - `Fallback`: what to do when preferred adapters are unavailable
 - `Require Adapter`: whether missing adapters should block the workflow
 
@@ -214,6 +215,11 @@ Use this structure:
 - workspace density
 - responsiveness expectations
 
+## Layout Hygiene Profile
+- Resolved profile: mobile / tablet / desktop / web
+- Per-surface overrides when mixed product surfaces require them
+- Blocker classes to watch during screenshot review
+
 ## Notes
 - explicit user preferences
 - inferred preferences
@@ -243,6 +249,7 @@ Use this structure:
 - Which `.pen` file is authoritative
 - Why that file should be preferred over live-only or external sources
 - whether the active Pencil editor matches that same path
+- whether the active Pencil editor is still an unnamed live document that must be reconciled before completion
 
 ## Visual Adapter Resolution
 - Requested adapters
@@ -483,7 +490,9 @@ Use this structure:
 - Which 1-3 anchor screens were designed first
 - Structural-delta summary for each anchor surface
 - Screenshot review status for each anchor
+- Applied layout-hygiene profile for each reviewed anchor surface
 - Whether screenshot review found hierarchy, spacing, clarity, or inconsistency issues
+- Whether screenshot review found blocker-level layout-hygiene issues
 - Whether each anchor was revised after screenshot review
 - Whether broad multi-screen expansion is approved yet
 
@@ -504,7 +513,30 @@ Use this structure:
 - Which states still need design coverage
 
 ## Screenshots
-- Reference image paths or exported nodes
+- Reference image paths or exported nodes under `.da-vinci/changes/<change-id>/exports/`
+
+## MCP Runtime Gate
+- Time
+- Phase
+- Active editor
+- Registered `.pen` path
+- Shell-visible `.pen` path
+- Shell-visible `.pen` exists
+- Claimed anchor ids
+- Reviewed screen ids
+- Screenshot target ids
+- Live screen ids
+- `Source convergence`
+- `Screen presence`
+- `Review execution`
+- `Final runtime gate status`
+- Notes
+
+## Checkpoint Status
+- `mcp runtime gate`
+- `design-source checkpoint`
+- `design checkpoint`
+- `completion gate`
 
 ## Implementation Notes
 - Important layout or styling constraints to preserve in code

package/references/checkpoints.md

@@ -48,6 +48,7 @@ Check:
 - the active mode is correct
 - the starting material is stable enough to write specs
 - product form factor and visual direction are known, inferred, or explicitly deferred
+- the form factor is specific enough to resolve the active layout-hygiene profile before screenshot review begins
 - candidate pages or current pages are clear enough to move into `page-map.md`
 - open questions are explicitly tracked
 - workflow artifacts are being written to standard locations, especially keeping `.da-vinci/designs/` for `.pen` files rather than markdown notes
@@ -101,6 +102,7 @@ Check:
 - when a primary adapter is active, the workflow wrote a visual thesis, content plan, and interaction thesis before broad anchor-surface generation
 - complex redesigns have 1-3 fully composed anchor surfaces reviewed before broad multi-screen expansion
 - each anchor surface includes a short explanation of how its composition differs structurally from the current layout truth
+- the relevant form-factor-specific layout-hygiene profile was applied to each reviewed anchor surface and any other screen being treated as approval-ready
 - each page has a clear visual anchor or primary working surface
 - section hierarchy is readable without relying on decorative chrome
 - the design does not collapse into generic card-grid or border-heavy filler UI
@@ -118,10 +120,13 @@ Result meanings:
 
 Automatic failures:
 
+- if anchor-surface design starts before the required discovery artifacts and design-source artifacts exist in their standard locations, treat the design checkpoint as `BLOCK`
 - if broad Pencil generation starts before anchor surfaces are compositionally stable, treat the design checkpoint as `BLOCK`
 - if more than roughly 20% of a screen's primary content area is unresolved placeholder scaffolding, treat the design checkpoint as `BLOCK`
 - if multiple screens are effectively the same scaffold with title changes, treat the design checkpoint as `BLOCK`
 - if screenshot review or image analysis calls out hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues and the workflow marks the screen as passed without revision, treat the design checkpoint as `BLOCK`
+- if any blocker-level condition from the active form-factor-specific layout-hygiene profile is present on a reviewed screen, treat the design checkpoint as `BLOCK`
+- if an anchor surface required repeated rolled-back Pencil batches from unsupported properties and the workflow still treats that surface as approved without a clean schema-safe pass, treat the design checkpoint as `BLOCK`
 - if a redesign screen materially mirrors the current XML grouping with only recolor, spacing tweaks, or minor rearrangement, treat the design checkpoint as `BLOCK`
 
 ## `design-source checkpoint`
@@ -133,9 +138,11 @@ Check:
 - `design-registry.md` records one specific preferred project-local `.pen` path
 - the preferred `.pen` path is workflow-owned state, not a hand-wavy placeholder
 - the active Pencil editor path matches the preferred project-local `.pen` path, or the mismatch has been reconciled explicitly
+- an unnamed live editor such as `new` is not being treated as the persisted project-local design source
 - if the workflow created or edited Pencil work, the preferred project-local `.pen` file exists as a shell-visible file immediately after the first successful Pencil write, not just at workflow close
 - if Pencil MCP only exposed a live document, the workflow reconstructed and wrote the registered project-local `.pen` file from MCP-readable document data before continuing
-- `.da-vinci/designs/` is being used cleanly for project-local `.pen` files rather than mixed with workflow markdown
+- `.da-vinci/designs/` is being used cleanly for project-local `.pen` files rather than mixed with workflow markdown, screenshots, or other exports
+- exported screenshots are stored under `.da-vinci/changes/<change-id>/exports/` and are not being used as a substitute for the `.pen` source
 - `design-registry.md`, `pencil-design.md`, and `pencil-bindings.md` describe the same active project-local `.pen` source clearly enough to map and implement from
 
 Result meanings:
@@ -144,6 +151,36 @@ Result meanings:
 - `WARN`: the workflow is intentionally staying on an older but still shell-visible baseline, or no new Pencil edits have happened yet
 - `BLOCK`: the registered `.pen` path, the active Pencil work, and the shell-visible project-local file do not agree well enough to treat the design source as traceable
 
+## `mcp runtime gate`
+
+Run inside the active design session when Pencil MCP is available:
+
+- after the first successful Pencil write
+- before broad expansion beyond approved anchor surfaces
+- before any terminal `design complete` or `workflow complete` claim
+
+Check:
+
+- the active editor is not still an unnamed live document such as `new`
+- the active editor, registered project-local `.pen` path, and shell-visible `.pen` file are converged strongly enough to trust the runtime source
+- claimed anchor ids exist in the active live editor
+- claimed reviewed screens and screenshot targets exist in the active live editor
+- screenshot-reviewed surfaces were not treated as approved while blocker-level review findings were ignored
+- runtime-gate evidence is recorded in `pencil-design.md`
+
+Result meanings:
+
+- `PASS`: runtime source and live screen state are trustworthy enough to continue
+- `WARN`: runtime evidence is partial or intentionally deferred, but not yet contradictory
+- `BLOCK`: runtime truth is too weak or contradictory to continue or claim completion
+
+Automatic failures:
+
+- if the active editor is still `new`, treat the runtime gate as `BLOCK`
+- if live anchor surfaces exist only in the current editor while no shell-visible `.pen` exists, treat the runtime gate as `BLOCK`
+- if claimed anchor ids, reviewed screen ids, or screenshot targets do not resolve in the active editor, treat the runtime gate as `BLOCK`
+- if blocker-level review findings were ignored while the workflow still approved the surface, treat the runtime gate as `BLOCK`
+
 ## `mapping checkpoint`
 
 Run after `design-registry.md` and `pencil-bindings.md`.
@@ -154,6 +191,7 @@ Check:
 - the preferred `.pen` path in `design-registry.md` is workflow-owned and specific, not hand-wavy
 - the active Pencil editor path matches the preferred project-local `.pen` path, or the project-local file has been reconstructed explicitly
 - the preferred project-local `.pen` file exists as a shell-visible file when the workflow created or edited Pencil work
+- exported screenshots are treated only as review artifacts, not as page-to-design source of truth
 - each implementation page has a Pencil page or an explicit exception
 - shared layouts and shared regions are bound clearly enough to implement from
 - route names and Pencil names are traceable
@@ -202,9 +240,39 @@ Examples of `BLOCK`:
 - page-to-Pencil bindings are too weak to know which redesign screen to follow
 - `design-registry.md` points to a project-local `.pen` path, but the workflow actually edited a different live editor document and did not reconcile the mismatch
 - the workflow created or edited Pencil pages but no shell-visible `.pen` file exists under the registered project-local path
+- `.da-vinci/designs/` contains workflow markdown or screenshot exports instead of `.pen` files only
 - required permissions, environment access, or protected files are unavailable
 - the implementation would overwrite the project baseline in a destructive way without an explicit go-ahead
 
+## `completion gate`
+
+Apply before reporting `design complete`, `workflow complete`, or any equivalent terminal state.
+
+When shell access is available:
+
+- use `da-vinci audit --mode integrity <project-path>` as a filesystem-truth sanity check during active work
+- use `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+- treat an audit failure as `BLOCK`
+
+Check:
+
+- the artifacts required for the active intent actually exist in their standard locations
+- for `redesign-from-code` with active Pencil work, this normally includes `project-inventory.md`, `page-map.md`, `design-registry.md`, `design-brief.md`, `design.md`, `pencil-design.md`, and `pencil-bindings.md`
+- if Pencil work happened, `design-source checkpoint` is at least `PASS`
+- if design output is being treated as ready, `design checkpoint` is at least `PASS` or an explicitly accepted `WARN`
+- if Pencil MCP is available, `mcp runtime gate` is at least `PASS` or an explicitly accepted `WARN`
+- the registered project-local `.pen` file exists as a shell-visible file
+- the active Pencil editor is not still an unnamed live document such as `new`
+- `.da-vinci/designs/` contains `.pen` files only
+- exported screenshots, if any, live under `.da-vinci/changes/<change-id>/exports/`
+- screenshots are recorded only as review artifacts and not described as the persisted design source
+
+Automatic failures:
+
+- if the workflow claims the `.pen` source exists only "in memory", treat completion as `BLOCK`
+- if the workflow claims success after exporting PNGs but without a shell-visible `.pen`, treat completion as `BLOCK`
+- if the workflow reports completion without the required standard artifacts for the active stage, treat completion as `BLOCK`
+
 ## `execution checkpoint`
 
 Run after each top-level task group during implementation.

package/references/design-inputs.md

@@ -9,7 +9,7 @@ Check for `DA-VINCI.md` first, then check whether the project already has persis
 - if it exists, treat it as the project visual contract
 - if `DA-VINCI.md` declares preferred visual adapters, treat them as optional design-assist preferences
 - if `.da-vinci/designs/*.pen` exists, treat those files as project-local design inputs and record the exact preferred path in `design-registry.md`
-- treat non-`.pen` files inside `.da-vinci/designs/` as artifact-placement drift that must be corrected instead of as valid design inputs
+- treat non-`.pen` files inside `.da-vinci/designs/` as artifact-placement drift that must be corrected instead of as valid design inputs; screenshot exports belong under `.da-vinci/changes/<change-id>/exports/`
 - if it does not exist, generate it from the best stable inputs before broad Pencil page generation
 - avoid re-deriving the visual language page by page
 
@@ -37,6 +37,7 @@ If Pencil MCP is currently pointing at a different active editor:
 
 - switch to the registered project-local path when possible
 - otherwise reconstruct the project-local `.pen` file from MCP-readable document data before treating the workflow as traceable
+- do not treat an unnamed live editor such as `new` as the resolved project-local path
 
 ## Minimum Inputs
 
@@ -72,6 +73,11 @@ Collect or infer:
    - whether adapter use is required or optional
    - fallback expectation when adapters are unavailable
 
+6. layout hygiene profile
+   - resolved from the product form factor
+   - per-surface override only when the product intentionally mixes different surface classes
+   - blocker classes that must fail screenshot review
+
 ## Inference Order
 
 Infer in this order:
@@ -97,6 +103,8 @@ Examples:
 
 Write stable answers into `design-brief.md`.
 
+Record the resolved layout-hygiene profile there as well, including any intentional per-surface overrides for mixed products.
+
 If `DA-VINCI.md` did not already exist, generate it from those stable answers and save it as the project visual baseline.
 
 If Pencil creates or updates a baseline during the workflow: