@xenonbyte/da-vinci-workflow 0.1.19 → 0.1.21

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:

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

@@ -14,6 +14,8 @@ Common rule:
 
 - `intake` and `continue` should usually generate a main `$da-vinci ...` or `/da-vinci ...` prompt
 - they should not default the user into `build` unless implementation readiness is already clear
+- `continue` should pick routes from artifact/checkpoint truth first, then use contextual deltas as auxiliary recovery notes
+- if contextual deltas conflict with current artifacts, ignore them for routing and record the conflict
 
 ## 1. `greenfield-spec`
 

package/docs/workflow-overview.md

@@ -128,6 +128,7 @@ Before mapping or implementation are treated as safe, Da Vinci runs:
 - `design-source checkpoint`
 - `MCP runtime gate` when Pencil MCP is active
 - `da-vinci audit --mode integrity <project-path>` during active work
+- checkpoint-adjacent `Context Delta` notes in existing change artifacts
 
 These checks verify that:
 
@@ -135,6 +136,7 @@ These checks verify that:
 - the active editor is the correct source
 - the shell-visible `.pen` exists
 - live snapshot and persisted snapshot are in sync
+- recent execution context is recoverable without replacing artifact truth as the routing authority
 
 ### 6. Mapping
 
@@ -163,6 +165,10 @@ The workflow must not report `design complete`, `workflow complete`, or any equi
 - MCP runtime gate is acceptable when Pencil MCP was used
 - `da-vinci audit --mode completion --change <change-id> <project-path>` passes
 
+Notes:
+
+- contextual delta warnings improve resume quality but do not create new completion blockers by themselves
+
 ## Gates And Audits
 
 ### Design Checkpoint
@@ -217,6 +223,11 @@ Run during active work, especially after the first successful Pencil write.
 
 Run before any terminal completion claim.
 
+Context-delta handling in audit:
+
+- missing, incomplete, or status-mismatched contextual deltas are warning-level quality signals
+- route and completion truth still come from artifacts, checkpoints, runtime gate, and filesystem audit
+
 ## Flow Diagram
 
 ```mermaid

package/docs/zh-CN/codex-natural-language-usage.md

@@ -54,6 +54,7 @@ $da-vinci use continue for <existing workflow state>
 - 已经存在 `DA-VINCI.md`
 - 已经存在 `.da-vinci/` 工件
 - 工作流中途暂停，需要恢复
+- 选路应先基于工件/checkpoint 真相，再参考 Context Delta
 
 ### 直接运行某个 mode
 
@@ -152,6 +153,8 @@ $da-vinci use continue for this existing redesign-from-code workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Existing code remains the behavior source of truth.
+Determine route progression from current artifacts and checkpoints first.
+Use contextual checkpoint deltas only as auxiliary recovery notes.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Do not stop at tasks.md.
 Continue into implementation and verification.

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

@@ -75,6 +75,7 @@ Da Vinci 期望它们遵循工作流状态。
 
 - 当前 workflow state
 - 缺失或薄弱工件
+- 与当前工件一致时可引用最近 checkpoint 的 Context Delta 作为恢复补充
 - 一条主 continuation prompt
 - 必要时的保守 continuation prompt
 
@@ -82,6 +83,9 @@ Da Vinci 期望它们遵循工作流状态。
 
 - 如果设计已经有了，但 `tasks.md` 还没有，`continue` 通常应该把你送到 `tasks`
 - 这时候不应该把 `build` 当成同级主推荐
+- 选路必须先基于工件和 checkpoint 真相，再参考 Context Delta
+- 如果 Context Delta 与当前工件冲突，选路时应忽略冲突条目并记录冲突
+- 当设计门禁还未收敛时，不应路由到 `build`：包括缺少 shell 可见的项目本地 `.pen`、Pencil session 仍为 active/unclosed、runtime 或 design-source checkpoint 仍是 `BLOCK`、或必需的 design-supervisor review 仍是 `BLOCK`/未接受
 
 ### `/dv:breakdown`
 
@@ -151,6 +155,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`
 
 适合：

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

@@ -76,6 +76,8 @@ project/
 
 - `intake` 和 `continue` 一般应该回到主工作流入口
 - 不应默认导向 `build`，除非实现就绪已经非常明确
+- `continue` 选路应先看工件/checkpoint 真相，再把 Context Delta 当作辅助恢复信息
+- 如果 Context Delta 与当前工件冲突，选路时应忽略冲突条目并记录冲突
 
 ## 1. `greenfield-spec`