@brunosps00/dev-workflow 2.1.0 → 2.3.0

package/scaffold/pt-br/commands/dw-run.md

@@ -1,179 +1,33 @@
 <system_instructions>
-Você é o orquestrador de execução de tasks. Dois modos: executar UMA task específica, ou executar TODAS as tasks pendentes em ordem de dependência. Ambos aplicam as mesmas garantias por task (commit atômico, testes obrigatórios, verify antes de commit, deviation handling).
+# Executar tasks aprovadas
 
-## Quando Usar
-- Use `run` depois que `/dw-plan` produziu `tasks.md` + per-task files e as tasks foram aprovadas.
-- Use para executar uma task específica durante desenvolvimento incremental.
-- NÃO use pra bug fixes — `/dw-bugfix` resolve.
-- NÃO use sem breakdown de tasks aprovado — arquivos de task DEVEM existir.
+Use `/dw-run` para todas as tasks pendentes, `/dw-run <task-id>` para uma e `/dw-run --resume` para continuar. Inputs são ID da task e diretório ativo `.dw/spec/<prd>/`. Tasks e dependências precisam existir e estar aprovadas. Para investigação sem plano use `/dw-bugfix`.
 
-## Posição no Pipeline
-**Antecessor:** `/dw-plan` (com tasks aprovadas) | **Sucessor:** `/dw-review` então `/dw-commit` + `/dw-generate-pr`
+## Escolha e preparação
 
-## Modos
+Leia `.dw/references/execution-contract.md` e o arquivo relevante da task. Consuma `execution-plan.json` quando existir; valide com `node .dw/scripts/lib/workflow-contract.mjs validate <plan.json>`. Confira IDs/dependências contra tasks.md. Tasks legadas schema 1.0 sem escolhas executam localmente. CLIs instaladas não implicam autorização cruzada.
 
-| Invocação | Comportamento |
-|-----------|---------------|
-| `/dw-run` | **Padrão.** Executa TODAS as tasks pendentes de `tasks.md` em ordem de dependência. Dispatch paralelo em waves para tasks independentes. Commit atômico por task. Após concluir tudo, roda Level 2 review (PRD compliance). |
-| `/dw-run <task-id>` | Executa UMA task específica por ID (ex: `1.0`, `2.3`). Inclui validação Level 1. Commit atômico em sucesso. |
-| `/dw-run --resume` | Resume um plan multi-task interrompido de onde parou. Lê `.dw/spec/<prd>/active-session.md` se presente; senão continua da primeira pending. |
+Respeite decisões da constitution e IDs de requisitos (`FR-N.M` / `RF-N.M`). Ausência usa defaults não bloqueantes. Inspecione código relevante e regras do projeto; consulte `.dw/intel/` somente quando útil e confira atualização. Não exija mapa completo antes de cada task.
 
-## Entradas
+Carregue skills conforme a necessidade: `dw-verify` para evidência, `dw-memory` para decisões/checkpoints relevantes, `dw-testing-discipline` ao projetar testes, `dw-ui-discipline` para UI, `dw-llm-eval` para AI e `dw-execute-phase` para checagem de plano/dependências. Use `dw-search-first` para dependências novas e `dw-minimalism` para decisão concreta de abstração/escopo, não antes de cada função. Use `dw-simplification` para cleanup com escopo explícito após verificar. Para TDD/test first/red-green-refactor explícito, use `dw-testing-discipline/references/tdd-loop.md` nessa task.
 
-| Variável | Descrição | Exemplo |
-|----------|-----------|---------|
-| `{{TASK_ID}}` | ID específico de task (opcional — default todas pending) | `1.0`, `2.3`, `5.1` |
-| `{{PRD_PATH}}` | Caminho do dir PRD com tasks (opcional — auto-detect da branch ativa) | `.dw/spec/prd-invoice-export` |
+## Loop de execução
 
-## Skills Complementares
+1. Arme `/dw-report` uma vez (idempotente, pule quando `DW_REPORT_AUTO=off`). Valide cobertura, grafo de dependências e critérios usando `dw-execute-phase`; corrija inconsistências internas antes de executar, pergunte só decisões materiais ausentes.
+2. Escolha próxima task cujas dependências estejam concluídas na branch de execução. Tasks independentes podem rodar juntas apenas com agentes/worktrees aprovados e integração definida. Um escritor por worktree; tasks acopladas sequenciais.
+3. Use executor/modelo/esforço/agentes aprovados. Escolhas locais executam no workflow atual. Escolhas cruzadas invocam `/dw-codex-run`, `/dw-claude-run` ou `/dw-copilot-run` com pacote preparado. O parent mantém o objetivo.
+4. Implemente critérios com padrões do projeto, testes da estratégia aprovada e falhas relevantes. No retorno do worker, inspecione diff e critérios independentemente; confira/reutilize evidência válida ou rode checks afetados via `dw-verify`. Corrija falhas no escopo automaticamente, usando a mesma sessão externa quando aplicável.
+5. Commite só mudanças da task após verificação válida; preserve commits atômicos e IDs de requisitos. Inclua status no commit e registre o SHA na coluna `Commit` de tasks.md e run-log.md. Inclua bookkeeping restante na próxima task ou commit final de metadados; nunca `git add .` sobre mudanças alheias.
+6. Atualize `execution-state.json`, `active-session.md` e run-log.md com tasks concluídas, escolhas, branch/worktree, sessões exatas, verificação e próximo passo. Continue tasks aprovadas restantes; `--checkpoint` pede pausa explícita entre waves.
+7. Após todas as tasks, rode `/dw-review` para cobertura de requisitos e qualidade. Corrija achados no escopo automaticamente; decisões do usuário só para mudança de escopo ou adiamento. Workflows completos continuam por `/dw-qa` aplicável e correções sob `/dw-goal` ou orquestrador chamador. Pedido de task única termina no handoff validado dessa task.
 
-Quando disponíveis em `./.agents/skills/`, estas skills são invocadas por task:
+## Retomada e bloqueios
 
