docs: versioning contract + known ANP gap (F1 audit I3/M1)

2026-07-22 15:56:25 -03:00
1 changed files with 18 additions and 0 deletions
@@ -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.