@brunosps00/dev-workflow 2.1.0 → 2.3.0

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

@@ -264,11 +264,11 @@
     | Question | If YES -> |
     |----------|-----------|
     | Needs migration/schema change? | Redirect to PRD |
-    | Affects more than 5 files? | Redirect to PRD |
+    | Broader file scope? | Reassess organization and actual risk; no automatic stop |
     | Requires new endpoint? | Redirect to PRD |
     | Changes existing API contract? | Redirect to PRD |
     | Affects multiple projects? | Redirect to PRD |
-    | Estimate > 2 hours of implementation? | Redirect to PRD |
+    | Larger implementation estimate? | Reorganize/checkpoint within approved scope |
 
     **If excessive scope detected:**
     ```
@@ -300,45 +300,19 @@
     - With `--analysis`: Go to step 6
     - Without `--analysis`: Continue to step 5
 
-    ### 5.0. Safety Valve (MANDATORY before step 5)
+    ### 5.0. Safety Valve (before implementation)
 
-    <critical>
-    BEFORE drafting the numbered task list in step 5, sketch the inline steps you intend to write.
-    If that sketch reveals **more than 5 distinct numbered tasks**, OR **any cross-file dependency that means tasks must be executed in a specific order**, OR **a task that requires running database migration / refactor / new endpoint / API contract change**, then the bugfix scope was UNDERESTIMATED and you MUST escalate.
-    </critical>
-
-    **Why this exists:** the triage at step 0 catches scope problems from the symptom description. The checkpoint at 4.1 catches them after root cause analysis. This valve catches the remaining case — when the fix itself, once laid out, reveals more complexity than triage and root cause analysis predicted. There is NO bypass flag. Escalation is the correct outcome.
-
-    **Escalation procedure:**
-
-    1. Allocate `NNN` for `.dw/bugfixes/NNN-<slug>/`. Write `TASK.md` with the triage, clarifications, root cause, and the would-be plan.
-    2. Create `.dw/spec/prd-bugfix-<slug>/` and write `prd.md` there (use `.dw/templates/bugfix-template.md`). This is the path `/dw-plan` expects.
-    3. Write `.dw/bugfixes/NNN-<slug>/escalated.md` with: `Escalated to /dw-plan on <YYYY-MM-DD> — reason: <which valve criterion tripped> → see .dw/spec/prd-bugfix-<slug>/`.
-    4. Report to the user:
-
-    ```
-    ## Scope larger than a bugfix
-
-    Listing the fix produced [N] tasks / [cross-file deps] / [forbidden change type].
-    Per the safety valve, this is no longer a surgical bugfix.
-
-    Bugfix index preserved at `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}`.
-    PRD created at `.dw/spec/prd-bugfix-<slug>/prd.md`.
-
-    Next — pick one:
-      - Manual chain: `/dw-plan techspec prd-bugfix-<slug>` → `/dw-plan tasks prd-bugfix-<slug>` → `/dw-run` → `/dw-qa` → `/dw-review` → `/dw-commit` → `/dw-generate-pr`.
-      - Hand off to autopilot: `/dw-autopilot --from-prd prd-bugfix-<slug>` — runs the planning phase from the existing PRD, stops after Tasks, then a later autopilot invocation resumes through `/dw-goal`.
-    ```
+    Inspect the proposed fix for material scope or architecture changes. Task count, file count, ordering dependencies and larger estimates are signals to organize work, not automatic blockers. Refactoring required to fix approved behavior can remain in scope. A new product contract, sensitive migration or unresolved architecture decision needs a concrete proposal before dependent implementation.
 
-    5. Stop this command. Do not proceed to step 5. The user (or autopilot) invokes `/dw-plan` or `/dw-autopilot --from-prd` next.
+    When a structured plan is needed, preserve `.dw/bugfixes/NNN-<slug>/TASK.md`, create `.dw/spec/prd-bugfix-<slug>/prd.md` using the bugfix template, and record the cross-reference in `escalated.md`. Continue through `/dw-plan` or `/dw-autopilot --from-prd prd-bugfix-<slug>` according to existing user intent. The task breakdown proposes executor/model/agents; after approval continue in the same invocation. Do not re-ask permission to organize an already authorized fix. An analysis-only request still ends with its report.
 
-    **If the valve does NOT trip:** Continue to step 5.
+    If no material new decision or structured plan is needed, continue to step 5.
 
     ### 5. Propose Numbered Tasks (Required)
 
     <critical>
     List ALL necessary tasks, numbered sequentially.
-    Wait for approval before executing.
+    Use existing approval for the same task scope; ask only for new material decisions before executing.
     </critical>
 
     **Format:**
@@ -425,8 +399,8 @@
 
     Option B (hand off to autopilot):
     1. Run: `/dw-autopilot --from-prd prd-bugfix-<slug>`
-    2. Autopilot runs PRD approval, TechSpec, and Tasks, then stops with `status: plan_complete`.
-    3. A later autopilot invocation resumes via `/dw-goal --from-autopilot prd-bugfix-<slug>` for Run, full Review, QA/Fix, and post-QA full Review before commit/PR.
+    2. Autopilot runs PRD approval, TechSpec, and Tasks, records `status: plan_complete` and continues after task/execution approval.
+    3. The same invocation continues via `/dw-goal --from-autopilot prd-bugfix-<slug>` for Run, full Review, QA/Fix, and post-QA full Review before commit/PR.
 
     The bugfix index entry stays queryable via `/dw-intel "bugfix history in <module>"`. Downstream `/dw-review --bugfix <slug>` and `/dw-qa --bugfix <slug>` still target `.dw/bugfixes/NNN-<slug>/` when you want a focused review of just the eventual surgical patch.
     ```

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

@@ -1,51 +1,35 @@
 <system_instructions>