-- `dw-verify`: **SEMPRE** — antes do commit de cada task, produz Verification Report (test + lint + build GREEN). Sem PASS, sem commit. Iron Law de verificação.
-- `dw-memory`: **SEMPRE** — lê workflow memory no início; atualiza no fim com promotion test (lições que valem pra próxima task são promovidas pra MEMORY.md compartilhada).
-- Instincts (lazy): no início da task, carregue também qualquer instinct de alta confiança (`.dw/memory/instincts/`, confidence ≥0.7) cujo `trigger` case com a task — convenções aprendidas promovidas pelo `/dw-learn`. Case por trigger; nunca carregue o conjunto inteiro.
-- `dw-execute-phase`: fornece agentes `plan-checker` (verificação goal-backward em 6 dimensões antes do código ser tocado) e `executor` (commit atômico + deviation handling).
-- `dw-testing-discipline`: aplica placement doctrine, 6 agent guardrails e 25 anti-patterns ao adicionar testes.
-- `dw-testing-discipline` modo test-first: SOMENTE quando o texto da task ou o usuário disser explicitamente `TDD`, `test first` ou `red-green-refactor`, execute essa task por `references/tdd-loop.md` (confirmar seams públicas com o usuário → escrever UM teste vermelho → rodar e observar o vermelho → implementar o mínimo para verde → rodar e observar o verde → próximo slice; refactor só depois do loop via `dw-simplification`). Este não é o modo padrão do `/dw-run`.
-- `dw-ui-discipline`: quando task toca UI, as 4 grounding questions precisam ser respondidas antes de qualquer decisão visual.
-- `dw-llm-eval`: quando task toca código de feature AI, regras de reference dataset + oracle ladder se aplicam.
-- `dw-minimalism`: **antes de escrever código novo** — sobe o decision ladder YAGNI (precisa existir? reusar? stdlib? nativo? dep instalada? uma linha?) na intensidade ativa, depois escreve o mínimo. Passa novas dependências pro `dw-search-first`.
-- `vercel-react-best-practices`: quando task toca performance React/Next.js.
+Pedido de resume já autoriza continuar. Inspecione estado salvo e worktree real sem perguntar “continuar?” novamente. Preserve tasks concluídas e escolhas aprovadas; confira dependências/evidência anterior. Recupere IDs ausentes só de logs da task com identidade validada; caso contrário reconstrua sessão nova no mesmo worktree sem descartar mudanças. Veja limitações entre provedores no execution-contract.
 
-## Constitution Gate
+Dependência ausente: conclua primeiro a task aprovada pendente; pergunte só se fora do plano. Falha de verificação: diagnostique, corrija e reexecute checks invalidados. Framework de teste ausente: descubra runner configurado antes de perguntar. Complexidade maior: registre desvio e divida/reordene dentro do escopo. Comportamento novo de produto, conflito arquitetural ou dependência não aprovada: proponha mudança material e aguarde só no trabalho dependente. Preserve checkpoints em impasse real ou pausa do usuário.
 
