@brunosps00/dev-workflow 1.0.0 → 1.0.2

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

@@ -15,16 +15,28 @@ Você é o orquestrador de review. Roda Level 2 (PRD compliance / cobertura) e L
 
 | Invocação | O que roda |
 |-----------|------------|
-| `/dw-review` | **Padrão.** Level 2 (cobertura PRD) + Level 3 (qualidade de código) em sequência. Relatório consolidado em `.dw/spec/<prd>/QA/review-consolidated.md`. |
-| `/dw-review --coverage-only` | Apenas Level 2 — mapeia cada requisito do PRD para o código que entrega. Pula qualidade. |
-| `/dw-review --code-only` | Apenas Level 3 — qualidade / convenção / security checks. Pula mapeamento PRD. |
+| `/dw-review` | **Padrão.** Level 2 (cobertura PRD) + Level 3 (qualidade de código) em sequência. Relatório consolidado em `<target>/QA/review-consolidated.md` (target resolve pra dir do PRD ou do bugfix; ver Resolução de Target). |
+| `/dw-review --coverage-only` | Apenas Level 2 — mapeia cada requisito do PRD (ou escopo do bugfix) para o código que entrega. Pula qualidade. |
+| `/dw-review --code-only` | Apenas Level 3 — qualidade / convenção / security checks. Pula mapeamento de PRD/escopo. |
+| `/dw-review --bugfix <NNN-slug>` | Aponta para um bugfix em `.dw/bugfixes/NNN-slug/` em vez de um PRD. Level 2 mapeia o escopo do bugfix (TASK.md + fix-report.md + SUMMARY.md) para o código que entrega o fix; Level 3 checa o diff. Output: `.dw/bugfixes/NNN-slug/review/`. |
 
 ## Entradas
 
 | Variável | Descrição | Exemplo |
 |----------|-----------|---------|
-| `{{PRD_PATH}}` | Caminho do dir PRD (auto-detect da branch ativa se omitido) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--coverage-only` / `--code-only` (opcional; default = ambos) | — |
+| `{{PRD_PATH}}` | Caminho do dir PRD (auto-detect da branch ativa se omitido; ignorado quando `--bugfix` é usado) | `.dw/spec/prd-invoice-export` |
+| `{{BUGFIX_SLUG}}` | Slug do bugfix quando a flag `--bugfix` é usada | `001-login-nao-funciona` |
+| `{{MODE}}` | `--coverage-only` / `--code-only` / `--bugfix <slug>` (opcional; default = ambos, target = PRD) | — |
+
+## Resolução de Target
+
+O review roda contra um de dois tipos de target. Compute `<target>` UMA VEZ no início; substitua onde aparecer `<target>` abaixo.
+
+1. **Target PRD (padrão):** `<target>` = `{{PRD_PATH}}` (auto-detectado da branch ativa quando omitido). Artefatos lidos: `prd.md`, `techspec.md`, `tasks.md`, `tasks/<N>_task.md`, `tasks-validation.md`. Output em `<target>/QA/`. Nomes de arquivo: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+2. **Target Bugfix (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artefatos lidos: `TASK.md` (o plano de fix com tasks numeradas 1..≤5), `fix-report.md` (evidência de verify), `SUMMARY.md` (registro de uma página). Não há FRs no sentido de PRD — em vez disso, cada task numerada em `TASK.md` é a unidade de cobertura. Output em `<target>/review/`. Nomes: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+Quando o target Bugfix é usado, o mapeamento de cobertura (Level 2) opera sobre as tasks numeradas do `TASK.md` (não FR-N.M); uma task é ENTREGUE quando (a) os arquivos que ela alegou tocar estão no diff e (b) o teste de regressão referenciado em `fix-report.md` existe e roda. Código órfão em modo bugfix é qualquer coisa no diff que não corresponde a uma task numerada — sinal forte de que o safety valve deveria ter escalado para `/dw-plan`.
 
 ## Skills Complementares
 
@@ -59,10 +71,8 @@ Quando disponíveis em `./.agents/skills/`, são invocadas como apoio analítico
 ### Comportamento
 
 1. **Carregar artefatos:**
-   - `.dw/spec/<prd>/prd.md` → extrair requisitos funcionais.
-   - `.dw/spec/<prd>/techspec.md` → extrair decisões arquiteturais.
-   - `.dw/spec/<prd>/tasks.md` + per-task files → extrair trabalho commitado.
-   - `tasks-validation.md` → trazer status das dimensões.
+   - **Target PRD:** `<target>/prd.md` → extrair requisitos funcionais. `<target>/techspec.md` → extrair decisões arquiteturais. `<target>/tasks.md` + per-task files → extrair trabalho commitado. `<target>/tasks-validation.md` → trazer status das dimensões.
+   - **Target Bugfix:** `<target>/TASK.md` → extrair as tasks numeradas (1..≤5) e seus arquivos-alvo. `<target>/fix-report.md` → extrair evidência de verify e referência do teste de regressão. `<target>/SUMMARY.md` → extrair Sintoma, Causa Raiz, Arquivos Tocados, Verificação.
 
 2. **Mapear cada FR para código:**
    - Para cada `FR-N.M`, encontrar código que entrega (file path + line range + commit SHA).
@@ -78,7 +88,7 @@ Quando disponíveis em `./.agents/skills/`, são invocadas como apoio analítico
 
 ### Output
 
-Salvo em `.dw/spec/<prd>/QA/review-coverage.md`:
+Salvo em `<target>/QA/review-coverage.md` (target PRD) ou `<target>/review/review-coverage.md` (target Bugfix):
 
 ```markdown
 # Coverage Review
