@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

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

@@ -0,0 +1,249 @@
+# MCP-Aware Gate 设计提案
+
+这份文档定义 Da Vinci 的 MCP-aware runtime gate 设计方向。
+
+它只是一份设计文档，不代表已经开始实现。
+
+## 当前状态
+
+- 设计状态：提案中
+- 可行性状态：已基于真实运行时行为做过部分验证
+- 实现状态：未开始
+
+## 为什么需要它
+
+当前文件系统 `audit` 已经补上了一层重要兜底：
+
+- 能证明项目内 `.pen` 是否真实落盘
+- 能证明 `.da-vinci/designs/` 是否被污染
+- 能证明截图导出是否写错目录
+
+但它证明不了这些 live 运行时事实：
+
+- 当前 active Pencil editor 是否仍然是 `new`
+- 声称完成的 anchor surface 是否真的存在于当前 editor
+- 当前 active editor 和登记的项目内 `.pen` 是否已经收敛
+
+这些事实只存在于 MCP 驱动的设计会话里。
+
+## 已验证的可行性
+
+下面这些事实已经被验证为“当前可读”：
+
+1. 可以通过 MCP 读取 active Pencil editor。
+2. 可以通过 MCP 读取 live 顶层节点。
+3. 可以通过 MCP 读取具体 screen node id。
+4. 可以通过 shell 单独读取项目文件系统状态。
+
+这意味着 Da Vinci 已经可以对比：
+
+- live editor truth
+- live screen truth
+- filesystem truth
+
+这个对比已经足够支持第一版 MCP-aware runtime gate。
+
+## 非目标
+
+这份提案不打算：
+
+- 取代文件系统 `da-vinci audit`
+- 直接把 MCP 状态暴露给 CLI
+- 自动把 live editor 修复成持久化 `.pen`
+- 让实现依赖未验证的 Pencil session 行为
+
+## 设计原则
+
+1. MCP-aware gate 只处理 runtime 真相。
+2. 文件系统 audit 继续作为终态持久化兜底。
+3. runtime gate 只负责阻断假进度，不负责自动修复。
+4. 设计只依赖已经验证过“当前可读”的事实。
+5. 当 Pencil MCP 不可用时，必须能优雅降级。
+
+## 在工作流里的位置
+
+MCP-aware gate 应该插在两个时点：
+
+1. 第一次成功写入 Pencil 之后。
+2. 任何 `design complete` 或 `workflow complete` 声明之前。
+
+它不应该在每一个小操作后都运行。
+
+## 建议的 Gate 分层
+
+### 1. Source Convergence Gate
+
+目的：
+
+- 判断 live editor、登记的 `.pen` 路径和 shell 可见 `.pen` 文件，是否已经足够收敛，可以把设计源视为可追踪
+
+输入：
+
+- MCP 返回的 active Pencil editor 状态
+- `design-registry.md` 中登记的 `.pen` 路径
+- `.da-vinci/designs/` 下 shell 可见的 `.pen` 文件
+
+直接阻断条件：
+
+- active editor 仍然是 `new` 这类未命名 live editor
+- active editor 与登记的项目内设计源不一致，且没有显式记录 reconciliation
+- live Pencil 工作已经发生，但 shell 上仍然没有 `.pen`
+- runtime 会话明显在使用另一个设计源，而不是登记的项目级 `.pen`
+
+结果：
+
+- `PASS`：设计源已收敛
+- `WARN`：设计源暂时延后处理，但仍然可追踪
+- `BLOCK`：设计源不稳定，不能继续
+
+### 2. Screen Presence Gate
+
+目的：
+
+- 确认声称完成的 anchor surface 是否真的存在于当前 live editor 中
+
+输入：
+
+- `pencil-design.md` 中记录的 node id 或 screen id
+- 当前 MCP editor 中的顶层节点或目标节点读取结果
+
+直接阻断条件：
+
+- 声称完成的 anchor screen 在当前 editor 中找不到
+- 截图使用的 node id 在当前 live 文档里不存在
+- 工作流声称完成的 anchor 数量已经超过当前 editor 能解释的范围
+
+结果：
+
+- `PASS`：声称完成的 screen 确实存在
+- `WARN`：命名有漂移，但仍能恢复映射
+- `BLOCK`：设计输出无法追溯到当前 live 文档
+
+### 3. Review Execution Gate
+
+目的：
+
+- 确认 screenshot review 真的是针对当前 live surface 做的，而不是形式化走流程
+
+输入：
+
+- `pencil-design.md` 里记录的 review surface
+- 当前设计会话里实际 review 的 screen id
+- 当前 form factor 对应的 layout hygiene profile
+
+直接阻断条件：
+
+- 一个 surface 被视为已批准，但没有任何 live screenshot review
+- screenshot review 明确出现 blocker 级 layout hygiene 问题，但仍然被标成通过
+- review 记录指向的 screen 在当前 active editor 里根本不存在
+
+结果：
+
+- `PASS`：review 与 live 设计状态一致
+- `WARN`：review 存在，但继续扩张前需要回改
+- `BLOCK`：当前批准结论不可信
+
+## Runtime 输出格式
+
+这层 gate 不应该引入全新的工件类型。
+
+更合理的做法，是把结果追加到 `pencil-design.md` 或同类合法工件里：
+
+```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:
+```
+
+这样 runtime 证据仍然附着在当前设计稿，而不是散落成新的临时文件。
+
+## 和 Filesystem Audit 的关系
+
+两者职责不同。
+
+### MCP-aware runtime gate
+
+- 检查 live editor 真相
+- 检查 live screen 真相
+- 在假进度扩散前发现 runtime/source 不收敛
+
+### Filesystem audit
+
+- 检查磁盘上的项目真相
+- 检查目录卫生
+- 检查完成态完整性
+
+建议的终态规则：
+
+- 只有 MCP-aware runtime gate 通过，同时 filesystem completion audit 也通过，才能声明完成
+
+## 为什么不该先做成 CLI 功能
+
+当前 CLI 只能读文件系统。
+
+它没有 MCP transport、没有 session identity，也读不到当前 live Pencil editor。
+
+所以如果一上来把 MCP-aware gate 做成 CLI 功能，会在结构上不可靠。
+
+当前更合理的定位是：
+
+- 作为 agent 执行的 runtime checkpoint
+- 而不是独立 CLI audit mode
+
+## 需要避免的失败方式
+
+1. 把 `new` 当成已经持久化的 `.pen`
+2. 把 PNG 导出当成设计源证据
+3. 把旧 live document 的 node id 继续当成当前 editor 的事实
+4. runtime/source 不一致时静默自我“和解”
+5. 未经明确规则，就把 live editor 自动写回 `.pen`
+
+## 第一版最小实现范围
+
+第一版实现应该非常收敛。
+
+只做：
+
+1. 读取 active editor 状态
+2. 读取声称完成的 anchor screen id
+3. 和 `design-registry.md` 以及 shell-visible `.pen` 做对照
+4. 记录结构化 PASS/WARN/BLOCK 结果
+5. runtime truth 和 filesystem truth 不一致时阻断完成态
+
+不做：
+
+- 自动重建 `.pen`
+- 除 checkpoint 记录外的自动文件修改
+- 新增面向 live runtime 的 CLI 命令
+
+## 仍待解答的问题
+
+这些问题应该在实现设计阶段解决，而不是在当前提案阶段拍板：
+
+1. 由哪个现有命令路由负责调用 runtime gate？
+2. runtime 证据只写进 `pencil-design.md`，还是也同步到 `design-registry.md`？
+3. editor-path mismatch 被 reconciliation 后，应如何记录才不会鼓励漂移？
+4. gate 应该按每个 approved anchor 运行，还是按每轮 design phase 运行？
+
+## 建议
+
+如果继续推进，只建议做一版收敛的 agent 执行型 MCP-aware runtime gate。
+
+不要顺手扩成：
+
+- CLI transport 工程
+- 自动持久化修复
+- 通用 MCP session 管理
+
+当前已经验证过的稳妥路径是：
+
+1. 保留 filesystem `audit` 作为持久化和终态兜底
+2. 增加 runtime MCP-aware gate，专门处理 source convergence 和 live screen presence
+3. 只有两层都通过，才允许终态完成

