agent-friendly L2-2: make verify (health contract)

.github/workflows/ci.yml

@@ -54,6 +54,23 @@ jobs:
         # moto mocks DynamoDB — no AWS credentials required
         run: PYTHONPATH=. pytest tests/ -v
 
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: make verify
+        # HTTP contracts via lambda_handler (GET /health + request/status/confirm)
+        run: make verify
+
   synth:
     runs-on: ubuntu-latest
     steps:

Makefile

@@ -1,8 +1,14 @@
 # Agent-friendly check: shortest path = correct path.
 # No deploy. Requires: pip install -r requirements.txt -r requirements-dev.txt
 # and -r cdk/requirements.txt; Node for npx.
+#
+# make verify  = prove-it-works (HTTP contracts via lambda_handler, incl. GET /health)
+# make check   = full gate (lint + typecheck + all tests + cdk synth)
 
-.PHONY: check test synth lint typecheck
+.PHONY: check test synth lint typecheck verify
+
+verify:
+	PYTHONPATH=. pytest tests/test_http_contract.py -v
 
 test:
 	PYTHONPATH=. pytest tests/ -v

README.md

@@ -19,7 +19,7 @@ API serverless para solicitação de exclusão de cliente com geração de QR Co
 
 - [ADR-001 — Unificar exclusão Pix (CDK + Lambda)](docs/adr/ADR-001-unificar-exclusao-pix.md) — **Accepted** (CAB 2026-09-20). Este repo é o canônico; `aws-api-gateway-cdk` será arquivado após migrar o stack. Access pattern Dynamo: pointer `LATEST`. Auth (PR3): Cognito JWT.
 
-**Feature map (agents):** [docs/feature-map.md](docs/feature-map.md) — rotas, auth Cognito JWT, env vars, pré-reqs `make check`.
+**Feature map (agents):** [docs/feature-map.md](docs/feature-map.md) — rotas, auth Cognito JWT, env vars, pré-reqs `make verify` / `make check`.
 
 ---
 
@@ -38,20 +38,24 @@ Cada solicitação grava **dois** itens (histórico depois ponteiro):
 - **Confirmar pagamento** atualiza histórico e depois `LATEST` (condition em `active_request_id`).
 - Writes ordenados (`put`/`update`) de propósito neste PR — TransactWrite fica pra um follow-up se precisar atomicidade forte.
 
-### Testes / check local
+### Testes / check / verify local
 
 ```bash
 pip install -r requirements.txt
 pip install -r requirements-dev.txt   # ruff + mypy
 pip install -r cdk/requirements.txt   # só se for rodar synth
-PYTHONPATH=. pytest tests/test_exclusao.py -v
-# caminho curto (lint + types + pytest + cdk synth, sem deploy):
+# prove-it-works (HTTP contracts via lambda_handler, incl. GET /health):
+make verify
+# full gate (lint + types + all pytest + cdk synth, sem deploy):
 make check
 ```
 
 Usa **moto** (sem AWS real). O pacote `lambda/` importa via `importlib` (nome reservado).
 
-CI (GitHub Actions): em todo PR/`push` na `main` — jobs **`lint`** (ruff + mypy), **`test`** (pytest/moto) e **`synth`** (`npx aws-cdk@2 synth`, sem AWS / sem deploy).
+- **`make verify`** = `tests/test_http_contract.py` (agent-trusted HTTP status/body contracts).
+- **`make check`** = lint + typecheck + `pytest tests/` + cdk synth.
+
+CI (GitHub Actions): em todo PR/`push` na `main` — jobs **`lint`**, **`test`**, **`verify`** (`make verify`), e **`synth`** (sem AWS / sem deploy).
 
 ### Agent-friendly / hard constraints
 

docs/feature-map.md

@@ -36,17 +36,19 @@ HTTP lives in `lambda/app.py`. Dynamo LATEST helpers in `lambda/domain_dynamo.py
 
 No secrets in repo. Cognito IDs / `ApiUrl` only via CloudFormation outputs after deploy (CAB).
 
-## Pre-reqs — tests / check
+## Pre-reqs — tests / verify / check
+
+Prove-it-works path for agents: **`make verify`** (HTTP contracts in `tests/test_http_contract.py` via `lambda_handler`, including `GET /health` → 200). Full gate: **`make check`**.
 
 ```bash
 pip install -r requirements.txt
 pip install -r requirements-dev.txt   # ruff + mypy
 pip install -r cdk/requirements.txt   # for synth
-PYTHONPATH=. pytest tests/test_exclusao.py -v
-make check   # lint + typecheck + test + cdk synth (no deploy)
+make verify  # HTTP contracts (health + request/status/confirm)
+make check   # lint + typecheck + all tests + cdk synth (no deploy)
 ```
 
-CI jobs on PR/`push` to `main`: **lint** (ruff + mypy), **test** (pytest/moto), **synth** (`npx aws-cdk@2 synth`).
+CI jobs on PR/`push` to `main`: **lint** (ruff + mypy), **test** (pytest/moto), **verify** (`make verify`), **synth** (`npx aws-cdk@2 synth`).
 
 ## Hard constraints (encoded)
 
@@ -60,4 +62,4 @@ CI jobs on PR/`push` to `main`: **lint** (ruff + mypy), **test** (pytest/moto),
 | [ADR-001](adr/ADR-001-unificar-exclusao-pix.md) | Canonical decision (monorepo, LATEST, Cognito) |
 | [ARCHITECTURE.md](../ARCHITECTURE.md) | Bounded context + components |
 | [SECURITY.md](../SECURITY.md) | Auth/CORS/throttle honesty |
-| [README.md](../README.md) | Deploy, Cognito lab curls, make check |
+| [README.md](../README.md) | Deploy, Cognito lab curls, make verify / make check |