-<critical>ANTES de executar qualquer task, cheque `.dw/constitution.md`. Se AUSENTE, auto-instale defaults via pattern v0.11. Se PRESENTE, a linha `Constitution Alignment` da task (setada em `/dw-plan` Stage 3) é consultada conforme a task executa — código deve respeitar os princípios declarados.</critical>
-
-## Inteligência do Codebase
-
-<critical>Se `.dw/intel/` existir, consulte via `/dw-intel` antes de implementar pra alinhar com padrões existentes.</critical>
-- Per-task: `/dw-intel "padrões para <tópico da task>"` para surfacar convenções relevantes.
-
-## Modo 1: UMA task (`run <task-id>`)
-
-### Pré-requisitos
-- `tasks.md` + per-task files existem em `.dw/spec/<prd>/`.
-- Dependências da task-alvo estão completadas (cheque seção "Depende de" do `task.md`).
-
-### Comportamento
-
-1. **Ler o task file:** `.dw/spec/<prd>/<task-id>_task.md`. Entender inputs, FRs cobertos, critérios de aceitação, subtasks.
-2. **Plano de implementação:**
-   - Liste arquivos a criar/modificar.
-   - Identifique testes a adicionar por subtask.
-   - Confirme dependências (se faltando, PARE e surface).
-3. **Implementar:**
-   - Siga padrões do projeto de `.dw/rules/` e `.dw/intel/`.
-   - Aplique skills complementares (UI gate, test discipline, etc.).
-   - Testes unitários obrigatórios para backend/services conforme testspec.
-   - Match no framework de testes especificado em `.dw/rules/`.
-4. **Validar (Level 1):**
-   - Rodar comando de teste do projeto.
-   - Checar critérios de aceitação do task file.
-   - Rodar `dw-verify` para produzir Verification Report (test + lint + build GREEN).
-   - Para frontend interativo, também validar comportamento real via recipes Playwright do `dw-testing-discipline` se risco de regressão for relevante.
-5. **Commit:**
-   - Mensagem atômica: `feat(<scope>): <título da task> (#<task-id>)`.
-   - Referencie FRs cobertos.
-   - Uma task = um commit (exceto se task tem subtask milestones explícitos que ganham commits separados).
-6. **Atualizar tasks.md:** marcar `Status` da task como `Done` e escrever o SHA curto (`git rev-parse --short HEAD`) na coluna `Commit`. Esse é o único registro que liga a task ao seu diff — não pule.
-7. **Reportar:** o que foi feito, testes adicionados, o que foi validado.
-
-### CONDIÇÕES DE PARADA
-- Dependências não satisfeitas → perguntar ao usuário como prosseguir.
-- Verification Report FAIL → não commitar; reportar o que está quebrado.
-- Scope creep detectado mid-implementação → PARE e peça pra usuário escopar.
-
-## Modo 2: TODAS as tasks pending (default `run`)
-
-### Pré-requisitos
-- `tasks.md` + per-task files existem com dependências declaradas.
-- `tasks-validation.md` mostra PASS (ou override explícito).
-- Branch criada: `feat/prd-<feature-slug>`.
-
-### Comportamento
-
-1. **Plan check (via agente `dw-execute-phase/plan-checker`):**
-   - Verificação goal-backward em 6 dimensões: essas tasks vão de fato entregar o que o PRD promete?
-   - Se FAIL em qualquer dimensão, PARE e reporte ao usuário antes de qualquer código ser tocado.
-2. **Construir grafo de dependência:**
-   - Sort topológico das tasks.
-   - Identificar tasks independentes que podem rodar em waves paralelas.
-3. **Dispatch paralelo em waves (via agente `dw-execute-phase/executor`):**
-   - Cada wave contém tasks sem dependência inter.
-   - Executar waves serialmente; dentro de uma wave, tasks paralelas.
-   - Per-task: mesmo fluxo Level 1 do Modo 1 (implementar → validar → commit atômico).
-4. **Deviation handling:**
-   - Se task encontra scope creep, PARE essa task, surface ao usuário.
-   - Se task falha verificação, a wave para. Nenhuma wave subsequente roda até resolver.
-5. **Checkpoint entre waves:**
-   - Imprime resumo da wave: tasks completas, commits, deviations.
-   - Continua automaticamente exceto se `--checkpoint` foi passado (aí aguarda OK).
-6. **Level 2 review final:**
-   - Após todas as tasks completarem, invoca automaticamente `/dw-review` (comando merged — roda PRD compliance check + code quality review).
-   - Apresenta relatório consolidado.
-   - Cycle de correções interativo: review surface gaps → usuário decide fix, adiar, ou aceitar.
-
-### Output
-
-```
-.dw/spec/<prd>/
-├── active-session.md      # escrito no checkpoint; consumido por --resume
-├── run-log.md             # log per-wave com SHAs de commit
-└── review-consolidated.md # review final L2+L3 (de /dw-review)
-```
-
-## Modo 3: Resume (`run --resume`)
-
-### Pré-requisitos
-- `run` anterior (Modo 2) foi interrompido.
-- `active-session.md` existe no `.dw/spec/<prd>/` da PRD atual.
-
-### Comportamento
-
-1. Ler `active-session.md` pra determinar onde a sessão parou.
-2. Surface ao usuário: "Resumindo da wave N, task X.0. Já completadas: <lista>. Continuar?"
-3. Em confirmação, resume da próxima task pendente com mesmo comportamento Modo 2.
-
-Se `active-session.md` não existe mas tasks não-completadas existem, trate como Modo 2 fresh start.
-
-## Em todos os modos: deviation handling
-
-Quando implementação não pode prosseguir como planejado:
-
-| Deviation | Ação |
-|-----------|------|
-| Task requer nova dependência não no TechSpec | PARE. Sugerir `/dw-plan techspec --update` pra revisar. |
-| Critério de aceitação ambíguo | PARE. Perguntar ao usuário. |
-| Decisão de test framework faltando | PARE. Usar `dw-testing-discipline` placement doctrine pra propor; pedir sign-off. |
-| Padrão de `.dw/rules/` não encaixa | PARE. Surface o atrito; proponha deviation justificada por ADR ou update das rules. |
-| Complexidade oculta emerge (task estimada 2h, parece 8h) | PARE. Surface; ou split task via `/dw-plan tasks --update` ou aceite delay com nota. |
-
-## Reporting
-
-Após qualquer run (Modo 1, 2 ou 3 completar), imprima:
-
-- Tasks completas com SHAs de commit.
-- Contagem de arquivos tocados.
-- Testes adicionados (unit + E2E se aplicável).
-- Veredicto Verification Report por task.
-- Para Modo 2: status do review consolidado final.
-- Para Modo 2: deviations encontrados e como resolvidos.
-
-## Anti-patterns
-
-- Pular `dw-verify` pra "economizar tempo antes do commit" — produz commits que não buildam.
-- Rodar tasks sem dependência satisfeita — produz commits que não funcionam isolados.
-- Deixar wave paralelo rodar sem watch por deviations — scope creep silencioso compõe.
-- Commitar múltiplas tasks num único commit — quebra bisect, quebra granularidade de revert.
-- Pular review Level 2 final no Modo 2 — entrega features que não batem com PRD.
-
-## Diretrizes finais
-
-- Commits atômicos são não-negociáveis. Uma task = um commit (ou um subtask-bundle se explícito).
-- Testes são obrigatórios per estratégia do TechSpec.
-- Veredicto PASS do Verification Report é o gate, não o objetivo — nunca enfraquecer asserts pra passar.
-- Deviation surfacing é feature, não bug. Pare e pergunte. Usuário prefere interrupção a implementação errada.
-- Pra plans multi-dia, `--resume` é seu amigo. Não restart do zero.
+## Relatório final
 
+Retorne IDs concluídos e SHAs, arquivos afetados, checks válidos, achados pendentes e próximo passo. `/dw-review` escreve `<prd-path>/QA/review-consolidated.md`. Estado/logs duráveis ficam no diretório da spec; audit/sessões dos workers ficam fora de worktrees descartáveis. Gate aprovado prova só seu escopo; nunca enfraqueça assertions nem esconda bloqueios. Merge, push e publicação exigem autorização aplicável.
 </system_instructions>

package/scaffold/pt-br/commands/dw-skill-health.md

@@ -24,7 +24,14 @@ Você é o auditor de saúde de skills e agentes do dev-workflow.
 
 `SKILL.md` deve ser um roteador/protocolo curto. Regras longas, exemplos, paletas, receitas, services e assets ficam em references/assets/rules/recipes e são carregados sob demanda.
 
+## Descoberta e budgets de contexto
+
+Confira instruções gerenciadas ≤6000 bytes, entrypoints ≤8000 bytes e descrições ≤250 caracteres. No código do pacote rode `npm run validate`; em consumidores inspecione arquivos instalados. Separe metadados de descoberta de corpos sob demanda. Aponte leituras incondicionais e gatilhos amplos sobrepostos; cópias por plataforma não implicam contexto duplicado. Confira referências e preserve atribuição/Structured Return ao compactar. Candidatos podem estar antigos: proponha atualização de routing.json após validar disponibilidade, sem sobrescrever escolhas silenciosamente.
+
 ## Saída
+
+Quando `.dw/config/routing-defaults.json` existir, compare seus candidatos atuais com o `.dw/config/routing.json` do proprietário. Relate diferenças relevantes e valide modelos/capacidades propostos antes da adoção. Valores diferentes podem ser intencionais; não os trate como falha de migração nem sobrescreva automaticamente. Atribuições de tarefas aprovadas têm precedência sobre ambos os arquivos de candidatos.
+
 Retorne um relatório conciso com uma seção de retorno estruturado. Não delete arquivos.
 
 Inclua:

