@xenonbyte/da-vinci-workflow 0.1.20 → 0.1.22

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

@@ -21,20 +21,10 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Scope:
-  - visual contract refinement
-  - workspace composition
-  - hierarchy and spacing
-  - motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Scope: visual contract refinement, workspace composition, hierarchy and spacing, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
 ```
 
 ### Variant 2: Advisory Supervisor Review
@@ -46,33 +36,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - workspace composition
-  - hierarchy and spacing
-  - motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
-- Require Supervisor Review:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, workspace composition, hierarchy and spacing, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 ### Variant 3: Required Supervisor Signoff
@@ -85,33 +56,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - workspace composition
-  - hierarchy and spacing
-  - motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - true
-- Require Supervisor Review:
-  - true
+- Preferred adapters: frontend-skill, ui-ux-pro-max
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, workspace composition, hierarchy and spacing, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 Notes for all variants:

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

@@ -21,20 +21,10 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Scope:
-  - visual contract refinement
-  - mobile page composition
-  - hierarchy and spacing
-  - touch-first motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Scope: visual contract refinement, mobile page composition, hierarchy and spacing, touch-first motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
 ```
 
 ### Variant 2: Advisory Supervisor Review
@@ -47,33 +37,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - mobile page composition
-  - hierarchy and spacing
-  - touch-first motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
-- Require Supervisor Review:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, mobile page composition, hierarchy and spacing, touch-first motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 ### Variant 3: Required Supervisor Signoff
@@ -86,33 +57,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - mobile page composition
-  - hierarchy and spacing
-  - touch-first motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - true
-- Require Supervisor Review:
-  - true
+- Preferred adapters: frontend-skill, ui-ux-pro-max
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, mobile page composition, hierarchy and spacing, touch-first motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 Notes for all variants:

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

@@ -21,20 +21,10 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Scope:
-  - visual contract refinement
-  - tablet page composition
-  - hierarchy and spacing
-  - touch-aware motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Scope: visual contract refinement, tablet page composition, hierarchy and spacing, touch-aware motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
 ```
 
 ### Variant 2: Advisory Supervisor Review
@@ -46,33 +36,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - tablet page composition
-  - hierarchy and spacing
-  - touch-aware motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
-- Require Supervisor Review:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, tablet page composition, hierarchy and spacing, touch-aware motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 ### Variant 3: Required Supervisor Signoff
@@ -85,33 +56,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - tablet page composition
-  - hierarchy and spacing
-  - touch-aware motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - true
-- Require Supervisor Review:
-  - true
+- Preferred adapters: frontend-skill, ui-ux-pro-max
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, tablet page composition, hierarchy and spacing, touch-aware motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 Notes for all variants:

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

@@ -21,20 +21,10 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - responsive motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Scope: visual contract refinement, page composition, hierarchy and spacing, responsive motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
 ```
 
 ### Variant 2: Advisory Supervisor Review
@@ -46,33 +36,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - responsive motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
-- Require Supervisor Review:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, page composition, hierarchy and spacing, responsive motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 ### Variant 3: Required Supervisor Signoff
@@ -85,33 +56,14 @@ Use when:
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - responsive motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - true
-- Require Supervisor Review:
-  - true
+- Preferred adapters: frontend-skill, ui-ux-pro-max
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, page composition, hierarchy and spacing, responsive motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 Notes for all variants:

package/docs/workflow-examples.md

@@ -85,19 +85,20 @@ 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. preflight non-trivial `batch_design` operation strings before sending them to Pencil, and keep anchor-surface batches small
-10. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
-11. require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
-12. during live design work, use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
-13. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
-14. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
-15. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
-16. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-17. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
-18. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
-19. bind routes and pages to Pencil screens
-20. generate tasks aligned to the redesign slices
-21. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
-22. build and verify only after the completion gate can eventually pass
+10. for functional icons, run `da-vinci icon-sync` then `da-vinci icon-search --query "<intent>"` to pick `icon_font` names before writing icon nodes
+11. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
+12. require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
+13. during live design work, use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
+14. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+15. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
+16. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
+17. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+18. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
+19. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
+20. bind routes and pages to Pencil screens
+21. generate tasks aligned to the redesign slices
+22. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+23. build and verify only after the completion gate can eventually pass
 
 ### Complex Android example
 