-You are the **Claude runner adapter**. You fire `claude -p` (headless) inside a **dedicated git worktree** to
-implement a prepared prompt/spec, capture the whole run to a durable audit log, keep a **resumable per-task
-session**, score the delivery 0–10, escalate on failure, and **STOP for the gate**.
+# Claude runner
 
-<critical>Load and follow the `dw-cli-run` skill — it holds the full CLI-agnostic protocol (hard worktree rule, pre-flight, vehicle choice, dual 0–10 evaluation, graded escalation, telemetry, kill/detection discipline, Structured Return). This file only supplies the **Claude adapter table**; substitute it into that protocol.</critical>
-<critical>NEVER run in the repo's main checkout — only a dedicated worktree off main. ABORT (`BLOCKED`) otherwise.</critical>
-<critical>NEVER merge or push. Merge is the owner's decision after the gate.</critical>
+Use `dw-cli-run` for the shared protocol. Consume the approved task assignment and return to the parent for review, corrections and continuation. Standalone invocation accepts an explicitly prepared prompt without requiring a PRD. WRITE requires a dedicated secondary worktree; READ-ONLY follows the skill’s enforced read-only rules. The worker never merges or pushes.
 
-## Claude adapter table (substitute into `dw-cli-run`)
+Run the examples with cwd set to `<WORKTREE>` by the process launcher. Substitute arguments safely, preferably as a subprocess argument array. Placeholder permission arguments mean the existing approved profile, not a bypass flag. Preserve effective permissions on resume; initial and resume commands may support different flags. Validate both help outputs before dispatch.
 
-| Slot | Claude value |
+## Claude adapter table
+
+| Slot | Value |
 |---|---|
-| `DISPATCH` | `UUID=$(cat /proc/sys/kernel/random/uuid); cd <WORKTREE> && claude -p --session-id "$UUID" --model <MODEL> --effort <EFFORT> --output-format stream-json --include-partial-messages --verbose --dangerously-skip-permissions "$(cat <PROMPT>)" </dev/null > <AUDIT>/<slug>.log 2>&1` |
-| `STREAM` | `--output-format stream-json --include-partial-messages --verbose` (`--verbose` is **required** with `stream-json` in `-p` mode) |
-| `MODEL` | `--model <MODEL>` — `opus` · `sonnet` · `haiku` · `fable`, or a full id (`claude-opus-5`) |
-| `EFFORT` | `--effort <EFFORT>` — `low` · `medium` · `high` · `xhigh` · `max` |
-| `AUTO` | `--dangerously-skip-permissions` (headless auto-approve for a **WRITE** dispatch; justified because the worktree is isolated) |
-| `AUTO_READONLY` | `--permission-mode plan` (optionally `--allowedTools <list>`). Never combine with `AUTO`. |
-| `NO_MCP` | `--strict-mcp-config` with no `--mcp-config` → boots zero MCP servers |
-| `RESUME <id>` | `cd <WORKTREE> && claude --resume "$UUID" -p --effort <EFFORT> --output-format stream-json --include-partial-messages --verbose --dangerously-skip-permissions "$(cat <FOLLOWUP_PROMPT>)" </dev/null >> <AUDIT>/<slug>.log 2>&1` |
-| `RESUME_LAST` | `claude -c -p …` (continue the most recent conversation in this cwd) |
-| `SESSION_ID` | **FIXED by you** — you pass `--session-id "$UUID"` on the first run, so the id is known up front. Generate it (`cat /proc/sys/kernel/random/uuid` or `uuidgen`) and write it to `<AUDIT>/<slug>.session` BEFORE/at dispatch. No stream-scraping needed — Claude is the easy case. |
-| `DONE_SIGNAL` | the final `{"type":"result"}` message in the stream (carries `subtype`, `usage`, `total_cost_usd`, `num_turns`) |
-| `USAGE` | the `result` message `usage` → `input_tokens` / `cache_read_input_tokens` / `cache_creation_input_tokens` / `output_tokens`, plus `total_cost_usd`. Extract: `grep -oE '"usage":\{[^}]*\}' <AUDIT>/<slug>.log \| tail -1` |
-
-**Model + effort:** `--model` selects the tier (`opus` · `sonnet` · `haiku`, or a full id). `--effort` selects the
-reasoning budget: `low` · `medium` · `high` · `xhigh` · `max` (supported by the Claude CLI ≥ 2.1.206). Escalate per
-`dw-cli-run`: raise `--effort` first (low→medium→high→xhigh→max), then bump `--model` one tier and reset effort.
-Start one notch below the ceiling.
-
-## Session resume (the heart)
-Because you pass `--session-id "$UUID"`, the id is **fixed and known** at dispatch — write it to
-`<AUDIT>/<slug>.session` (durable, outside the worktree → survives `git worktree remove`). To come back with the
-**same context**, read the id and re-run `RESUME <id>` (`claude --resume "$UUID" -p …`) with the follow-up prompt
-— Claude reloads the same conversation (its reasoning + files already touched). Fallback if the sidecar is gone:
-`claude -c -p …` from the same worktree (continues the most recent conversation there).
-
-## Input Variables
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `<WORKTREE>` | dedicated git worktree (off main) | `~/code/vizzita-billing-s10` |
-| `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
-| `<slug>` | task key for audit/session files | `prd-billing-integrador` |
-| `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |
-| `<MODEL>` | Claude tier or full model id | `opus` / `sonnet` / `haiku` |
-| `<EFFORT>` | reasoning budget (Claude CLI ≥ 2.1.206) | `low` / `medium` / `high` / `xhigh` / `max` |
-
-Return via the `dw-cli-run` **Structured Return** (Status/Score/Scope/Evidence/Artifacts/Decisions/Risks/Telemetry/
-Next Step), including the fixed `session-id` (UUID), its sidecar path, and the exact `RESUME` command to continue.
+| `DISPATCH` | `claude -p --session-id "<SESSION_ID>" --model "<MODEL>" --effort "<EFFORT>" <PERMISSIONS> --output-format stream-json --include-partial-messages --verbose < "<PROMPT>" > "<AUDIT>/<slug>.log" 2>&1` |
+| `STREAM` | `--output-format stream-json --verbose` |
+| `MODEL` | `--model "<MODEL>"` |
+| `EFFORT` | `--effort "<EFFORT>"` |
+| `AUTO` | <PERMISSIONS> — approved non-interactive profile; retain existing configuration |
+| `AUTO_READONLY` | `--permission-mode plan --tools "Read,Grep,Glob" --strict-mcp-config` |
+| `NO_MCP` | Select only capabilities needed, if supported; preserve user configuration otherwise |
+| `RESUME <id>` | `claude --resume "<SESSION_ID>" -p --model "<MODEL>" --effort "<EFFORT>" <RESUME_PERMISSIONS> --output-format stream-json --include-partial-messages --verbose < "<FOLLOWUP_PROMPT>" >> "<AUDIT>/<slug>.log" 2>&1` |
+| `SESSION_ID` | UUID generated before dispatch (`node -e "console.log(require('node:crypto').randomUUID())"`) → `<AUDIT>/<slug>.session` |
+| `DONE_SIGNAL` | `result` with its subtype |
+| `USAGE` | `result.usage` and reported `total_cost_usd` |
+
+Create/reuse through `/dw-worktree create <slug>`; after authorized integration, `/dw-worktree merge <slug>` owns merge and safe cleanup. Workers return to the parent and never invoke integration themselves.
+
+## Model selection and resume
+
+Resolve concrete model/effort at task breakdown using `.dw/config/routing.json`, current provider metadata and the installed tool. Do not embed a fixed strongest-to-lightest model list in this adapter. Supported effort values depend on model/version; low, medium, high, xhigh and max are candidates only when supported. No mandatory escalation to the ceiling.
+
+Store task, provider, worktree, approved assignment, session ID and audit path before handoff. If the session sidecar is absent, recover the exact task session from its log; never blindly continue the latest cwd session. If identity cannot be proven, start a new session from saved state and the actual diff, preserving partial work. Provider sessions are not portable across CLIs.
+
+Return the `dw-cli-run` Structured Return with evidence and the exact supported resume command. The parent continues the approved plan; merge/push/publication require applicable authorization.
+
+Capability inspection: Claude Code 2.1.265.
 </system_instructions>

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

