@brunosps00/dev-workflow 0.8.0 → 0.8.1

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

@@ -9,7 +9,7 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
 ## Posição no Pipeline
 **Antecessor:** `/dw-run-plan` ou `/dw-run-task` | **Sucessor:** `/dw-code-review` (auto-fixes bugs internally before completing)
 
-<critical>Utilize o Playwright MCP para executar todos os testes E2E</critical>
+<critical>Em modo UI, use o Playwright MCP para todos os testes E2E. Em modo API (sem UI no projeto OU flag `--api`), use a skill bundled `api-testing-recipes` para gerar scripts `.http` / pytest+httpx / supertest / WebApplicationFactory / reqwest e capturar logs de request/response como evidência.</critical>
 <critical>Verifique TODOS os requisitos do PRD e TechSpec antes de aprovar</critical>
 <critical>O QA NÃO está completo até que TODAS as verificações passem</critical>
 <critical>Documente TODOS os bugs encontrados com screenshots de evidência</critical>
@@ -20,9 +20,10 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
 
 Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apoio operacional sem substituir este comando:
 
-- `webapp-testing`: apoio para estruturar fluxos de teste, retestes, screenshots e logs quando complementar ao Playwright MCP
-- `vercel-react-best-practices`: use apenas se o frontend sob teste for React/Next.js e houver indicação de regressão relacionada a renderização, fetching, hidratação ou performance percebida
-- `ui-ux-pro-max`: use quando validar consistência de design, paletas de cores, tipografia, espaçamento e hierarquia visual contra padrões da indústria
+- `webapp-testing`: (modo UI) apoio para estruturar fluxos de teste, retestes, screenshots e logs quando complementar ao Playwright MCP
+- `vercel-react-best-practices`: (modo UI) use apenas se o frontend sob teste for React/Next.js e houver indicação de regressão relacionada a renderização, fetching, hidratação ou performance percebida
+- `ui-ux-pro-max`: (modo UI) use quando validar consistência de design, paletas de cores, tipografia, espaçamento e hierarquia visual contra padrões da indústria
+- `api-testing-recipes`: **(modo API — SEMPRE)** snippets validados para `.http`, pytest+httpx, supertest, WebApplicationFactory, reqwest. Compõe um arquivo de teste por RF em `QA/scripts/api/` e logs JSONL em `QA/logs/api/` segundo seus references
 
 ## Ferramentas de Análise
 
@@ -38,12 +39,13 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apo
 ## Objetivos
 
 1. Validar implementação contra PRD, TechSpec e Tasks
-2. Executar testes E2E com Playwright MCP
-3. Cobrir cenários positivos, negativos, limites e regressões relevantes
-4. Verificar acessibilidade (WCAG 2.2)
-5. Realizar verificações visuais
-6. Documentar bugs encontrados
-7. Gerar relatório final de QA
+2. **Detectar modo** (UI vs API-only) e escolher o caminho de execução certo
+3. Executar testes E2E via Playwright MCP (modo UI) OU via skill `api-testing-recipes` (modo API)
+4. Cobrir cenários positivos, negativos, limites e regressões relevantes
+5. Verificar acessibilidade (modo UI = WCAG 2.2; modo API = formato de erro e contratos de superfície)
+6. Realizar verificações visuais (somente modo UI — pulado em modo API)
+7. Documentar bugs encontrados
+8. Gerar relatório final de QA
 
 ## Localização dos Arquivos
 
@@ -56,10 +58,13 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apo
 - Pasta de evidências QA (obrigatória): `{{PRD_PATH}}/QA/`
 - Relatório de Saída: `{{PRD_PATH}}/QA/qa-report.md`
 - Bugs encontrados: `{{PRD_PATH}}/QA/bugs.md`
-- Screenshots: `{{PRD_PATH}}/QA/screenshots/`
-- Logs (console/rede): `{{PRD_PATH}}/QA/logs/`
-- Scripts de teste Playwright: `{{PRD_PATH}}/QA/scripts/`
+- Screenshots (modo UI): `{{PRD_PATH}}/QA/screenshots/`
+- Logs — UI (console/rede): `{{PRD_PATH}}/QA/logs/`
+- Logs — API (JSONL request/response): `{{PRD_PATH}}/QA/logs/api/`
+- Scripts de teste Playwright (modo UI): `{{PRD_PATH}}/QA/scripts/`
+- Scripts de teste API (modo API — `.http` / pytest+httpx / supertest / etc.): `{{PRD_PATH}}/QA/scripts/api/`
 - Checklist consolidado: `{{PRD_PATH}}/QA/checklist.md`
+- Receitas de API testing (skill): `.agents/skills/api-testing-recipes/`
 
 ## Contexto Multi-Projeto
 
