@xenonbyte/da-vinci-workflow 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v0.1.22 - 2026-03-29
+
+### Added
+- `da-vinci icon-sync` to fetch official icon-name catalogs for Material Symbols, Lucide, Feather, and Phosphor into a local cache
+- `lib/icon-sync.js` and `scripts/test-icon-sync.js` for catalog sync, parsing, and offline validation coverage
+- `lib/icon-aliases.js` and `scripts/test-icon-aliases.js` for project/business semantic alias expansion via `~/.da-vinci/icon-aliases.json`
+- `references/icon-aliases.example.json` as a starter alias mapping template
+
+### Changed
+- `da-vinci icon-search` now supports `--aliases <path>` and automatically expands query terms using alias mappings
+- icon search now merges synced catalog entries with built-in fallback entries, preserving availability even when sync data is missing
+- `da-vinci icon-sync` now reports explicit sync health (`OK` vs `DEGRADED`) and supports `--strict` for optional hard-gate behavior in CI
+- `scripts/test-pen-persistence.js` now uses a local mock Pencil binary fixture to keep reopen-verification tests deterministic in sandboxed/no-network environments
+- README, command-reference docs, workflow examples, and constraint-file docs (English and Chinese) now document the sync + search + alias icon workflow consistently
+- `examples/greenfield-spec-markupflow/*` now include advisory icon-system guidance and icon-usage notes
+- package version is aligned to `0.1.22`
+
+## v0.1.21 - 2026-03-29
+
+### Added
+- `scripts/test-mode-consistency.js` coverage for `build` completion-audit discipline and `continue` build-recommendation gate behavior
+- `scripts/test-pencil-session.js` coverage requiring live snapshot input for `pencil-session end` unless `--force` is used
+
+### Changed
+- `da-vinci pencil-session end` now requires `--nodes-file` (and optional variables/version payload) unless `--force` is explicitly provided
+- `build` prompts across Codex, Claude, and Gemini now treat compile success as non-terminal and require completion-audit pass before terminal completion claims
+- `continue` prompts across Codex, Claude, and Gemini now block build recommendation while unresolved design gates exist
+- command reference docs (English and Chinese) now reflect the stricter build/continue routing discipline and completion gate expectations
+
 ## v0.1.20 - 2026-03-29
 
 ### Added

package/README.md

@@ -28,10 +28,14 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.20`
+- `@xenonbyte/da-vinci-workflow@0.1.21`
 
 Release highlights:
 
+- `da-vinci pencil-session end` now requires live snapshot input (`--nodes-file`) unless `--force` is used, preventing silent session close while live MCP and disk are out of sync
+- `build` route discipline now treats compile success as non-terminal and requires `da-vinci audit --mode completion --change <change-id> <project-path>` before reporting terminal completion
+- `continue` route guidance now blocks `build` recommendation whenever core design gates remain unresolved (missing project-local `.pen`, active session, runtime/design-source BLOCK, or required design-supervisor BLOCK)
+- added regression coverage for session-end sync guards and prompt-level build/continue gate discipline
 - continue-routing and recovery guidance now consistently prioritize artifact/checkpoint truth first, with contextual deltas treated as auxiliary notes only
 - context-delta audit now uses tighter expectation signals, status-mismatch wording, and `supersedes` validation with timestamp normalization
 - context-delta expectation checks are now automatic for checkpoint-bearing artifacts and allow explicit opt-in (`Context Delta Required`) only for edge cases
@@ -133,32 +137,14 @@ Recommended default:
 
 ```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
-  - 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, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 Use this when:
@@ -171,33 +157,14 @@ Quality-first redesign configuration:
 
 ```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
-  - 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, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 Use this when:
@@ -479,6 +446,9 @@ 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 icon-sync                      # tolerant by default; add --strict for hard gating
+cp references/icon-aliases.example.json ~/.da-vinci/icon-aliases.json
+da-vinci icon-search --query "settings lock" --family material --top 8
 da-vinci preflight-pencil --ops-file /abs/path/to/ops.txt
 da-vinci uninstall --platform codex,claude,gemini
 ```
