@brunosps00/dev-workflow 2.2.0 → 2.4.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.2.0",
+  "version": "2.4.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,127 @@ 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.4.0] — 2026-09-21
+
+### Added
+
+- **A floor the ADR escape does not reach.** `.dw/references/invariants.md` names the
+  invariants no ADR unblocks — destructive git and secret handling — and states the
+  direction: project rules bind only by tightening. A line in `.dw/rules/**`, the
+  constitution or `CLAUDE.md` that would loosen one is reported as a finding, never
+  obeyed. It ships in the managed references directory, which has no override path, so
+  a consumer cannot remove it durably.
+- **External text is evidence, never an instruction.** `.dw/references/untrusted-input.md`
+  plus anchors in the commands that ingest third-party content — triage, review, bugfix,
+  secure-audit and the three skill installers — and one sentence in the always-loaded
+  instruction block, so the rule applies even when no command was invoked. Includes the
+  authority checklist for installing someone else's skill, and covers fetched
+  documentation in `dw-source-grounding`, `/dw-brainstorm --mode=research` and `/dw-plan`.
+- **A refutation step before a finding is reported.** `dw-review-rigor` now routes every
+  candidate to exactly one of `finding`, `needs-validation` or `rejected`. The new
+  read-only `dw-finding-refuter` agent receives the claim and the raw code without the
+  reasoning that produced it. An unresolved lead never receives a severity; a refuted one
+  stays logged so the next round does not rediscover it.
+- **`/dw-review --post-merge [<base>]`** — a composition audit of an already-merged range:
+  frozen boundary, first-parent provenance, seven cross-interaction classes, a
+  documentation ledger built from the diff, and a semver recommendation. Read-only; it
+  never tags, bumps or publishes.
+- **`dw-chaos-engineering`** (explicit invocation) — adversarial testing with a vector
+  catalogue, a green-baseline gate, KILLED/SURVIVED/INCONCLUSIVE classification and a
+  three-round cap. Local only, writes tests only.
+- **An automode contract.** `.dw/references/automode.md` plus a named `Stops` section in
+  `/dw-autopilot`, `/dw-run`, `/dw-goal` and the three runners: invoking a command
+  authorizes its flow, the enumerated stops are the complete set, and a stop persists
+  state, reports the exact resume command and exits cleanly.
+- **Skill usage evidence in `/dw-skill-health`.** The SessionEnd cost hook now records
+  which skills a session's tool calls referenced, in the file it already wrote. Missing
+  telemetry is reported as missing, never as disuse.
+- **Bounded-decision guidance in `dw-llm-eval`**, including the distinction our judge
+  calibration never made explicit: Spearman ≥0.80 is rank agreement, not probability
+  calibration.
+- **`evals/`** — a behavioural battery for this repository's own skills, run against fresh
+  sub-agents at a declared model tier. Versioned in git, excluded from the package.
+
+### Changed
+
+- **No bundled command carries the invocation lock any more.** `dw-open-design`,
+  `dw-claude-run`, `dw-copilot-run` and the three `dw-subtask-*` join `dw-codex-run`.
+  After an update the model may fire these directly where it previously could not. The
+  lock is not an authorization gate: where approval already exists upstream it only made
+  the user retype a command they had authorized. The runners' real gates are unchanged —
+  dedicated worktree, never the main checkout, never a merge, dual evaluation and the STOP
+  at the gate.
+- `security-review`'s fp-check gains a third verdict: reachability that cannot be
+  established either way is `needs-validation`, with no severity, rather than drifting into
+  blocking or advisory.
+- A candidate whose deciding environment is unavailable stays unresolved instead of being
+  promoted or dropped.
+
+### Fixed
+
+- `dw-review-rigor` pointed prior-round awareness at `.dw/spec/prd-*/reviews/`, a directory
+  no command has ever written. Reviews live in `<target>/QA/` and `<target>/review/`.
+- `<AUDIT>` was referenced nine times across the runners without ever being resolved. It is
+  `.dw/cli-run`, which `init` has been creating all along.
+- `autopilot-state.json` had no directory anywhere in the repository. It is
+  `.dw/autopilot-state.json`.
+- The constitution installer printed "All 10 principles start at `severity: info`". The
+  template has eleven, and two ship at `high`.
+- `security-review` appeared twice in `/dw-review`'s complementary skills.
+- The git guardrails hook now also denies `filter-branch`, `reflog expire`, `gc --prune`,
+  `stash drop`, `stash clear`, `branch -M` and `update-ref -d`. `rebase` and
+  `commit --amend` are deliberately left out — routine on unpushed work, and a command line
+  cannot tell pushed from unpushed.
+- The ecosystem comparison's title and attribution chain: the adversarial-verification
+  model originates in `cloudflare/security-audit-skill` (MIT) and reached this project
+  through `akitaonrails/my-skills`.
+
+## [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

