From bf829da574913548793624a09e7d110fd49f274f Mon Sep 17 00:00:00 2001
From: jonatanritter <jonatan.ritter@gmail.com>
Date: Wed, 22 Jul 2026 15:56:25 -0300
Subject: [PATCH] docs: versioning contract + known ANP gap (F1 audit I3/M1)

---
 README.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 1e5e26d..c38c574 100644
--- a/README.md
+++ b/README.md
@@ -43,3 +43,21 @@ uv run pytest
 ```
 
 100% local — sem Postgres, sem k8s.
+
+## Versionamento (contrato)
+
+- **SemVer estrito.** Os nomes públicos (`resolve_fiscal`, `build_nfe`,
+  `montar_chave_acesso`, `TaxDomain`, `DOMAIN_FIELDS`, `MATCHER_WEIGHTS`, `PRESETS`,
+  `TPAG_CODES`, `DadosEmissao` e sub-dataclasses, `FiscalOperation/FiscalItem/
+  FiscalResult/TributoLinha`, exceções) são O CONTRATO — mudança incompatível = major.
+- **Consumidores pinam por TAG, nunca por branch**: `uv add "sowai-fiscal @
+  git+https://git.sowai.com.br/jonatan/sowai-fiscal.git@vX.Y.Z"` (o lock pina o hash).
+- Goldens mudam SÓ quando uma NT muda o leiaute de propósito (ver seção acima) — e isso
+  é sempre pelo menos um minor, com nota de release explicando a NT.
+
+## Gap conhecido (registrado na F1, 2026-07-17)
+
+- **Grupo ANP (`gProdANP`) não é emitido** — `ItemData`/builder não têm o campo. NF-e de
+  óleo lubrificante SEM esse grupo é REJEITADA pela SEFAZ. Fechar na cobertura R1 (junto
+  do cClassTrib) ANTES de homologar o caso Óleos na F4. O golden `caso_st_intra` cobre
+  ICMS-ST/CSOSN 500, NÃO cobre ANP.