agent-engineering-skills 1.0.0

package/skills/reliability/data-integrity-audit/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: data-integrity-audit
+description: Verifies unique constraints, foreign keys, transactions, cascading, soft delete, enums, and database constraints to confirm the database prevents impossible states instead of trusting application logic to do so.
+category: reliability
+triggers:
+  - "audit data integrity"
+  - "check database constraints"
+  - "unique constraint and foreign keys"
+  - "soft delete and orphaned data"
+  - "prevent impossible states at the db"
+priority: high
+---
+
+# Data Integrity Audit
+
+## Objective
+
+Ensinar o agente a verificar se o **banco de dados** impede estados impossíveis —
+em vez de confiar que a aplicação nunca vai gravá-los. A pergunta central (do
+`plan.md` §8):
+
+> "O banco deve impedir estados impossíveis sempre que apropriado."
+
+Campos em foco: unique constraints, foreign keys, transactions, cascading, soft delete,
+enums, database constraints.
+
+## When to Use
+
+* Quando a aplicação grava dados e *assume* invariants que só ela conhece (regra de
+  negócio) — se a regra não está no banco, outra rota pode violá-la.
+* Em fluxos com unicidade (username, slug, chave de idempotência), referências
+  (FK), estados (enum), e soft delete.
+* Quando há escrita concorrente ou múltiplos writers (jobs, workers, admin, import)
+  fora do fluxo da aplicação principal.
+* Quando o pedido menciona "data integrity", "constraints", "unique", "foreign key",
+  "soft delete", "orphans", "enums", "transactions".
+* **Composição:** pareia com `race-condition-hunter` (constraint = defesa contra
+  race), `idempotency-audit` (unique na chave de idempotência), `error-flow-audit`
+  (transação/rollback), `business-logic-audit` (invariants que deveriam ser constraints),
+  `state-consistency-audit` (banco como fonte de verdade).
+
+## Mental Model
+
+A aplicação é uma via de escrita; o banco é a **última linha de defesa**. Toda regra
+que impede um estado impossível deve, idealmente, existir como constraint — porque:
+
+1. **Aplicação não é o único writer** — jobs, workers, imports, admin tools, migrações,
+   e correções manuais escrevem fora dos handlers. Só o banco cobre todos.
+2. **Aplicação pode errar** — um bug de lógica grava dados inválidos e não há erro.
+   A constraint transforma silêncio em erro.
+3. **Aplicação pode ter race** — dois requests passam a checagem; a constraint rejeita
+   o segundo (ver `race-condition-hunter`).
+
+A skill verifica, para cada invariant importante: **ele está no banco, ou só na
+aplicação?** Se só na aplicação, é uma crença, não uma garantia.
+
+Eixos a verificar (do `plan.md` §8):
+
+```text
+unique constraints   — unicidade real ou contornável?
+foreign keys         — referências pendentes/órfãs?
+transactions         — writes agrupados atomically?
+cascading            — o que acontece quando o pai some?
+soft delete          — registros "deletados" ainda referenciáveis?
+enums                — estados fora do domínio permitidos?
+database constraints — CHECK, NOT NULL, DEFAULT, tipos corretos?
+```
+
+## Investigation Procedure
+
+1. **Inventariar invariants** do schema — unicidade, obrigatoriedade, domínio de
+   estados, referências, relação pai-filho.
+2. **Para cada, verificar se há constraint real no banco** (migração/schema), não só
+   validação de aplicação.
+3. **Unique**: a coluna é única no DB? Ou só verificada no handler? (race gap)
+4. **FK**: referências têm FK real com `ON DELETE` definido? (RESTRICT/CASCADE/SET NULL)
+5. **Transações**: operações multi-write são atômicas (uma transaction), ou writes
+   parciais possíveis?
+6. **Soft delete**: registros soft-deleted ainda são referenciáveis/recuperáveis sem
+   proteção? A unicidade ainda vale entre "deletado" e "ativo"?
+7. **Enums**: estados são `CHECK`/`enum` no DB, ou strings livres na aplicação?
+   Valores fora do domínio podem ser gravados?
+8. **Constraints de domínio**: NOT NULL, CHECK (ex: saldo ≥ 0), DEFAULT, tipos.
+9. **Testar**: tente inserir/atualizar um valor que violaria o invariant *direto no
+   banco* (ou via aplicação sem validação). O banco rejeita?
+10. **Confirmar com evidência** e reportar via `templates/audit-report.md`.
+
+## Questions to Ask
+
+* Cada invariant importante tem constraint no banco, ou só validação na aplicação?
+* Unique: há índice único? Ou duplicata é possível via race/outro writer?
+* FK: há constraint real? O `ON DELETE` está definido e correto?
+* Soft delete: a unicidade separa "deletado" de "ativo"? Um slug deletado pode ser
+  reclamado? Um item soft-deleted ainda é editável/referenciável?
+* Enums: o estado é validado pelo banco (CHECK/enum) ou string livre?
+* CHECK: o banco rejeita `balance < 0`, `quantity < 0`, `date` inválido?
+* Multi-write: as operações são atômicas? Uma falha no meio deixa partial?
+* Migrações: constraints existem no schema de produção, não só em algum ambiente?
+* Outros writers (jobs/admin/import) respeitam as regras que só a aplicação conhece?
+
+## Attack Patterns
+
+```text
+unique bypass
+    app: verifica username único no handler
+    banco: sem unique index
+    → race ou outro writer grava duplicata; unicidade violada silenciosamente
+
+orphan FK
+    post.deleted (hard)  → comments.post_id  pendente
+    sem FK / ON DELETE RESTRICT
+    → comentários órfãos, referência inválida
+
+soft delete + unique collision
+    "deleted" é só um flag; unique na coluna `slug`
+    → slug deletado bloqueia reuso, OU slug reusado cria duplicata visível
+    (defesa: unique parcial `WHERE deleted_at IS NULL`)
+
+enum as free string
+    estado gravado como string no app ("paid", "paid2")
+    banco: VARCHAR, sem CHECK
+    → estados fora do domínio persistidos; transições inválidas viram dado
+
+no CHECK on negative
+    banco aceita quantity = -5
+    app valida, mas import/job/admin grava -5
+    → estado impossível no dado
+
+transaction partial
+    writes em 3 tabelas sem transaction
+    falha na 2ª → 1ª commitada, 2ª e 3ª não
+    → estado parcial (overlap com error-flow-audit)
+
+cascade wrong
+    DELETE user → CASCADE apaga posts (talvez certo) ou RESTRICT bloqueia por um
+    comment órfão (talvez errado)
+    → política ON DELETE ausente ou errada
+
+NULL where not allowed
+    sem NOT NULL em coluna obrigatória (ownerId)
+    → registro sem dono; depois autorização quebra (overlap com authorization-audit)
+```
+
+## Evidence Requirements
+
+* **Nomear o invariant e o eixo** (unique/FK/transaction/soft-delete/enum/CHECK).
+* **Mostrar o schema real** — a migração/DDL que (não) tem a constraint. Cite o
+  arquivo/schema.
+* **Mostrar a violação** — inserção/atualização que o banco *aceita* mas que viola o
+  invariant. Ou a demonstração de que ela é possível (outro writer, race).
+* **Escalar confiança:**
+  * `CONFIRMED` — gravou o dado impossível direto no banco (ou provou o caminho que o
+    grava).
+  * `HIGH CONFIDENCE` — schema claramente sem a constraint em invariant claro.
+  * `POSSIBLE` — invariant assumido, ausência de constraint plausível.
+  * `SPECULATIVE` — "deveria ter constraint" sem identificar o invariant concreto.
+* Ausência de unique em unicidade real de negócio = mínimo `HIGH CONFIDENCE`.
+
+## False Positives
+
+* **Constraint existe em migração** — o índice/CHECK/FK existe no schema de produção;
+  a validação de app é defesa adicional. Confirmar no DDL real antes de reportar.
+* **Semanticamente não-único** — se a coluna *não deveria* ser única (ex: nomes
+  repetem), "sem unique" não é bug. Verificar o invariant de negócio.
+* **Soft delete sem reuso** — se o produto *não* reusa slugs/identificadores de
+  deletados, unique parcial é desnecessário. Julgar pelo comportamento desejado.
+* **Enums de app suficientes** — se todos os writers passam pela mesma validação de
+  enum da aplicação (nunca há outros writers), string livre é aceitável. Raro; verificar
+  a existência de outros writers.
+* **CHECK redundante** — se a app garante `balance ≥ 0` com lock+transaction e não há
+  outro writer, o CHECK é reforço, não necessidade. Marcar como melhoria, não bug.
+* **Cascade policy é correta para o domínio** — CASCADE em user→posts pode ser
+  intencional (dados sem valor pós-exclusão). Não reportar política correta.
+
+## Output Format
+
+Para cada invariant sem constraint no banco, um finding via `templates/audit-report.md`.
+Em **Affected component**, nomeie a tabela/coluna e o DDL. Em **Reproduction**, dê a
+inserção/atualização que viola o invariant e mostre que o banco aceita. Em **Root
+cause**, diga qual constraint falta (unique/FK/CHECK/enum/transaction/NOT NULL). Em
+**Recommendation**, indique a constraint exata (ex: `UNIQUE (user_id, target_id)`,
+`CHECK (balance >= 0)`, `FOREIGN KEY ... ON DELETE RESTRICT`, `CHECK` no enum) e a
+migração.
+
+Apresente a tabela por invariant (invariant | eixo | constraint no banco? | onde é
+aplicado hoje | ✓/✗). Unique e FK (dados órfãos/duplicados) primeiro; soft delete e
+enums depois; CHECK/transações em seguida.