@@ -145,14 +155,14 @@ Se FALTANDO > 0, o veredicto sugere revisitar `/dw-plan tasks` pra escopar ou `/
 
 ### Output
 
-Salvo em `.dw/spec/<prd>/QA/dw-review --code-only.md`. Linha de verdict é uma de:
+Salvo em `<target>/QA/dw-code-review.md` (target PRD) ou `<target>/review/dw-code-review.md` (target Bugfix). Linha de verdict é uma de:
 - **APROVADO** — todos os gates verdes; pronto pra commit + PR.
 - **APROVADO COM RESSALVAS** — verde mas findings valem corrigir em follow-up (filed com severities).
 - **REPROVADO** — ao menos um hard gate falhou. Especifique qual.
 
 ## Output consolidado (modo padrão)
 
-Quando ambos níveis rodam, relatório consolidado em `.dw/spec/<prd>/QA/review-consolidated.md`:
+Quando ambos níveis rodam, relatório consolidado em `<target>/QA/review-consolidated.md` (target PRD) ou `<target>/review/review-consolidated.md` (target Bugfix):
 
 ```markdown
 # Review Consolidado

package/scaffold/pt-br/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}}
+
+Registro de uma pagina de um bugfix. Arquivos irmaos neste diretorio:
+
+- `TASK.md` — a triagem original, respostas das perguntas de clarificacao e o plano de fix que rodou
+- `fix-report.md` — evidencia de verificacao (saida do `dw-verify` PASS, prova de reproducao, execucao do teste de regressao)
+- `review/` — populado por `/dw-review --bugfix {{NNN}}-{{slug}}`
+- `QA/` — populado por `/dw-qa --bugfix {{NNN}}-{{slug}}` (quando aplicavel)
+
+## Sintoma
+
+O que o usuario observou. Cite a descricao original do bug verbatim; nao parafraseie.
+
+> _"…"_
+
+## Causa Raiz
+
+O que estava de fato quebrado, em uma frase. Nao o sintoma — a causa.
+
+_…_
+
+## Resolucao
+
+O que mudou, em 2-4 bullets. Paths de arquivos, nao snippets.
+
+- _mudanca 1_
+- _mudanca 2_
+
+## Arquivos Tocados
+
+Lista completa, incluindo testes. <=5 — se mais, o safety valve deveria ter escalado para `/dw-plan`.
+
+| Path | Mudanca |
+|------|---------|
+| `src/foo/bar.ts` | _fix cirurgico em X_ |
+| `src/foo/bar.test.ts` | _teste de regressao adicionado_ |
+
+## Verificacao
+
+Como o fix foi provado, alem de "os testes passam".
+
+- **Reproducao antes do fix:** _passo que disparava o bug, capturado_
+- **Reproducao depois do fix:** _mesmo passo, agora passa_
+- **Teste de regressao:** _nome + path_
+- **Relatorio de verify:** `fix-report.md`
+
+## Relacionado
+
+- **Concerns tocados:** _refs de `.dw/rules/concerns.md` se o fix caiu em area flagada_
+- **Bugfixes adjacentes:** _slugs de fixes anteriores no mesmo modulo, se houver_
+- **Contexto de PRD:** _se o bug apareceu dentro de uma feature em andamento, link para o path do PRD_
+
+## Followups
+
+Pontas soltas que este fix descobriu mas nao resolveu. Adicione ao `.dw/STATE.md` Open-Loops ao fechar.
+
+- _nenhum_

