@xenonbyte/da-vinci-workflow 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## Unreleased
+## v0.1.16 - 2026-03-28
+
+### Added
+- `da-vinci preflight-pencil` as a static preflight for non-trivial Pencil `batch_design` payloads, catching common syntax and schema drift before they hit MCP
+- `da-vinci write-pen` to atomically write a project-local `.pen` from MCP-readable node and variable snapshot data
+- `da-vinci snapshot-pen` to reopen an existing `.pen`, capture a fresh MCP-readable snapshot, and rewrite a canonical project-local `.pen` with reopen verification
+
+### Changed
+- active Pencil guidance now requires smaller anchor-surface batches, micro-batch fallback after repeated rollbacks, and structured screenshot-review records instead of self-affirming prose
+- design routes, prompt presets, workflow examples, and README guidance now call for `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write during active redesign work
+- project-local `.pen` persistence now treats headless interactive `save()` as non-authoritative; first-run sessions must persist the first approved live MCP snapshot, and resume sessions must overwrite the registered `.pen` from the current snapshot after material live edits
 
 ## v0.1.15 - 2026-03-27
 

package/README.md

@@ -27,10 +27,13 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.14`
+- `@xenonbyte/da-vinci-workflow@0.1.16`
 
 Release highlights:
 
+- project-local `.pen` persistence now uses an MCP-snapshot-to-disk path instead of relying on headless interactive `save()`
+- `da-vinci write-pen` now atomically writes workflow-owned `.pen` files from MCP-readable node and variable payloads with optional reopen verification
+- `da-vinci snapshot-pen` now rebuilds a canonical local `.pen` from an existing Pencil source and verifies reopen with Pencil
 - visual-adapter execution now requires explicit runtime declaration of the resolved primary adapter and any unavailable requested adapters
 - cross-platform near-name adapters such as `frontend-skill` and `frontend-design` are now treated as distinct unless the current environment explicitly resolves them
 - complex `redesign-from-code` runs now require a visual thesis, content plan, interaction thesis, and anchor-surface structural-delta notes before broad Pencil generation
@@ -416,6 +419,7 @@ da-vinci status
 da-vinci validate-assets
 da-vinci audit --mode integrity /abs/path/to/project
 da-vinci audit --mode completion --change <change-id> /abs/path/to/project
+da-vinci preflight-pencil --ops-file /abs/path/to/ops.txt
 da-vinci uninstall --platform codex,claude,gemini
 ```
 
@@ -432,7 +436,26 @@ Both modes check the most common workflow-integrity failures in a project:
 - screenshot exports stored in the wrong place
 - empty or partial change scaffolds
 
+`da-vinci preflight-pencil` is a static guard for non-trivial `batch_design` payloads:
+
+- catches JS-like syntax mistakes before they hit Pencil MCP
+- flags common schema drift such as bad `padding`, invalid hex colors, `flex`, `margin`, and `overflow`
+- warns when anchor-surface batches are too large and should be split before retrying
+
 When Pencil MCP is active, Da Vinci now also expects an MCP runtime gate record in `pencil-design.md` before terminal completion claims. That runtime gate checks live editor/source convergence separately from filesystem audit.
+During active redesign work, prefer running `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write, then use `da-vinci preflight-pencil` plus smaller follow-up batches if the same anchor surface rolls back twice.
+
+Project-local `.pen` persistence now has two supported paths:
+
+- first-run path: if no registered project-local `.pen` exists yet, let the first approved anchor surface happen in the live editor, then persist that approved MCP snapshot under `.da-vinci/designs/`
+- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it
+
+Persistence helpers:
+
+- `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`
+
+Do not treat headless interactive `save()` as authoritative persistence truth until the underlying Pencil behavior is proven reliable again.
 
 Installation targets:
 

package/README.zh-CN.md