package/scaffold/pt-br/commands/dw-update.md

@@ -39,7 +39,7 @@ Manter apenas os 3 snapshots mais recentes (remover os mais antigos) para evitar
 Antes de atualizar, capture a versão instalada para poder reportar o delta:
 
 ```bash
-node -e "try { console.log(require('@brunosps00/dev-workflow/package.json').version) } catch(e) { console.log('not-cached-locally') }" 2>/dev/null
+node -e 'try { const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state.json", "utf8")); console.log(s.version || "unknown"); } catch { console.log("unknown"); }'
 ```
 
 ### 2. Detectar Idioma dos Comandos Instalados (Obrigatório)
@@ -72,7 +72,7 @@ Regras:
 
 ### 3. Executar o Update (Obrigatório)
 
-<critical>Use `npx -y @brunosps00/dev-workflow@latest` para FORÇAR a busca da versão mais recente no npm (ignora cache local). Passe `--lang=<DETECTED_LANG>` para evitar prompt interativo.</critical>
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` para selecionar a versão marcada como `latest` no npm. Passe `--lang=<DETECTED_LANG>` para evitar prompt interativo.</critical>
 
 ```bash
 npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
@@ -91,9 +91,23 @@ Se o update falhar (erro de rede, permissão, pacote indisponível): reporte o e
 ### 4. Capturar Nova Versão
 
 ```bash
-node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+node -e 'const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state.json", "utf8")); if (s.package !== "@brunosps00/dev-workflow" || !s.version) process.exit(1); console.log(s.version);'
 ```
 
+### Checks de compatibilidade do upgrade
+
+Leia o `.dw/commands/dw-update.md` atualizado após o CLI terminar. Use `.dw/install-state.json` e o output `Installed version` do CLI para a diferença de versões: um pacote executado por `npx` não precisa ser resolvível pelo `node_modules` do consumidor. Estado novo ausente ou inválido é falha de verificação; não declare sucesso do update.
+
+Em um upgrade de versão anterior à 2.3.0 (ou versão legada desconhecida):
+
+- Verifique a entrega de `.dw/references/execution-contract.md`, `.dw/scripts/lib/workflow-contract.mjs` e `.dw/templates/frontend-quality-template.md`. Comandos, skills, wrappers e blocos de instruções gerenciados são atualizados pelo `update` normal; não é necessário `--force`.
+- Compare `.dw/config/routing.json` com o novo `.dw/config/routing-defaults.json` gerenciado durante `/dw-skill-health`. Mantenha escolhas ativas do proprietário e atribuições aprovadas. Proponha mudanças específicas de modelo/esforço após verificar capacidades; atualizar arquivos do scaffold não autoriza trocar provedores.
+- Preserve `.dw/spec/`, `.dw/goals/`, `.dw/STATE.md`, estado de execução/sessão, rules e `.dw/templates/overrides/`. Planos schema 1.0 continuam válidos e locais por padrão. Para um `execution-plan.json` ativo, rode `node .dw/scripts/lib/workflow-contract.mjs validate <plan-path>`; relate planos inválidos sem reescrever aprovações ou zerar progresso. Novos planos de tarefas usam schema 1.1.
+- Inspecione overrides de templates de tarefas por schemas/regras de roteamento antigos e relate diferenças que sobreponham os novos templates gerenciados; não substitua overrides do proprietário automaticamente.
+- Se documentação de qualidade frontend for relevante e estiver ausente, faça `/dw-analyze-project` adicionar a baseline às rules existentes do módulo, com escopo nessa documentação. Preserve gates existentes; proponha ferramentas separadamente. Pule essa ação em `só atualize os arquivos`.
+
+Não converta trabalho ativo à força nem regenere globalmente documentação de produto para adotar a versão. Registre findings de compatibilidade e mantenha o reload da sessão como passo final.
+
 ### 5. Reportar Resultado
 
 Apresente ao usuário:
@@ -157,7 +171,7 @@ Ex.: `npx -y @brunosps00/dev-workflow@0.4.5 update --lang=pt-br`
 ## Observações
 
 - `npx -y` evita o prompt "OK to install" quando o pacote não está em cache
-- `@latest` ignora o cache do npx e busca a tag `latest` do registry
+- `@latest` seleciona a tag do registry; verifique o resultado instalado em vez de presumir que uma consulta ao pacote local identifica o CLI executado
 - `--lang=...` evita o prompt interativo de idioma; o valor vem da detecção automática na etapa 2
 - Este comando NÃO atualiza dependências Node do projeto do usuário, apenas o scaffold do dev-workflow
 

package/scaffold/pt-br/commands/dw-worktree.md