package/scaffold/pt-br/templates/concerns-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+generated_by: dw-analyze-project (Step 9)
+last_refreshed: ""
+---
+
+# Concerns — Mapa de Riscos
+
+Mapa de riscos deste codebase. Nao sao convencoes ("como fazemos as coisas" — isso e `.dw/rules/`), nao e arquitetura ("como esta construido" — isso e `.dw/intel/arch.md`). Este arquivo responde uma unica pergunta: **onde e perigoso mexer?**
+
+Carregado on-demand por `/dw-plan`, `/dw-run` e `/dw-bugfix` quando o alvo deles toca uma entrada abaixo. Auto-instalado pelo `/dw-analyze-project` Step 9; nunca bloqueia (ausencia = nenhuma area flagada ainda).
+
+## Hot Spots
+
+Arquivos ou modulos com churn alto, reports frequentes de bug ou historico repetido de "mexi aqui e quebrou algo". Mencione em PRDs que toquem a mesma area; adicione revisor extra ou passada extra de teste.
+
+| Path | Por que e quente | Primeiro flag | Ultimo incidente |
+|------|------------------|---------------|------------------|
+| _ex. `src/auth/session.ts`_ | _3 fixes de token em 60d_ | _YYYY-MM-DD_ | _YYYY-MM-DD_ |
+
+## Integracoes Fragis
+
+Sistemas externos (APIs, filas, vendors, bancos legados) com historico de falhas silenciosas, drift de schema, surpresas de rate-limit ou comportamento nao-documentado. Codigo novo que toque eles precisa de tratamento explicito de retry/timeout/idempotencia.
+
+| Integracao | Modo de falha | Mitigacao esperada |
+|------------|---------------|--------------------|
+| _ex. export SAP legado_ | _200 OK silencioso com body vazio quando source esta lockado_ | _checar tamanho do body; logar e alertar_ |
+
+## Codigo Hostil
+
+Funcoes especificas, regexes, parsers ou algoritmos dificeis de raciocinar — quem toca precisa entender 100% primeiro (ou reescrever, nao remendar). Suspeitos comuns: regex artesanal, parsers de string ad-hoc, serializadores custom, async com race condition, codigo de transacao manual.
+
+| Path / funcao | Por que e hostil | Owner / contexto |
+|---------------|------------------|------------------|
+| _ex. `src/billing/parseInvoice.ts:parseLine`_ | _regex de 900 chars com 12 alternativas, sem comentarios_ | _Bruno escreveu em 2024; reescrever se quebrar_ |
+
+## Historico de Bugs Conhecidos
+
+Agregado de `.dw/bugfixes/*/SUMMARY.md` pelo `/dw-intel --build`. Lista modulos com >=2 fixes historicos. Leia junto com Hot Spots ao planejar trabalho relacionado.
+
+| Modulo | Contagem de bugs | Slugs recentes |
+|--------|------------------|----------------|
+| _ex. `src/payments/`_ | _4_ | _002-stripe-webhook-retry, 007-refund-rounding_ |
+
+## Tech Debt — Reconhecida
+
+Pedacos de debt que o time concorda que existem. Nao sao para limpar oportunisticamente sem coordenacao — podem ser load-bearing de formas nao obvias.
+
+| Area | Descricao do debt | Por que fica | Trigger de cleanup |
+|------|-------------------|--------------|--------------------|
+| _ex. `src/legacy/userMapper.ts`_ | _Dois codepaths paralelos de field-mapping_ | _Esperando migracao v3 da API_ | _Q3 2026 apos cutover do vendor_ |
+
+---
+
+**Como manter este arquivo:**
+
+- `/dw-analyze-project` reescreve a cada execucao. Entradas escritas a mao entre `<!-- preserved:start -->` e `<!-- preserved:end -->` sao mantidas.
+- Quando um bugfix descobrir uma nova area perigosa, adicione manualmente em Hot Spots e deixe a proxima analise confirmar.
+- Promova entradas para `.dw/constitution.md` quando virarem regras nao-negociaveis ("nunca toque X sem ADR").

package/scaffold/pt-br/templates/state-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+last_paused: ""
+last_resumed: ""
+---
+
+# Estado da Sessao
+
+Memoria de trabalho entre sessoes. Indice leve do que esta em andamento, do que foi decidido, do que ficou parado. Atualizado por `/dw-pause` (consolida) e lido por `/dw-resume` (orienta).
+
+Diferente do `MEMORY.md` por-PRD (memoria de workflow para uma feature) ou dos ADRs (decisoes arquiteturais duraveis), este arquivo vive no nivel do projeto e sobrevive entre PRDs, branches e sessoes. Edite livremente entre pausas.
+
+## Open Loops (Pontas Soltas)
+
+O que esta em andamento — trabalho comecado mas nao terminado. Cada entrada: label curto + path/alvo + proxima acao concreta.
+
+- _nenhum_
+
+## Decisoes
+
+Decisoes transversais que ainda nao viraram ADR (porque nao justificam um, ou porque a formalizacao foi adiada). Formato: `YYYY-MM-DD — decisao — contexto (1 linha)`.
+
+- _nenhuma_
+
+## Bloqueios
+
+O que esta impedindo o avanco. Externo (esperando alguem), interno (lacuna de conhecimento) ou tecnico (tooling quebrado). Cada entrada: label curto + o que esta bloqueado + dono / condicao de desbloqueio.
+
+- _nenhum_
+
+## Todos
+
+Pequenos follow-ups que nao justificam um PRD ou task. Uma linha cada. Limpe conforme forem feitos ou migrados para um PRD.
+
+- _nenhum_
+
+## Ideias Adiadas
+
+Ideias consideradas mas parqueadas. Capture para nao perder; revisite quando o escopo mudar. Cada entrada: ideia + motivo do park + trigger de revisita (se conhecido).
+
+- _nenhuma_
+
+## Licoes
+
+Pequenas licoes aprendidas no trabalho recente — padroes que funcionaram, pegadinhas, "da proxima vez eu...". Nao sao arquiteturais (essas vao para ADRs); sao operacionais.
+
+- _nenhuma_
+
+## Preferencias
+
+Convencoes acordadas durante o trabalho que afetam como o agent deve se comportar dali em diante. Exemplos: "sempre rodar `pnpm typecheck` antes do commit", "preferir named exports a default exports em utils".
+
+- _nenhuma_
+
+## Notas
+
+Bloco livre. Opcional.
+
+- _nenhuma_

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -44,8 +44,9 @@ The intel directory is the contract. Every file is machine-parseable and referen
 | `files.json` | File graph: per-file imports/exports/type | JSON |
 | `apis.json` | API surface: routes, methods, params, source file | JSON |
 | `deps.json` | Dependencies: version, type, used_by, invocation | JSON |
