@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.15

package/docs/mcp-aware-gate.md

@@ -0,0 +1,246 @@
+# MCP-Aware Gate Proposal
+
+This document defines a proposed MCP-aware runtime gate for Da Vinci.
+
+It is intentionally a design document, not an implementation commitment.
+
+## Status
+
+- Design status: proposed
+- Validation status: partially validated from real runtime observations
+- Implementation status: not started
+
+## Why This Exists
+
+The current filesystem audit closes one important gap:
+
+- it can prove whether the project-local `.pen` file exists on disk
+- it can prove whether `.da-vinci/designs/` is polluted
+- it can prove whether exported screenshots were misplaced
+
+But it cannot prove live MCP state such as:
+
+- whether the active Pencil editor is still `new`
+- whether the claimed anchor surfaces actually exist in the active editor
+- whether the active editor and the registered project-local `.pen` source have converged
+
+Those facts only exist at runtime inside the MCP-backed design session.
+
+## Validated Feasibility
+
+The following facts have already been validated as observable:
+
+1. The active Pencil editor can be read through MCP.
+2. The top-level live nodes can be read through MCP.
+3. Specific screen node ids can be read through MCP.
+4. The shell-visible project state can be read separately through normal filesystem access.
+
+This means Da Vinci can already compare:
+
+- live editor truth
+- live screen truth
+- filesystem truth
+
+That comparison is enough to support a first MCP-aware runtime gate.
+
+## Non-Goals
+
+This proposal does not attempt to:
+
+- replace the filesystem `da-vinci audit`
+- expose MCP state directly through the CLI
+- auto-repair live editor state into a persisted `.pen` file
+- make implementation depend on undocumented Pencil session behavior
+
+## Design Principles
+
+1. MCP-aware gate is runtime-only.
+2. Filesystem audit remains the terminal persistence gate.
+3. Runtime gate blocks false progress; it does not auto-heal state.
+4. The design should only rely on facts already observed to be readable.
+5. The design should degrade cleanly when Pencil MCP is unavailable.
+
+## Placement In The Workflow
+
+The MCP-aware gate should sit in two places:
+
+1. After the first successful Pencil write on a redesign pass.
+2. Before any terminal `design complete` or `workflow complete` claim.
+
+It should not run on every trivial design operation.
+
+## Proposed Gate Layers
+
+### 1. Source Convergence Gate
+
+Purpose:
+
+- determine whether the live editor, registered `.pen` path, and shell-visible `.pen` file agree well enough to treat the design source as traceable
+
+Inputs:
+
+- active Pencil editor state from MCP
+- registered `.pen` path from `design-registry.md`
+- shell-visible `.pen` path under `.da-vinci/designs/`
+
+Blocking conditions:
+
+- active editor is still an unnamed live editor such as `new`
+- active editor does not match the registered project-local source and the mismatch is not explicitly reconciled
+- shell-visible `.pen` file does not exist after live Pencil work has already happened
+- runtime session appears to be using a different source than the registered project-local source
+
+Result:
+
+- `PASS`: source is converged
+- `WARN`: source is intentionally deferred but still traceable
+- `BLOCK`: source of truth is not stable enough to continue
+
+### 2. Screen Presence Gate
+
+Purpose:
+
+- verify that claimed anchor surfaces actually exist in the active live editor
+
+Inputs:
+
+- node ids or screen ids recorded in `pencil-design.md`
+- current top-level or targeted node reads from MCP
+
+Blocking conditions:
+
+- claimed anchor screen cannot be found in the active editor
+- screenshot node id does not resolve in the current live document
+- the design claims more approved anchor surfaces than the current editor can account for
+
+Result:
+
+- `PASS`: claimed screens exist
+- `WARN`: some naming drift exists but mapping is still recoverable
+- `BLOCK`: claimed design output cannot be traced to the live document
+
+### 3. Review Execution Gate
+
+Purpose:
+
+- verify that screenshot review was performed on the live surfaces that are being treated as approved
+
+Inputs:
+
+- reviewed screen ids from `pencil-design.md`
+- screenshot targets used in the current design session
+- resolved form-factor layout hygiene profile
+
+Blocking conditions:
+
+- a surface is treated as approved without any live screenshot review
+- screenshot review flagged blocker-level layout hygiene issues but the workflow still marked the surface as passed
+- review artifacts refer to screens that are not present in the active editor
+
+Result:
+
+- `PASS`: reviewed surfaces match live runtime state
+- `WARN`: review exists but needs follow-up before expansion
+- `BLOCK`: approval claim is not trustworthy
+
+## Runtime Output Shape
+
+The gate should not invent a new artifact family.
+
+Instead, it should append a short runtime section to `pencil-design.md` or another already valid change artifact:
+
+```md
+## MCP Runtime Gate
+- Time:
+- Active editor:
+- Registered `.pen` path:
+- Shell-visible `.pen` path:
+- Reviewed screen ids:
+- Source convergence: PASS | WARN | BLOCK
+- Screen presence: PASS | WARN | BLOCK
+- Review execution: PASS | WARN | BLOCK
+- Notes:
+```
+
+This keeps runtime evidence attached to the design pass instead of scattering it into ad hoc files.
+
+## Relationship To Filesystem Audit
+
+The two systems have different jobs.
+
+### MCP-aware runtime gate
+
+- checks live editor truth
+- checks live screen truth
+- checks runtime/source convergence before false progress spreads
+
+### Filesystem audit
+
+- checks persisted project truth
+- checks directory hygiene
+- checks completion integrity
+
+Expected terminal rule:
+
+- do not report completion unless MCP-aware runtime gate passes and filesystem completion audit passes
+
+## Why This Should Not Be A CLI Feature First
+
+The current CLI can only read filesystem state.
+
+It has no MCP transport, no session identity, and no direct access to the live Pencil editor.
+
+That makes a CLI-only MCP-aware gate structurally unreliable.
+
+For now, the MCP-aware gate should be treated as an agent-executed runtime checkpoint, not a standalone CLI audit mode.
+
+## Failure Modes To Avoid
+
+1. Treating `new` as if it were a persisted `.pen` path.
+2. Treating exported PNG files as design-source evidence.
+3. Treating node ids from an old live document as if they still describe the current active editor.
+4. Silently reconciling runtime/source mismatches without recording that reconciliation.
+5. Auto-writing a `.pen` file from live state without an explicit workflow rule.
+
+## Minimum Viable Implementation Scope
+
+The first implementation should stay narrow.
+
+It should only:
+
+1. read active editor state
+2. read claimed anchor screen ids
+3. compare those facts against `design-registry.md` and the shell-visible `.pen` file
+4. record structured PASS/WARN/BLOCK output
+5. block completion when runtime truth and filesystem truth diverge
+
+It should not:
+
+- attempt automatic reconstruction
+- mutate design files on its own beyond structured checkpoint recording
+- add a new CLI command for live runtime state
+
+## Open Questions
+
+These questions remain open and should be answered during implementation design, not before:
+
+1. Which existing command route should own the runtime gate call?
+2. Should the runtime evidence live in `pencil-design.md` only, or also in `design-registry.md`?
+3. How should a reconciled editor-path mismatch be recorded without encouraging drift?
+4. Should the gate run once per approved anchor or once per design phase?
+
+## Recommendation
+
+Proceed only with a narrow agent-executed MCP-aware runtime gate.
+
+Do not expand it into:
+
+- CLI transport work
+- automatic persistence repair
+- generalized MCP session management
+
+The validated path is:
+
+1. keep filesystem `audit` as the persistence and completion backstop
+2. add a runtime MCP-aware gate for source convergence and live screen presence
+3. require both layers before terminal completion is allowed