@@ -509,6 +479,20 @@ Both modes check the most common workflow-integrity failures in a project:
 - flags common schema drift such as bad `padding`, invalid hex colors, `flex`, `margin`, and `overflow`
 - warns when anchor-surface batches are too large and should be split before retrying
 
+`da-vinci icon-search` helps pick `icon_font` names before rendering:
+
+- run `da-vinci icon-sync` first to fetch official icon names into `~/.da-vinci/icon-catalog.json`
+- default catalog scope is user-level (under current HOME), so one sync is reusable across this user's projects
+- run `da-vinci icon-sync` again when upstream icon libraries change or when you need newly added icons
+- `icon-sync` is non-blocking on partial upstream failures by default (`Status: DEGRADED`); use `da-vinci icon-sync --strict` when CI must fail on any source error
+- use `--catalog <path>` to keep an isolated project-level catalog when needed
+- optionally create `~/.da-vinci/icon-aliases.json` (start from `references/icon-aliases.example.json`) for domain terms like `保险箱`, `解密`, `重试`
+- supports mixed English/Chinese query terms
+- supports family filtering (`material`, `rounded`, `outlined`, `sharp`, `lucide`, `feather`, `phosphor`)
+- automatically expands query terms with alias mappings during ranking
+- returns ranked candidates with ready-to-use `icon_font` node payload hints
+- for a copy-ready `Icon System Guidance (Advisory)` template, see `docs/constraint-files.md` and `references/artifact-templates.md`
+
 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.
 During active redesign work, run `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write, then use `da-vinci preflight-pencil` plus smaller follow-up batches if the same anchor surface rolls back twice.
 
@@ -679,6 +663,7 @@ See:
   - includes `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue` variants in each surface file
 - `docs/workflow-overview.md`
 - `docs/pencil-rendering-workflow.md`
+- `docs/constraint-files.md`
 - `docs/codex-natural-language-usage.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
@@ -695,6 +680,7 @@ Chinese companion documents are included in this repository:
   - each surface file also includes `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue`
 - `docs/zh-CN/workflow-overview.md`
 - `docs/zh-CN/pencil-rendering-workflow.md`
+- `docs/zh-CN/constraint-files.md`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/README.zh-CN.md

@@ -30,10 +30,14 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.20`
+- `@xenonbyte/da-vinci-workflow@0.1.21`
 
 已发布版本重点：
 
+- `da-vinci pencil-session end` 现在默认要求提供 live 快照输入（`--nodes-file`）；只有显式 `--force` 才允许跳过，避免 live MCP 与磁盘未同步时被静默关闭
+- `build` 路由现在明确：编译成功不等于流程完成；对外宣布终态前必须通过 `da-vinci audit --mode completion --change <change-id> <project-path>`
+- `continue` 的推荐规则现在会拦截未过设计门禁时的 `build` 选路（缺少项目内 `.pen`、session 未关闭、runtime/design-source BLOCK、required design-supervisor BLOCK）
+- 新增回归测试覆盖：session 结束同步防护，以及 build/continue 提示词级门禁约束
 - `continue` 的选路与恢复规则现已统一：先看工件/checkpoint 真相，再把 Context Delta 当作辅助信息
 - Context Delta 审计规则已强化：触发信号更精确、告警改为状态不一致语义，并补充 `supersedes` 校验与时间归一化
 - checkpoint 相关工件默认自动启用 Context Delta 期望检查；只有少数无 checkpoint 标题的工件才需要显式 `Context Delta Required`
@@ -138,32 +142,14 @@ Da Vinci 当前支持五种模式：
 
 ```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
