refactor(skills): cut the workflows to ~100 lines and scale phases by tier

Each workflow was ~300 lines of grep-count "VERIFICAR" steps and ran every
phase for every request. Phases now state their minimum tier, checks are the
quality gate plus real tools, detail moved to references/, and machine-specific
paths and non-public skills are gone. Security references move to OWASP Top
10:2025, ASVS 5.0 and the OWASP LLM Top 10.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

skills/wf-backend/SKILL.md

@@ -1,281 +1,93 @@
 ---
 name: wf-backend
-description: "Use p/ backend/API. Fluxo PLAN→BUILD→SECURITY→TEST."
-version: 1.0.0
-author: Hermes Agent
+description: Use para trabalho de backend e API - endpoint REST/GraphQL, autenticação, schema e migração de banco, integração, fila, webhook, job. Contrato antes do handler, defaults seguros, auditoria OWASP e gate de qualidade no nível que o dev-router definiu. Não use para UI (wf-frontend), para correção pontual sem mudança de contrato (wf-bugfix) nem para desenho de sistema com vários serviços (wf-architecture primeiro).
 license: MIT
-platforms: [linux, macos, windows]
 metadata:
-  hermes:
-    tags: [backend, api, security, rest, sql, auth, workflow]
+  dev-workflows:
+    uses: [api-security-review, safedeps, sca-audit, secrets-scan, hermaguard]
+    external: [secure-coding, bola-detector, auth-rbac-scaffold, injection-checker, openapi-hardener, security-test-generator]
 ---
 
 # Workflow Backend/API
 
-Orquestrador obrigatório para TODO trabalho backend: APIs REST/GraphQL,
-autenticação, banco de dados, integrações, serviços, jobs. Processo de 4
-fases com skills fixas.
+O `dev-router` define o nível. Cada fase diz a partir de qual nível roda. No nível 1, a mudança segue
+o `wf-bugfix` (ou `wf-refactor`) com as regras de build seguro abaixo e o gate `--tier 1`.
 
-## When to Use
+## Fase 1: PLAN, contrato antes do código (nível 2+)
 
-Sempre que a tarefa envolver servidor: criar/editar endpoints, auth, schema
-DB, integrações, filas, webhooks, ou revisar segurança de backend/models.
+Nível 0 e 1 pulam esta fase. No nível 3, o `planner` escreve a spec EARS e esta fase vira a parte de
+API dela.
 
-## Skills do stack (carregar conforme a fase)
+1. `explorer` mapeia rotas, modelos e validações que já existem. Reaproveite antes de criar.
+2. Contrato em `docs/contract.md` ou OpenAPI: rotas, métodos, payloads, status codes, erros em
+   RFC 9457 (`application/problem+json`), paginação, rate limit e versionamento.
+3. Schemas validados na borda (Zod, Pydantic, OpenAPI). `openapi-hardener`, se instalado, saneia.
+4. Modelo de dados e migração desenhados antes da query: idempotente e reversível.
+5. Modelo de auth decidido e escrito no contrato (sessão, OAuth, JWT) com o motivo.
+6. Contrato com decisão de produto passa pelo usuário antes do build.
 
-- Segurança multi-stack: `secure-coding` (15 stacks)
-- Segurança de API (OWASP): `api-security-review`, `bola-detector`,
-  `auth-rbac-scaffold`, `injection-checker`, `openapi-hardener`,
-  `security-test-generator`
-- Bug hunting adversarial: `hermaguard` (pre-scan + 3 agentes — edge cases,
-  ataque, blast radius; read-only, encontra o que está quebrado)
-- Locais: `fastapi-uvicorn-wiring` (Python), `rest-graphql-debug`,
-  `software-code-quality`, `dependency-cve-audit`, `security-best-practices`,
-  `test-driven-development`, `network-audit`
+## Fase 2: BUILD com defaults seguros (nível 1+)
 
-## Fase 1 — PLAN (contrato antes de código)
+`implementer` com TDD: comportamento novo começa por teste que falha. Regras:
 
