@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

package/docs/prompt-presets/mobile-app.md

@@ -126,7 +126,7 @@ Use only Pencil-supported properties; do not use web-only props like flex or mar
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Run `da-vinci audit --mode integrity <project-path>` after that first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
@@ -164,7 +164,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -199,7 +199,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, keep the anchor-first flow until the design checkpoint passes.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.

package/docs/prompt-presets/tablet-app.md

@@ -120,7 +120,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Run `da-vinci audit --mode integrity <project-path>` after the first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
 If `DA-VINCI.md` configures `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, using screenshots plus Pencil variables and the design theses as inputs. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
@@ -156,7 +156,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -191,7 +191,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.

package/docs/prompt-presets/web-app.md

@@ -121,7 +121,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Run `da-vinci audit --mode integrity <project-path>` after the first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
 If `DA-VINCI.md` configures `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, using screenshots plus Pencil variables and the design theses as inputs. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
@@ -157,7 +157,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -192,7 +192,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.

package/docs/skill-usage.md

@@ -85,6 +85,12 @@ When design is mostly ready and implementation is next, use these checks:
   - use this when runtime spec quality is still uncertain
 - `da-vinci scope-check`
   - use this when page/state propagation across planning artifacts looks ambiguous
+- `da-vinci lint-tasks`
+  - confirm task groups have discipline markers, exact ownership targets, execution intent, and verification commands
+- `da-vinci lint-bindings`
+  - run this when `pencil-design.md` and `pencil-bindings.md` both exist so implementation landing evidence stays parseable
+- `da-vinci worktree-preflight`
+  - run this before bounded-parallel execution to decide whether local worktree isolation is recommended
 
 If you are already inside the project root directory, `--project` is optional because the CLI falls back to `cwd`.
 
@@ -95,8 +101,17 @@ da-vinci workflow-status
 da-vinci next-step
 da-vinci lint-spec
 da-vinci scope-check
+da-vinci lint-tasks
 ```
 
+During implementation, persist machine-readable task evidence instead of relying on chat-only summaries:
+
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> ...`
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage spec ...`
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage quality ...`
+
+`quality` review is valid only after `spec` review has a `PASS` record for the same task group.
+
 ## After Pausing Midway
 
 The safest resume order is:
@@ -107,6 +122,7 @@ The safest resume order is:
 4. if planning propagation is unclear, run `da-vinci scope-check`
 5. if planning artifacts changed since the last stable snapshot, run `da-vinci generate-sidecars` and `da-vinci diff-spec`
 6. before terminal completion, run `da-vinci verify-bindings` and `da-vinci verify-coverage`
+7. if completion wording is needed, confirm `verify-coverage` freshness is current and run `da-vinci audit --mode completion --change <id> <project-path>`
 
 Resume should follow the artifacts, not old conversation state:
 
@@ -146,67 +162,74 @@ npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
 
 The TUI provides:
 
-- command grouping by workflow phase
-- English and Chinese UI descriptions
-- current project path and change-id context at the top
-- preview commands before execution
-- one-key toggles for `--strict`, `--json`, and `--continue-on-error`
-- placeholder-aware editing for commands that still need specific paths like `<pen-path>`
+- a scene-first landing screen with `Install & Uninstall`, `Current Status`, `Switch Work Item`, `Design Ops`, `Pre-Implementation Checks`, `Pre-Acceptance Checks`, and `Settings`
+- guided compound flows for resume, implementation readiness, and completion validation
+- `Design Ops` focuses on practical design operations (`Save Current Design`, `Sync Icon Library`, and `Visual Assist Preset`)
+- `Install & Uninstall` provides three actions: `Status` (show `da-vinci status`), `Install` (install all supported platforms), and `Uninstall` (uninstall all supported platforms)
+- English and Chinese chrome while keeping emitted Visual Assist content in canonical English
+- project/change context in the header with minimal persistent chrome
+- `Settings` keeps only `Language` and `Logs`
+- project-local daily diagnostics under `Settings > Logs` (`.da-vinci/logs/YYYY-MM-DD.ndjson`)
 