+| `bugfixes.json` | Historical bugfix index aggregated from `.dw/bugfixes/*/SUMMARY.md` (slug, date, modules touched, related concerns, by_module map). Optional — present only if `.dw/bugfixes/` is non-empty. | JSON |
 | `arch.md` | Human-readable architecture overview + key components + data flow | Markdown |
-| `.last-refresh.json` | Timestamps + content hashes for incremental detection | JSON |
+| `.last-refresh.json` | Timestamps + content hashes for incremental detection (now includes `bugfixes_indexed` count) | JSON |
 
 Schemas are documented in `references/intel-format.md`.
 
@@ -61,9 +62,10 @@ This skill ships ONE agent — `intel-updater` — which produces machine-readab
 
 1. **`/dw-intel --build`** is invoked.
 2. The command spawns `intel-updater` with `focus: full` (first run) or `focus: partial --files <paths>` (incremental).
-3. The agent reads source files (using Glob/Read/Grep; no Bash file listing for cross-platform safety) and writes the 5 intel files.
-4. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run.
-5. `/dw-intel --build` reports completion and invites the user to query via `/dw-intel "<question>"`.
+3. The agent reads source files (using Glob/Read/Grep; no Bash file listing for cross-platform safety) and writes the intel files (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`).
+4. If `.dw/bugfixes/` exists and contains at least one `SUMMARY.md`, the agent additionally scans every SUMMARY frontmatter + Files Touched section and writes `bugfixes.json`. SUMMARY files with invalid frontmatter are logged and skipped.
+5. The agent writes `.last-refresh.json` with timestamps + hashes for incremental change detection on the next run, including a `bugfixes_indexed` count.
+6. `/dw-intel --build` reports completion and invites the user to query via `/dw-intel "<question>"`.
 
 For human-readable analysis (architecture overview, module conventions, anti-patterns), run `/dw-analyze-project` after `/dw-intel --build` — it reads `.dw/intel/` as input and produces `.dw/rules/`.
 
@@ -88,7 +90,7 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 - **Cross-platform**: use Glob/Read/Grep; never Bash `ls`/`find`/`cat` (those break on Windows).
 - **Forbidden files**: never read `.env*` (except `.env.example`/`.env.template`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*.keystore`, `*.jks`, `id_rsa`, `id_ed25519`, or files matching `*credential*`/`*secret*` in name. Skip silently if encountered.
 - **Excluded directories**: `node_modules/`, `.git/`, `dist/`, `build/`, `.dw/` (planning docs, not project code).
-- **Output budget**: `files.json` ≤2K tokens, `apis.json` ≤1.5K, `deps.json` ≤1K, `stack.json` ≤500, `arch.md` ≤1.5K. For large repos, prioritize coverage of key files over exhaustive listing.
+- **Output budget**: `files.json` ≤2K tokens, `apis.json` ≤1.5K, `deps.json` ≤1K, `stack.json` ≤500, `arch.md` ≤1.5K, `bugfixes.json` ≤1K. For large repos, prioritize coverage of key files over exhaustive listing. For `bugfixes.json`, keep one-line symptom/root-cause summaries; do not embed full SUMMARY.md content.
 
 ## References
 
@@ -100,3 +102,5 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 ## Inspired by
 
 Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-intel-updater`) by gsd-build (MIT license). Core schemas (`files.json`, `apis.json`, `deps.json`, `stack.json`, `arch.md`) and incremental update protocol preserved. Path conventions changed from `.planning/intel/` to `.dw/intel/`. CLI tooling (`gsd-sdk query intel.*`) replaced by agent-driven inline operations (no separate runtime). The companion `gsd-codebase-mapper` agent (human-readable analysis docs) was NOT ported — its scope overlaps with the existing `/dw-analyze-project` command which writes to `.dw/rules/`.
+
+The `bugfixes.json` index and the `bugfix-history` / `risk-area` query shapes (see `references/query-patterns.md`) were added in v1.0.2 to enable cross-skill awareness of `.dw/bugfixes/` — adapted from the operational-memory pattern in [`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). The original skill maintains a single `STATE.md`; dev-workflow splits this into project-level `.dw/STATE.md` (session continuity) and a queryable `bugfixes.json` (historical fixes), which compose with the existing per-PRD `MEMORY.md`.

package/scaffold/skills/dw-codebase-intel/references/query-patterns.md

@@ -16,6 +16,8 @@ The command classifies the query into one of these shapes before searching:
 | **api-list** | "list endpoints", "what routes exist?" | `apis.json` | — |
 | **find-export** | "where is `createServer` exported from?", "find the `userSchema` symbol" | `files.json` (search `exports` arrays) | grep fallback |
 | **convention** | "what's the file naming convention?", "are tests co-located?" | `arch.md` | `.dw/rules/` if available |