@@ -74,6 +79,43 @@ Consulte `.dw/rules/` para URLs e frameworks específicos do projeto.
 
 ## Etapas do Processo
 
+### 0. Detecção de Modo (UI vs API) — Obrigatório PRIMEIRO
+
+Decida se o projeto tem UI testável ou e API-only antes de qualquer setup de browser/API. O modo escolhido dirige todas as etapas seguintes.
+
+**Auto-detecção (mesma matriz usada por `/dw-dockerize`):**
+
+| Sinal | Modo UI | Modo API |
+|-------|---------|----------|
+| `package.json` deps | `next`, `vite`, `react`, `vue`, `svelte`, `@angular/*`, `nuxt`, `astro`, `solid-js`, `remix` | nenhum dos acima |
+| `pyproject.toml` / `requirements*.txt` | `jinja2`, `django` (full), `flask` + `flask_login`/`render_template` | `fastapi`, `flask` (so JSON), `starlette`, `litestar` |
+| `*.csproj` | `Microsoft.AspNetCore.Mvc`, Razor, Blazor | `Microsoft.AspNetCore.Mvc.Core` so, templates de minimal API |
+| `Cargo.toml` | `yew`, `leptos`, `dioxus`, `sycamore` | `axum`, `actix-web`, `rocket`, `warp` (sem template engine) |
+
+Se NENHUM sinal de UI bater → **modo API**. Se pelo menos um bate → **modo UI** (default).
+
+**Override manual (flags):**
+
+- `--api` força modo API (útil para rodar testes API headless dentro de um projeto fullstack onde a UI nao importa nesta rodada).
+- `--ui` força modo UI (gera erro claro se nenhuma dep de UI for detectada — evita rodar testes de browser contra repo backend-only sem querer).
+- `--from-openapi <path-or-url>` adiciona baseline OpenAPI em cima do modo API (veja `.agents/skills/api-testing-recipes/references/openapi-driven.md`).
+
+**Efeito nas etapas seguintes:**
+
+| Etapa | Modo UI | Modo API |
+|-------|---------|----------|
+| 2 — Preparação do Ambiente | Playwright + browser setup completo | Setup de cliente API, sem browser; cria `QA/scripts/api/` e `QA/logs/api/` |
+| 3 — Verificação de Páginas do Menu | obrigatório, bloqueante | **pulado** |
+| 4 — Testes E2E | Playwright MCP | skill `api-testing-recipes` (recipe por stack) |
+| 5 — Acessibilidade | WCAG 2.2 com browser tools | checks de superfície API (formato de erro, semântica de status, detecção de leak) |
+| 6 — Verificações Visuais | obrigatório (mobile + desktop) | **pulado** |
+| 7-8 — Documentação de Bugs + Relatório | screenshots como evidência | logs JSONL como evidência (`evidence_type: api-log`) |
+| 9 — Loop Fix-Retest | mesmo formato; replay do Playwright | mesmo formato; replay da recipe e gravação de nova linha de log |
+
+Registre o modo escolhido no frontmatter do relatório QA (`mode: ui | api | mixed`). Em caso de dúvida, pergunte ao usuário antes de prosseguir — nunca caia em fallback silencioso.
+
+<critical>Se nenhum sinal de UI nem de API for detectável (ex.: repo vazio), aborte com: "Não é possivel determinar o modo do QA. Rode `/dw-analyze-project` primeiro OU passe `--ui` ou `--api` explicitamente."</critical>
+
 ### 1. Análise de Documentação (Obrigatório)
 
 - Ler o PRD e extrair TODOS os requisitos funcionais numerados (RF-XX)
@@ -109,9 +151,11 @@ Se NENHUMA credencial for encontrada, PARE e pergunte ao usuário antes de conti
 - Confirmar que a página carregou corretamente com `browser_snapshot`
 - Se sessão persistente, import de auth, inspeção de rede além do MCP ou reprodução browser-first forem necessários, complementar com `webapp-testing`
 
-### 3. Verificação de Páginas do Menu (Obrigatório — Executar ANTES dos testes de RF)
+### 3. Verificação de Páginas do Menu (Somente modo UI — Obrigatório, Executar ANTES dos testes de RF)
 
-<critical>ANTES de testar RFs individuais, verificar que CADA item do menu do módulo leva a uma página FUNCIONAL e ÚNICA. Esta verificação é bloqueante — se falhar, o QA NÃO pode ser aprovado.</critical>
+**Em modo API, esta etapa é PULADA.** Superfícies de API não têm menus; o check equivalente (todo endpoint anunciado existe e responde) está dobrado dentro da Etapa 4-API.
+
+<critical>(modo UI) ANTES de testar RFs individuais, verificar que CADA item do menu do módulo leva a uma página FUNCIONAL e ÚNICA. Esta verificação é bloqueante — se falhar, o QA NÃO pode ser aprovado.</critical>
 
 Para cada item do menu do módulo:
 1. Navegar para a página via `browser_navigate`
