@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.15

package/CHANGELOG.md

@@ -2,7 +2,15 @@
 
 ## Unreleased
 
-- No unreleased changes yet.
+## 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

@@ -414,9 +414,26 @@ 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 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
+
+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.
+
 Installation targets:
 
 - Codex prompts: `~/.codex/prompts/`

package/README.zh-CN.md

@@ -343,9 +343,26 @@ 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 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 只有空目录或只写了一半
+
+当 Pencil MCP 可用时，Da Vinci 现在还要求在终态完成声明前，把 MCP runtime gate 结果记录到 `pencil-design.md`。这层 gate 负责检查 live editor/source convergence，与 filesystem audit 分工不同。
+
 安装目标：
 
 - Codex prompts：`~/.codex/prompts/`

package/SKILL.md

@@ -216,16 +216,24 @@ 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
 - 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 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
 - 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`
 
 ## Load References On Demand
@@ -573,6 +581,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,5 @@ Create or update:
 - `pencil-design.md`
 
 Run the `design checkpoint` before locking implementation tasks.
+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`, 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,5 @@ Output should move the work toward:
 - `pencil-design.md`
 
 Use Pencil-backed structure as the design source when available.
+If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
+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,6 @@ Create or update:
 - `pencil-design.md`
 
 Use Pencil-backed page coverage as the source of presentation truth.
+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`, 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

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

@@ -0,0 +1,244 @@
+# MCP-Aware Gate Test Design
+
+This document defines how to test the future MCP-aware gate implementation.
+
+It is a design for validation coverage, not a test implementation.
+
+## Test Goal
+
+Prove that the MCP-aware gate:
+
+- blocks false runtime completion states
+- does not replace filesystem audit
+- does not misclassify healthy runtime design sessions
+- behaves predictably when MCP runtime facts are incomplete
+
+## Test Layers
+
+The test plan should cover three layers.
+
+### 1. Evaluator unit tests
+
+Test the pure runtime-gate evaluator against synthetic snapshot inputs.
+
+Why:
+
+- fastest feedback
+- deterministic
+- does not depend on a live Pencil session
+
+### 2. Runtime integration tests
+
+Test the runtime-gate caller against real or fixture-backed MCP responses.
+
+Why:
+
+- proves that active editor and node reads are interpreted correctly
+
+### 3. End-to-end workflow tests
+
+Test that runtime gate and filesystem audit cooperate correctly in realistic workflow states.
+
+Why:
+
+- prevents regressions where runtime gate passes but completion still lies
+
+## Core Test Categories
+
+### A. Healthy runtime source convergence
+
+Expected:
+
+- active editor is a named project-local `.pen`
+- registered `.pen` path matches
+- shell-visible `.pen` exists
+- result is `PASS`
+
+### B. Live editor still `new`
+
+Expected:
+
+- source convergence is `BLOCK`
+- completion is blocked even if screens exist in the live editor
+
+### C. Registered `.pen` path missing on disk
+
+Expected:
+
+- source convergence or completion status becomes `BLOCK`
+- runtime gate does not treat the live editor alone as sufficient
+
+### D. Live screens exist but are not persisted
+
+Example:
+
+- active editor contains `Splash`, `Home`, `SafeBox`
+- shell-visible `.pen` does not exist
+
+Expected:
+
+- runtime gate can prove screens exist
+- source convergence is still `BLOCK`
+
+### E. Claimed anchor id missing
+
+Example:
+
+- `pencil-design.md` claims `mCZ1G`
+- current live editor does not contain `mCZ1G`
+
+Expected:
+
+- screen presence is `BLOCK`
+
+### F. Screenshot target missing
+
+Expected:
+
+- review execution is `BLOCK`
+
+### G. Review blockers ignored
+
+Example:
+
+- screenshot review records blocker-level layout-hygiene issues
+- workflow still marks anchor as approved
+
+Expected:
+
+- review execution is `BLOCK`
+
+### H. Source mismatch with explicit reconciliation
+
+Example:
+
+- active editor path and registered path differ
+- `pencil-design.md` records a documented reconciliation
+
+Expected:
+
+- evaluator returns `WARN` or `PASS` only if the reconciliation rules are satisfied
+
+### I. No new Pencil edits yet
+
+Expected:
+
+- runtime gate may return `WARN` or partial result
+- must not fabricate full `PASS`
+
+### J. Pencil MCP unavailable
+
+Expected:
+
+- runtime gate reports unavailable or skipped state
+- workflow does not treat runtime gate as passed
+- filesystem audit remains usable
+
+## Required End-to-End Scenarios
+
+### Scenario 1: Real failure pattern from Cipher
+
+State:
+
+- active editor is `new`
+- live screens exist
+- `.da-vinci/designs/` is polluted
+- no shell-visible `.pen`
+
+Expected:
+
+- runtime gate blocks completion
+- filesystem completion audit also fails
+
+### Scenario 2: Healthy redesign completion
+
+State:
+
+- active editor is the registered `.pen`
+- anchor ids exist
+- screenshot review exists
+- shell-visible `.pen` exists
+- completion audit passes
+
+Expected:
+
+- runtime gate passes
+- completion audit passes
+- terminal completion is allowed
+
+### Scenario 3: Runtime pass, filesystem fail
+
+State:
+
+- active editor is healthy
+- shell-visible `.pen` exists
+- but `.da-vinci/designs/` contains extra PNG or markdown files
+
+Expected:
+
+- runtime gate may pass
+- filesystem completion audit fails
+- terminal completion is blocked
+
+### Scenario 4: Filesystem pass, runtime fail
+
+State:
+
+- shell-visible `.pen` exists
+- files look healthy
+- active editor is still `new` or points elsewhere
+
+Expected:
+
+- runtime gate fails
+- completion is blocked
+
+## Assertions That Must Exist
+
+For every runtime-gate result, tests should assert:
+
+- final status
+- per-layer status
+- which blocking condition fired
+- whether completion would be allowed
+- whether artifact recording shape stays stable
+
+## Artifact Recording Tests
+
+Verify that runtime gate output:
+
+- appends to `pencil-design.md`
+- does not create a new artifact family
+- does not write into `.da-vinci/designs/`
+- does not overwrite unrelated sections
+
+## Regression Cases
+
+These regressions should be covered:
+
+1. runtime gate accidentally behaves like a CLI-only audit
+2. runtime gate silently treats `new` as acceptable
+3. runtime gate treats PNG exports as source evidence
+4. runtime gate passes when anchor ids are missing
+5. runtime gate is skipped but reported as passed
+6. runtime gate writes ad hoc markdown files outside the allowed artifact path
+
+## Recommended Test Matrix
+
+Minimum matrix:
+
+- form factor: mobile first
+- design stage: first Pencil write / approved anchor / terminal completion
+- source state: healthy / `new` / diverged / missing `.pen`
+- screen state: present / missing / stale ids
+- review state: reviewed / missing / blocker ignored
+
+## Exit Criteria
+
+The implementation should not be considered ready unless all of the following are true:
+
+1. evaluator unit tests cover all blocker branches
+2. at least one runtime integration test proves live editor detection works
+3. the Cipher-like failure scenario is blocked
+4. a healthy redesign scenario passes
+5. runtime gate plus filesystem audit together prevent false terminal completion