-1. Definir API contract primeiro: rotas, métodos, payloads, status codes,
-   erros (RFC 9457 / RFC 7807), rate limit, versionamento.
-2. Validar schema: `openapi-hardener` — OpenAPI/Zod/Pydantic saneado antes
-   de escrever handler.
-3. Definir modelo de dados + migração (idempotente) ANTES de query.
-4. Decidir auth: sessão/OAuth/JWT com base no contexto; documentar.
-5. Approved do contrato pelo usuário antes de build.
-6. VERIFICAR: validar o contrato com `openapi-hardener` (schemas coerentes),
-   conferir rate limit + versionamento definidos, e confirmar que o modelo
-   de dados tem migração idempotente antes de construir.
-7. VERIFICAR (comandos de plano): usar `curl` para provar o contrato contra
-   um stub (ex: `curl -i localhost:PORT/health`) e `git log`/branches para
-   confirmar que o contrato fica versionado no repo.
-8. CHECKPOINT: registrar contrato em `docs/contract.md` (ou OpenAPI) para as
-   fases seguintes referenciarem.
-9. VERIFICAR (comandos de contrato completo): `grep -c "->" docs/contract.md` — todas as rotas têm status codes esperados; e `grep -c "429\|rate" docs/contract.md` para provar que rate limit está no contrato.
-10. VERIFICAR (auth no contrato): `grep -rn "auth\|bearer\|session" docs/contract.md` — decidir e documentar o modelo de auth ANTES do build (não deixar para a Fase 2/3).
-11. VERIFICAR (validação de contrato): se OpenAPI, `python3 -m json.tool docs/openapi.json > /dev/null` para provar que o schema é válido em JSON.
+- Validação de toda entrada externa na borda; nada de confiar em payload, header ou query.
+- Erros estruturados (RFC 9457); nunca `except: pass` nem `catch` vazio.
+- Timeout em todo cliente HTTP e conexão de banco; retry só em operação idempotente.
+- Mutações idempotentes (chave de idempotência em POST que cobra ou cria); transação quando há várias escritas.
+- Toda listagem com paginação e limite máximo.
+- Query de dado do usuário escopada ao ID autenticado (ownership), nunca a um ID vindo do cliente.
+- Senha com Argon2id; sessão em cookie `httpOnly`, `Secure`, `SameSite`; nenhum segredo, token ou senha em log.
+- CORS com allowlist explícita (nunca `*` com credenciais); configuração por variável de ambiente.
+- Tipos seguros na fronteira: sem `any` ou cast forçado no que entra ou sai.
+- `secure-coding`, se instalado, como checklist da stack.
 
-**Checklist da fase 1 (validar antes do build):**
-- [ ] Rotas/métodos/payloads/status codes definidos e aprovados.
-- [ ] Erros no padrão RFC 9457/7807; rate limit e versionamento especificados.
-- [ ] `openapi-hardener` validou os schemas (Zod/Pydantic/OpenAPI).
-- [ ] Migração de dados idempotente desenhada antes de qualquer query.
+Dependência nova: justifique (`lean-code`) e consulte `safedeps` antes de instalar.
 
-**Anti-padrões desta fase:**
-- NUNCA escrever handler sem contrato aprovado.
-- NUNCA deixar schema "se inferir na mão livre" — definir e validar.
-- NÃO esquecer rate limit/versionamento na fase 1 (correção é cara depois).
-- NÃO misturar payload v2 com contrato v1 sem versionamento explícito.
+## Fase 3: SECURITY (nível 2+, ou nível 1 com gatilho)
 
-## Fase 2 — BUILD (escrever com defaults seguros)
+Gatilhos do `dev-router` (auth, dinheiro, dado pessoal, SQL montado à mão, upload, shell, LLM) chamam
+o `security-auditor`, que segue o `wf-security-review` com escopo no diff e no que ele alcança.
 
-1. `secure-coding` — aplicar padrões da stack em uso (Node/FastAPI/Go/etc).
-2. Validação na borda (Zod/Pydantic), erros estruturados, timeouts em
-   clientes HTTP e DB, idempotência em mutações.
-3. Argon2id p/ senhas, httpOnly cookies p/ sessões, nunca logar segredos.
-4. Type-safe boundaries; evitar `any`/`as` descontrolados em TS.
-5. VERIFICAR: rodar `secure-coding` como checklist da stack (validação na
-   borda, timeouts, idempotência) e `rest-graphql-debug` para confirmar
-   que os status codes/mensagens batem com o contrato da Fase 1.
-6. VERIFICAR (timeouts): para todo cliente HTTP do serviço, confirmar
-   `timeout` definido — `grep -rn "requests\|fetch(" src/ | wc -l` contra
-   o número de `timeout` presentes; igual = OK.
-7. VERIFICAR (redação de segredos): `grep -rniE "password|secret|token" src/ --include="*.py" --include="*.ts" | grep -i "log\|print"` — zero
-   hits é o esperado (nenhum segredo sendo logado).
-8. VERIFICAR (queries): conferir que toda listagem tem `LIMIT` — checar
-   com `search_files` as chamadas sem paginação antes de seguir.
+- Referências: OWASP API Security Top 10 (2023) e OWASP Top 10:2025.
+- ASVS 5.0: L1 no nível 2, L2 no nível 3.
+- Vendorizadas: `api-security-review` (OWASP API Top 10), `secrets-scan`, `sca-audit`, `safedeps` (CVE ao vivo no OSV.dev).
+- Externas, se instaladas: `bola-detector` em rotas com `:id`, `auth-rbac-scaffold` em login e papéis, `injection-checker` em SQL/ORM/shell/template.
+- Achado P0/P1 bloqueia a entrega; depois do fix, rode a auditoria de novo e confirme que sumiu.
+- Nível 3 ou gatilho disparado: `hermaguard` no diff como passe adversarial (edge cases, ataque, blast radius).
 
