@xenonbyte/da-vinci-workflow 0.1.15 → 0.1.17

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## Unreleased
+## v0.1.17 - 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 ensure-pen` to seed or verify a registered project-local `.pen` before live editing starts
+- `da-vinci check-pen-sync` to compare a current live MCP snapshot payload against the persisted project-local `.pen`
+- `da-vinci pencil-lock` to serialize Pencil MCP write access across multiple projects on the same machine
+- `da-vinci pencil-session begin / persist / end / status` as the preferred session-level wrapper for seeded `.pen` ownership, persistence, sync checks, and lock release
+- `scripts/test-pencil-session.js` and `scripts/test-persistence-flows.js` to cover session lifecycle plus new/existing/parallel project flows
+
+### 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; redesign passes should seed the registered `.pen` before the first edit, then persist current live MCP snapshots back to that same path after material edits
+- `da-vinci snapshot-pen` is now documented and treated as a disk-to-disk utility only, not as a live-edit persistence step
+- completion audit now expects `.da-vinci/state/pencil-session.json` plus matching persisted snapshot hashes before completion can pass
 
 ## v0.1.15 - 2026-03-27
 

package/README.md

@@ -27,10 +27,16 @@ 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()`
+- redesign runs now seed a registered project-local `.pen` before the first Pencil edit and record persisted snapshot hashes for later sync checks
+- `da-vinci write-pen` now atomically writes workflow-owned `.pen` files from MCP-readable node and variable payloads with optional reopen verification
+- `da-vinci ensure-pen` now seeds or verifies a registered project-local `.pen` before live editing starts
+- `da-vinci check-pen-sync` now compares a current live MCP snapshot payload against the persisted project-local `.pen`
+- `da-vinci snapshot-pen` now serves only as a disk-to-disk utility for rebuilding an existing Pencil source and verifying reopen
 - 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 +422,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 +439,34 @@ 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: seed the registered project-local `.pen` with `da-vinci ensure-pen --output <path> --verify-open`, open that exact path, then persist later MCP snapshot writes back to the same file
+- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh live MCP snapshot back to that same path and run `da-vinci check-pen-sync`
+
+Persistence helpers:
+
+- preferred wrapper:
+  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci ensure-pen --output <path> --verify-open`
+- `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
+- `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open` (disk-to-disk only)
+- `da-vinci pencil-lock acquire --project <project-path>` / `da-vinci pencil-lock release --project <project-path>`
+
+Do not treat headless interactive `save()` as authoritative persistence truth until the underlying Pencil behavior is proven reliable again.
+Completion audit now also expects `.da-vinci/state/pencil-session.json` to reflect the latest persisted `.pen` hash, so autonomous runs should prefer the `pencil-session` wrapper.
 
 Installation targets:
 

package/README.zh-CN.md

@@ -29,10 +29,16 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.14`
+- `@xenonbyte/da-vinci-workflow@0.1.16`
 
 已发布版本重点：
 