-### TUI Phase Map
+### TUI Scene Map
 
 ```mermaid
 flowchart TD
-  A[Launch da-vinci tui] --> B[Set project path and change-id context]
-  B --> C[Routing & Resume<br/>workflow-status / next-step]
-  C --> D{Which phase is active?}
-
-  D --> E[Planning & Drift<br/>lint-spec / scope-check / lint-tasks / lint-bindings / generate-sidecars / diff-spec / scaffold]
-  D --> F[Visual & Review<br/>icon-sync / icon-search / supervisor-review]
-  D --> G[Pen Files & Sync<br/>preflight-pencil / ensure-pen / write-pen / check-pen-sync / check-pen-baseline / sync-pen-source / snapshot-pen]
-  D --> H[Pencil Session<br/>pencil-lock * / pencil-session begin|persist|end|status]
-  D --> I[Verification & Completion<br/>verify-bindings / verify-implementation / verify-structure / verify-coverage / audit]
-  D --> J[Setup & Tooling<br/>install / uninstall / status / validate-assets / bootstrap-project]
-
-  E --> I
-  F --> G
-  G --> H
-  H --> E
-  I --> K{Ready to finish?}
-  K -->|No| C
-  K -->|Yes| L[Completion audit and terminal claim]
+  A[Launch da-vinci tui] --> B[Set project path and change context]
+  B --> C[Install & Uninstall<br/>status + install-all + uninstall-all]
+  B --> D[Current Status<br/>workflow-status + next-step summary]
+  B --> E[Switch Work Item<br/>pick an existing change]
+  B --> F[Design Ops<br/>icon sync + visual assist preset]
+  B --> G[Pre-Implementation Checks<br/>implementation readiness gate]
+  B --> H[Pre-Acceptance Checks<br/>verify-* chain]
+  B --> I[Settings<br/>language + logs]
 ```
 
 Use this as the quick mental model:
 
-- start from `Routing & Resume`
-- move into the phase that matches the current blockers
-- return to `Routing & Resume` whenever the workflow pauses or artifacts changed materially
-- only finish after the verification lane and completion audit are both clear
+- start from the scene that matches the current operator moment
+- let the scene entrypoints orchestrate the common checks first
+- use `Current Status` when a workflow pauses or the next route is unclear
+- finish only after `Pre-Acceptance Checks` is clear
+
+Visual Assist Preset mapping (`Design Ops > Visual Assist Preset`):
+
+- `Masterpiece` => `required reviewer signoff`
+- `High Quality` => `advisory reviewer`
+- `Normal` => `adapter-only`
+
+Managed Visual Assist behavior:
+
+- select platform first, then select one of 3 quality levels
+- write canonical English output from `docs/visual-assist-presets/`
+- replace only `## Visual Assist` in project-root `DA-VINCI.md`
+- preserve unrelated sections and avoid duplicate `## Visual Assist` blocks
 
 Main keys:
 
 - `Up/Down` or `j/k`: move selection
-- `Enter` or `r`: run the selected command
-- `h`: inspect parameters for the selected command
-- `m`: edit the preview command first
+- `Enter` or `r`: open selected scene / action
+- `u/d`: page up / page down in long content views
+- `g/G`: jump to top / bottom in long content views
 - `p`: change project path context
 - `c`: change or clear change-id context
 - `l`: toggle English / Chinese
+- `t`: cycle between theme modes when auto-detection is wrong
 - `s`: toggle `--strict`
 - `J`: toggle `--json`
 - `e`: toggle `--continue-on-error`
 - `?`: open help
-- `q`: quit
+- `Ctrl-C`: emergency exit
 
 Recommended TUI usage:
 
 1. launch the TUI from the project root
-2. set or confirm project path and change-id in the header
-3. start with `workflow-status`
-4. run `next-step`
-5. move into `lint-spec` / `scope-check` / `tasks` / `verify-*` as needed
-6. for specialized Pencil commands, press `m` and fill the remaining placeholders before execution
+2. pick the workflow scene that matches your current moment
+3. set or confirm project path and change-id in the header
+4. use the scene entrypoints first (`Switch Work Item`, `Pre-Implementation Checks`, `Install & Uninstall`, `Pre-Acceptance Checks`) and use `Current Status` as the direct re-entry summary
+5. use `Design Ops > Visual Assist Preset` to select platform + quality and write managed `Visual Assist` blocks
+6. use `Install & Uninstall > Status` to inspect installation state, or run `Install`/`Uninstall` for all supported platforms in one step
+7. inspect/copy diagnostics from `Settings > Logs` when troubleshooting; keep logs as evidence only, not routing truth
 
 ## Practical Shortcuts
 

package/docs/workflow-examples.md

