@brunosps00/dev-workflow 1.0.1 → 1.0.4

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

@@ -0,0 +1,90 @@
+<system_instructions>
+You are a session-resumption agent. Your job is to read `.dw/STATE.md`, orient yourself and the user, and route to the most useful next step. This command is the inverse of `/dw-pause`.
+
+## When to Use
+- Use when the user says "resume work", "continue", "where did we stop?", "pick up where we left off", or starts a new session in an existing project
+- Use proactively at the start of any session that lands in a project with a non-empty `.dw/STATE.md` and the user hasn't yet stated an intent
+
+## Pipeline Position
+**Predecessor:** `/dw-pause` (previous session) | **Successor:** depends on what's open (typically `/dw-run --resume`, `/dw-bugfix`, `/dw-plan`, `/dw-qa`, or `/dw-review`)
+
+## File Location
+- Read-only target: `.dw/STATE.md`
+- Cross-reference: `.dw/spec/` (list active PRDs), `.dw/bugfixes/` (list open bugfixes), `.dw/incidents/` (if any)
+
+## Workflow
+
+### 1. Read STATE.md
+- If `.dw/STATE.md` is missing, report: "No paused state found — this looks like a fresh session. Run `/dw-help` for next steps." Stop here.
+- If `STATE.md` exists but every section is `_none_`, report: "STATE.md is empty — nothing to resume. Tell me what you want to do."
+
+### 2. Cross-reference with disk
+Verify that the state still matches the filesystem:
+
+- For each Open Loop referencing a PRD path, run `ls` on `.dw/spec/<slug>/`. If missing, flag `[stale: PRD not found]` and ask if the user wants it removed.
+- For each Open Loop referencing a bugfix slug, check `.dw/bugfixes/<NNN-slug>/`.
+- For each Blocker referencing an external system, do not verify — just surface it.
+- If `last_paused` in frontmatter is more than 14 days old, surface this prominently (state may be stale).
+
+### 3. Produce TLDR
+
+Present a concise summary, **not the raw STATE.md**:
+
+```
+## Where you left off
+
+Last paused: YYYY-MM-DD (Nd ago)
+
+### Open Loops (N)
+- [path or label] — next: <one-line next action> [<status flag if stale>]
+- ...
+
+### Blockers (N unresolved)
+- [label] — waiting on <X>
+
+### Top Todos (up to 5)
+- ...
+
+[Decisions, Lessons, Preferences — only mention if relevant to active loops]
+```
+
+Keep the TLDR under 30 lines. If STATE.md has more, summarize and offer `cat .dw/STATE.md` as a follow-up.
+
+### 4. Suggest the next step
+
+Based on the TLDR, route to a concrete command. Use these heuristics:
+
+| Strongest signal in STATE.md | Suggested command |
+|------------------------------|-------------------|
+| Open Loop on a PRD at `tasks/` stage | `/dw-run --resume` |
+| Open Loop on a PRD at `techspec` stage | `/dw-plan techspec` |
+| Open Loop on a PRD at `prd` stage | `/dw-plan tasks` (if PRD approved) or continue PRD |
+| Open Loop on a bugfix slug | `/dw-bugfix --resume <slug>` or `/dw-qa --bugfix <slug>` |
+| Blocker waiting on external input | Suggest the user resolve the blocker first |
+| Only Todos and Decisions, no active work | Ask the user what they want to start |
+
+Phrase the suggestion as a question, not an order:
+
+```
+Want me to <suggested command>?
+- yes → I'll run it
+- no, <other intent> → tell me what instead
+```
+
+### 5. Update STATE.md frontmatter
+
+Set `last_resumed` to today's date (YYYY-MM-DD). Do not modify section content — that's the user's call now that the session is back.
+
+## Required Behavior
+
+<critical>NEVER auto-execute the suggested command. `/dw-resume` only proposes; the user confirms before any `/dw-run`, `/dw-plan`, or `/dw-bugfix` fires.</critical>
+
+<critical>NEVER fabricate stale-detection results. If you didn't run `ls`, don't report the file exists or doesn't exist.</critical>
+
+<critical>NEVER dump the full STATE.md into the chat. Summarize. Long state files mean compaction is needed — suggest `/dw-pause` to compact next time.</critical>
+
+## Inspired by
+
+This command adapts the session-handoff pattern 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) (CC-BY-4.0, Felipe Rodrigues). Adaptations: routing heuristics map STATE.md content to specific `dw-*` commands; cross-reference with `.dw/spec/` and `.dw/bugfixes/` to detect staleness; never auto-execute.
+
+</system_instructions>

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

@@ -15,16 +15,28 @@ You are the review orchestrator. Runs both Level 2 (PRD compliance / coverage) a
 
 | Invocation | What runs |
 |------------|-----------|