@@ -146,7 +190,11 @@ digraph menu_check {
 }
 ```
 
-### 4. Testes E2E com Playwright MCP (Obrigatório)
+### 4. Testes E2E (Obrigatório, mode-aware)
+
+Esta etapa tem dois branches; escolha conforme o modo da Etapa 0.
+
+#### 4-UI (modo UI) — Playwright MCP
 
 Utilize as ferramentas do Playwright MCP para testar cada fluxo:
 
@@ -179,6 +227,39 @@ Para cada requisito funcional do PRD:
 <critical>Não basta validar apenas o caminho feliz. Cada requisito deve ser exercitado contra seus estados de borda e suas regressões mais prováveis</critical>
 <critical>Se um requisito não puder ser completamente validado via E2E, o QA deve ser marcado como REJEITADO ou BLOQUEADO, nunca APROVADO</critical>
 
+#### 4-API (modo API) — skill `api-testing-recipes`
+
+Use a skill bundled `api-testing-recipes` para compor os testes. A skill escolhe a recipe certa por stack (default `.http` / REST Client; `pytest+httpx`, `supertest`, `WebApplicationFactory`, `reqwest` por linguagem) e grava scripts e logs JSONL como evidência.
+
+Processo:
+
+1. **Leia** `.agents/skills/api-testing-recipes/SKILL.md` e selecione a recipe que casa com o stack backend primário do projeto. Default em `recipes/http-rest-client.md` a menos que o projeto já rode `pytest`/`vitest`/`dotnet test`/`cargo test`, caso em que prefira a recipe especifica do stack para os testes QA viverem ao lado dos testes unitários.
+2. **Para cada requisito funcional (RF-XX) do PRD**, derive a matriz seguindo `.agents/skills/api-testing-recipes/references/matrix-conventions.md`:
+   - 200 happy path
+   - 4xx — validação (campo faltando, tipo errado, fora de range)
+   - 4xx — auth (sem token, expirado, malformado)
+   - 4xx — autorização (token válido, role errada)
+   - 4xx — not found
+   - 4xx — conflict
+   - 5xx — server error (so se reproduzível sinteticamente)
+   - **Contract drift** (formato da response vs OpenAPI / TS types) — obrigatório
+   - **Authorization cross-tenant** (token de outra org) — obrigatório se multi-tenant
+3. **Gere um arquivo por RF** em `{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].<ext>` usando a estrutura da recipe. Encaminhe credenciais segundo os padrões em `.agents/skills/api-testing-recipes/references/auth-patterns.md` (NUNCA hardcode tokens).
+4. **Execute** cada request (`curl` para `.http`; o runner do projeto para stack-specific). Para CADA request, anexe uma linha JSONL em `{{PRD_PATH}}/QA/logs/api/RF-XX-[slug].log` segundo `references/log-conventions.md`. Redact headers `Authorization`/`Cookie`/`X-API-Key` e qualquer campo de response que case com `password*`/`secret*`/`*_hash`/`token*`.
+5. **Asserte** por expectativa da matriz:
+   - Status code casa com o esperado
+   - Response body casa com o schema (use `jq` em `.http`, matchers do framework por stack)
+   - Headers obrigatórios presentes (ex.: `Content-Type: application/json`)
+   - Sem campos internos vazados
+6. **Marque o requisito** como APROVADO ou REPROVADO com resumo de uma linha citando o caminho do log e (se REPROVADO) o número da linha JSONL que falhou.
+7. **Opcional**: se o projeto expõe spec OpenAPI (`openapi.yaml`, `openapi.json`, runtime `/openapi.json`), siga `references/openapi-driven.md` para gerar baseline. Use a flag `--from-openapi <path-or-url>` para deixar explícito.
+
+Nota sobre baseline OpenAPI: se `--from-openapi` for usado, os testes gerados ficam ao lado dos derivados a mão, com filename `openapi-RF-XX-[path-slug].<ext>`. Endpoints da spec sem mapeamento para nenhum RF viram lacuna documental no relatório QA (`openapi-no-rf-*`).
+
+<critical>(modo API) Todo endpoint que muta ou lê dados tenant-scoped DEVE ter teste de negacao cross-tenant. Pular so e permitido em sistemas explicitamente single-tenant e tem que ser registrado como `pytest.skip`/`it.skip`/equivalente com motivo.</critical>
+<critical>(modo API) Logs sao evidência. Toda afirmacao de PASS ou FAIL no relatorio QA deve citar uma linha JSONL em `QA/logs/api/`. Sem log = sem evidência = QA nao pode ser APROVADO.</critical>
+<critical>(modo API) NUNCA hardcode tokens ou credenciais em scripts commitados. Use referencias `@variavel`/env-var.</critical>
+
 ### 4.1. Matriz mínima obrigatória por requisito
 
 Para cada RF, o QA deve responder explicitamente:
@@ -201,9 +282,9 @@ Exemplos de edge cases que devem ser considerados sempre que relevantes:
 - reentrada/ações repetidas
 - falhas de API, loading e estados intermediários
 
-### 5. Verificações de Acessibilidade (Obrigatório)
+### 5. Acessibilidade / Checks de Superfície API (Obrigatório, mode-aware)
 
-Verificar para cada tela/componente (WCAG 2.2):
+Em **modo UI**, verificar para cada tela/componente (WCAG 2.2):
 
 - [ ] Navegação por teclado funciona (Tab, Enter, Escape)
 - [ ] Elementos interativos têm labels descritivos
@@ -217,13 +298,26 @@ Verificar para cada tela/componente (WCAG 2.2):
 Use `browser_press_key` para testar navegação por teclado.
 Use `browser_snapshot` para verificar labels e estrutura semântica.
 
-### 6. Verificações Visuais (Obrigatório)
+**Em modo API**, o checklist WCAG acima é SUBSTITUÍDO por checks de superfície API:
+
+- [ ] Todo endpoint retorna o `Content-Type` correto
+- [ ] Erros seguem formato consistente (ex.: `{ "error": { "code": "...", "message": "..." } }`)
+- [ ] `401` (auth missing/invalid) é distinto de `403` (auth presente mas não autorizado)
+- [ ] Responses de erro NÃO vazam stack traces, IDs internos, fragmentos SQL ou pistas de ambiente
+- [ ] Campos sensíveis (`password*`, `*_hash`, `secret*`, `token*`) NUNCA aparecem em response body
+- [ ] Endpoints com rate limit retornam `429` com header `Retry-After` (quando aplicável)
+
+Cada check FALHADO vira bug HIGH em `QA/bugs.md` com `evidence_type: api-log` apontando para a linha JSONL do erro.
+
+### 6. Verificações Visuais (Somente modo UI — Obrigatório)
+
+**Em modo API, esta etapa é PULADA.** O relatório QA omite a seção "Visual" inteira.
 
 - Capturar screenshots das telas principais com `browser_take_screenshot` e salvar em `{{PRD_PATH}}/QA/screenshots/`
 - Verificar layouts em diferentes estados (vazio, com dados, erro, loading)
 - Documentar inconsistências visuais encontradas
 
-### 6.1. Validação Mobile (Obrigatório)
+### 6.1. Validação Mobile (Somente modo UI — Obrigatório)
 
 <critical>TODA verificação visual DEVE incluir testes em viewport mobile (375px) ALÉM do desktop (1440px). A aprovação do QA REQUER que AMBAS as resoluções estejam funcionais e visualmente aceitáveis. Se o layout mobile estiver quebrado, inutilizável ou visualmente degradado, o QA NÃO pode ser aprovado.</critical>
 
@@ -246,13 +340,15 @@ Para cada bug encontrado, criar entrada em `{{PRD_PATH}}/QA/bugs.md`:
 
 - **Severidade:** Alta/Média/Baixa
 - **RF Afetado:** RF-XX
-- **Componente:** [componente/página]
+- **Componente:** [componente/página ou caminho do endpoint]
+- **Modo:** ui | api
 - **Passos para Reproduzir:**
   1. [passo 1]
   2. [passo 2]
 - **Resultado Esperado:** [o que deveria acontecer]
 - **Resultado Atual:** [o que acontece]
-- **Screenshot:** `QA/screenshots/[arquivo].png`
+- **Tipo de evidência:** screenshot | api-log
+- **Caminho da evidência:** `QA/screenshots/[arquivo].png` (modo UI) OU `QA/logs/api/RF-XX-[slug].log#L<linha>` (modo API)
 - **Status:** Aberto
 ```
 
@@ -294,10 +390,15 @@ Gerar relatório em `{{PRD_PATH}}/QA/qa-report.md`:
 [Parecer final do QA]
 ```
 