@@ -99,17 +99,19 @@ Expected flow:
 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. when external or secondary `.pen` sources exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before the new session write phase; if diverged, sync the chosen source into `<project-pen>` first
-14. 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 ...`
-15. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
-16. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
-17. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
-18. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-19. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
-20. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
-21. bind routes and pages to Pencil screens
-22. generate tasks aligned to the redesign slices
-23. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
-24. build and verify only after the completion gate can eventually pass
+14. during live design work, use `da-vinci save-current-design --project <project-path>` after material edits, then end with `da-vinci pencil-session end ...`
+15. treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only `saved` means the design source was persisted
+16. if save returns `unavailable`, do not claim success; use the lower-level `pencil-session persist --nodes-file/--variables-file` path only when the high-level bridge is unavailable
+17. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+18. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
+19. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
+20. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+21. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
+22. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
+23. bind routes and pages to Pencil screens
+24. generate tasks aligned to the redesign slices
+25. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+26. build and verify only after the completion gate can eventually pass
 
 ### Complex Android example
 
@@ -134,7 +136,8 @@ If the same anchor surface rolls back twice, switch to micro-batches of 6 or few
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
 When external or secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` first; if hashes diverge, sync the preferred source into `<project-pen>` before editing.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `da-vinci pencil-session persist`.
+If a registered project-local `.pen` already exists, reopen it for continuity and save through `da-vinci save-current-design --project <project-path>`.
+Treat `saved`, `blocked`, and `unavailable` as distinct outcomes. If `unavailable`, do not claim success and only then fall back to the lower-level `pencil-session persist` payload path.
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Run `da-vinci audit --mode integrity <project-path>` after that first successful Pencil write before broad expansion continues.
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
@@ -201,7 +204,7 @@ If frontend-skill is available, use it as the primary visual adapter.
 If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
 If no registered project-local `.pen` exists yet, seed it there before the first Pencil edit and keep subsequent live edits bound to that exact path.
-If a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+If a registered project-local `.pen` already exists, reopen it for continuity and persist after material live edits through `da-vinci save-current-design --project <project-path>`.
 ```
 
 ## Icon-library helper example

package/docs/workflow-overview.md

@@ -30,6 +30,12 @@ This means:
 - project-local `.pen` files remain the design source of truth
 - implementation must stay traceable to both
 
+Truth-versus-orchestration boundary:
+
+- route and completion truth comes from artifacts, checkpoints, execution signals, and `audit`
+- orchestration hints such as execution profiles and worktree preflight remain advisory guidance
+- orchestration hints must never override explicit `BLOCK` truth from artifacts, checkpoints, or completion audit
+
 ## Main Flow
 
 1. Choose the correct mode.
@@ -60,6 +66,12 @@ Use these command surfaces to inspect route readiness before selecting the next
   - explicitly generates deterministic planning sidecars used by diff and downstream tooling
 - `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
   - validates execution-chain evidence from bindings through implementation and structural coverage
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> ...`
+  - persists normalized implementer evidence per task group so pause/resume routing can read unresolved blockers and concerns
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> ...`
+  - persists ordered two-stage review evidence (`spec` before `quality`) and can append review records into `verification.md`
+- `da-vinci worktree-preflight --project <path> [--change <id>] [--json]`
+  - runs advisory worktree isolation checks before bounded-parallel execution
 - `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
   - reports normalized planning deltas for spec/tasks/page-map/bindings sidecars to support safe continuation
 
@@ -157,6 +169,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 save-current-design --project <project-path>` after material live edits (high-level bound-source save path)
 - `da-vinci audit --mode integrity <project-path>` during active work
 - checkpoint-adjacent `Context Delta` notes in existing change artifacts
 
@@ -166,6 +179,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
+- high-level save outcomes are handled honestly (`saved` / `blocked` / `unavailable`)
 - recent execution context is recoverable without replacing artifact truth as the routing authority
 
 ### 6. Mapping
@@ -183,7 +197,11 @@ These checks verify that:
 After mapping passes:
 
 - generate `tasks.md`
+- keep task groups parseable with discipline markers plus explicit file targets, execution intent, review intent, and verification commands
 - implement from requirements plus Pencil data
+- inspect `executionProfile` from `workflow-status` or `next-step --json` before broad implementation
+- if bounded parallelism is suggested, run `da-vinci worktree-preflight --project <path> [--change <id>]` and downgrade to serial when isolation is not ready
+- persist per-task implementer and review evidence via `task-execution` and ordered `task-review` records
 - verify requirement drift and design drift
 
 ### 8. Terminal Completion