@@ -29,10 +29,13 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.14`
+- `@xenonbyte/da-vinci-workflow@0.1.16`
 
 已发布版本重点：
 
+- 项目内 `.pen` 持久化现在改为“从 MCP 快照写回磁盘”的正式路径，不再依赖 headless interactive `save()`
+- `da-vinci write-pen` 现在可以把 MCP 可读的节点和变量快照原子写成工作流管理的 `.pen` 文件，并可选地做 reopen 校验
+- `da-vinci snapshot-pen` 现在可以从现有 Pencil 源重建一个规范化的本地 `.pen`，并验证重新打开结果
 - visual adapter 的执行现在要求在运行时明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
 - `frontend-skill`、`frontend-design` 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
 - 复杂 `redesign-from-code` 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
@@ -345,6 +348,7 @@ da-vinci status
 da-vinci validate-assets
 da-vinci audit --mode integrity /abs/path/to/project
 da-vinci audit --mode completion --change <change-id> /abs/path/to/project
+da-vinci preflight-pencil --ops-file /abs/path/to/ops.txt
 da-vinci uninstall --platform codex,claude,gemini
 ```
 
@@ -361,7 +365,27 @@ da-vinci uninstall --platform codex,claude,gemini
 - 截图导出写到了错误位置
 - change scaffold 只有空目录或只写了一半
 
+`da-vinci preflight-pencil` 是给非小型 `batch_design` 用的静态预检：
+
+- 在发给 Pencil MCP 之前先抓出 JS-like 语法错误
+- 直接标出常见 schema 漂移，比如错误 `padding`、非法 hex 颜色、`flex`、`margin`、`overflow`
+- 当 anchor-surface 批次太大时给出拆批警告，避免继续大块回滚
+
 当 Pencil MCP 可用时，Da Vinci 现在还要求在终态完成声明前，把 MCP runtime gate 结果记录到 `pencil-design.md`。这层 gate 负责检查 live editor/source convergence，与 filesystem audit 分工不同。
+在重设计进行中，建议在第一次成功写入 Pencil 后立即运行 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚，则继续配合 `da-vinci preflight-pencil` 和更小的 follow-up batch。
+
+项目内 `.pen` 持久化现在分成两条受支持路径：
+
+- 首次运行路径：如果当前还没有登记的项目内 `.pen`，先允许第一个通过审查的 anchor surface 在 live editor 里完成，然后把这个 MCP 快照持久化到 `.da-vinci/designs/`
+- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 MCP 快照重新持久化回同一路径，而不是假设 interactive `save()` 已经刷回磁盘
+
+推荐使用的持久化命令：
+
+- `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`
+
+在 Pencil 底层 `save()` 语义再次被证明可靠之前，不要把 headless interactive `save()` 当作权威持久化真相。
+在重设计进行中，建议在第一次成功写入 Pencil 后立刻跑一次 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚两次，就配合 `da-vinci preflight-pencil` 改成更小的后续批次。
 
 安装目标：
 

package/SKILL.md

@@ -226,15 +226,24 @@ During active Pencil work:
 - do not begin anchor-surface generation until the required discovery and design-source artifacts exist in their standard locations for the active mode
 - keep `.da-vinci/designs/` reserved for project-local `.pen` files; do not write workflow markdown such as inventories, proposals, or checkpoints into that directory
 - on `redesign-from-code`, write a short structural-delta note for each anchor surface explaining how the new composition differs from the current XML or layout grouping
+- when shell access is available, preflight non-trivial `batch_design` operation strings before sending them to Pencil
+- prefer 12 or fewer operations on anchor-surface batches; if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
+- do not rely on headless interactive `save()` as the persistence truth; when live MCP edits exist, persist project-local `.pen` files from MCP-readable document snapshots
+- when no registered project-local `.pen` exists yet, let the first anchor work happen in the live editor, then persist the first complete MCP snapshot to the registered `.pen` path before broad expansion continues
+- when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to the 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` to atomically write the registered project-local `.pen` from MCP snapshot data
 - after the first successful Pencil write, verify that the registered project-local `.pen` path exists as a shell-visible file before treating the design source as persistent
+- after the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` when shell access is available before broad expansion continues
 - after the first successful Pencil write, run the MCP runtime gate when Pencil MCP is available and record the result in `pencil-design.md`
 - do not treat an unnamed live editor such as `new` as a persisted project design source; reconcile it to the registered project-local `.pen` path before the design pass is considered traceable
 - use only Pencil-supported properties; do not emit web- or CSS-only layout properties such as `flex` or `margin`
 - if unsupported Pencil properties cause repeated rolled-back batches on the same anchor surface, treat that pass as unstable and fix the schema usage before expanding further
