@brunosps00/dev-workflow 2.1.0 → 2.3.0

package/scaffold/en/commands/dw-plan.md

@@ -44,6 +44,8 @@ When available under `./.agents/skills/`, use these as planning support:
 
 ## Agent Dispatch
 
+Use these roles only when bounded delegation improves the task; they may be performed locally. Do not spawn every listed agent or override inherited models automatically.
+
 When project agents are installed, use:
 
 - `dw-code-explorer` before TechSpec and Tasks to trace existing flows and reusable patterns.
@@ -92,7 +94,7 @@ For each stage: build the matrix, mark each dimension `covered` (fact discovered
 
 ## Codebase Intelligence
 
-<critical>If `.dw/intel/` exists, query it via `/dw-intel` before each stage. MANDATORY for TechSpec stage.</critical>
+Query `.dw/intel/` when it helps locate current patterns; inspect relevant source directly and validate index freshness. Reuse evidence already gathered across stages.
 - PRD stage: `/dw-intel "existing features in the <topic> domain"` to avoid duplicate functionality.
 - TechSpec stage: `/dw-intel "architectural patterns, API conventions, technical decisions"` to align with existing project shape.
 - Tasks stage: `/dw-intel "test patterns, build pipeline, deployment cadence"` for accurate task sizing.
@@ -141,8 +143,9 @@ Runs when default mode (after PRD approval) OR `plan techspec` OR `plan --from t
 5. **Constitution gate.** Each architectural decision lists `Respects: P-NNN` or `Deviates: P-NNN — justification: <ADR slug or rationale>`. Deviations from `severity: high/critical` principles without ADR → STOP.
 6. **API design discipline.** When defining endpoints, consult `dw-codebase-intel/references/api-design-discipline.md` for Hyrum's Law, error semantics, versioning.
 7. **UI sections** (when feature has UI): the 4 grounding questions from `dw-ui-discipline` must be answered in the techspec; state matrix + scene sentence required.
+   - For frontend data flow, dependencies or tooling, read `dw-ui-discipline/references/frontend-engineering.md` from the installed skills location. Reuse the module's quality baseline; add only affected decisions from `.dw/templates/frontend-quality-template.md`. Distinguish existing required checks from advisory/proposed controls. Include accepted configuration work and its validation in the task breakdown and execution matrix.
 8. **Branch name section:** `feat/prd-<feature-slug>`.
-9. **Testing strategy section:** explicit tests-per-method, mock setup, coverage targets (80% services, 70% controllers), E2E flows.
+9. **Testing strategy section:** behavior/risk coverage, lowest effective test layers, existing suites, justified mocks and applicable E2E flows. Project-required thresholds apply; no universal percentage target.
 10. **Output location:** `.dw/spec/prd-<feature-slug>/techspec.md` (same dir as PRD).
 
 ### Optional: `--council` flag
@@ -162,7 +165,7 @@ Runs when default mode (after TechSpec approval) OR `plan tasks`.
 ### Required behavior
 
 1. **Feature branch instruction:** include the `feat/prd-<feature-slug>` branch creation in the tasks summary.
-2. **Decompose** PRD + TechSpec into tasks. Target ~6 tasks per feature. **NEVER exceed 2 FRs per task.**
+2. **Decompose** PRD + TechSpec into tasks. Use coherent, independently verifiable slices; preserve complete requirement coverage without a fixed task or FR quota.
 3. **End-to-end coverage:** every user-facing flow has backend + frontend + functional UI subtasks if applicable.
 4. **Test placement (`dw-testing-discipline`):** every test-adding subtask names its invariant per the placement doctrine. Owning layer specified.
 5. **Constitution alignment:** every task lists `Constitution: respects P-NNN` or `Constitution: deviates P-NNN — ADR planned: <slug>` or `Constitution: n/a — reason: <one-liner>`.
@@ -172,20 +175,24 @@ Runs when default mode (after TechSpec approval) OR `plan tasks`.
    - Summary: `.dw/spec/prd-<feature-slug>/tasks.md`
    - Per-task files: `.dw/spec/prd-<feature-slug>/<N>_task.md`
 
-### Final Consistency Check (auto-invoked before user approval)
+### Task execution matrix
+
+At Stage 3 read `.dw/references/execution-contract.md`. Propose local or cross-tool development per task, choosing model, effort and installed agents from actual complexity and risk. Write schema 1.1 task templates and `execution-plan.json`, validate with `node .dw/scripts/lib/workflow-contract.mjs validate <plan.json>`, and check assignment IDs/dependencies against tasks.md. Present choices with rationale for approval; never silently pick another provider during execution. Legacy schema 1.0 plans remain valid and default to local execution.
+
+## Final Consistency Check (auto-invoked before user approval)
 
 Run 5-dimension check, write `.dw/spec/prd-<feature-slug>/tasks-validation.md`:
 
 1. **FR coverage:** every numbered FR maps to ≥1 task.
 2. **Task grounding:** every task references ≥1 FR.
-3. **Test coverage:** every user-facing FR has ≥1 test-adding task.
+3. **Test coverage:** every user-facing FR has a meaningful verification path, reusing existing tests when sufficient.
 4. **Dependency graph:** topological order valid, no cycles.
 5. **Constitution alignment:** every task has the alignment line (only if `.dw/constitution.md` exists).
 
-Any FAIL → STOP. Show the dimension table in chat. Three options: auto-fix (regenerate affected tasks), manual edit, explicit override with reason.
+Repair internal consistency failures and rerun the check. Ask only for material missing decisions or an explicit override with reason; do not request permission to repair the draft.
 
 ### Checkpoint
-Present tasks.md summary + per-task list. User approves to allow `/dw-run` execution.
+Present tasks.md plus the execution matrix (local/cross-tool, model, effort, agents and approved fallbacks). Approval authorizes these assignments. For an implementation request continue to `/dw-run` or the invoking `/dw-goal`; a planning-only request ends with the approved plan.
 
 ## Output Files Summary
 

package/scaffold/en/commands/dw-qa.md

@@ -81,6 +81,8 @@ When available under `./.agents/skills/`, these are invoked operationally:
 
 ### Behavior — UI mode
 
+Read the affected module's quality baseline/TechSpec. Reuse valid required-check evidence through `dw-verify`; keep browser behavior, contract validation and diagnostic reports distinct. When critical logic or weak assertions warrant mutation analysis, read `dw-testing-discipline/references/mutation-testing.md`. Do not introduce a score threshold or install a new suite for unrelated UI edits. Record unavailable/not-run diagnostics and investigated findings in `qa-report.md`.
+
 1. **Pre-flight**: confirm the project dev server can run. Confirm `.dw/spec/<prd>/` has the PRD + TechSpec + tasks.
 2. **Map FRs to test plan**: for each FR, identify the user-facing flow that exercises it.
 3. **Drive Playwright MCP** (if unavailable or blocked — common on WSL — fall back to the WSL-resilient local capture `node .dw/scripts/lib/capture-screenshots.mjs`, which picks the browser via `.dw/scripts/lib/resolve-browser.mjs`; see the "Browser on WSL" section of `dw-testing-discipline/references/playwright-recipes.md`):

package/scaffold/en/commands/dw-report.md

@@ -0,0 +1,169 @@
+<system_instructions>
+You are the progress-report loop. While long work is running in this session, you emit a detailed, timestamped report at a fixed cadence (default every 10 minutes) saying **what is already done, what is being done right now, and what is still left** — without the user having to ask "any news?". Each report goes to the chat AND is appended to a daily log under `.dw/reports/`. The loop disarms itself when the work is finished.
+
+## When to Use
+- Use when the user says "report every N minutes", "keep me posted while this runs", "give me status reports", "I want to know where we are every 10 minutes".
+- Auto-armed by `/dw-run` (all-tasks and `--resume` modes), by `/dw-autopilot` (execution invocation), and by the `dw-cli-run` adapters (`/dw-codex-run`, `/dw-claude-run`, `/dw-copilot-run`) when they dispatch long work. Auto-arm is idempotent and can be disabled with `DW_REPORT_AUTO=off`.
+- Do NOT use as a substitute for `/dw-pause` (mental-state handoff) or `/dw-goal status` (goal contract state). This is a heartbeat about work in flight, not durable project state.
+- Do NOT use to poll a background task the harness already notifies you about — the loop reports *around* those notifications; it never replaces them.
+
+## Pipeline Position
+**Predecessor:** any long-running command (`/dw-run`, `/dw-autopilot`, `/dw-goal`, `/dw-codex-run`, builds, deploys) | **Successor:** none — the loop ends with a final report; `/dw-pause` may consume the day's log.
+
+## Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-report` | Arm the loop at the default cadence (**10 minutes**). If already armed, print the current state and do nothing else. |
+| `/dw-report --every <N>m` | Arm (or re-arm) the loop at `N` minutes (`5m`, `10m`, `15m`, `30m`; `--every 600s` also accepted). Minimum `1m`. |
+| `/dw-report now` | Emit one report immediately, without touching the cadence. Works armed or not. |
+| `/dw-report status` | Show whether the loop is armed, the cadence, when it was armed, the last report time, how many reports were emitted, and the log path. |
+| `/dw-report stop` | Disarm. Emits a final report first if there is unreported progress. |
+
+## Inputs
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{EVERY}}` | Cadence. Optional; defaults to `10m`. | `--every 5m` |
+| `DW_REPORT_AUTO` | Env var. `off` disables auto-arm from other commands (manual `/dw-report` still works). | `DW_REPORT_AUTO=off` |
+| `DW_REPORT_BELL` | Env var. Optional shell command executed right before each report is written (local sound, desktop notification, etc.). Silent when unset. | `DW_REPORT_BELL="paplay /usr/share/sounds/freedesktop/stereo/message.oga"` |
+
+`report.bell` in `.dw/config.json` is the file-based equivalent of `DW_REPORT_BELL` (env var wins). Because the bell is machine-specific, prefer the env var over committing it.
+
+## State and Artifacts
+
+```
+.dw/reports/
+├── .gitignore        # ????-??-??.md and .active.json are machine-local (created by init/update)
+├── .active.json      # loop state — exists only while armed
+└── YYYY-MM-DD.md     # append-only daily log; one entry per emitted report
+```
+
+`.active.json` schema:
+
+```json
+{
+  "schema_version": "1.0",
+  "armed_at": "2026-08-24 15:10:02",
+  "every_seconds": 600,
+  "vehicle": "wakeup | background-bash",
+  "armed_by": "user | dw-run | dw-autopilot | dw-cli-run",
+  "seq": 3,
+  "last_report_at": "2026-08-24 15:40:12",
+  "last_state": "working | blocked | finished"
+}
+```
+
+Timestamps are **real** — always taken from `date '+%Y-%m-%d %H:%M:%S'`, never estimated.
+
+## Vehicle — how the loop stays alive
+
+<critical>The main thread never sleeps in the foreground. Pick ONE vehicle, record it in `.active.json`, and never claim "loop armed" unless that vehicle is actually scheduled.</critical>
+
+1. **Native wakeup (PREFERRED — Claude Code).** Use the harness's scheduled-wakeup facility (the same mechanism as `/loop` in self-paced mode): after every tick, schedule the next wake-up in `every_seconds`. Pass `noop: true` on a silent tick and `noop: false` on a tick that reported. The `reason` is `dw-report tick every <N>m`. The loop dies with the session — no orphan.
+2. **Background shell timer (FALLBACK — Codex, Copilot, OpenCode, or any harness without wakeups).** Run, in the background, `sleep <every_seconds>; date '+%Y-%m-%d %H:%M:%S'`. When its completion notification arrives, run the tick, then start the next timer. One timer at a time; never chain sleeps in the foreground.
+3. **Never a system cron.** A cron does not know when the work ended and keeps firing (and ringing the bell) for days. If the harness only offers cron-style scheduling, use it but treat `/dw-report stop` and the auto-disarm rule as mandatory cleanup.
+
+If the work changes vehicle mid-way (e.g. the session is resumed elsewhere), `/dw-report status` must say so honestly: `armed in state file, but no wake-up is scheduled in this session — run /dw-report to re-arm`.
+
+## Tick Protocol (every fire)
+
+1. **Timestamp.** `date '+%Y-%m-%d %H:%M:%S'`.
+2. **Assess from the session.** The source of truth is the session's own work — what you did, what you started, what came back. Use cheap observable checks as evidence, not as archaeology: `git log --oneline` since the last report, `git status --short | wc -l`, the tail of a log or stream this session started, the number of completed steps in a CLI stream (`grep -c '"type":"item.completed"' <stream>.jsonl`), a background task's last notification. Do NOT go mining `.dw/spec/`, `.dw/goals/`, or `STATE.md` to reconstruct history you were not part of.
+3. **Classify the moment.**
+   - **working** — something is in flight (a command, a subagent, a workflow, a CLI run, a build, a deploy) or you are actively implementing.
+   - **blocked** — nothing is running because the work is waiting on the user (a decision, an approval, a credential).
+   - **finished** — the work the loop was armed for is complete (or failed terminally) and nothing else is queued.
+4. **Decide whether to speak.**
+   - `working` → **REPORT**. Always. Even when nothing changed since the last tick ("build still at step 6/9, ~4 min left" is a valid, expected report).
+   - `blocked` → report **once** when the state changes to blocked (that is news); afterwards, on every tick where nothing changed, **stay silent**: no chat line, no log entry, no bell. The check happens; the output does not.
+   - `finished` → **FINAL REPORT immediately** (do not wait for the cadence when you notice completion outside a tick), then **disarm**: delete `.active.json`, cancel the pending wake-up/timer, and say so in the final report.
+5. **Bell (optional).** If `DW_REPORT_BELL` (or `report.bell`) is set, run it *before* writing. Never on a silent tick.
+6. **Write.** The report goes to the chat and is appended verbatim to `.dw/reports/YYYY-MM-DD.md` (create the file with a `# Reports — YYYY-MM-DD` heading if missing). Update `.active.json` (`seq`, `last_report_at`, `last_state`).
+7. **Re-arm** the vehicle — unless step 4 disarmed the loop.
+
+## Report Format — cumulative with delta highlighted
+
+The user asked for a **detailed** report. Detailed means: every item carries evidence, every in-flight item carries a measurable progress figure, and the remaining list is ordered with the next milestone first.
+
+```markdown
+📊 Report — 2026-08-24 15:40:12 (#3 · every 10m · armed 15:10)
+
+## ✅ Done (cumulative)
+- ➕ Task 3/7 — import parser handles quoted fields — `src/import/parser.ts`, commit `a1b2c3d`, 14 tests green
+- ➕ Task 2/7 — CSV schema validation — commit `9f8e7d6`, `npm test` 41/41
+- Task 1/7 — fixture set for imports — commit `1234abc`
+
+## 🔄 Doing
+- Task 4/7 — batch upsert endpoint — 6 files touched, last command `npm test -- import` (running 1m40s); codex stream: 23 steps completed, last `command_execution: pnpm build`
+
+## ⏳ Remaining
+1. Task 5/7 — error report download (next milestone, blocked on Task 4)
+2. Task 6/7 — UI wiring
+3. Task 7/7 — E2E for the happy path
+4. Level 2 review + QA + security gate
+
+## ⚠️ Blockers / decisions needed
+- none
+```
+
+Rules:
+- **`➕` marks items completed since the previous report.** Older items stay in the list without the marker, so each report is self-contained and still shows the pace.
+- **Evidence or it did not happen:** a file path, a commit SHA, a test count, a log line. "Implemented X" without evidence is not allowed.
+- **Measurable progress in Doing:** a step counter, a file count, a running command with its elapsed time, a percentage from a real progress line. Never a bare "in progress".
+- **Remaining is ordered:** the next milestone first, then the rest; include the pipeline gates that still lie ahead (review, QA, security audit, commit, PR) when they apply.
+- **Blockers section only when there is something to say** — otherwise write `- none` or omit it.
+- **Header counts are real:** `#n` is `seq`, the cadence and the arm time come from `.active.json`.
+- When the loop was armed by another command, the first report says so: `armed by /dw-run (all pending tasks)`.
+
+### Final report
+
+Same shape, with the header `📊 FINAL Report — <timestamp> (#n · loop disarmed)`, an explicit outcome line under Done (`Outcome: all 7 tasks committed, review APPROVED` or `Outcome: FAILED at task 4 — see blockers`), and `Remaining` listing what the user still has to do by hand (open the PR, approve the gate, merge).
+
+### Chat output for arm / status / stop
+
+```
+📊 Report loop armed — every 10m · vehicle: wakeup · log: .dw/reports/2026-08-24.md
+First report at ~15:20. Silent while blocked; final report + auto-disarm when the work ends. Stop with /dw-report stop.
+```
+
+```
+📊 Report loop — ARMED · every 10m · since 15:10 · 3 reports · last 15:40 · state: working · log: .dw/reports/2026-08-24.md
+```
+
+```
+📊 Report loop — NOT armed. Arm with /dw-report [--every <N>m].
+```
+
+## Cadence Discipline
+
+<critical>The cadence is the user's, not yours. Never stretch the interval to "wait for the build to finish" or "avoid noise" — a report that says "nothing changed, ~X min left" is the product while work is running. Change the interval only on an explicit user instruction (`--every`).</critical>
+
+<critical>Never claim the loop is active without a scheduled wake-up or a live background timer. `/dw-report status` reads `.active.json` AND checks the vehicle; if they disagree, say so.</critical>
+
+<critical>Silence is only for the blocked/idle state. Working state always reports; the transition to blocked reports once; completion reports immediately.</critical>
+
+## Auto-arm Contract (for the commands that call this)
+
+When `/dw-run` (Mode 2 / Mode 3), `/dw-autopilot` (execution invocation), or a `dw-cli-run` adapter starts long work, it invokes `/dw-report` **before** dispatching:
+
+- **Idempotent:** if `.dw/reports/.active.json` exists and the vehicle is live, do nothing (keep the existing cadence). If the file exists but the vehicle is dead, re-arm and say so.
+- **Respects opt-out:** if `DW_REPORT_AUTO=off`, skip silently (one line in the caller's output: `report loop: auto-arm disabled by DW_REPORT_AUTO`).
+- **Records the caller:** `armed_by` in `.active.json`, echoed in the first report.
+- **Ends with the caller's work:** the caller's completion (all tasks done + final review, goal complete + PR gate, CLI run gated) is the `finished` state — final report, then disarm. The caller does not need to call `/dw-report stop`.
+- **Never blocks the caller:** arming takes one tool call; if the vehicle is unavailable, the caller proceeds and prints `report loop: no wake-up vehicle available in this harness — run /dw-report manually if you want a background timer`.
+
+## Anti-patterns
+- Reporting "in progress" without a number, a command, or a file.
+- Inventing a timestamp, a commit SHA, or a test count.
+- Emitting `idle` / `no news` lines while nothing is running — that is exactly the noise this loop exists to prevent.
+- Stretching or skipping a tick while work is running.
+- Leaving a system cron behind after the work ended.
+- Reading `.dw/spec/` or `.dw/goals/` to narrate work this session did not do.
+- Ringing the bell on a silent tick.
+
+## Structured Return
+
+After arming, stopping, or each report, the command's own status is fully described by the chat line plus `.dw/reports/.active.json`. Other commands only need to know: **armed (bool), every_seconds, seq, last_state**.
+
+</system_instructions>

package/scaffold/en/commands/dw-resume.md

@@ -15,8 +15,8 @@ You are a session-resumption agent. Your job is to read `.dw/STATE.md`, orient y
 ## Workflow
 
 ### 1. Read STATE.md
-- If `.dw/STATE.md` is missing, report: "No paused state found — this looks like a fresh session. Run `/dw-help` for next steps." Stop here.
-- If `STATE.md` exists but every section is `_none_`, report: "STATE.md is empty — nothing to resume. Tell me what you want to do."
+- If `.dw/STATE.md` is missing or empty, inspect `.dw/goals/*/status.json`, `.dw/spec/*/execution-state.json` and `active-session.md`. Use the explicit target or unique active workflow; ask only if multiple candidates remain. Report no resumable work only after checking these sources.
+- Cross-check any recovered checkpoint against actual files and evidence.
 
 ### 2. Cross-reference with disk
 Verify that the state still matches the filesystem:
@@ -63,13 +63,7 @@ Based on the TLDR, route to a concrete command. Use these heuristics:
 | Blocker waiting on external input | Suggest the user resolve the blocker first |
 | Only Todos and Decisions, no active work | Ask the user what they want to start |
 
-Phrase the suggestion as a question, not an order:
-
-```
-Want me to <suggested command>?
-- yes → I'll run it
-- no, <other intent> → tell me what instead
-```
+For a request to continue, execute the identified next step using existing authorization and saved task assignments. A status-only question receives the summary and suggested next step without execution.
 
 ### 5. Update STATE.md frontmatter
 
@@ -77,7 +71,7 @@ Set `last_resumed` to today's date (YYYY-MM-DD). Do not modify section content
 
 ## Required Behavior
 
-<critical>NEVER auto-execute the suggested command. `/dw-resume` only proposes; the user confirms before any `/dw-run`, `/dw-plan`, or `/dw-bugfix` fires.</critical>
+<critical>Honor the requested intent: continue authorized work on resume; report only for status questions. Read `.dw/references/execution-contract.md` for assignment/session recovery and evidence invalidation.</critical>
 
 <critical>NEVER fabricate stale-detection results. If you didn't run `ls`, don't report the file exists or doesn't exist.</critical>
 
@@ -85,6 +79,6 @@ Set `last_resumed` to today's date (YYYY-MM-DD). Do not modify section content
 
 ## Inspired by
 
-This command adapts the session-handoff pattern from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). Adaptations: routing heuristics map STATE.md content to specific `dw-*` commands; cross-reference with `.dw/spec/` and `.dw/bugfixes/` to detect staleness; never auto-execute.
+This command adapts the session-handoff pattern from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). Adaptations: routing heuristics map STATE.md content to specific `dw-*` commands; cross-reference with `.dw/spec/` and `.dw/bugfixes/` to detect staleness; intent-aware continuation after an authorized resume request.
 
 </system_instructions>