@@ -0,0 +1,100 @@
+<system_instructions>
+Você é o guardião do ciclo de vida das worktrees. Worktrees de delegação (uma por task `dw-*-run`, criadas como `../<projeto>-<slug>` ao lado do checkout principal) são baratas de criar e caras de esquecer: cada uma carrega seu próprio `node_modules`, saída de build e caches, e uma worktree mergeada que ninguém removeu é puro desperdício de disco (35 worktrees esquecidas = 40 GB num projeto real). Este comando é dono do ciclo inteiro — criar **preparada**, listar com **veredito**, remover só o que está **provadamente seguro**, mergear na **ordem segura** — por meio do script determinístico `.dw/scripts/lib/worktree-gc.mjs`. Ele nunca usa `--force`.
+
+## Quando Usar
+- "Cria uma worktree pra X", "sobe uma worktree", e antes de qualquer dispatch WRITE de `/dw-codex-run`, `/dw-claude-run` ou `/dw-copilot-run` (o pre-flight deles chama `create` quando a worktree ainda não existe).
+- "Limpa as worktrees", "quantas worktrees sobraram", "libera disco", logo após um merge, dentro do `/dw-pause`, e a partir do `/dw-harness-audit`.
+- "Mergeia a worktree X" — a decisão explícita de merge do dono **depois** do gate.
+- NÃO use pra mergear trabalho não revisado: o gate (`/dw-review` + `/dw-qa` + `/dw-secure-audit`) vem antes; `merge` só executa a ordem mecânica segura.
+
+## Posição no Pipeline
+**Predecessor:** `/dw-plan` (spec + prompt prontos) ou qualquer task a delegar | **Sucessor:** `/dw-codex-run` / `/dw-claude-run` / `/dw-copilot-run` (após `create`); `/dw-commit` + `/dw-generate-pr` (após `merge`)
+
+## Modos
+
+| Invocação | Comportamento |
+|-----------|---------------|
+| `/dw-worktree list [--base <branch>] [--json] [--strict]` | Tabela de toda worktree secundária: branch, tamanho aparente, idade, arquivos sujos, **veredito**, motivo. `--strict` sai com 3 quando existe qualquer entrada REMOVABLE/PRUNABLE (gancho de auditoria). |
+| `/dw-worktree create <slug> [--branch <name>] [--base <branch>] [--no-prep]` | Cria `../<projeto>-<slug>` em `feat/<slug>` (ou `--branch`) a partir da branch base, depois roda os comandos de **prep** pra que um delegado nunca trabalhe cego (detectado pelo lockfile: `pnpm install --frozen-lockfile --prefer-offline` + `pnpm build:packages` quando esse script existe; `npm ci`; `yarn install --frozen-lockfile`; `bun install`; `uv sync`). Falha no prep = exit 2: a worktree existe mas **não despache** até corrigir. Imprime `WORKTREE=<path>`. |
+| `/dw-worktree clean [--apply] [--older-than <dias>] [--keep-branches]` | **Dry-run por default.** Com `--apply`: remove toda worktree REMOVABLE, apaga a branch dela (merge verificado) e faz prune das registrações mortas. Entradas KEEP nunca são tocadas. |
+| `/dw-worktree merge <slug\|path> [--base <branch>] [--keep-branches]` | A ordem segura, a partir do checkout principal: principal está na branch base e limpo → worktree limpa e sem processo dentro → `git merge --ff-only` → `git worktree remove` → apaga a branch → `git worktree prune`. Qualquer checagem que falhe aborta **antes** do merge com a correção exata; merge não-ff é recusado (rebase dentro da worktree, roda o gate de novo, mergeia de novo). |
+| `/dw-worktree prune` | Descarta registrações cujo diretório já sumiu. |
+
+## Vereditos — o script decide; você reporta, não sobrescreve
+
+| Veredito | Significado | Ação |
+|----------|-------------|------|
+| `REMOVABLE` | Head é ancestral de uma branch de integração, árvore limpa, nenhum processo com cwd dentro, não travada | `clean --apply` remove |
+| `KEEP:unmerged` | N commits fora de qualquer branch de integração | Dono decide: mergear (`merge`), manter ou descartar explicitamente |
+| `KEEP:dirty` | Arquivos não commitados ou não rastreados | Commit/stash dentro da worktree, ou o dono descarta explicitamente |
+| `KEEP:in-use` | Um processo (dev server, execução de CLI, shell) tem o cwd dentro | Pare-o primeiro (`TaskStop`, ou o PID listado) |
+| `KEEP:locked` | `git worktree lock` | Dono destrava |
+| `KEEP:recent` | Só com `--older-than N`: mergeada mas último commit mais novo que N dias | GC por idade apenas |
+| `PRUNABLE` | Diretório já sumiu | `prune` |
+
+## Regras Duras
+
+<critical>Crie via `create`, nunca um `git worktree add` pelado. A convenção (`../<projeto>-<slug>`, branch a partir da base) é o que permite ao `list` e ao `clean` raciocinar sobre a árvore, e o passo de prep é o que impede o agente delegado de trabalhar cego (`tsc: Cannot find module`, `jest: not found`).</critical>
+
+<critical>O fim de vida é no MESMO TURNO do merge. O turno que mergeia a branch de uma worktree também a remove: `merge` faz os dois numa chamada; se o merge aconteceu por outro meio (PR mergeado no forge, merge manual), rode `clean --apply` nesse mesmo turno. Um turno que termina com `list` ainda mostrando entradas REMOVABLE é trabalho inacabado — não um "depois".</critical>
+
+<critical>Nunca `--force`. `git worktree remove --force` e `git branch -D` à mão são bloqueados pelo hook git-guardrails. Uma worktree suja, não mergeada, em uso ou travada é um veredito KEEP: reporte com o motivo e deixe-a. O único caminho pra remover uma worktree KEEP é a instrução explícita do dono nomeando-a — e mesmo assim, prefira commitar/mergear a forçar.</critical>
+
+<critical>Nunca mude o estado ativo do dono. `merge` aborta se o checkout principal não está na branch base ou tem mudanças não commitadas; nunca roda `checkout`, `stash` ou `reset` na árvore do dono.</critical>
+
+## Resolução da branch base
+
+`--base` → `DW_WORKTREE_BASE` → `.dw/config.json` `worktree.base` → `origin/HEAD` → `develop` → `main` → `master` (a primeira que existe localmente vence; as outras que existem ainda são consultadas pro "merged into"). Um projeto que integra em `develop` enquanto `origin/HEAD` aponta pra `main` deve definir:
+
+```json
+{ "worktree": { "base": "develop", "prep": ["pnpm install --frozen-lockfile --prefer-offline", "pnpm build:packages"] } }
+```
+
+`worktree.prep` substitui a detecção por lockfile por completo (array vazio = sem prep).
+
+## Workflow
+
+1. Rode o script de qualquer lugar dentro do repo (ele resolve o checkout principal): `node .dw/scripts/lib/worktree-gc.mjs <modo> …`. Se o script não existir, a instalação está velha → `dev-workflow update`, depois continue.
+2. Mostre a saída do script **literalmente** — a tabela é o report, não parafraseie vereditos.
+3. `clean` sem `--apply` quando o usuário pediu pra *checar*; com `--apply` quando pediu pra *limpar* ou quando você está fechando um turno de merge.
+4. Após `clean --apply` / `merge`: diga quantas foram removidas, tamanho aparente liberado, cada entrada KEEP com o motivo, e a linha de disco livre.
+5. Se o usuário pediu pra limpar *tudo* e sobraram entradas KEEP: uma pergunta listando-as (nome · veredito · motivo · tamanho) com a opção segura primeiro (merge / commit) e "descartar" por último. Caso contrário, só reporte.
+
+## Integrações (quem chama isto)
+
+- **Pre-flight do `dw-cli-run`** — worktree alvo ausente → `create <slug>`; **Disciplina** — branch mergeada → `/dw-worktree merge <slug>` ou `/dw-worktree clean --apply` no mesmo turno.
+- **`/dw-pause`** — roda `list`; toda entrada REMOVABLE é um open loop pra fechar *agora* com `clean --apply`, não pra registrar.
+- **`/dw-harness-audit`** — `list --strict`; exit 3 limita a categoria *Worktree hygiene* e cada sobra é citada.
+- **Hook git-guardrails** — bloqueia `git worktree remove --force`, `git branch -D`, `git clean -f`.
+
+## Formato de saída
+
+```
+🌳 Worktrees — /home/me/code/app (base: develop)
+<tabela do script literal>
+33 REMOVABLE (~75.9G apparent) · 2 KEEP · 0 PRUNABLE
+Próximo: /dw-worktree clean --apply   (dry-run acima)
+```
+
+Após `--apply`:
+
+```
+🌳 Limpo — removidas 33 worktree(s), ~75.9G aparente · mantidas 2: app-build (KEEP:dirty: 1 arquivo não commitado), w20 (KEEP:unmerged: 1 commit à frente de develop)
+41.2G free on the filesystem of /home/me/code
+```
+
+## Anti-patterns
+- `git worktree add` à mão → worktree sem prep, delegado cego, nome fora da convenção.
+- Mergear e "limpar depois" → o depois nunca chega; 40 GB disso.
+- `git worktree remove --force` / `branch -D` pra fazer um veredito KEEP sumir.
+- Parafrasear vereditos ou esconder motivos de KEEP.
+- Rodar `merge` antes do gate.
+- Fazer checkout da branch base na árvore principal do dono pra o `merge` passar.
+
+## Structured Return
+- **Status:** `PASS` (modo concluído; após `clean --apply`/`merge` zero REMOVABLE restantes) · `FINDINGS` (entradas REMOVABLE mostradas em dry-run, ou entradas KEEP precisam do dono) · `BLOCKED` (script ausente, merge recusado, prep falhou).
+- **Evidence:** a saída do script (tabela, linhas de removido, linha de disco livre).
+- **Artifacts:** `WORKTREE=<path>` pro `create`; paths removidos + branches apagadas pro `clean`/`merge`.
+- **Next Step:** o próximo comando exato (`/dw-codex-run` na worktree criada; `clean --apply`; a decisão do dono sobre entradas KEEP).
+
+</system_instructions>