+| **bugfix-history** | "bugs in `src/auth/`?", "recent fixes touching login?", "what broke in payments?", "fix history for the export feature" | `bugfixes.json` | `.dw/rules/concerns.md`, `.dw/bugfixes/<NNN-slug>/SUMMARY.md` for top hits |
+| **risk-area** | "is `src/auth/session.ts` risky?", "what's fragile here?", "where are the hot spots?", "tech debt in payments?" | `.dw/rules/concerns.md` | `bugfixes.json` (cross-ref bug history for the same module) |
 
 ## Match algorithm
 
@@ -122,6 +124,56 @@ Users (5)
 Orders (5) ...
 ```
 
+### Query: "bugs in src/auth/?"
+
+**Shape:** bugfix-history
+
+**Process:**
+1. Read `bugfixes.json`, look up `by_module["src/auth/"]`.
+2. For each slug returned, fetch the matching `fixes[]` entry (one-line symptom + root cause + date).
+3. Cross-reference `.dw/rules/concerns.md` — if `src/auth/` appears under Hot Spots or Known Bug History, surface that callout.
+4. Return chronological list with paths to the full SUMMARY.md for the top 3.
+
+**Output:**
+```
+3 historical fixes touched src/auth/ (concerns.md flags it as a Hot Spot — 4 fixes in 60d):
+
+- 007-refresh-token-leak   (2026-03-12, Fixed, High)
+  Symptom: refresh token survived sign-out
+  Root cause: session map keyed by user id, not session id
+  → .dw/bugfixes/007-refresh-token-leak/SUMMARY.md
+
+- 003-mfa-skip-on-redirect (2026-02-04, Fixed, Medium)
+  Symptom: redirect chain bypassed MFA check
+  → .dw/bugfixes/003-mfa-skip-on-redirect/SUMMARY.md
+
+- 001-login-not-working    (2026-01-20, Fixed, Medium)
+  Symptom: 500 on POST /login when email casing varied
+  → .dw/bugfixes/001-login-not-working/SUMMARY.md
+
+Consider adding a regression-test guard before further changes here.
+```
+
+### Query: "what's fragile in payments?"
+
+**Shape:** risk-area
+
+**Process:**
+1. Read `.dw/rules/concerns.md`. Search each section (Hot Spots, Fragile Integrations, Hostile Code, Known Bug History, Tech Debt) for `payments`.
+2. For Known Bug History matches, cross-reference `bugfixes.json` `by_module["src/payments/"]` to enumerate recent slugs.
+3. Return one paragraph per concerns.md section that matched, with cross-ref to the bugfix slugs.
+
+**Output:**
+```
+Three risk signals for src/payments/:
+
+Hot Spot: 5 commits in last 30 days; 2 historical bugfixes (refund-rounding, stripe-webhook-retry).
+Fragile Integration: Stripe webhook delivery — concerns.md notes "silent 200 OK when signature header is absent".
+Hostile Code: src/payments/parseInvoice.ts:parseLine — 900-char regex, no comments; original author flagged "rewrite if it breaks".
+
+See: .dw/rules/concerns.md, .dw/bugfixes/{002-stripe-webhook-retry,007-refund-rounding}/SUMMARY.md
+```
+
 ## Stale-index handling
 
 Before answering, check `.dw/intel/.last-refresh.json`:

package/scaffold/skills/dw-memory/SKILL.md

@@ -145,6 +145,29 @@ When flagged for compaction, apply inline:
 4. **Rewrite** retained items as short factual bullets. No narrative logs, no chronological play-by-play.
 5. Keep the default section headings intact. Remove empty sections only if truly unused.
 
+## Context Budget
+
+Memory is part of a broader **context budget** the agent must respect during execution. A blown budget degrades reasoning before any output is produced — the model starts missing requirements, drops constraints, and reverts to averaged-over-training answers. Full guidance: [`references/context-budget.md`](references/context-budget.md).
+
+**Targets:**
+
+- **Total active context:** under **40k tokens** (rough working budget across PRD + TechSpec + tasks + MEMORY.md + per-task memory + open files).
+- **Reserve:** at least **120k tokens** of headroom for actual reasoning, tool output, and the model's response stream.
+- **Hard ceiling per memory file:** `MEMORY.md` ≤ 6KB; `<N>_memory.md` ≤ 3KB. Past those, compact instead of growing.
+
+**Anti-co-load rules** (apply on every load):
+
+1. Never load two PRD specs in the same context. If switching PRDs, drop the previous PRD's spec/techspec/tasks references from the active set.
+2. Never load multiple archived `.dw/bugfixes/` SUMMARY.md files together — load only what's needed for the active fix or query.
+3. Never load `.dw/intel/files.json` and `.dw/intel/deps.json` simultaneously when answering a single question — pick the primary per query shape (see `dw-codebase-intel/references/query-patterns.md`).
+4. Never load a design proposal AND the prior design's full text — if comparing, summarize the prior into 5-10 lines.
+
+**Monitoring signal:**
+
+If the agent finds itself reading large files repeatedly or summarizing the same fact across multiple turns, that's a budget signal. Compact memory and explicitly drop unrelated loaded context before proceeding. Note this in `MEMORY.md` under Handoff Notes so the next task starts lean.
+
+This budget is doctrine, not a hard gate. No command currently rejects work for exceeding 40k. The discipline lives here because future sessions read this skill first.
+
 ## Error Handling
 
 - If any caller-provided memory path is missing, stop and report the mismatch instead of guessing another path.
@@ -165,6 +188,8 @@ Ported from Compozy's `cy-workflow-memory` skill (`/tmp/compozy/.agents/skills/c
 
 - Paths are `.dw/spec/<prd-slug>/` instead of `.compozy/tasks/<name>/`.
 - Task-local file is `<N>_memory.md` next to `<N>_task.md` (mirrors the existing dev-workflow task layout).
