@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -2,7 +2,27 @@
 
 ## 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
+
+### Added
+- `references/layout-hygiene.md` as the central form-factor-specific layout hygiene gate for mobile, tablet, desktop, and web screenshot review
+
+### Changed
+- screenshot-review and design-checkpoint guidance now apply a resolved layout-hygiene profile per reviewed surface instead of relying on generic spacing checks alone
+- design-input and artifact-template guidance now records the resolved layout-hygiene profile and blocker classes in `design-brief.md` and `pencil-design.md`
+- visual-adapter docs now state explicitly that `Visual Assist` does not replace form-factor-specific layout hygiene
+- prompt presets for mobile, tablet, desktop, and web now point to the form-factor-specific layout hygiene gate before screenshot review passes
+- Chinese documentation now matches the new layout-hygiene guidance instead of mixing untranslated preset instructions
 
 ## v0.1.13 - 2026-03-27
 

package/README.md

@@ -27,7 +27,7 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.13`
+- `@xenonbyte/da-vinci-workflow@0.1.14`
 
 Release highlights:
 
@@ -35,6 +35,7 @@ Release highlights:
 - 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
 - screenshot review is now documented as a binding gate; analysis that reports hierarchy, spacing, clarity, or inconsistency issues cannot be treated as an automatic pass
+- form-factor-specific layout hygiene is now documented as a separate hard gate from `Visual Assist`, with blocker conditions for mobile, tablet, desktop, and web review
 - `.da-vinci/designs/` is now documented more strictly as a `.pen`-only directory, and project-local `.pen` persistence must be verified as shell-visible immediately after the first Pencil write
 - multi-surface redesign guidance now requires a shared primitive family to be defined from approved anchor surfaces before broad page expansion
 - Pencil generation guidance now explicitly rejects web-only properties such as `flex` and `margin`
@@ -116,6 +117,7 @@ Recommended default:
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -141,6 +143,7 @@ Quality-first redesign configuration:
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -158,8 +161,10 @@ Selection rules:
 
 - keep `ui-ux-pro-max` first for dense app and dashboard surfaces when the visual bar is moderate
 - move `frontend-skill` to the first slot when art direction, composition quality, and premium visual hierarchy matter more
+- write actual installed adapter names for the current environment instead of assuming cross-platform aliases
 - when `Preferred adapters` are configured, the resolved primary adapter should actively lead the first design pass instead of being recorded only for traceability
 - state the resolved primary adapter explicitly at runtime and name any requested adapters that are unavailable
+- treat form-factor-specific layout hygiene as a separate hard gate from `Visual Assist`; adapter choice does not override mobile/tablet/desktop/web review failures
 - do not assume cross-platform equivalence between near-name adapters
 - write a visual thesis, content plan, and interaction thesis before the first anchor surface
 - use Pencil guides as platform/buildability constraints, not as the main art-direction source
@@ -409,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

@@ -29,7 +29,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.13`
+- `@xenonbyte/da-vinci-workflow@0.1.14`
 
 已发布版本重点：
 
@@ -37,6 +37,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 - `frontend-skill`、`frontend-design` 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
 - 复杂 `redesign-from-code` 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
 - screenshot review 现在被明确强调为硬闸门；只要分析指出 hierarchy、spacing、clarity 或 inconsistency 问题，就不能自动判通过
+- form factor 专用的 layout hygiene 现在被定义成独立于 `Visual Assist` 的硬闸门，mobile、tablet、desktop、web 都有各自的 blocker 条件
 - `.da-vinci/designs/` 现在更明确只用于放 `.pen` 文件，而且第一次 Pencil 写入后就要验证对应 `.pen` 已经成为 shell 可见文件
 - 多 surface 重设计现在要求先从已通过的 anchor surface 中抽出 shared primitive family，再扩展更多页面
 - Pencil 生成规则现在明确拒绝 `flex`、`margin` 这类 Web 属性
@@ -121,6 +122,7 @@ Da Vinci V2 支持四种模式：
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -146,6 +148,7 @@ Da Vinci V2 支持四种模式：
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -163,8 +166,10 @@ Da Vinci V2 支持四种模式：
 
 - 高密度 app、dashboard、工具型界面，且视觉要求中等时，优先把 `ui-ux-pro-max` 放第一位
 - 如果更重视 art direction、构图和高级感，就把 `frontend-skill` 放第一位
+- `Preferred adapters` 里要写当前环境里真实存在的 adapter 名，不要默认套用跨平台别名
 - 一旦配置了 `Preferred adapters`，解析出来的主 adapter 应该真正主导首轮设计，而不是只登记在工件里
 - 运行时必须明确写出解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
+- form factor 专用的 layout hygiene 是独立于 `Visual Assist` 的硬闸门；adapter 选择不能覆盖 mobile、tablet、desktop、web 的版式失败条件
 - 不要默认把跨平台的近名 adapter 当成同一个能力源
 - 在第一个 anchor surface 之前，先写 visual thesis、content plan 和 interaction thesis
 - Pencil 的 guide 只应该约束平台布局和可实现性，不应该替代主 adapter 成为设计方向来源
@@ -338,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,15 +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
@@ -235,6 +244,7 @@ Load only the reference that matches the current step:
 - Read `references/artifact-templates.md` when creating or updating workflow artifacts
 - Read `references/checkpoints.md` when running or reporting checkpoints
 - Read `references/design-inputs.md` when collecting product form factor, style, and constraints
+- Read `references/layout-hygiene.md` when screenshot review or the design checkpoint needs form-factor-specific layout hygiene rules
 - Read `references/page-mapping.md` when defining project pages, Pencil pages, and route-to-screen bindings
 - Read `references/pencil-design-to-code.md` when turning Pencil data into implementation
 - Read `references/platform-adapters.md` when guiding users on Codex, Claude, or Gemini invocation patterns
@@ -571,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