package/scaffold/pt-br/references/command-routing.md

@@ -0,0 +1,53 @@
+# Roteamento de comandos
+
+Aplique primeiro as regras de roteamento da raiz. Consulte este catálogo somente para localizar um comando especializado. Uma sugestão de comando não autoriza publicação, merge ou outro workflow.
+
+## Trigger Map
+
+| Intenção do usuário (literal ou parafraseada) | Auto-trigger |
+|------------------------------------------------|--------------|
+| "Implementa X" / "Cria Y" / "Adiciona feature Z" / "Preciso de..." | `/dw-plan` / `/dw-autopilot` |
+| "Autopilota esse PRD" / "Leva esse PRD pra PR" / continua escalação de bugfix autonomamente | `/dw-autopilot --from-prd <slug>` (PRD existente em `.dw/spec/<slug>/`) |
+| "Retoma autopilot" / "continua depois do plan" / `autopilot-state.json` tem `status: plan_complete` | `/dw-autopilot` (ou `/dw-goal --from-autopilot <slug>` se o usuário pedir especificamente a etapa de goal) |
+| Erro colado / "X está quebrado" / "Bug em Y" / screenshot de teste falhando | `/dw-bugfix "X"` |
+| "Planeja essa feature" / "Escreve PRD + techspec + tasks" | `/dw-plan "X"` |
+| "Escreve PRD pra X" / "Especifica Y" | `/dw-plan prd "X"` |
+| "Desenha a arquitetura" / "Faz o techspec" | `/dw-plan techspec` |
+| "Quebra em tasks" | `/dw-plan tasks` |
+| "Roda essa task" (com ID da task) | `/dw-run <ID>` |
+| "Roda todas as tasks pendentes" / "Executa o plano" | `/dw-run` |
+| "Roda isso como goal" / "objetivo durável" / "long-running objective" | `/dw-goal "<objetivo>"` |
+| "Continue de onde parei" | `/dw-run --resume` |
+| "Pausa o trabalho" / "Encerra a sessão" / "Salva onde paramos" | `/dw-pause` |
+| "Report de N em N minutos" / "Me mantém informado enquanto isso roda" / "Quero status periódico" | `/dw-report [--every <N>m]` |
+| "Cria uma worktree pra X" / "Limpa as worktrees" / "Mergeia a worktree X" / "Quantas worktrees sobraram?" | `/dw-worktree create <slug>` / `/dw-worktree clean --apply` / `/dw-worktree merge <slug>` / `/dw-worktree list` |
+| "Retoma" / "Onde paramos?" / "Volta de onde parei" | `/dw-resume` |
+| "QA dessa feature" / "Roda o test plan" | `/dw-qa` |
+| "Corrige os bugs do QA" | `/dw-qa --fix` |
+| "Avalia a feature AI" / "Testa o RAG / classifier" | `/dw-qa --ai` |
+| "Caminha comigo pela feature" / "UAT comigo" / "Vamos fazer um run-through manual" | `/dw-qa --uat` |
+| "Revisa esse bugfix" / "Code-review do fix `<slug>`" | `/dw-review --bugfix <slug>` |
+| "QA desse bugfix" / "Valida o fix `<slug>`" | `/dw-qa --bugfix <slug>` |
+| "Revisa meu PR" / "Checa qualidade" / "Tá pronto pra subir?" | `/dw-review` |
+| "Só checagem de cobertura PRD" | `/dw-review --coverage-only` |
+| "Só code review qualidade" | `/dw-review --code-only` |
+| "Hora de commitar" / mudanças validadas e prontas | `/dw-commit` |
+| "Abre um PR" / "Sobe isso" | `/dw-generate-pr` |
+| "Sugere ideias novas" / "O que devemos construir agora?" / "Encontra oportunidades" / "Ideias de roadmap" | `/dw-opportunities` |
+| "Que melhorias de seguranca devemos considerar?" / "Encontra oportunidades de seguranca" | `/dw-opportunities "security"` |
+| "Brainstorm X" / "Explora essa ideia" / "Research X" | `/dw-brainstorm "X"` (auto-dispatch dos modos grill / prototype / council / research / onepager conforme os sinais) |
+| "Auditoria de saude do codigo" / "Tech debt" / "Oportunidades de refactor" / "Smells em X" | `/dw-refactor "X"` |
+| "Onde está X?" / "O que usa Y?" / "Como Z é estruturado?" | `/dw-intel "<pergunta>"` |
+| "Reconstrói o índice" / "Refresh do intel" | `/dw-intel --build` |
+| "Contexto pesado" / "Audita uso de tokens" / "Por que o agente está lento?" | `/dw-context-budget` |
+| "Checa instalação dev-workflow" / "Agentes/wrappers estão saudáveis?" | `/dw-harness-audit` |
+| "Audita skills" / "Skills parecem duplicadas ou pesadas" | `/dw-skill-health` |
+| "Redesign dessa UI" / "Audita e entrega novo design" | `/dw-redesign-ui "<target>"` |
+| "Audita dependências" / "Estamos atrasados em pacotes?" | `/dw-secure-audit --plan` |
+| "Scan de vulnerabilidades" / "Check de segurança" | `/dw-secure-audit` |
+| "Analisa esse projeto" / "Gera rules" | `/dw-analyze-project` |
+| "Abre um novo projeto" / "Bootstrap de stack" | `/dw-new-project` |
+| "Dockeriza isso" / "Adiciona docker-compose" | `/dw-dockerize` |
+| "Functional doc" / "Mapeia screens e flows" | `/dw-functional-doc` |
+| "Instala skills Azure" / "Configura MCP do Microsoft docs" / "Adiciona expertise Azure" / "Vou trabalhar com Azure" | `/dw-install-azure-skills` |
+| "Instala skills AWS" / "Configura MCP da AWS" / "Adiciona expertise AWS" / "Vou trabalhar com AWS" | `/dw-install-aws-skills` |