package/docs/zh-CN/mode-use-cases.md

@@ -140,6 +140,7 @@ Da Vinci 应该：
    - 首轮设计由解析出来的主 visual adapter 主导
    - 把新的 Pencil 基线真正落到登记好的 `.da-vinci/designs/` 路径
    - 在第一次成功写入 Pencil 后，立即验证登记的 `.pen` 路径已经成为 shell 可见文件
+   - 截图导出必须写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
 11. 进入实现
@@ -165,6 +166,8 @@ Da Vinci 应该：
 - 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 - `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
+- 截图 PNG 只是审查产物，不能替代登记好的 `.pen` 设计源
+- 如果当前 Pencil editor 仍然是 `new` 或其他未命名 live document，就不能宣布工作流完成
 
 ## 4. `feature-change`
 

package/docs/zh-CN/prompt-presets/README.md

@@ -25,6 +25,7 @@
 
 - 提示词模板负责定义工作流意图、拆分规则和真相源处理方式
 - `Visual Assist` 模板负责定义 UI 设计增强偏好
+- form factor 专用的 layout hygiene 仍然是独立硬闸门，screen 在通过 screenshot review 前必须应用对应规则
 - 两者一起使用，结果通常更稳
 
 现在每个场景模板里都固定包含：

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

@@ -41,11 +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.
+在开始第一个 anchor surface 之前，先把 discovery 和 design-source 工件写到标准路径。
 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.
+在通过 screenshot review 之前，先应用桌面端专用的 form-factor layout hygiene 规则。
+截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
 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/zh-CN/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.
+在开始第一个 anchor surface 之前，先把 discovery 和 design-source 工件写到标准路径。
 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.
@@ -50,9 +51,12 @@ Do not start with broad multi-screen scaffolding.
 Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout.
 Do not treat screenshot analysis as an automatic pass if it reports hierarchy, spacing, clarity, or inconsistency issues.
+在通过 screenshot review 之前，先应用移动端专用的 form-factor layout hygiene 规则。
 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/`.