-  - 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, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 适用场景：
@@ -176,33 +162,14 @@ Da Vinci 当前支持五种模式：
 
 ```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
-  - 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, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 适用场景：
@@ -400,6 +367,9 @@ 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 icon-sync                      # 默认容错；需要强门禁时加 --strict
+cp references/icon-aliases.example.json ~/.da-vinci/icon-aliases.json
+da-vinci icon-search --query "settings lock" --family material --top 8
 da-vinci preflight-pencil --ops-file /abs/path/to/ops.txt
 da-vinci uninstall --platform codex,claude,gemini
 ```
@@ -430,6 +400,20 @@ Context Delta 与 audit 的关系：
 - 直接标出常见 schema 漂移，比如错误 `padding`、非法 hex 颜色、`flex`、`margin`、`overflow`
 - 当 anchor-surface 批次太大时给出拆批警告，避免继续大块回滚
 
+`da-vinci icon-search` 用于在渲染前选择更稳定的 `icon_font` 名称：
+
+- 先运行 `da-vinci icon-sync`，把官方图标名同步到 `~/.da-vinci/icon-catalog.json`
+- 默认是用户级缓存（当前 HOME 下），同一用户执行一次通常可被多个项目复用
+- 当上游图标库有更新，或你需要最新新增图标时，建议重新执行 `da-vinci icon-sync`
+- `icon-sync` 默认对上游部分失败不阻塞（会标记 `Status: DEGRADED`）；如果 CI 需要任何源失败即退出，请使用 `da-vinci icon-sync --strict`
+- 如果你要项目隔离，可用 `--catalog <path>` 指定项目级 catalog
+- 可选创建 `~/.da-vinci/icon-aliases.json`（可从 `references/icon-aliases.example.json` 拷贝），用于 `保险箱`、`解密`、`重试` 这类业务词
+- 支持中英文混合关键词检索
+- 支持家族过滤（`material`、`rounded`、`outlined`、`sharp`、`lucide`、`feather`、`phosphor`）
+- 检索排序会自动叠加别名扩展词
+- 返回排序候选，并附带可直接复用的 `icon_font` 节点 payload 提示
+- `Icon System Guidance (Advisory)` 可复制模板见 `docs/constraint-files.md` 与 `references/artifact-templates.md`
+
 当 Pencil MCP 可用时，Da Vinci 现在还要求在终态完成声明前，把 MCP runtime gate 结果记录到 `pencil-design.md`。这层 gate 负责检查 live editor/source convergence，与 filesystem audit 分工不同。
 在重设计进行中，如果有 shell 能力，应在第一次成功写入 Pencil 后立即运行 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚，则继续配合 `da-vinci preflight-pencil` 和更小的 follow-up batch。
 
@@ -584,6 +568,7 @@ Continue from proposal, migration-contract, and target specs into design or impl
   - 每个场景文件都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
 - `docs/workflow-overview.md`
 - `docs/pencil-rendering-workflow.md`
+- `docs/constraint-files.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
@@ -598,6 +583,7 @@ Continue from proposal, migration-contract, and target specs into design or impl
   - 每个场景文件也都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
 - `docs/zh-CN/workflow-overview.md`
 - `docs/zh-CN/pencil-rendering-workflow.md`
+- `docs/zh-CN/constraint-files.md`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/commands/claude/dv/build.md

@@ -15,3 +15,9 @@ Focus on:
 During implementation:
 - run `execution checkpoint` after each top-level task group
 - update source artifacts before continuing if drift is found
+
+Completion discipline:
+- treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
+- do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
+- if completion audit fails, continue from the minimal unfinished stage instead of exiting

package/commands/claude/dv/continue.md

@@ -27,4 +27,5 @@ Route discipline:
 - do not default the user into `/dv:build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
 - only prefer `/dv:build` once task generation and implementation readiness are already clear
+- do not route into `/dv:build` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

package/commands/codex/prompts/dv-build.md