+- after any rolled-back batch or structure-changing edit, refresh the live node structure before descendant-targeted follow-up operations; do not assume stale ids, bindings, or parent relationships are still valid
 - on complex redesigns, turn approved anchor surfaces into a small shared primitive family before broad page expansion
 - apply the resolved form-factor-specific layout hygiene profile before passing screenshot review on any anchor surface or other approval candidate
 - exported screenshots are review artifacts only; place them under `.da-vinci/changes/<change-id>/exports/` and never treat them as a substitute for the project-local `.pen` source
 - screenshot review is binding: if the review calls out hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues, revise the screen before treating the checkpoint as `PASS`
+- screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the concrete issue list and revision outcome; phrases such as "looks good" do not count as review evidence
 
 ## Load References On Demand
 

package/commands/claude/dv/design.md

@@ -18,5 +18,11 @@ Create or update:
 - `pencil-design.md`
 
 Run the `design checkpoint` before locking implementation tasks.
+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.
+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 a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
+Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
 Before reporting `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.

package/commands/codex/prompts/dv-design.md

@@ -12,5 +12,11 @@ Output should move the work toward:
 - `pencil-design.md`
 
 Use Pencil-backed structure as the design source when available.
+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.
+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 a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
+Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
 Before claiming `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.

package/commands/gemini/dv/design.toml

@@ -11,6 +11,12 @@ Create or update:
 - `pencil-design.md`
 
 Use Pencil-backed page coverage as the source of presentation truth.
+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.
+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 a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
+Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
 Before reporting `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.
 """

package/docs/mode-use-cases.md

@@ -138,7 +138,8 @@ 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`
@@ -355,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/.
 ```
@@ -48,8 +51,15 @@ 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/.
 ```
@@ -66,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.
 ```
 
@@ -76,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/.
 ```
@@ -52,11 +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/.
@@ -74,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.
 ```
 
@@ -84,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.
 ```
 

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

@@ -28,6 +28,9 @@ 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 the current tablet surfaces 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 ignores tablet-scale composition or collapses into a stretched phone layout.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -48,8 +51,15 @@ 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.
+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 collapses into a stretched phone layout, repeated placeholders, or weak multi-region hierarchy.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -66,6 +76,9 @@ Decompose complex pages 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.
 ```
 
@@ -76,8 +89,10 @@ $da-vinci use continue for this existing tablet-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/web-app.md

@@ -28,6 +28,9 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current product surfaces 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 generic SaaS card grid or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -49,8 +52,15 @@ Use Pencil guides only as responsive layout constraints, not as the design direc
 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.
+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 generic SaaS card grid, repeated placeholder scaffolds, or a recolor of the old interface.
 Persist project-local Pencil files under .da-vinci/designs/.
 ```
@@ -67,6 +77,9 @@ Decompose complex pages 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.
 ```
 
@@ -77,8 +90,10 @@ $da-vinci use continue for this existing web-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/visual-assist-presets/README.md

@@ -13,6 +13,11 @@ Use them together with:
 
 - `docs/prompt-presets/`
 
+These presets do not carry workflow completion gates by themselves:
+
+- keep MCP runtime gate requirements in the workflow prompt/checkpoint layer
+- keep `da-vinci audit --mode completion ...` in the workflow prompt/checkpoint layer
+
 If the project is design-critical or previous outputs were weak, generic, or too close to the old UI:
 
 - keep the same preset family

package/docs/workflow-examples.md

@@ -82,14 +82,20 @@ Expected flow:
 6. rebuild or refine `page-map.md`, including subpages, overlays, and materially different states
 7. write the visual thesis, content plan, interaction thesis, and structural-delta notes for the anchor surfaces
 8. create new or updated Pencil pages from fresh composition rather than a recolor of the old UI, preferring persistence under `.da-vinci/designs/`
-9. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
-10. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
-11. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-12. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
-13. bind routes and pages to Pencil screens
-14. generate tasks aligned to the redesign slices
-15. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
-16. build and verify only after the completion gate can eventually pass
+9. preflight non-trivial `batch_design` operation strings before sending them to Pencil, and keep anchor-surface batches small
+10. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
+11. if no registered project-local `.pen` existed at the start of the session, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`
+12. if a registered project-local `.pen` already existed, reopen it for continuity and persist fresh MCP snapshots back to that same path after material live edits
+13. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+14. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
+15. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
+16. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+17. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
+18. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
+19. bind routes and pages to Pencil screens
+20. generate tasks aligned to the redesign slices
+21. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+22. build and verify only after the completion gate can eventually pass
 
 ### Complex Android example
 