+- 项目内 `.pen` 持久化现在改为“从 MCP 快照写回磁盘”的正式路径，不再依赖 headless interactive `save()`
+- 重设计流程现在要求在第一次 Pencil 编辑前先 seed 一个登记好的项目内 `.pen`，并记录后续持久化快照 hash 以便做同步校验
+- `da-vinci write-pen` 现在可以把 MCP 可读的节点和变量快照原子写成工作流管理的 `.pen` 文件，并可选地做 reopen 校验
+- `da-vinci ensure-pen` 现在可以在 live 编辑开始前 seed 或校验登记好的项目内 `.pen`
+- `da-vinci check-pen-sync` 现在可以把当前 live MCP 快照和已持久化的项目内 `.pen` 做同步比对
+- `da-vinci snapshot-pen` 现在只作为 disk-to-disk 工具，用来从已有 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 +351,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 +368,34 @@ 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` 持久化现在分成两条受支持路径：
+
+- 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
+- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
+
+推荐使用的持久化命令：
+
+- 优先使用封装好的 session 命令：
+  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci ensure-pen --output <path> --verify-open`
+- `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
+- `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`（仅限 disk-to-disk）
+- `da-vinci pencil-lock acquire --project <project-path>` / `da-vinci pencil-lock release --project <project-path>`
+
+在 Pencil 底层 `save()` 语义再次被证明可靠之前，不要把 headless interactive `save()` 当作权威持久化真相。
+completion audit 现在还会检查 `.da-vinci/state/pencil-session.json` 是否记录了最新的 `.pen` hash，所以自治运行优先走 `pencil-session` 封装。
 
 安装目标：
 

package/SKILL.md

@@ -226,15 +226,33 @@ 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
+- prefer the session wrapper commands:
+  `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- before the first Pencil edit on a redesign pass, begin a Pencil session so the registered project-local `.pen` exists before editing and the global Pencil lock is held for that project
+- acquire the global Pencil lock before MCP write operations on a project and release it after the write phase so two projects do not compete for the same active editor
+- when a registered project-local `.pen` already exists, 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
+- `da-vinci snapshot-pen` is a disk-to-disk utility for rebuilding an existing `.pen`; do not use it as live-edit persistence
+- 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 writing the project-local `.pen`, run `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>` before treating the disk source as current
+- completion audit expects a recorded Pencil session state under `.da-vinci/state/pencil-session.json`; do not bypass the session wrapper on autonomous runs
 - 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`
+- if the workflow already has a registered `.pen`, do not send Pencil write operations with an empty `filePath`
 - 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,12 @@ 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.
+Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `pencil-session persist` after material 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,12 @@ 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.
+Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `pencil-session persist` after material 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,13 @@ 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.
+Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `pencil-session persist` after material 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/`
+   - prefer `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
+   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current live MCP snapshot through `da-vinci pencil-session persist` 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 drive `da-vinci pencil-session begin / persist / end`; fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the wrapper cannot be used
 
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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`.
+Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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`.
+Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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`.
+Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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`.
+Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
 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.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
+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. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
 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. prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
+12. during live design work, prefer `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
+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.
+Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
+If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `da-vinci pencil-session persist`.
 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, seed it there before the first Pencil edit and keep subsequent live edits bound to that exact path.
+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`，先在登记好的 `.da-vinci/designs/` 路径 seed 一个 `.pen` 再开始第一次 Pencil 编辑
+   - 如果项目里原本已有 `.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`，先在登记好的 `.da-vinci/designs/` 路径 seed 一个 `.pen` 再开始第一次 Pencil 编辑
+   - 如果项目里原本已有 `.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`，先在登记好的 `.da-vinci/designs/` 路径 seed 一个 `.pen` 再开始第一次 Pencil 编辑
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
    - 在第一次成功写入 Pencil 后，立即验证登记的 `.pen` 路径已经成为 shell 可见文件
    - 截图导出必须写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`
 9. 生成 `pencil-bindings.md`
@@ -159,11 +162,16 @@ 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()` 当作可靠的持久化真相；应先 seed 项目内 `.pen`，然后从当前 MCP 可读快照重建并覆盖它，并通过 `da-vinci check-pen-sync` 做同步校验
+- 如果支持 CLI，优先走 `da-vinci pencil-session begin / persist / end`，不要再手拼 `ensure-pen + write-pen + lock`
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 - `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
 - 截图 PNG 只是审查产物，不能替代登记好的 `.pen` 设计源
@@ -183,7 +191,8 @@ Da Vinci 应该：
 4. 复用或更新 `design-registry.md`
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
-   - 把更新后的 `.pen` 文件真正落到登记好的 `.da-vinci/designs/` 路径
+   - 优先通过 `da-vinci pencil-session begin` 开始这轮设计，让登记路径先 seed 好并拿到锁
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现