@@ -191,6 +192,21 @@ If no registered project-local `.pen` exists yet, seed it there before the first
 If a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
 ```
 
+## Icon-library helper example
+
+Use:
+
+```text
+da-vinci icon-sync
+cp references/icon-aliases.example.json ~/.da-vinci/icon-aliases.json
+da-vinci icon-search --query "保险箱 解密 重试" --family material --top 8
+```
+
+Notes:
+
+- use `icon-sync --strict` only in CI or explicit hard-gate workflows
+- keep icon-family consistency per anchor surface unless there is a deliberate rationale
+
 ## Cross-mode rule
 
 In every mode:

package/docs/workflow-overview.md

@@ -12,6 +12,7 @@ Use it when you need the high-level delivery chain:
 
 Use [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/pencil-rendering-workflow.md) when you need the lower-level Pencil session, persistence, gate, and audit details.
 Use [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/dv-command-reference.md) when you need route-by-route `dv:` command behavior, next-step recommendations, and verify rollback handling.
+Use [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/constraint-files.md) when you need a single map for project constraint files, hard-gate fields, and advisory guidance sections.
 
 ## Core Contract
 
@@ -115,6 +116,7 @@ Anchor surfaces must:
 - include structural-delta notes for redesign-from-code
 - stay aligned with the approved `migration-contract.md`, `page-map.md`, and new `specs/` when the active mode is `overhaul-from-code`
 - go through screenshot review
+- resolve functional icon names with `da-vinci icon-sync` + `da-vinci icon-search` when shell access is available
 - satisfy the active form-factor layout-hygiene profile
 - pass the design checkpoint before broad expansion
 - run `design-supervisor review` when `DA-VINCI.md` configures `Design-supervisor reviewers`, and treat it as blocking only when `Require Supervisor Review: true`

package/docs/zh-CN/constraint-files.md

@@ -0,0 +1,111 @@
+# 约束文件说明
+
+> 中文配套文档。若与英文原文存在差异，请以 `docs/constraint-files.md` 为准。
+
+这份文档用于统一说明 Da Vinci 的约束文件，以及哪些字段是机器硬门禁，哪些只是设计指导。
+
+适合在你需要确认下面问题时阅读：
+
+- 约束写在哪些文件
+- 哪些内容可以自由定制
+- 哪些字段会阻断 completion
+
+## 约束文件地图
+
+- `DA-VINCI.md`：项目级视觉与工作流契约
+- `.da-vinci/design-registry.md`：项目内优先 `.pen` 路径与设计源归属
+- `.da-vinci/changes/<change-id>/design-brief.md`：form-factor、视觉方向、layout-hygiene 重点
+- `.da-vinci/changes/<change-id>/design.md`：设计计划与构图决策
+- `.da-vinci/changes/<change-id>/pencil-design.md`：实时设计记录、截图评审、门禁证据
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`：实现页面到 Pencil 页面的绑定
+- `.da-vinci/changes/<change-id>/tasks.md`：实现任务拆分
+- `.da-vinci/changes/<change-id>/verification.md`：验证与漂移总结
+
+## 硬门禁字段（机器解析）
+
+当前审计会解析特定字段名。以下字段建议保持稳定。
+
+### `DA-VINCI.md` -> `## Visual Assist`
+
+- `Preferred adapters`
+- `Design-supervisor reviewers`
+- `Design-supervisor review mode`
+- `Design-supervisor review inputs`
+- `Scope`
+- `Fallback`
+- `Require Adapter`
+- `Require Supervisor Review`
+
+当 `Require Supervisor Review: true` 时，缺失或阻断的 supervisor review 会卡住 completion。
+
+### `pencil-design.md` -> `## Design-Supervisor Review`
+
+- `Status`
+- `Issue list`
+- `Revision outcome`
+
+当 supervisor review 是必需时，缺失或 `BLOCK` 的评审证据会阻断 completion。
+
+## 指导型约束段（可定制）
+
+你可以增加任意自定义段作为项目指导。默认不会成为硬门禁，除非你额外实现自定义检查。
+
+图标指导当前也属于这个层级：`dv:` 路由本身没有独立的 Pencil 图标检索 API，通常通过显式 `icon_font` 约束 + 截图复核来收敛质量，再配合 CLI 图标检索能力。
+如果有 shell 能力，建议先运行 `da-vinci icon-sync` 同步官方图标名，再运行 `da-vinci icon-search --query "<关键词>"`，先收敛 `iconFontFamily` + `iconFontName`，再写入 `batch_design`。`icon-sync` 默认对上游部分失败不阻塞（会显示 `Status: DEGRADED`）；只有在 CI 里确实需要强门禁时再加 `--strict`。
+如果有业务语义词，建议补充 `~/.da-vinci/icon-aliases.json`（可用 `references/icon-aliases.example.json` 作为起点），让 `保险箱`、`解密`、`重试` 这类词自动扩展成更稳定的图标检索词。
+
+推荐示例：
+
+```md
+## Icon System Guidance (Advisory)
+- Goal: improve icon consistency and visual quality without blocking delivery.
+- Source: functional icons should prefer `icon_font`.
+- Allowed families: `Material Symbols Rounded`, `lucide`, `feather`, `phosphor`.
+- Default family: `Material Symbols Rounded`.
+- Default spec: `24x24`, `weight 700` (when supported), unified color token per surface.
+- Reuse rule: prefer reusable `Icon/*` components, then `ref` reuse.
+- Placeholder policy: avoid placeholder geometry for functional icons.
+- Review requirement: each anchor screenshot review should include an `icon consistency` note.
+- Checkpoint policy: icon inconsistency => `WARN` (not `BLOCK`), then fix in next visual pass.
+```
+
+落地使用建议：
+
+1. 把这一段直接复制到项目根目录 `DA-VINCI.md`。
+2. 默认先保持指导型（`WARN`），只有明确签收流程才升级成硬门禁。
+3. `da-vinci icon-sync` 作为周期性缓存刷新使用，不需要每次 design 都执行。
+4. 只有在图标语义不明确、图标质量漂移、或出现新业务词时，再执行 `da-vinci icon-search`。
+5. 每个 anchor 的截图评审在 `pencil-design.md` 里至少记录一条 `icon consistency` 结论。
+
+字段解释：
+
+- `Goal`：本项目希望达到的图标质量目标。
+- `Source`：功能图标的来源约束，通常要求优先 `icon_font`。
+- `Allowed families`：项目允许的图标家族范围。
+- `Default family`：默认首选家族，用于避免混用漂移。
+- `Default spec`：默认尺寸、字重、颜色 token 规则。
+- `Reuse rule`：是否要求先沉淀可复用 Icon 组件再扩屏。
+- `Placeholder policy`：哪些占位图标行为不可接受。
+- `Review requirement`：评审时必须显式检查什么。
+- `Checkpoint policy`：问题严重度（`WARN` / `BLOCK`）和回改预期。
+
+最小模板（推荐默认）：
+
+```md
+## Icon System Guidance (Advisory)
+- Goal: improve icon consistency and visual quality without blocking delivery.
+- Source: functional icons should prefer `icon_font`.
+- Allowed families: `Material Symbols Rounded`, `lucide`, `feather`, `phosphor`.
+- Default family: `Material Symbols Rounded`.
+- Default spec: `24x24`, `weight 700` (when supported), unified color token per surface.
+- Reuse rule: prefer reusable `Icon/*` components, then `ref` reuse.
+- Placeholder policy: avoid placeholder geometry for functional icons.
+- Review requirement: each anchor screenshot review should include an `icon consistency` note.
+- Checkpoint policy: icon inconsistency => `WARN` (not `BLOCK`), then fix in next visual pass.
+```
+
+## 推荐默认值
+
+- 除非确实需要 reviewer 签字，否则保持 `Require Supervisor Review: false`
+- 默认把图标策略作为指导型约束（`WARN`）
+- 只有在明确签收流程里，才把图标问题升级成硬门禁

package/docs/zh-CN/dv-command-reference.md

@@ -35,6 +35,23 @@ Da Vinci 期望它们遵循工作流状态。
 
 这些辅助入口负责选路和续跑，不是主状态机本身。
 
+## 路由外的辅助 CLI 能力
+
+这些命令不会替代 `dv:` 选路，但能显著提升设计执行质量：
+
+- `da-vinci icon-sync`
+  - 同步官方图标名（Material Symbols、Lucide、Feather、Phosphor）到 `~/.da-vinci/icon-catalog.json`
+  - 默认是用户级范围（当前 HOME），同一用户可跨项目复用
+  - 当上游图标库更新或需要最新新增图标时，应重新执行
+  - 默认对上游部分失败不阻塞（`Status: DEGRADED`）
+  - 只有在 CI 需要强门禁时才加 `--strict`
+  - 需要项目隔离时可用 `--catalog <path>` 指定项目级 catalog
+- `da-vinci icon-search --query "<关键词>" [--family ...] [--top ...] [--aliases ...]`
+  - 在写 Pencil `batch_design` 前先收敛可用的 `icon_font` 名称
+  - 支持中英文混合词，并可通过 `~/.da-vinci/icon-aliases.json` 做语义扩展
+
+建议在 `/dv:design` 阶段使用，尤其是在 anchor surface 的图标定稿前。
+
 ## 每个路由的含义
 
 ### `/dv:intake`
@@ -85,6 +102,7 @@ Da Vinci 期望它们遵循工作流状态。
 - 这时候不应该把 `build` 当成同级主推荐
 - 选路必须先基于工件和 checkpoint 真相，再参考 Context Delta
 - 如果 Context Delta 与当前工件冲突，选路时应忽略冲突条目并记录冲突
+- 当设计门禁还未收敛时，不应路由到 `build`：包括缺少 shell 可见的项目本地 `.pen`、Pencil session 仍为 active/unclosed、runtime 或 design-source checkpoint 仍是 `BLOCK`、或必需的 design-supervisor review 仍是 `BLOCK`/未接受
 
 ### `/dv:breakdown`
 
@@ -154,6 +172,12 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层才是真正的执行阶段。
 
+完成判定规则：
+
+- `BUILD SUCCESSFUL` 只代表可编译，不代表 workflow 完成
+- 只要 in-scope task groups 还没做完，就不能宣告 `design complete` 或 `workflow complete`
+- 任何终态声明前都要运行 `da-vinci audit --mode completion --change <change-id> <project-path>` 并通过
+
 ### `/dv:verify`
 
 适合：