-- Inline Compaction Rules (Compozy keeps them in `references/memory-guidelines.md`); if the rule set grows, extract a `references/` directory later.
+- Inline Compaction Rules (Compozy keeps them in `references/memory-guidelines.md`); the budget discipline was extracted to `references/context-budget.md` because it's about model behavior, not file management.
 
 Credit: Compozy project (https://github.com/compozy/compozy).
+
+The Context Budget section adapts the context-loading discipline 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). The target, the anti-co-load rules, and the "monitoring signal" framing come from there; the integration with two-tier memory and the specific file ceilings are dev-workflow-specific.

package/scaffold/skills/dw-memory/references/context-budget.md

@@ -0,0 +1,63 @@
+# Context Budget — Discipline
+
+A working context window is finite. Past about 40k tokens of active content, model output quality degrades — the model starts to miss requirements, lose constraints, blur details across sources, and revert to training-set averages. This file codifies the discipline that keeps active context lean across a long dev-workflow session.
+
+## The numbers
+
+- **Target active load:** under **40k tokens** total — PRD, TechSpec, tasks, MEMORY.md, per-task memory, all open files together.
+- **Reasoning reserve:** **120k+ tokens** of headroom for tool output, model thinking, and response generation.
+- **Soft alert:** when active load crosses **30k tokens**, plan to compact before the next major task.
+- **Compaction threshold for `MEMORY.md`:** ≤ 6KB on disk.
+- **Compaction threshold for `<N>_memory.md`:** ≤ 3KB on disk.
+
+These are doctrine, not enforced by any hard gate. The cost of breaking them is degraded output, not a command failure. Catch it yourself; the framework can't.
+
+## The anti-co-load rules
+
+Each is a "do not load both simultaneously" pairing. Pick one; if you must consult the other, summarize it to 5–10 lines first and drop the full version.
+
+1. **Two PRDs at once.** Working on `prd-foo`, then user asks about `prd-bar`? Finish `prd-foo`'s active turn first, drop its spec/techspec/tasks from active context, then load `prd-bar`. Never carry both spec sets.
+
+2. **Multiple archived bugfix SUMMARY.md files.** Bugfix history queries should go through `.dw/intel/bugfixes.json` (compact, indexed), not by reading 20 SUMMARY.md files. Read individual SUMMARY.md only when the user is acting on that specific fix.
+
+3. **Files.json + deps.json simultaneously.** They overlap. Each query has a primary file per `dw-codebase-intel/references/query-patterns.md`. Pick the primary; consult the secondary only if the primary returns nothing.
+
+4. **A design proposal AND its predecessor's full text.** When comparing two designs, summarize the older one to 5–10 lines (the deltas the new one addresses) and reference it that way. Don't carry both in full.
+
+5. **Per-task memories from non-adjacent tasks.** Only the current task's `<N>_memory.md` and the immediately-previous one (for handoff) belong in active context. Older `<N>_memory.md` files are durable storage — read them when explicitly handing back to an old task, not as part of routine loading.
+
+## The monitoring signal
+
+You will not see a token counter. You can't measure your own budget directly. But these are observable proxies that mean **you are over budget**:
+
+- You are reading the same file twice in the same session without it having changed.
+- You are summarizing the same fact across multiple turns to keep it in scope.
+- You are answering questions by re-deriving from the repo what a memory file would tell you in one line.
+- You are confusing details between two PRDs, tasks, or designs.
+- Your turn outputs are getting longer to compensate for context that is silently slipping out of the model's attention.
+
+When you notice any of these, stop:
+
+1. Compact `MEMORY.md` and the active `<N>_memory.md` per the Compaction Rules in `SKILL.md`.
+2. Explicitly state in chat what you are dropping from active context.
+3. Note the budget event in `MEMORY.md` under Handoff Notes ("compacted at task N — see this section for what was dropped").
+4. Resume the turn.
+
+## What is NOT a budget problem
+
+These look like budget problems but aren't — don't compact for them:
+
+- **A genuinely complex task.** Some features legitimately need many files. Read what you need; the alternative (working from partial context) is worse.
+- **A long verification report.** Verify output can be long. Don't summarize it before logging it to disk; truncate the chat surface, not the artifact.
+- **A long user message.** The user wrote what they wrote. Don't compact to shave their words.
+- **The first PRD load of a new feature.** First-load is fine; second-load of the same PRD in the same turn is the signal.
+
+## Integration with other skills
+
+- **`dw-memory` (this skill)**: compaction is the lever for memory files; this file describes when and why.
+- **`dw-codebase-intel`**: `query-patterns.md` defines the primary-vs-secondary rule that anti-co-load rule #3 references.
+- **`dw-verify`**: a budget-related degradation may show up as a verify regression. If verify keeps failing on facts the PRD already states, suspect budget before suspecting code.
+
+## Source
+
+Adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). The 40k target, the anti-co-load principle, and the monitoring-signal framing come from there. The specific anti-co-load pairings, file-size ceilings, and the integration with `dw-memory`/`dw-codebase-intel` are dev-workflow-specific.