+截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
 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/zh-CN/prompt-presets/tablet-app.md

@@ -41,11 +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.
+在开始第一个 anchor surface 之前，先把 discovery 和 design-source 工件写到标准路径。
 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.
+在通过 screenshot review 之前，先应用平板端专用的 form-factor layout hygiene 规则。
+截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
 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/zh-CN/prompt-presets/web-app.md

@@ -42,11 +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.
+在开始第一个 anchor surface 之前，先把 discovery 和 design-source 工件写到标准路径。
 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.
+在通过 screenshot review 之前，先应用 Web 专用的 form-factor layout hygiene 规则。
+截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
+如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
 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/zh-CN/visual-adapters.md

@@ -26,6 +26,11 @@ visual adapter 是可选的 presentation 质量增强层。
 
 这些仍然由 requirements、existing code、`page-map.md` 和 `pencil-bindings.md` 决定。
 
+visual adapter 也不能替代按 form factor 执行的 layout hygiene 规则。
+
+- adapter 负责 art direction
+- layout hygiene 负责判断当前 screen 对于其 form factor 是否结构上合格
+
 ## 应该配置在哪里
 
 把 visual adapter 偏好写在 `DA-VINCI.md` 里。
@@ -51,6 +56,7 @@ visual adapter 是可选的 presentation 质量增强层。
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -73,6 +79,7 @@ visual adapter 是可选的 presentation 质量增强层。
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -97,6 +104,7 @@ visual adapter 是可选的 presentation 质量增强层。
   - page composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -122,6 +130,7 @@ visual adapter 是可选的 presentation 质量增强层。
 - `Scope`
   - adapter 被允许影响的范围
   - 应该限制在构图、层级、spacing、Pencil refinement 这类 presentation 质量问题
+  - 当重设计高度依赖首轮视觉质量时，也应该把 anchor-surface composition 明确写进 `Scope`
   - 不要把 behavior、route、state truth 交给它
 - `Fallback`
   - 当本地没有可用 adapter 时应该怎么处理

package/docs/zh-CN/visual-assist-presets/README.md

@@ -20,6 +20,7 @@
 - 视情况把 `Require Adapter` 改成 `true`
 - 在大规模 Pencil 设计前先把 design checkpoint 门槛抬高
 - 改成 anchor-first：先做 1 到 3 个 anchor surface，截图审查通过后再扩展
+- 把 `Preferred adapters` 改成当前环境里真实存在的 adapter 名，不要默认沿用跨平台别名
 
 可用模板：
 
@@ -32,6 +33,7 @@
 
 1. 先选最接近当前产品形态的模板
 2. 把其中的 `## Visual Assist` 片段复制到 `DA-VINCI.md`
-3. 只有在项目真的有不同视觉偏向时才调整 adapter 顺序
-4. 除非确实“没有某个本地 skill 就不能继续”，否则保持 `Require Adapter: false`
-5. 如果是复杂重设计，不要只复制 preset 就开画；还要配合 anchor-first 的 Pencil 生成策略
+3. 如果当前环境里的 adapter 名不同，先把 `Preferred adapters` 改成真实可用名称
+4. 只有在项目真的有不同视觉偏向时才调整 adapter 顺序
+5. 除非确实“没有某个本地 skill 就不能继续”，否则保持 `Require Adapter: false`
+6. 如果是复杂重设计，不要只复制 preset 就开画；还要配合 anchor-first 的 Pencil 生成策略

package/docs/zh-CN/visual-assist-presets/desktop-app.md