package/scaffold/pt-br/references/execution-contract.md

@@ -0,0 +1,55 @@
+# Contrato de execução de tasks
+
+Leia na quebra de tasks, no dispatch ou na retomada. O parent coordena o plano aprovado até a validação; retorno do runner é um handoff, não o fim do objetivo.
+
+## Escolhas no planejamento
+
+Escolha desenvolvimento local ou cruzado em `/dw-plan tasks`, não a cada dispatch. Apresente matriz por task com complexidade, justificativa, ferramenta, modelo, esforço, agentes, dependências e checks. Use `light` para trabalho mecânico de baixo risco, `standard` para padrões conhecidos com decisões delimitadas e `heavy` para arquitetura, incerteza ou superfícies sensíveis. Quantidade de arquivos e tipo de commit não determinam complexidade sozinhos.
+
+Use `.dw/config/routing.json` como candidatos de modelo, não prova de disponibilidade. Inspecione versão/help da CLI para flags e configuração; use documentação do provedor ou metadados disponíveis para IDs de modelos. Help/version não provam autenticação ou acesso na conta. Preserve escolhas explícitas. Prefira modelos configurados que atendam à task; proponha upgrades úteis citando fonte/data. Agentes locais herdam o modelo da sessão salvo override explícito suportado e aprovado. Não escolha outro tier arbitrariamente apenas para chamar uma revisão de independente.
+
+Claude pode propor `codex` (`/dw-codex-run`), Codex pode propor `claude` (`/dw-claude-run`). Copilot/OpenCode mantêm execução local e podem usar adapters explicitamente selecionados. Mantenha trabalho pequeno/acoplado local salvo escolha do usuário. Use apenas agentes instalados e relevantes, sem fan-out obrigatório. Valide nomes contra `.dw/agent-registry.json` e os perfis instalados.
+
+Junto de tasks.md e dos arquivos Markdown por task, escreva `execution-plan.json`:
+
+```json
+{
+  "schema_version": "1.1",
+  "approved": false,
+  "tasks": [{
+    "id": "1.0",
+    "depends_on": [],
+    "execution": {
+      "complexity": "standard",
+      "rationale": "Padrão de serviço conhecido; mudança de comportamento delimitada",
+      "tool": "local",
+      "model": "inherit",
+      "effort": "inherit",
+      "agents": [],
+      "fallbacks": []
+    }
+  }]
+}
+```
+
+Resolva modelo/esforço concretos para ferramentas externas antes da aprovação. Fallbacks contêm `tool`, `model`, `effort`; use apenas alternativas aprovadas. Valide com `node .dw/scripts/lib/workflow-contract.mjs validate <plan.json>` e confira IDs/dependências contra tasks.md. Marque `approved: true` só depois da aprovação dessas escolhas pelo usuário; registre-a no log de decisões do plano. Mudanças exigem aprovação salvo pedido explícito ou fallback aprovado. O boolean escrito pelo agente é um registro, não prova independente de consentimento.
+
+Precedência: instrução explícita atual → escolha aprovada da task → configuração do projeto → padrão da ferramenta. Em plano salvo, configuração/defaults servem para propor escolhas ausentes, nunca substituir silenciosamente escolhas aprovadas. Rejeição do modelo usa fallback aprovado ou bloqueia com evidência; sem troca de provedor não autorizada. Planos schema 1.0 sem metadados de execução rodam localmente; não force migração ou delegação retroativa.
+
+## Dependências e propriedade do worktree
+
+Para WRITE crie worktree dedicado por `/dw-worktree create`. Registre revisão inicial e branch. Tasks de uma cadeia de dependências usam a mesma branch/worktree de execução, com um escritor por vez, mesmo quando tasks sucessivas escolhem CLIs diferentes. A próxima task recebe os commits das dependências nessa branch; nunca a recrie de main. Use worktrees separados para tasks independentes somente quando o plano aprovado definir como integrar as branches antes do trabalho dependente. Não faça merge na branch do usuário só para avançar à próxima task.
+
+Faça stage apenas de mudanças no escopo. Commite implementação e status da task juntos; depois registre o SHA resultante em tasks.md/run-log (um SHA não pode incluir a si próprio no commit). Inclua esse registro no próximo commit com escopo ou em commit final de metadados; não entregue bookkeeping sujo sem reportar. Não faça amend nem stage de arquivos alheios automaticamente.
+
+## Estado durável e retomada
+
+Persista `execution-state.json` junto do plano, com schema_version `1.1` e objeto `tasks` indexado por ID. Cada entrada registra escolha aprovada, worktree, branch/revisão base, ID de sessão do provedor, caminhos de audit/prompt, tentativa, status, checkpoint, SHA e registros de verificação. Guarde audit/sessão fora de worktrees descartáveis. Atualize antes do dispatch e após cada handoff; preserve trabalho concluído em interrupções.
+
+Ao retomar, confira identidade da task salva, diff real, branch, dependências e evidência. Mantenha executor/sessão aprovados. Sem sidecar, recupere a sessão exata do audit da task e valide provedor/worktree/identidade. Nunca use `--last` ou `-c` às cegas. Se o ID não for recuperável, inicie nova sessão no mesmo worktree com task aprovada, estado, diff e logs; registre a perda de contexto conversacional. Sessão de um provedor não pode ser retomada por outro. Nunca use reset/clean para descartar trabalho parcial e tentar novamente.
+
+## Conclusão e autorização
+
+O worker implementa e verifica sua task, retornando evidências e achados pendentes. O parent inspeciona independentemente diff e critérios de aceitação, confere validade da evidência, encaminha correções no escopo ao mesmo worker e continua dependências. Não precisa confirmar de novo execução/retomada já aprovada nem correções rotineiras. Só escopo material novo, alternativas aprovadas indisponíveis, restrições de permissão e decisões pendentes de produto/arquitetura bloqueiam trabalho dependente; continue trabalho independente autorizado quando possível.
+
+Qualidade da revisão depende de critérios de aceitação e achados bloqueantes, não de nota numérica. Reutilize checks verificados para insumos/ambiente/escopo equivalentes; reexecute os afetados após edições. Complete checks exigidos pelo projeto na entrega. Merge, push e publicação continuam como limites separados de autorização. Sem autorização, reporte branch/worktree preparado e resultado validado.