package/scaffold/skills/dw-simplification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw-simplification
-description: Use when simplifying code. Chesterton's Fence (understand WHY first), behavior-preserving refactor, complexity metrics. Triggers from /dw-review --code-only and /dw-brainstorm --refactor.
+description: Use when simplifying code. Chesterton's Fence (WHY first), behavior-preserving refactor, complexity metrics, deep-modules analysis. Triggers from /dw-review and /dw-brainstorm refactor-audit.
 allowed-tools:
   - Read
   - Edit
@@ -18,7 +18,7 @@ Behavioral discipline for simplifying code without breaking it. The trap of refa
 Read this skill when:
 
 - `/dw-review --code-only` flagged a complexity issue (deep nesting, long function, duplication).
-- `/dw-brainstorm --refactor` proposed a simplification target.
+- `/dw-brainstorm` dispatched its **refactor-audit** mode and proposed a simplification target.
 - The user explicitly asks to "clean this up" / "simplify X".
 - During `/dw-run` if the implementation accidentally produced complex code that wants pre-commit cleanup.
 
@@ -117,11 +117,13 @@ For changes that altered cyclomatic complexity, optionally run a complexity anal
 
 In the formal Level 3 review (post-Level 2 chain from `dw-review-implementation`), code-review flags complexity issues using the patterns above. Each flagged issue references this skill: "consider simplifying via guard clauses; apply Chesterton's Fence — verify why the nested check exists before flattening."
 
-## How `dw-refactoring-analysis` uses this
+## How `/dw-brainstorm` refactor-audit mode uses this
+
+The refactor-audit mode dispatched by `/dw-brainstorm` catalogs code smells (Fowler vocabulary) AND runs the deep-modules analysis (`references/deep-modules.md`) against the target area. For each smell or shallow-module flag, the proposed refactor cites:
 
-The analysis catalogs code smells (Fowler vocabulary). For each smell, the proposed refactor cites:
 1. Which simplification rule applies (early return / extract method / lookup table / etc.).
 2. Whether Chesterton's Fence concerns block the refactor (existing tests inadequate? no recent commits explaining the structure? → flag as YELLOW, don't act).
+3. Whether the deep-modules test points the other way (some "code smells" are actually deep-module wrappers that absorb complexity; the fix is to make the wrapper deeper, not to flatten it).
 
 ## Anti-patterns
 
@@ -136,7 +138,10 @@ The analysis catalogs code smells (Fowler vocabulary). For each smell, the propo
 - `references/chestertons-fence.md` — the protocol in detail; case studies of "obvious-but-wrong" removals.
 - `references/complexity-metrics.md` — when each metric (cyclomatic, cognitive, depth, fanout) actually matters; how to measure cheaply.
 - `references/behavior-preserving.md` — characterization tests, refactor with test gate, rollback patterns, codemod tooling per language.
+- `references/deep-modules.md` — high-leverage modules behind small interfaces; deletion test, locality, leverage, seam, adapter diagnostic; anti-patterns (shallow wrapper, god-module). Invoked by `/dw-brainstorm` refactor-audit mode.
 
 ## Inspired by
 