@@ -107,10 +113,16 @@ 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.
+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.
+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 a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
 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.
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
 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 `.pen` source exists only in memory or only as exported PNGs.
 Do not pass design checkpoint if the result is just a skin-swap of the old UI.
 ```
@@ -148,6 +160,8 @@ Use the visual-adapter preferences declared in DA-VINCI.md.
 If frontend-skill is available, use it as the primary visual adapter.
 If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
+If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot there.
+If a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
 ```
 
 ## Cross-mode rule

package/docs/zh-CN/mode-use-cases.md

@@ -91,7 +91,8 @@ Da Vinci 应该：
    - 优先登记 `.da-vinci/designs/` 下的本地 `.pen` 路径
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
-   - 确保当前设计真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -112,7 +113,8 @@ Da Vinci 应该：
 5. 生成 `specs/<capability>/spec.md`
 6. 生成 `page-map.md`
 7. 继续到设计、绑定、任务和实现
-   - 把当前设计真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
 
 ## 3. `redesign-from-code`
 
@@ -138,7 +140,8 @@ Da Vinci 应该：
    - 在大规模 anchor 设计前，先写 visual thesis、content plan、interaction thesis 和 structural-delta 说明
    - 先做 1 到 3 个 anchor surface，再扩展更多页面
    - 首轮设计由解析出来的主 visual adapter 主导
-   - 把新的 Pencil 基线真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
    - 在第一次成功写入 Pencil 后，立即验证登记的 `.pen` 路径已经成为 shell 可见文件
    - 截图导出必须写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`
 9. 生成 `pencil-bindings.md`
@@ -159,11 +162,15 @@ Da Vinci 应该：
 - 对复杂产品，先把 1 到 3 个 anchor surface 做到通过截图审查，再扩展其他页面
 - 对每个 anchor surface，都要说明“新的构图与当前布局结构相比具体改了什么”
 - 只要截图分析指出 hierarchy、spacing、clarity、inconsistency 或 unresolved placeholder 问题，就不能自动判通过
+- 不要把截图审查写成“看起来很好”；必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改
 - 在扩展更多页面前，先从已通过的 anchor surface 中抽出一组 shared primitives
 - 只使用 Pencil 支持的属性，不要继续使用 `flex`、`margin` 这类 Web/CSS 属性
+- 在发送非小型 `batch_design` 之前，如果有 shell 能力，先对 Pencil operations 做 preflight
+- 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
 - 一个实现页如果包含多个 Fragment、多个 tab、多个状态或多个 overlay，应该拆成多个设计 surface
 - `design-registry.md` 里的首选 `.pen` 路径由工作流自动维护，不应该依赖用户手工填写
 - 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
+- 不要把 interactive `save()` 当作可靠的持久化真相；应从当前 MCP 可读快照重建并覆盖项目内 `.pen`
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 - `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
 - 截图 PNG 只是审查产物，不能替代登记好的 `.pen` 设计源
@@ -183,7 +190,8 @@ Da Vinci 应该：
 4. 复用或更新 `design-registry.md`
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
-   - 把更新后的 `.pen` 文件真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
+   - 如果这次改动还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现

package/docs/zh-CN/prompt-presets/README.md

@@ -13,6 +13,8 @@
 3. 再选和项目复杂度、交付意图匹配的提示词版本
 4. 两者一起放进工作流设置
 5. 只有在项目存在特殊真相源或平台约束时，再继续收紧提示词
+6. 如果 Pencil MCP 可用，优先使用已经明确要求 MCP runtime gate 和 completion audit 的那版 redesign 提示词
+7. 如果项目要把 `.pen` 真正持久化到本地，优先使用已经区分“首次生成快照”和“继续迭代覆盖保存”的那版提示词，不要依赖 interactive `save()`
 
 可用模板：
 
@@ -26,6 +28,7 @@
 - 提示词模板负责定义工作流意图、拆分规则和真相源处理方式
 - `Visual Assist` 模板负责定义 UI 设计增强偏好
 - form factor 专用的 layout hygiene 仍然是独立硬闸门，screen 在通过 screenshot review 前必须应用对应规则
+- MCP runtime gate 和 `da-vinci audit --mode completion ...` 属于工作流 gate，不属于 `Visual Assist` 配置本身
 - 两者一起使用，结果通常更稳
 
 现在每个场景模板里都固定包含：