@brunosps00/dev-workflow 0.0.8 → 0.1.2

package/lib/constants.js

@@ -103,7 +103,7 @@ const MCP_SERVERS = {
   },
   playwright: {
     command: 'npx',
-    args: ['-y', '@anthropic-ai/mcp-server-playwright'],
+    args: ['-y', '@playwright/mcp@latest'],
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.0.8",
+  "version": "0.1.2",
   "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"

package/scaffold/en/commands/dw-functional-doc.md

@@ -37,6 +37,12 @@ Works best with project analyzed by `/dw-analyze-project`
 <critical>Header and footer of human videos must not compete for useful area with the browser stage. When they exist, they must be outside the browser stage, in a larger composition, preserving the real application viewport intact.</critical>
 <critical>When the goal is a human tour with centered browser, keep the application in a central stage without fixed side columns, preserving header and footer at full width outside the browser area.</critical>
 <critical>Browser visual quality is a mandatory requirement. Do not deliver a human tour with viewport or recording downscaled relative to the final resolution. The runner must align viewport and video capture to the final resolution or record an explicit blocker.</critical>
+<critical>Hardcoded subtitles over the product screen are not an acceptable standard when the environment supports a dedicated shell. The preferred and mandatory standard is: `header` at the top with the tour title, `stage` centered for the intact browser, and `footer` at the bottom exclusively for the narrative caption.</critical>
+<critical>Even when the human video is assembled from screenshots rather than recorded navigation, the final composition must maintain the same shell layout: header and footer outside the application area. Do not deliver a fullscreen slideshow with subtitles burned directly over the product content.</critical>
+<critical>In the main human video artifact, the caption must be visible inside the shell's `footer`. A sidecar `.srt` file and an embedded subtitle track may exist as support, but they do not replace the obligation for the main narrative to already appear correctly positioned in the footer of the final composition.</critical>
+<critical>It is invalid to deliver as the main version an MP4 whose caption depends on the player for positioning (`mov_text`, `tx3g`, or similar subtitle track) when this causes the text to appear outside the shell's footer. If there is an auxiliary embedded track, visually validate that the main version remains correct even without the player rendering subtitles.</critical>
+<critical>When the request involves human video with captions, always generate two video artifacts: a `clean` version without captions rendered in the frame, for use with player + sidecar `.srt`; and a `captioned` version with the narrative already burned correctly in the shell's `footer`.</critical>
+<critical>If a previous flow in the workspace already has a better-resolved human recording shell, reuse that visual and structural pattern before improvising a new composition. This reuse is preferable to a simplified solution with captions embedded over the viewport.</critical>
 
 ### Video Pacing Requirements
 <critical>Before and after main actions, insert intentional pauses. As an operational rule: maintain 2 to 3 seconds of permanence on relevant loaded states and at least 1.5 seconds after the visible outcome of each main action before proceeding.</critical>
@@ -118,6 +124,9 @@ If there is execution:
 If there is a final human video:
 - save in `evidence/videos/` with a name that clearly differentiates the final tour from the raw capture
 - when `ffmpeg` is available, also save the `mp4` version of the final human tour
+- when captions are involved, save two explicit variants:
+  - a `clean` version without captions drawn in the frame
+  - a `captioned` version with captions drawn in the shell's `footer`
 - record in `manifest.json` which files are `raw` and which are `human_final`
 
 ## Required Flow
@@ -223,6 +232,11 @@ Generate `e2e-runbook.md` in detailed operational style:
   - when there is a title and caption, reserve header and footer outside the browser stage
   - when the composition calls for a centered browser, keep the application in a central stage without fixed side columns and without sacrificing full-width header and footer
   - avoid any artificial reduction of the app viewport to fit overlays
+  - avoid burned subtitles directly inside the product viewport when there is a possibility of using an external shell
+  - burn the main narrative in the shell's `footer` of the final video; use sidecar `.srt` and embedded track only as complementary artifacts
+  - for each final tour with captions, produce:
+    - `clean`: no captions in the frame, with separate `.srt` for the player to decide
+    - `captioned`: captions already positioned in the shell's `footer`
   - align video capture to final resolution to avoid sharpness loss in the browser
   - keep each relevant state on screen long enough for visual reading, especially lists, dialogs, badges, validations, messages, and final results
   - keep captions on screen long enough for comfortable reading, without switching text before the corresponding step is visually understood
@@ -245,6 +259,28 @@ When producing or reviewing the final tour, apply these rules as baseline:
 - when comparing before and after states, clearly show both moments
 - if the recording is too fast for human reading, consider the execution inadequate even if technically correct
 - if `ffmpeg` is installed, consider incomplete any delivery that leaves only `webm` or another raw format without generating `mp4`
+- consider inadequate any video that uses only overlaid captions on the browser when the project supports a shell with dedicated header/footer
+- consider inadequate any video whose main caption depends on the player's renderer and therefore appears outside the shell's intended `footer`
+- consider incomplete any delivery that provides only one of the variants (`clean` or `captioned`) when the flow requires video with captions
+
+## Mandatory Visual Shell Standard
+
+When there is a final human video, adopt as minimum visual standard:
+
+- `header` fixed outside the browser with the module or flow name
+- `main` centering a single browser `stage`
+- `footer` fixed outside the browser, reserved for narrative caption or short context
+- `stage` with its own border, radius, and shadow, without cropping the application viewport
+- `stage` width and height explicitly defined and proportional to the final resolution
+
+Baseline recommended for `1920x1080` when no better standard exists in the flow itself:
+
+- `header`: ~`64px`
+- `footer`: ~`112px`
+- `stage`: ~`1600x900`
+
+If a previous flow in the workspace already has a working shell script (e.g., `record-human-tour.cjs`), reuse it as reference. If choosing a different layout, justify explicitly in `manifest.json`.
+
 - Update `manifest.json` with final status, artifacts, and blockers, distinguishing:
   - MCP evidence
   - raw execution capture

package/scaffold/en/commands/dw-review-implementation.md

@@ -7,7 +7,7 @@ You are a specialized implementation reviewer that compares documented requireme
 - Do NOT use when requirements have not been finalized yet
 
 ## Pipeline Position
-**Predecessor:** `/dw-run-plan` (auto) or `/dw-run-task` (manual) | **Successor:** `/dw-code-review`
+**Predecessor:** `/dw-run-plan` (auto) or `/dw-run-task` (manual) | **Successor:** `/dw-code-review` (auto-fixes gaps before completing)
 
 Called by: `/dw-run-plan` at end of all tasks
 
@@ -175,35 +175,82 @@ Check if the implementation follows project patterns:
 2. [secondary action]
 ```
 
-### 8. Post-Report Decision (Required)
+### 8. Gap Resolution Loop (Required)
 
-After generating the final report, evaluate the result:
+<critical>Review does NOT end at the first report. If gaps are found, enter an automatic fix-review loop until 100% compliance or explicit BLOCK.</critical>
+
+After generating the report, evaluate:
 
-**If there are NO gaps (0 pending, 0 partial, 100% implemented):**
-- Present the report to the user
-- **DO NOT enter planning mode (EnterPlanMode)**
-- **DO NOT dispatch execution agents (Task)**
-- **DO NOT create tasks (TaskCreate)**
-- **DO NOT propose implementing anything**
-- Simply conclude with: "Implementation 100% compliant. No action needed."
-- END the review immediately
-
-**If there ARE gaps (pending > 0 OR partial > 0):**
-- Present the report with gaps and recommendations
-- List actions needed to resolve each gap
-- Wait for user instructions on how to proceed
-- **DO NOT enter planning mode automatically**
-- **DO NOT execute fixes without explicit user instruction**
-
-**Compliance Check Decision Flow:**
 ```dot
-digraph compliance {
-  "Analysis Complete" -> "0 gaps AND 0 partial?";
-  "0 gaps AND 0 partial?" -> "Report + EXIT" [label="yes"];
-  "0 gaps AND 0 partial?" -> "Report + List Actions\nWAIT for user" [label="no"];
+digraph review_loop {
+  rankdir=TB;
+  "Generate Review Report" -> "Gaps found?";
+  "Gaps found?" -> "100% Compliant\nExit" [label="no"];
+  "Gaps found?" -> "Fix gaps\n(implement missing code)" [label="yes"];
+  "Fix gaps\n(implement missing code)" -> "Re-review\nimplementation";
+  "Re-review\nimplementation" -> "Still gaps?";
+  "Still gaps?" -> "100% Compliant\nExit" [label="no"];
+  "Still gaps?" -> "Max cycles\nreached?" [label="yes"];
+  "Max cycles\nreached?" -> "Fix gaps\n(implement missing code)" [label="no"];
+  "Max cycles\nreached?" -> "BLOCKED\nReport residual gaps" [label="yes (3 cycles)"];
 }
 ```
 
+**Loop rules:**
+1. After the initial report, if there are gaps (❌ not implemented or ⚠️ partial), enter the loop automatically
+2. For each cycle:
+   a. Fix all identified gaps: implement missing code, complete partial implementations
+   b. Follow project patterns from `.dw/rules/` during fixes
+   c. Run tests after fixes (`pnpm test` or equivalent)
+   d. Re-read the changed files and re-compare against PRD requirements
+   e. Update the review report with cycle results
+   f. If 100% compliance → exit loop, present final report
+   g. If gaps remain → continue next cycle
+3. **Maximum 3 fix-review cycles.** After 3 cycles, mark review as **BLOCKED** with residual gaps documented
+4. Each cycle must append a section to the report showing what was fixed and the new compliance status
+5. Commit fixes after each cycle: `fix(review): implement [requirement] from PRD`
+
+**What to fix automatically:**
+- ❌ Requirements not implemented → implement them
+- ⚠️ Requirements partially implemented → complete them
+- 📝 Tasks marked complete but actually incomplete → finish them
+
+**What NOT to fix (stop and ask user):**
+- Requirements that contradict each other in the PRD
+- Requirements that need architectural decisions not covered in TechSpec
+- Requirements that depend on external services not available
+- If a fix would take more than the scope of a single task
+
+**Cycle report format (append to review report):**
+```markdown
+## Fix Cycle [N] — [YYYY-MM-DD]
+
+### Gaps Resolved
+| RF | Description | Action Taken | Status |
+|----|-------------|-------------|--------|
+| RF-XX | [requirement] | [what was implemented] | ✅ |
+
+### Tests
+- `pnpm test`: PASS/FAIL
+- Files changed: [list]
+
+### Remaining Gaps
+- [list or "None"]
+
+### Cycle Result: CONTINUE / COMPLIANT / BLOCKED
+```
+
+**If 100% compliant after any cycle:**
+- Present the final report
+- **DO NOT enter planning mode (EnterPlanMode)**
+- **DO NOT create tasks (TaskCreate)**
+- Conclude with: "Implementation 100% compliant after [N] fix cycles. No further action needed."
+
+**If BLOCKED after 3 cycles:**
+- Present the report with residual gaps
+- List what could not be resolved and why
+- Wait for user instructions
+
 ## Status Levels
 
 | Icon | Meaning |
@@ -255,4 +302,5 @@ git diff <commit> -- path/to/file
 <critical>DO NOT APPROVE requirements without concrete evidence in the code</critical>
 <critical>ANALYZE the actual code, do not trust only the checkboxes in tasks.md</critical>
 <critical>If 100% of requirements were implemented and there are NO gaps: DO NOT enter plan mode, DO NOT create tasks, DO NOT dispatch agents. Just present the report and END.</critical>
+<critical>If gaps are found, enter the fix-review loop automatically. Do NOT wait for user instructions to fix gaps. Maximum 3 cycles before marking as BLOCKED.</critical>
 </system_instructions>

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

@@ -7,7 +7,7 @@ You are an AI assistant specialized in Quality Assurance. Your task is to valida
 - Do NOT use when requirements have not been defined yet (create PRD first)
 
 ## Pipeline Position
-**Predecessor:** `/dw-run-plan` or `/dw-run-task` | **Successor:** `/dw-fix-qa` (if bugs) or `/dw-code-review`
+**Predecessor:** `/dw-run-plan` or `/dw-run-task` | **Successor:** `/dw-code-review` (auto-fixes bugs internally before completing)
 
 <critical>Use the Playwright MCP to execute all E2E tests</critical>
 <critical>Verify ALL requirements from the PRD and TechSpec before approving</critical>
@@ -271,6 +271,62 @@ Generate report in `{{PRD_PATH}}/QA/qa-report.md`:
 [Final QA assessment]
 ```
 
+### 9. QA Fix-Retest Loop (Automatic)
+
+<critical>QA does NOT end at the first report. If bugs are found, enter an automatic fix-retest loop until QA is APPROVED or explicitly BLOCKED.</critical>
+
+After generating the initial QA report:
+
+```dot
+digraph qa_loop {
+  rankdir=TB;
+  "Generate QA Report" -> "Bugs found?";
+  "Bugs found?" -> "QA APPROVED\nExit" [label="no"];
+  "Bugs found?" -> "Fix bugs\n(follow dw-fix-qa rules)" [label="yes"];
+  "Fix bugs\n(follow dw-fix-qa rules)" -> "Retest ALL\nfixed bugs";
+  "Retest ALL\nfixed bugs" -> "New/reopened\nbugs?";
+  "New/reopened\nbugs?" -> "QA APPROVED\nExit" [label="no"];
+  "New/reopened\nbugs?" -> "Max cycles\nreached?" [label="yes"];
+  "Max cycles\nreached?" -> "Fix bugs\n(follow dw-fix-qa rules)" [label="no"];
+  "Max cycles\nreached?" -> "QA BLOCKED\nReport residual bugs" [label="yes (5 cycles)"];
+}
+```
+
+**Loop rules:**
+1. After the initial report, if `QA/bugs.md` has bugs with `Status: Open`, enter the loop automatically
+2. For each cycle:
+   a. Fix all open bugs surgically (same rules as `/dw-fix-qa`: no scope creep, minimal impact)
+   b. Retest ALL fixed bugs via Playwright MCP with evidence capture
+   c. Check for regressions introduced by the fixes
+   d. Update `QA/bugs.md` and `QA/qa-report.md` with the cycle results
+   e. If all critical/high bugs are closed → **QA APPROVED**, exit loop
+   f. If new bugs appeared or fixes failed → continue next cycle
+3. **Maximum 5 fix-retest cycles.** After 5 cycles, mark QA as **BLOCKED** with residual bugs documented
+4. Each cycle must update the QA report with a "Cycle N" section showing what was fixed, retested, and the result
+5. Commit fixes after each successful cycle: `fix(qa): resolve BUG-NN [description]`
+
+**Cycle report format (append to qa-report.md):**
+```markdown
+## Fix-Retest Cycle [N] — [YYYY-MM-DD]
+
+### Bugs Fixed
+| Bug | Fix Description | Retest | Evidence |
+|-----|----------------|--------|----------|
+| BUG-01 | [what was changed] | PASS/FAIL | `QA/screenshots/BUG-01-cycle-N.png` |
+
+### Regressions Checked
+- [list of related flows retested]
+
+### Cycle Result
+- **Bugs remaining:** [count]
+- **Status:** CONTINUE / APPROVED / BLOCKED
+```
+
+**Red flags — STOP the loop:**
+- Fix requires a new feature (not a bug) → stop, recommend `/dw-create-prd`
+- Fix requires major refactoring → stop, recommend `/dw-refactoring-analysis`
+- Same bug keeps reappearing after 2+ fix attempts → mark as BLOCKED with root cause analysis
+
 ## Quality Checklist
 
 - [ ] PRD analyzed and requirements extracted

package/scaffold/pt-br/commands/dw-functional-doc.md

@@ -37,6 +37,12 @@ Funciona melhor com projeto analisado por `/dw-analyze-project`
 <critical>Header e footer de vídeos humanos não podem disputar área útil com a tela do browser. Quando eles existirem, devem ficar fora do stage do browser, em uma composição maior, preservando intacta a viewport real da aplicação.</critical>
 <critical>Quando o objetivo for um tour humano com browser centralizado, mantenha a aplicação em um palco central sem colunas laterais fixas, preservando header e footer em largura total fora da área do browser.</critical>
 <critical>Qualidade visual do browser é requisito obrigatório. Não entregue tour humano com viewport ou gravação reescalada para baixo em relação à resolução final. O runner deve alinhar viewport e captura de vídeo à resolução final ou registrar bloqueio explícito.</critical>
+<critical>Legenda hardcoded sobre a tela do produto não é padrão aceitável quando o ambiente permitir shell dedicada. O padrão preferencial e obrigatório é: `header` superior com título do tour, `stage` centralizado para o browser intacto e `footer` inferior exclusivo para a legenda narrativa.</critical>
+<critical>Mesmo quando o vídeo humano for montado a partir de screenshots e não de navegação gravada, a composição final deve manter o mesmo layout de shell: cabeçalho e rodapé fora da área útil da aplicação. Não entregar slideshow fullscreen com subtitles queimadas diretamente sobre o conteúdo do produto.</critical>
+<critical>No artefato principal de vídeo humano, a legenda precisa estar visível dentro do `footer` da shell. Arquivo `.srt` sidecar e faixa de subtitle embutida podem existir como apoio, mas não substituem a obrigação de a narrativa principal já aparecer posicionada corretamente no rodapé da composição final.</critical>
+<critical>É inválido entregar como versão principal um MP4 cuja legenda dependa do player para posicionamento (`mov_text`, `tx3g`, subtitle track similar) quando isso fizer o texto sair do footer da shell. Se houver faixa embutida auxiliar, validar visualmente que a versão principal continua correta mesmo sem o player renderizar subtitles.</critical>
+<critical>Quando o pedido envolver vídeo humano com legenda, gerar sempre dois artefatos de vídeo: um `clean` sem legenda renderizada no quadro, para uso com player + `.srt` sidecar; e um `captioned` com a narrativa já queimada corretamente no `footer` da shell.</critical>
+<critical>Se já existir no workspace um flow anterior com shell de gravação humana melhor resolvida, reutilize esse padrão visual e estrutural antes de improvisar nova composição. Esse reaproveitamento é preferível a uma solução simplificada com legendas embutidas sobre a viewport.</critical>
 
 ### Requisitos de Cadência do Vídeo
 <critical>Antes e depois de ações principais, inserir pausas intencionais. Como regra operacional: manter de 2 a 3 segundos de permanência em estados relevantes já carregados e pelo menos 1,5 segundo após o desfecho visível de cada ação principal antes de seguir.</critical>
@@ -118,6 +124,9 @@ Se houver execução:
 Se houver vídeo humano final:
 - salvar em `evidence/videos/` com nome que diferencie claramente o tour final da captura bruta
 - quando `ffmpeg` estiver disponível, salvar também a versão `mp4` do tour humano final
+- quando houver legendas, salvar também duas variantes explícitas:
+  - uma versão `clean` sem legenda desenhada no frame
+  - uma versão `captioned` com legenda desenhada no `footer` da shell
 - registrar no `manifest.json` quais arquivos são `raw` e quais são `human_final`
 
 ## Fluxo obrigatório
@@ -223,6 +232,11 @@ Gerar `e2e-runbook.md` no estilo operacional detalhado:
   - quando houver título e legenda, reservar cabeçalho e rodapé próprios fora do stage do browser
   - quando a composição pedir browser centralizado, manter a aplicação em um palco central sem colunas laterais fixas e sem sacrificar a largura total do cabeçalho e do rodapé
   - evitar qualquer redução artificial da viewport do app para encaixar overlays
+  - evitar subtitles queimadas diretamente dentro da viewport do produto quando houver possibilidade de usar shell externa
+  - queimar a narrativa principal no `footer` da shell do vídeo final; usar `.srt` sidecar e faixa embutida apenas como artefatos complementares
+  - para cada tour final com legenda, produzir:
+    - `clean`: sem legenda no frame, com `.srt` separado para o player decidir
+    - `captioned`: legenda já posicionada no `footer` da shell
   - alinhar a captura de vídeo à resolução final para evitar perda de nitidez no browser
   - manter em tela cada estado relevante por tempo suficiente para leitura visual, em especial listas, diálogos, badges, validações, mensagens e resultados finais
   - manter as legendas tempo suficiente para leitura confortável, sem trocar texto antes de a etapa correspondente ser compreendida visualmente
@@ -245,6 +259,28 @@ Quando produzir ou revisar o tour final, aplicar estas regras como baseline:
 - quando houver comparação entre estado anterior e posterior, mostrar claramente os dois momentos
 - se a gravação ficar rápida demais para leitura humana, considerar a execução inadequada mesmo que tecnicamente correta
 - se `ffmpeg` estiver instalado, considerar incompleta a entrega que deixar apenas `webm` ou outro bruto sem gerar `mp4`
+- considerar inadequado o vídeo que use apenas captions sobrepostas ao browser quando o projeto permitir shell com header/footer dedicados
+- considerar inadequado o vídeo cuja legenda principal dependa do renderer do player e por isso apareça fora do `footer` previsto na shell
+- considerar incompleta a entrega que disponibilize só uma das variantes (`clean` ou `captioned`) quando o fluxo exigir vídeo com legenda
+
+## Padrão visual obrigatório da shell
+
+Quando houver vídeo humano final, adotar como padrão visual mínimo:
+
+- `header` fixo fora do browser com o nome do módulo ou fluxo
+- `main` centralizando um `stage` único do browser
+- `footer` fixo fora do browser, reservado para legenda narrativa ou contexto curto
+- `stage` com borda, raio e sombra próprios, sem cortar a viewport da aplicação
+- largura e altura do `stage` definidas explicitamente e proporcionais à resolução final
+
+Baseline recomendada para `1920x1080` quando não houver padrão melhor no próprio flow:
+
+- `header`: ~`64px`
+- `footer`: ~`112px`
+- `stage`: ~`1600x900`
+
+Se já existir no workspace um script de shell funcional (ex: `record-human-tour.cjs`), reutilize-o como referência. Se optar por outro layout, justifique explicitamente no `manifest.json`.
+
 - Atualizar `manifest.json` com status final, artefatos e bloqueios, distinguindo:
   - evidências MCP
   - captura bruta de execução

package/scaffold/pt-br/commands/dw-review-implementation.md

@@ -7,7 +7,7 @@
     - NÃO use quando os requisitos ainda não foram finalizados
 
     ## Posição no Pipeline
-    **Antecessor:** `/dw-run-plan` (auto) ou `/dw-run-task` (manual) | **Sucessor:** `/dw-code-review`
+    **Antecessor:** `/dw-run-plan` (auto) ou `/dw-run-task` (manual) | **Sucessor:** `/dw-code-review` (auto-fixes gaps before completing)
 
     Chamado por: `/dw-run-plan` ao final de todas as tasks
 
@@ -170,31 +170,82 @@
     2. [ação secundária]
     ```
 
-    ### 8. Decisão Pós-Relatório (Obrigatório)
+    ### 8. Loop de Resolução de Gaps (Obrigatório)
 
-    **Se NÃO há gaps (0 pendentes, 0 parciais, 100% implementado):**
-    - Apresente o relatório ao usuário
-    - **NÃO entre em modo de planejamento**
-    - **NÃO crie tasks adicionais**
-    - **NÃO proponha implementar nada**
-    - Simplesmente conclua com: "Implementação 100% conforme. Nenhuma ação necessária."
-    - ENCERRE a revisão imediatamente
+    <critical>A revisão NÃO termina no primeiro relatório. Se gaps forem encontrados, entre em um loop automático de fix-review até 100% de conformidade ou BLOCK explícito.</critical>
 
-    **Se HÁ gaps (pendentes > 0 OU parciais > 0):**
-    - Apresente o relatório com gaps e recomendações
-    - Liste ações necessárias para resolver cada gap
-    - Aguarde instruções do usuário sobre como proceder
-    - **NÃO execute correções sem instrução explícita do usuário**
+    Após gerar o relatório, avalie:
 
-    **Fluxo de Decisão de Verificação de Conformidade:**
     ```dot
-    digraph compliance {
-      "Analysis Complete" -> "0 gaps AND 0 partial?";
-      "0 gaps AND 0 partial?" -> "Report + EXIT" [label="yes"];
-      "0 gaps AND 0 partial?" -> "Report + List Actions\nWAIT for user" [label="no"];
+    digraph review_loop {
+      rankdir=TB;
+      "Generate Review Report" -> "Gaps found?";
+      "Gaps found?" -> "100% Compliant\nExit" [label="no"];
+      "Gaps found?" -> "Fix gaps\n(implement missing code)" [label="yes"];
+      "Fix gaps\n(implement missing code)" -> "Re-review\nimplementation";
+      "Re-review\nimplementation" -> "Still gaps?";
+      "Still gaps?" -> "100% Compliant\nExit" [label="no"];
+      "Still gaps?" -> "Max cycles\nreached?" [label="yes"];
+      "Max cycles\nreached?" -> "Fix gaps\n(implement missing code)" [label="no"];
+      "Max cycles\nreached?" -> "BLOCKED\nReport residual gaps" [label="yes (3 cycles)"];
     }
     ```
 
+    **Regras do loop:**
+    1. Após o relatório inicial, se houver gaps (❌ não implementado ou ⚠️ parcial), entre no loop automaticamente
+    2. Para cada ciclo:
+       a. Corrija todos os gaps identificados: implemente código faltante, complete implementações parciais
+       b. Siga os padrões do projeto em `.dw/rules/` durante as correções
+       c. Execute testes após as correções (`pnpm test` ou equivalente)
+       d. Releia os arquivos alterados e recompare com os requisitos do PRD
+       e. Atualize o relatório de revisão com os resultados do ciclo
+       f. Se 100% conforme → saia do loop, apresente o relatório final
+       g. Se gaps permanecerem → continue para o próximo ciclo
+    3. **Máximo de 3 ciclos de fix-review.** Após 3 ciclos, marque a revisão como **BLOCKED** com gaps residuais documentados
+    4. Cada ciclo deve adicionar uma seção ao relatório mostrando o que foi corrigido e o novo status de conformidade
+    5. Commite correções após cada ciclo: `fix(review): implement [requirement] from PRD`
+
+    **O que corrigir automaticamente:**
+    - ❌ Requisitos não implementados → implemente-os
+    - ⚠️ Requisitos parcialmente implementados → complete-os
+    - 📝 Tasks marcadas como concluídas mas incompletas → finalize-as
+
+    **O que NÃO corrigir (parar e perguntar ao usuário):**
+    - Requisitos que contradizem uns aos outros no PRD
+    - Requisitos que precisam de decisões arquiteturais não cobertas na TechSpec
+    - Requisitos que dependem de serviços externos não disponíveis
+    - Se uma correção ultrapassar o escopo de uma única task
+
+    **Formato do relatório por ciclo (adicionar ao relatório de revisão):**
+    ```markdown
+    ## Fix Cycle [N] — [YYYY-MM-DD]
+
+    ### Gaps Resolved
+    | RF | Description | Action Taken | Status |
+    |----|-------------|-------------|--------|
+    | RF-XX | [requirement] | [what was implemented] | ✅ |
+
+    ### Tests
+    - `pnpm test`: PASS/FAIL
+    - Files changed: [list]
+
+    ### Remaining Gaps
+    - [list or "None"]
+
+    ### Cycle Result: CONTINUE / COMPLIANT / BLOCKED
+    ```
+
+    **Se 100% conforme após qualquer ciclo:**
+    - Apresente o relatório final
+    - **NÃO entre em modo de planejamento (EnterPlanMode)**
+    - **NÃO crie tasks (TaskCreate)**
+    - Conclua com: "Implementação 100% conforme após [N] ciclos de fix. Nenhuma ação adicional necessária."
+
+    **Se BLOCKED após 3 ciclos:**
+    - Apresente o relatório com gaps residuais
+    - Liste o que não pôde ser resolvido e por quê
+    - Aguarde instruções do usuário
+
     ## Níveis de Status
 
     | Ícone | Significado |
@@ -246,4 +297,5 @@
     <critical>NÃO APROVE requisitos sem evidência concreta no código</critical>
     <critical>ANALISE o código real, não confie apenas nos checkboxes do tasks.md</critical>
     <critical>Se 100% dos requisitos foram implementados e NÃO há gaps: NÃO entre em plan mode, NÃO crie tasks. Apenas apresente o relatório e ENCERRE.</critical>
+    <critical>Se gaps forem encontrados, entre no loop de fix-review automaticamente. NÃO aguarde instruções do usuário para corrigir gaps. Máximo de 3 ciclos antes de marcar como BLOCKED.</critical>
 </system_instructions>

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

@@ -7,7 +7,7 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
 - NÃO use quando os requisitos ainda não foram definidos (crie o PRD primeiro)
 
 ## Posição no Pipeline
-**Antecessor:** `/dw-run-plan` ou `/dw-run-task` | **Sucessor:** `/dw-fix-qa` (se bugs) ou `/dw-code-review`
+**Antecessor:** `/dw-run-plan` ou `/dw-run-task` | **Sucessor:** `/dw-code-review` (auto-fixes bugs internally before completing)
 
 <critical>Utilize o Playwright MCP para executar todos os testes E2E</critical>
 <critical>Verifique TODOS os requisitos do PRD e TechSpec antes de aprovar</critical>
@@ -269,6 +269,62 @@ Gerar relatório em `{{PRD_PATH}}/QA/qa-report.md`:
 [Parecer final do QA]
 ```
 
+### 9. Loop QA Fix-Retest (Automático)
+
+<critical>O QA NÃO termina no primeiro relatório. Se bugs forem encontrados, entre em um loop automático de fix-retest até que o QA seja APROVADO ou explicitamente BLOQUEADO.</critical>
+
+Após gerar o relatório inicial de QA:
+
+```dot
+digraph qa_loop {
+  rankdir=TB;
+  "Generate QA Report" -> "Bugs found?";
+  "Bugs found?" -> "QA APPROVED\nExit" [label="no"];
+  "Bugs found?" -> "Fix bugs\n(follow dw-fix-qa rules)" [label="yes"];
+  "Fix bugs\n(follow dw-fix-qa rules)" -> "Retest ALL\nfixed bugs";
+  "Retest ALL\nfixed bugs" -> "New/reopened\nbugs?";
+  "New/reopened\nbugs?" -> "QA APPROVED\nExit" [label="no"];
+  "New/reopened\nbugs?" -> "Max cycles\nreached?" [label="yes"];
+  "Max cycles\nreached?" -> "Fix bugs\n(follow dw-fix-qa rules)" [label="no"];
+  "Max cycles\nreached?" -> "QA BLOCKED\nReport residual bugs" [label="yes (5 cycles)"];
+}
+```
+
+**Regras do loop:**
+1. Após o relatório inicial, se `QA/bugs.md` tiver bugs com `Status: Open`, entre no loop automaticamente
+2. Para cada ciclo:
+   a. Corrija todos os bugs abertos cirurgicamente (mesmas regras do `/dw-fix-qa`: sem scope creep, impacto mínimo)
+   b. Reteste TODOS os bugs corrigidos via Playwright MCP com captura de evidências
+   c. Verifique regressões introduzidas pelas correções
+   d. Atualize `QA/bugs.md` e `QA/qa-report.md` com os resultados do ciclo
+   e. Se todos os bugs críticos/altos estiverem fechados → **QA APPROVED**, saia do loop
+   f. Se novos bugs apareceram ou correções falharam → continue para o próximo ciclo
+3. **Máximo de 5 ciclos de fix-retest.** Após 5 ciclos, marque o QA como **BLOCKED** com bugs residuais documentados
+4. Cada ciclo deve atualizar o relatório de QA com uma seção "Cycle N" mostrando o que foi corrigido, retestado e o resultado
+5. Faça commit das correções após cada ciclo bem-sucedido: `fix(qa): resolve BUG-NN [description]`
+
+**Formato do relatório por ciclo (adicionar ao qa-report.md):**
+```markdown
+## Fix-Retest Cycle [N] — [YYYY-MM-DD]
+
+### Bugs Fixed
+| Bug | Fix Description | Retest | Evidence |
+|-----|----------------|--------|----------|
+| BUG-01 | [what was changed] | PASS/FAIL | `QA/screenshots/BUG-01-cycle-N.png` |
+
+### Regressions Checked
+- [list of related flows retested]
+
+### Cycle Result
+- **Bugs remaining:** [count]
+- **Status:** CONTINUE / APPROVED / BLOCKED
+```
+
+**Red flags — PARE o loop:**
+- Correção requer uma nova feature (não é bug) → pare, recomende `/dw-create-prd`
+- Correção requer refatoração significativa → pare, recomende `/dw-refactoring-analysis`
+- Mesmo bug reaparece após 2+ tentativas de correção → marque como BLOCKED com análise de causa raiz
+
 ## Checklist de Qualidade
 
 - [ ] PRD analisado e requisitos extraídos