package/skills/reliability/idempotency-audit/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: idempotency-audit
+description: Tests request → request → request and request → response-lost → retry, especially for payments, rewards, creation, webhooks, notifications, and counters, to find operations that duplicate effects on repeat or retry.
+category: reliability
+triggers:
+  - "audit idempotency"
+  - "duplicate effects on retry"
+  - "double submit double charge"
+  - "webhook replay"
+  - "request repeated N times"
+priority: high
+---
+
+# Idempotency Audit
+
+## Objective
+
+Ensinar o agente a testar se operações **idempotentes-deveria-ser** continuam
+produzindo efeito único quando repetidas ou reexecutadas após falha/retry:
+
+```text
+request
+request
+request        ← mesmo efeito 1×? ou efeito duplicado N×?
+
+request
+response lost
+retry           ← o retry duplica o efeito que já aconteceu?
+```
+
+Especialmente em (do `plan.md` §8): **pagamentos, rewards, criação, webhooks,
+notificações, contadores.**
+
+## When to Use
+
+* Em qualquer operação que *cria* algo, *concede* algo, *debita/cobra* algo, ou
+  *incrementa* — se repetida, duplicaria.
+* Em endpoints que recebem webhooks/retries de terceiros (gateway de pagamento,
+  provedores).
+* Quando o usuário pode duplo-submitar (duplo clique, retry manual).
+* Quando o pedido menciona "idempotency", "duplicate", "double charge", "double
+  submit", "webhook replay", "retry".
+* **Composição:** pareia com `error-flow-audit` (retry após falha mid-op),
+  `race-condition-hunter` (retry concorrente), `gamification-audit` (reward duplicada),
+  `api-abuse-audit` (repetição via API), `business-logic-audit` (regra de efeito único).
+
+## Mental Model
+
+Idempotência não é "aceitar o request duas vezes". É **produzir o mesmo efeito** na
+segunda vez. Um POST que cria um pedido é idempotente só se reenviá-lo (mesma
+idempotency key, mesmo payload) retorna o pedido original sem criar outro.
+
+O que torna um request *candidato* a idempotente: existe uma **chave de idempotência**
+(um identificador estável da intenção — ex: `Idempotency-Key` header, `orderId`,
+`eventId` de webhook) e o servidor **verifica a chave** antes de executar. Sem chave
+verificada, a repetição duplica.
+
+Eixo de investigação:
+
+```text
+qual é a chave de idempotência?      (se não existe, suspeito)
+o servidor verifica antes de agir?   (lookup por chave antes do efeito)
+o efeito é duplicado no retry?       (quando a chave não é verificada, ou a resposta se perdeu)
+```
+
+Áreas críticas (efeito duplicado = consequência real):
+
+```text
+payments      — cobrança duplicada
+rewards       — XP/pontos concedidos 2×
+creation      — recurso criado 2×
+webhooks      — evento processado 2× (sem eventId dedup)
+notifications — email/SMS duplicado
+counters      — incremento dobrado
+```
+
+## Investigation Procedure
+
+1. **Listar operações que criam/concedem/debitam/incrementam.**
+2. **Para cada, identificar a chave de idempotência natural** — existe no request
+   (header, idempotency key, eventId) ou no payload?
+3. **Rastrear onde a chave é verificada** — o handler busca o efeito pela chave antes
+   de executar? Ou executa sempre?
+4. **Testar repetição** — envie o mesmo request N vezes (mesma chave/payload). Efeito
+   único ou duplicado?
+5. **Testar response-lost + retry** — envie, ignore a resposta, reenvie. O servidor
+   reconhece e retorna o efeito original, ou executa de novo?
+6. **Testar duplo-submit** — dois POSTs no mesmo instante (double click). Um 200 e um
+   409, ou dois 200 com dois efeitos?
+7. **Testar webhook dedup** — o mesmo evento entregue 2× (retry do provider) é
+   processado 2×?
+8. **Testar concorrência de idempotência** — dois requests com a mesma chave chegam
+   juntos; ambos passam a verificação antes de qualquer um gravar? (race no dedup)
+9. **Confirmar com evidência** — reproduza a duplicação.
+10. **Reportar** via `templates/audit-report.md`.
+
+## Questions to Ask
+
+* Qual é a chave de idempotência desta operação? Ela existe?
+* O servidor verifica a chave antes de executar, ou executa e só então grava?
+* Enviar o mesmo request 2× — efeito único ou duplicado?
+* Resposta perdida + retry — o servidor reconhece ou reexecuta?
+* Double click / duplo submit — dois efeitos?
+* Webhook reentregue pelo provider (retry) — processado 2×?
+* A verificação de idempotência é atômica (lock/unique na chave), ou dois requests com
+  a mesma chave podem passar juntos?
+* O efeito é registrado *depois* de um efeito externo irreversível (cobrança)? (se sim,
+  conecta a `error-flow-audit`)
+
+## Attack Patterns
+
+```text
+creation duplicated
+    POST /orders  → 200 (pedido A)
+    POST /orders  (mesmo payload) → 200 (pedido B)  ← dois pedidos, deveria reusar A
+
+payment double charge
+    POST /charge {amount, orderId} → 200 (cobrado)
+    retry (response lost) → 200 (cobrado de novo)  ← sem idempotency key verificado
+
+reward double-grant
+    POST /react → +10 XP
+    replay → +10 XP de novo (mesmo target)  ← sem "already reacted" dedup
+
+webhook reprocessing
+    provider: eventId=evt_123 entregue → processado (pedido pago)
+    provider retry (sem ACK): evt_123 de novo → processado 2× (recompensa 2×)
+    ← falta dedup por eventId
+
+notification duplicate
+    POST /notify → email enviado
+    retry → email de novo  ← sem dedup por recipient+type+id
+
+counter double increment
+    POST /increment (mesma chave) ×2 → count += 2  ← deveria += 1
+
+race on idempotency key
+    A e B: POST {key:"k1"}  (nenhum gravou ainda)
+    ambos passam lookup (não acham k1)
+    ambos executam → efeito duplicado apesar da chave
+    defesa: unique constraint na chave (segundo INSERT falha)
+```
+
+## Evidence Requirements
+
+* **Nomear a operação e sua chave de idempotência** (ou a ausência dela).
+* **Mostrar o efeito duplicado** — repetição/retry/replay reproduzido, com o efeito 1×
+  vs 2×.
+* **Mostrar onde a chave não é verificada** — o handler executa sem lookup por chave,
+  ou verifica depois de agir.
+* **Verificar a atomicidade do dedup** — a chave tem unique constraint? Ou dois
+  requests simultâneos passam juntos (race)?
+* **Escalar confiança:**
+  * `CONFIRMED` — reproduziu o efeito duplicado (2 pedidos, 2 cobranças, 2 rewards).
+  * `HIGH CONFIDENCE` — handler executa sem verificação de chave em operação de
+    efeito-único; sem reprodução.
+  * `POSSIBLE` — operação candidata, caminho não confirmado.
+  * `SPECULATIVE` — "pode duplicar em retry" sem rastrear.
+* Duplicação de cobrança/reward = mínimo `HIGH CONFIDENCE` se o padrão for claro.
+
+## False Positives
+
+* **Idempotência real** — se há idempotency key + lookup + unique constraint, a
+  repetição retorna o efeito original. Confirmar antes de reportar.
+* **Operação é naturalmente idempotente** — `GET`, `PUT` com valor absoluto (SET), e
+  `DELETE` muitas vezes são idempotentes por natureza. Não reportar.
+* **Duplo-submit defendido** — se o botão desabilita no submit E o servidor tem
+  idempotency, defesa em profundidade. Não reportar.
+* **Webhook com dedup por eventId** — se o provider envia eventId e o servidor dedup
+  por ele (único), reprocessamento é evitado. Confirmar a dedup.
+* **Notificação é fire-and-forget tolerada** — se o produto tolera email duplicado
+  raro (e não há consequência), pode ser aceitável. Julgar pelo impacto.
+* **Contador é aproximado por design** — alguns contadores (views) são eventualmente
+  consistentes e toleram drift. Relacionado a `state-consistency-audit`; não reportar
+  se o produto tolera.
+* **Retry com query-decidida** — se após response lost o sistema consulta o estado
+  real antes de reexecutar, é idempotente por compensação. Não reportar.
+
+## Output Format
+
+Para cada operação que duplica efeito em repetição/retry, um finding via
+`templates/audit-report.md`. Em **Reproduction**, dê a sequência de requests (mesma
+chave/payload) e o efeito observado 1× vs 2×. Em **Affected flow**, nomeie a operação
+(payment/reward/creation/webhook/notification/counter). Em **Root cause**, diga o que
+falta (idempotency key, lookup antes de agir, unique constraint na chave, dedup por
+eventId). Em **Recommendation**, indique a defesa (chave + `INSERT ... ON CONFLICT`/
+unique, lookup + reuso do efeito, dedup por eventId em webhooks).
+
+Apresente a tabela por operação (operação | chave de idempotência | verificada antes de
+agir? | dedup atômico? | efeito duplicado? | ✓/✗). Cobranças e rewards primeiro;
+criação, webhooks e notificações depois; contadores por último (impacto menor).

