@xenonbyte/da-vinci-workflow 0.1.21 → 0.1.23

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## v0.1.23 - 2026-03-29
+
+### Added
+- `lib/audit-parsers.js` to isolate markdown/checkpoint/context-delta/design-supervisor parsing concerns from audit orchestration
+- `lib/fs-safety.js` for bounded recursive traversal and project-root path-boundary checks
+- `lib/icon-text.js` to share icon text normalization/tokenization across icon modules
+- `scripts/test-audit-safety.js` to cover out-of-root registry paths and traversal truncation warnings
+- `test:audit-safety` npm script
+
+### Changed
+- `lib/audit.js` now uses bounded safe scans, emits traversal warnings, and rejects out-of-root registry `.pen` references
+- `lib/install.js` now uses bounded safe traversal for asset enumeration
+- `lib/pencil-preflight.js` now hardens VM execution with unsafe-source checks, disabled dynamic code generation, source-size limits, and explicit timeout classification
+- `lib/icon-search.js` and `lib/icon-aliases.js` now consume shared text utilities instead of duplicate local implementations
+- preflight/icon tests now include safety and normalization regression coverage
+
+## 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

package/README.md

@@ -28,10 +28,15 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.21`
+- `@xenonbyte/da-vinci-workflow@0.1.23`
 
 Release highlights:
 
+- audit parser logic is now split into `lib/audit-parsers.js`, reducing `lib/audit.js` size and making maintenance safer
+- recursive file traversal now uses bounded safe scans with depth/count limits and symlink skipping
+- completion/integrity audit now rejects out-of-root `.pen` references from `design-registry.md`
+- `preflight-pencil` sandbox now blocks unsafe runtime tokens, disables dynamic code generation, and reports timeout failures explicitly
+- icon text normalization/tokenization is now shared across `icon-search` and `icon-aliases`, removing duplicated logic and adding parity coverage
 - `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)
@@ -446,6 +451,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
 ```
@@ -476,6 +484,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.
 
@@ -646,6 +668,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/`
@@ -662,6 +685,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,15 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.21`
+- `@xenonbyte/da-vinci-workflow@0.1.23`
 
 已发布版本重点：
 
+- audit 解析职责已拆分到 `lib/audit-parsers.js`，`lib/audit.js` 体量下降，可维护性更好
+- 递归文件扫描改为安全有界遍历：增加深度/数量上限，并跳过符号链接
+- completion/integrity audit 现在会拦截并忽略 `design-registry.md` 中越出项目根目录的 `.pen` 引用
+- `preflight-pencil` 沙箱增强：拦截危险运行时 token、禁用动态代码生成，并对超时失败给出明确分类
+- `icon-search` 与 `icon-aliases` 现在复用同一套文本归一化/分词逻辑，去掉重复实现并补了一致性回归测试
 - `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）
@@ -367,6 +372,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
 ```
@@ -397,6 +405,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。
 
@@ -551,6 +573,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`
@@ -565,6 +588,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/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`

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`

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

@@ -96,19 +96,20 @@ $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. 在把 operations 发给 Pencil 前，先对非小型 `batch_design` 做 preflight，并保持 anchor-surface 批次足够小
-10. 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
-11. 如果这一轮开始时还没有登记的项目内 `.pen`，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，先 seed 登记路径并拿到全局锁，再开始第一次 Pencil 编辑
-12. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
-13. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
-14. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
-15. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
-16. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
-17. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
-18. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
-19. 绑定路由和 Pencil 页面
-20. 生成和 redesign slice 对齐的任务
-21. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
-22. 只有在 completion gate 最终能通过时，才进入实现和验证
+10. 对功能性图标，先运行 `da-vinci icon-sync` 再运行 `da-vinci icon-search --query "<意图词>"`，先选定 `icon_font` 名称再写图标节点
+11. 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
+12. 如果这一轮开始时还没有登记的项目内 `.pen`，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，先 seed 登记路径并拿到全局锁，再开始第一次 Pencil 编辑
+13. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
+14. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
+15. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
+16. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
+17. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+18. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
+19. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
+20. 绑定路由和 Pencil 页面
+21. 生成和 redesign slice 对齐的任务
+22. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
+23. 只有在 completion gate 最终能通过时，才进入实现和验证
 
 ### 复杂 Android 页面示例
 
