@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -1,8 +1,26 @@
 # Changelog
 
-## Unreleased
+## v0.1.16 - 2026-03-28
 
-- No unreleased changes yet.
+### 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
+
+### Changed
+- MCP-aware runtime gate now has a first implementation slice: a pure evaluator, runtime-gate recording shape, and workflow hooks that require live source convergence checks before terminal completion claims
+- `da-vinci audit` now distinguishes `integrity` and `completion` modes so mid-workflow sanity checks do not masquerade as terminal completion gates
+- completion guidance now blocks terminal `design complete` or `workflow complete` claims unless the registered project-local `.pen` source is shell-visible, standard artifacts exist, and the completion gate passes
+- design-source rules now reject unnamed live editors such as `new` as persisted project sources and explicitly block screenshot or markdown pollution inside `.da-vinci/designs/`
+- prompt presets, workflow examples, and mode guides now state that screenshot exports belong under `.da-vinci/changes/<change-id>/exports/` and cannot replace the `.pen` source of truth
+- Pencil-operation guidance now treats repeated unsupported-property rollbacks on the same anchor surface as unstable progress instead of acceptable forward motion
 
 ## v0.1.14 - 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
@@ -414,9 +417,46 @@ Useful commands:
 ```bash
 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
 ```
 
+`da-vinci audit` has two intended modes:
+
+- `--mode integrity`: a mid-workflow filesystem-truth check for missing baseline artifacts, misplaced exports, polluted `.da-vinci/designs/`, and missing persisted `.pen` sources
+- `--mode completion`: a strict pre-completion gate for one change scope; use `--change <change-id>` and treat any failure as blocking
+
+Both modes check the most common workflow-integrity failures in a project:
+
+- missing standard Da Vinci artifacts
+- missing shell-visible project-local `.pen` sources
+- pollution inside `.da-vinci/designs/`
+- 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:
 
 - Codex prompts: `~/.codex/prompts/`

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 说明
@@ -343,9 +346,47 @@ da-vinci install --platform codex,claude,gemini
 ```bash
 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
 ```
 
+`da-vinci audit` 现在有两种主要模式：
+
+- `--mode integrity`：适合在工作进行中检查文件系统真相，比如基础工件缺失、导出路径错误、`.da-vinci/designs/` 被污染、项目内 `.pen` 没落盘
+- `--mode completion`：适合在宣称完成前做严格检查；配合 `--change <change-id>` 使用，任何失败都应视为阻断
+
+两种模式都会检查项目里最常见的工作流完整性问题：
+
+- 标准 Da Vinci 工件缺失
+- 项目内 shell 可见 `.pen` 设计源缺失
+- `.da-vinci/designs/` 目录被污染
+- 截图导出写到了错误位置
+- 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` 改成更小的后续批次。
+
 安装目标：
 
 - Codex prompts：`~/.codex/prompts/`

package/SKILL.md

@@ -216,17 +216,34 @@ Default completion rule:
 - if the request is `design-only`, stop after design artifacts and bindings
 - otherwise assume `full-delivery` and continue through implementation and verification
 
+Do not report `design complete`, `workflow complete`, or any equivalent terminal state unless the completion gate in `references/checkpoints.md` is satisfied.
+When shell access is available, prefer `da-vinci audit --mode integrity <project-path>` during active workflow work and `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim.
+
 ## Pencil Generation Rules
 
 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
 
@@ -573,6 +590,11 @@ When Pencil is available through MCP:
 - Before mapping or implementation closes, verify both:
   - the `.pen` path is readable through MCP
   - the same path exists as a shell-visible file inside the project
+- Before broad expansion or terminal completion, run the MCP runtime gate:
+  - evaluate source convergence from the active editor, registered `.pen` path, and shell-visible `.pen` file
+  - evaluate screen presence for claimed anchor and review target ids
+  - evaluate review execution for approved surfaces
+  - append the runtime gate result to `pencil-design.md`
 
 When Pencil is not available:
 

package/commands/claude/dv/design.md

@@ -18,3 +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/claude/dv/verify.md

@@ -14,3 +14,5 @@ Check:
 
 Create or update:
 - `verification.md`
+
+If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.

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

@@ -12,3 +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/codex/prompts/dv-verify.md