package/docs/mode-use-cases.md

@@ -139,6 +139,7 @@ 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/`
+   - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`
    - map implementation pages to Pencil pages
@@ -156,6 +157,7 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 - `DA-VINCI.md` exists and is stable
 - every core page exists in `page-map.md`
 - every implementation page has a Pencil counterpart or an explicit exception
+- the registered project-local `.pen` file is shell-visible and not just a live editor session
 - `task checkpoint` passes
 
 ### Best fit

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

@@ -41,12 +41,15 @@ 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 primary workspaces, side panels, inspectors, dialogs, settings flows, overlays, and materially different states before broad Pencil work.
 Decompose complex screens into primary surfaces, secondary surfaces, overlays, and implementation surfaces.
+Create the required discovery and design-source artifacts in their standard locations before the first anchor surface.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 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.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.
 ```

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

@@ -41,6 +41,7 @@ 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 activities, fragments, tabs, dialogs, bottom sheets, nested flows, overlays, and materially different states before broad Pencil work.
 Decompose complex screens into subpages, overlays, materially different states, and implementation surfaces.
+Create the required discovery and design-source artifacts in their standard locations before the first anchor surface.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 State the resolved primary visual adapter explicitly in the log and name any requested adapters that are unavailable.
@@ -54,6 +55,8 @@ Apply the form-factor-specific layout hygiene rules for mobile before passing sc
 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.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.

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

@@ -41,12 +41,15 @@ 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 split-pane regions, sidebars, expanded canvases, dialogs, sheets, orientation-driven changes, and materially different states before broad Pencil work.
 Decompose complex pages into multi-region surfaces, overlays, materially different states, and implementation surfaces.
+Create the required discovery and design-source artifacts in their standard locations before the first anchor surface.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 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.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.
 ```

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