@@ -1,51 +1,36 @@
 <system_instructions>
-You are the **Codex runner adapter**. You fire `codex exec` inside a **dedicated git worktree** to implement a
-prepared prompt/spec, capture the whole run to a durable audit log, keep a **resumable per-task session**, score
-the delivery 0–10, escalate on failure, and **STOP for the gate**.
+# Codex runner
 
-<critical>Load and follow the `dw-cli-run` skill — it holds the full CLI-agnostic protocol (hard worktree rule, pre-flight, vehicle choice, dual 0–10 evaluation, graded escalation, telemetry, kill/detection discipline, Structured Return). This file only supplies the **Codex adapter table**; substitute it into that protocol.</critical>
-<critical>NEVER run in the repo's main checkout — only a dedicated worktree off main. ABORT (`BLOCKED`) otherwise.</critical>
-<critical>NEVER merge or push. Merge is the owner's decision after the gate.</critical>
+Use `dw-cli-run` for the shared protocol. Consume the approved task assignment and return to the parent for review, corrections and continuation. Standalone invocation accepts an explicitly prepared prompt without requiring a PRD. WRITE requires a dedicated secondary worktree; READ-ONLY follows the skill’s enforced read-only rules. The worker never merges or pushes.
 
-## Codex adapter table (substitute into `dw-cli-run`)
+Run the examples with cwd set to `<WORKTREE>` by the process launcher. Substitute arguments safely, preferably as a subprocess argument array. Placeholder permission arguments mean the existing approved profile, not a bypass flag. Preserve effective permissions on resume; initial and resume commands may support different flags. Validate both help outputs before dispatch.
 
-| Slot | Codex value |
+## Codex adapter table
+
+| Slot | Value |
 |---|---|