package/skills/reliability/race-condition-hunter/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: race-condition-hunter
+description: Hunts for READ → DECISION → WRITE sequences and asks what happens if another request modifies the shared state between the read and the write, exposing double-spend, over-limit grants, and counter inflation under concurrency.
+category: reliability
+triggers:
+  - "audit race conditions"
+  - "find concurrency bugs"
+  - "read then write check-then-act"
+  - "double-spend and over-limit under concurrency"
+  - "two simultaneous requests"
+priority: high
+---
+
+# Race Condition Hunter
+
+## Objective
+
+Ensinar o agente a reconhecer o padrão canônico de race condition e a testar se o
+sistema sobrevive a dois requests simultâneos sobre o mesmo estado:
+
+```text
+READ
+  ↓
+DECISION
+  ↓
+WRITE
+```
+
+A pergunta central (do `plan.md` §8):
+
+> "O que acontece se outro request modificar o estado entre essas operações?"
+
+## When to Use
+
+* Sempre que uma operação lê estado, decide baseada no que leu, e escreve — sem lock ou
+  atomicidade.
+* Em fluxos com valor: saldo, estoque, cota/limite, contador, reward, voto, convite.
+* Quando há "check-then-act": checa saldo → debita; checa limite → concede; checa
+  unicidade → cria.
+* Quando o pedido menciona "race condition", "concurrency", "simultaneous", "double
+  spend", "TOCTOU", "check then act".
+* **Composição:** pareia com `idempotency-audit` (retry concorrente), `business-logic-audit` (limite/invariant que dependem de read-then-write), `data-integrity-audit`
+  (constraint/lock que deve defender), `error-flow-audit` (estado parcial após falha
+  concorrente), `gamification-audit` (reward farming concorrente).
+
+## Mental Model
+
+Uma race condition não é sobre *velocidade* — é sobre **janela entre leitura e escrita**.
+Se dois requests leem o mesmo estado (ambos veem "ok"), ambos decidem "permitido", e
+ambos escrevem, o invariant é violado — mesmo que cada um isoladamente esteja correto.
+
+```text
+request A: READ  balance=100   (≥50? yes)
+request B: READ  balance=100   (≥50? yes)   ← mesma leitura, A ainda não commitou
+request A: WRITE balance=50
+request B: WRITE balance=50    ← saldo real = 50, mas dois débitos de 50 = -50 efetivo
+```
+
+O defeito é a **ausência de atomicidade** entre read e write. As defesas:
+* **lock** (pessimistic) — ninguém lê/escreve entre;
+* **conditional update / CAS** (optimistic) — `UPDATE … WHERE balance=100` falha se
+  mudou;
+* **unique constraint** — o banco impede a duplicata;
+* **serializable transaction / SELECT FOR UPDATE** — o banco isola.
+
+A skill procura a janela e pergunta qual defesa (se alguma) a fecha.
+
+## Investigation Procedure
+
+1. **Encontrar sequências READ → DECISION → WRITE.** Para cada operação que muta
+   estado baseada em leitura, mapeie as três etapas.
+2. **Identificar o estado compartilhado** — linha de DB, contador, cache, arquivo.
+3. **Identificar o invariant** que a decisão protege (saldo ≥ 0, limite ≤ N, único,
+  estoque ≥ 0).
+4. **Determinar a atomicidade** — há transação? lock? CAS? constraint? ou read e write
+   em momentos separados sem proteção?
+5. **Modelar a intercalação** — dois requests (ou mais) lêem o mesmo estado antes de
+   qualquer write. Ambos passam pela decisão?
+6. **Confirmar com evidência** — se possível, reproduza (dois requests simultâneos,
+   ou raciocínio sobre o SQL mostrando que o `WHERE` não guarda a condição).
+7. **Verificar a defesa** — o `UPDATE` é condicional ao valor lido? Há `SELECT FOR
+   UPDATE`? Unique constraint? Se sim, a janela está fechada.
+8. **Reportar** via `templates/audit-report.md`.
+
+## Questions to Ask
+
+* A operação lê estado e depois escreve baseada no que leu? Qual o invariant?
+* Entre o READ e o WRITE, outro request pode modificar o mesmo estado?
+* Há transação? Ela é serializable / usa SELECT FOR UPDATE, ou só agrupa queries?
+* O UPDATE é condicional (`WHERE balance = :lido`) ou incondicional (`SET balance = :novo`)?
+* Há unique constraint que impediria a duplicata mesmo sem lock de aplicação?
+* O limite/cota é checado em read-then-write, ou decrementado atomicamente?
+* Dois requests simultâneos passam ambos pela checagem de saldo/limite/estoque?
+* O cache é a fonte da leitura? (race entre cache e DB — conecta a `state-consistency-audit`)
+
+## Attack Patterns
+
+```text
+double-spend (balance)
+    A: READ balance=100 (ok ≥50)   B: READ balance=100 (ok ≥50)
+    A: WRITE balance=50            B: WRITE balance=50
+    → dois saques de 50 sobre saldo 100; saldo real deveria ser 0, ficou 50 (ou -50)
+
+over-limit grant
+    A: READ claims_today=4/5 (ok)  B: READ claims_today=4/5 (ok)
+    A: WRITE 5/5 + reward          B: WRITE 5/5 + reward
+    → 6/5, limite violado
+
+duplicate creation (uniqueness check-then-insert)
+    A: SELECT (slug exists? no)    B: SELECT (slug exists? no)
+    A: INSERT slug=x               B: INSERT slug=x
+    → dois criados; defesa = unique constraint (se houver)
+
+counter inflation
+    A: READ count=10               B: READ count=10
+    A: WRITE count=11              B: WRITE count=11
+    → deveria ser 12, ficou 11 (increment perdido)
+    defesa = UPDATE count = count + 1 (atômico)
+
+reward double-grant (concurrent same action)
+    A: react + XP                  B: react (same target) + XP
+    → se "already reacted?" check é read-then-write, ambos concedem
+
+stock oversell
+    A: READ stock=1 (ok)           B: READ stock=1 (ok)
+    A: WRITE stock=0 + order       B: WRITE stock=0 + order
+    → dois pedidos, 1 item
+
+cache-then-db race
+    A: read cache (miss) → read DB=100 → write cache=100
+    B: write DB=50 (invalida cache?)
+    → cache serviu 100 após DB virar 50 (state-consistency overlap)
+```
+
+## Evidence Requirements
+
+* **Nomear o invariant** e a sequência READ → DECISION → WRITE.
+* **Mostrar a janela** — onde está o READ, onde o WRITE, e por que nada os atomiza.
+* **Mostrar a intercalação** que viola o invariant (os dois requests lendo o mesmo
+  estado).
+* **Verificar a defesa ausente** — sem CAS, sem lock, sem constraint, sem transaction
+  serializable. Ou a defesa existe mas não cobre (ex: transação sem `FOR UPDATE`).
+* **Escalar confiança:**
+  * `CONFIRMED` — reproduziu com requests simultâneos e observou a violação (saldo
+    negativo, 6/5, duplicata).
+  * `HIGH CONFIDENCE` — código mostra read-then-write sem atomicidade em estado
+    compartilhado, invariant claro; sem reprodução manual.
+  * `POSSIBLE` — padrão presente, estado compartilhado plausível, não confirmado.
+  * `SPECULATIVE` — "pode ter race" sem mapear a sequência.
+* Races sobre valor transferível (saldo/estoque/reward) = mínimo `HIGH CONFIDENCE` se o
+  padrão for claro.
+
+## False Positives
+
+* **CAS / conditional update fecha a janela** — `UPDATE … WHERE balance = :lido` faz B
+  falhar se A mudou. Confirmar o `WHERE` guarda a condição antes de reportar.
+* **Unique constraint** — mesmo sem lock de aplicação, o banco rejeita a duplicata.
+  "Duplicate creation" é defendido se a constraint existe.
+* **SELECT FOR UPDATE / serializable** — a transação isola; a janela não existe.
+  Confirmar o nível de isolamento real.
+* **Incremento atômico** — `UPDATE count = count + 1` é atômico no DB; "counter
+  inflation" não aplica. Aplica só se o app lê e reescreve o valor calculado.
+* **Estado não é compartilhado** — se cada request opera sobre sua própria linha
+  (isolada por chave), não há race no mesmo estado.
+* **Cache com invalidação síncrona** — se a escrita invalida o cache antes de servir a
+  próxima leitura, a race cache-DB é defendida. Relacionado a `state-consistency-audit`.
+* **Limite é soft** — se o limite é orientativo, "6/5" pode ser tolerado por design.
+  Marcar `POSSIBLE` e levantar como decisão de produto.
+
+## Output Format
+
+Para cada read-then-write sem atomicidade que viola um invariant sob concorrência, um
+finding via `templates/audit-report.md`. Em **Reproduction**, dê a intercalação dos
+dois requests (com timestamps/ordem) e o estado final observado. Em **Affected flow**,
+nomeie o invariant (saldo ≥ 0, limite ≤ N, único). Em **Root cause**, diga o que falta
+(transaction + FOR UPDATE, CAS, unique constraint, incremento atômico). Em
+**Recommendation**, indique a defesa apropriada (preferir constraint/CAS no DB quando
+possível — o banco é a última linha).
+
+Apresente cada sequência como diagrama READ/DECISION/WRITE com a janela marcada.
+Double-spend e over-limit primeiro; counter e cache-DB depois.