@@ -193,6 +211,7 @@ The workflow must not report `design complete`, `workflow complete`, or any equi
 - design checkpoint is no longer blocking
 - design-source checkpoint is at least `PASS`
 - MCP runtime gate is acceptable when Pencil MCP was used
+- fresh verification evidence is present for in-scope implementation and coverage claims
 - `da-vinci audit --mode completion --change <change-id> <project-path>` passes
 
 Notes:

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

@@ -45,10 +45,11 @@ Da Vinci 期望它们遵循工作流状态。
   - 当真正难记的是命令面而不是流程本身时，优先用它
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - 从工件和 checkpoint 真相推导当前 workflow 阶段
-  - 报告 blocker、warning、handoff gate 状态，以及主推荐路由
+  - 报告 blocker、warning、handoff gate、discipline marker、execution profile 提示与 verification freshness
   - 它和 `audit` 职责不同：它负责选路，不是终态审计真相
 - `da-vinci next-step --project <path> [--change <id>] [--json]`
   - 基于同一套 workflow-state 推导，给出 route-first 的续跑建议
+  - JSON 输出包含 `nextStep`、`executionProfile`、`worktreePreflight` 与 discipline/freshness 元数据
   - 在自由扫描工件之前，优先把它作为第一路由信号
 - `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
   - 校验 Da Vinci 运行时 `spec.md` 的核心章节（`Behavior`、`States`、`Inputs`、`Outputs`、`Acceptance`、`Edge Cases`）
@@ -59,7 +60,7 @@ Da Vinci 期望它们遵循工作流状态。
   - 输出页面与状态两条线的机器可读覆盖矩阵
   - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
 - `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
-  - 校验顶层 task groups、编号顺序、verification 动作和 behavior 覆盖提示
+  - 校验顶层 task groups、编号顺序、discipline markers、执行模式提示、文件目标、verification 命令与 behavior 覆盖提示
   - 默认 advisory（有发现给 `WARN` 且不阻断）；显式 `--strict` 才升级为阻断
 - `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
   - 校验实现到 Pencil 的映射是否可解析、source 形态是否合理、实现落点是否可定位
@@ -70,6 +71,12 @@ Da Vinci 期望它们遵循工作流状态。
 - `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
   - 校验代码落点、计划状态实现证据、以及绑定驱动的结构一致性
   - `verify-structure` 会明确报告是 markup-backed 还是 heuristic fallback，并给出置信度
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]`
+  - 持久化结构化 implementer 执行结果包，作为 task 级执行证据
+- `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]`
+  - 持久化有序两阶段 task review 证据（`spec` 在前，`quality` 在后）
+- `da-vinci worktree-preflight --project <path> [--change <id>] [--json]`
+  - 运行 advisory worktree 隔离预检（目录 ignore 安全、工作区脏状态、baseline 检查启发）
 - `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
   - 比较规范化 planning sidecars，报告新增/删除/修改的规划项
   - 在同一 surface 下提供 spec 差异以及 tasks/page-map/bindings 摘要差异
@@ -101,6 +108,11 @@ Da Vinci 期望它们遵循工作流状态。
 - `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
   - 把被选中的最新 `.pen` 来源同步到项目内 `.pen` 路径，并刷新 Da Vinci state 元数据
   - 当外部备份是最新基线时，在 `pencil-session begin` 前先执行
+- `da-vinci save-current-design --project <path> [--json] [--continue-on-error]`
+  - 运行高层绑定源保存流程，作为 guided 设计持久化主路径
+  - 持久化前必须确认 registered `.pen`、session `penPath`、active editor path 收敛到同一来源
+  - 统一返回 `saved` / `blocked` / `unavailable`
+  - `blocked` 表示保存契约失败（来源/锁/载荷）；`unavailable` 表示 MCP bridge 或 runtime 抓取不可达
 
 建议在 `/dv:design` 阶段使用，尤其是在 anchor surface 的图标定稿前。
 
@@ -174,6 +186,14 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层负责塑造行为真相。
 
+需求拆解阶段自检：
+
+- 在把 requirements 交给设计前，先跑 `da-vinci workflow-status --project <path> [--change <id>] --json`
+- 再跑 `da-vinci next-step --project <path> [--change <id>]`
+- 跑 `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- 把命令结果当成门禁，不要把 `BLOCK` 或非零退出码解释成软建议
+- 如果主推荐路由仍然是 `/dv:breakdown`，就继续修 `proposal.md` 和 specs，不要硬推进到 `/dv:design`
+
 ### `/dv:design`
 
 适合：