-| `DISPATCH` | `cd <WORKTREE> && codex exec --skip-git-repo-check -m <MODEL> --config model_reasoning_effort="<EFFORT>" --dangerously-bypass-approvals-and-sandbox --json -o <AUDIT>/<slug>.last.md "$(cat <PROMPT>)" </dev/null > <AUDIT>/<slug>.log 2>&1` |
-| `STREAM` | `--json` (JSONL events) |
-| `MODEL` | `-m <MODEL>` — `gpt-5.5` · `gpt-5.3-codex` · `gpt-5.4` · `gpt-5.3-codex-spark` · `gpt-5.4-mini` |
-| `EFFORT` | `--config model_reasoning_effort="<EFFORT>"` — `low` · `medium` · `high` · `xhigh` |
-| `AUTO` | `--dangerously-bypass-approvals-and-sandbox` (no sandbox + no approvals = full access **with network** so the CLI can run the gate; **WRITE** dispatch only, justified because the worktree is isolated). Edits without a network gate: `--sandbox workspace-write --full-auto`. |
-| `AUTO_READONLY` | `--sandbox read-only` (drop `--full-auto`). Never combine with `AUTO`. |
-| `NO_MCP` | `-c mcp_servers='{}'` → boots zero MCP servers, keeps auth and the rest of `config.toml`. Blunter alternative: `--ignore-user-config` (also drops model defaults — then `MODEL` + `EFFORT` are mandatory). |
-| `RESUME <id>` | `cd <WORKTREE> && codex exec resume <THREAD_ID> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox --json "$(cat <FOLLOWUP_PROMPT>)" </dev/null >> <AUDIT>/<slug>.log 2>&1` |
-| `RESUME_LAST` | `codex exec resume --last …` (filters by cwd = the worktree) |
-| `SESSION_ID` | Codex has **no flag to fix** the id → **capture** the thread id from the first run's stream: `grep -oE '"thread_id":"[^"]*"' <AUDIT>/<slug>.log \| head -1` (from the `thread.started` event) → write to `<AUDIT>/<slug>.session`. |
-| `DONE_SIGNAL` | `{"type":"turn.completed"}` in the stream log |
-| `USAGE` | `turn.completed.usage` → `input_tokens` / `cached_input_tokens` / `output_tokens` / `reasoning_output_tokens`. Extract: `grep -oE '"usage":\{[^}]*\}' <AUDIT>/<slug>.log \| tail -1` |
-
-**Models (strong→light):** `gpt-5.5` · `gpt-5.3-codex` · `gpt-5.4` · `gpt-5.3-codex-spark` · `gpt-5.4-mini`.
-**Effort:** `low` · `medium` · `high` · `xhigh`. Start one notch below the ceiling; escalate per `dw-cli-run`.
-
-**Detailed report (recommended):** add `--output-schema <schema.json>` requiring a rich report
-(`summary`/`tasks`/`filesChanged`/`gate`/`fenceViolations`/`uncommitted`/`blockers`/`nextSteps`) — don't accept an
-opaque "ok". The `codex-prompt.md` should also ask for a STOP-with-detailed-report so schema + prompt reinforce.
-
-## Session resume (the heart)
-First run: capture the `thread_id` to `<AUDIT>/<slug>.session` (durable, outside the worktree → survives
-`git worktree remove`). To come back with the **same context**, read the id and re-run `RESUME <id>` with the
-follow-up prompt — Codex continues the same thread (reasoning + files already touched). Fallback if the sidecar is
-gone: `codex exec resume --last` from the same worktree.
-
-## Input Variables
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `<WORKTREE>` | dedicated git worktree (off main) | `~/code/vizzita-billing-s10` |
-| `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
-| `<slug>` | task key for audit/session files | `prd-billing-integrador` |
-| `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |
-
-Return via the `dw-cli-run` **Structured Return** (Status/Score/Scope/Evidence/Artifacts/Decisions/Risks/Telemetry/
-Next Step), including the captured `thread_id`, its sidecar path, and the exact `RESUME` command to continue.
-Tested: codex-cli 0.141.0.
+| `DISPATCH` | `codex exec -m "<MODEL>" -c 'model_reasoning_effort="<EFFORT>"' <PERMISSIONS> --json -o "<AUDIT>/<slug>.last.md" - < "<PROMPT>" > "<AUDIT>/<slug>.log" 2>&1` |
+| `STREAM` | `--json` |
+| `MODEL` | `-m "<MODEL>"` |
+| `EFFORT` | `-c 'model_reasoning_effort="<EFFORT>"'` |
+| `AUTO` | <PERMISSIONS> — approved non-interactive profile; retain existing configuration |
+| `AUTO_READONLY` | `--sandbox read-only` |
+| `NO_MCP` | Select only capabilities needed, if supported; preserve user configuration otherwise |
+| `RESUME <id>` | `codex exec resume "<SESSION_ID>" -m "<MODEL>" -c 'model_reasoning_effort="<EFFORT>"' <RESUME_PERMISSIONS> --json - < "<FOLLOWUP_PROMPT>" >> "<AUDIT>/<slug>.log" 2>&1` |
+| `SESSION_ID` | `thread.started.thread_id` → `<AUDIT>/<slug>.session` |
+| `DONE_SIGNAL` | `turn.completed` |
+| `USAGE` | `turn.completed.usage` |
+
+Create/reuse through `/dw-worktree create <slug>`; after authorized integration, `/dw-worktree merge <slug>` owns merge and safe cleanup. Workers return to the parent and never invoke integration themselves.
+
+## Model selection and resume
+
+Resolve concrete model/effort at task breakdown using `.dw/config/routing.json`, current provider metadata and the installed tool. Do not embed a fixed strongest-to-lightest model list in this adapter. Supported effort values depend on model/version; low, medium, high, xhigh and max are candidates only when supported. No mandatory escalation to the ceiling.
+
+Store task, provider, worktree, approved assignment, session ID and audit path before handoff. If the session sidecar is absent, recover the exact task session from its log; never blindly continue the latest cwd session. If identity cannot be proven, start a new session from saved state and the actual diff, preserving partial work. Provider sessions are not portable across CLIs.
+
+Return the `dw-cli-run` Structured Return with evidence and the exact supported resume command. The parent continues the approved plan; merge/push/publication require applicable authorization.
+
+Capability inspection: codex-cli 0.153.4.
+The current `exec resume` help lacks `--sandbox`; do not copy initial flags blindly or add bypass to compensate. Use an equivalent supported approved profile/config, otherwise block that resume mode and reconstruct a new restricted session. TOML `mcp_servers='{}'` alone is not proof inherited MCP entries were disabled.
 </system_instructions>

package/scaffold/en/commands/dw-context-budget.md

@@ -7,23 +7,15 @@ You are the context budget auditor for dev-workflow.
 - Use during `/dw-analyze-project` follow-up when the harness looks bloated.
 
 ## Process
