@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

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

@@ -14,3 +14,17 @@ Tasks must cover:
 - spec-backed behavior
 - Pencil-backed UI work
 - verification work
+
+Task-plan discipline:
+- each top-level task group should include exact file or code-area ownership targets
+- include explicit verification commands, not only abstract verification wording
+- include execution intent hints (`serial`, `bounded_parallel`, or `review_required`) and review intent
+- include parseable discipline markers for design approval, plan self-review, and operator review acknowledgment
+
+Before claiming implementation-ready task planning:
+- re-check that the workflow is still in the `/dv:tasks` lane when route context is stale or unclear
+- run the `task checkpoint`
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not hand off to `build` while task coverage or bindings readiness are still blocking

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

@@ -13,4 +13,14 @@ Check:
 - drift between artifacts and code
 
 Update `verification.md` when needed.
+When shell access is available:
+- run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
+- require fresh verification evidence in `verify-coverage` and `workflow-status` before any terminal completion wording
+- if task-review evidence is recorded, keep unresolved `WARN/BLOCK` task-review stages open instead of closing the task group
 If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.
+Before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.

package/commands/gemini/dv/breakdown.toml

@@ -6,6 +6,14 @@ Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 
+Before handing requirements off to design when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- run `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- treat command output as the gate; do not replace `BLOCK` or non-zero results with narrative judgment
+- if the primary recommended route is still `/dv:breakdown`, keep refining `proposal.md` and specs instead of forcing design
+- do not move to `/dv:design` until the command-backed checks stop blocking
+
 Focus on:
 - scope
 - pages

package/commands/gemini/dv/build.toml

@@ -6,12 +6,28 @@ Use the Da Vinci workflow for this request.
 
 Action: `build`
 
+Before broad implementation when shell access is available:
+- run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- if the primary recommended route is not `/dv:build`, stop and continue from that route instead of forcing implementation
+- run `da-vinci lint-spec --project <path> [--change <id>]`
+- run `da-vinci scope-check --project <path> [--change <id>]`
+- if `tasks.md` exists, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- inspect `executionProfile` and discipline blockers from `da-vinci next-step --project <path> [--change <id>] --json`
+- if profile mode is `bounded_parallel`, run `da-vinci worktree-preflight --project <path> [--change <id>]` and downgrade to serial unless isolation is ready or explicitly accepted
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- treat any `BLOCK` or missing required planning/design artifact as a hard stop before broad implementation
+
 Implementation rules:
 - requirements decide behavior
 - Pencil decides presentation
 - run `execution checkpoint` after each top-level task group
+- persist per-task implementer evidence via `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <...> --summary <...>`
+- persist ordered review evidence via `da-vinci task-review --project <path> --change <id> --task-group <id> --stage spec ...` then `--stage quality ...`
 - treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
 - do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- do not use terminal completion wording without fresh verification evidence
 - before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
 - if completion audit fails, continue from the minimal unfinished stage instead of exiting
 """

package/commands/gemini/dv/continue.toml

@@ -22,15 +22,19 @@ Route discipline:
 - treat this route as prompt-first orchestration; do not assume a standalone CLI `continue` command exists
 - when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before deciding the primary continuation route
 - use `da-vinci next-step --project <path> [--change <id>]` as the first routing signal
+- prefer `da-vinci next-step --project <path> [--change <id>] --json` when available so discipline markers, execution profile hints, and verification freshness are explicit
 - run `da-vinci scope-check --project <path> [--change <id>]` when page/state propagation looks ambiguous
 - do not restart discovery if the current artifacts already contain enough truth
 - determine route selection from artifact and checkpoint truth before reading contextual deltas
 - if workflow-status or next-step output is missing, stale, or unavailable, fall back to artifact scanning and checkpoint evidence
 - use contextual deltas as auxiliary recovery context only; they must not override route selection
 - if contextual deltas conflict with current artifacts, ignore them for routing and call out the conflict
+- if design approval discipline markers are missing, malformed, or stale, keep routing in design/task refinement rather than promoting directly into implementation
 - do not default the user into `/dv:build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
 - only prefer `/dv:build` once task generation and implementation readiness are already clear
 - do not route into `/dv:build` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
