@brunosps00/dev-workflow 2.1.0 → 2.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,124 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > those versions were released, so they are summaries of what shipped, not
 > contemporaneous release notes. `git log` remains the authoritative record.
 
+## [2.3.0] — 2026-09-09
+
+### Added
+
+- Task execution contracts with per-task tool, model, effort, agent and fallback
+  choices, dependency validation and persistent execution state. Schema 1.0 plans
+  remain supported with local execution defaults.
+- Instruction size and routed-reference validation in `npm run validate`, with
+  regression tests for missing resources and byte/discovery budget violations.
+- Frontend engineering guidance and EN/PT-BR quality baseline templates integrated
+  into project analysis, planning, review and QA. Controls cover API contracts,
+  types, import boundaries, code reachability, duplication and gradual CI adoption.
+- Scoped mutation-testing guidance that investigates behavioral gaps and cache
+  validity without introducing a universal score threshold.
+- Managed `routing-defaults.json` for comparing current model candidates while
+  preserving owner routing. Upgrade checks cover legacy plans and template overrides.
+
+### Changed
+
+- Approved implementation plans continue through execution, correction and
+  validation without a mandatory second invocation. Publication remains subject
+  to the user's authorization.
+- Claude, Codex and Copilot runner instructions use approved task assignments,
+  explicit session identity and parent review. New-install model routing defaults
+  are updated; existing owner configuration is preserved.
+- Installed root instructions are approximately 62% smaller. Detailed command
+  routing and conditional skill procedures move into references loaded as needed.
+- Verification reuses inspectable passing evidence only while command, inputs,
+  environment and scope remain equivalent. Required project checks still apply.
+- Planning and testing guidance favors behavior and risk over fixed task/file
+  quotas, blanket parallelism, universal coverage targets and score-only approval.
+
+### Fixed
+
+- Resume guidance preserves partial work and avoids blind latest-session recovery
+  or destructive retries. Dependent tasks retain a coherent worktree history.
+- Removed contradictory mutation-testing guidance and aligned EN/PT-BR review,
+  goal and resume behavior with the continuous execution contract.
+- Humanizer's upstream version is preserved under supported skill metadata.
+- `/dw-update` reads installed versions from `.dw/install-state.json` instead of
+  resolving an npm package that may only exist in the `npx` execution environment.
+
+Validation: 129 tests pass; registry, instruction and plugin checks pass.
+Install/update and package checks include the new resources. External provider
+dispatches and frontend analysis tools were not exercised against live projects.
+
+## [2.2.0] — 2026-08-24
+
+Release driven by two operational failures observed on a real project, both of the
+same family: the pipeline was good at *starting* long work and silent about what
+happened next. Delegated runs gave no visibility until someone asked "any news?",
+and the worktrees those runs lived in were created by a hard rule and removed by
+nobody — 35 of them (33 already merged) were sitting on disk at 40 GB with the
+root filesystem at 95%. Both fixes are deterministic where prose had failed.
+
+### Added
+
+- **`/dw-report` — timestamped progress loop for long work.** Every 10 minutes
+  (`--every <N>m`) it emits a report with a real `date` timestamp saying what is
+  **done** (cumulative, new items marked `➕`, each with evidence: file, commit,
+  test count), what is **being done** (with a measurable figure — step counter,
+  files touched, running command and elapsed time — never a bare "in progress"),
+  and what is **left** (ordered, next milestone first, remaining gates included).
+  Reports go to the chat and are appended to `.dw/reports/YYYY-MM-DD.md`. The
+  cadence is the user's: it never stretches to "wait for the build"; a report
+  saying "nothing changed, ~4 min left" is the product while work runs. Silence is
+  reserved for the blocked/idle state (the transition to blocked reports once);
+  completion produces a final report immediately and disarms the loop. Vehicle is
+  the harness's native scheduled wake-up when available, a background `sleep`
+  timer otherwise, and never a system cron (which keeps firing for days after the
+  work ended). Auto-armed by `/dw-run`, `/dw-autopilot` (execution invocation), and
+  the `dw-cli-run` adapters; `DW_REPORT_AUTO=off` opts out and `DW_REPORT_BELL`
+  hooks a local sound or notification. `now`, `status`, `stop` modes.
+- **`/dw-worktree` — the lifecycle the runner adapters never had.** Backed by
+  `.dw/scripts/lib/worktree-gc.mjs` (Node, no dependencies), which resolves the
+  main checkout from anywhere in the repo. `list` gives every secondary worktree a
+  verdict — `REMOVABLE` (head is an ancestor of an integration branch, clean, no
+  process has its cwd inside, not locked), `KEEP:unmerged`, `KEEP:dirty`,
+  `KEEP:in-use`, `KEEP:locked`, `KEEP:recent`, `PRUNABLE` — with apparent size,
+  age, and dirty count; `--strict` exits 3 on leftovers. `clean` is a **dry-run by
+  default**; `--apply` removes only `REMOVABLE` entries, deletes their branches
+  (verified merged), and prunes. `create <slug>` enforces the `../<project>-<slug>`
+  convention and runs the install/build prep (lockfile-detected or
+  `.dw/config.json` `worktree.prep`) so a delegated agent never runs blind.
+  `merge <slug>` performs the safe order from the main checkout — ff-only merge →
+  remove → branch delete → prune — and aborts **before** the merge if the main
+  checkout is off the base branch or dirty, the worktree is dirty or in use, or
+  the merge is not a fast-forward. It never uses `--force` and never changes the
+  owner's active branch. Base resolution: `--base` → `DW_WORKTREE_BASE` →
+  `worktree.base` → `origin/HEAD` → `develop` → `main` → `master`.
+
+### Changed
+
+- **End of life is the same turn as the merge.** `dw-cli-run` pre-flight creates
+  missing worktrees through `/dw-worktree create`, and its Discipline section now
+  carries the hard rule: merged → `/dw-worktree merge` (or `clean --apply`) in
+  that same turn. The three adapters point their `<WORKTREE>` input at the same
+  commands. `/dw-pause` sweeps worktrees and treats every `REMOVABLE` entry as an
+  open loop to close now rather than record; `/dw-harness-audit` gained a
+  *Worktree hygiene* category scored from `list --strict`.
+- **git guardrails** (`scaffold/scripts/hooks/git-guardrails.mjs`) also block
+  `git worktree remove --force` / `-f`; plain `remove` and `prune` stay allowed.
+- `/dw-run` (all-tasks and `--resume`) and `/dw-autopilot` Step 8 arm the progress
+  loop before dispatching; `dw-help`, the agent-instructions trigger map, and the
+  README register both commands (41 commands, Tier 2 = 11, Tier 3 = 14).
+- `dw-cli-run` `context_limit` raised 19000 → 20500 to hold the two new sections.
+
+### Fixed
+
+- `init`/`update` now create `.dw/cli-run/.gitignore` (`*`, `!.gitignore`). The
+  adapters' durable audit logs, session sidecars, and last-message captures were
+  being committed and then checked out into every worktree (219 tracked files on
+  the project that motivated this release). Existing projects untrack them with
+  `git rm -r --cached .dw/cli-run`.
+- `init`/`update` create `.dw/reports/.gitignore` so the daily report logs and the
+  loop's `.active.json` stay machine-local while other reports (e.g.
+  `context-budget.md`) remain tracked.
+
 ## [2.1.0] — 2026-08-04
 
 Release driven by a skill-by-skill analysis of [mattpocock/skills](https://github.com/mattpocock/skills),

package/README.md

@@ -42,18 +42,18 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v2.1.0 ships **39 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v2.3.0 ships **41 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (4)
 
 | Command | When |
 |---------|------|
-| **`/dw-autopilot "wish"`** | Default entry point in two invocations. First run completes PRD → TechSpec → Tasks and stops. Second run resumes from state, executes `/dw-goal --from-autopilot <slug>` for Run → Review → QA/Fix → Review, then Security Gate → Commit → PR. |
+| **`/dw-autopilot "wish"`** | Plan and approve task execution assignments, then continue through implementation, review and validation. Cross-tool workers return to the parent; merge/push/publication follow existing authorization. |
 | **`/dw-bugfix "description"`** | A bug report or pasted error. Triages bug-vs-feature-vs-scope, surgical fix or routes to a PRD. |
 | **`/dw-triage [item]`** | An external bug report, feature request, or PR. Checks whether it already exists and whether it was rejected before, verifies the claim, then routes to `/dw-bugfix`, `/dw-plan prd`, or `/dw-brainstorm --mode=grill`. Local-first in `.dw/triage/`; works with no network and no `gh`. |
 | **`/dw-help [keyword]`** | Discover commands. Pass a keyword for shortcuts; `--advanced` reveals internal commands. |
 
-### Tier 2 — Pipeline granular (10)
+### Tier 2 — Pipeline granular (11)
 
 Use these when you want step-by-step control instead of `/dw-autopilot`.
 
@@ -67,10 +67,11 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-qa`** | Mode-aware QA. Auto-detects UI vs API. Flags: `--fix` (iterative QA + fix-retest loop), `--api`, `--ai` (AI eval against reference dataset), `--uat` (human-in-the-loop walkthrough), `--bugfix <slug>` (QA a bugfix). |
 | **`/dw-pause`** | Consolidate the current session's mental state into `.dw/STATE.md` (Decisions, Blockers, Todos, Deferred, Lessons, Open Loops). Used before long breaks or context-window compactions. |
 | **`/dw-resume`** | Read `.dw/STATE.md`, present a TLDR of where work left off, and suggest the next `dw-*` command. Never auto-executes. |
+| **`/dw-report [--every <N>m]`** | Timestamped progress loop while long work runs: what is done (with evidence), what is being done (with measurable progress), what is left — every 10 minutes by default, appended to `.dw/reports/YYYY-MM-DD.md`. Silent while blocked, final report + auto-disarm when the work ends. `now`, `status`, `stop`. Auto-armed by `/dw-run`, `/dw-autopilot`, and the CLI runners; `DW_REPORT_AUTO=off` opts out, `DW_REPORT_BELL` hooks a local sound. |
 | **`/dw-commit`** | Atomic Conventional Commits for pending changes. Applies `dw-git-discipline` (one intent per commit, lint+tests+build green before). |
 | **`/dw-generate-pr [target]`** | Push the branch, draft a PR body with summary + test plan, open the browser. Hard gates: dw-verify PASS + secure-audit. |
 
-### Tier 3 — Specialty (13)
+### Tier 3 — Specialty (14)
 
 | Command | What |
 |---------|------|
@@ -82,6 +83,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-context-budget`** | Audits context overhead from commands, skills, agents, instruction files, and MCPs. |
 | **`/dw-harness-audit`** | Deterministic health scorecard for the dev-workflow install, agents, wrappers, MCPs, and gates. |
 | **`/dw-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references. |
+| **`/dw-worktree <list\|create\|clean\|merge>`** | Lifecycle of delegation worktrees (`../<project>-<slug>`): `create` runs install/build prep so a delegate never works blind; `list` gives every worktree a verdict (`REMOVABLE`, `KEEP:unmerged`, `KEEP:dirty`, `KEEP:in-use`); `clean` removes only proven-merged-and-clean ones (dry-run by default, `--apply` to execute); `merge` does the safe order from the main checkout (ff-only → remove → branch delete → prune). Never `--force`. Backed by `.dw/scripts/lib/worktree-gc.mjs`; auto-used by the CLI runners, `/dw-pause`, and `/dw-harness-audit`. |
 | **`/dw-learn`** | Synthesizes durable decisions (confidence-tagged), bugfixes, deviations, and git history into atomic confidence-weighted **instincts** you approve at `.dw/memory/instincts/`; can propose constitution principles. On-demand and human-in-the-loop — **no always-on observer**. |
 | **`/dw-new-project`** | Bootstrap a new project from an empty or docs-first directory while preserving existing documentation and prototypes. Stack interview includes Next.js + NestJS, Postgres, pg-boss, Mailpit, dev topology, and wraps official `create-*` tools before composing dev infrastructure, `.env`, scripts, CI, and `.dw/rules/`. |
 | **`/dw-dockerize`** | Reads existing project, detects stack + runtime deps, proposes Dockerfile + docker-compose for dev/prod with explicit trade-offs (Conservative/Balanced/Bold). |
@@ -110,8 +112,8 @@ These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help
 ## Workflow
 
 ```
-/dw-autopilot "wish"  ------>  First invocation: PRD → TechSpec → Tasks → STOP
-/dw-autopilot          ------>  Second invocation: /dw-goal → Security Gate → Commit → PR
+/dw-autopilot "wish"  ------>  PRD → TechSpec → Tasks + execution assignments → approval
+                             → /dw-goal → Security Gate → validated delivery → authorized publication
     --- OR step-by-step ---
 
 /dw-opportunities --> /dw-brainstorm --> /dw-plan --> .dw/spec/prd-{name}/{prd,techspec,tasks}.md
@@ -226,6 +228,7 @@ your-project/
 │   ├── spec/              # PRD directories — each contains tasks-validation.md
 │   ├── bugfixes/          # Persistent bugfix records: NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md} + review/, QA/
 │   ├── goals/             # Durable goal state used by /dw-goal and /dw-autopilot
+│   ├── reports/           # Progress-report loop (/dw-report): daily YYYY-MM-DD.md logs + .active.json, machine-local (gitignored)
 │   ├── secure-audit/      # Security Gate summaries and per-layer reports
 │   ├── subtasks/          # Local ephemeral subagent input packets and handoffs (pending/archive ignored by Git)
 │   └── STATE.md           # Session state: Decisions, Blockers, Todos, Open Loops, Deferred Ideas, Lessons, Preferences (managed by /dw-pause + /dw-resume)
@@ -312,6 +315,8 @@ These are not slash commands — they are primitives other commands call to enfo
 
 ## Dependencies
 
+Frontend engineering guidance is loaded when planning or reviewing frontend data flow, dependencies or quality tooling. `/dw-analyze-project` documents the module's existing controls and gaps; `/dw-plan` carries accepted changes into tasks; `/dw-review` and `/dw-qa` use applicable evidence. The localized `frontend-quality-template.md` distinguishes required checks, advisory diagnostics and deferred proposals. API contracts, architecture checks and scoped mutation analysis complement the visual UI skill. Tool installation and CI policy changes remain scoped to the consumer project's task.
+
 Installed via `npx @brunosps00/dev-workflow install-deps`:
 
 | Dependency | Purpose | Link |
@@ -439,3 +444,9 @@ Skill description format ("pushy" trigger phrases ≤200 chars, "Use when X. Tri
 ## License
 
 MIT
+
+### Task execution across tools
+
+During `/dw-plan tasks`, review the proposed complexity, local/cross-tool executor, model, effort and agents for each task. Claude can delegate to `/dw-codex-run`, and Codex to `/dw-claude-run`. Approval carries through implementation, review and corrections; the parent continues after each worker handoff. A planning-only request still ends with the plan.
+
+Existing task documents remain compatible and default to local execution. Updates preserve your `.dw/config/routing.json`; new model candidates are proposals to verify against your account, not silent upgrades. See [workflow modernization](docs/model-workflow-modernization.md) for the execution contract, evidence reuse and validation limits.

package/lib/constants.js

@@ -2,13 +2,13 @@ const COMMANDS = {
   en: [
     { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost. --scope=repo writes .dw/adrs/ (works before any PRD); --scope=prd writes under the active PRD. Gated on hard-to-reverse + surprising + genuine trade-off.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
-    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. First invocation plans and stops; second invocation resumes via dw-goal, then commit and PR.' },
-    { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Auto-dispatches internal modes via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill is a native stateful alignment session (a direct grill-me phrase or --mode=grill) that writes canonical vocabulary to .dw/domain/. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
+    { name: 'dw-autopilot', description: 'Plan a multi-component implementation, approve task execution assignments, then continue through implementation, review and validation.' },
+    { name: 'dw-brainstorm', description: 'Explore unresolved product or architecture choices for a concrete idea; use grill for stateful alignment, research for unknowns, or council for competing approaches.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
-    { name: 'dw-claude-run', userInvoked: true, description: 'Trigger when user asks to run/fire Claude (claude -p headless) in a dedicated worktree to implement a prepared prompt/spec. Claude adapter over the dw-cli-run protocol: durable audit log, resumable session via --session-id, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
-    { name: 'dw-codex-run', userInvoked: true, description: 'Trigger when user asks to run/fire Codex (codex exec) in a dedicated worktree to implement a prepared prompt/spec. Codex adapter over the dw-cli-run protocol: durable audit log, resumable per-task session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-claude-run', userInvoked: true, description: 'Run an approved task through Claude CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
+    { name: 'dw-codex-run', userInvoked: true, description: 'Run an approved task through Codex CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
-    { name: 'dw-copilot-run', userInvoked: true, description: 'Trigger when user asks to run/fire GitHub Copilot CLI (copilot -p) in a dedicated worktree to implement a prepared prompt/spec. Copilot adapter over the dw-cli-run protocol: durable audit log, resumable session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-copilot-run', userInvoked: true, description: 'Run an approved task through Copilot CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
     { name: 'dw-dockerize', description: 'Reads a project, detects the stack and runtime deps, then proposes Dockerfile and docker-compose for dev and prod with explicit trade-offs.' },
     { name: 'dw-find-skills', description: 'Searches the npx skills ecosystem for a skill matching what you need, vets it, and installs it where you choose.' },
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
@@ -17,39 +17,41 @@ const COMMANDS = {
     { name: 'dw-help', description: 'Lists primary commands and the flows that connect them. Pass --advanced to see internal/hidden commands.' },
     { name: 'dw-context-budget', description: 'Audits context overhead from commands, skills, agents, instructions, and MCPs; recommends token savings.' },
     { name: 'dw-harness-audit', description: 'Runs a deterministic health scorecard for dev-workflow installation, agents, MCPs, gates, and context discipline.' },
-    { name: 'dw-install-aws-skills', description: 'Trigger when user asks to install AWS expertise, setup AWS MCP server, or add AWS agent skills. Opt-in: clones curated skills from aws/agent-toolkit-for-aws into .agents/skills/aws/ and registers the unified AWS MCP Server (stdio via mcp-proxy-for-aws). Requires uv, aws cli, and AWS credentials.' },
+    { name: 'dw-install-aws-skills', description: 'Install selected AWS expertise and configure the AWS MCP integration when requested.' },
     { name: 'dw-install-azure-skills', description: 'Trigger when user asks to install Azure expertise, setup Microsoft docs MCP, or add Azure agent skills. Opt-in: clones curated skills from MicrosoftDocs/Agent-Skills into .agents/skills/azure/ and registers the Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
-    { name: 'dw-open-design', userInvoked: true, description: 'Trigger when user asks to generate, iterate, or refactor/redesign headless Open Design HTML prototypes via the od CLI. Imports a target folder with isolated OD_DATA_DIR, refines briefs before dispatch, supports --refactor screenshots via --url/--viewports or --screenshot, runs web-prototype briefs with explicit --agent codex|claude, verifies files, captures JSONL audit logs, and stops for a dual >=9 visual gate.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Generate or iterate Open Design HTML prototypes through the od CLI, including screenshot-based redesign and visual verification.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
-    { name: 'dw-plan', description: 'Trigger when user has a feature idea and needs spec + architecture + tasks. Runs PRD → TechSpec → Tasks sequentially. Stages: prd / techspec / tasks; --from techspec; --council.' },
+    { name: 'dw-plan', description: 'Produce PRD, architecture and tasks, with local/cross-tool executor, model, effort and agent proposals by task complexity.' },
     { name: 'dw-qa', description: 'Trigger when user wants to validate behavior beyond unit tests. Mode-aware (UI / API / --ai / --uat). --fix enters the iterative QA + fix-retest loop. --bugfix <slug> targets a .dw/bugfixes/ entry.' },
     { name: 'dw-redesign-ui', description: 'Audits a frontend page, proposes design directions you choose from, then ships the redesign.' },
     { name: 'dw-refactor', description: 'Audits a target for refactor opportunities using the refactor-audit protocol, Fowler smells, deep-modules analysis, and behavior-preserving test gates.' },
+    { name: 'dw-report', description: 'Report progress periodically during authorized long-running work; persist updates and stop reporting when the work ends.' },
     { name: 'dw-resume', description: 'Trigger when user says "resume work", "where did we stop?", or starts a session in a project with an existing .dw/STATE.md. Reads STATE.md, presents a TLDR, and suggests the next dw-* command.' },
     { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
-    { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block. Auto-invoked by /dw-review and /dw-generate-pr, explicit phase in /dw-autopilot, and runnable standalone.' },
+    { name: 'dw-secure-audit', description: 'Audit relevant code and dependencies for security findings using available scanners; validate exploitability and enforce blocking findings.' },
     { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
     { name: 'dw-subtask-start', userInvoked: true, description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
     { name: 'dw-triage', description: 'Local-first intake for external bug reports, feature requests, and PRs. Persists .dw/triage/ state, checks redundancy and prior rejections, verifies claims, then routes to /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, or no work.' },
+    { name: 'dw-worktree', description: 'Create prepared worktrees, inspect their state, clean safely merged worktrees, or integrate an explicitly authorized branch.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
     { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam. --scope=repo escreve em .dw/adrs/ (funciona antes de qualquer PRD); --scope=prd escreve sob o PRD ativo. Gated em dificil-de-reverter + surpreendente + trade-off real.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
-    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Primeira invocacao planeja e para; segunda retoma via dw-goal, depois commit e PR.' },
-    { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Auto-dispatch de modos internos via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill e uma sessao nativa de alinhamento com estado (frase direta tipo me-questione ou --mode=grill) que escreve vocabulario canonico em .dw/domain/. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
+    { name: 'dw-autopilot', description: 'Planeja implementação multicomponente, aprova escolhas de execução por task e continua por implementação, review e validação.' },
+    { name: 'dw-brainstorm', description: 'Explora escolhas pendentes de produto ou arquitetura; grill para alinhamento com estado, pesquisa para lacunas e council para alternativas concorrentes.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
-    { name: 'dw-claude-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Claude (claude -p headless) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Claude sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel via --session-id, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
-    { name: 'dw-codex-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Codex (codex exec) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Codex sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel por tarefa, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-claude-run', userInvoked: true, description: 'Executa task aprovada pela CLI Claude em worktree dedicado; retorna sessão durável e evidências ao parent.' },
+    { name: 'dw-codex-run', userInvoked: true, description: 'Executa task aprovada pela CLI Codex em worktree dedicado; retorna sessão durável e evidências ao parent.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
-    { name: 'dw-copilot-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o GitHub Copilot CLI (copilot -p) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Copilot sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-copilot-run', userInvoked: true, description: 'Executa task aprovada pela CLI Copilot em worktree dedicado; retorna sessão durável e evidências ao parent.' },
     { name: 'dw-dockerize', description: 'Le um projeto, detecta stack e deps de runtime, e propoe Dockerfile e docker-compose para dev e prod com trade-offs explicitos.' },
     { name: 'dw-find-skills', description: 'Busca no ecossistema npx skills uma skill que resolva o que voce precisa, valida e instala onde voce escolher.' },
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
@@ -58,27 +60,29 @@ const COMMANDS = {
     { name: 'dw-help', description: 'Lista comandos primarios e fluxos que os conectam. Passe --advanced para ver comandos internos/escondidos.' },
     { name: 'dw-context-budget', description: 'Audita overhead de contexto em comandos, skills, agentes, instrucoes e MCPs; recomenda economia de tokens.' },
     { name: 'dw-harness-audit', description: 'Roda um scorecard deterministico da instalacao dev-workflow, agentes, MCPs, gates e disciplina de contexto.' },
-    { name: 'dw-install-aws-skills', description: 'Trigger quando usuario pede pra instalar expertise AWS, configurar MCP da AWS, ou adicionar agent skills AWS. Opt-in: clona skills curadas de aws/agent-toolkit-for-aws para .agents/skills/aws/ e registra o AWS MCP Server unificado (stdio via mcp-proxy-for-aws). Requer uv, aws cli e credenciais AWS.' },
-    { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure. Opt-in: clona skills curadas de MicrosoftDocs/Agent-Skills para .agents/skills/azure/ e registra o Microsoft Learn MCP server.' },
+    { name: 'dw-install-aws-skills', description: 'Instala expertise AWS selecionada e configura integração MCP AWS quando solicitado.' },
+    { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure.' },
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
-    { name: 'dw-open-design', userInvoked: true, description: 'Trigger quando usuario pede para gerar, iterar ou refatorar/redesenhar prototipos HTML headless do Open Design via od CLI. Importa pasta alvo com OD_DATA_DIR isolado, refina briefs antes de despachar, suporta prints --refactor via --url/--viewports ou --screenshot, roda briefs web-prototype com --agent codex|claude explicito, verifica arquivos, captura logs JSONL e para para gate visual dual >=9.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Gera ou itera protótipos HTML Open Design pela CLI od, incluindo redesign por screenshots e verificação visual.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
-    { name: 'dw-plan', description: 'Trigger quando usuario tem ideia de feature e precisa spec + arquitetura + tasks. Roda PRD → TechSpec → Tasks sequencial. Stages: prd / techspec / tasks; --from techspec; --council.' },
+    { name: 'dw-plan', description: 'Produz PRD, arquitetura e tasks com propostas de executor local/cruzado, modelo, esforço e agentes por complexidade.' },
     { name: 'dw-qa', description: 'Trigger quando usuario quer validar comportamento alem de unit tests. Mode-aware (UI / API / --ai / --uat). --fix entra no loop iterativo QA + fix-retest. --bugfix <slug> aponta para uma entrada em .dw/bugfixes/.' },
     { name: 'dw-redesign-ui', description: 'Audita uma pagina frontend, propoe direcoes de design que voce escolhe, e entrega o redesign.' },
     { name: 'dw-refactor', description: 'Audita um target por oportunidades de refactor usando o protocolo refactor-audit, smells Fowler, deep-modules e gates de teste preservando comportamento.' },
+    { name: 'dw-report', description: 'Reporta progresso periódico durante trabalho longo autorizado; persiste atualizações e encerra quando o trabalho termina.' },
     { name: 'dw-resume', description: 'Trigger quando usuario diz "retoma", "onde paramos?" ou comeca sessao num projeto com .dw/STATE.md existente. Le STATE.md, apresenta TLDR e sugere proximo comando dw-*.' },
     { name: 'dw-review', description: 'Trigger quando usuário pede pra revisar código, checar qualidade ou validar prontidão pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
-    { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH bloqueiam. Auto-invocado por /dw-review e /dw-generate-pr, fase explicita no /dw-autopilot, e executavel standalone.' },
+    { name: 'dw-secure-audit', description: 'Audita código e dependências relevantes com scanners disponíveis; valida explorabilidade e aplica achados bloqueantes.' },
     { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
     { name: 'dw-subtask-start', userInvoked: true, description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
-    { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos. Persiste estado em .dw/triage/, checa redundância e rejeições anteriores, verifica alegações, e então roteia para /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, ou nenhum trabalho.' },
+    { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos.' },
+    { name: 'dw-worktree', description: 'Cria worktrees preparados, inspeciona estado, limpa worktrees integrados com segurança ou integra branch explicitamente autorizada.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };

package/lib/init.js

@@ -202,6 +202,13 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     const cfgDir = path.join(projectRoot, '.dw', 'config');
     ensureDir(cfgDir);
     const routingDest = path.join(cfgDir, 'routing.json');
+    // Refresh the candidate reference without replacing active owner choices.
+    const defaultsDest = path.join(cfgDir, 'routing-defaults.json');
+    const defaultsStatus = writeFile(defaultsDest, require('fs').readFileSync(routingSrc, 'utf-8'), managedForce);
+    if (defaultsStatus === 'created') totalCreated++;
+    else if (defaultsStatus === 'overwritten') totalOverwritten++;
+    else totalSkipped++;
+    touchedFiles.push(defaultsDest);
     const rtStatus = writeFile(routingDest, require('fs').readFileSync(routingSrc, 'utf-8'), false);
     if (rtStatus === 'created') totalCreated++;
     else totalSkipped++;
@@ -283,6 +290,32 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     touchedFiles.push(metricsGitignore);
   }
 
+  // 5.25b. Ensure .dw/reports/ + .gitignore (progress-report loop; the daily logs and
+  // the .active.json loop state are machine-local so they are gitignored, while other
+  // reports such as context-budget.md stay tracked). Created if missing on init and update.
+  {
+    const reportsDir = path.join(projectRoot, '.dw', 'reports');
+    ensureDir(reportsDir);
+    const reportsGitignore = path.join(reportsDir, '.gitignore');
+    const rStatus = writeFile(reportsGitignore, '????-??-??.md\n.active.json\n', false);
+    if (rStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(reportsGitignore);
+  }
+
+  // 5.25c. Ensure .dw/cli-run/ + .gitignore (durable audit logs, session sidecars and
+  // last-message captures of the dw-*-run adapters are machine-local; committing them
+  // bloats every worktree checkout). Created if missing on init and update.
+  {
+    const cliRunDir = path.join(projectRoot, '.dw', 'cli-run');
+    ensureDir(cliRunDir);
+    const cliRunGitignore = path.join(cliRunDir, '.gitignore');
+    const cStatus = writeFile(cliRunGitignore, '*\n!.gitignore\n', false);
+    if (cStatus === 'created') totalCreated++;
+    else totalSkipped++;
+    touchedFiles.push(cliRunGitignore);
+  }
+
   // 5.26. Ensure .dw/memory/instincts/ (durable learnings promoted by /dw-learn;
   // format in the dw-memory skill's references/instincts.md). Init only; preserved on update.
   if (!isUpdate) {
@@ -393,6 +426,7 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     managedFiles: listManagedFiles(projectRoot, touchedFiles),
   });
   console.log(`  Install state: ${path.relative(projectRoot, path.join(projectRoot, '.dw', 'install-state.json'))} (${installState.managed_files.length} files tracked)\n`);
+  console.log(`  Installed version: ${priorState?.version || 'unknown'} -> ${installState.version}\n`);
 
   // 10. Summary
   console.log(`  ${'='.repeat(40)}`);

package/lib/instruction-health.js

@@ -0,0 +1,38 @@
+const fs = require('fs');
+const path = require('path');
+const { COMMANDS } = require('./constants');
+
+const LIMITS = { instructions: 6000, skill: 8000, description: 250 };
+
+function inspectInstructions(root = path.join(__dirname, '..')) {
+  const issues = [];
+  const metrics = { instructions: {}, descriptions: {}, skills: {} };
+  for (const locale of ['en', 'pt-br']) {
+    const file = path.join(root, 'scaffold', locale, 'agent-instructions.md');
+    metrics.instructions[locale] = fs.statSync(file).size;
+    if (metrics.instructions[locale] > LIMITS.instructions) issues.push(`${locale} installed instructions exceed ${LIMITS.instructions} bytes`);
+    metrics.descriptions[locale] = 0;
+    for (const command of COMMANDS[locale]) {
+      metrics.descriptions[locale] += [...command.description].length;
+      if ([...command.description].length > LIMITS.description) issues.push(`${locale} ${command.name} description exceeds ${LIMITS.description} characters`);
+    }
+  }
+  const skillsDir = path.join(root, 'scaffold', 'skills');
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (!fs.existsSync(file)) continue; // Registry validator reports missing entrypoints.
+    const content = fs.readFileSync(file, 'utf8');
+    metrics.skills[entry.name] = Buffer.byteLength(content);
+    if (metrics.skills[entry.name] > LIMITS.skill) issues.push(`${entry.name} entrypoint exceeds ${LIMITS.skill} bytes`);
+    const description = content.match(/^description:\s*(.+)$/m)?.[1]?.replace(/^"|"$/g, '');
+    if (!description || [...description].length > LIMITS.description) issues.push(`${entry.name} requires a description of at most ${LIMITS.description} characters`);
+    // Concrete skill-relative router links, not wildcard examples or installed paths.
+    for (const match of content.matchAll(/(?:`|\]\()((?:references|agents|rules|languages|infrastructure)\/[\w./-]+\.md)(?:`|\))/g)) {
+      if (!fs.existsSync(path.join(path.dirname(file), match[1]))) issues.push(`${entry.name} missing routed reference ${match[1]}`);
+    }
+  }
+  return { issues, metrics };
+}
+
+module.exports = { LIMITS, inspectInstructions };

package/lib/post-update.js

@@ -71,7 +71,7 @@ function listPostUpdateActions(projectRoot) {
   });
   actions.push({
     command: '/dw-skill-health',
-    reason: 'audit refreshed bundled skills and agents for bloat, duplication, and stale references',
+    reason: 'audit refreshed skills and compare .dw/config/routing.json with managed routing-defaults.json; preserve owner choices and approved plans',
   });
 
   return actions;
@@ -80,6 +80,7 @@ function listPostUpdateActions(projectRoot) {
 function printPostUpdateActions(projectRoot) {
   const actions = listPostUpdateActions(projectRoot);
   console.log('  Post-update agent actions:');
+  console.log('    Read the refreshed .dw/commands/dw-update.md before following the post-update instructions.');
   console.log('    The CLI refreshed managed files. Project-derived docs require the agent to run commands:');
   for (const action of actions) {
     console.log(`    - ${action.command} - ${action.reason}`);

package/lib/validate.js

@@ -3,6 +3,7 @@ const path = require('path');
 const { validateSkillRegistry } = require('./skill-registry');
 const { validateAgentRegistry, readAgentRegistry } = require('./agents');
 const { buildManifests } = require('./build-plugin');
+const { inspectInstructions } = require('./instruction-health');
 
 /**
  * Repo quality gate (npm run validate). Validates the skill + agent registries
@@ -20,6 +21,7 @@ function run() {
   const agent = validateAgentRegistry(readAgentRegistry());
   issues.push(...agent.issues);
   warnings.push(...agent.warnings);
+  issues.push(...inspectInstructions().issues);
 
   // Plugin manifest drift check.
   const { plugin, marketplace } = buildManifests();
@@ -41,7 +43,7 @@ function run() {
     console.log('FAIL');
     process.exit(1);
   }
-  console.log('PASS: skill + agent registries valid; plugin manifests in sync.');
+  console.log('PASS: skill + agent registries valid; instruction budgets valid; plugin manifests in sync.');
 }
 
 function checkManifestDrift(relPath, expected, issues) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"