-| `/dw-review` | **Default.** Level 2 (PRD coverage) + Level 3 (code quality) in sequence. Consolidated report saved to `.dw/spec/<prd>/QA/review-consolidated.md`. |
-| `/dw-review --coverage-only` | Only Level 2 — maps every PRD requirement to the code that delivers it. Skips code quality. |
-| `/dw-review --code-only` | Only Level 3 — code quality / convention / security checks. Skips PRD mapping. |
+| `/dw-review` | **Default.** Level 2 (PRD coverage) + Level 3 (code quality) in sequence. Consolidated report saved to `<target>/QA/review-consolidated.md` (target resolves to PRD dir or bugfix dir; see Target Resolution). |
+| `/dw-review --coverage-only` | Only Level 2 — maps every PRD requirement (or bugfix scope) to the code that delivers it. Skips code quality. |
+| `/dw-review --code-only` | Only Level 3 — code quality / convention / security checks. Skips PRD/scope mapping. |
+| `/dw-review --bugfix <NNN-slug>` | Targets a bugfix at `.dw/bugfixes/NNN-slug/` instead of a PRD. Level 2 maps the bugfix scope (TASK.md + fix-report.md + SUMMARY.md) to the code that delivers the fix; Level 3 checks the diff. Output: `.dw/bugfixes/NNN-slug/review/`. |
 
 ## Inputs
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to PRD directory (auto-detect from active branch if omitted) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--coverage-only` / `--code-only` (optional; default = both) | — |
+| `{{PRD_PATH}}` | Path to PRD directory (auto-detect from active branch if omitted; ignored when `--bugfix` is used) | `.dw/spec/prd-invoice-export` |
+| `{{BUGFIX_SLUG}}` | Bugfix slug when `--bugfix` flag is used | `001-login-not-working` |
+| `{{MODE}}` | `--coverage-only` / `--code-only` / `--bugfix <slug>` (optional; default = both, target = PRD) | — |
+
+## Target Resolution
+
+The review runs against one of two target kinds. Compute `<target>` ONCE at the start; substitute it wherever you see `<target>` below.
+
+1. **PRD target (default):** `<target>` = `{{PRD_PATH}}` (auto-detected from active branch when omitted). Artifacts read: `prd.md`, `techspec.md`, `tasks.md`, `tasks/<N>_task.md`, `tasks-validation.md`. Output written to `<target>/QA/`. Filenames: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+2. **Bugfix target (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artifacts read: `TASK.md` (the fix plan with numbered tasks 1..≤5), `fix-report.md` (verify evidence), `SUMMARY.md` (one-page record). There are no FRs in the PRD sense — instead, each numbered task in `TASK.md` is the unit of coverage. Output written to `<target>/review/`. Filenames: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+When the bugfix target is used, the Coverage mapping (Level 2) operates on the numbered tasks from `TASK.md` (not FR-N.M); a task is DELIVERED when (a) the files it claimed to touch are in the diff and (b) the regression test referenced in `fix-report.md` exists and runs. Orphan code in bugfix mode is anything in the diff that does not correspond to a numbered task — a strong signal the safety valve should have escalated to `/dw-plan`.
 
 ## Complementary Skills
 
@@ -59,10 +71,8 @@ When available under `./.agents/skills/`, these are invoked as analytical suppor
 ### Behavior
 
 1. **Load artifacts:**
-   - `.dw/spec/<prd>/prd.md` → extract functional requirements.
-   - `.dw/spec/<prd>/techspec.md` → extract architectural decisions.
-   - `.dw/spec/<prd>/tasks.md` + per-task files → extract committed work.
-   - `tasks-validation.md` → carry forward dimension status.
+   - **PRD target:** `<target>/prd.md` → extract functional requirements. `<target>/techspec.md` → extract architectural decisions. `<target>/tasks.md` + per-task files → extract committed work. `<target>/tasks-validation.md` → carry forward dimension status.
+   - **Bugfix target:** `<target>/TASK.md` → extract the numbered tasks (1..≤5) and their target files. `<target>/fix-report.md` → extract the verify evidence and the regression test reference. `<target>/SUMMARY.md` → extract Symptom, Root Cause, Files Touched, Verification.
 
 2. **Map each FR to code:**
    - For each `FR-N.M`, find code that delivers it (file path + line range + commit SHA).
@@ -78,7 +88,7 @@ When available under `./.agents/skills/`, these are invoked as analytical suppor
 
 ### Output
 
-Saved to `.dw/spec/<prd>/QA/review-coverage.md`:
+Saved to `<target>/QA/review-coverage.md` (PRD target) or `<target>/review/review-coverage.md` (bugfix target):
 
 ```markdown
 # Coverage Review
@@ -145,14 +155,14 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
 
 ### Output
 
-Saved to `.dw/spec/<prd>/QA/dw-review --code-only.md`. The verdict line is one of:
+Saved to `<target>/QA/dw-code-review.md` (PRD target) or `<target>/review/dw-code-review.md` (bugfix target). The verdict line is one of:
 - **APPROVED** — all gates green; ready for commit + PR.
 - **APPROVED WITH CAVEATS** — green but findings worth fixing in follow-up (filed with severities).
 - **REJECTED** — at least one hard gate failed. Specify which.
 
 ## Consolidated output (default mode)
 