@@ -42,12 +42,15 @@ Preserve current business logic, routes, permissions, integrations, validations,
 Inventory responsive product surfaces, marketing surfaces, authenticated areas, settings pages, dialogs, drawers, overlays, and materially different states before broad Pencil work.
 Separate marketing-style surfaces from product-workflow surfaces when they require different visual treatment.
 Decompose complex pages into subpages, overlays, materially different states, and implementation surfaces.
+Create the required discovery and design-source artifacts in their standard locations before the first anchor surface.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 Treat the resolved primary visual adapter as the first-pass design lead.
 Use Pencil guides only as responsive 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 web before passing screenshot review.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
 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/.
 ```

package/docs/workflow-examples.md

@@ -83,10 +83,13 @@ Expected flow:
 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. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-11. bind routes and pages to Pencil screens
-12. generate tasks aligned to the redesign slices
-13. build and verify
+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
 
 ### Complex Android example
 
@@ -107,6 +110,8 @@ Do not treat screenshot analysis as an automatic pass if it reports hierarchy, s
 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.
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
+Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
+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.
 ```
 

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

@@ -0,0 +1,290 @@
+# MCP-Aware Gate 实现设计
+
+这份文档把 MCP-aware gate 提案收敛成实现设计。
+
+它仍然不是代码实现承诺。
+
+## 范围
+
+这份设计只覆盖第一版最小实现：
+
+- runtime source convergence
+- runtime screen presence
+- runtime review execution
+- runtime truth 和 filesystem truth 不一致时阻断完成态
+
+不覆盖：
+
+- 自动重建 `.pen`
+- 通过 CLI 读取 live MCP 状态
+- session persistence 或 transport 工程
+
+## 设计目标
+
+增加一个很窄的 runtime checkpoint，用来阻断 live editor 漂移造成的假完成态。
+
+它应该能抓住这类情况：
+
+- active editor 仍然是 `new`
+- anchor screen 只存在于 live session
+- 截图使用的 node id 在当前 editor 中不存在
+- runtime 状态和 filesystem 状态没收敛时，工作流却声称完成
+
+## 当前架构约束
+
+当前架构已经具备：
+
+- filesystem `audit`
+- `references/checkpoints.md` 中的 checkpoint 规则
+- `design-registry.md` 和 `pencil-design.md` 中的工件约束
+- 通过 MCP 读取 active editor 和 live screen 的能力
+
+当前架构还不具备：
+
+- 直接从 CLI 读取 MCP runtime state 的能力
+- 脱离当前 agent 上下文的稳定 session id
+
+所以 MCP-aware gate 必须在 agent 工作流里执行，而不是由 CLI 接管。
+
+## 实现挂载点
+
+### 主挂载点
+
+1. 第一次成功写入 Pencil 之后。
+2. 任何 `design complete` 或 `workflow complete` 声明之前。
+
+### 次挂载点
+
+3. 当设计要从 anchor surface 扩张到更多页面前。
+
+### 原因
+
+- 第一次写入后执行：尽早抓到 `new` editor 漂移
+- 完成前执行：阻止假完成
+- 扩张前执行：防止弱 runtime 状态扩散到更多页面
+
+## 归属阶段
+
+runtime gate 应该归设计阶段所有，不归 CLI 所有。
+
+也就是说：
+
+- design route 在 Pencil MCP 可用时负责执行
+- verify route 在声称设计完成时可以复查
+- build route 不应该成为 runtime gate 的主要执行方
+
+## 输入来源
+
+### MCP 输入
+
+必需：
+
+- active editor state
+- top-level nodes
+- 声称完成的 anchor screen 对应节点
+
+预期 MCP 操作：
+
+- `pencil.get_editor_state`
+- `pencil.batch_get`
+
+### 文件系统输入
+
+必需：
+
+- shell 可见 `.pen`
+- `design-registry.md` 中登记的 `.pen`
+- `pencil-design.md` 中记录的 anchor / review / screenshot target
+
+预期文件读取：
+
+- 读取 `design-registry.md`
+- 读取 `pencil-design.md`
+- 检查登记的 `.pen` 是否真实存在
+
+## Runtime Snapshot 模型
+
+runtime gate 应先构造一个结构化 snapshot：
+
+```md
+runtime snapshot
+- activeEditor
+- topLevelScreenIds
+- topLevelScreenNames
+- registeredPenPath
+- shellVisiblePenExists
+- claimedAnchorIds
+- claimedReviewedScreenIds
+- reviewTargets
+```
+
+后续 evaluator 只依赖这份 snapshot。
+
+这样实现就能在没有真实 Pencil session 的情况下做单元测试。
+
+## 评估阶段
+
+### Stage 1: Source Convergence
+
+检查：
+
+- active editor 不是 `new`
+- `design-registry.md` 中存在登记的 `.pen`
+- 登记的 `.pen` 在磁盘上真实存在
+- active editor 和登记设计源没有明显分叉
+
+结果规则：
+
+- `PASS`：runtime source 和登记 source 已收敛
+- `WARN`：还没产生新的 live edit，或在用已记录的延后 baseline
+- `BLOCK`：runtime source 未命名、缺失，或已经分叉
+
+### Stage 2: Screen Presence
+
+检查：
+
+- 声称完成的 anchor id 在 live MCP state 中存在
+- 声称已 review 的 screen 在 live MCP state 中存在
+- screenshot target 在当前文档中可解析
+
+结果规则：
+
+- `PASS`：声称完成的设计输出能追溯到 live editor
+- `WARN`：screen 命名有漂移，但仍可恢复映射
+- `BLOCK`：声称完成的 screen 或 target 无法解析
+
+### Stage 3: Review Execution
+
+检查：
+
+- 每个已批准 anchor 都存在 reviewed screen id 或 screenshot target
+- runtime review 记录和当前 live editor 对齐
+- review blocker 没有被忽略
+
+结果规则：
+
+- `PASS`：runtime review 可信
+- `WARN`：存在 review，但继续扩张前还需要回改
+- `BLOCK`：当前批准结论缺乏 runtime 证据支撑
+
+## 记录策略
+
+不要新增一类全新工件。
+
+应把结果追加到 `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:
+```
+
+### 为什么选 `pencil-design.md`
+
+- 它本来就记录 source path、screens、screenshots 和设计说明
+- 它离 runtime 设计真相最近
+- 避免引入新的临时工件，导致流程继续分叉
+
+## 失败处理
+
+当 runtime gate 返回 `BLOCK`：
+
+- 不允许继续 broad multi-screen expansion
+- 不允许声称 design complete
+- 不允许声称 workflow complete
+- 必须把不一致显式记录到 `pencil-design.md`
+
+当 runtime gate 返回 `WARN`：
+
+- 只有在不会造成 source ambiguity 的情况下才能继续
+- 终态完成前仍要先解决或明确接受这个 warning
+
+## 和 Filesystem Audit 的协作
+
+顺序应该是：
+
+1. 先跑 runtime gate
+2. runtime gate 通过后，再跑 filesystem completion audit
+3. 两层都通过，才能宣称完成
+
+也就是：
+
+1. runtime gate
+2. filesystem completion audit
+3. terminal completion claim
+
+## 最小伪流程
+
+```md
+1. 第一次成功写入 Pencil
+2. 通过 MCP 读取 active editor
+3. 从 `pencil-design.md` 读取声称完成的 anchor ids
+4. 从 `design-registry.md` 读取登记 `.pen`
+5. 检查 shell-visible `.pen`
+6. 读取 live anchor 节点
+7. 评估 source convergence
+8. 评估 screen presence
+9. 在需要时评估 review execution
+10. 把 runtime gate 结果追加到 `pencil-design.md`
+11. 如果要声称终态完成，再跑 filesystem completion audit
+12. 两层都过，才能输出完成
+```
+
+## 边界决策
+
+### 当 Pencil MCP 不可用
+
+不要伪造 runtime gate。
+
+应该：
+
+- 记录 MCP runtime gate 无法执行
+- 回退到 filesystem audit 和已知约束
+- 但不能把 runtime gate 记成已通过
+
+### 当还没有 anchor ids
+
+第一次成功写入后，可以先跑一个缩减版 source-convergence-only check。
+
+但不能假装 screen-presence 或 review-execution 已经完成。
+
+### 当还没有新的 Pencil 修改
+
+应返回 `WARN` 或 skip，而不是伪造 `PASS`。
+
+## 非功能要求
+
+第一版实现应该满足：
+
+- deterministic
+- artifact 记录是 append-only
+- evaluator 可以针对 runtime snapshot 单独单元测试
+- 不依赖 CLI transport 改造
+
+## 实现步骤
+
+建议顺序：
+
+1. 先定义 runtime snapshot 结构
+2. 再定义一个纯 evaluator
+3. 增加一个把结果追加到 `pencil-design.md` 的 writer
+4. 在 design-phase runtime checkpoint 中调用它
+5. 把终态完成规则改成“runtime gate + filesystem audit”双通过
+
+## 延后工作
+
+第一版不要带上：
+
+- 自动修复 editor/source mismatch
+- 多 session 状态和解
+- 面向 live runtime 的 CLI 命令
+- 通用 checkpoint orchestration engine