-**Checklist da fase 2 (build seguro):**
-- [ ] Validação na borda (Zod/Pydantic) em TODA entrada externa.
-- [ ] Erros estruturados; timeouts em clientes HTTP e DB.
-- [ ] Mutações idempotentes; transações onde há múltiplas gravações.
-- [ ] Senhas com Argon2id; sessões httpOnly; nenhum segredo em log.
-- [ ] Type-safe boundaries; sem `any` solto no que atravessa a fronteira.
+## Fase 4: TEST + GATE (nível 1+)
 
-**Anti-padrões desta fase:**
-- NUNCA logar senha/token/dado sensível.
-- NUNCA confiar em input externo sem validação na borda.
-- NÃO fazer query sem LIMIT/paginação em listas não limitadas.
-- NÃO engolir erro com `except: pass` / catch vazio (mascara falha).
+1. Testes de validação, auth negativa (outro usuário, sem token, papel errado) e idempotência.
+   `security-test-generator`, se instalado, ajuda a gerar os casos negativos.
+2. Gate: `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N`. Já cobre lint, typecheck, testes,
+   gitleaks, semgrep, cobertura do diff, mutação e osv-scanner conforme o nível.
+3. Checagens que dependem do app de pé entram como `[[check]]` no `.dev-workflows.toml` do projeto
+   (receitas em [references/checks.md](references/checks.md)):
+   - schemathesis contra o OpenAPI (nível 2+): zero erro 5xx e zero violação de schema;
+   - Pact quando há outro serviço consumindo a API;
+   - migração up, down, up num banco descartável (testcontainers) quando o schema muda;
+   - `EXPLAIN` das queries novas e detecção de N+1 quando há query nova;
+   - k6 com thresholds de p95 quando a mudança toca um caminho quente (nível 3 ou gatilho de performance).
+4. No nível 2+, `reviewer` revisa o diff; no nível 3, `verifier` roda o gate final e devolve a evidência.
 
-## Fase 3 — SECURITY (auditar tudo)
+Detalhes do gate e da configuração: [../dev-router/references/quality-gate.md](../dev-router/references/quality-gate.md).
 
-1. `bola-detector` em rotas com `:id`/`findUnique` (Object-Level Authz).
-2. `auth-rbac-scaffold` em qualquer fluxo de JWT/login/roles.
-3. `injection-checker` em SQL/ORM/shell/templates.
-4. `api-security-review` no conjunto final (OWASP API Top 10).
-5. `dependency-cve-audit` nas deps do projeto (local).
-6. VERIFICAR: consolidar achados P0/P1 por severidade, validar que cada
-   rota sensível tem auth + ownership-scope, e re-auditar depois de
-   qualquer fix (nada de despachar cego).
-7. VERIFICAR (ownership): para rotas com `:id`, conferir que a query usa o
-   ID autenticado — `grep -rn "user_id\|user.id\|req.user" src/ | wc -l`
-   >= número de rotas protegidas.
-8. VERIFICAR (rate limit): `grep -rniE "ratelimit|rate_limit|limiter" src/`
-   — toda rota de escrita tem rate limit de referência; se ausente, anotar
-   como P2.
-9. VERIFICAR (headers/CORS): conferir CSP/CORS configurados (CORS
-   allowlist explícita, não `*` com credenciais); `grep -rn "access-control\|csp\|content-security" src/`.
-10. VERIFICAR (re-audit pós-fix): após corrigir P0/P1, re-rodar
-    `bola-detector` + `api-security-review` e confirmar que os achados
-    sumiram (não só mudaram de arquivo).
-11. VERIFICAR (critério de aceite de segurança): para cada achado P0/P1,
-    reexecutar o teste que o reproduzia e confirmar que agora passa;
-    manter o PoC no repositório de testes.
-12. VERIFICAR (comandos de confirmação): `grep -c "auth\|ownership" src/`
-    deve ser >= número de rotas que mexem em dado de usuário — cada rota
-    sensível tem o controle por objeto documentado no código.
+## Relatório
 