-When both levels run, a consolidated report at `.dw/spec/<prd>/QA/review-consolidated.md`:
+When both levels run, a consolidated report at `<target>/QA/review-consolidated.md` (PRD target) or `<target>/review/review-consolidated.md` (bugfix target):
 
 ```markdown
 # Consolidated Review

package/scaffold/en/templates/bugfix-summary-template.md

@@ -0,0 +1,66 @@
+---
+schema_version: "1.0"
+slug: ""
+created: ""
+status: "Fixed | In Review | QA Pending | Reverted"
+severity: "Low | Medium | High"
+related_concerns: []
+---
+
+# Bugfix Summary — {{NNN}}-{{slug}}
+
+One-page record of a bugfix. Sibling files in this directory:
+
+- `TASK.md` — the original triage, clarification answers, and the fix plan that ran
+- `fix-report.md` — verification evidence (`dw-verify` PASS output, reproduction proof, regression test run)
+- `review/` — populated by `/dw-review --bugfix {{NNN}}-{{slug}}`
+- `QA/` — populated by `/dw-qa --bugfix {{NNN}}-{{slug}}` (when applicable)
+
+## Symptom
+
+What the user observed. Quote the original bug description verbatim; do not paraphrase.
+
+> _"…"_
+
+## Root Cause
+
+What was actually broken, in a single sentence. Not the symptom — the cause.
+
+_…_
+
+## Resolution
+
+What changed, in 2-4 bullets. File paths, not snippets.
+
+- _change 1_
+- _change 2_
+
+## Files Touched
+
+Full list, including tests. ≤5 — if more, the safety valve should have escalated to `/dw-plan`.
+
+| Path | Change |
+|------|--------|
+| `src/foo/bar.ts` | _surgical fix to X_ |
+| `src/foo/bar.test.ts` | _regression test added_ |
+
+## Verification
+
+How the fix was proven, beyond "tests pass".
+
+- **Reproduction before fix:** _step that triggered the bug, captured_
+- **Reproduction after fix:** _same step, now passes_
+- **Regression test:** _name + path_
+- **Verify report:** `fix-report.md`
+
+## Related
+
+- **Concerns touched:** _refs from `.dw/rules/concerns.md` if the fix landed in a flagged area_
+- **Adjacent bugfixes:** _slugs of prior fixes in the same module, if any_
+- **PRD context:** _if the bug surfaced inside a feature in flight, link to its PRD path_
+
+## Followups
+
+Open loops this fix surfaced but did not resolve. Add to `.dw/STATE.md` Open-Loops on close.
+
+- _none_

package/scaffold/en/templates/concerns-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+generated_by: dw-analyze-project (Step 9)
+last_refreshed: ""
+---
+
+# Concerns — Risk Map
+
+Risk map for this codebase. Not conventions ("how we do things" — that's `.dw/rules/`), not architecture ("how it's built" — that's `.dw/intel/arch.md`). This file answers a single question: **where is it dangerous to mess around?**
+
+Loaded on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix` when their target touches an entry below. Auto-installed by `/dw-analyze-project` Step 9; never blocks (absence = no flagged areas yet).
+
+## Hot Spots
+
+Files or modules with high churn, frequent bug reports, or repeated "I touched this and broke something" history. Mention them in PRDs that touch the same area; add an extra reviewer or extra test pass.
+
+| Path | Why it's hot | First flagged | Last incident |
+|------|--------------|---------------|---------------|
+| _e.g. `src/auth/session.ts`_ | _3 token-handling fixes in 60d_ | _YYYY-MM-DD_ | _YYYY-MM-DD_ |
+
+## Fragile Integrations
+
+External systems (APIs, queues, vendors, legacy databases) that have a track record of silent failures, schema drift, rate-limit surprises, or undocumented behavior. New code touching them needs explicit retry/timeout/idempotency handling.
+
+| Integration | Failure mode | Mitigation expected |
+|-------------|--------------|---------------------|
+| _e.g. legacy SAP export_ | _silent 200 OK with empty body when source is locked_ | _check body length; log and alert_ |
+
+## Hostile Code
+
+Specific functions, regexes, parsers, or algorithms that are hard to reason about — anyone touching them should fully understand them first (or rewrite, not patch). Common offenders: hand-rolled regex, ad-hoc string parsers, custom serializers, race-prone async, manual transaction code.
+
+| Path / function | Why it's hostile | Owner / context |
+|-----------------|------------------|-----------------|
+| _e.g. `src/billing/parseInvoice.ts:parseLine`_ | _900-char regex with 12 alternatives, no comments_ | _Bruno wrote it in 2024; rewrite if it breaks_ |
+
+## Known Bug History
+
+Aggregated from `.dw/bugfixes/*/SUMMARY.md` by `/dw-intel --build`. Lists modules with ≥2 historical fixes. Read alongside Hot Spots when planning related work.
+
+| Module | Bug count | Recent slugs |
+|--------|-----------|--------------|
+| _e.g. `src/payments/`_ | _4_ | _002-stripe-webhook-retry, 007-refund-rounding_ |
+
+## Tech Debt — Acknowledged
+
+Pieces of debt the team has agreed exist. Not to be cleaned up opportunistically without coordination — they may be load-bearing in ways that aren't obvious.
+
+| Area | Debt description | Why it stays | Cleanup trigger |
+|------|------------------|--------------|-----------------|
+| _e.g. `src/legacy/userMapper.ts`_ | _Two parallel field-mapping codepaths_ | _Awaiting v3 API migration_ | _Q3 2026 after vendor cutover_ |
+
+---
+
+**How to maintain this file:**
+
+- `/dw-analyze-project` rewrites this on each run. Hand-written entries between `<!-- preserved:start -->` and `<!-- preserved:end -->` markers are kept.
+- When a bugfix surfaces a new dangerous area, add it manually under Hot Spots and let the next analyze rerun confirm it.
+- Promote entries to `.dw/constitution.md` when they become non-negotiable rules ("never touch X without an ADR").