@@ -210,6 +230,14 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层只做实现拆解，不写代码。
 
+任务阶段自检：
+
+- 在把工作移交给实现前，先跑 `task checkpoint`
+- 有 shell 能力时，跑 `da-vinci lint-tasks --project <path> [--change <id>]`
+- 如果 `pencil-design.md` 和 `pencil-bindings.md` 都存在，再跑 `da-vinci lint-bindings --project <path> [--change <id>]`
+- 把命令结果当成门禁，不要把 `BLOCK` 或非零退出码降级成软提示
+- 只要任务覆盖或 bindings 就绪度仍然阻塞，就不要推进到 `/dv:build`
+
 ### `/dv:build`
 
 适合：
@@ -225,10 +253,27 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层才是真正的执行阶段。
 
+实现阶段自检：
+
+- 在大范围实现前，先跑 `da-vinci workflow-status --project <path> [--change <id>] --json`
+- 再跑 `da-vinci next-step --project <path> [--change <id>]`
+- 如果主推荐路由不是 `/dv:build`，就停止并回到那个路由，而不是硬做实现
+- 跑 `da-vinci lint-spec --project <path> [--change <id>]`
+- 跑 `da-vinci scope-check --project <path> [--change <id>]`
+- 如果 `tasks.md` 已存在，跑 `da-vinci lint-tasks --project <path> [--change <id>]`
+- 如果 `pencil-design.md` 和 `pencil-bindings.md` 都存在，跑 `da-vinci lint-bindings --project <path> [--change <id>]`
+- 查看 `da-vinci next-step --project <path> [--change <id>] --json` 的 `executionProfile`
+- 若 profile 为 `bounded_parallel`，先跑 `da-vinci worktree-preflight --project <path> [--change <id>]`；隔离未就绪则降级串行
+- 用 `da-vinci task-execution ...` 持久化每个 task group 的 implementer 结果包，确保 concern/blocker 可追踪
+- 按顺序执行 task review：先 `da-vinci task-review ... --stage spec ...`，再 `da-vinci task-review ... --stage quality ...`
+- 把命令结果当成门禁，不要把 `BLOCK` 或非零退出码降级成软提示
+- 只要还有 `BLOCK` 或缺少必要 planning/design 工件，就不要进入大范围实现
+
 完成判定规则：
 
 - `BUILD SUCCESSFUL` 只代表可编译，不代表 workflow 完成
 - 只要 in-scope task groups 还没做完，就不能宣告 `design complete` 或 `workflow complete`
+- 终态 completion 表述前必须具备 fresh verification evidence
 - 任何终态声明前都要运行 `da-vinci audit --mode completion --change <change-id> <project-path>` 并通过
 
 ### `/dv:verify`
@@ -245,6 +290,18 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层是 truth reconciliation 阶段。
 
+验证阶段自检：
+
+- 有 shell 能力时，跑 `da-vinci verify-bindings --project <path> [--change <id>]`
+- 跑 `da-vinci verify-implementation --project <path> [--change <id>]`
+- 跑 `da-vinci verify-structure --project <path> [--change <id>]`
+- 跑 `da-vinci verify-coverage --project <path> [--change <id>]`
+- 把命令结果当成门禁，不要把 `BLOCK` 或 `FAIL` 降级成软提示
+- 只要任何验证面仍然是 `BLOCK` 或 `FAIL`，就继续停留在验证阶段并记录 drift，而不是宣称成功
+- 终态表述前要求 `verify-coverage` 和 `workflow-status` 中的验证证据 freshness 为最新
+- 如果启用了 task-review 证据，存在未解决 `WARN/BLOCK` 评审阶段时不得关闭对应 task group
+- 如果要声称终态完成，先要求 `da-vinci audit --mode completion --change <change-id> <project-path>` 通过
+
 ## 基于状态的下一步规则
 
 这就是当前应该给用户的推荐逻辑。

package/docs/zh-CN/execution-chain-migration.md

@@ -44,3 +44,26 @@ Audit 集成：
 - MVP 不做多框架扩展
 - scaffold 边界来自 `pencil-bindings.md` 映射
 - 接受前需跑 `verify-bindings`、`verify-implementation`、`verify-structure`