package/scaffold/en/commands/dw-review.md

@@ -173,10 +173,11 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
    - Cyclomatic / cognitive complexity (with `dw-simplification` thresholds).
    - DRY violations (only when impact is meaningful — not premature deduplication).
    - Code smells (Fowler taxonomy).
+   - For frontend data flow, dependency or quality-tooling changes, read `dw-ui-discipline/references/frontend-engineering.md` and the module's quality baseline/TechSpec. Inspect API generation/validation, import boundaries, duplicated business behavior, unreachable code and newly widened ignores. Execute adopted checks under `dw-verify`; an absent optional tool is a proposal, not an automatic rejection. Investigate mutation survivors when analysis is in scope; do not approve from a score alone. Report changes to CI enforcement separately from local test results.
 
 5. **Test execution:**
-   - Run the project's test command.
-   - Verify coverage targets per TechSpec (80% services, 70% controllers).
+   - Use `dw-verify` to inspect valid test evidence; run missing or invalidated required checks.
+   - Verify the approved testing strategy and project-required thresholds; no universal coverage target.
 
 6. **Apply `dw-review-rigor`:**
    - De-duplicate findings.
@@ -184,7 +185,7 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
    - Verify intent before flagging (the linter already catches some — those don't repeat).
 
 7. **Final verification (`dw-verify`):**
-   - Run dw-verify to produce a VERIFICATION REPORT (test + lint + build all GREEN).
+   - Use dw-verify to produce a VERIFICATION REPORT for applicable required checks, reusing equivalent evidence.
    - Without PASS, verdict cannot be APPROVED.
 
 8. **Security Gate (`dw-secure-audit` for TS/Python/C#/Rust):**

package/scaffold/en/commands/dw-run.md

@@ -1,179 +1,33 @@
 <system_instructions>
-You are the task execution orchestrator. Two modes: execute ONE specific task, or execute ALL pending tasks in dependency order. Both modes apply the same task-level guarantees (atomic commit per task, mandatory tests, verify before commit, deviation handling).
+# Execute approved tasks
 
-## When to Use
-- Use `run` after `/dw-plan` has produced `tasks.md` + per-task files and the tasks are approved.
-- Use to execute a single targeted task during incremental development.
-- Do NOT use for bug fixes — `/dw-bugfix` handles those.
-- Do NOT use without an approved tasks breakdown — tasks files MUST exist.
+Use `/dw-run` for all pending tasks, `/dw-run <task-id>` for one, and `/dw-run --resume` to continue. Inputs are the task ID and active `.dw/spec/<prd>/` directory. Tasks and dependencies must exist and be approved. For investigation without a plan use `/dw-bugfix`.
 
-## Pipeline Position
-**Predecessor:** `/dw-plan` (with tasks approved) | **Successor:** `/dw-review` then `/dw-commit` + `/dw-generate-pr`
+## Assignment and preparation
 
-## Modes
+Read `.dw/references/execution-contract.md` and the relevant task file. Consume `execution-plan.json` when present; validate it with `node .dw/scripts/lib/workflow-contract.mjs validate <plan.json>`. Cross-check IDs/dependencies against tasks.md. Legacy schema 1.0 tasks without assignments execute locally. Never infer cross-tool authorization from installed CLIs alone.
 
-| Invocation | Behavior |
-|------------|----------|
-| `/dw-run` | **Default.** Executes ALL pending tasks from `tasks.md` in dependency order. Wave-based parallel dispatch for independent tasks. Atomic commit per task. After all complete, runs Level 2 review (PRD compliance). |
-| `/dw-run <task-id>` | Executes ONE specific task by ID (e.g., `1.0`, `2.3`). Includes Level 1 validation. Atomic commit on success. |
-| `/dw-run --resume` | Resumes an interrupted multi-task plan from where it stopped. Reads `.dw/spec/<prd>/active-session.md` if present; otherwise continues from first pending task. |
+Respect applicable constitution decisions and the task's requirement IDs (`FR-N.M` / `RF-N.M`). Missing constitution uses non-blocking defaults. Inspect relevant source and project rules; query `.dw/intel/` only when useful and check freshness. Do not require a full repository map before every task.
 
-## Inputs
+Load skills by need: `dw-verify` for evidence, `dw-memory` for relevant durable decisions/checkpoints, `dw-testing-discipline` when designing tests, `dw-ui-discipline` for UI, `dw-llm-eval` for AI behavior, `dw-execute-phase` for dependency/plan checks. Use `dw-search-first` for new dependencies and `dw-minimalism` for a concrete abstraction/scope decision, not before each new function. Use `dw-simplification` for an explicitly scoped cleanup after verification. For explicitly requested TDD/test first/red-green-refactor, use `dw-testing-discipline/references/tdd-loop.md` for that task.
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `{{TASK_ID}}` | Specific task identifier (optional — defaults to all pending) | `1.0`, `2.3`, `5.1` |
-| `{{PRD_PATH}}` | Path to PRD directory containing tasks (optional — auto-detect from active branch) | `.dw/spec/prd-invoice-export` |
+## Execution loop
 
-## Complementary Skills
+1. Arm `/dw-report` once (idempotent, skipped when `DW_REPORT_AUTO=off`). Validate task coverage, dependency graph and acceptance checks using `dw-execute-phase`; repair internal inconsistencies before execution, ask only for missing material decisions.
+2. Choose the next task whose dependencies are complete on the execution branch. Independent tasks may run concurrently only with approved agents/worktrees and a defined integration path. One writer per worktree; coupled tasks stay sequential.
+3. Use the approved task executor/model/effort/agents. Local assignments execute in the current workflow. Cross-tool assignments invoke `/dw-codex-run`, `/dw-claude-run`, or `/dw-copilot-run` with the prepared task packet. The parent owns the objective throughout.
+4. Implement acceptance criteria with project patterns, tests from the approved strategy and necessary failure handling. When a worker returns, independently inspect diff and criteria; inspect/reuse valid evidence or run affected checks through `dw-verify`. Fix in-scope failures automatically, using the same external session when applicable.
+5. Commit only scoped task changes after valid verification; retain atomic commits and requirement IDs. Include task status in the commit, then record its SHA in the `Commit` column of tasks.md and run-log.md. Commit remaining bookkeeping in the next task or final metadata commit; never `git add .` across unrelated changes.
+6. Update `execution-state.json`, `active-session.md` and run-log.md with completed tasks, assignments, branch/worktree, exact sessions, verification and next step. Continue remaining approved tasks; `--checkpoint` explicitly requests a pause between waves.
+7. After all tasks, run `/dw-review` for requirement coverage and code quality. Correct in-scope findings automatically; user decisions are needed only for scope changes or deferrals. Full implementation workflows continue to applicable `/dw-qa` and fixes under `/dw-goal` or the invoking orchestrator. A single-task request ends after that task's validated handoff.
 
-When available under `./.agents/skills/`, these skills are invoked per task:
+## Resume and blockers
 
-- `dw-verify`: **ALWAYS** — before each task's commit, produces a Verification Report (test + lint + build all GREEN). Without PASS, no commit. The Iron Law of verification.
-- `dw-memory`: **ALWAYS** — reads workflow memory at task start; updates at task end with the promotion test (lessons that apply to next task get promoted to shared MEMORY.md).
-- Instincts (lazy): at task start, also load any high-confidence instinct (`.dw/memory/instincts/`, confidence ≥0.7) whose `trigger` matches the task — learned project conventions promoted by `/dw-learn`. Match by trigger only; never bulk-load the set.
-- `dw-execute-phase`: provides `plan-checker` (6-dimension goal-backward verification before any code is touched in plan mode) and `executor` (atomic commit + deviation handling) agents.
-- `dw-testing-discipline`: applies the placement doctrine, 6 agent guardrails, and 25 anti-patterns when adding tests during the task.
-- `dw-testing-discipline` test-first mode: ONLY when the task text or user explicitly says `TDD`, `test first`, or `red-green-refactor`, execute that task through `references/tdd-loop.md` (confirm public seams with the user → write ONE red test → run and observe red → implement minimum green → run and observe green → next slice; refactor only after the loop via `dw-simplification`). This is not the default `/dw-run` mode.
-- `dw-ui-discipline`: when the task touches UI, the 4 grounding questions must be answered before any visual decision lands.
-- `dw-llm-eval`: when the task touches AI feature code paths, the reference dataset + oracle ladder rules apply.
-- `dw-minimalism`: **before writing new code** — climb the YAGNI decision ladder (need it? reuse? stdlib? native? installed dep? one line?) at the active intensity, then write the minimum. Hands new dependencies to `dw-search-first`.
-- `vercel-react-best-practices`: when the task touches React/Next.js performance.
+A resume request already authorizes continuation. Inspect saved state and actual worktree rather than asking “continue?” again. Keep completed tasks and approved assignments; validate dependencies and prior evidence. Recover missing session IDs only from task-specific logs with identity checks; otherwise reconstruct a new session in the same worktree without discarding changes. See execution-contract for cross-provider limitations.
 
-## Constitution Gate
+Missing dependency: finish its pending approved task first; ask only if it is outside the plan. Verification failure: diagnose, fix and rerun invalidated checks. Missing test framework: discover the configured runner before asking. Increased complexity: record a deviation and split/reorder within approved scope. New product behavior, architectural conflict or unapproved dependency: propose the material change and wait only on dependent work. Preserve checkpoints at a real impasse or user pause.
 
-<critical>BEFORE executing any task, check `.dw/constitution.md`. If MISSING, auto-install defaults via the v0.11 pattern. If PRESENT, the task's `Constitution Alignment` line (set during `/dw-plan` Stage 3) is consulted as the task executes — code must respect the claimed principles.</critical>
-
-## Codebase Intelligence
-
-<critical>If `.dw/intel/` exists, query it via `/dw-intel` before implementation to align with existing patterns.</critical>
-- Per-task: `/dw-intel "patterns for <task topic>"` to surface relevant conventions.
-
-## Mode 1: ONE task (`run <task-id>`)
-
-### Prerequisites
-- `tasks.md` + per-task files exist in `.dw/spec/<prd>/`.
-- The target task's dependencies are completed (check `task.md` "Depends on" section).
-
-### Behavior
-
-1. **Read the task file:** `.dw/spec/<prd>/<task-id>_task.md`. Understand inputs, FRs covered, acceptance criteria, subtasks.
-2. **Plan implementation:**
-   - List files to create/modify.
-   - Identify test additions per subtask.
-   - Confirm dependencies (if missing, STOP and surface).
-3. **Implement:**
-   - Follow project patterns from `.dw/rules/` and `.dw/intel/`.
-   - Apply complementary skills (UI gate, test discipline, etc.).
-   - Mandatory unit tests for backend/services per testspec.
-   - Match the testing framework specified in `.dw/rules/`.
-4. **Validate (Level 1):**
-   - Run the project's test command.
-   - Check acceptance criteria from the task file.
-   - Run `dw-verify` to produce the Verification Report (test + lint + build GREEN).
-   - For interactive frontend, also validate real behavior via `dw-testing-discipline` Playwright recipes if regression risk is meaningful.
-5. **Commit:**
-   - Atomic commit message: `feat(<scope>): <task title> (#<task-id>)`.
-   - Reference the FRs covered.
-   - One task = one commit (unless the task explicitly has subtask milestones that earn separate commits).
-6. **Update tasks.md:** set this task's `Status` to `Done` and write the short SHA (`git rev-parse --short HEAD`) into its `Commit` column. This is the only record linking a task to its diff — do not skip it.
-7. **Report:** what was done, what tests were added, what was validated.
-
-### STOP CONDITIONS
-- Dependencies not satisfied → ask user how to proceed.
-- Verification Report FAIL → do not commit; report what's broken.
-- Task scope creep detected mid-implementation → STOP and ask user to scope.
-
-## Mode 2: ALL pending tasks (default `run`)
-
-### Prerequisites
-- `tasks.md` + per-task files exist with declared dependencies.
-- `tasks-validation.md` shows PASS (or explicit override).
-- The branch is created: `feat/prd-<feature-slug>`.
-
-### Behavior
-
-1. **Plan check (via `dw-execute-phase/plan-checker` agent):**
-   - 6-dimension goal-backward verification: are these tasks actually going to deliver what the PRD promises?
-   - If FAIL on any dimension, STOP and report to user before any code is touched.
-2. **Build dependency graph:**
-   - Topological sort of tasks.
-   - Identify independent tasks that can run in parallel waves.
-3. **Wave-based parallel dispatch (via `dw-execute-phase/executor` agent):**
-   - Each wave contains tasks with no inter-dependencies.
-   - Execute waves serially; within a wave, tasks dispatch in parallel.
-   - Per-task: same Level 1 flow as Mode 1 (implement → validate → atomic commit).
-4. **Deviation handling:**
-   - If a task encounters scope creep, STOP that task, surface to user.
-   - If a task fails verification, the wave halts. No subsequent waves run until resolved.
-5. **Checkpoint between waves:**
-   - Print wave summary: tasks completed, commits, any deviations.
-   - Continue automatically unless `--checkpoint` was passed (then wait for user OK).
-6. **Final Level 2 review:**
-   - After all tasks complete, automatically invoke `/dw-review` (the merged review command — runs both PRD compliance check and code quality review).
-   - Present consolidated review report.
-   - Interactive corrections cycle: review surfaces gaps → user decides to fix, defer, or accept.
-
-### Output
-
-```
-.dw/spec/<prd>/
-├── active-session.md      # written at checkpoint; consumed by --resume
-├── run-log.md             # per-wave execution log with commit SHAs
-└── review-consolidated.md # final L2+L3 review (from /dw-review)
-```
-
-## Mode 3: Resume (`run --resume`)
-
-### Prerequisites
-- Previous `run` (Mode 2) was interrupted.
-- `active-session.md` exists in the current PRD's `.dw/spec/<prd>/` directory.
-
-### Behavior
-
-1. Read `active-session.md` to determine which task/wave the session stopped at.
-2. Surface to user: "Resuming from wave N, task X.0. Previously completed: <list>. Continue?"
-3. On confirmation, resume from the next pending task with the same Mode 2 behavior.
-
-If `active-session.md` doesn't exist but uncompleted tasks remain, treat as Mode 2 fresh start.
-
-## Across all modes: deviation handling
-
-When implementation cannot proceed as planned:
-
-| Deviation | Action |
-|-----------|--------|
-| Task requires new dependency not in TechSpec | STOP. Suggest `/dw-plan techspec --update` to revise. |
-| Acceptance criterion is ambiguous | STOP. Ask user for clarification. |
-| Test framework decision missing | STOP. Use `dw-testing-discipline` placement doctrine to propose; ask for sign-off. |
-| Pattern from `.dw/rules/` doesn't fit cleanly | STOP. Surface the friction; propose either an ADR-justified deviation or a rules update. |
-| Hidden complexity emerges (task estimated 2h, looks like 8h) | STOP. Surface; either split the task via `/dw-plan tasks --update` or accept the delay with note. |
-
-## Reporting
-
-After every run (Mode 1, 2, or 3 completion), print:
-
-- Tasks completed with commit SHAs.
-- Files touched count.
-- Tests added (unit + E2E if applicable).
-- Verification Report verdict per task.
-- For Mode 2: final consolidated review status.
-- For Mode 2: any deviations encountered and how they were resolved.
-
-## Anti-patterns
-
-- Skipping `dw-verify` to "save time before commit" — produces commits that don't build.
-- Running tasks without dependency satisfaction — produces commits that won't work in isolation.
-- Letting wave-based parallel run without watching for deviations — silent scope creep compounds.
-- Committing multiple tasks in one commit — breaks bisect, breaks revert granularity.
-- Skipping the final Level 2 review in Mode 2 — ships features that don't fully match the PRD.
-
-## Final Guidelines
-
-- Atomic commits are non-negotiable. One task = one commit (or one subtask-bundle if explicit).
-- Tests are mandatory per the testing strategy section of the TechSpec.
-- Verification Report PASS is the gate, not the goal — never weaken assertions to make tests pass.
-- Deviation surfacing is a feature, not a bug. Stop and ask. The user prefers an interruption to a wrong implementation.
-- For multi-day plans, `--resume` is your friend. Don't restart from zero.
+## Completion report
 
+Return completed task IDs and commit SHAs, affected files, valid checks, unresolved findings and next step. `/dw-review` writes `<prd-path>/QA/review-consolidated.md`. Durable state and logs remain in the spec directory; worker audit/session files stay outside disposable worktrees. A passed gate proves its scope only; never weaken assertions or hide a blocking finding. Merge, push and publication require applicable authorization.
 </system_instructions>

package/scaffold/en/commands/dw-skill-health.md

@@ -24,7 +24,14 @@ You are the dev-workflow skill and agent health auditor.
 
 `SKILL.md` should be a short router/protocol. Long rules, examples, palettes, recipes, services, and assets must stay in references/assets/rules/recipes and be loaded lazily.
 
+## Discovery and context budgets
+
+Check managed instructions ≤6000 bytes, skill entrypoints ≤8000 bytes and descriptions ≤250 characters. In package source run `npm run validate`; in consumers inspect installed files. Distinguish discovery metadata from on-demand bodies. Flag unconditional reference loading and broad overlapping triggers, not every platform copy as duplicate live context. Check routed reference paths and preserve attribution/Structured Return when compacting. Model candidates may be stale: propose updates to routing.json after verifying availability; never overwrite owner choices silently.
+
 ## Output
+
+When `.dw/config/routing-defaults.json` exists, compare its current candidates with the owner's `.dw/config/routing.json`. Report relevant differences and validate proposed models/capabilities before adoption. Different values can be intentional; do not treat them as failed migration or overwrite them automatically. Approved task assignments take precedence over either candidate file.
+
 Return a concise health report with a structured-return section. Do not delete files.
 
 Include:

package/scaffold/en/commands/dw-update.md

@@ -38,7 +38,7 @@ Keep only the 3 most recent snapshots (remove older ones) to avoid buildup.
 Before updating, capture the installed version so you can report the delta:
 
 ```bash
-node -e "try { console.log(require('@brunosps00/dev-workflow/package.json').version) } catch(e) { console.log('not-cached-locally') }" 2>/dev/null
+node -e 'try { const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state.json", "utf8")); console.log(s.version || "unknown"); } catch { console.log("unknown"); }'
 ```
 
 ### 2. Detect Language of Installed Commands (Required)
@@ -71,7 +71,7 @@ Rules:
 
 ### 3. Run the Update (Required)
 
-<critical>Use `npx -y @brunosps00/dev-workflow@latest` to FORCE fetching the latest version from npm (bypass local cache). Pass `--lang=<DETECTED_LANG>` to skip the interactive prompt.</critical>
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` to select the version tagged `latest` on npm. Pass `--lang=<DETECTED_LANG>` to skip the interactive prompt.</critical>
 
 ```bash
 npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
@@ -90,9 +90,23 @@ If the update fails (network error, permission, package unavailable): report the
 ### 4. Capture New Version
 
 ```bash
-node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+node -e 'const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state.json", "utf8")); if (s.package !== "@brunosps00/dev-workflow" || !s.version) process.exit(1); console.log(s.version);'
 ```
 
+### Upgrade compatibility checks
+
+Read the refreshed `.dw/commands/dw-update.md` after the CLI completes. Use `.dw/install-state.json` and the CLI's `Installed version` output for the version delta: an `npx` package need not be resolvable from the consumer's `node_modules`. A missing or invalid new install state is a failed verification; do not claim the update succeeded.
+
+For an upgrade from before 2.3.0 (or an unknown legacy version):
+
+- Verify `.dw/references/execution-contract.md`, `.dw/scripts/lib/workflow-contract.mjs` and `.dw/templates/frontend-quality-template.md` were delivered. Managed commands, skills, wrappers and instruction blocks refresh through normal `update`; no `--force` is needed.
+- Compare `.dw/config/routing.json` with the newly managed `.dw/config/routing-defaults.json` during `/dw-skill-health`. Keep active owner choices and approved assignments. Propose specific model/effort changes after checking capabilities; updating scaffold files alone does not authorize changing providers.
+- Preserve `.dw/spec/`, `.dw/goals/`, `.dw/STATE.md`, execution/session state, rules and `.dw/templates/overrides/`. Schema 1.0 plans remain valid and local by default. For an active `execution-plan.json`, run `node .dw/scripts/lib/workflow-contract.mjs validate <plan-path>`; report invalid plans without rewriting approvals or resetting progress. New task plans use schema 1.1.
+- Inspect task template overrides for old schemas/routing rules and report any differences that shadow the new managed templates; do not replace owner overrides automatically.
+- If frontend quality documentation is relevant and missing, have `/dw-analyze-project` add the baseline to the existing module rules, scoped to that documentation. Preserve existing gates; propose tooling separately. Skip this action for `update files only`.
+
+Do not force-convert active work or globally regenerate product documentation to adopt the release. Record compatibility findings and retain session reload as the final step.
+
 ### 5. Report Result
 
 Present to the user:
@@ -156,7 +170,7 @@ E.g.: `npx -y @brunosps00/dev-workflow@0.4.5 update --lang=en`
 ## Notes
 
 - `npx -y` skips the "OK to install" prompt when the package is not cached
-- `@latest` bypasses the npx cache and pulls the `latest` tag from the registry
+- `@latest` selects the registry tag; verify the installed result rather than assuming a local package lookup identifies the executed CLI
 - `--lang=...` skips the interactive language prompt; the value comes from the auto-detection in step 2
 - This command does NOT update the user project's Node dependencies — only the dev-workflow scaffold