@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.5

package/commands/claude/dv/build.md

@@ -15,6 +15,8 @@ Before broad implementation when shell access is available:
 - 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
 
@@ -25,10 +27,13 @@ Focus on:
 
 During implementation:
 - 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 ...`
 - update source artifacts before continuing if drift is found
 
 Completion discipline:
 - treat `BUILD SUCCESSFUL` as compile-only evidence, not workflow completion
 - do not report `design complete` or `workflow complete` while in-scope task groups remain unfinished
+- 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/claude/dv/continue.md

@@ -23,14 +23,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 `/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/claude/dv/tasks.md

@@ -13,6 +13,12 @@ Focus on:
 - Pencil coverage
 - dependency order
 
+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
+
 Create or update:
 - `tasks.md`
 

package/commands/claude/dv/verify.md

@@ -22,6 +22,8 @@ When shell access is available:
 - 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/codex/prompts/dv-build.md

@@ -15,6 +15,8 @@ Before broad implementation when shell access is available:
 - 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
 
@@ -22,7 +24,10 @@ 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/codex/prompts/dv-continue.md

@@ -23,14 +23,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 `/prompts:dv-build` unless the project is clearly implementation-ready
 - if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/prompts:dv-tasks`
 - only prefer `/prompts:dv-build` once task generation and implementation readiness are already clear
 - do not route into `/prompts:dv-build` when any design gate is unresolved: missing shell-visible project-local `.pen`, active/unclosed Pencil session, runtime/design-source checkpoint still BLOCK, or required design-supervisor review still BLOCK/unaccepted
+- 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/codex/prompts/dv-tasks.md

@@ -15,6 +15,12 @@ Tasks must cover:
 - 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`

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

@@ -20,5 +20,7 @@ When shell access is available:
 - 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/build.toml

@@ -14,6 +14,8 @@ Before broad implementation when shell access is available:
 - 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
 
@@ -21,8 +23,11 @@ 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/tasks.toml

@@ -11,6 +11,12 @@ Create or update:
 
 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`

package/commands/gemini/dv/verify.toml

@@ -19,6 +19,8 @@ When shell access is available:
 - 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
@@ -65,9 +66,30 @@ These commands do not replace route selection, but they support design execution
 - `da-vinci generate-sidecars --project <path> [--change <id>] [--json]`
   - explicitly generates deterministic planning sidecars: `spec.index.json`, `tasks.index.json`, `page-map.index.json`, `bindings.index.json`
   - this is the only write surface for planning sidecars; lint/status/verify surfaces should not silently rewrite them
-- `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 verify-bindings --project <path> [--change <id>] [--strict] [--json]`
+  - validates implementation landing resolution from `pencil-bindings.md`
+- `da-vinci verify-implementation --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - verifies planned-state/task-group implementation evidence with per-check `mode` + `confidence` metadata
+  - JS/TS checks are syntax-aware and do not count comment-only or string-literal-only matches as normal coverage
+  - when `--changed-files` is used, the run is explicit incremental scope (partial semantics) and reports selected/scanned/filtered file counts
+- `da-vinci verify-structure --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - verifies structural consistency against bindings and reports `markup` vs `heuristic` confidence surfaces
+  - when `--changed-files` is used, unmatched or irrelevant entries stay visible instead of silently widening to full scan
+- `da-vinci verify-coverage --project <path> [--change <id>] [--changed-files <csv>] [--strict] [--json]`
+  - aggregates upstream verification surfaces and marks incremental upstream results as partial freshness
+- `da-vinci scaffold --project <path> [--change <id>] [--output <path>] [--json]`
+  - generates reviewable TODO scaffold templates with framework-aware shape (`next`/`react`/`vue`/`svelte`/`html`)
+  - keeps known implementation landing extension/route shape when a concrete landing already exists
+  - unknown/ambiguous framework detection falls back to HTML with explicit warning; traversal/output-root safety remains enforced
+- `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
@@ -255,6 +277,10 @@ Build-stage self-check:
 - 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
 
@@ -286,6 +312,8 @@ Verify-stage self-check:
 - 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

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/prompt-entrypoints.md

@@ -66,13 +66,18 @@ 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
+- if using `--changed-files` with `verify-implementation`/`verify-structure`/`verify-coverage`, treat results as explicit incremental partial evidence, not full-project freshness
 - 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 +98,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/skill-contract-maintenance.md

@@ -0,0 +1,14 @@
+# SKILL Contract Maintenance
+
+Use this policy when editing workflow guidance:
+
+1. Keep invariant route/execution truth in `SKILL.md` only.
+2. Keep stage-specific procedure in one owned reference file.
+3. Ensure `SKILL.md` `Load References On Demand` map points to that owner.
+4. Avoid duplicate prose across `SKILL.md`, `references/`, and generated command assets unless tests explicitly require duplication.
+5. Update `references/skill-workflow-detail.md` move map when relocating sections.
+
+Boundary rule:
+
+- If a rule changes workflow truth, route semantics, or execution policy, edit core.
+- If a rule is tactical for one stage (design/build/review/scaffold), edit reference docs.

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:
 

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
 
@@ -185,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
@@ -195,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: