@brunosps00/dev-workflow 0.7.0 → 0.8.1

package/scaffold/skills/api-testing-recipes/recipes/rust-reqwest.md

@@ -0,0 +1,173 @@
+# Recipe: `reqwest + tokio::test` (Rust)
+
+Use for Axum, Actix-web, Rocket. Async HTTP client that pairs naturally with each framework's tower / actix-rt runtime.
+
+Two execution modes:
+
+- **A: against a running server** — best when the project already exposes the API in dev.
+- **B: in-process via `axum::Router::oneshot`** — fastest, no port, no flake.
+
+## File shape (mode A — running server, framework-agnostic)
+
+`{{PRD_PATH}}/QA/scripts/api/rf_xx_[slug].rs` (typically a `tests/` integration target):
+
+```rust
+// RF-XX [slug] — API QA suite
+use reqwest::{Client, StatusCode};
+use serde_json::{json, Value};
+
+fn base() -> String { std::env::var("API_BASE_URL").unwrap_or_else(|_| "http://localhost:3000".into()) }
+fn token_admin() -> String { std::env::var("QA_TOKEN_ADMIN").unwrap_or_default() }
+fn token_other() -> String { std::env::var("QA_TOKEN_OTHER_ORG").unwrap_or_default() }
+
+fn client() -> Client {
+    Client::builder().timeout(std::time::Duration::from_secs(10)).build().unwrap()
+}
+
+#[tokio::test]
+async fn happy_path_returns_201() {
+    let r = client().post(format!("{}/users", base()))
+        .bearer_auth(token_admin())
+        .json(&json!({ "email": format!("qa-{}@example.com", uuid::Uuid::new_v4()), "name": "QA" }))
+        .send().await.unwrap();
+    assert_eq!(r.status(), StatusCode::CREATED);
+    let body: Value = r.json().await.unwrap();
+    assert!(body.get("id").is_some());
+}
+
+#[tokio::test]
+async fn validation_missing_email_returns_422() {
+    let r = client().post(format!("{}/users", base()))
+        .bearer_auth(token_admin())
+        .json(&json!({ "name": "No email" }))
+        .send().await.unwrap();
+    assert_eq!(r.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    let body: Value = r.json().await.unwrap();
+    let msg = body["error"]["message"].as_str().unwrap_or_default().to_lowercase();
+    assert!(msg.contains("email"));
+}
+
+#[tokio::test]
+async fn no_token_returns_401() {
+    let r = client().post(format!("{}/users", base()))
+        .json(&json!({ "email": "x@y.com", "name": "x" }))
+        .send().await.unwrap();
+    assert_eq!(r.status(), StatusCode::UNAUTHORIZED);
+}
+
+#[tokio::test]
+async fn cross_tenant_denied() {
+    if token_other().is_empty() { return; }
+    let r = client().get(format!("{}/users/{}", base(), "00000000-0000-0000-0000-000000000001"))
+        .bearer_auth(token_other())
+        .send().await.unwrap();
+    assert!(matches!(r.status(), StatusCode::FORBIDDEN | StatusCode::NOT_FOUND));
+}
+
+#[tokio::test]
+async fn contract_required_fields_present_no_leaks() {
+    let create = client().post(format!("{}/users", base()))
+        .bearer_auth(token_admin())
+        .json(&json!({ "email": format!("c-{}@example.com", uuid::Uuid::new_v4()), "name": "C" }))
+        .send().await.unwrap();
+    let created: Value = create.json().await.unwrap();
+    let id = created["id"].as_str().unwrap();
+
+    let get = client().get(format!("{}/users/{}", base(), id))
+        .bearer_auth(token_admin())
+        .send().await.unwrap();
+    assert_eq!(get.status(), StatusCode::OK);
+    let body: Value = get.json().await.unwrap();
+
+    for f in ["id", "email", "name", "created_at"] { assert!(body.get(f).is_some(), "missing {f}"); }
+    for leak in ["password_hash", "internal_id", "_raw"] {
+        assert!(body.get(leak).is_none(), "leaked {leak}");
+    }
+}
+```
+
+## File shape (mode B — Axum in-process via `Router::oneshot`)
+
+```rust
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use http_body_util::BodyExt;
+use my_app::build_router;
+use serde_json::{json, Value};
+use tower::util::ServiceExt;
+
+#[tokio::test]
+async fn happy_path_oneshot() {
+    let app = build_router().await;
+    let req = Request::post("/users")
+        .header("authorization", "Bearer test-admin")
+        .header("content-type", "application/json")
+        .body(Body::from(json!({"email":"qa@example.com","name":"QA"}).to_string()))
+        .unwrap();
+    let res = app.oneshot(req).await.unwrap();
+    assert_eq!(res.status(), StatusCode::CREATED);
+    let bytes = res.into_body().collect().await.unwrap().to_bytes();
+    let body: Value = serde_json::from_slice(&bytes).unwrap();
+    assert!(body.get("id").is_some());
+}
+```
+
+`build_router()` is the project's exported async function that returns the `axum::Router` — same one used in `main.rs`.
+
+## Configuration
+
+`Cargo.toml`:
+
+```toml
+[dev-dependencies]
+reqwest = { version = "0.12", features = ["json", "rustls-tls"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+serde_json = "1"
+uuid = { version = "1", features = ["v4"] }
+# mode B (Axum):
+http-body-util = "0.1"
+tower = { version = "0.5", features = ["util"] }
+```
+
+## Running
+
+```bash
+# all
+cargo test --test rf_xx_create_user -- --nocapture
+
+# log to QA/logs/api/
+cargo test --test rf_xx_create_user -- --nocapture 2>&1 \
+  | tee "QA/logs/api/run-$(date +%F).log"
+```
+
+## Logging request/response
+
+`reqwest` doesn't ship a logging middleware out of the box. Two options:
+
+- **Wrap at the test layer**: small helper that calls `client.execute(req)` and writes JSONL.
+- **Tower middleware in mode B**: insert a `tower::Layer` that logs request/response. Reuse the project's tracing/logging layer if it has one.
+
+```rust
+use std::fs::OpenOptions;
+use std::io::Write;
+
+async fn log_request(method: &str, url: &str, status: u16, ms: u128, body: &str) {
+    std::fs::create_dir_all("QA/logs/api").ok();
+    let mut f = OpenOptions::new().create(true).append(true)
+        .open("QA/logs/api/RF-XX-create-user.log").unwrap();
+    let entry = serde_json::json!({
+        "ts": chrono::Utc::now().timestamp_millis(),
+        "method": method, "url": url, "status": status, "ms": ms,
+        "response_body": body,
+    });
+    writeln!(f, "{entry}").ok();
+}
+```
+
+## Pros / cons
+
+- **Pro (mode B)**: in-process, no port, fastest, deterministic.
+- **Pro**: `tokio::test` integrates with the project's existing `cargo test` flow.
+- **Pro**: type-safe assertions on response bodies.
+- **Con (mode A)**: depends on the server being up before `cargo test`.
+- **Con (mode B)**: requires the project to expose a `build_router()` factory.

package/scaffold/skills/api-testing-recipes/recipes/supertest-node.md

@@ -0,0 +1,153 @@
+# Recipe: `supertest` (Node.js / TypeScript)
+
+Use for Fastify, Express, NestJS projects that already run `vitest` or `jest`. supertest binds directly to the app instance and runs in-process — no port allocation, no flake.
+
+## File shape
+
+`{{PRD_PATH}}/QA/scripts/api/RF-XX-[slug].test.ts`
+
+```ts
+// RF-XX [slug] — API QA suite
+import request from 'supertest';
+import { describe, expect, it, beforeAll } from 'vitest';
+import { buildApp } from '../../../src/app'; // or: import app from '../../../src/server';
+
+const BASE = process.env.API_BASE_URL ?? 'http://localhost:3000';
+const TOKEN_ADMIN = process.env.QA_TOKEN_ADMIN ?? '';
+const TOKEN_USER = process.env.QA_TOKEN_USER ?? '';
+const TOKEN_OTHER_ORG = process.env.QA_TOKEN_OTHER_ORG ?? '';
+
+let app: Awaited<ReturnType<typeof buildApp>>;
+let createdUserId: string;
+
+beforeAll(async () => { app = await buildApp(); });
+
+const auth = (t: string) => ({ Authorization: `Bearer ${t}` });
+
+describe('RF-XX create user', () => {
+
+  it('happy path returns 201 and id', async () => {
+    const r = await request(app.server).post('/users')
+      .set(auth(TOKEN_ADMIN))
+      .send({ email: `qa-${Date.now()}@example.com`, name: 'QA' });
+    expect(r.status).toBe(201);
+    expect(r.body.id).toBeDefined();
+    createdUserId = r.body.id;
+  });
+
+  it.each([
+    [{ name: 'No email' }, 'email'],
+    [{ email: 'no-name@x.com' }, 'name'],
+    [{ email: 'not-an-email', name: 'X' }, 'email'],
+  ])('validation: %j → mentions %s', async (payload, missing) => {
+    const r = await request(app.server).post('/users')
+      .set(auth(TOKEN_ADMIN))
+      .send(payload);
+    expect(r.status).toBe(422);
+    expect(r.body.error.message.toLowerCase()).toContain(missing);
+  });
+
+  it('no token returns 401', async () => {
+    const r = await request(app.server).post('/users')
+      .send({ email: 'x@y.com', name: 'x' });
+    expect(r.status).toBe(401);
+  });
+
+  it('expired token returns 401', async () => {
+    const r = await request(app.server).post('/users')
+      .set({ Authorization: 'Bearer expired.token.here' })
+      .send({ email: 'x@y.com', name: 'x' });
+    expect(r.status).toBe(401);
+  });
+
+  it('cross-tenant access denied', async () => {
+    if (!TOKEN_OTHER_ORG) return;
+    const r = await request(app.server).get(`/users/${createdUserId}`)
+      .set(auth(TOKEN_OTHER_ORG));
+    expect([403, 404]).toContain(r.status);
+  });
+
+  it('contract: required fields present, leaked fields absent', async () => {
+    const r = await request(app.server).get(`/users/${createdUserId}`)
+      .set(auth(TOKEN_ADMIN));
+    expect(r.status).toBe(200);
+    for (const f of ['id', 'email', 'name', 'created_at']) {
+      expect(r.body[f]).toBeDefined();
+    }
+    for (const f of ['password_hash', 'internal_id', '_raw']) {
+      expect(r.body[f]).toBeUndefined();
+    }
+  });
+});
+```
+
+## Configuration
+
+`vitest.config.ts`:
+
+```ts
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    include: ['QA/scripts/api/**/*.test.ts'],
+    testTimeout: 10_000,
+    hookTimeout: 30_000,
+  },
+});
+```
+
+## Running
+
+```bash
+# all
+pnpm vitest run QA/scripts/api
+
+# one RF
+pnpm vitest run QA/scripts/api/RF-01-create-user.test.ts
+
+# log to QA/logs/api/
+pnpm vitest run QA/scripts/api 2>&1 | tee "QA/logs/api/run-$(date +%F).log"
+```
+
+## Logging request/response
+
+Wrap the supertest agent in a small helper that emits to JSONL:
+
+```ts
+import fs from 'node:fs';
+
+const LOG = 'QA/logs/api/RF-XX-create-user.log';
+fs.mkdirSync('QA/logs/api', { recursive: true });
+
+function logRequest(method: string, url: string, status: number, ms: number, reqBody: unknown, resBody: unknown) {
+  fs.appendFileSync(LOG, JSON.stringify({
+    ts: Date.now(), method, url, status, ms, request_body: reqBody, response_body: resBody,
+  }) + '\n');
+}
+```
+
+## NestJS variant
+
+Use `@nestjs/testing`'s `Test.createTestingModule(...)` + `app.getHttpServer()` instead of `buildApp`:
+
+```ts
+import { Test } from '@nestjs/testing';
+import { AppModule } from '../../../src/app.module';
+
+let app: INestApplication;
+beforeAll(async () => {
+  const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
+  app = moduleRef.createNestApplication();
+  await app.init();
+});
+
+// then: request(app.getHttpServer()) ...
+```
+
+## Pros / cons
+
+- **Pro**: in-process, no port allocation, fastest possible.
+- **Pro**: integrates with `vitest`/`jest` watch + coverage.
+- **Pro**: `it.each` covers the 4xx matrix in one block.
+- **Con**: only works against a `supertest`-compatible HTTP framework.
+- **Con**: requires the `buildApp` factory pattern; one-off scripts/handlers may need refactor.

package/scaffold/skills/api-testing-recipes/references/auth-patterns.md

@@ -0,0 +1,138 @@
+# Auth patterns — how to wire credentials into API tests
+
+Tests need real credentials, but credentials must never live in the script files (which are committed). This file describes how each recipe handles the four common auth schemes and where credentials come from.
+
+## The four schemes
+
+| Scheme | How it travels | Recipe handling |
+|--------|----------------|-----------------|
+| **Bearer JWT** | `Authorization: Bearer <token>` | Most common. Token comes from a login response or pre-issued for QA. |
+| **Cookie session** | `Cookie: session=<sid>` (set by `Set-Cookie` on login) | Recipes capture the cookie from a login call and replay it. |
+| **API key** | `X-API-Key: <key>` (header) or `?api_key=<key>` (query) | Header form is preferred; key comes from a per-environment env var. |
+| **Basic auth** | `Authorization: Basic <base64(user:pass)>` | Rare in modern APIs; supported but discouraged. |
+
+## Where credentials come from (in priority order)
+
+1. **`.env` file** at the repo root, gitignored. Contains `QA_TOKEN_ADMIN`, `QA_ADMIN_EMAIL`, `QA_ADMIN_PASSWORD`, etc.
+2. **Pre-issued QA tokens** — long-lived JWTs minted by an admin tool (e.g., a `make qa-tokens` target) and stored in `.env`. Best for CI; avoids login-time flake.
+3. **Login at runtime** — a setup request hits `/auth/login` with `QA_ADMIN_EMAIL` + `QA_ADMIN_PASSWORD` and captures the token. Use when no pre-issued option exists.
+4. **`.dw/templates/qa-test-credentials.md`** — the project-level QA credentials registry that `dw-run-qa` already reads (UI mode). API mode reads the same file for env-var hints + role mapping.
+
+## Three roles every project should have
+
+Even for single-tenant apps, define at minimum:
+
+- **`token_admin`** — has every permission. Used for setup (create test data) and teardown.
+- **`token_user`** — regular authenticated user. The role most happy-path tests run as.
+- **`token_guest`** OR **`token_other_org_admin`** — for negative tests. In multi-tenant apps, this token belongs to a different org and powers the cross-tenant denial tests.
+
+## Per-recipe variable conventions
+
+### `.http` (REST Client)
+
+Top of the file:
+
+```http
+@base = {{$dotenv API_BASE_URL}}
+@token_admin = {{$dotenv QA_TOKEN_ADMIN}}
+@token_user = {{$dotenv QA_TOKEN_USER}}
+@token_other_org = {{$dotenv QA_TOKEN_OTHER_ORG}}
+```
+
+Or, if logging in at runtime, capture once and reuse:
+
+```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);
+client.test("login ok", () => client.assert(response.status === 200));
+%}
+```
+
+### `pytest + httpx`
+
+Read from environment in module scope; expose as fixtures if the test count grows:
+
+```python
+TOKEN_ADMIN = os.environ["QA_TOKEN_ADMIN"]
+TOKEN_USER = os.environ["QA_TOKEN_USER"]
+TOKEN_OTHER_ORG = os.environ.get("QA_TOKEN_OTHER_ORG", "")
+
+@pytest.fixture(scope="session")
+async def admin_client():
+    async with httpx.AsyncClient(base_url=BASE,
+        headers={"Authorization": f"Bearer {TOKEN_ADMIN}"},
+        timeout=10.0) as c:
+        yield c
+```
+
+### `supertest` (Node)
+
+Same `process.env` reads, optionally one helper per role:
+
+```ts
+const auth = (token: string) => ({ Authorization: `Bearer ${token}` });
+const TOKEN_ADMIN = process.env.QA_TOKEN_ADMIN!;
+```
+
+### `WebApplicationFactory` (.NET)
+
+Subclass the factory once per role:
+
+```csharp
+public class AdminAppFactory : WebApplicationFactory<Program>
+{
+    protected override void ConfigureClient(HttpClient client)
+    {
+        client.DefaultRequestHeaders.Authorization =
+            new AuthenticationHeaderValue("Bearer",
+                Environment.GetEnvironmentVariable("QA_TOKEN_ADMIN") ?? "");
+    }
+}
+```
+
+### `reqwest` (Rust)
+
+Helper functions read env once:
+
+```rust
+fn token_admin() -> String { std::env::var("QA_TOKEN_ADMIN").unwrap_or_default() }
+fn admin_client() -> reqwest::Client {
+    reqwest::Client::builder().build().unwrap()
+}
+// then: admin_client().get(url).bearer_auth(token_admin()).send().await
+```
+
+## Refresh tokens
+
+If the API uses refresh tokens, capture both `access_token` and `refresh_token` in the login setup. When a test needs a long-lived flow (e.g., wait for a webhook), refresh the access token before the wait.
+
+For most QA suites, the access token's TTL (typically 15-60 min) is longer than the suite's runtime, so refresh is unnecessary.
+
+## Scoped credentials per role
+
+For RBAC-heavy systems, define more roles:
+
+- `token_admin` — global admin
+- `token_org_admin` — admin within one org
+- `token_member` — regular member of one org
+- `token_billing` — read-only billing access
+- `token_other_org_admin` — admin of a different org (for cross-tenant tests)
+
+Add one env var per role; the recipe reads them as needed. Tests that don't need a particular role just don't reference it.
+
+## Anti-patterns
+
+- **Don't hardcode `Bearer eyJ...` in any committed file.** Even "test" tokens leak.
+- **Don't share one token across happy-path AND negative tests.** If a happy-path test mutates the token's user (e.g., suspends it), every later test fails.
+- **Don't reuse production tokens for QA.** Mint QA-only tokens with a clearly distinct subject (`sub: qa-admin@example.com`).
+- **Don't pass credentials via command-line args.** They land in shell history and process listings.
+
+## What `dw-run-qa` does
+
+In API mode, `/dw-run-qa` reads `QA/test-credentials.md` (or `.env`) for the env var names, picks the recipe, and substitutes variables at test-generation time. The script files reference `@variable` references only — never raw tokens.