@@ -11,3 +11,7 @@ Implementation rules:
 - requirements decide behavior
 - Pencil decides presentation
 - run `execution checkpoint` after each top-level task group
+- treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
+- do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
+- if completion audit fails, continue from the minimal unfinished stage instead of exiting

package/commands/codex/prompts/dv-continue.md

@@ -27,4 +27,5 @@ Route discipline:
 - do not default the user into `/prompts:dv-build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/prompts:dv-tasks`
 - only prefer `/prompts:dv-build` once task generation and implementation readiness are already clear
+- do not route into `/prompts:dv-build` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

package/commands/gemini/dv/build.toml

@@ -10,4 +10,8 @@ Implementation rules:
 - requirements decide behavior
 - Pencil decides presentation
 - run `execution checkpoint` after each top-level task group
+- treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
+- do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
+- if completion audit fails, continue from the minimal unfinished stage instead of exiting
 """

package/commands/gemini/dv/continue.toml

@@ -26,5 +26,6 @@ Route discipline:
 - do not default the user into `/dv:build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
 - only prefer `/dv:build` once task generation and implementation readiness are already clear
+- do not route into `/dv:build` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine
 """

package/docs/constraint-files.md

@@ -0,0 +1,109 @@
+# Constraint Files
+
+This document maps the workflow constraint files and clarifies which fields are machine-parsed gates versus advisory guidance.
+
+Use this when you want one place to understand:
+
+- where constraints live
+- what can be customized freely
+- what can block completion
+
+## Constraint File Map
+
+- `DA-VINCI.md`: project-level visual and workflow contract
+- `.da-vinci/design-registry.md`: preferred project-local `.pen` path and source ownership
+- `.da-vinci/changes/<change-id>/design-brief.md`: form-factor profile, visual direction, and layout-hygiene focus
+- `.da-vinci/changes/<change-id>/design.md`: design plan and composition decisions
+- `.da-vinci/changes/<change-id>/pencil-design.md`: live design record, screenshot review notes, gate evidence
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`: implementation page to Pencil page mapping
+- `.da-vinci/changes/<change-id>/tasks.md`: implementation task plan
+- `.da-vinci/changes/<change-id>/verification.md`: verification and drift summary
+
+## Hard-Gate Fields (Machine Parsed)
+
+The workflow audit currently parses specific fields. Keep these names stable.
+
+### `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` makes missing or blocked supervisor review a completion blocker.
+
+### `pencil-design.md` -> `## Design-Supervisor Review`
+
+- `Status`
+- `Issue list`
+- `Revision outcome`
+
+When supervisor review is required, missing or blocked review evidence blocks completion.
+
+## Advisory Constraint Sections (Customizable)
+
+Any additional section can be used as project guidance. These sections are not hard-gated unless you add custom checks.
+
+For icon guidance specifically, route-level workflow checks do not include a dedicated Pencil icon-lookup API. Use explicit `icon_font` constraints plus screenshot review, and rely on CLI helpers for icon discovery.
+When shell access is available, run `da-vinci icon-sync` to fetch official icon names first, then use `da-vinci icon-search --query "<text>"` to resolve likely `iconFontFamily` + `iconFontName` pairs before writing `batch_design` operations. By default `icon-sync` is non-blocking on partial source failures (reports `Status: DEGRADED`); use `--strict` only when you intentionally want hard gating in CI.
+For product-specific vocabulary, add `~/.da-vinci/icon-aliases.json` (example: `references/icon-aliases.example.json`) so terms like `保险箱`, `解密`, and `重试` expand into icon-friendly query tokens automatically.
+
+Recommended example:
+
+```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.
+```
+
+How to use this template in practice:
+
+1. Copy the section into project-root `DA-VINCI.md`.
+2. Keep it advisory first (`WARN`), and only convert to hard gate when explicit signoff requires it.
+3. Use `da-vinci icon-sync` as a periodic cache refresh (not every design pass).
+4. Run `da-vinci icon-search` when icon intent is ambiguous, icon quality drifts, or a new domain term appears.
+5. Record one `icon consistency` note per anchor screenshot review in `pencil-design.md`.
+
+Field guidance:
+
+- `Goal`: the expected icon-quality outcome for the project.
+- `Source`: require `icon_font` for functional icons; avoid placeholder vectors for real actions.
+- `Allowed families`: approved icon families for this project.
+- `Default family`: preferred first choice to avoid mixed-family drift.
+- `Default spec`: baseline size/weight/color-token policy.
+- `Reuse rule`: whether icon components should be reusable before page-wide expansion.
+- `Placeholder policy`: what is considered unacceptable placeholder behavior.
+- `Review requirement`: what reviewers must explicitly check.
+- `Checkpoint policy`: expected severity (`WARN` or `BLOCK`) and remediation expectation.
+
+Minimal template (recommended default):
+
+```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.
+```
+
+## Recommended Defaults
+
+- keep `Require Supervisor Review: false` unless reviewer signoff is a delivery requirement
+- keep icon guidance advisory by default (`WARN`)
+- raise icon issues to hard-gate only for explicit signoff workflows