@@ -208,6 +209,21 @@ Persist project-local Pencil files under .da-vinci/designs/.
 如果项目里原本已有 `.pen`，继续设计后要把当前 MCP 快照覆盖写回同一路径。
 ```
 
+## 图标库辅助示例
+
+可执行示例：
+
+```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
+```
+
+说明：
+
+- 只有在 CI 或明确强门禁流程里，才建议使用 `icon-sync --strict`
+- 单个 anchor surface 内尽量保持同一图标家族，除非有明确设计理由
+
 ## 复杂重设计的入口辅助示例
 
 如果用户起点是复杂的存量项目重设计，可以先这样：

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

@@ -14,6 +14,7 @@
 
 如果你想看 Pencil 渲染、持久化、门禁和审计的专门说明，请看 [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/pencil-rendering-workflow.md)。
 如果你想看逐个 `dv:` 命令的职责、下一步推荐和 `verify` 回退规则，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
+如果你想看约束文件总览（哪些字段是硬门禁、哪些是指导项），请看 [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/constraint-files.md)。
 
 ## 核心契约
 
@@ -117,6 +118,7 @@ Da Vinci 围绕一个固定契约工作：
 - 在 redesign-from-code 下写 structural-delta 说明
 - 如果当前 mode 是 `overhaul-from-code`，还要和已经批准的 `migration-contract.md`、`page-map.md`、新 `specs/` 保持一致
 - 经过 screenshot review
+- 如果有 shell 能力，先用 `da-vinci icon-sync` + `da-vinci icon-search` 收敛功能性图标名称
 - 满足当前 form factor 的 layout-hygiene 规则
 - 通过 design checkpoint 才能扩屏
 - 如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，还要运行 `design-supervisor review`；只有 `Require Supervisor Review: true` 时，它才是阻断性的最终风格质量 gate

package/examples/greenfield-spec-markupflow/DA-VINCI.md

@@ -40,6 +40,15 @@
 - Fallback: native-da-vinci
 - Require Adapter: false
 
+## Icon System Guidance (Advisory)
+- Goal: keep product-marketing icons coherent and functional
+- Source: prefer `icon_font` for functional icons
+- Allowed families: `Material Symbols Rounded`, `lucide`, `feather`, `phosphor`
+- Default family: `Material Symbols Rounded`
+- Default spec: `24x24`, `weight 700` (when supported)
+- Reuse rule: define reusable icon instances before broad expansion
+- Checkpoint policy: icon inconsistency is `WARN`, fix in next visual pass
+
 ## Do
 - keep page sections clearly bounded
 - use contrast panels to explain structured output

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

@@ -46,6 +46,13 @@ Visual adapter used for this forward test:
 - runtime declaration: explicit before first anchor pass
 - fallback: `native-da-vinci` if no local adapter were available
 
+Icon library workflow used for this forward test:
+
+- sync command: `da-vinci icon-sync`
+- alias template: `cp references/icon-aliases.example.json ~/.da-vinci/icon-aliases.json`
+- lookup command example: `da-vinci icon-search --query "settings publish workflow" --family material --top 6`
+- gate policy: icon lookup remains advisory by default; use `--strict` only for explicit CI hard gates
+
 Important note:
 
 - the `.pen` source was authored in a live Pencil session and the example records `.da-vinci/designs/project-baseline.pen` as the intended project-local persisted path

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

@@ -41,6 +41,11 @@
 - keep the structural emphasis on three core capabilities on page one
 - keep the import, annotate, publish pipeline readable on page two
 
+## Icon Notes
+- functional icons are expected to use `icon_font` instead of placeholder geometry
+- preferred family for this pass: `Material Symbols Rounded`
+- when icon intent is ambiguous, resolve candidates via `da-vinci icon-search` before writing `batch_design`
+
 ## Validation Notes
 - both screens were reviewed in Pencil during authoring
 - no obvious clipping, overlap, or alignment failures were observed in the design pass