-**Checklist da fase 3 (segurança):**
-- [ ] `bola-detector` limpo em rotas com `:id` (object-level authz).
-- [ ] Auth/RBAC (`auth-rbac-scaffold`) cobrindo roles e sessions.
-- [ ] `injection-checker` limpo (SQL/ORM/shell/templates).
-- [ ] `api-security-review` sem P0/P1 (OWASP API Top 10).
-- [ ] `dependency-cve-audit` sem CVEs críticas pendentes.
+Contrato entregue (nível 2+), achados de segurança por severidade e o que foi corrigido, testes que
+provam (nomes e contagem real), veredito do gate com o que ficou não verificado, e linhas líquidas.
 
-**Anti-padrões desta fase:**
-- NUNCA definir query escopada por outro ID que não o autenticado.
-- NUNCA aceitar finding P0/P1 sem evidência de correção.
-- NÃO revisar segurança só nos endpoints novos — escopar também os existentes.
-- NÃO tratar auditoria como checklist burocrático: achado não resolvido bloqueia.
+## Critérios de aceite
 
-## Fase 4 — TEST + BUG HUNT (provar antes de entregar)
-
-1. `hermaguard` no diff do backend — dispachar os 3 agentes adversariais
-   (Edge Case Hunter, Adversarial Reviewer, Blast Radius). Esperar falhar:
-   NUNCA parar em "parece ok"; exigir cobertura de edge cases, races,
-   rollback safety e schema drift. Read-only (não corrige — acha).
-2. `test-driven-development`: testar o que valida/auth/idempotência.
-3. `security-test-generator`: testes de segurança (authz negativa,
-   payloads malformados, rate limit).
-4. Rodar suíte + lint + typecheck; status real, não suposição.
-5. Corrigir os findings P0/P1 do hermaguard como tarefas separadas; rodar
-   hermaguard de novo se o fix mudou >3 arquivos.
-6. Relatório: contrato entregue, achados de segurança P0/P1/P2 resolvidos,
-   bugs caçados pelo hermaguard (por severidade), testes passando (contagem).
-7. VERIFICAR (não-regressão QA): rodar `test_quality.py` (gate do workflow)
-   — score não pode cair em relação ao baseline.
-8. VERIFICAR (cobertura de classes): para rolls em produção, conferir que
-   o hermaguard cobriu edge cases, races, rollback safety e schema drift —
-   não aceitar "sem achados" sem essa cobertura.
-9. VERIFICAR (efeito colateral): se a mudança alterou contrato/DB, rodar
-   `rest-graphql-debug` para confirmar status codes e mensagens sem
-   regressão.
-10. VERIFICAR (cobertura de testes real): `python3 -m pytest --cov=app -q`
-    (ou `npm test -- --coverage`) — anotar % de cobertura e garantir que
-    os módulos críticos (auth, validação, idempotência) têm pelo menos
-    smoke test.
-11. VERIFICAR (migração reversível): se houve schema change, rodar
-    `alembic downgrade -1`/equivalente em dev para provar rollback; e
-    `git diff --stat` para conferir o escopo do que está indo pra frente.
-12. VERIFICAR (config por ambiente): `grep -rn "getenv\|os.environ\|process.env" src/` — toda configuração via env, sem valores hardcoded que
-    vazam para prod.
-13. VERIFICAR (comandos de entrega): `python3 -m pytest -q && npm run build` (ou stack equivalente) como smoke final; e `git status` para
-    confirmar que os artefatos de teste não vazaram pro repo.
-14. VERIFICAR (critério de entrega): relatório final só fecha quando cada
-    item do checklist da Fase 4 está marcado — sem exceção de última hora
-    não auditada.
-
-**Checklist da fase 4 (gate de entrega):**
-- [ ] `hermaguard` rodado; findings CRITICAL/HIGH zero ou com plano de fix.
-- [ ] TDD: testes de validação, auth e idempotência verdes.
-- [ ] `security-test-generator`: authz negativa, payloads mal, rate limit.
-- [ ] Suíte + lint + typecheck verdes (contagem real, não suposição).
-- [ ] Findings P0/P1 corrigidos e re-verificados (hermaguard rodado de novo
-      se o fix alterou >3 arquivos).
-
-**Anti-padrões desta fase:**
-- NUNCA rodar hermaguard em código com testes quebrados (polui o review).
-- NUNCA dar "suíte passando" sem ter executado a suíte.
-- NÃO aceitar "hermaguard não achou nada" sem exigir a cobertura por classe
-  (edge cases, races, rollback, schema drift).
-- NÃO reportar achado P0/P1 como resolvido sem a verificação de volta.
-
-## Comandos de Verificação (executáveis)
-
-```bash
-# Gate de qualidade do próprio workflow (sem regressão)
-python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
-
-# Testes + meta-testes (prova que o harness detecta regressão)
-python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py
-
-# Audit OWASP de um endpoint/controller
-# (skill api-security-review) — veja a skill
-
-# CVE nas deps do projeto
-# (skill dependency-cve-audit) — veja a skill
-
-# Bug hunt adversarial no diff (read-only)
-# (skill hermaguard: "hermaguard this")
-```
-
-## Critérios de Aceite (checklist não-regressivo)
-
-- [ ] Contrato aprovado (PLAN) antes de qualquer handler.
-- [ ] BUILD com defaults seguros; `secure-coding` validado na stack.
-- [ ] SECURITY: bola/auth/injection/api-review/CVE rodados; P0/P1 resolvidos.
-- [ ] TEST: hermaguard + TDD + security-test-generator; suíte verde com
-      contagem real.
-- [ ] Nenhuma skill do stack removida do arquivo.
-- [ ] Rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`
-      → exit 0 (sem regressão).
-
-## Exemplos de execução por fase (comandos reais)
-
-Fase 1 — validar contrato antes de codar:
-
-```bash
-# Lista de rotas planejadas (contrato em aberto)
-cat > docs/contract.md <<'EOF'
-POST /api/v1/users   -> 201 | 400 | 401 | 409 | 429
-GET  /api/v1/users/:id -> 200 | 404 | 403
-Erros: RFC 9457 (application/problem+json)
-EOF
-```
-
-Fase 2 — build seguro (exemplo FastAPI + Pydantic):
-
-```bash
-# Rodar a stack e conferir a OpenAPI gerada
-uvicorn app.main:app --reload   # ou npm run dev
-curl -s localhost:8000/openapi.json | python3 -m json.tool > /tmp/openapi.json
-python3 -c "import sys,json; d=json.load(open('/tmp/openapi.json')); print('schemas:', len(d.get('components',{}).get('schemas',{})))"
-
-# Validação de contrato contra a OpenAPI real
-curl -s localhost:8000/health -i | head -5        # status codes do health
-curl -s -X POST localhost:8000/api/v1/users -d '{}' -i | head -5  # 400 esperado
-```
-
-Fase 3 — auditoria de segurança:
-
-```bash
-# Rodar as skills de auditoria OWASP (veja cada skill p/ uso exato)
-# bola-detector: "audite rotas com :id" / auth-rbac-scaffold: "valide o fluxo de login"
-# injection-checker: "escaneie SQL/ORM" / api-security-review: "revisão OWASP do conjunto"
-# dependency-cve-audit: "audite as dependências" (skill local)
-```
-
-Fase 4 — testes e bug hunt:
-
-```bash
-python3 -m pytest -v                   # ou npm test
-python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py  # gate do workfl
-# "hermaguard this"  (bug hunt adversarial no diff)
-```
-
-Gates anti-regressão (rodar junto com o fluxo):
-
-```bash
-python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py   # teste dos testes
-# verifica que o harness DETECTA regressão (mutações sempre derrubam o score)
-python3 -m pytest tests/security/ -x   # se existir suíte de segurança
-```
+- [ ] Nível 2+: contrato aprovado antes do primeiro handler.
+- [ ] Toda entrada externa validada na borda; erros em RFC 9457.
+- [ ] Queries de dado do usuário escopadas ao ID autenticado.
+- [ ] Nenhum P0/P1 de segurança aberto; CVEs consultados ao vivo, com data.
+- [ ] Migração reversível provada (up, down, up) quando o schema mudou.
+- [ ] Gate `pass`, ou `incomplete` com a lista do que não foi verificado dita ao usuário.
 
 ## Regras duras
 
-- NUNCA escrever handler antes do contrato aprovado.
-- NUNCA entregar endpoint sem passar pelas 4 fases (security + testes +
-  hermaguard).
-- Rota que mexe em dado do usuário → ownership-check obrigatório (query
-  escopada ao ID autenticado).
-- Tests vermelhos = fixar primeiro; hermaguard não roda em código quebrado.
+- Nunca escrever handler antes do contrato aprovado (nível 2+).
+- Nunca rodar `hermaguard` ou auditoria em código com testes vermelhos; corrija os testes primeiro.
+- Nunca dizer "suíte passando" sem ter rodado a suíte.