package/docs/dv-command-reference.md

@@ -33,6 +33,23 @@ Entry helpers:
 
 These helpers exist to select or resume the correct route. They are not substitutes for the main state machine.
 
+## Supporting CLI Utilities (Outside `dv:` Routes)
+
+These commands do not replace route selection, but they support design execution quality:
+
+- `da-vinci icon-sync`
+  - sync official icon names (Material Symbols, Lucide, Feather, Phosphor) into `~/.da-vinci/icon-catalog.json`
+  - default scope is user-level (current HOME), reusable across projects for the same user
+  - rerun when upstream icon libraries are updated or when you need newly added icons
+  - default behavior is non-blocking on partial source failures (`Status: DEGRADED`)
+  - use `--strict` only when CI should fail on any upstream source error
+  - use `--catalog <path>` for an isolated project-level catalog
+- `da-vinci icon-search --query "<text>" [--family ...] [--top ...] [--aliases ...]`
+  - resolve likely `icon_font` names before writing Pencil `batch_design` operations
+  - supports mixed EN/ZH terms and optional alias expansion via `~/.da-vinci/icon-aliases.json`
+
+Use these utilities during `/dv:design`, especially before anchor-surface icon finalization.
+
 ## Route Meanings
 
 ### `/dv:intake`
@@ -83,6 +100,7 @@ Important continuation rule:
 - it should not promote `build` as a co-equal next step yet
 - route selection should be derived from artifact and checkpoint truth before contextual deltas are consulted
 - if contextual deltas conflict with current artifacts, ignore those deltas for route selection and report the conflict
+- do not route into `build` while design gates are unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime or design-source checkpoint still `BLOCK`, or required design-supervisor review still `BLOCK`/unaccepted
 
 ### `/dv:breakdown`
 
@@ -154,6 +172,12 @@ Creates or updates:
 
 This is the execution stage.
 
+Completion discipline:
+
+- treat `BUILD SUCCESSFUL` as compile-only evidence
+- do not claim `design complete` or `workflow complete` while in-scope task groups remain
+- run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+
 ### `/dv:verify`
 
 Use when:

package/docs/visual-adapters.md

@@ -46,33 +46,14 @@ Recommended shape:
 
 ```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
-  - motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
-- Require Supervisor Review:
-  - false
+- 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, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 Use `Require Adapter: true` only when the workflow must stop if the preferred adapter is unavailable locally.
@@ -83,32 +64,14 @@ Balanced default:
 
 ```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
-  - 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, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 Use this when:
@@ -120,33 +83,14 @@ Quality-first redesign:
 
 ```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
-  - motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - true
-- Require Supervisor Review:
-  - false
+- 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, motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: false
 ```
 
 Use this when: