@brunosps00/dev-workflow 2.2.0 → 2.3.0

package/scaffold/skills/dw-cli-run/references/dispatch-tuning.md

@@ -1,85 +1,27 @@
-# Dispatch tuning — trim the cold start, bind the routing table
+# Dispatch diagnostics and tuning
 
-Read this when a dispatch feels disproportionately expensive for the size of the task, or when wiring
-`.dw/config/routing.json` for the first time. The protocol in `SKILL.md` works without it.
+Read when configuring a provider, diagnosing a failed dispatch, or proposing an approved escalation.
 
-## Cold-start cost
+## Configuration
 
-A spawned CLI does not share the parent session's prompt cache and boots every configured MCP server before doing
-any work. On a small task that startup can cost more than the task itself. This is the one real advantage an
-in-session subagent keeps over a spawned CLI — so trim the spawn until the gap stops mattering.
+Inspect CLI version/help for supported flags. Model identifiers and effort support depend on the selected model, provider, account and CLI; help alone is not an availability check. Use project routing candidates and current official provider documentation to propose concrete assignments at task breakdown. Do not silently overwrite `.dw/config/routing.json` during updates.
 
-| | Claude | Codex |
-|---|---|---|
-| No MCP servers | `--strict-mcp-config` (with no `--mcp-config`) | `-c mcp_servers='{}'` |
-| Drop all user config | — | `--ignore-user-config` (blunt: also drops model defaults, so `MODEL` + `EFFORT` become mandatory) |
-| Restrict tools | `--tools ""` disables all; `--allowedTools <list>` for a subset | `--sandbox read-only` |
+For legacy plans, `by_commit_type` may suggest a tier; sensitive surfaces and actual complexity take precedence. An approved task assignment wins over routing defaults. Agent profiles keep `model: inherit`; dispatch overrides belong in the task plan.
 
-**Default:** pass the MCP kill switch on every dispatch whose prompt does not name an MCP capability. If the
-prompt needs docs lookup (`context7`) or browser automation (`playwright`), keep them and say so in the dispatch
-rationale.
+## Permissions and MCP
 
-Verified against `claude` 2.1.220 and `codex-cli` 0.144.4. Re-check with `claude --help` / `codex exec --help`
-after a CLI upgrade — these flags are not covered by either project's stability guarantees.
+Use the approved permission profile for WRITE and enforced read-only controls for READ-ONLY. Preserve the same boundary on resume. Do not use bypass flags as a response to a generic network/test failure. Identify the failing operation and request only missing access if existing authorization does not cover it.
 
-## Binding `.dw/config/routing.json`
+Load MCP capabilities needed by the task, retaining user configuration. Claude supports `--strict-mcp-config` with an explicit config for selected servers. On Codex, a TOML override such as `mcp_servers='{}'` must not be assumed to remove inherited entries: confirm effective configuration before claiming zero servers. If no selective mechanism is available, retain configuration and report the overhead. Do not drop user rules/auth/config wholesale for a faster start.
 
-Resolution order for a dispatch:
+## Review and escalation
 
-1. Read the task's Conventional-Commit type (already in `tasks.md` and in the atomic commit subject).
-2. `by_commit_type[<type>]` → tier name.
-3. If the fence or the task title matches any `escalate_on_surface.patterns`, override the tier upward.
-4. `tiers[<tier>][<brand>]` → concrete `MODEL` + `EFFORT`.
-5. Substitute into the adapter's `MODEL`/`EFFORT` slots.
+Parent re-gate (independent) checks the actual implementation and acceptance criteria. It can reuse matching verification evidence after checking command, inputs, environment, scope and output. It need not buy another provider invocation solely to repeat passing commands. Where a specialized independent reviewer adds value, use the approved agent assignment.
 
-If the file is absent, or the task has no declared type, fall back to the sizing heuristic in `SKILL.md` step 2.
+Fix ordinary defects with the current executor. Escalate model/effort only when the diagnosis identifies a capability limit and the alternative is in the approved plan. Preserve the same session when supported; otherwise reconstruct from durable state in the same worktree. Never discard partial edits. Provider errors, missing credentials, resource limits and permission failures do not automatically justify a stronger model.
 