-1. Count approximate tokens for `CLAUDE.md`, `AGENTS.md`, `.dw/commands/*.md`, `.agents/skills/*/SKILL.md`, `.agents/agents/*.md`, `.claude/agents/*.md`, `.opencode/agent/*.md`, `.github/agents/*.agent.md`, `.dw/subtasks/pending/*/HANDOFF.md`, and `.claude/settings.json`.
-2. Estimate prose tokens as `words * 1.3`; estimate JSON/tool schemas as `chars / 4`.
-3. Flag:
-   - command files over 20KB,
-   - skill `SKILL.md` files over 12KB,
-   - agent files over 8KB,
-   - missing agent `output_budget_words` in `.dw/agent-registry.json` or scaffold registry,
-   - pending handoffs averaging over 1200 words,
-   - Copilot agents above 30k chars,
-   - more than 10 MCP servers,
-   - duplicate agent/skill names across platform folders,
-   - Claude/OpenCode agent files with provider-incompatible tool or permission fields.
-4. Recommend the top 5 savings with concrete paths.
+1. Separate three categories: permanent instructions for the active host; discovery metadata (skill/command names and descriptions); and on-demand command bodies, skill bodies, references and handoffs. Disk inventory is not simultaneous context consumption. Count only the active host's surfaces; platform copies alone are not duplicated live context.
+2. Label prose estimates (`words * 1.3`, schema `chars / 4`) as estimates, not measured tokens. Report each category separately and observed loads only when telemetry exists.
+3. Check project budgets: installed managed instruction block ≤6000 bytes per locale; skill entrypoints ≤8000 bytes; descriptions ≤250 characters. Commands over 20KB and agent files over 8KB are review signals, not evidence they were loaded. Review overlapping triggers, unconditional reference loads, broken links and incompatible provider metadata.
+4. In this repository `npm run validate` enforces entrypoint/description budgets and routed references through `lib/instruction-health.js`. In a consumer project inspect installed files; do not require the package source to exist there.
+5. Report the top concrete savings. Audit `.dw/config/routing.json` candidates against current provider information, noting stale choices without overwriting owner configuration.
 
 ## Part B — Runtime spend (actual token cost)
 
-Static overhead (above) is what the harness *loads*; this part is what sessions actually *cost*. Report from `.dw/metrics/costs.jsonl` (appended by the `session-cost` SessionEnd hook — one row per session with per-model token usage + estimated USD):
+The inventory above estimates potential context; this part reports observed session usage. Report from `.dw/metrics/costs.jsonl` (appended by the `session-cost` SessionEnd hook — one row per session with per-model token usage + estimated USD):
 
 1. Read `.dw/metrics/costs.jsonl` if present. If absent, note "no runtime cost data yet (hook disabled or no session has ended)" and skip this part — never fail.
 2. Dedupe by `session_id` (latest row per session wins).

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

@@ -1,47 +1,35 @@
 <system_instructions>
-You are the **Copilot runner adapter**. You fire the GitHub Copilot CLI (`copilot -p`) inside a **dedicated git
-worktree** to implement a prepared prompt/spec, capture the whole run to a durable audit log, keep a **resumable
-per-task session**, score the delivery 0–10, escalate on failure, and **STOP for the gate**.
+# Copilot runner
 
-<critical>Load and follow the `dw-cli-run` skill — it holds the full CLI-agnostic protocol (hard worktree rule, pre-flight, vehicle choice, dual 0–10 evaluation, graded escalation, telemetry, kill/detection discipline, Structured Return). This file only supplies the **Copilot adapter table**; substitute it into that protocol.</critical>
-<critical>NEVER run in the repo's main checkout — only a dedicated worktree off main. ABORT (`BLOCKED`) otherwise.</critical>
-<critical>NEVER merge or push. Merge is the owner's decision after the gate.</critical>
+Use `dw-cli-run` for the shared protocol. Consume the approved task assignment and return to the parent for review, corrections and continuation. Standalone invocation accepts an explicitly prepared prompt without requiring a PRD. WRITE requires a dedicated secondary worktree; READ-ONLY follows the skill’s enforced read-only rules. The worker never merges or pushes.
 
-## Copilot adapter table (substitute into `dw-cli-run`)
+Run the examples with cwd set to `<WORKTREE>` by the process launcher. Substitute arguments safely, preferably as a subprocess argument array. Placeholder permission arguments mean the existing approved profile, not a bypass flag. Preserve effective permissions on resume; initial and resume commands may support different flags. Validate both help outputs before dispatch.
 
-| Slot | Copilot value |
+## Copilot adapter table
+
+| Slot | Value |
 |---|---|