@@ -13,3 +13,4 @@ Check:
 - drift between artifacts and code
 
 Update `verification.md` when needed.
+If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.

package/commands/gemini/dv/design.toml

@@ -11,4 +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/commands/gemini/dv/verify.toml

@@ -12,4 +12,5 @@ Check:
 - drift between artifacts and code
 
 Update `verification.md` when needed.
+If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.
 """

package/docs/mcp-aware-gate-implementation.md

@@ -0,0 +1,291 @@
+# MCP-Aware Gate Implementation Design
+
+This document turns the MCP-aware gate proposal into an implementation design.
+
+It still does not commit to writing code.
+
+## Scope
+
+This design covers only the first implementation slice:
+
+- runtime source convergence
+- runtime screen presence
+- runtime review execution
+- completion blocking when runtime truth and filesystem truth diverge
+
+It does not cover:
+
+- automatic `.pen` reconstruction
+- CLI access to live MCP state
+- session persistence or transport work
+
+## Design Goal
+
+Add a narrow runtime checkpoint that can stop false completion claims caused by live-editor drift.
+
+The gate should catch cases like:
+
+- active editor is still `new`
+- anchor screens exist only in the live session
+- node ids used for screenshots do not exist in the current editor
+- the workflow claims completion before runtime state and filesystem state converge
+
+## Existing Constraints
+
+The current architecture already provides:
+
+- filesystem `audit`
+- checkpoint rules in `references/checkpoints.md`
+- artifact expectations in `design-registry.md` and `pencil-design.md`
+- MCP access to active editor state and screen nodes
+
+The current architecture does not provide:
+
+- a CLI bridge to MCP runtime state
+- a stable session id outside the active agent context
+
+That means the MCP-aware gate must be executed inside the agent workflow while MCP tools are live.
+
+## Implementation Placement
+
+### Primary insertion points
+
+1. After the first successful Pencil write in a design pass.
+2. Before any terminal `design complete` or `workflow complete` claim.
+
+### Secondary insertion point
+
+3. Before broad expansion beyond approved anchor surfaces when the design pass depends on screenshot-reviewed anchors.
+
+### Why these points
+
+- after first write: catches `new`-editor drift early
+- before completion: catches false success claims
+- before broad expansion: prevents weak runtime state from spreading into more screens
+
+## Owning Workflow Stage
+
+The runtime gate should be owned by the design phase, not the CLI.
+
+That means:
+
+- design routes should execute it while Pencil MCP is available
+- verify routes may re-check it if design completion is being claimed
+- build routes should not become the primary owner of runtime gate logic
+
+## Input Sources
+
+### MCP inputs
+
+Required:
+
+- active editor state
+- top-level nodes
+- targeted node reads for claimed anchor surfaces
+
+Expected MCP operations:
+
+- `pencil.get_editor_state`
+- `pencil.batch_get`
+
+### Filesystem inputs
+
+Required:
+
+- shell-visible `.pen` existence
+- registered `.pen` path from `design-registry.md`
+- declared reviewed screens and screenshot targets from `pencil-design.md`
+
+Expected shell or file reads:
+
+- read `design-registry.md`
+- read `pencil-design.md`
+- check registered `.pen` path on disk
+
+## Runtime Snapshot Model
+
+The runtime gate should build one structured snapshot in memory:
+
+```md
+runtime snapshot
+- activeEditor
+- topLevelScreenIds
+- topLevelScreenNames
+- registeredPenPath
+- shellVisiblePenExists
+- claimedAnchorIds
+- claimedReviewedScreenIds
+- reviewTargets
+```
+
+The evaluator should only depend on this snapshot.
+
+That keeps the implementation testable without needing a real live Pencil session for every case.
+
+## Evaluation Stages
+
+### Stage 1: Source Convergence
+
+Checks:
+
+- active editor is not `new`
+- registered `.pen` path exists in `design-registry.md`
+- registered `.pen` path exists on disk
+- active editor and registered source do not obviously diverge
+
+Result rules:
+
+- `PASS`: runtime source and registered source converge
+- `WARN`: no new live edits happened yet, or a documented deferred baseline is still being used
+- `BLOCK`: runtime source is unnamed, missing, or diverged
+
+### Stage 2: Screen Presence
+
+Checks:
+
+- claimed anchor ids exist in live MCP state
+- claimed reviewed screens exist in live MCP state
+- screenshot targets resolve in the active document
+
+Result rules:
+
+- `PASS`: claimed design output is traceable to live editor nodes
+- `WARN`: screen naming drift exists but ids are still traceable
+- `BLOCK`: claimed screens or targets do not resolve
+
+### Stage 3: Review Execution
+
+Checks:
+
+- each approved anchor has a reviewed screen id or screenshot target
+- runtime review records align with the current live editor
+- review blockers were not ignored
+
+Result rules:
+
+- `PASS`: runtime review is credible
+- `WARN`: review exists but requires follow-up before expansion
+- `BLOCK`: approval claim is unsupported by runtime evidence
+
+## Recording Strategy
+
+Do not introduce a new artifact family.
+
+Append a structured section to `pencil-design.md`:
+
+```md
+## MCP Runtime Gate
+- Time:
+- Active editor:
+- Registered `.pen` path:
+- Shell-visible `.pen` path:
+- Claimed anchor ids:
+- Reviewed screen ids:
+- Source convergence: PASS | WARN | BLOCK
+- Screen presence: PASS | WARN | BLOCK
+- Review execution: PASS | WARN | BLOCK
+- Final runtime gate status: PASS | WARN | BLOCK
+- Notes:
+```
+
+### Why `pencil-design.md`
+
+- it already records source path, screens, screenshots, and design notes
+- it is the closest existing artifact to runtime design truth
+- it avoids scattering checkpoint state across ad hoc files
+
+## Failure Handling
+
+When runtime gate returns `BLOCK`:
+
+- do not continue to broad multi-screen expansion
+- do not claim design completion
+- do not claim workflow completion
+- record the mismatch explicitly in `pencil-design.md`
+
+When runtime gate returns `WARN`:
+
+- allow continuation only when the warning does not create source ambiguity
+- do not allow terminal completion unless the warning is explicitly resolved or accepted by the workflow rules
+
+## Interaction With Filesystem Audit
+
+The runtime gate should run first.
+
+Then:
+
+- if runtime gate is `BLOCK`, stop immediately
+- if runtime gate is `PASS` or acceptable `WARN`, run filesystem completion audit before terminal completion
+
+That yields this order:
+
+1. runtime gate
+2. filesystem completion audit
+3. completion claim
+
+## Minimal Pseudoflow
+
+```md
+1. perform first successful Pencil write
+2. read active editor via MCP
+3. read claimed anchor ids from `pencil-design.md`
+4. read registered `.pen` path from `design-registry.md`
+5. check shell-visible `.pen`
+6. read live nodes for claimed anchors
+7. evaluate source convergence
+8. evaluate screen presence
+9. evaluate review execution when relevant
+10. append runtime gate results to `pencil-design.md`
+11. if terminal completion is being claimed, run filesystem completion audit
+12. only report completion if both layers pass
+```
+
+## Boundary Decisions
+
+### When Pencil MCP is unavailable
+
+Do not try to emulate runtime gate.
+
+Instead:
+
+- record that MCP runtime gate could not run
+- fall back to filesystem audit plus documented constraints
+- do not describe the runtime gate as passed
+
+### When no anchor ids are recorded yet
+
+The runtime gate may run a reduced source-convergence-only check after the first Pencil write.
+
+It should not pretend screen-presence or review-execution checks were completed.
+
+### When no new Pencil edits happened
+
+Use `WARN` or skip runtime gate rather than fabricating a pass.
+
+## Non-Functional Requirements
+
+The first implementation should be:
+
+- deterministic
+- append-only in artifact recording
+- easy to unit-test from a runtime snapshot object
+- independent from CLI transport changes
+
+## Implementation Steps
+
+Recommended order:
+
+1. define a runtime snapshot shape
+2. define a pure evaluator over that snapshot
+3. add a writer that appends runtime gate results to `pencil-design.md`
+4. call the gate from design-phase runtime checkpoints
+5. wire terminal completion to require both runtime gate and filesystem completion audit
+
+## Deferred Work
+
+Do not include these in the first implementation:
+
+- auto-repair of editor/source mismatch
+- multi-session state reconciliation
+- CLI-facing live runtime commands
+- generalized checkpoint orchestration engine