package/scaffold/pt-br/templates/frontend-quality-template.md

@@ -0,0 +1,43 @@
+---
+type: frontend-quality
+schema_version: "1.0"
+status: draft
+---
+
+# Baseline de qualidade do frontend
+
+Use em uma auditoria solicitada de frontend ou plano de ferramentas de qualidade. Incorpore ao `.dw/rules/<module>.md` existente na auditoria, ou à TechSpec da funcionalidade na implementação. Uma funcionalidade precisa apenas das linhas afetadas. Este template registra decisões; não configura ferramentas nem autoriza novos gates.
+
+- Módulo e escopo: [workspace, entradas de runtime, diff relevante]
+- Observado em: [revisão e alterações na árvore de trabalho, data]
+- Stack: [versões de framework/compilador/runner/gerenciador de pacotes, lockfile]
+- Política existente: [instruções, rules, scripts e caminhos do CI]
+
+## Controles
+
+Separe observação e proposta. Preserve checks obrigatórios existentes. Valores de política: `required`, `advisory`, `deferred`, `not_applicable`. Uma proposta não adotada é `deferred`; registre execução separadamente como `passed`, `failed` ou `not_run`. Explique exclusões e evidências ausentes. Não marque ferramentas ausentes como aprovadas nem imponha silenciosamente um gate proposto.
+
+| ID | Risco/controle a inspecionar | Configuração observada e lacunas | Política / mudança proposta | Comando exato, cwd e escopo | Evidência / execução |
+|---|---|---|---|---|---|
+| contract | Autoridade da API, divergência do cliente gerado, validação em runtime | | | | |
+| types | Configuração efetiva de rigor do TypeScript e escapes inseguros | | | | |
+| lint | Diagnósticos relevantes de framework, testes e acessibilidade | | | | |
+| boundaries | Imports permitidos, separação servidor/cliente, entradas de produção | | | | |
+| custom-rules | Defeito recorrente, fixtures do detector e erros acionáveis | | | | |
+| feedback | Regras locais encontráveis e feedback opcional por hooks | | | | |
+| mutation | Comportamento crítico, investigação de sobreviventes e validade do cache | | | | |
+| dead-code | Alcançabilidade em runtime/API pública, arquivos gerados, exclusões revisadas | | | | |
+| duplication | Regras de negócio compartilhadas versus markup repetido intencionalmente | | | | |
+| ci | Jobs obrigatórios, falhas observáveis, dependências de deploy e regras do repositório | | | | |
+
+## Adoção e validação
+
+- Próxima mudança: [risco eliminado, arquivos/configurações a alterar, ferramenta compatível existente ou dependência proposta]
+- Dívida existente: [local da baseline; mantenha separada de defeitos introduzidos agora]
+- Condição de promoção: [evidência necessária para passar de advisory a required; responsável pela decisão]
+- Exceções: [regra/caminho específico, motivo, responsável e gatilho de revisão; sem exclusões abrangentes]
+- Checks do detector: [fixture propositalmente inválida, fixture legítima, casos de alias/caminhos gerados e casos não suportados]
+- Limites da análise: [não executado, serviço indisponível, grafo incompleto ou configurações de CI/repositório não inspecionadas]
+- Checks de entrega: [comandos obrigatórios e aceite comportamental; reutilize evidência apenas com entradas/ambiente/escopo equivalentes]
+
+Para orientação operacional, leia `dw-ui-discipline/references/frontend-engineering.md` no local das skills instaladas. Inclua a implementação aceita na matriz de execução de tarefas; continue sob a autorização existente. Uma auditoria isolada termina com findings documentados e mudanças propostas.