package/scaffold/skills/api-testing-recipes/references/log-conventions.md

@@ -0,0 +1,117 @@
+# Log conventions — request/response evidence as JSONL
+
+In API mode, **logs replace screenshots** as the primary QA evidence. Every request/response pair the QA suite makes is captured as one JSONL line so the bug report links back to a reproducible event.
+
+## File location
+
+`{{PRD_PATH}}/QA/logs/api/<scope>.log`
+
+Where `<scope>` is one of:
+
+- `RF-XX-[slug].log` — log for a single requirement run (1 file per RF).
+- `BUG-NN-retest.log` — log for a fix retest (1 file per bug retest cycle).
+- `run-<YYYY-MM-DD>.log` — global run log (full QA pass).
+
+## Line shape (JSONL — one JSON object per line)
+
+```json
+{
+  "ts": 1715000000000,
+  "rf": "RF-03",
+  "case": "happy-path",
+  "method": "POST",
+  "url": "http://localhost:3000/users",
+  "request_headers": {
+    "authorization": "Bearer <redacted>",
+    "content-type": "application/json"
+  },
+  "request_body": {
+    "email": "qa-1@example.com",
+    "name": "QA"
+  },
+  "status": 201,
+  "response_headers": {
+    "content-type": "application/json",
+    "location": "/users/12345"
+  },
+  "response_body": {
+    "id": "12345",
+    "email": "qa-1@example.com",
+    "name": "QA",
+    "created_at": "2026-05-06T12:00:00Z"
+  },
+  "ms": 47,
+  "verdict": "PASS",
+  "assertion_failures": []
+}
+```
+
+## Required fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `ts` | int (epoch ms, UTC) | When the request was sent |
+| `rf` | string | Which `RF-XX` this request belongs to (or `"BUG-NN"` for retests) |
+| `case` | string | One of `happy-path`, `validation`, `auth-missing`, `auth-expired`, `authz-cross-tenant`, `not-found`, `conflict`, `server-error`, `contract` |
+| `method` | string | HTTP method |
+| `url` | string | Full URL including query string |
+| `status` | int | HTTP status code |
+| `ms` | int | Elapsed milliseconds |
+| `verdict` | string | `"PASS"` or `"FAIL"` |
+| `assertion_failures` | array of strings | Each failed assertion as a one-line description (empty array on PASS) |
+
+## Optional fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `request_headers` | object | Map of header name → value |
+| `request_body` | any | Parsed JSON if `Content-Type: application/json`; raw string otherwise |
+| `response_headers` | object | Same shape as request_headers |
+| `response_body` | any | Parsed JSON if `Content-Type: application/json`; raw string otherwise |
+| `err` | string | Network/runtime error message (if no response was received at all) |
+
+## Redaction rules
+
+The log goes to `QA/logs/api/` which **may end up in artifacts uploaded to CI** or attached to bug reports. Redact:
+
+- **`Authorization` header** → `"Bearer <redacted>"` or `"Basic <redacted>"`. The token's presence is logged; the value never is.
+- **`Cookie` header** → `"<redacted>"`. Same reasoning.
+- **`X-API-Key` header** → `"<redacted>"`.
+- **Response fields named `password*`, `secret*`, `*_hash`, `token*`, `apiKey*`** → `"<redacted>"`. These should never be in a response anyway; if they are, the log redacts AND the QA report flags the leak.
+- **Free-form `request_body` fields named `password`** → `"<redacted>"`.
+
+The redaction is applied at log-write time, never on read; even a leaked log file should not expose secrets.
+
+## Why JSONL (not pretty-printed JSON)
+
+- **Append-friendly**: each request is one line; concurrent runs append safely without parsing the whole file.
+- **Greppable**: `grep '"verdict":"FAIL"' QA/logs/api/RF-03.log` shows every failed case in one shot.
+- **Queryable**: `jq -c 'select(.status >= 500)' QA/logs/api/run-*.log | jq -s 'group_by(.url) | map({url: .[0].url, count: length})'` finds the most-failing URLs.
+- **Diffable across runs**: `diff <(jq -c 'del(.ts, .ms)' RF-03.log) <(jq -c 'del(.ts, .ms)' RF-03.log.prev)` shows behavior changes free of timing noise.
+
+## Per-recipe writers
+
+Every recipe in `recipes/` includes a small writer helper in its example:
+
+- `.http` — the agent writes via `Bash` after each `curl` invocation.
+- `pytest+httpx` — `LoggingClient` subclass overriding `request`.
+- `supertest` — small `logRequest` helper imported by tests.
+- `.NET WebApplicationFactory` — `DelegatingHandler` registered on the test client.
+- `reqwest` — wrapper function around `client.execute(req)`.
+
+All of them produce the same JSONL shape so downstream tooling (the QA report renderer, the bug retest loop) doesn't care which recipe was used.
+
+## How `dw-run-qa` reads logs back
+
+When generating the QA report (Step 8 in `dw-run-qa`), the agent reads each `RF-XX-[slug].log`, computes:
+
+- **Total requests** per RF
+- **Pass count vs fail count**
+- **Failing cases** with the assertion message
+- **Tail latency** (p99 if there are ≥10 requests, max otherwise)
+
+These land in the report's "Verified Requirements" table and feed the bug entries (with `evidence_path: QA/logs/api/RF-03.log#L42` pointing to the failing line).
+
+## How `dw-fix-qa` consumes them
+
+The retest loop reads `QA/bugs.md` for each open bug, finds the corresponding log line via `evidence_path`, replays the request via the same recipe + assertions, and writes a new line to `BUG-NN-retest.log` with `verdict: "PASS"` (closing the bug) or `verdict: "FAIL"` (cycling through the fix-retest loop again, max 5 cycles).

package/scaffold/skills/api-testing-recipes/references/matrix-conventions.md

@@ -0,0 +1,68 @@
+# Matrix conventions — deriving tests from a PRD requirement
+
+Every API requirement (`RF-XX`) gets a structured matrix of test cases. The matrix is the bridge between "the PRD says this endpoint must exist" and "we have evidence it works under the cases that matter."
+
+## The five tiers
+
+For each `RF-XX`, generate at least one test per tier that applies:
+
+| Tier | Goal | When to skip |
+|------|------|--------------|
+| **200 happy path** | Prove the endpoint accepts the documented input and returns the documented output. | Never — every RF needs at least one happy path. |
+| **4xx — validation** | Prove input validation rejects malformed payloads with a useful error. | Skip only for endpoints with no body (`GET` without query params). |
+| **4xx — auth (401)** | Prove missing/expired/invalid credentials return 401. | Skip for endpoints documented as anonymous. |
+| **4xx — authorization (403)** | Prove valid credentials without the required role/scope return 403. | Skip if the endpoint is open to any authenticated user. |
+| **4xx — not found (404)** | Prove non-existent IDs return 404, not 500. | Skip for endpoints that don't take an ID. |
+| **4xx — conflict (409)** | Prove duplicates / version mismatches return 409. | Skip if the endpoint is idempotent and conflict-free by design. |
+| **5xx — server error** | Prove the system fails gracefully (no leaked stack trace, no half-write). | Skip if no synthetic failure is reproducible without invasive infrastructure changes. |
+| **Contract drift** | Prove the response shape matches the documented spec (OpenAPI, TS types, README examples). | Never — this is the cheapest way to catch silent breakage. |
+| **Authorization cross-tenant** | Prove tokens from org A cannot access data of org B. | Skip only for single-tenant systems (rare in practice). |
+
+## Why the cross-tenant test is mandatory
+
+Cross-tenant data leakage is the most damaging API bug class — it's silent (no error), undetected by happy-path tests, and lethal in B2B SaaS. Every endpoint that returns or mutates tenant-scoped data must have a cross-tenant denial test. If the project is single-tenant, mark the test `pytest.skip` / `it.skip` / `[Fact(Skip="single-tenant")]` instead of omitting — the explicit skip is a record of the decision.
+
+## How to enumerate inputs per tier
+
+For each tier, ask:
+
+- **200**: what's the minimum valid payload? Build the test around that. Add 2-3 variations only if the endpoint has interesting branching (nullable fields, enum variants, optional sections).
+- **4xx validation**: what fields are required? Drop each one. What types are constrained? Send the wrong type. What ranges? Test min-1 and max+1. Don't test all combinations — one per kind of constraint is enough.
+- **4xx auth**: 3 variants — no token, expired token, malformed token. One test for each is enough.
+- **4xx authorization**: identify role boundaries (admin vs user vs guest, owner vs member). One test per boundary.
+- **4xx not found**: 1 test with a syntactically-valid-but-nonexistent ID (UUID, integer, etc.).
+- **4xx conflict**: 1 test that triggers the documented conflict (duplicate email, race on version).
+- **5xx**: skip if not reproducible. If the project has a way to inject failures (chaos hooks, dev-only error endpoints), use them.
+- **Contract drift**: 1 test that asserts every documented field is present AND no leaked internal field is.
+- **Cross-tenant**: 1 test per tenant-scoped endpoint with a token from a different tenant.
+
+## Example expansion: `POST /users`
+
+PRD says: "RF-03 — admins can create users. Validation: email is required and must be unique. Returns 201 with the new user."
+
+Matrix:
+
+| # | Tier | Case | Expected |
+|---|------|------|----------|
+| 1 | 200 | admin creates user with valid payload | 201, body has id |
+| 2 | 4xx validation | missing email | 422, error mentions email |
+| 3 | 4xx validation | invalid email format | 422 |
+| 4 | 4xx auth | no token | 401 |
+| 5 | 4xx auth | expired token | 401 |
+| 6 | 4xx authorization | regular user (not admin) | 403 |
+| 7 | 4xx conflict | email already taken | 409 |
+| 8 | Contract | all required fields present, no `password_hash` | matches spec |
+| 9 | Cross-tenant | admin from another org tries to fetch this user | 403 or 404 |
+
+That's 9 test cases for one RF — the floor for a real API surface, not the ceiling.
+
+## What NOT to do
+
+- **Don't test every combination** of validation failures. The framework already enforces type + presence; one test per kind of constraint is the signal.
+- **Don't test the framework**. `Content-Type: application/json` parsing, default routing, etc. — those belong to FastAPI / Fastify / ASP.NET, not to your QA suite.
+- **Don't write tests for endpoints with no PRD reference**. If a route exists but no RF describes it, that's a documentation gap to flag, not a test to add.
+- **Don't skip 5xx because "it shouldn't happen"**. If you have a way to reproduce, do it. If you genuinely can't, document the skip in the QA report so the gap is visible.
+
+## How `dw-run-qa` uses this
+
+When in API mode, `/dw-run-qa` walks each `RF-XX` in the PRD, runs through this matrix, and emits PASS/FAIL per RF — not per test case. A single FAIL in any tier marks the RF as FAIL and lands a `BUG-NN` entry pointing to the failing log line.