package/scaffold/en/templates/state-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+last_paused: ""
+last_resumed: ""
+---
+
+# Session State
+
+Cross-session working memory. Lightweight index of what is in flight, what was decided, what is parked. Updated by `/dw-pause` (consolidates) and read by `/dw-resume` (orients).
+
+Unlike per-PRD `MEMORY.md` (workflow memory for one feature) or ADRs (durable architectural records), this file lives at the project level and survives across PRDs, branches, and sessions. Edit it freely between pauses.
+
+## Open Loops
+
+What is currently in flight — work started but not finished. Each entry: short label + path/target + next concrete action.
+
+- _none_
+
+## Decisions
+
+Cross-cutting decisions that haven't been promoted to an ADR yet (because they don't warrant one, or because the formalization is deferred). Format: `YYYY-MM-DD — decision — context (1 line)`.
+
+- _none_
+
+## Blockers
+
+What's preventing forward motion. External (waiting on someone), internal (knowledge gap), or technical (broken tooling). Each entry: short label + what's blocked + owner / unblock condition.
+
+- _none_
+
+## Todos
+
+Small follow-ups that don't justify a full PRD or task file. One line each. Cleared as they get done or migrated to a PRD.
+
+- _none_
+
+## Deferred Ideas
+
+Ideas you considered but parked. Capture so they aren't lost; revisit when scope changes. Each entry: idea + reason it was parked + revisit trigger (if known).
+
+- _none_
+
+## Lessons
+
+Small lessons learned during recent work — patterns that worked, gotchas, "next time I'll …". Not architectural (those go to ADRs); operational.
+
+- _none_
+
+## Preferences
+
+Conventions agreed during work that affect how the agent should behave going forward. Examples: "always run `pnpm typecheck` before commit", "prefer named exports over default exports for utils".
+
+- _none_
+
+## Notes
+
+Free-form scratchpad. Optional.
+
+- _none_

package/scaffold/pt-br/agent-instructions.md