package/README.md

@@ -42,13 +42,13 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v2.2.0 ships **41 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. |
@@ -63,7 +63,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-brainstorm "idea"`** | Refine a concrete idea before PRD. Flags: `--onepager` (durable artifact), `--council` (multi-advisor debate), `--research` (multi-source cited research). |
 | **`/dw-plan "feature"`** | PRD → TechSpec → Tasks sequentially with checkpoints. Stages: `prd`, `techspec`, `tasks`. Mandatory clarification questions, source-grounding, constitution gate, final consistency check. |
 | **`/dw-run [task-id]`** | Execute tasks. Default: all pending in dependency order with wave-based parallel dispatch. Single-task: pass an ID. `--resume` continues an interrupted plan. |
-| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`), `--since <ref>` (ad-hoc review from a verified comparison point). |
+| **`/dw-review`** | Level 2 (PRD coverage mapping) + Level 3 (code quality). Hard gates on dw-verify PASS, secure-audit, constitution violations. Every candidate finding passes a refutation step before it is reported; an unresolved lead becomes `needs-validation` with no severity, and a refuted one stays logged. Flags: `--coverage-only`, `--code-only`, `--bugfix <slug>` (review a bugfix at `.dw/bugfixes/<slug>/`), `--since <ref>` (ad-hoc review from a verified comparison point), `--post-merge [<base>]` (composition audit of an already-merged range — cross-PR interaction, documentation ledger, semver recommendation; never tags or publishes). |
 | **`/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. |
@@ -82,7 +82,7 @@ Use these when you want step-by-step control instead of `/dw-autopilot`.
 | **`/dw-functional-doc`** | Maps screens + user flows into a functional doc, validated end-to-end with Playwright. Uses the WSL-resilient browser resolver and can capture guided functional video evidence. |
 | **`/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-skill-health`** | Audits installed skills and agents for bloat, duplication, and missing references, plus usage evidence: which installed skills have not fired inside a declared, observed window. Missing telemetry is reported as missing, never as disuse. |
 | **`/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/`. |
@@ -100,9 +100,9 @@ These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help
 | **`/dw-intel "question"`** | Query codebase intelligence (`.dw/intel/`). `--build` (re)creates the index. | `/dw-plan`, `/dw-review`, `/dw-bugfix` |
 | **`/dw-secure-audit`** | **Security Gate** (phase after review/QA, before commit/PR): OWASP + Semgrep SAST (diff/generated code) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block (secrets have no ADR escape). Flags: `--scan-only`, `--plan`, `--execute`. See [docs/security-gate.md](docs/security-gate.md). | `/dw-review`, `/dw-autopilot` (explicit step), enforced by `/dw-generate-pr` |
 | **`/dw-goal "<objective>"`** | Durable objective contract. Uses Codex native `/goal` when available and `.dw/goals/` everywhere for Codex, Copilot, Claude Code, and OpenCode. | `/dw-autopilot` after planning |
-| **`/dw-claude-run`** | Fire `claude -p` (headless) in a dedicated git 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. | manual delegation step |
-| **`/dw-codex-run`** | Fire `codex exec` in a dedicated git 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. | manual delegation step |
-| **`/dw-copilot-run`** | Fire `copilot -p` (GitHub Copilot CLI) in a dedicated git 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. | manual delegation step |
+| **`/dw-claude-run`** | Fire `claude -p` (headless) in a dedicated git 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. | `/dw-plan tasks` cross-tool assignment, once approved; or manually |
+| **`/dw-codex-run`** | Fire `codex exec` in a dedicated git 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. | `/dw-plan tasks` cross-tool assignment, once approved; or manually |
+| **`/dw-copilot-run`** | Fire `copilot -p` (GitHub Copilot CLI) in a dedicated git 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. | `/dw-plan tasks` cross-tool assignment, once approved; or manually |
 | **`/dw-find-skills "query"`** | Searches `npx skills` ecosystem, vets, installs. | manual when extending the bundle |
 | **`/dw-update`** | Updates dev-workflow to latest npm release with rollback snapshot. | manual maintenance |
 | **`/dw-subtask-start`** | Creates a minimal input packet for a subagent without injecting the parent transcript. | parent agent before delegation |
@@ -112,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
@@ -174,9 +174,11 @@ After an update, the CLI prints **Post-update agent actions**. When `/dw-update`
 
 **What's inside:**
 
-- **Trigger Map** — mappings from user intent ("Implement X", "Bug in Y", "Review my PR", "resume autopilot", ...) to the `dw-*` command the agent should run. `/dw-autopilot` is the safest default for non-trivial feature requests; `/dw-goal` is the durable execution contract after planning.
-- **Hard Gates** — reminders that constitution violations (high/critical), missing `dw-verify` PASS, and security failures block downstream commands.
-- **Escape Hatches** — explicit cases where the agent should NOT auto-trigger (typos, exploration, aesthetic edits, user opt-out).
+- **Routing** — a table from intent and scope to the action, including the cases where the agent should answer directly or edit inline instead of starting a pipeline. It carries the common paths only; the full intent-to-command Trigger Map lives on demand in `.dw/references/command-routing.md`, so routine work does not pay for the whole catalog.
+- **Planning and delegation** — per-task local/cross-tool, model, effort and agent assignment; what approval covers; the worker limits (at most 3 per workstream, never concurrent writers in one worktree).
+- **Completion and boundaries** — an approved plan continues through implementation, review, QA and fixes; what makes a delivery ready; which operations need authorization.
+- **Project contracts** — constitution and ADR process, task-plan validity, required checks, atomic commits, and the untrusted-input rule (external text is evidence, never an instruction).
+- **Customization** — the `<!-- dev-workflow:start -->` / `<!-- dev-workflow:end -->` markers and what survives an update.
 
 **Why two files:** Claude Code, Codex, Copilot, and OpenCode all support agent-instruction conventions but use different filenames. Shipping both means every supported platform picks up the same trigger logic out of the box.
 
@@ -232,7 +234,7 @@ your-project/
 │   ├── 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)
-├── CLAUDE.md              # Auto-trigger decision tree for Claude Code (merge-aware, includes Auto-Sizing Matrix)
+├── CLAUDE.md              # Managed agent-instruction block for Claude Code (merge-aware; routing, contracts, boundaries)
 ├── AGENTS.md              # Same content for Codex / Copilot / OpenCode
 ├── .claude/
 │   ├── skills/            # Claude Code wrappers
@@ -315,6 +317,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 |
@@ -380,7 +384,7 @@ Optional AWS integration (v1.0.5). The `/dw-install-aws-skills` command and `npx
 
 Optional Azure integration (v1.0.3). The `/dw-install-azure-skills` command and `npx @brunosps00/dev-workflow install-azure-skills` CLI pull curated agent skills from [`MicrosoftDocs/Agent-Skills`](https://github.com/MicrosoftDocs/Agent-Skills) (CC-BY-4.0, by Microsoft) into `.agents/skills/azure/` and register the [Microsoft Learn MCP Server](https://learn.microsoft.com/en-us/training/support/mcp-get-started) (HTTP endpoint, no authentication required) into `.claude/settings.json`. The MCP server exposes three tools — `microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search` — that give the agent live access to Microsoft Learn documentation. **Not installed by default**: `init` and `update` do not touch `.agents/skills/azure/` or register the MCP. Users explicitly invoke the command when they begin Azure-focused work. The 10 categories (Compute, Data & Storage, AI & ML, Networking, Identity & Security, DevOps, Observability, Integration, Architecture, All) are dev-workflow's curated grouping over the 200+ skills in the upstream repo; the `--products=<csv>` flag lets advanced users pick individual services. Re-running the command refreshes from upstream; `dev-workflow update` deliberately does not touch these external skills so the Microsoft upstream release cadence is decoupled from the dev-workflow npm release cadence. Skills are copied verbatim from the upstream repo (CC-BY-4.0 permits this with attribution); the agent-facing `.dw/references/azure-mcp-instructions.md` is a clean-room adaptation of Microsoft's "Set instructions" guidance.
 
-Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex) formalized in `CLAUDE.md`/`AGENTS.md` above the Trigger Map; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
+Session continuity and adaptive routing patterns adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) by Felipe Rodrigues (CC-BY-4.0, v1.0.2). Eight patterns were absorbed selectively after a comparative analysis confirmed that the majority of the skill duplicates existing dev-workflow capabilities (PRD/TechSpec/Tasks pipeline, constitution discipline, source-grounding, two-tier memory, verify-before-complete, brownfield mapping, sub-agent delegation, atomic commits). Patterns adopted: (1) `STATE.md` cross-session working memory at `.dw/STATE.md` + new `/dw-pause` and `/dw-resume` commands; (2) Auto-Sizing Matrix (Small/Medium/Large/Complex), formalized in `CLAUDE.md`/`AGENTS.md` at the time and **since removed** — the managed block now routes on intent and scope instead of a size bracket, and the fixed matrix was dropped when the block was compacted; (3) Concerns Map (`.dw/rules/concerns.md`) generated by a new Step 9 in `/dw-analyze-project` and consumed on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix`; (4) Context Budget discipline as a new section in `dw-memory` with reference `dw-memory/references/context-budget.md`; (5) Interactive UAT walkthrough as `/dw-qa --uat`; (6) Quick-mode persistence — bugfixes now land in `.dw/bugfixes/NNN-<slug>/{TASK.md, SUMMARY.md, fix-report.md}` and remain queryable via `/dw-intel`; (7) Safety valve in `/dw-bugfix` Step 5.0 that forces escalation to `/dw-plan` when scope exceeds 5 tasks or has cross-dependencies; (8) Cross-skill awareness — `/dw-intel --build` now indexes `.dw/bugfixes/*/SUMMARY.md` into `bugfixes.json`, and `dw-codebase-intel` documents the new `bugfix-history` and `risk-area` query shapes. Patterns explicitly REJECTED: `.specs/` directory structure (dev-workflow uses `.dw/`), Knowledge Verification Chain (already covered by `dw-source-grounding`), Specify/Design/Tasks/Execute naming (dev-workflow keeps PRD/TechSpec/Tasks/Run), Skill Integrations pattern with mermaid-studio/codenavi delegation, and literal text copying (everything is clean-room reimplementation from the conceptual patterns; CC-BY-4.0 attribution is for derivative ideas, not borrowed prose).
 
 Patterns from [`mattpocock/skills`](https://github.com/mattpocock/skills) by Matt Pocock (MIT) were integrated **without adding any new public command** (the public command count is unchanged): (1) **grill** — a native, stateful alignment session reimplemented (clean-room, no upstream prose copied) from [`skills/engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md), [`skills/productivity/grilling`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md), and [`skills/engineering/domain-modeling`](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md). It is the `/dw-brainstorm` `grill` mode, backed by two **internal, non-exported** bundled skills — `dw-grilling` (dependency-ordered decision-tree interview, one decision per turn with a recommended answer, facts looked up rather than asked, shared-understanding gate) and `dw-domain-modeling` (canonical glossary, fuzzy/overloaded-term challenge, rare ADRs). Intentional `.dw/` differences: the curated glossary lives in **`.dw/domain/**`** (not upstream's root `CONTEXT.md`, and not our auto-generated `.dw/rules/`); Grill requires **one explicit authorization** before it writes and is mutually exclusive with the option matrix; alignment emits an idea one-pager at **schema `1.1`** consumed by `/dw-plan` without re-asking; and ADR creation is gated on the 3-criteria test and routed via `/dw-adr --scope=repo|prd`. (2) **prototype** → `/dw-brainstorm` `prototype` mode (LOGIC terminal app or UI variant dispatch); (3) **improve-codebase-architecture** → `dw-simplification/references/deep-modules.md` (deletion test, locality, leverage, seam, adapter diagnostic invoked by the `refactor-audit` mode); (4) **zoom-out** → one-paragraph guidance in `agent-instructions.md`. The same line of work also collapses `/dw-brainstorm`'s six legacy flags into a single full-flow entry point that auto-dispatches modes based on project signals.
 
@@ -433,7 +437,7 @@ On the next `npx @brunosps00/dev-workflow update`, the following happens automat
 
 ### CLAUDE.md / AGENTS.md updates
 
-The Trigger Map block (between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->`) refreshes automatically on update with the v1.0.0 command surface. Your edits outside the markers are preserved.
+The managed instruction block (between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->`) refreshes automatically on update with the v1.0.0 command surface. Your edits outside the markers are preserved.
 
 ### Skill conventions
 
@@ -442,3 +446,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', 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', 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', 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,41 +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', 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: 'Trigger when user asks for periodic progress reports ("report every 10 minutes", "keep me posted while this runs"). Timestamped done / doing / remaining report at a fixed cadence (default 10m, --every <N>m), appended to .dw/reports/YYYY-MM-DD.md; silent while blocked, final report + auto-disarm when the work ends. Auto-armed by dw-run, dw-autopilot, and the dw-cli-run adapters.' },
+    { 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-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> / --post-merge <base>.' },
     { 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-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-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 modules; reports usage evidence so an idle skill is named with its observed window, never guessed.' },
+    { name: 'dw-subtask-start', description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
+    { name: 'dw-subtask-complete', description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
+    { name: 'dw-subtask-resume', 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: 'Worktree lifecycle for delegated work: create prepared (../<project>-<slug> + install/build prep), list with verdicts (REMOVABLE / KEEP:unmerged / KEEP:dirty / KEEP:in-use), clean only what is proven merged and clean (dry-run by default), merge in the safe ff-only order and remove in the same turn. Never --force. Backed by .dw/scripts/lib/worktree-gc.mjs; used by the dw-*-run adapters, /dw-pause, and /dw-harness-audit.' },
+    { 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', description: 'Executa task aprovada pela CLI Claude em worktree dedicado; retorna sessão durável e evidências ao parent.' },
+    { name: 'dw-codex-run', 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', 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.' },
@@ -60,29 +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', 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: 'Trigger quando usuário pede report periódico de progresso ("report de 10 em 10 minutos", "me mantém informado enquanto isso roda"). Report carimbado com data/hora de feito / fazendo / falta em cadência fixa (default 10m, --every <N>m), anexado em .dw/reports/YYYY-MM-DD.md; silencioso enquanto bloqueado, report final + auto-desarme quando o trabalho termina. Auto-armado por dw-run, dw-autopilot e pelos adapters dw-cli-run.' },
+    { 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-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> / --post-merge <base>.' },
     { 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-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-worktree', description: 'Ciclo de vida de worktrees de delegação: cria preparada (../<projeto>-<slug> + prep de install/build), lista com vereditos (REMOVABLE / KEEP:unmerged / KEEP:dirty / KEEP:in-use), limpa só o que está provadamente mergeado e limpo (dry-run por default), mergeia na ordem segura ff-only e remove no mesmo turno. Nunca --force. Apoiado em .dw/scripts/lib/worktree-gc.mjs; usado pelos adapters dw-*-run, /dw-pause e /dw-harness-audit.' },
+    { 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 velhos; reporta evidencia de uso, nomeando skill ociosa com a janela observada em vez de chutar.' },
+    { name: 'dw-subtask-start', description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
+    { name: 'dw-subtask-complete', description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
+    { name: 'dw-subtask-resume', 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.' },
+    { 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.' },
   ],
 };
@@ -91,8 +91,11 @@ const PLATFORMS = {
   claude: {
     dir: '.claude/skills',
     // opts.userInvoked → emit disable-model-invocation: true so Claude Code never
-    // auto-fires hidden/internal commands (e.g. the worktree runners); the user
-    // still invokes them explicitly with /<name>.
+    // auto-fires that command; the user invokes it explicitly with /<name>.
+    // No bundled command sets this today (see docs/skills-ecosystem-comparison.md §2:
+    // the lock is not a substitute for an authorization gate). It is kept for a
+    // consumer's own commands, and test/wrappers.test.js exercises it directly so the
+    // path cannot rot unnoticed while unused.
     wrapperTemplate: (name, description, opts = {}) => `---
 name: ${name}
 description: "${description.replace(/"/g, '\\"')}"${opts.userInvoked ? '\ndisable-model-invocation: true' : ''}

package/lib/doctor.js

@@ -207,7 +207,7 @@ function checkMcp(projectRoot, issues) {
 
 function checkHooks(projectRoot, issues, warnings) {
   // Hook scripts (copied from scaffold/scripts/ into .dw/scripts/).
-  for (const script of ['git-guardrails.mjs', 'statusline.mjs']) {
+  for (const script of ['git-guardrails.mjs', 'statusline.mjs', 'session-cost.mjs']) {
     const file = path.join(projectRoot, '.dw', 'scripts', 'hooks', script);
     if (!fs.existsSync(file)) issues.push(`Missing hook script: ${path.relative(projectRoot, file)}`);
   }

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++;
@@ -419,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.2.0",
+  "version": "2.4.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"