+- if bounded-parallel execution is hinted, include `da-vinci worktree-preflight --project <path> [--change <id>]` before emitting a parallel implementation continuation prompt
+- avoid terminal completion wording unless fresh verification evidence and completion audit requirements are explicit
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine
 """

package/commands/gemini/dv/design.toml

@@ -13,10 +13,13 @@ Create or update:
 Use Pencil-backed page coverage as the source of presentation truth.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Require the session wrapper commands on autonomous runs: `da-vinci pencil-session begin`, `da-vinci save-current-design`, and `da-vinci pencil-session end`.
 Before the first Pencil edit, require `da-vinci pencil-session begin` so the registered project-local `.pen` is seeded and locked before editing starts.
 When multiple `.pen` sources exist (for example an external backup), run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before `pencil-session begin`. If hashes diverge, confirm source priority explicitly and sync the chosen source into the project-local `.pen` (for example `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`) before continuing edits.
-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 `pencil-session persist` after material edits.
+If a registered project-local `.pen` already exists, reopen it for continuity and use `da-vinci save-current-design --project <project-path>` after material edits.
+Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; never treat `unavailable` as a successful save.
+Use the lower-level `pencil-session persist` payload path only when the high-level save bridge is unavailable.
+The MVP guarantee is bound source-path safety (`registered .pen`, session `penPath`, and active editor path converge), not exact window-instance identity before MCP exposes stable window/editor identifiers.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/commands/gemini/dv/tasks.toml

@@ -10,4 +10,18 @@ Create or update:
 - `tasks.md`
 
 Tasks must cover spec behavior, Pencil-backed UI work, and verification.
+
+Task-plan discipline:
+- include exact file or code-area ownership targets per task group
+- include explicit verification commands, not only abstract verification wording
+- include execution intent hints (`serial`, `bounded_parallel`, or `review_required`) and review intent
+- include parseable discipline markers for design approval, plan self-review, and operator review acknowledgment
+
+Before claiming implementation-ready task planning:
+- re-check that the workflow is still in the `/dv:tasks` lane when route context is stale or unclear
+- run the `task checkpoint`
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not hand off to `build` while task coverage or bindings readiness are still blocking
 """

package/commands/gemini/dv/verify.toml

@@ -12,5 +12,15 @@ Check:
 - drift between artifacts and code
 
 Update `verification.md` when needed.
+When shell access is available:
+- run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
+- require fresh verification evidence in `verify-coverage` and `workflow-status` before any terminal completion wording
+- if task-review evidence is recorded, keep unresolved `WARN/BLOCK` task-review stages open instead of closing the task group
 If Pencil MCP is active and terminal completion is being considered, re-check the MCP runtime gate evidence before treating verification as complete.