-`routing.json` is seeded once on init and never reconciled on update, because model availability differs per
-account. Treat the shipped model ids as defaults to verify, not as a guarantee of access — a dispatch that fails
-with an unknown-model error is a routing-table edit, not a protocol bug.
+Stop when the task is accepted or a concrete blocker prevents further progress; a 0–10 self-score neither proves quality nor authorizes endless retries. Report exhausted approved alternatives and preserve the branch for the owner.
 
-## Dual evaluation in full
+## Process handling
 
-The CLI auto-gates cheaply (close to the work); the parent/orchestrator audits independently and compares the
-scores, which is what catches an inflated self-score. The parent is the dispatching session — possibly Claude
-itself; the re-gate is provider-neutral.
-
-1. **Worker auto-gate (loop, MAX effort).** The prompt MUST instruct: after implementing, **run the SAME gate**
-   and give a **self-score 0–10**; **fix and re-run while the self-score <9 or the gate isn't green**, at max
-   effort. Stop at self-score ≥9 + green gate (or report `blockers`). The final report carries the self-score plus
-   a per-criterion breakdown.
-2. **Parent re-gate (independent).** When the worker declares pass, the parent **re-runs the SAME gate** (fan-out,
-   prefer Workflow → `/workflows`) and gives its **own 0–10**, without trusting the self-score. Prefer a different
-   brand for this step when both are installed — a second vendor fails differently, which is the whole point of
-   the second layer. With one brand installed, re-gate in a separate dispatch at a different tier.
-3. **Compare + decide.** Parent ≥9 and small gap → **PASS** (ready for the owner's merge decision). Parent <9 OR a
-   large gap (worker overestimated) → re-execute: hand the gaps back via **session resume** at max effort and
-   repeat 1→2→3 until it converges. **The score that counts for acceptance is the parent's**; the self-score is
-   signal plus an inflation detector. Always record both scores and the gap in the Structured Return.
-
-## The escalation ladder in full
-
-If the score is low, the gate failed, or the CLI didn't finish, re-run the SAME task one notch up — gradual, no
-giving up on the first stumble, no jumping to the top.
-
-- **Ladder (one at a time):** first **effort** `low`→`medium`→`high`→`xhigh`(→`max` on Claude; the adapter names
-  the levels it supports); once exhausted, bump the **model** one tier and reset effort to `high`. Re-run and
-  **re-score**.
-- **Continue vs restart:** coherent partial edits → **resume the session** (keeps its context and the files it
-  already touched). Broken or dirty worktree → **reset first**
-  (`git -C <worktree> reset --hard && git clean -fd`) and run fresh at the higher notch. Don't stack error on
-  error.
-- **Stop:** at **score ≥9** (ready for the owner's gate), OR when **exhausted** (strongest model at max effort
-  still below the bar) → `BLOCKED` with evidence. Announce each notch; with autonomy, escalate to the ceiling
-  yourself rather than asking at every step.
-
-## Reading escalation as a routing signal
-
-A task that routinely needs two or more notches above what the table assigned is telling you the table is wrong
-for that commit type. Report which
-entry mis-sized it in the Structured Return, so the next edit to `routing.json` is grounded in a real run rather
-than a guess.
-
-The reverse also matters and is easier to miss: a tier that never escalates may be over-provisioned. If `feat`
-work consistently lands at score ≥9 on the first try, try the tier below it before assuming the current one is
-load-bearing.
+Capture the actual process handle/PID on launch. Use its completion/exit status plus the provider's terminal event and final report. Cancel only that task's process through the host handle; do not infer task identity from a broad process-name match. Keep audit logs outside worktrees so authorized cleanup cannot erase evidence.

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -31,58 +31,24 @@ Read this skill when:
 Do NOT use when:
 
 - The user is asking a runtime question (use logs / running app).
-- The intel is fresh (`.dw/intel/.last-refresh.json` is current and the user did not ask for a refresh).
+- Do not rebuild fresh intel unless requested; querying a fresh index remains appropriate.
 - The project is greenfield with no source files yet — in that case, fall back to `.dw/rules/` seeded by `/dw-new-project`.
 
 ## Files in `.dw/intel/`
 
-The intel directory is the contract. Every file is machine-parseable and references real file paths.
-
-| File | Purpose | Format |
-|------|---------|--------|
-| `stack.json` | Languages, frameworks, build/test tooling, package manager | JSON |
-| `files.json` | File graph: per-file imports/exports/type | JSON |
-| `apis.json` | API surface: routes, methods, params, source file | JSON |
-| `deps.json` | Dependencies: version, type, used_by, invocation | JSON |
-| `bugfixes.json` | Historical bugfix index aggregated from `.dw/bugfixes/*/SUMMARY.md` (slug, date, modules touched, related concerns, by_module map). Optional — present only if `.dw/bugfixes/` is non-empty. | JSON |
-| `arch.md` | Human-readable architecture overview + key components + data flow | Markdown |
-| `codemaps/*.md` | Token-lean architecture maps for architecture/backend/frontend/data/dependencies. Optional but recommended for large repos. | Markdown |
-| `.last-refresh.json` | Timestamps + content hashes for incremental detection (now includes `bugfixes_indexed` count) | JSON |
-
-Schemas are documented in `references/intel-format.md`.
+For files in `.dw/intel/`, read `references/files-in-dw-intel-detail.md`. Load only when this part of the task applies.
 
 ## Agents
 
-| Agent | Responsibility | Spawn from |
-|-------|----------------|------------|
-| `agents/intel-updater.md` | Reads source files, writes structured intel to `.dw/intel/`. Supports `full` or `partial --files <paths>` updates. | `/dw-intel --build` |
-
-This skill ships ONE agent — `intel-updater` — which produces machine-readable JSON for `/dw-intel` queries. Human-readable architecture analysis (per-module conventions, anti-patterns, code smells) lives in `.dw/rules/` and is generated by `/dw-analyze-project`. The two are complementary: `.dw/intel/` answers "what's in this codebase right now?" and `.dw/rules/` answers "how should we write code here?".
+For agents, read `references/agents-detail.md`. Load only when this part of the task applies.
 
 ## How to Compose (the typical flow)
 
-1. **`/dw-intel --build`** is invoked.
-2. The command spawns `intel-updater` with `focus: full` (first run) or `focus: partial --files <paths>` (incremental).
-3. The agent reads source files using iterative retrieval: broad search, relevance evaluation, refined search, then final read set. Use Glob/Read/Grep; no Bash file listing for cross-platform safety.
-4. The agent writes the intel files (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`) plus token-lean codemaps in `.dw/intel/codemaps/` when enough structure exists.
-5. If `.dw/bugfixes/` exists and contains at least one `SUMMARY.md`, the agent additionally scans every SUMMARY frontmatter + Files Touched section and writes `bugfixes.json`. SUMMARY files with invalid frontmatter are logged and skipped.
-6. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run, including a `bugfixes_indexed` count.
-7. `/dw-intel --build` reports completion and invites the user to query via `/dw-intel "<question>"`.
-
-For human-readable analysis (architecture overview, module conventions, anti-patterns), run `/dw-analyze-project` after `/dw-intel --build` — it reads `.dw/intel/` as input and produces `.dw/rules/`.
+For how to compose (the typical flow), read `references/how-to-compose-the-typical-flow-detail.md`. Load only when this part of the task applies.
 
 ## How `/dw-intel` Reads This
 
-`/dw-intel "auth flow"` does:
-
-1. Check `.dw/intel/.last-refresh.json` — is the index fresh (within last 7 days)? If stale, suggest re-running `/dw-intel --build`.
-2. Search `apis.json` for matching paths/descriptions.
-3. Search `files.json` for matching exports.
-4. Search `arch.md` (full-text) for the keyword.
-5. Cross-reference with `deps.json` if the query is about a library.
-6. Return a structured answer with file paths cited, each tagged with a `relevance` (0–1, or high/medium/low) and a one-line reason — so the calling command reads the high-relevance files first and skips the rest, instead of loading the whole result set. Ordering by relevance is what keeps intel queries token-lean.
-
-If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded by `/dw-new-project` or `/dw-analyze-project`) and direct grep over the codebase.
+For how `/dw-intel` reads this, read `references/how-dw-intel-reads-this-detail.md`. Load only when this part of the task applies.
 
 ## Rules
 

package/scaffold/skills/dw-codebase-intel/agents/intel-updater.md

@@ -15,7 +15,7 @@ Skipping this causes hallucinated context and broken output.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 1. List available skills (subdirectories)
-2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+2. Read only the matching skill entrypoint; discovery metadata is enough to select it
 3. Load specific reference files as needed during analysis
 4. Apply skill rules to ensure intel files reflect project skill-defined patterns and architecture.
 

package/scaffold/skills/dw-codebase-intel/references/agents-detail.md

@@ -0,0 +1,7 @@
+## Agents
+
+| Agent | Responsibility | Spawn from |
+|-------|----------------|------------|
+| `../agents/intel-updater.md` | Reads source files, writes structured intel to `.dw/intel/`. Supports `full` or `partial --files <paths>` updates. | `/dw-intel --build` |
+
+This skill ships ONE agent — `intel-updater` — which produces machine-readable JSON for `/dw-intel` queries. Human-readable architecture analysis (per-module conventions, anti-patterns, code smells) lives in `.dw/rules/` and is generated by `/dw-analyze-project`. The two are complementary: `.dw/intel/` answers "what's in this codebase right now?" and `.dw/rules/` answers "how should we write code here?".

package/scaffold/skills/dw-codebase-intel/references/files-in-dw-intel-detail.md

@@ -0,0 +1,16 @@
+## Files in `.dw/intel/`
+
+The intel directory is the contract. Every file is machine-parseable and references real file paths.
+
+| File | Purpose | Format |
+|------|---------|--------|
+| `stack.json` | Languages, frameworks, build/test tooling, package manager | JSON |
+| `files.json` | File graph: per-file imports/exports/type | JSON |
+| `apis.json` | API surface: routes, methods, params, source file | JSON |
+| `deps.json` | Dependencies: version, type, used_by, invocation | JSON |
+| `bugfixes.json` | Historical bugfix index aggregated from `.dw/bugfixes/*/SUMMARY.md` (slug, date, modules touched, related concerns, by_module map). Optional — present only if `.dw/bugfixes/` is non-empty. | JSON |
+| `arch.md` | Human-readable architecture overview + key components + data flow | Markdown |
+| `codemaps/*.md` | Token-lean architecture maps for architecture/backend/frontend/data/dependencies. Optional but recommended for large repos. | Markdown |
+| `.last-refresh.json` | Timestamps + content hashes for incremental detection (now includes `bugfixes_indexed` count) | JSON |
+
+Schemas are documented in `intel-format.md`.

package/scaffold/skills/dw-codebase-intel/references/how-dw-intel-reads-this-detail.md

@@ -0,0 +1,12 @@
+## How `/dw-intel` Reads This
+
+`/dw-intel "auth flow"` does:
+
+1. Check `.dw/intel/.last-refresh.json` — is the index fresh (within last 7 days)? If stale, suggest re-running `/dw-intel --build`.
+2. Search `apis.json` for matching paths/descriptions.
+3. Search `files.json` for matching exports.
+4. Search `arch.md` (full-text) for the keyword.
+5. Cross-reference with `deps.json` if the query is about a library.
+6. Return a structured answer with file paths cited, each tagged with a `relevance` (0–1, or high/medium/low) and a one-line reason — so the calling command reads the high-relevance files first and skips the rest, instead of loading the whole result set. Ordering by relevance is what keeps intel queries token-lean.
+
+If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded by `/dw-new-project` or `/dw-analyze-project`) and direct grep over the codebase.

package/scaffold/skills/dw-codebase-intel/references/how-to-compose-the-typical-flow-detail.md

@@ -0,0 +1,11 @@
+## How to Compose (the typical flow)
+
+1. **`/dw-intel --build`** is invoked.
+2. The command spawns `intel-updater` with `focus: full` (first run) or `focus: partial --files <paths>` (incremental).
+3. The agent reads source files using iterative retrieval: broad search, relevance evaluation, refined search, then final read set. Use Glob/Read/Grep; no Bash file listing for cross-platform safety.
+4. The agent writes the intel files (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`) plus token-lean codemaps in `.dw/intel/codemaps/` when enough structure exists.
+5. If `.dw/bugfixes/` exists and contains at least one `SUMMARY.md`, the agent additionally scans every SUMMARY frontmatter + Files Touched section and writes `bugfixes.json`. SUMMARY files with invalid frontmatter are logged and skipped.
+6. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run, including a `bugfixes_indexed` count.
+7. `/dw-intel --build` reports completion and invites the user to query via `/dw-intel "<question>"`.
+
+For human-readable analysis (architecture overview, module conventions, anti-patterns), run `/dw-analyze-project` after `/dw-intel --build` — it reads `.dw/intel/` as input and produces `.dw/rules/`.

package/scaffold/skills/dw-council/SKILL.md

@@ -74,19 +74,8 @@ Render as:
 
 ## Phase 2: Tensions and Rebuttals
 
-Read the openings and identify 2-4 **genuine tensions** (Side A, Side B, meaningful stakes — not cosmetic disagreements).
+For phase 2: tensions and rebuttals, read `references/phase-2-tensions-and-rebuttals-detail.md`. Load only when this part of the task applies.
 
-For each tension, re-dispatch the two opposing advisors (can be parallel within a tension, sequential across tensions) with this prompt:
-
-```
-Steel-man [opponent]'s position in 1-2 sentences, then deliver your rebuttal
-in 1 paragraph. State whether you concede, partially concede, or hold firm,
-and why. Reference your priorities from agents/<your-id>.md.
-```
-
-Record as:
-
-```markdown
 ## Core Tensions
 
 | Tension | Side A (Advisor) | Side B (Advisor) | Facilitator Note |
@@ -159,11 +148,7 @@ Record as:
 
 ## Integration With Other dw-* Commands
 
-- **`/dw-brainstorm --council`** (opt-in): invokes the council after the normal brainstorm to stress-test the top 2-3 options before recommending
-- **`/dw-plan techspec --council`** (opt-in): invokes the council on the primary architectural decision of the techspec before finalizing
-- **Standalone** `/dw-council "<dilemma>"` (if registered as a command — currently this is a bundled skill invoked by the two above; it can be promoted to a command in a future release if direct usage becomes common)
-
-The `--council` flag is **additive**: omitting it produces the normal brainstorm/techspec flow. Including it adds a debate section to the output.
+For integration with other dw-* commands, read `references/integration-with-other-dw-commands-detail.md`. Load only when this part of the task applies.
 
 ## Inspired by
 

package/scaffold/skills/dw-council/references/integration-with-other-dw-commands-detail.md

@@ -0,0 +1,7 @@
+## Integration With Other dw-* Commands
+
+- **`/dw-brainstorm --council`** (opt-in): invokes the council after the normal brainstorm to stress-test the top 2-3 options before recommending
+- **`/dw-plan techspec --council`** (opt-in): invokes the council on the primary architectural decision of the techspec before finalizing
+- **Standalone** `/dw-council "<dilemma>"` (if registered as a command — currently this is a bundled skill invoked by the two above; it can be promoted to a command in a future release if direct usage becomes common)
+
+The `--council` flag is **additive**: omitting it produces the normal brainstorm/techspec flow. Including it adds a debate section to the output.

package/scaffold/skills/dw-council/references/phase-2-tensions-and-rebuttals-detail.md

@@ -0,0 +1,15 @@
+## Phase 2: Tensions and Rebuttals
+
+Read the openings and identify 2-4 **genuine tensions** (Side A, Side B, meaningful stakes — not cosmetic disagreements).
+
+For each tension, re-dispatch the two opposing advisors (can be parallel within a tension, sequential across tensions) with this prompt:
+
+```
+Steel-man [opponent]'s position in 1-2 sentences, then deliver your rebuttal
+in 1 paragraph. State whether you concede, partially concede, or hold firm,
+and why. Reference your priorities from agents/<your-id>.md.
+```
+
+Record as:
+
+```markdown

package/scaffold/skills/dw-domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw-domain-modeling
-description: "Internal domain-vocabulary protocol for the native Grill flow. Loaded by /dw-brainstorm (grill mode) and referenced by /dw-analyze-project to keep canonical vocabulary: challenge fuzzy or overloaded terms, propose precise canonical names, stress-test with concrete edge-case scenarios, cross-check terms against the code, and persist resolved terms safely and lazily into .dw/domain (glossary for a single context, context-map plus per-context files for many). Rare ADR policy. Pipeline-internal, never exported, never implements code."
+description: Internal domain-vocabulary protocol for the native Grill flow.
 allowed-tools:
   - Read
   - Grep

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -26,7 +26,7 @@ Read this skill when:
 
 - `/dw-execute-phase` is invoked to run a batch of tasks in parallel waves.
 - `/dw-plan-checker` is invoked to verify a `tasks.md` file will achieve its PRD goal before execution.
-- `/dw-run` is invoked (it spawns the executor agent for each wave).
+- `/dw-run` needs dependency or plan verification for approved tasks.
 - `/dw-autopilot` enters the execution stage (it gates on plan-checker before invoking the executor).
 
 Do NOT use when:
@@ -35,6 +35,8 @@ Do NOT use when:
 - The user is exploring/brainstorming, not executing (use `/dw-brainstorm`).
 - The plan hasn't been created yet (use `/dw-plan tasks` first).
 
+Read `.dw/references/execution-contract.md` for approved tool/model/agent assignments and durable state. Agent profiles below are available protocols, not mandatory additional dispatches.
+
 ## Agents
 
 | Agent | Responsibility | Spawn from |
@@ -44,40 +46,27 @@ Do NOT use when:
 
 ## How the Two Agents Compose
 
-The expected flow:
-
-1. `/dw-plan tasks` produces `.dw/spec/prd-<slug>/tasks.md` from PRD + TechSpec.
-2. **Plan-checker GATE** — `/dw-plan-checker .dw/spec/prd-<slug>/` spawns the plan-checker agent. The agent reads PRD/TechSpec/tasks.md and verifies tasks WILL achieve the goal. Returns one of: `PASS` (proceed), `REVISE` (issues found, planner re-runs), `BLOCK` (fundamental gap, abort).
-3. `/dw-execute-phase` spawns the executor agent ONLY if plan-checker returned `PASS`. The executor runs tasks in waves, commits atomically, handles deviations.
-4. `/dw-qa` runs after all waves complete to validate the implementation against PRD.
-
-`/dw-autopilot` orchestrates this entire flow with hard gates between stages.
+For how the two agents compose, read `references/how-the-two-agents-compose-detail.md`. Load only when this part of the task applies.
 
 ## Wave Concept
 
 Tasks in `tasks.md` are grouped into **waves** by their `Depends on:` frontmatter:
 
-- Wave 1: tasks with no dependencies → run in parallel
+- Wave 1: tasks with no dependencies → ready to run
 - Wave 2: tasks that depend on Wave 1 → run after Wave 1 commits land
 - Wave N: ...
 
-Within a wave, tasks run in parallel via subagent dispatch. Across waves, sequential.
+Within a wave, concurrency is optional and follows approved assignments. One writer per worktree, at most 3 workers; dependent tasks share the execution branch sequentially.
 
 The executor calculates waves automatically by topologically sorting task dependencies. See `references/wave-coordination.md`.
 
 ## Deviation Rules (during execution)
 
-Mid-task, the executor may discover the plan is incomplete or contradicted by reality. Three rules:
-
-1. **Auto-add missing critical functionality** — if a task says "create endpoint" but no validation is specified and the project's CLAUDE.md/rules require it, add the validation as part of the same task. Note in the task's commit message.
-2. **Surface ambiguity, don't guess** — if the plan says "use the existing service" and 3 services match, STOP, write a deviation entry to `.dw/spec/prd-<slug>/deviations.md`, and ask the user.
-3. **Block on architectural conflicts** — if the task as planned would violate a locked decision in CONTEXT.md / project rules, abort the task and surface the conflict for re-planning.
-
-Detail in `references/atomic-commits.md` (deviation entry format) and `references/plan-verification.md` (what plan-checker should catch BEFORE execution to prevent deviations).
+For deviation rules (during execution), read `references/deviation-rules-during-execution-detail.md`. Load only when this part of the task applies.
 
 ## Atomic Commit Protocol
 
-Every task ends with exactly one git commit:
+Formal tasks use scoped atomic commits, with approved subtask milestones when specified:
 
 ```
 feat(<scope>): <task title> (#<task-id>)
@@ -98,16 +87,7 @@ The commit message format is consistent across waves so `/dw-generate-pr` can bu
 
 ## De-Sloppify Pass (optional cleanup task)
 
-LLM implementers are thorough but leave slop — tests of framework/language behavior, defensive checks the type system already enforces, leftover `console.log`, over-handled impossible states. Constraining the implementer with "don't over-engineer" degrades its output unpredictably; a **separate cleanup pass in a fresh context** works better. Two focused agents beat one constrained agent.
-
-To request one, a task in `tasks.md` may carry `Cleanup After: <N>` in its frontmatter. The executor runs it as its own task (own commit) right after task N's wave lands, scoped to task N's diff:
-
-- Remove tests that assert language/framework behavior rather than business logic.
-- Remove type checks and guards the type system or a prior validation already guarantees.
-- Remove `console.log`/debug prints and commented-out code.
-- Keep every business-logic test and every real error path — when unsure, keep it.
-
-The cleanup task commits as `refactor(<scope>): de-slop <task N title>` and must leave the gate green (lint + tests + build) — it never changes behavior. Opt-in: no `Cleanup After:` means no cleanup task runs.
+For de-sloppify pass (optional cleanup task), read `references/de-sloppify-pass-optional-cleanup-task-detail.md`. Load only when this part of the task applies.
 
 ## Checkpoint Protocol
 
@@ -137,11 +117,11 @@ If the executor exhausts its context budget mid-phase OR the user signals stop:
 
 ## Rules
 
-- **No execution without plan-checker PASS.** `/dw-execute-phase` and `/dw-run` must call plan-checker first; if it returns REVISE or BLOCK, abort.
-- **One commit per task, no exceptions.** Even trivial tasks commit. This drives traceability and revert safety.
+- **No execution without plan-checker PASS.** `/dw-execute-phase` and `/dw-run` must call plan-checker first; repair internal REVISE findings; BLOCK only when a material decision or invalid dependency remains.
+- **Scoped atomic commits for formal tasks.** Follow approved subtask milestones when specified; direct small edits do not invoke this protocol. This drives traceability and revert safety.
 - **Deviations are recorded, not silenced.** Every adjustment beyond the plan goes in `deviations.md` with reason.
 - **Checkpoint > timeout.** When context budget is low, checkpoint cleanly rather than running tasks half-way.
-- **Wave order is topological, not user-defined.** The executor computes wave boundaries from `Depends on:` fields; users can't override.
+- **Wave order is topological, not user-defined.** The executor computes wave boundaries from `Depends on:` fields; concurrency limits queue ready tasks without inventing dependencies.
 
 ## Inspired by