-| `DISPATCH` | `cd <WORKTREE> && copilot -p "$(cat <PROMPT>)" --allow-all --model <MODEL> --output-format json </dev/null > <AUDIT>/<slug>.log 2>&1` |
-| `STREAM` | `--output-format json` (JSONL records) |
-| `AUTO` | `--allow-all` (auto-approve all tool/command use; justified because the worktree is isolated). Read-only/analysis: drop it and let it prompt-deny, or scope with `--allow-tool`/`--deny-tool`. |
-| `RESUME <id>` | `cd <WORKTREE> && copilot --resume="<SESSION_ID>" -p "$(cat <FOLLOWUP_PROMPT>)" --allow-all --output-format json </dev/null >> <AUDIT>/<slug>.log 2>&1` (also: `--connect=<SESSION_ID>`) |
-| `RESUME_LAST` | `copilot --continue -p …` (continue the most recent session in this cwd) |
-| `SESSION_ID` | Copilot's `--resume`/`--session-id` **RESUME** an existing session (they don't fix a new one) → **capture** the id from the first run: scan the stream/log for the session id record, or read the newest dir under `~/.copilot/logs` / `~/.copilot/history-session-state`. Write it to `<AUDIT>/<slug>.session`. **Confirm the exact id field in the smoke test.** |
-| `DONE_SIGNAL` | the final JSON record of the stream (end-of-turn) |
-| `USAGE` | the final record's token usage (confirm the exact field names in the smoke test) |
-
-**Model:** `--model` selects the engine (e.g. `claude-sonnet-4.5`, `gpt-5`). Copilot has no numeric effort flag;
-map "escalation" to model tier. Start one tier below the ceiling; escalate per `dw-cli-run`.
-
-## Session resume (the heart)
-Copilot does not let you fix the id, so on the first run **capture** the session id (from the stream/log or
-`~/.copilot/logs`) and write it to `<AUDIT>/<slug>.session` (durable, outside the worktree → survives
-`git worktree remove`). To come back with the **same context**, read the id and re-run `RESUME <id>`
-(`copilot --resume="<id>" -p …` or `--connect=<id>`) with the follow-up prompt — Copilot reloads the same session.
-Fallback if the sidecar is gone: `copilot --continue -p …` from the same worktree.
-
-> **Smoke-test confirmations (per the plan):** the exact session-id field in the JSONL, the usage field names, and
-> that `--resume=<id>` truly continues the same context — verify these on a throwaway worktree before relying on
-> them, and update this table with what you find.
-
-## Input Variables
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `<WORKTREE>` | dedicated git worktree (off main) | `~/code/vizzita-billing-s10` |
-| `<PROMPT>` | prepared prompt/spec path | `.dw/spec/prd-billing-integrador/codex-prompt.md` |
-| `<slug>` | task key for audit/session files | `prd-billing-integrador` |
-| `<AUDIT>` | durable audit dir OUTSIDE the worktree | `~/code/vizzita/.dw/cli-run` |
-
-Return via the `dw-cli-run` **Structured Return** (Status/Score/Scope/Evidence/Artifacts/Decisions/Risks/Telemetry/
-Next Step), including the captured `session-id`, its sidecar path, and the exact `RESUME` command to continue.
+| `DISPATCH` | `copilot -p "<PROMPT_TEXT>" --model "<MODEL>" <PERMISSIONS> --output-format json > "<AUDIT>/<slug>.log" 2>&1` |
+| `STREAM` | `--output-format json` (verify installed CLI) |
+| `MODEL` | `--model "<MODEL>"` |
+| `EFFORT` | Use `default` when no effort flag is supported; never invent a flag |
+| `AUTO` | <PERMISSIONS> — approved non-interactive profile; retain existing configuration |
+| `AUTO_READONLY` | Resolve enforced read-only tool controls from installed help; block READ-ONLY if unavailable |
+| `NO_MCP` | Select only capabilities needed, if supported; preserve user configuration otherwise |
+| `RESUME <id>` | `copilot --resume="<SESSION_ID>" -p "<FOLLOWUP_TEXT>" --model "<MODEL>" <RESUME_PERMISSIONS> --output-format json >> "<AUDIT>/<slug>.log" 2>&1` |
+| `SESSION_ID` | Capture exact ID from this task’s stream; verify event schema against installed CLI → `<AUDIT>/<slug>.session` |
+| `DONE_SIGNAL` | Provider terminal record plus process exit and inspected report |
+| `USAGE` | Reported usage fields only; unknown if absent |
+
+Create/reuse through `/dw-worktree create <slug>`; after authorized integration, `/dw-worktree merge <slug>` owns merge and safe cleanup. Workers return to the parent and never invoke integration themselves.
+
+## Model selection and resume
+
+Resolve concrete model/effort at task breakdown using `.dw/config/routing.json`, current provider metadata and the installed tool. Do not embed a fixed strongest-to-lightest model list in this adapter. Supported effort values depend on model/version; low, medium, high, xhigh and max are candidates only when supported. No mandatory escalation to the ceiling.
+
+Store task, provider, worktree, approved assignment, session ID and audit path before handoff. If the session sidecar is absent, recover the exact task session from its log; never blindly continue the latest cwd session. If identity cannot be proven, start a new session from saved state and the actual diff, preserving partial work. Provider sessions are not portable across CLIs.
+
+Return the `dw-cli-run` Structured Return with evidence and the exact supported resume command. The parent continues the approved plan; merge/push/publication require applicable authorization.
+
+Capability inspection: Copilot adapter requires installed-version capability validation.
 </system_instructions>

package/scaffold/en/commands/dw-generate-pr.md

@@ -13,11 +13,11 @@ You are an assistant specialized in creating well-documented Pull Requests. Your
 
 | Skill | Trigger |
 |-------|---------|
-| `dw-verify` | **ALWAYS** — invoked before `git push`. Without a VERIFICATION REPORT PASS in the current session AFTER the last code edit, the PR **CANNOT** be created. |
+| `dw-verify` | **ALWAYS** — invoked before `git push`. Without a VERIFICATION REPORT PASS valid for the current inputs, environment and scope, the PR **CANNOT** be created. |
 | `dw-git-discipline` | **ALWAYS** — validates branch naming (`<type>/<scope>` kebab-case), atomic-commit history (each commit single-intent, conventional message), branch lifetime (flag if >7 days old), and PR scope (suggest split if diff > ~400 lines). PR description follows summary + test plan structure, not a `git log` dump. |
 | `/dw-secure-audit` | **ALWAYS for TS/Python/C#/Rust projects** — a fresh `.dw/secure-audit/audit-summary.md` with status ≠ REJECTED is required for supported-language projects. |
 
-<critical>Hard gate 1 (verify): if the current session has no VERIFICATION REPORT PASS from `dw-verify` produced AFTER the last edit/commit, STOP and invoke `dw-verify` before proceeding. A PR is a permanent artifact — it demands the highest verification standard.</critical>
+<critical>Hard gate 1 (verify): use `dw-verify` to confirm valid passing evidence for current inputs, environment and scope before push/PR. Reuse equivalent evidence; run missing or invalidated required checks. No new-session or bookkeeping-only-commit reset.</critical>
 
 <critical>Hard gate 2 (security): for TS/Python/C#/Rust projects, if `.dw/secure-audit/audit-summary.md` is missing, stale (predates the last edit), OR has REJECTED status, STOP and invoke `/dw-secure-audit` before proceeding. SECRET findings and HIGH/CRITICAL vulnerabilities CANNOT reach the PR. For other languages (Go, Java, etc.), this gate is skipped with a note.</critical>
 

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