+Before any terminal completion claim, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 """

package/commands/templates/dv-continue.shared.md

@@ -20,14 +20,18 @@ Route discipline:
 - treat this route as prompt-first orchestration; do not assume a standalone CLI `continue` command exists
 - when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before deciding the primary continuation route
 - use `da-vinci next-step --project <path> [--change <id>]` as the first routing signal
+- prefer `da-vinci next-step --project <path> [--change <id>] --json` when available so discipline markers, execution profile hints, and verification freshness are explicit
 - run `da-vinci scope-check --project <path> [--change <id>]` when page/state propagation looks ambiguous
 - do not restart discovery if the current artifacts already contain enough truth
 - determine route selection from artifact and checkpoint truth before reading contextual deltas
 - if workflow-status or next-step output is missing, stale, or unavailable, fall back to artifact scanning and checkpoint evidence
 - use contextual deltas as auxiliary recovery context only; they must not override route selection
 - if contextual deltas conflict with current artifacts, ignore them for routing and call out the conflict
+- if design approval discipline markers are missing, malformed, or stale, keep routing in design/task refinement rather than promoting directly into implementation
 - do not default the user into `{{BUILD_ROUTE}}` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `{{TASKS_ROUTE}}`
 - only prefer `{{BUILD_ROUTE}}` once task generation and implementation readiness are already clear
 - do not route into `{{BUILD_ROUTE}}` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
+- if bounded-parallel execution is hinted, include `da-vinci worktree-preflight --project <path> [--change <id>]` before emitting a parallel implementation continuation prompt
+- avoid terminal completion wording unless fresh verification evidence and completion audit requirements are explicit
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

package/docs/discipline-and-orchestration-upgrade.md

@@ -0,0 +1,83 @@
+# Discipline And Orchestration Upgrade
+
+This document explains the implemented `discipline-and-orchestration-upgrade` change and how to use its artifacts.
+
+Status:
+
+- completed (runtime surfaces and docs rolled out)
+- tracking path: `openspec/changes/discipline-and-orchestration-upgrade/`
+
+## Purpose
+
+This upgrade imports bounded ideas from external projects while preserving Da Vinci's core truth model.
+
+Primary intent:
+
+- improve execution discipline from `design` to `tasks` to `build` to `verify`
+- improve task-plan quality and implementation review structure
+- expose orchestration hints without allowing orchestration to override workflow truth
+
+Core boundary:
+
+- artifacts, checkpoints, execution signals, and `audit` remain workflow truth
+- orchestration remains advisory or explicitly bounded
+
+## External Inspiration (Source-Tracked)
+
+- `obra/superpowers`:
+  - design-first discipline
+  - plan-quality discipline
+  - two-stage implementation review
+  - verification-before-completion wording discipline
+  - optional worktree isolation practice
+- `ruvnet/ruflo`:
+  - bounded orchestration profiles
+  - anti-drift execution patterns
+  - role and concurrency guidance
+
+See exact source files in:
+
+- `openspec/changes/discipline-and-orchestration-upgrade/README.md`
+
+## OpenSpec Structure
+
+Use these files in order:
+
+1. `openspec/changes/discipline-and-orchestration-upgrade/proposal.md`
+2. `openspec/changes/discipline-and-orchestration-upgrade/design.md`
+3. `openspec/changes/discipline-and-orchestration-upgrade/specs/workflow-discipline/spec.md`
+4. `openspec/changes/discipline-and-orchestration-upgrade/specs/execution-orchestration/spec.md`
+5. `openspec/changes/discipline-and-orchestration-upgrade/specs/execution-evidence-and-isolation/spec.md`
+6. `openspec/changes/discipline-and-orchestration-upgrade/tasks.md`
+
+## Documentation Rollout Scope
+
+During implementation of this upgrade, keep the following docs aligned:
+
+- `README.md`
+- `README.zh-CN.md`
+- `docs/workflow-overview.md`
+- `docs/dv-command-reference.md`
+- `docs/skill-usage.md`
+- `docs/prompt-entrypoints.md`
+- `docs/zh-CN/workflow-overview.md`
+- `docs/zh-CN/dv-command-reference.md`
+- `docs/zh-CN/skill-usage.md`
+- `docs/zh-CN/prompt-entrypoints.md`
+
+Prompt and command assets that must stay aligned:
+
+- `commands/codex/**`
+- `commands/claude/**`
+- `commands/gemini/**`
+
+Maintainer rollout and source-trace checklist:
+
+- `openspec/changes/discipline-and-orchestration-upgrade/docs-update-plan.md`
+
+## Documentation Guardrails
+
+- Do not document planned behavior as already shipped behavior.
+- Keep advisory vs blocking semantics explicit in operator docs.
+- Keep completion-audit authority explicit; do not imply replacement by orchestration hints.
+- When English operator docs are updated, update existing `docs/zh-CN` mirrors in the same rollout.

package/docs/dv-command-reference.md

@@ -43,10 +43,11 @@ These commands do not replace route selection, but they support design execution
   - useful when the command surface is harder to remember than the workflow itself
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - derives the current workflow stage from artifact and checkpoint truth
-  - reports blockers, warnings, handoff-gate state, and one primary route recommendation
+  - reports blockers, warnings, handoff-gate state, discipline markers, execution profile hints, and verification-evidence freshness
   - keep this distinct from `audit`: route guidance is not completion truth
 - `da-vinci next-step --project <path> [--change <id>] [--json]`
   - provides a route-first continuation summary from the same derived workflow state
+  - JSON output includes `nextStep`, `executionProfile`, `worktreePreflight`, and discipline/freshness metadata for orchestration consumers
   - use this as the first continuation signal before free-form artifact scanning
 - `da-vinci lint-spec --project <path> [--change <id>] [--strict] [--json]`
   - validates Da Vinci runtime `spec.md` schema sections (`Behavior`, `States`, `Inputs`, `Outputs`, `Acceptance`, `Edge Cases`)
@@ -57,7 +58,7 @@ These commands do not replace route selection, but they support design execution
   - emits a machine-readable coverage matrix for pages and states
   - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
 - `da-vinci lint-tasks --project <path> [--change <id>] [--strict] [--json]`
-  - validates top-level task groups, ordering, verification actions, and behavior-to-task coverage hints
+  - validates top-level task groups, ordering, discipline markers, execution-mode hints, file targets, verification commands, and behavior-to-task coverage hints
   - default behavior is advisory (`WARN` with zero exit); `--strict` upgrades findings to blocking
 - `da-vinci lint-bindings --project <path> [--change <id>] [--strict] [--json]`
   - validates implementation-to-Pencil mappings for parseability, source shape, and implementation landings
@@ -68,6 +69,15 @@ These commands do not replace route selection, but they support design execution
 - `da-vinci verify-bindings|verify-implementation|verify-structure|verify-coverage --project <path> [--change <id>] [--strict] [--json]`
   - verifies code landings, planned-state implementation evidence, and structural consistency against bindings
   - `verify-structure` reports whether checks used markup-backed analysis or heuristic fallback and exposes confidence
+- `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]`
+  - persists normalized implementer-status envelopes into execution signals
+  - use this to keep resume routing machine-readable when implementation is blocked or concerns remain
+- `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]`
+  - persists ordered two-stage task review evidence (`spec` before `quality`)
+  - rejects out-of-order quality approval and can append evidence into `verification.md`
+- `da-vinci worktree-preflight --project <path> [--change <id>] [--json]`
+  - runs advisory worktree isolation checks (`.worktrees/` or `worktrees/` ignore safety, dirty workspace, baseline test heuristics)
+  - does not replace route truth; use it to decide whether bounded-parallel execution should downgrade to serial
 - `da-vinci diff-spec --project <path> [--change <id>] [--from <sidecars-dir>] [--json]`
   - compares normalized planning sidecars and reports added/removed/modified requirement planning items
   - includes normalized spec deltas plus broader planning summaries (tasks/page-map/bindings) under one surface
@@ -99,6 +109,11 @@ These commands do not replace route selection, but they support design execution
 - `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
   - copies the selected latest `.pen` source into the project-local `.pen` path and refreshes Da Vinci state metadata
   - use when external backup is the latest baseline and must be materialized before `pencil-session begin`
+- `da-vinci save-current-design --project <path> [--json] [--continue-on-error]`
+  - runs the high-level bound-source save flow for guided design persistence
+  - requires convergence of registered `.pen`, session `penPath`, and active editor path before persistence
+  - returns one explicit outcome envelope: `saved`, `blocked`, or `unavailable`
+  - `blocked` means save-time source/lock/payload contracts failed; `unavailable` means MCP bridge/runtime capture was not reachable
 
 Use these utilities during `/dv:design`, especially before anchor-surface icon finalization.
 
@@ -172,6 +187,14 @@ For `overhaul-from-code`, this stage may also create:
 
 This is the behavior-truth shaping stage.
 
+Breakdown-stage self-check:
+
+- before handing requirements off to design, run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- run `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- treat command output as the gate; do not replace `BLOCK` or non-zero results with narrative judgment
+- if the primary recommended route is still `/dv:breakdown`, keep refining `proposal.md` and specs instead of forcing `/dv:design`
+
 ### `/dv:design`
 
 Use when:
@@ -210,6 +233,14 @@ This is the implementation-planning stage.
 
 It does not write code.
 
+Task-stage self-check:
+
+- run the `task checkpoint` before handing work off to implementation
+- when shell access is available, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- do not promote `/dv:build` while task coverage or bindings readiness are still blocking
+
 ### `/dv:build`
 
 Use when:
@@ -225,6 +256,22 @@ Creates or updates:
 
 This is the execution stage.
 
+Build-stage self-check:
+
+- before broad implementation, run `da-vinci workflow-status --project <path> [--change <id>] --json`
+- run `da-vinci next-step --project <path> [--change <id>]`
+- if the primary recommended route is not `/dv:build`, stop and continue from that route instead of forcing implementation
+- run `da-vinci lint-spec --project <path> [--change <id>]`
+- run `da-vinci scope-check --project <path> [--change <id>]`
+- if `tasks.md` exists, run `da-vinci lint-tasks --project <path> [--change <id>]`
+- if both `pencil-design.md` and `pencil-bindings.md` exist, run `da-vinci lint-bindings --project <path> [--change <id>]`
+- inspect `executionProfile` from `da-vinci next-step --project <path> [--change <id>] --json`
+- if profile mode is `bounded_parallel`, run `da-vinci worktree-preflight --project <path> [--change <id>]` and downgrade to serial unless isolation is ready or explicitly accepted
+- persist per-task implementer outcomes via `da-vinci task-execution ...` and keep unresolved concerns visible before closure
+- run task review in order: `da-vinci task-review ... --stage spec ...` then `da-vinci task-review ... --stage quality ...`
+- treat command output as the gate; do not downgrade `BLOCK` or non-zero results into soft guidance
+- treat any `BLOCK` or missing required planning/design artifact as a hard stop before broad implementation
+
 Completion discipline:
 
 - treat `BUILD SUCCESSFUL` as compile-only evidence
@@ -245,6 +292,18 @@ Creates or updates:
 
 This is the truth-reconciliation stage.
 
+Verify-stage self-check:
+
+- when shell access is available, run `da-vinci verify-bindings --project <path> [--change <id>]`
+- run `da-vinci verify-implementation --project <path> [--change <id>]`
+- run `da-vinci verify-structure --project <path> [--change <id>]`
+- run `da-vinci verify-coverage --project <path> [--change <id>]`
+- treat command output as the gate; do not downgrade `BLOCK` or `FAIL` into soft guidance
+- if any verification surface is still `BLOCK` or `FAIL`, keep the workflow in verification and record the drift instead of claiming success
+- require fresh verification evidence in `verify-coverage` and `workflow-status` before terminal completion wording
+- if task-review evidence is being recorded, keep unresolved `WARN/BLOCK` review stages open instead of closing the task group
+- before terminal completion, require `da-vinci audit --mode completion --change <change-id> <project-path>` to pass
+
 ## State-Based Next-Step Rules
 
 These are the intended route recommendations.

package/docs/execution-chain-migration.md

@@ -44,3 +44,26 @@ If any check fails, Da Vinci falls back to derived state from artifacts and reco
 - no multi-framework expansion in the MVP
 - scaffold boundaries come from `pencil-bindings.md` mappings
 - verify scaffold output with `verify-bindings`, `verify-implementation`, and `verify-structure` before acceptance
+
+## 5. Planned Next Upgrade: Discipline And Orchestration
+
+After execution-chain surfaces are enabled, the next planned upgrade is:
+
+- `openspec/changes/discipline-and-orchestration-upgrade/`
+
+This planned change adds:
+
+- stronger handoff discipline before implementation
+- stronger task-plan quality checks
+- bounded orchestration hints tied to workflow state
+- structured task execution and review evidence
+- completion wording discipline backed by fresh verification evidence
+- optional worktree preflight guidance
+
+Important boundary:
+
+- this does not replace artifact truth, checkpoint truth, or completion-audit authority
+
+See:
+
+- `docs/discipline-and-orchestration-upgrade.md`

package/docs/execution-chain-plan.md

@@ -1,5 +1,9 @@
 # Execution-Chain Upgrade Plan Notes
 
+Historical planning note only.
+
+Use `openspec/changes/execution-chain-upgrade-plan/tasks.md` as the canonical executable task breakdown for this upgrade. This file records the background planning decisions that shaped that OpenSpec change; it is not the source of truth for implementation sequencing or release signoff.
+
 This document records planning decisions required by the execution-chain upgrade.
 
 ## Phase 0 Pre-work Decisions
@@ -24,6 +28,7 @@ The workflow contract must own:
 - route dependencies
 - stage handoff gates
 - status vocabulary (`PASS/WARN/BLOCK`)
+- audit-owned machine-parsed hard-gate fields from `DA-VINCI.md`, `.da-vinci/design-registry.md`, and `pencil-design.md`
 
 ### Compatibility boundaries
 
@@ -83,18 +88,18 @@ Re-baseline rule:
 ### Measurable DoD checks
 
 - Phase 0: inventory, parser ownership, schema boundaries, and test layers documented
-- Phase 1: workflow-status/next-step + prompt-first continue integration + contract tests green
+- Phase 1: workflow-status/next-step + prompt-first continue integration + design-source/runtime/mapping-aware routing + contract tests green
 - Phase 2: lint/scope + deterministic sidecars + advisory/strict semantics tested
 - Phase 3: verify surfaces + task-group metadata + audit wiring tested
 - Phase 4a: persisted state + diff + compatibility hardening tested
 - Phase 4b: constrained scaffold MVP tested
-- Phase 4c: command-asset convergence + docs + release controls tested
+- Phase 4c: command-asset convergence + docs + audit-aligned release controls tested
 
 ### First-release MVP scope
 
 In scope:
 
-- workflow-status/next-step
+- workflow-status/next-step with design-source/runtime/mapping-aware route guards
 - lint-spec/lint-tasks/lint-bindings/scope-check
 - generate-sidecars + diff-spec
 - verify-bindings/verify-implementation/verify-structure/verify-coverage
@@ -121,5 +126,7 @@ Out of scope:
 ### Release criteria and fallback
 
 - release requires core + contracts + e2e lanes green
+- completion or release-ready claims for shipped change scope must also pass `da-vinci audit --mode completion --change <change-id> <project-path>`
+- CI green is necessary but not sufficient when workflow truth or completion semantics disagree with audit
 - stale persisted state always falls back to derived state
 - verify-structure unsupported cases must emit heuristic fallback with confidence

package/docs/mode-use-cases.md

@@ -146,7 +146,8 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 8. create `pencil-design.md`
    - record the generated Pencil screens
    - require `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
-   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current live MCP snapshot through `da-vinci pencil-session persist` after material live edits
+   - if a registered project-local `.pen` already exists, reopen it for continuity, then run `da-vinci save-current-design --project <project-path>` after material live edits
+   - treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to low-level `pencil-session persist --nodes-file/--variables-file` when the high-level bridge is unavailable
    - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`

package/docs/pencil-rendering-workflow.md

@@ -29,7 +29,7 @@ PNG exports are review artifacts only. They are not the design source of truth.
 Da Vinci now requires the session wrapper on autonomous runs:
 
 - `da-vinci pencil-session begin`
-- `da-vinci pencil-session persist`
+- `da-vinci save-current-design`
 - `da-vinci pencil-session end`
 
 This wrapper exists to make three things mandatory:
@@ -75,18 +75,21 @@ When resuming from existing artifacts:
 
 Da Vinci does not treat headless interactive `save()` as authoritative persistence truth.
 
-Instead, the persistence step is:
+Instead, the primary persistence step is:
 
-1. read MCP-readable node snapshot data
-2. read MCP-readable variable snapshot data
-3. write the project-local `.pen`
-4. reopen-verify it
-5. compare live snapshot and persisted snapshot hashes
+1. run `da-vinci save-current-design --project <project-path>`
+2. require one explicit result envelope: `saved`, `blocked`, or `unavailable`
+3. treat only `saved` as persisted success
+4. treat `blocked` as save-time source/lock/payload contract failure
+5. treat `unavailable` as MCP bridge/runtime capture absence (never as a successful save)
 
 Relevant commands:
 
-- `da-vinci write-pen`
-- `da-vinci check-pen-sync`
+- high-level: `da-vinci save-current-design`
+- low-level fallback: `da-vinci pencil-session persist`, `da-vinci write-pen`, `da-vinci check-pen-sync`
+
+The MVP safety guarantee is source-path convergence only: registered `.pen`, session `penPath`, and active editor path must converge.
+Exact window-instance identity remains out of scope until MCP exposes stable window/editor identifiers.
 
 `da-vinci snapshot-pen` is disk-to-disk only. It is not the live-edit persistence path.
 
@@ -251,7 +254,7 @@ Typical autonomous chain:
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
 2. if external/secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before edits; if diverged, sync the preferred source into `<project-pen>` first
 3. Pencil MCP edits
-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 when configured
@@ -278,13 +281,13 @@ flowchart TD
     K -- No --> F
     K -- Yes --> L{Design-supervisor review configured?}
     L -- Yes --> M[Run design-supervisor review on screenshots plus theme inputs]
-    L -- No --> N[pencil-session persist writes live MCP snapshot back to .pen]
+    L -- No --> N[save-current-design persists bound live snapshot back to .pen]
     M --> O{Require Supervisor Review?}
     O -- No --> N
     O -- Yes --> P{Review PASS or accepted WARN?}
     P -- No --> F
     P -- Yes --> N
-    N --> Q[check-pen-sync verifies live hash equals persisted hash]
+    N --> Q[save-current-design returns saved or a terminal blocker/unavailable result]
     Q --> R{design-source checkpoint and runtime gate pass?}
     R -- No --> F
     R -- Yes --> S{More design work needed?}

package/docs/prompt-entrypoints.md

@@ -66,13 +66,17 @@ Continuation precedence:
 
 - when shell access is available, run `da-vinci workflow-status --project <path> [--change <id>] --json` before route selection
 - use `da-vinci next-step --project <path> [--change <id>]` as the first continuation routing signal
+- prefer reading `da-vinci next-step --project <path> [--change <id>] --json` when available so discipline marker state, execution-profile hints, and verification freshness are explicit
 - run `da-vinci lint-spec --project <path> [--change <id>]` when runtime spec quality is uncertain before routing into `build`
 - run `da-vinci scope-check --project <path> [--change <id>]` when page or state propagation across planning artifacts is uncertain
+- run `da-vinci lint-tasks --project <path> [--change <id>]` before routing into `build` when task metadata quality is uncertain
 - run `da-vinci verify-bindings --project <path> [--change <id>]` and `da-vinci verify-coverage --project <path> [--change <id>]` before terminal completion routing
 - run `da-vinci diff-spec --project <path> [--change <id>]` after planning edits when continuation must reason about changed requirement slices
 - determine routing from artifact and checkpoint truth first
 - use contextual checkpoint deltas only as auxiliary recovery context
 - if contextual deltas conflict with current artifacts, ignore them for routing and note the conflict
+- if design approval discipline markers are missing, malformed, or stale, keep routing in `design` or `tasks` and avoid direct promotion into `build`
+- if bounded-parallel execution is hinted, run `da-vinci worktree-preflight --project <path> [--change <id>]` before emitting a parallel build continuation prompt
 
 ## Default Flow
 
@@ -93,6 +97,7 @@ State rule:
 
 - if design is done but `tasks.md` does not exist yet, the next recommended route should usually be `tasks`, not `build`
 - only recommend `build` as the primary next step once tasks and implementation readiness are already clear
+- never include terminal completion wording unless fresh verification evidence is present and completion audit is explicitly required
 
 ## Platform Syntax
 

package/docs/prompt-presets/README.md

@@ -21,7 +21,7 @@ Recommended flow:
 4. copy both into your workflow setup
 5. tighten the prompt further only when the project has unusual truth sources or platform constraints
 6. when Pencil MCP is active, prefer the redesign prompts that explicitly require an MCP runtime gate plus a completion audit before terminal completion claims
-7. for project-local `.pen` persistence on autonomous runs, require prompts that drive `da-vinci pencil-session begin / persist / end`; fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the wrapper truly cannot be used
+7. for project-local `.pen` persistence on autonomous runs, require prompts that drive `da-vinci pencil-session begin / save-current-design / end`; treat `saved`, `blocked`, and `unavailable` as distinct outcomes, and only fall back to lower-level payload persistence when high-level save is unavailable
 
 Available presets:
 

package/docs/prompt-presets/desktop-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.