@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

package/docs/visual-assist-presets/tablet-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - tablet page composition
   - hierarchy and spacing
   - touch-aware motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - keep spacing more generous than desktop but more structured than phone UI
+- replace adapter names with the actual installed names for the current environment when they differ
 - use adapter guidance to improve split layouts, canvases, and workspace balance
 - avoid over-compressing content into phone-like stacking
 - if the result still feels bland or over-framed, move `frontend-skill` to the first slot and require a stronger visual thesis before Pencil work

package/docs/visual-assist-presets/web-app.md

@@ -21,6 +21,7 @@ Recommended `DA-VINCI.md` block:
   - page composition
   - hierarchy and spacing
   - responsive motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -31,6 +32,7 @@ Recommended `DA-VINCI.md` block:
 Notes:
 
 - keep `ui-ux-pro-max` first for product surfaces, dashboards, and operational UI
+- replace adapter names with the actual installed names for the current environment when they differ
 - if the project is more brand-led than tool-led, swap the order and put `frontend-skill` first
 - do not let responsive polish erase product clarity
 - if the output feels like generic SaaS filler, switch `frontend-skill` to first and tighten the visual direction in `DA-VINCI.md`

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

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

@@ -0,0 +1,244 @@
+# MCP-Aware Gate 测试设计
+
+这份文档定义未来 MCP-aware gate 的测试覆盖设计。
+
+它是验证设计，不是测试实现。
+
+## 测试目标
+
+证明 MCP-aware gate：
+
+- 能阻断假的 runtime 完成态
+- 不会取代 filesystem audit
+- 不会把健康的 runtime 设计会话误判成失败
+- 在 runtime 信息不完整时，行为仍然可预测
+
+## 测试层级
+
+测试应覆盖三层。
+
+### 1. Evaluator 单元测试
+
+对纯 runtime-gate evaluator 输入 synthetic snapshot 做测试。
+
+原因：
+
+- 反馈最快
+- 可重复
+- 不依赖真实 Pencil session
+
+### 2. Runtime 集成测试
+
+对 runtime-gate caller 使用真实或 fixture 化的 MCP 响应做测试。
+
+原因：
+
+- 能证明 active editor 和 node 读取确实被正确解释
+
+### 3. 端到端工作流测试
+
+验证 runtime gate 和 filesystem audit 在真实工作流状态下是否能正确协作。
+
+原因：
+
+- 防止 runtime gate 过了，但完成态仍然能说谎
+
+## 核心测试类别
+
+### A. 健康的 runtime source convergence
+
+期望：
+
+- active editor 是有名的项目内 `.pen`
+- 登记的 `.pen` 路径一致
+- shell-visible `.pen` 存在
+- 结果是 `PASS`
+
+### B. Live editor 仍然是 `new`
+
+期望：
+
+- source convergence 为 `BLOCK`
+- 即使 live editor 里有 screen，也不能完成
+
+### C. 登记的 `.pen` 在磁盘上不存在
+
+期望：
+
+- source convergence 或 completion 状态变成 `BLOCK`
+- runtime gate 不能把 live editor 单独当成充分条件
+
+### D. Live screen 存在，但没有持久化
+
+示例：
+
+- active editor 中有 `Splash`、`Home`、`SafeBox`
+- shell-visible `.pen` 不存在
+
+期望：
+
+- runtime gate 能证明 screen 的确存在
+- 但 source convergence 仍然是 `BLOCK`
+
+### E. 声称完成的 anchor id 缺失
+
+示例：
+
+- `pencil-design.md` 声称有 `mCZ1G`
+- 当前 live editor 中没有 `mCZ1G`
+
+期望：
+
+- screen presence 为 `BLOCK`
+
+### F. Screenshot target 缺失
+
+期望：
+
+- review execution 为 `BLOCK`
+
+### G. Review blocker 被忽略
+
+示例：
+
+- screenshot review 已记录 blocker 级 layout-hygiene 问题
+- 但工作流仍然把 anchor 标成 approved
+
+期望：
+
+- review execution 为 `BLOCK`
+
+### H. Source mismatch 但有显式 reconciliation
+
+示例：
+
+- active editor 路径和登记路径不同
+- `pencil-design.md` 中记录了明确 reconciliation
+
+期望：
+
+- 只有在 reconciliation 满足规则时，才允许 `WARN` 或 `PASS`
+
+### I. 还没有新的 Pencil 修改
+
+期望：
+
+- runtime gate 返回 `WARN` 或 partial result
+- 不能伪造 full `PASS`
+
+### J. Pencil MCP 不可用
+
+期望：
+
+- runtime gate 报 unavailable 或 skipped
+- 工作流不能把 runtime gate 视为已通过
+- filesystem audit 仍然可以独立工作
+
+## 必须覆盖的端到端场景
+
+### 场景 1：Cipher 这次真实失败模式
+
+状态：
+
+- active editor 是 `new`
+- live screen 存在
+- `.da-vinci/designs/` 被污染
+- 没有 shell-visible `.pen`
+
+期望：
+
+- runtime gate 阻断完成
+- filesystem completion audit 也失败
+
+### 场景 2：健康的 redesign 完成态
+
+状态：
+
+- active editor 就是登记的 `.pen`
+- anchor ids 存在
+- screenshot review 存在
+- shell-visible `.pen` 存在
+- completion audit 通过
+
+期望：
+
+- runtime gate 通过
+- completion audit 通过
+- 允许终态完成
+
+### 场景 3：runtime 过了，filesystem 没过
+
+状态：
+
+- active editor 正常
+- shell-visible `.pen` 存在
+- 但 `.da-vinci/designs/` 中混入 PNG 或 markdown
+
+期望：
+
+- runtime gate 可以通过
+- filesystem completion audit 失败
+- 不允许终态完成
+
+### 场景 4：filesystem 过了，runtime 没过
+
+状态：
+
+- shell-visible `.pen` 存在
+- 磁盘结构也健康
+- 但 active editor 仍然是 `new` 或指向别处
+
+期望：
+
+- runtime gate 失败
+- 不允许终态完成
+
+## 必须断言的内容
+
+每一条 runtime-gate 测试都应该断言：
+
+- final status
+- 各子层 status
+- 触发的是哪条 blocking condition
+- completion 是否允许继续
+- 工件写入格式是否保持稳定
+
+## 工件记录测试
+
+需要验证 runtime gate 输出：
+
+- 追加到 `pencil-design.md`
+- 不会新增新的工件家族
+- 不会写进 `.da-vinci/designs/`
+- 不会覆盖无关 section
+
+## 回归场景
+
+这些回归必须覆盖：
+
+1. runtime gate 意外退化成 CLI-only audit
+2. runtime gate 静默接受 `new`
+3. runtime gate 把 PNG 当成设计源证据
+4. anchor id 缺失时 runtime gate 仍通过
+5. runtime gate 实际没跑，却被记成通过
+6. runtime gate 输出新的临时 markdown 文件到错误目录
+
+## 建议测试矩阵
+
+最小矩阵：
+
+- form factor：先覆盖 mobile
+- design stage：第一次 Pencil 写入 / anchor approved / terminal completion
+- source state：healthy / `new` / diverged / missing `.pen`
+- screen state：present / missing / stale ids
+- review state：reviewed / missing / blocker ignored
+
+## Exit Criteria
+
+只有以下条件同时满足，才应该认为实现达标：
+
+1. evaluator 单元测试覆盖所有 blocker 分支
+2. 至少有一条 runtime 集成测试证明 live editor 检测可用
+3. Cipher 类失败场景被阻断
+4. 健康 redesign 场景可以通过
+5. runtime gate + filesystem audit 的双层组合，能够阻止假的终态完成