-### 9. Loop QA Fix-Retest (Automático)
+### 9. Loop QA Fix-Retest (Automático, mode-aware)
 
 <critical>O QA NÃO termina no primeiro relatório. Se bugs forem encontrados, entre em um loop automático de fix-retest até que o QA seja APROVADO ou explicitamente BLOQUEADO.</critical>
 
+**Comportamento mode-aware:** a estrutura do loop (max 5 ciclos, commit atômico por fix, regression checks, critérios de saída) é idêntica nos dois modos. O que muda é a EVIDÊNCIA replayada:
+
+- modo UI: re-executar o fluxo Playwright, capturar nova screenshot `BUG-NN-retest.png`.
+- modo API: re-executar a mesma `.http`/recipe via runner da recipe, anexar nova linha em `QA/logs/api/BUG-NN-retest.log` com `verdict: "PASS"` (fecha o bug) ou `verdict: "FAIL"` (segue o ciclo).
+
 Após gerar o relatório inicial de QA:
 
 ```dot

package/scaffold/skills/api-testing-recipes/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: api-testing-recipes
+description: Validated API-testing snippets (.http, pytest+httpx, supertest, WebApplicationFactory, reqwest) used by /dw-run-qa and /dw-fix-qa when the project has no UI. Default format is .http (REST Client) for IDE portability.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+---
+
+# api-testing-recipes
+
+Curated library of **API-testing snippets** that `/dw-run-qa` and `/dw-fix-qa` use when a project is API-only (no Playwright). Each recipe is a ready-to-customize block per stack; the default is `.http` (REST Client) for maximum portability across IDEs.
+
+## Why a skill (not inline)
+
+- Each recipe is independently maintainable. Bumping `pytest` or `supertest` patterns is a one-file change.
+- Discoverable by AI agents in any project the user installs dev-workflow into.
+- Reusable by future commands (e.g., `dw-bench-api`, `dw-contract-test`) without duplication.
+
+## When to Use
+
+Read this skill when:
+
+- `/dw-run-qa` detected API mode (no UI deps in the manifest) or was invoked with `--api`.
+- `/dw-fix-qa` is retesting a bug whose `evidence_type` is `api-log`.
+- Generating a baseline test suite from an OpenAPI spec.
+- Authoring contract checks against a backend.
+
+Do NOT use when:
+
+- The project has a UI and `/dw-run-qa` is in UI mode → use Playwright MCP instead.
+- The user wants browser-level acceptance (forms, navigation, accessibility) — that's Playwright territory.
+
+## Available Recipes
+
+| Format | When to use | Recipe path |
+|--------|-------------|-------------|
+| `.http` (REST Client) — DEFAULT | Universal. Reads in VSCode (REST Client), JetBrains (HTTP Client), Neovim (rest.nvim, kulala), Zed. Stack-agnostic. Best for projects without an existing test runner, or when devs read tests in their IDE. | `recipes/http-rest-client.md` |
+| `pytest + httpx` | Python project (FastAPI, Starlette, Flask). Already runs `pytest` in CI. Async client matches FastAPI's async-first design. | `recipes/pytest-httpx.md` |
+| `supertest` (Node/TS) | Node/TS project (Fastify, Express, NestJS). Already runs `vitest`/`jest`. Integrates with the app's test setup. | `recipes/supertest-node.md` |
+| `WebApplicationFactory<T>` (.NET) | C# project (ASP.NET Core minimal API or MVC). Built-in support for in-process testing without HTTP overhead. | `recipes/dotnet-webapp-factory.md` |
+| `reqwest + tokio::test` (Rust) | Rust project (Axum, Actix-web, Rocket). Async client matches Axum's tower-based design. | `recipes/rust-reqwest.md` |
+
+Picking order:
+1. Default to `.http` unless the project already has an established test runner.
+2. If the project has a test runner (`pytest`, `vitest`, `dotnet test`, `cargo test`), prefer the stack-specific recipe so QA tests live alongside unit tests.
+3. The user can override during the interview/run with `--format=http|pytest|supertest|dotnet|rust`.
+
+## How to Compose
+
+The composing command (`/dw-run-qa` API mode) follows this loop:
+
+1. **Pick the recipe** based on the rules above.
+2. **Read the recipe file** (`recipes/<name>.md`) for the variable conventions, test-matrix shape, and an example block.
+3. **For each requirement (RF-XX) in the PRD**, derive a test matrix per `references/matrix-conventions.md`:
+   - 200 happy path
+   - 4xx — validation, auth, not found, conflict
+   - 5xx — server error (synthetic)
+   - Contract drift — response shape vs OpenAPI / TS types
+   - Authorization cross-tenant
+4. **Generate** one file per RF in `{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].<ext>` using the recipe's structure. Wire credentials via the patterns in `references/auth-patterns.md` (NEVER hardcode tokens).
+5. **Execute** each request:
+   - `.http` → `curl` (Bash) or the in-IDE runner during interactive review.
+   - Stack-specific → the project's test runner (`pytest <files>`, `vitest run <files>`, `dotnet test --filter`, `cargo test`).
+6. **Log** every request/response per `references/log-conventions.md` to `{{PRD_PATH}}/QA/logs/api/RF-XX-[slug].log` (one JSONL line per request).
+7. **Assert** per matrix expectation: status code, response shape (use `jq` for `.http`, framework matchers per stack), headers.
+8. **Mark** PASS/FAIL per RF, citing the log path as evidence.
+
+## OpenAPI-Driven Mode
+
+If the project exposes OpenAPI (`openapi.yaml`/`openapi.json` static, or `/openapi.json` in runtime for FastAPI), follow `references/openapi-driven.md` to:
+- Generate a baseline of 200/4xx tests per endpoint automatically.
+- Detect contract drift by diffing live responses against the spec.
+- Skip endpoints marked `x-internal: true` or those without examples.
+
+## Variable Conventions
+
+Every recipe uses three variable layers:
+
+- **`@base`** — base URL (`http://localhost:3000` in dev). Set once per file.
+- **`@token_admin` / `@token_user` / `@token_guest`** — credential tokens, captured from a login response or read from `.env` / `QA/test-credentials.md`.
+- **`@<resource>_id`** — IDs created during a multi-step flow (e.g., create → fetch → update → delete on the same RF).
+
+Per-recipe details in `references/auth-patterns.md`.
+
+## References
+
+- `references/matrix-conventions.md` — how to derive the {200, 4xx, 5xx, contract drift, authz cross-tenant} matrix from a PRD requirement.
+- `references/auth-patterns.md` — how to capture and reuse JWT / cookie / API-key credentials in scripts; refresh-token patterns; scoped credentials per role.
+- `references/openapi-driven.md` — generating a baseline test suite from an OpenAPI spec; detecting contract drift.
+- `references/log-conventions.md` — JSONL log shape (one line per request: timestamp, method, url, status, request_headers, request_body, response_headers, response_body, ms).
+
+## Rules
+
+- **Default to `.http`** unless the project already has a test runner.
+- **Never hardcode credentials**. Always use `@variable` references that resolve to env vars or files outside git.
+- **Always log request + response** so the bug evidence is reproducible without re-running.
+- **One file per RF**. Don't pile every requirement into one giant test file.
+- **PASS/FAIL per RF, never per request**. A request that returns 401 when the matrix says it should is a PASS for that case.
+
+## Inspired by
+
+Hand-curated by dev-workflow. `.http` syntax follows the JetBrains HTTP Client / VSCode REST Client conventions. Per-stack recipes adapt patterns from each ecosystem's official testing docs (FastAPI testing tutorial, NestJS testing recipes, Microsoft.AspNetCore.Mvc.Testing docs, Axum testing examples).