@@ -4,7 +4,7 @@ You are the dev-workflow durable goal orchestrator. This command gives every sup
 ## When to Use
 - Use when a workflow is larger than one normal turn but has a clear finish line.
 - Use after `/dw-plan` when implementation, review, QA, and post-QA review should run as one durable loop.
-- Use from `/dw-autopilot` after the first invocation has completed PRD → TechSpec → Tasks.
+- Use from `/dw-autopilot` after the approved PRD → TechSpec → Tasks plan is ready.
 - Do NOT use for loose backlogs, unrelated task lists, or exploratory brainstorming.
 
 ## Position in Pipeline
@@ -28,7 +28,7 @@ You are the dev-workflow durable goal orchestrator. This command gives every sup
 Official Codex guidance treats `/goal` as an experimental durable objective for long-running work with a verifiable stopping condition. In Codex CLI it requires `features.goals`; it can be set with `/goal <objective>`, inspected with `/goal`, and controlled with `/goal pause`, `/goal resume`, or `/goal clear`.
 
 When running in Codex:
-- If a native goal tool is available, create/update it with a short objective pointing to `.dw/goals/<slug>/goal.md`.
+- Use native goal tools only when explicitly requested and permitted by their actual tool contract; never infer native-goal authorization from a portable workflow alone.
 - If the interactive `/goal` slash command is available and `features.goals` is enabled, use `/goal <objective>` with an objective under 4,000 characters.
 - If native goals are unavailable, continue with the portable `.dw/goals/` loop. Do not block.
 
@@ -101,12 +101,12 @@ Checkpoints:
 | `review-before-qa` | `/dw-review <prd-path>` | `<prd-path>/QA/review-consolidated.md` exists and overall verdict is approved or approved with explicit non-blocking caveats. |
 | `qa` | `/dw-qa <prd-path>` | Required QA artifacts exist. |
 | `qa-fix` | `/dw-qa --fix <prd-path>` when `bugs.md` has Open bugs | Bugs are Fixed/Closed or explicitly deferred by user. |
-| `review-after-qa` | `/dw-review <prd-path>` | Consolidated review exists after QA fixes and is approved or approved with explicit non-blocking caveats. |
+| `review-after-qa` | `/dw-review <prd-path>` when QA edits/findings invalidate review | Current consolidated review is approved or approved with explicit non-blocking caveats; unchanged QA reuses valid review. |
 
 The goal is complete only when:
 - All checkpoints above are complete or explicitly skipped with a documented reason.
 - No Open QA bug remains unless the user explicitly accepted deferral.
-- The final `/dw-review` ran after the last QA fix.
+- The final full `/dw-review` covers the current implementation. Repeat after QA edits or new findings; reuse when QA invalidated nothing.
 - `status.json` has `"status": "complete"`.
 
 ## Execution Rules
@@ -123,7 +123,7 @@ The goal is complete only when:
 
 - `status`: read `status.json` and last 10 entries of `progress.md`; report current checkpoint, completed checkpoints, last verification, and blockers.
 - `pause`: set `status: "paused"` and append why.
-- `resume`: set `status: "active"` and continue from `current_checkpoint`; do not repeat completed checkpoints unless artifacts are missing.
+- `resume`: set `status: "active"` and continue from `current_checkpoint`; do not repeat completed checkpoints unless artifacts are missing or evidence was invalidated.
 - `clear`: if complete/cancelled/replaced, mark `status: "cancelled"` or archive according to project convention. Do not delete evidence by default.
 
 ## Anti-patterns
@@ -133,4 +133,10 @@ The goal is complete only when:
 - Do not mark a checkpoint complete without checking artifacts.
 - Do not use native Codex `/goal` as the only state; `.dw/goals/` remains the cross-agent contract.
 
+## Approved execution state
+
+Read `.dw/references/execution-contract.md`. Consume approved task assignments and preserve `execution-state.json` through checkpoints. A runner return goes back to the parent for review, corrections and next tasks. Do not repeat `/dw-run`'s final full review when it already covers the unchanged implementation: validate its evidence and record the checkpoint as reused. Conditional/inapplicable QA needs a recorded reason, not invented artifacts. Complete the goal by verifying acceptance and evidence first, then set status complete; the status field itself does not prove completion.
+
+Resume preserves completed checkpoints unless evidence is invalid or artifacts are missing. Separate delivery from merge/push/publication authorization. Keep partial work on block/pause and never silently change a task's executor.
+
 </system_instructions>

package/scaffold/en/commands/dw-harness-audit.md

@@ -22,7 +22,9 @@ You are the dev-workflow harness auditor.
    - Verification gates
    - Security gates
    - Context discipline
+   - Worktree hygiene
 3. For structured skill returns, inspect bundled skill `SKILL.md` files and require a `## Structured Return` contract with `Status`, `Evidence`, `Artifacts`, and `Next Step`.
+3b. For worktree hygiene, run `node .dw/scripts/lib/worktree-gc.mjs list --strict`. Exit 3 (any `REMOVABLE` or `PRUNABLE` worktree) caps the category at 3/10; cite each leftover with its size and verdict and recommend `/dw-worktree clean --apply`. `KEEP:*` entries are informational.
 4. Cite missing paths, broken references, stale managed files, and skills without a structured return.
 5. Recommend the top 3 fixes.
 

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

@@ -19,11 +19,11 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 
 | Command | When |
 |---------|------|
