Ir para o conteúdo

Quality Layer (Esteira de Qualidade)
Tipo Camada transversal de qualidade — shift-left, gates determinísticos
Triggers /qa-plan · /run-regression · /smoke · /validacao-testes · /qa-gate
Agentes qa-strategist → test-validator → smoke-runner → qa-expert → learning-agent (loop)
Policy qa-policy.md (hard stop)
Status 🔬 experimental (v1.5.0) — ADR-009

Pré-requisito: instalação concluída (00 — Instalação e Setup) + bloco quality no .claude/.local-config.json (comandos de test/coverage/smoke/e2e por stack).

1. O que é e quando usar

A maioria das equipes trata QA como uma fase no fim, feita por uma pessoa. Esta camada transforma QA em gates automatizados embutidos no pipeline: qualquer fix/feature só passa com cobertura, smoke e E2E garantidos. Um dev percorre discovery → implementação → entrega sozinho; o QA humano vira owner (cura regras e conhecimento, melhora os agentes).

Use sempre que houver código/UI mudando. Não substitui discovery (/discover) nem dev (/feature, /generate-fix) — aumenta esses fluxos.

2. Os 4 gates (shift-left)

DISCOVERY            DEV                      PRÉ-DEPLOY            DEPLOY
/discover·/qa-plan   /feature·/generate-fix   homologação
 FEAT-{N} testável → builder-agent       →    qa-expert       →    learning-agent
 + estratégia        ▸ GATE 1 cobertura       ▸ GATE 3 E2E         (loop do owner)
 (DoR-for-QA)        ▸ GATE 2 smoke           + Checkpoint 3
      └────────── mesmo FEAT-{N} atravessa os 4 gates ──────────┘
                     ▸ /qa-gate = meta-gate (4 verdes) antes do PR/release
Gate Comando Agente Critério (hard stop)
1 — Cobertura + Execucao no dev (1a+1b) /run-regression test-validator 1a: diff coverage ≥ threshold + RED→GREEN (ou N/A-por-ADR) · 1b: QA Plan (CTs) via Playwright no dev/stg
2 — Smoke /smoke smoke-runner caminho crítico passa (exit 0)
3 — E2E /validacao-testes qa-expert 100% dos FEAT-{N} com evidência
S — Security /scan-vuln --semgrep-only (diff) vuln-triage 0 findings ≥ MEDIUM no diff
Meta /qa-gate (consolida) os 4 verdes → libera PR/release

Segurança em todo flow, em duas lentes: o Gate S (SAST do diff) roda no /qa-gate; o /security-review (lente semântica, LLM) roda no /open-pr e bloqueia a criação do PR com finding ≥ MEDIUM.

3. Passo a passo

Shift-left — /qa-plan (qa-strategist)

Deriva dos FEAT-{N} a estratégia por camada (qual FEAT é unit/smoke/E2E), checa testabilidade (DoR-for-QA) e define massa. Output: .ns-flow/delivery/<ticket>-qa-plan.md. Rode no discovery (após CP-D2) ou no início do ticket.

Gate 1 — /run-regression (test-validator)

1a (cobertura): escreve testes (RED→GREEN), roda build gate e o gate de cobertura do diff (ou N/A-por-ADR quando o stack não permite unit). 1b (execução no dev): executa o QA Plan (CTs) via Playwright no ambiente dev/stg (nunca HML — HML é o Gate 3), reusando o motor do qa-expert com ambiente=dev. Vermelho em 1a ou 1b → bloqueia.

Gate 2 — /smoke (smoke-runner)

Roda o caminho crítico do sistema afetado. Vermelho → bloqueia.

Gate 3 — /validacao-testes (qa-expert)

Valida os FEAT-{N} na UI de HML (Playwright/Voidr) com evidência visual, anti-falso-positivo/negativo. Alimenta o Checkpoint 3 (homologação).

Meta-gate — /qa-gate

Consolida os 4 e dá o veredito único. 4 verdes → libera /open-pr e /release-check; o release-agent recusa o release sem isso.

Loop — learning-agent

Grava métricas de QA no metrics-feed e propõe deltas para .speckit/quality/ (seletores, mensagens, navegação, flaky) — o owner revisa e consolida.

4. Gates e checkpoints

Gate Tipo Bloqueia?
1, 2, 3, meta automático (determinístico) sim, hard stop
Checkpoint 3 (homologação) humano reviewer confirma com base no Gate 3

Só há um checkpoint humano dedicado à qualidade — o Checkpoint 3 (homologação), alimentado pelo Gate 3. Os demais gates são automáticos.

5. Pastas e arquivos gerados

Fase Arquivo
Shift-left .ns-flow/delivery/<ticket>-qa-plan.md
Gate 1 .ns-flow/delivery/<ticket>-validation.md
Gates 2/3/meta .ns-flow/delivery/<ticket>-qa-report.md + evidencias/
Loop metrics-feed.jsonl + .speckit/quality/

6. Papéis no time

Papel Responsabilidade
Dev Roda os gates (/qa-plan→…→/qa-gate); entrega com qualidade garantida nos gates
QA (owner) Cura .speckit/quality/ e thresholds; revisa flaky/exploratório; promove regressivo — ver Guia do QA Owner
Reviewer Confirma a homologação no Checkpoint 3 com base no Gate 3

7. Definições honestas

  • "100% de cobertura" = 100% do código alterado (diff), configurável por severidade — não do repo legado inteiro.
  • "E2E 100%" = 100% dos FEAT-{N} tocados, não 100% da UI.
  • Tooling real é por projeto: sem comando configurado no bloco quality, o gate reporta "não configurado" e instrui o owner — nunca passa silenciosamente.
  • O QA não some — vira owner.

Referências

Voltar ao topo