-Adapted from [`addyosmani/agent-skills/code-simplification`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core principles (Chesterton's Fence, behavior preservation, scope discipline, Rule of 500) preserved. dev-workflow integration: invoked by `dw-code-review` and `dw-refactoring-analysis` via Complementary Skills.
+Adapted from [`addyosmani/agent-skills/code-simplification`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core principles (Chesterton's Fence, behavior preservation, scope discipline, Rule of 500) preserved. dev-workflow integration: invoked by `dw-code-review` and `/dw-brainstorm` refactor-audit mode via Complementary Skills.
+
+The deep-modules reference is adapted from [`mattpocock/skills/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/improve-codebase-architecture) by Matt Pocock (MIT license). Core framing (deep modules = high leverage at small interface, deletion test, shallow-wrapper anti-pattern) preserved; paths and integration points rebased on dev-workflow conventions.

package/scaffold/skills/dw-simplification/references/deep-modules.md

@@ -0,0 +1,105 @@
+# Deep modules — high leverage at small interface
+
+A **deep module** absorbs complexity behind a narrow public surface. Its callers see a small, stable API and get a lot of work done per call. A **shallow module** is the opposite — small interface AND small implementation, so it adds an indirection without absorbing any complexity. Or worse: a god-module, deep implementation BUT huge interface, where the surface itself is the complexity.
+
+The refactor-audit mode of `/dw-brainstorm` checks every candidate module against this framing alongside the Fowler smell taxonomy. A "code smell" can mislead if the construct is actually a deep wrapper doing its job correctly.
+
+## The premise
+
+Good abstractions hide complexity. The metric isn't "how short is the code?" — it's "how much complexity does the interface eliminate per unit of public surface area?"
+
+- **Deep module**: 1000 lines of implementation, 3 public functions. Caller does NOT need to know the 1000 lines.
+- **Shallow module**: 50 lines of implementation, 8 public functions. Caller has to learn all 8 to use the 50 productively.
+- **God-module**: 5000 lines of implementation, 60 public functions. Surface area is itself unmanageable.
+
+The deep version wins not because it's shorter overall (it's longer), but because the cost of using it is concentrated in the implementation, not spread to every caller.
+
+## Diagnostic checklist
+
+When the refactor-audit mode evaluates a module, ask these in order:
+
+### 1. Deletion test
+
+> If this module were deleted, how many call sites would break?
+
+- **0–1 callers**: the module isn't pulling its weight. Inline it; the abstraction is shallower than the call sites' real shape. Mark this as `low` priority candidate for removal.
+- **2–3 callers**: borderline. Look at what each caller does with the result — if they immediately wrap/unwrap, the module is shallow. If they consume the result directly, leave it alone.
+- **4+ callers**: the module is at least somewhat load-bearing. Move to next checks.
+
+### 2. Locality test
+
+> Does the caller pass everything the module needs, OR does the module reach into globals / shared state to fill gaps?
+
+A deep module is **self-contained**: callers pass in arguments, get back results. A module that reads from `process.env`, a shared singleton, or implicit thread-local state has a deeper coupling than its interface admits — the caller has to know about the hidden inputs too.
+
+If the module reaches into shared state, its **effective interface** is bigger than what the function signature shows. That's a hidden shallowness — the public surface lies about its real cost.
+
+### 3. Leverage test
+
+> LOC saved per caller × number of callers — what's the multiplicative payoff?
+
+Crude formula: if each caller would otherwise write ~N lines of inline code to replace this module's call, and there are M callers, the module's leverage is N × M. A module whose leverage is < 2× its own LOC is shallow — it's not absorbing enough complexity to justify itself.
+
+### 4. Seam test
+
+> How often does the public interface change relative to the implementation?
+
+A stable public interface with frequently-changing implementation is the **ideal seam** — callers stay put while internals evolve. An interface that changes every few months means callers track it; the abstraction is leaking.
+
+Check `git log --oneline -- <module>` against `git log --oneline -- <module-public-surface-file>`. If they move together, the seam is weak.
+
+### 5. Adapter test
+
+> Does this module mediate between two foreign vocabularies?
+
+The best deep modules are **adapters** — they translate between two domains that have different naming conventions, error semantics, or state models. A module that doesn't mediate between domains is harder to justify as deep; it's probably either a passthrough (shallow) or just a piece of the same domain stretched across files (cohesion issue).
+
+## Anti-patterns
+
+### Shallow wrapper
+
+```ts
+// shallow — passthrough with one line of "work"
+export function getUserName(id: string) {
+  return db.users.findById(id).name;
+}
+```
+
+The wrapper saves the caller 8 characters (`.name`) and forces them to learn a new function name. The leverage is < 1. Inline it.
+
+When to keep a one-liner: it's an **adapter** that locks down ONE meaning of a query. If `getUserName` exists specifically because there are 4 candidate fields (`name`, `displayName`, `username`, `fullName`) and the team's canonical answer is "use `name`", the function IS pulling its weight by serving as the project's vocabulary anchor. Document the WHY in the function body.
+
+### God-module
+
+A class with 60 public methods is shallow even if each method is 100 lines, because the caller has to learn 60 concepts. Split by **role**: what is the smallest subset of methods a caller typically uses together? Each subset becomes a deep module of its own.
+
+### Implementation-leak abstraction
+
+A module that returns its internal representation directly (`return this.cache;`) makes callers depend on the internals. The first time the cache shape changes, every caller breaks. Wrap or copy on egress.
+
+## When refactor-audit raises a smell, also check deep-modules
+
+The combined verdict:
+
+| Fowler smell | Deep-modules check | Action |
+|--------------|--------------------|--------|
+| Long Method | Is the method INSIDE a deep module that callers don't see? | If yes, leave it — internal complexity is OK in deep modules. If no, extract. |
+| Large Class | Is the public surface narrow despite the line count? | If yes, leave it — that's deep. If no, split by role. |
+| Long Parameter List | Does each parameter represent a real choice the caller makes? | If yes, the deep module is forcing necessary configuration; introduce a config object. If parameters are derivable from each other, reduce. |
+| Feature Envy | Is the module a deep adapter between domains? | If yes, the "envy" is the mediation — keep it. If no, move the logic closer to its data. |
+| Middle Man | Does the middle man absorb any complexity? | If no, delete the middle man. If yes, document the why (it's a deep wrapper). |
+
+A flat "this is too long, extract method" recommendation is shallow analysis. Combining Fowler + deep-modules surfaces when the smell is actually a feature.
+
+## Output for refactor-audit findings
+
+When the audit flags a module as a shallow-wrapper or god-module candidate, the finding entry adds a `Deep-modules: <verdict>` line:
+
+```markdown
+### P1 — Shallow Wrapper
+**Files:** src/lib/getUserName.ts
+**Symptom:** 1-line passthrough wrapper around `db.users.findById(id).name`; 2 callers.
+**Deep-modules:** SHALLOW — fails deletion test (only 2 callers) AND leverage test (0 LOC saved per call).
+**Refactor:** Inline at both call sites. If the wrapper exists for vocabulary reasons, document and keep — otherwise remove.
+**Risk:** Low.
+```