+
+## 5. 下一阶段规划升级：Discipline And Orchestration
+
+execution-chain 能力落地后，下一项规划中的升级是：
+
+- `openspec/changes/discipline-and-orchestration-upgrade/`
+
+该规划变更会补充：
+
+- 实施前交接纪律的强化
+- `tasks.md` 执行就绪质量检查强化
+- 与 workflow state 绑定的有边界编排提示
+- 结构化 task 执行与审查证据
+- 基于 fresh verification evidence 的 completion 表述约束
+- 可选 worktree preflight 隔离建议
+
+重要边界：
+
+- 该升级不会替代 artifact truth、checkpoint truth 或 completion-audit 权威
+
+参考：
+
+- `docs/discipline-and-orchestration-upgrade.md`

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

@@ -239,7 +239,8 @@ Da Vinci 应该：
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
    - 必须通过 `da-vinci pencil-session begin` 开始这轮设计，让登记路径先 seed 好并拿到锁
-   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`
+   - 必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 的底层链路
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现

package/docs/zh-CN/pencil-rendering-workflow.md

@@ -31,7 +31,7 @@ PNG 只是审查产物，不是设计真相源。
 Da Vinci 现在要求自治运行使用这组 session wrapper：
 
 - `da-vinci pencil-session begin`
-- `da-vinci pencil-session persist`
+- `da-vinci save-current-design`
 - `da-vinci pencil-session end`
 
 这组 wrapper 的作用，是把下面三件事变成强制步骤：
@@ -77,18 +77,21 @@ Da Vinci 不会假设 live MCP 编辑已经被自动刷盘。
 
 Da Vinci 不把 headless interactive `save()` 当作权威持久化真相。
 
-正式持久化步骤是：
+主路径持久化步骤是：
 
-1. 读取 MCP 可读的 node snapshot
-2. 读取 MCP 可读的 variable snapshot
-3. 写项目内 `.pen`
-4. reopen 校验
-5. 比较 live snapshot hash 和 persisted snapshot hash
+1. 执行 `da-vinci save-current-design --project <project-path>`
+2. 明确读取结果包：`saved` / `blocked` / `unavailable`
+3. 只有 `saved` 才表示持久化成功
+4. `blocked` 表示保存时的来源/锁/载荷契约失败
+5. `unavailable` 表示 MCP bridge 或 runtime 抓取不可达，不能当成“已保存”
 
 相关命令：
 
-- `da-vinci write-pen`
-- `da-vinci check-pen-sync`
+- 高层主路径：`da-vinci save-current-design`
+- 底层回退路径：`da-vinci pencil-session persist`、`da-vinci write-pen`、`da-vinci check-pen-sync`
+
+MVP 安全保证仅覆盖“来源路径收敛”：registered `.pen`、session `penPath`、active editor path 必须收敛到同一文件。
+在 MCP 暴露稳定 window/editor 标识前，精确窗口实例绑定仍是非目标。
 
 `da-vinci snapshot-pen` 只用于 disk-to-disk，不是 live 编辑持久化路径。
 
@@ -253,7 +256,7 @@ Context Delta 相关审计期望都是告警级：
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
 2. 如果存在外部/次要 `.pen`，在编辑前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若分叉，先把优先来源同步回 `<project-pen>`
 3. Pencil MCP 编辑
-4. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+4. `da-vinci save-current-design --project <project-path>`
 5. screenshot review + layout hygiene
 6. design checkpoint
 7. 如果配置了，就执行 design-supervisor review
@@ -280,13 +283,13 @@ flowchart TD
     K -- 否 --> F
     K -- 是 --> L{是否配置了 design-supervisor review?}
     L -- 是 --> M[执行 design-supervisor review，结合 screenshots 与 theme inputs]
-    L -- 否 --> N[pencil-session persist 把 live MCP 快照写回 .pen]
+    L -- 否 --> N[save-current-design 把绑定的 live 快照写回 .pen]
     M --> O{是否要求 Supervisor Review?}
     O -- 否 --> N
     O -- 是 --> P{review 为 PASS 或已接受 WARN?}
     P -- 否 --> F
     P -- 是 --> N
-    N --> Q[check-pen-sync 校验 live hash 与 persisted hash 一致]
+    N --> Q[save-current-design 返回 saved 或终态 blocked/unavailable]
     Q --> R{design-source checkpoint 和 runtime gate 通过?}
     R -- 否 --> F
     R -- 是 --> S{是否还要继续设计?}