package/scaffold/skills/api-testing-recipes/recipes/dotnet-webapp-factory.md

@@ -0,0 +1,168 @@
+# Recipe: `WebApplicationFactory<T>` + xUnit (.NET)
+
+Use for ASP.NET Core minimal API or MVC. Microsoft's official integration-testing pattern. Runs the full pipeline (DI, middleware, filters) in-process — no Kestrel port, no flake.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF_XX_[Slug]Tests.cs`
+
+```csharp
+using System.Net;
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using Microsoft.AspNetCore.Mvc.Testing;
+using Xunit;
+
+namespace YourProject.QA.Api;
+
+public class RF_XX_CreateUserTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly WebApplicationFactory<Program> _factory;
+    private readonly string _tokenAdmin = Environment.GetEnvironmentVariable("QA_TOKEN_ADMIN") ?? "";
+    private readonly string _tokenOtherOrg = Environment.GetEnvironmentVariable("QA_TOKEN_OTHER_ORG") ?? "";
+
+    public RF_XX_CreateUserTests(WebApplicationFactory<Program> factory) => _factory = factory;
+
+    private HttpClient Client(string? token = null)
+    {
+        var c = _factory.CreateClient();
+        if (!string.IsNullOrEmpty(token))
+            c.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
+        return c;
+    }
+
+    private record CreateUserDto(string Email, string Name);
+    private record UserResponse(string Id, string Email, string Name, DateTime CreatedAt);
+
+    [Fact]
+    public async Task HappyPath_Returns201()
+    {
+        var r = await Client(_tokenAdmin).PostAsJsonAsync("/users",
+            new CreateUserDto($"qa-{Guid.NewGuid():N}@example.com", "QA"));
+        Assert.Equal(HttpStatusCode.Created, r.StatusCode);
+        var body = await r.Content.ReadFromJsonAsync<UserResponse>();
+        Assert.NotNull(body);
+        Assert.NotNull(body!.Id);
+    }
+
+    [Theory]
+    [InlineData("{\"name\":\"No email\"}", "email")]
+    [InlineData("{\"email\":\"no-name@x.com\"}", "name")]
+    [InlineData("{\"email\":\"not-an-email\",\"name\":\"X\"}", "email")]
+    public async Task Validation_Returns422_AndMentionsField(string payload, string field)
+    {
+        var content = new StringContent(payload, System.Text.Encoding.UTF8, "application/json");
+        var r = await Client(_tokenAdmin).PostAsync("/users", content);
+        Assert.Equal(HttpStatusCode.UnprocessableEntity, r.StatusCode);
+        var msg = await r.Content.ReadAsStringAsync();
+        Assert.Contains(field, msg.ToLower());
+    }
+
+    [Fact]
+    public async Task NoToken_Returns401()
+    {
+        var r = await Client().PostAsJsonAsync("/users", new CreateUserDto("x@y.com", "x"));
+        Assert.Equal(HttpStatusCode.Unauthorized, r.StatusCode);
+    }
+
+    [Fact]
+    public async Task CrossTenant_Returns403Or404()
+    {
+        if (string.IsNullOrEmpty(_tokenOtherOrg)) return;
+        // assume a known id from another tenant; in a real suite, create one in setup
+        var r = await Client(_tokenOtherOrg).GetAsync("/users/00000000-0000-0000-0000-000000000001");
+        Assert.True(r.StatusCode is HttpStatusCode.Forbidden or HttpStatusCode.NotFound);
+    }
+
+    [Fact]
+    public async Task Contract_HasRequiredFields_NoLeaks()
+    {
+        var create = await Client(_tokenAdmin).PostAsJsonAsync("/users",
+            new CreateUserDto($"contract-{Guid.NewGuid():N}@example.com", "Contract"));
+        var created = await create.Content.ReadFromJsonAsync<UserResponse>();
+        var get = await Client(_tokenAdmin).GetAsync($"/users/{created!.Id}");
+        Assert.Equal(HttpStatusCode.OK, get.StatusCode);
+
+        var raw = await get.Content.ReadAsStringAsync();
+        foreach (var field in new[] { "id", "email", "name", "created_at" })
+            Assert.Contains(field, raw, StringComparison.OrdinalIgnoreCase);
+        foreach (var leak in new[] { "password_hash", "internal_id", "_raw" })
+            Assert.DoesNotContain(leak, raw, StringComparison.OrdinalIgnoreCase);
+    }
+}
+```
+
+## Configuration
+
+Project file (`*.QA.csproj` or extend the existing test project):
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.*" />
+  <PackageReference Include="xunit" Version="2.9.*" />
+  <PackageReference Include="xunit.runner.visualstudio" Version="2.8.*" />
+  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.*" />
+</ItemGroup>
+<ItemGroup>
+  <InternalsVisibleTo Include="$(AssemblyName)" />
+</ItemGroup>
+```
+
+The `Program` class must be public (for `WebApplicationFactory<Program>`). For minimal APIs, add at the bottom of `Program.cs`:
+
+```csharp
+public partial class Program { }
+```
+
+## Running
+
+```bash
+# all RF tests
+dotnet test --filter FullyQualifiedName~YourProject.QA.Api
+
+# one RF
+dotnet test --filter FullyQualifiedName~RF_XX_CreateUserTests
+
+# log to QA/logs/api/
+dotnet test --filter FullyQualifiedName~YourProject.QA.Api \
+  --logger "console;verbosity=detailed" 2>&1 \
+  | tee "QA/logs/api/run-$(date +%F).log"
+```
+
+## Logging request/response
+
+Use a custom `DelegatingHandler` registered on the factory's client:
+
+```csharp
+public class LoggingHandler : DelegatingHandler
+{
+    private static readonly string LogPath = "QA/logs/api/RF-XX-create-user.log";
+
+    protected override async Task<HttpResponseMessage> SendAsync(
+        HttpRequestMessage req, CancellationToken ct)
+    {
+        var sw = Stopwatch.StartNew();
+        var res = await base.SendAsync(req, ct);
+        sw.Stop();
+        Directory.CreateDirectory(Path.GetDirectoryName(LogPath)!);
+        var entry = new {
+            ts = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+            method = req.Method.Method,
+            url = req.RequestUri?.ToString(),
+            status = (int)res.StatusCode,
+            ms = sw.ElapsedMilliseconds,
+        };
+        await File.AppendAllTextAsync(LogPath,
+            System.Text.Json.JsonSerializer.Serialize(entry) + "\n", ct);
+        return res;
+    }
+}
+```
+
+## Pros / cons
+
+- **Pro**: in-process — full DI graph, no port, deterministic.
+- **Pro**: `[Theory]` + `[InlineData]` covers the 4xx matrix.
+- **Pro**: same project as unit tests; `dotnet test` runs both.
+- **Con**: requires `Program` to be partial and public.
+- **Con**: tied to `Microsoft.AspNetCore.Mvc.Testing` package versions.

package/scaffold/skills/api-testing-recipes/recipes/http-rest-client.md

@@ -0,0 +1,130 @@
+# Recipe: `.http` (REST Client) — DEFAULT
+
+Universal API-testing format. One file per RF. Read by VSCode REST Client, JetBrains HTTP Client, Neovim rest.nvim/kulala, Zed Assistant. No test runner needed.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].http`
+
+```http
+### RF-XX [slug] — happy path
+# @name create_user
+POST {{base}}/users
+Authorization: Bearer {{token_admin}}
+Content-Type: application/json
+
+{
+  "email": "qa-{{$randomInt 1 999999}}@example.com",
+  "name": "QA User"
+}
+
+> {%
+client.test("status is 201", () => client.assert(response.status === 201));
+client.test("response has id", () => client.assert(response.body.id != null));
+client.global.set("created_user_id", response.body.id);
+%}
+
+### RF-XX — 4xx validation: missing email
+POST {{base}}/users
+Authorization: Bearer {{token_admin}}
+Content-Type: application/json
+
+{ "name": "No email" }
+
+> {%
+client.test("status is 422", () => client.assert(response.status === 422));
+client.test("error mentions email", () => client.assert(response.body.error.message.toLowerCase().includes("email")));
+%}
+
+### RF-XX — 4xx auth: missing token
+POST {{base}}/users
+Content-Type: application/json
+
+{ "email": "x@y.com", "name": "x" }
+
+> {%
+client.test("status is 401", () => client.assert(response.status === 401));
+%}
+
+### RF-XX — 4xx authz: cross-tenant access
+GET {{base}}/users/{{created_user_id}}
+Authorization: Bearer {{token_other_org_admin}}
+
+> {%
+client.test("status is 403 or 404", () =>
+  client.assert(response.status === 403 || response.status === 404));
+%}
+
+### RF-XX — contract drift: response shape vs OpenAPI
+GET {{base}}/users/{{created_user_id}}
+Authorization: Bearer {{token_admin}}
+
+> {%
+client.test("has required fields", () => {
+  ["id", "email", "name", "created_at"].forEach(f =>
+    client.assert(response.body[f] != null, `missing ${f}`));
+});
+client.test("no leaked internal fields", () => {
+  ["password_hash", "internal_id", "_raw"].forEach(f =>
+    client.assert(response.body[f] === undefined, `leaked ${f}`));
+});
+%}
+```
+
+## Variables
+
+Set once at the top of the file (or in a `http-client.env.json` next to it):
+
+```http
+@base = {{$dotenv API_BASE_URL}}
+@token_admin = {{$dotenv QA_TOKEN_ADMIN}}
+@token_user = {{$dotenv QA_TOKEN_USER}}
+@token_other_org_admin = {{$dotenv QA_TOKEN_OTHER_ORG}}
+```
+
+Or, if the project uses login-based auth, capture the token in a setup request and reference it in subsequent requests:
+
+```http
+### Setup — login as admin
+# @name login_admin
+POST {{base}}/auth/login
+Content-Type: application/json
+
+{ "email": "{{$dotenv QA_ADMIN_EMAIL}}", "password": "{{$dotenv QA_ADMIN_PASSWORD}}" }
+
+> {% client.global.set("token_admin", response.body.access_token); %}
+```
+
+## Execution from `dw-run-qa` (CLI fallback)
+
+When running outside an IDE (e.g., from the agent in headless mode), parse and execute via `curl`:
+
+```bash
+# For each ### block, extract method/url/headers/body and execute:
+curl -sS -X POST "$BASE/users" \
+  -H "Authorization: Bearer $TOKEN_ADMIN" \
+  -H "Content-Type: application/json" \
+  -d '{"email":"qa-1@example.com","name":"QA"}' \
+  -w '\n%{http_code} %{time_total}s\n' \
+  | tee -a "QA/logs/api/RF-XX-create-user.log"
+```
+
+The `dw-run-qa` agent does this loop automatically and writes to the JSONL log per `references/log-conventions.md`.
+
+## Assertions
+
+Use the inline `> {% ... %}` post-response handler when running in an IDE. For headless `curl` execution, use `jq`:
+
+```bash
+RESP=$(curl -sS ...)
+STATUS=$(echo "$RESP" | head -1 | awk '{print $2}')
+[ "$STATUS" = "201" ] || { echo "FAIL: expected 201, got $STATUS"; exit 1; }
+echo "$RESP" | jq -e '.id != null' >/dev/null || { echo "FAIL: missing id"; exit 1; }
+```
+
+## Pros / cons
+
+- **Pro**: zero install, opens in any IDE, devs read it without running a test runner.
+- **Pro**: each request is a single block, easy to copy-paste into incident tickets.
+- **Con**: no native fixture/teardown — multi-request flows rely on `client.global.set` for state.
+- **Con**: parallel execution requires per-block uniqueness in resource names (use `{{$randomInt}}` or `{{$timestamp}}`).