@@ -18,6 +18,7 @@
   - workspace composition
   - hierarchy and spacing
   - motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -28,5 +29,6 @@
 说明：
 
 - 优先用 `ui-ux-pro-max` 做高密度 app 布局判断
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - `frontend-skill` 更适合作为辅助，不要反过来把工具界面做成营销页
 - 如果结果太平、太盒子化、太像通用后台，就把 `frontend-skill` 调到第一位，并提高 design checkpoint 的要求

package/docs/zh-CN/visual-assist-presets/mobile-app.md

@@ -17,6 +17,7 @@
   - mobile page composition
   - hierarchy and spacing
   - touch-first motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -27,5 +28,6 @@
 说明：
 
 - `ui-ux-pro-max` 更适合移动端 app 表面的密度和平衡
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - motion 要轻，不要把普通 app 页面做成营销页
 - 如果结果总是变成泛化卡片堆砌或层级太弱，就把 `frontend-skill` 调到第一位，并考虑把 `Require Adapter` 改成 `true`

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

@@ -17,6 +17,7 @@
   - tablet page composition
   - hierarchy and spacing
   - touch-aware motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -27,5 +28,6 @@
 说明：
 
 - spacing 一般要比手机更舒展，但又不能像桌面端那样过密
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - 更适合用 adapter 去辅助分栏、画布区和主次区域的平衡
 - 如果结果还是寡淡或被边框框死，就把 `frontend-skill` 调到第一位，并要求在 Pencil 设计前先写清楚 visual thesis

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

@@ -18,6 +18,7 @@
   - page composition
   - hierarchy and spacing
   - responsive motion guidance
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci
@@ -28,5 +29,6 @@
 说明：
 
 - 如果是典型 product UI，优先 `ui-ux-pro-max`
+- 如果当前环境里的 adapter 名不一样，先改成真实可用名称
 - 如果页面更偏品牌表达或强视觉，可以把 `frontend-skill` 放前面
 - 如果结果像很普通的 SaaS 模板，就把 `frontend-skill` 提到第一位，并把 `DA-VINCI.md` 的视觉方向写得更具体

package/docs/zh-CN/workflow-examples.md

@@ -94,10 +94,13 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 7. 先写出 anchor surface 的 visual thesis、content plan、interaction thesis 和 structural-delta 说明
 8. 创建新的或更新后的 Pencil 页面，基于重新构图而不是旧 UI 换皮，并优先持久化到 `.da-vinci/designs/`
 9. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
-10. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
-11. 绑定路由和 Pencil 页面
-12. 生成和 redesign slice 对齐的任务
-13. 实现并验证
+10. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
+11. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+12. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
+13. 绑定路由和 Pencil 页面
+14. 生成和 redesign slice 对齐的任务
+15. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
+16. 只有在 completion gate 最终能通过时，才进入实现和验证
 
 ### 复杂 Android 页面示例
 
@@ -118,6 +121,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/examples/greenfield-spec-markupflow/DA-VINCI.md

@@ -42,6 +42,7 @@
   - visual contract refinement
   - page composition
   - hierarchy and spacing
+  - anchor-surface composition
   - Pencil design refinement
 - Fallback:
   - native-da-vinci

package/examples/greenfield-spec-markupflow/README.md

@@ -40,7 +40,10 @@ Live design source used for this forward test:
 Visual adapter used for this forward test:
 
 - requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- available requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- unavailable requested adapters: none
 - resolved primary adapter: `frontend-skill`
+- runtime declaration: explicit before first anchor pass
 - fallback: `native-da-vinci` if no local adapter were available
 
 Important note:

package/examples/greenfield-spec-markupflow/design-registry.md

@@ -10,9 +10,12 @@
 
 ## Visual Adapter Resolution
 - Requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- Available requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- Unavailable requested adapters: none
 - Resolved primary adapter: `frontend-skill`
 - Secondary helpers: none
 - Status: active
+- Runtime declaration: explicitly stated before first anchor pass
 - Scope: `DA-VINCI.md`, `design.md`, `pencil-design.md`
 - Fallback reason if native Da Vinci rules were used: none
 

package/examples/greenfield-spec-markupflow/pencil-design.md

@@ -8,8 +8,12 @@
   - `MarkupFlow Product Detail`
 
 ## Visual Adapter Use
+- Available requested adapters: `frontend-skill`, `ui-ux-pro-max`
+- Unavailable requested adapters: none
 - Resolved primary adapter: `frontend-skill`
 - Secondary helpers: none
+- Whether runtime execution explicitly declared the resolved primary adapter: yes
+- Whether the primary adapter actively led the first-pass composition: yes
 - How it affected composition, hierarchy, or motion guidance:
   - stronger hero anchor for the desktop-product story
   - restrained panel treatment instead of generic card grids