-| `/dw-autopilot "wish"` | Default entry point in two invocations. First run plans and stops; second run resumes through `/dw-goal`, Security Gate, commit, and PR. |
+| `/dw-autopilot "wish"` | Plan and approve execution assignments, then continue through implementation, review and validation. |
 | `/dw-bugfix "description"` | A bug or error report. Surgical fix or PRD route. |
 | `/dw-help [keyword]` | This screen. Pass a keyword for shortcuts. `--advanced` reveals internal commands. |
 
-## Tier 2 — Pipeline granular (10)
+## Tier 2 — Pipeline granular (11)
 
 | Command | What |
 |---------|------|
@@ -35,10 +35,11 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-qa` | Mode-aware QA (UI / API auto-detect). Flags: `--fix`, `--api`, `--ai`, `--uat`, `--bugfix <slug>`. |
 | `/dw-pause` | Save session state, decisions, blockers, todos, and open loops into `.dw/STATE.md`. |
 | `/dw-resume` | Read `.dw/STATE.md`, show a TLDR, and suggest the next `dw-*` command. |
+| `/dw-report [--every <N>m]` | Timestamped done / doing / remaining report every 10 minutes while long work runs; appended to `.dw/reports/`. `now`, `status`, `stop`. Auto-armed by `/dw-run`, `/dw-autopilot`, and the CLI runners. |
 | `/dw-commit` | Atomic Conventional Commits for pending work. |
 | `/dw-generate-pr [target]` | Push branch, draft PR body, open browser. |
 
-## Tier 3 — Specialty (12)
+## Tier 3 — Specialty (13)
 
 | Command | What |
 |---------|------|
@@ -50,6 +51,7 @@ Use `/dw-autopilot "wish"` as the gateway for most feature work. The granular co
 | `/dw-context-budget` | Audit context overhead from commands, skills, agents, instructions, and MCPs. |
 | `/dw-harness-audit` | Score dev-workflow install health: wrappers, agents, MCPs, gates. |
 | `/dw-skill-health` | Audit skills and agents for bloat, duplication, and missing references. |
+| `/dw-worktree <list\|create\|clean\|merge>` | Worktree lifecycle: create prepared, list with verdicts, clean only proven-merged (dry-run default), ff-only merge + remove in the same turn. Never `--force`. |
 | `/dw-new-project` | Interview-driven bootstrap (stack + infra + docker-compose + CI). |
 | `/dw-dockerize` | Detect stack, propose Dockerfile + docker-compose for dev/prod. |
 | `/dw-install-azure-skills` | Opt-in Azure skills + Microsoft Learn MCP setup. Interactive category selection. |
@@ -103,6 +105,7 @@ Match the keyword and suggest:
 | `run`, `execute`, `implement` | `/dw-run` |
 | `goal`, `objective`, `long-running`, `resume autopilot` | `/dw-goal` or `/dw-autopilot` if `autopilot-state.json` exists |
 | `pause`, `save state`, `end session` | `/dw-pause` |
+| `report`, `progress`, `keep me posted`, `status every` | `/dw-report [--every <N>m]` |
 | `resume`, `continue`, `where did we stop` | `/dw-resume` |
 | `review`, `quality`, `audit code` | `/dw-review` |
 | `qa`, `test plan`, `e2e` | `/dw-qa` |
@@ -121,6 +124,7 @@ Match the keyword and suggest:
 | `design.md`, `design authority`, `concerns map` | `/dw-analyze-project` (also listed as a post-update action when missing) |
 | `subagent`, `subtask`, `handoff`, `delegate` | `/dw-subtask-start` or `/dw-subtask-resume` |
 | `skills`, `skill health`, `bloat` | `/dw-skill-health` |
+| `worktree`, `worktrees`, `disk`, `merge worktree`, `clean worktrees` | `/dw-worktree list` / `create <slug>` / `clean --apply` / `merge <slug>` |
 | `analyze`, `rules`, `conventions` | `/dw-analyze-project` |
 | `constitution`, `principles` | `/dw-analyze-project` (Step 8 generates the constitution) |
 | `security opportunities`, `hardening ideas`, `improve security` | `/dw-opportunities "security"` |
@@ -141,7 +145,7 @@ If no keyword matches, show the default surface and a note: "Keyword `<word>` no
 ## FAQ
 
 **Q: I'm not sure where to start with a new feature.**
-- Use `/dw-autopilot "what you want"`. First invocation runs PRD → TechSpec → Tasks and stops; second invocation resumes through `/dw-goal`, Security Gate, commit, and PR.
+- Use `/dw-autopilot "what you want"`; approve the task/executor matrix and continue to validated delivery. Publication follows existing authorization.
 
 **Q: Do I have to use `/dw-autopilot`?**
 - No. The granular pipeline (`/dw-brainstorm` → `/dw-plan` → `/dw-goal` or `/dw-run`/`/dw-qa`/`/dw-review` → `/dw-secure-audit` → `/dw-commit` → `/dw-generate-pr`) gives you control at each step.

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

@@ -29,6 +29,7 @@ You are a session-handoff agent. Your job is to consolidate the current session'
 Read the conversation context and identify, **without inventing**:
 
 - **Open loops**: tasks/work started but not finished (e.g. "PRD `prd-foo` is at TechSpec stage, awaiting user approval"; "Task 3 of `prd-bar` failing on lint")
+- **Leftover worktrees**: run `node .dw/scripts/lib/worktree-gc.mjs list`. Every `REMOVABLE` entry is an open loop to close **now** with `/dw-worktree clean --apply` — not something to record; `KEEP:*` entries go under Open Loops with their verdict and reason.
 - **Decisions made**: choices the user and agent agreed on during the session that affect future work
 - **Blockers encountered**: things that stopped forward motion (waiting on input, broken tooling, knowledge gap)
 - **Todos** mentioned in passing that don't yet have a PRD or task file