@@ -5,11 +5,27 @@ Este projeto usa [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@bru
 
 **Objetivo deste arquivo:** quando o usuário expressar uma intenção que casa com a Trigger Map abaixo, rode o comando `dw-*` correspondente **sem pedir permissão** — exceto se a mudança for genuinamente trivial (veja Escape Hatches).
 
+## Matriz de Auto-Sizing
+
+Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudança. A mesma intenção ("conserta isso", "adiciona isso") pode significar quantidades muito diferentes de trabalho; a matriz nomeia quatro tamanhos e roteia cada um para uma entrada diferente. **Escolha o menor que cabe — sub-rotear desperdiça cerimônia, super-rotear esconde o escopo.**
+
+| Tamanho | Como se parece | Rotear para |
+|---------|----------------|-------------|
+| **Pequeno** | ≤3 arquivos, sem migration, sem novo endpoint, descritível em uma frase. Exemplos: typo, log message, config de uma linha, bump de dependência, version pin. | Faça inline. Nenhum comando `dw-*`. |
+| **Médio** | Feature ou bug claro, <10 tasks numeradas esperadas, único componente ou serviço, sem decisões arquiteturais. Exemplos: adicionar campo de form com validação, corrigir regressão em módulo conhecido, ligar novo endpoint num handler existente. | `/dw-bugfix` (bugs) ou `/dw-plan` (features) — direto, não via `/dw-autopilot`. |
+| **Grande** | Feature multi-componente, ≥10 tasks esperadas, toca múltiplos módulos, tem superfície UX user-visible E backend. Exemplos: adicionar nova entidade end-to-end (model + migration + API + UI), introduzir integração de terceiro, redesenhar fluxo. | `/dw-autopilot "<wish>"` — pipeline completo PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR com três gates. |
+| **Complexo** | Domínio novo, requisitos ambíguos, decisão arquitetural exigida, superfície regulatória ou de compliance, ou escopo que cruza múltiplos PRDs. Exemplos: introduzir event sourcing, reconstruir auth, multi-tenancy, nova linha de produto. | `/dw-brainstorm "<ideia>"` primeiro (auto-dispatch de modos research/council), depois `/dw-plan --council` para a etapa de techspec rodar o debate multi-advisor. |
+
+**Safety valve:** se você começou em Pequeno ou Médio mas o trabalho revela que é Grande de fato (a listagem inline passa de 5 passos, ou `/dw-bugfix` dispara seu `Step 5.0`), PARE e escale. Não existe flag para bypass. Escalar é o desfecho correto.
+
+**Adaptado de** [`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) (CC-BY-4.0). A matriz de quatro tamanhos é de lá; o mapeamento para comandos `dw-*` é específico do dev-workflow.
+
 ## Trigger Map
 
 | Intenção do usuário (literal ou parafraseada) | Auto-trigger |
 |------------------------------------------------|--------------|
 | "Implementa X" / "Cria Y" / "Adiciona feature Z" / "Preciso de..." | `/dw-autopilot "X"` |
+| "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>/`) |
 | 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"` |
@@ -18,9 +34,14 @@ Este projeto usa [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@bru
 | "Roda essa task" (com ID da task) | `/dw-run <ID>` |
 | "Roda todas as tasks pendentes" / "Executa o plano" | `/dw-run` |
 | "Continue de onde parei" | `/dw-run --resume` |
+| "Pausa o trabalho" / "Encerra a sessão" / "Salva onde paramos" | `/dw-pause` |
+| "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` |
@@ -36,6 +57,8 @@ Este projeto usa [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@bru
 | "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` |
 
 **Prioridade:** na dúvida entre dois comandos, `/dw-autopilot` é o default mais seguro pra qualquer pedido de feature não-trivial — ele compõe os demais.
 

package/scaffold/pt-br/commands/dw-analyze-project.md

@@ -706,6 +706,67 @@ Três opções:
 - Nunca escrever `.dw/constitution.md` sem aprovação explícita (opção A) ou escolha explícita (opções B/C).
 - Constitution é commitada ao repositório como qualquer outro artefato do projeto — nunca gitignored.
 
+### Step 9: Geração do Mapa de Concerns (Risk Map)
+
+Depois do passo de constitution, gerar `.dw/rules/concerns.md` — o **mapa de riscos** do projeto. Enquanto `.dw/rules/` descreve como o código É e `.dw/constitution.md` descreve o que ele DEVE SER, o mapa de concerns responde uma terceira pergunta: **onde é perigoso mexer?**
+
+**Diferença dos outros dois:**
+- `.dw/rules/*.md` — analítico (padrões observados).
+- `.dw/constitution.md` — declarativo (princípios comprometidos).
+- `.dw/rules/concerns.md` — risco operacional (fragilidade load-bearing, hot spots, código hostil).
+
+**Comportamento:**
+
+Se `.dw/rules/concerns.md` já existir com entradas escritas a mão entre `<!-- preserved:start -->` e `<!-- preserved:end -->`, preserve essas entradas. Atualize as seções auto-geradas (dados de churn de Hot Spots, Histórico de Bugs Conhecidos a partir de `.dw/bugfixes/`).
+
+Caso contrário (primeira execução), construa o arquivo do zero usando `.dw/templates/concerns-template.md` como base.
+
+**Dados a coletar:**
+
+1. **Hot Spots — análise de churn.** Para cada módulo descoberto no Passo 5, compute a contagem de commits tocando arquivos do módulo nos últimos 90 dias (`git log --since="90 days ago" --name-only -- <module-path> | wc -l`). Módulos no top 20% por churn são candidatos. Cruze com `.dw/bugfixes/` (próximo item) — módulos que também aparecem lá são Hot Spots confirmados; o resto fica como "churn alto — verificar com o time."
+
+2. **Histórico de Bugs Conhecidos — agregação de bugfixes.** Se `.dw/bugfixes/` existir, escaneie todo `SUMMARY.md` dentro. Para cada um, parseie a tabela `Arquivos Tocados`; agregue paths de arquivos pelo módulo top-level (ex: `src/auth/session.ts` -> `src/auth/`). Qualquer módulo com `>= 2` fixes históricos entra na seção Histórico de Bugs Conhecidos com contagem e slugs recentes.
+
+3. **Integrações Frágeis.** Procure padrões delatores no código e config:
+   - Clientes SDK externos com scaffolding de retry/backoff (sugere falhas anteriores).
+   - Comentários como `// FIXME: vendor retorna 200 com body vazio às vezes`, `// HACK: workaround para API legada`, `// TODO: tratar edge case do vendor X`.
+   - Loops de retry artesanais ao redor de fetch/axios/HTTP clients.
+   - Diretório `.dw/incidents/` — todo postmortem de incidente que nomeie um sistema externo entra aqui.
+   Liste esses candidatos. Não fabrique — apenas o que você observar.
+
+4. **Código Hostil.** Heurísticas para código que precisa de entendimento completo antes de modificar:
+   - Regex literais com mais de 80 caracteres sem comentário explicativo.
+   - Funções acima de 100 linhas com complexidade ciclomática que resiste à leitura rápida (heurística aproximada: muitos `if`/`switch`/loops aninhados).
+   - Código manual de transação/locking fora da camada idiomática de um ORM.
+   - Serializadores/parsers custom (ex: JSON, CSV, formatos binários escritos a mão) sem arquivo de teste correspondente.
+   Sinalize candidatos e deixe o usuário confirmar.
+
+5. **Tech Debt — Reconhecida.** Escaneie README, CONTRIBUTING, docs/, e comentários no código por marcadores `TODO`, `FIXME`, `XXX`, `HACK`, `DEPRECATED` com mais de 90 dias (use `git blame` para datar). Agrupe por área. Apresente como candidatos; o usuário decide quais merecem reconhecimento (alguns são comentários velhos, alguns são debt real).
+
+**Procedimento:**
+
+1. **Mostre os candidatos no chat primeiro** (NÃO escreva o arquivo ainda). Formate como tabela markdown por seção com contagem e a evidência mais forte para cada entrada. Limite cada seção a 10 entradas — se mais, liste "+N mais (peça expansão)" e deixe o usuário pedir.
+
+2. Pergunte: "Aprovar como está, descartar entradas específicas (passe os labels das linhas), ou pular esse passo inteiro?" Aguarde resposta explícita.
+
+3. Em caso de aprovação, escreva `.dw/rules/concerns.md` usando `.dw/templates/concerns-template.md`. Preencha:
+   - Frontmatter `last_refreshed: <data ISO de hoje>`.
+   - Tabela de Hot Spots.
+   - Tabela de Integrações Frágeis.
+   - Tabela de Código Hostil.
+   - Tabela de Histórico de Bugs Conhecidos.
+   - Tabela de Tech Debt — Reconhecida.
+
+4. Se existia um bloco `<!-- preserved:start --> ... <!-- preserved:end -->` numa versão anterior, anexe-o de volta ao final do arquivo (as entradas curadas a mão pelo time).
+
+5. Imprima: "Escrito `.dw/rules/concerns.md`. Carregado on-demand por `/dw-plan`, `/dw-run` e `/dw-bugfix` quando o alvo deles tocar uma área listada. Nunca bloqueia — informa, sinaliza e sugere ADR para desvios."
+
+**Caso especial — nenhum sinal encontrado:**
+
+Se após as heurísticas nada cruzar a barra (codebase pequeno, churn baixo, sem incidents, sem histórico de bugfix), escreva um `concerns.md` mínimo com todas as seções vazias (apenas headers) e uma nota: "Nenhum sinal de risco no momento. Re-execute depois que o projeto acumular mais histórico."
+
+**Cadência de refresh:** usuários re-rodam `/dw-analyze-project` quando rules ficam desatualizadas. O Passo 9 atualiza seções auto mantendo entradas preservadas. Não existe comando separado só de refresh.
+
 ## Checklist de Qualidade
 
 - [ ] Estrutura do repositório escaneada
@@ -734,6 +795,9 @@ Três opções:
 - [ ] Exemplos de código reais incluídos
 - [ ] Nenhum secret exposto
 - [ ] Convenções de teste documentadas (framework, padrões, cobertura)
+- [ ] Step 8 (constitution) oferecido e resolvido (A/B/C)
+- [ ] Step 9 (mapa de concerns) apresentou candidatos, aguardou aprovação, escreveu `.dw/rules/concerns.md` (ou anotou que não há sinais)
+- [ ] Blocos com marker preserved em concerns.md mantidos verbatim no refresh
 
 ## Exemplo de Uso
 

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

@@ -44,13 +44,22 @@ Uma etapa que invoca um comando `/dw-xxx` SO e considerada completa quando os ar
 
 | Variavel | Descricao | Exemplo |
 |----------|-----------|---------|
-| `{{WISH}}` | Descricao do que o usuario quer construir | "sistema de notificacoes push com preferencias por canal" |
+| `{{WISH}}` | Descricao do que o usuario quer construir (modo padrao) | "sistema de notificacoes push com preferencias por canal" |
+| `{{PRD_SLUG}}` | Slug do PRD existente para autopilotar a partir dele (quando `--from-prd` e usado) | `prd-bugfix-stripe-webhook-retry` |
+| `{{MODE}}` | Flag opcional de invocacao | `--from-prd <slug>` |
+
+## Modos de Invocacao
+
+| Invocacao | Comportamento |
+|-----------|---------------|
+| `/dw-autopilot "<wish>"` | **Padrao.** Pipeline completo do zero: Codebase Intelligence → Pesquisa → Brainstorm → PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR. |
+| `/dw-autopilot --from-prd <slug>` | **Modo retomada-a-partir-do-PRD.** Pula Etapas 1–4 (Intel, Pesquisa, Brainstorm, PRD). Comeca no GATE 1 (apresenta o PRD existente para aprovacao), depois segue por TechSpec → Tasks → Run → QA → Review → Commit → PR. Usado quando `/dw-bugfix` escalou via seu safety valve e escreveu um PRD em `.dw/spec/<slug>/`, ou quando o usuario redigiu um PRD a mao antes e quer o resto automatizado. |
 
 ## Gates de Aprovacao
 
 O autopilot para APENAS nestes 3 momentos:
 
-1. **GATE 1 — PRD**: Apresenta o PRD gerado e aguarda aprovacao do usuario antes de gerar techspec/tasks
+1. **GATE 1 — PRD**: Apresenta o PRD gerado (modo padrao) ou o PRD existente (modo --from-prd) e aguarda aprovacao do usuario antes de gerar techspec/tasks
 2. **GATE 2 — Tasks**: Apresenta a lista de tasks e aguarda aprovacao antes de iniciar a execucao
 3. **GATE 3 — PR**: Apos commit automatico, pergunta se o usuario quer gerar o Pull Request
 
@@ -66,6 +75,22 @@ Se este comando for re-invocado no mesmo PRD apos interrupcao:
 
 ## Pipeline Completo
 
+### Etapa 0: Resolver modo de invocacao (PRIMEIRA acao obrigatoria)
+
+Antes da Etapa 1, decida qual modo esta em efeito:
+
+1. **Se `--from-prd <slug>` aparece na invocacao:**
+   - Resolva `{{PRD_SLUG}}` para `.dw/spec/<slug>/`.
+   - Verifique que o diretorio existe e contem `prd.md`. Se algum faltar, PARE e reporte: `Alvo de --from-prd .dw/spec/<slug>/prd.md nao encontrado. Rode /dw-plan prd ou corrija o slug.`
+   - Cheque se algum `.dw/bugfixes/*/escalated.md` referencia esse slug. Se sim, anote no bloco de progresso: `Retomando de escalacao de bugfix: <NNN-bugfix-slug> → <slug>`.
+   - Defina `mode: "from-prd"` em `autopilot-state.json` e `skipped_steps: [1, 2, 3, 4]` com `skip_reason: "from-prd-mode"`.
+   - Pule direto para o **GATE 1** (aprovacao do PRD) usando o `prd.md` existente.
+
+2. **Caso contrario (modo padrao):**
+   - Defina `mode: "autopilot"` e prossiga para Etapa 1 normalmente.
+
+<critical>Em modo `--from-prd`, as Etapas 1–4 DEVEM ser marcadas como `skipped_steps` com `skip_reason: "from-prd-mode"`. A auditoria de pre-commit (Etapa 14) DEVE honrar isso — etapa pulada nao e o mesmo que etapa faltando.</critical>
+
 ### Etapa 1: Inteligencia do Codebase
 
 <critical>Se `.dw/intel/` existir, a consulta via `/dw-intel` e OBRIGATORIA antes de iniciar. Cai para `.dw/rules/` e grep direto se ausente.</critical>
@@ -104,12 +129,15 @@ Execute `/dw-plan prd` usando os findings do brainstorm.
 
 ### ═══ GATE 1: Aprovacao do PRD ═══
 
+**Em modo padrao:** o PRD acabou de ser escrito na Etapa 4.
+**Em modo `--from-prd`:** o PRD ja existia em disco antes deste run de autopilot comecar (tipicamente redigido por `/dw-bugfix --analise` ou por uma escalacao via safety valve, ou editado a mao).
+
 Apresente ao usuario:
 - Resumo dos requisitos funcionais
-- Decisoes tomadas automaticamente
+- Decisoes tomadas automaticamente (modo padrao) OU nota de origem: "PRD redigido por escalacao do /dw-bugfix em <data>" / "PRD ja existia em disco" (modo --from-prd)
 - Questoes em aberto (se houver)
 
-**Aguarde aprovacao explicita.** Se o usuario pedir mudancas, ajuste e reapresente.
+**Aguarde aprovacao explicita.** Se o usuario pedir mudancas, ajuste e reapresente. Em modo `--from-prd`, edits vao direto para o `.dw/spec/<slug>/prd.md` existente — nao existe rascunho separado.
 
 ### Etapa 5: TechSpec (Interativo — 7+ Perguntas)
 
@@ -216,6 +244,34 @@ Execute `/dw-review --coverage-only` novamente para confirmar que as correcoes d
 Execute `/dw-review --code-only` (Level 3) para review formal.
 - Gere relatorio persistido
 
+### Etapa 13.5: Fechar o loop do bugfix (Condicional)
+
+<critical>Esta etapa roda apenas quando `mode == "from-prd"` E o `prd_path` casa com `.dw/spec/prd-bugfix-*`. Caso contrário pule com `skip_reason: "nao e escalacao de bugfix"`.</critical>
+
+Quando o autopilot está terminando um bugfix que foi escalado por `/dw-bugfix`, a entrada de índice em `.dw/bugfixes/NNN-<slug>/` ainda tem apenas `TASK.md` e `escalated.md` — nenhum `SUMMARY.md` foi escrito porque o fluxo cirúrgico do bugfix nunca chegou ao step 5.5 (o fluxo spec-driven fez o trabalho no lugar). Sem `SUMMARY.md`, o `/dw-intel --build` pula este bugfix para sempre, e queries `bugfix-history` nunca trazem a lição aprendida.
+
+Esta etapa fecha esse loop **antes** da Etapa 14 (Commit) para o SUMMARY cair no mesmo commit do fix.
+
+**Procedimento:**
+
+1. **Encontre a entrada de índice.** Glob em `.dw/bugfixes/*/escalated.md`. Para cada um, leia o conteúdo de uma linha e cheque se referencia o slug do PRD atual (ex: `→ see .dw/spec/prd-bugfix-stripe-webhook-retry/` casa com o PRD ativo `prd-bugfix-stripe-webhook-retry`). O match é o diretório-alvo `NNN-<slug>/`.
+2. **Se nenhum match for encontrado:** o índice de bugfix não espera write-back. Pule silenciosamente e continue para Etapa 14.
+3. **Se `SUMMARY.md` já existir no diretório:** não sobrescreva. Continue para Etapa 14 — humano ou run anterior já fechou o loop.
+4. **Caso contrário, escreva `SUMMARY.md`** usando `.dw/templates/bugfix-summary-template.md`. Origem dos campos:
+   - **Sintoma (verbatim):** seção `Sintoma` de `<prd_path>/prd.md`, ou o primeiro parágrafo do `TASK.md` original se o PRD não carregar.
+   - **Causa Raiz:** seção Causa Raiz do `TASK.md` original.
+   - **Resolução (2–4 bullets):** destilada das decisões em `<prd_path>/techspec.md` + resumo de `git diff <base>...HEAD --stat`.
+   - **Arquivos Tocados:** parseado de `git diff <base>...HEAD --name-only` (exclua paths em `.dw/`). Se >5 arquivos, é esperado para bugfix escalado — liste todos e adicione nota "escalado de bugfix por causa do escopo".
+   - **Verificação:** aponte para `<prd_path>/QA/qa-report.md` e o relatório verify referenciado na saída de sessão da Etapa 9.
+   - **Relacionado — Concerns tocados:** copie das entradas correspondentes em `.dw/rules/concerns.md` se alguma row referenciar módulos em Arquivos Tocados.
+   - **Frontmatter:** `slug: NNN-<slug>`, `created: <data ISO de hoje>`, `status: Fixed`, `severity: <inferida da prioridade do PRD ou Medium default>`, `related_concerns: [lista de cima]`.
+5. **Anexe uma linha final** ao `escalated.md`: `Closed by /dw-autopilot --from-prd on <YYYY-MM-DD>; SUMMARY.md written.` Preserve a linha original da escalação acima.
+6. **Registre o artefato** em `autopilot-state.json` `step_artifacts["13.5"] = [".dw/bugfixes/NNN-<slug>/SUMMARY.md", ".dw/bugfixes/NNN-<slug>/escalated.md"]`.
+
+<critical>NUNCA fabrique evidência de verificação. Se o QA report estiver vazio ou o diff vazio, não invente arquivos em Arquivos Tocados. Escreva as seções do SUMMARY.md que tenham embasamento e marque o resto como `_(não disponível — veja <prd_path>/QA/ para detalhes)_`.</critical>
+
+Após esta etapa, o bugfix se torna visível para `/dw-intel "bugfix history in <module>"` na próxima run de `/dw-intel --build`.
+
 ### Etapa 14: Commit
 
 <critical>AUDITORIA PRE-COMMIT OBRIGATORIA — execute ANTES de invocar `/dw-commit`:
@@ -230,7 +286,7 @@ Rode `ls` em cada caminho abaixo e confirme existencia. Se QUALQUER um faltar, N
 - Evidencia do ultimo `/dw-review --coverage-only` com matriz RF-by-RF (output da sessao ou referencia em `autopilot-state.json`)
 
 Verifique tambem `autopilot-state.json`:
-- Toda etapa de 1 a 13 que NAO esta em `skipped_steps` deve estar em `completed_steps`
+- Toda etapa de 1 a 13 (e 13.5 quando em modo `--from-prd` contra um PRD `prd-bugfix-*`) que NAO esta em `skipped_steps` deve estar em `completed_steps`
 - Cada etapa completada deve ter seus artefatos listados em `step_artifacts`
 
 Se faltar qualquer artefato ou etapa: PARE imediatamente. Reporte ao usuario: `Etapa N nao produziu artefato X — re-executando /dw-[comando]`. Re-execute o comando. Verifique novamente. Soh entao prossiga para `/dw-commit`.
@@ -263,9 +319,11 @@ Salve o arquivo `.dw/spec/prd-[nome]/autopilot-state.json` com o seguinte format
   "mode": "autopilot",
   "wish": "descricao original do usuario",
   "prd_path": ".dw/spec/prd-[nome]",
+  "from_prd_slug": null,
   "current_step": 8,
   "completed_steps": [1, 2, 3, 4, 5, 6, 7],
   "skipped_steps": [2],
+  "skip_reasons": {"2": "dominio ja mapeado em .dw/rules/auth.md"},
   "gates_passed": ["prd", "tasks"],
   "step_artifacts": {
     "9": ["review-matrix-shown-in-session"],
@@ -288,6 +346,7 @@ Salve o arquivo `.dw/spec/prd-[nome]/autopilot-state.json` com o seguinte format
 - Uma etapa SO vai para `completed_steps` apos verificar que seus artefatos existem no disco
 - Se a sessao cair, re-invoque `/dw-autopilot` no mesmo PRD; o comando le `autopilot-state.json` e continua da etapa correta, revalidando artefatos antes de confiar em `completed_steps`
 - Ao finalizar o pipeline (apos commit ou PR), remova o arquivo ou marque `"status": "completed"`
+- Em modo `--from-prd`, defina `from_prd_slug: "<slug>"`, `mode: "from-prd"` e inclua as etapas 1–4 em `skipped_steps` com `skip_reason: "from-prd-mode"` — e isso que a auditoria de pre-commit checa (Etapa 14 verifica que toda etapa NAO listada em `skipped_steps` esta em `completed_steps`)
 
 <critical>Apos CADA etapa completada, exiba o bloco de progresso atualizado ao usuario. Isso e OBRIGATORIO — o usuario DEVE ver o que foi feito e o que vem a seguir. Se uma etapa foi pulada, o motivo DEVE aparecer no bloco de progresso.</critical>