docs: PROJECT_STATE.md - session closeout snapshot (Missões 1-5)

Factual, no client data: Hub 1.3.14 (deployed), Agent published 1.3.8,
Agent 2 1.3.8 (operator-reported, heartbeat not confirmed this session).
Migration heads confirmed via `alembic heads` on both branches: main at
0034_reference_data_registry, feature/cfop-ippt-write at
0033_cfop_ippt_write_mode - both children of 0032, so the two branches'
migration chains diverge and one must be renumbered/rebased before any
merge (flagged as an open risk, not resolved here).

Reference Data Registry status, the 3 pending Contexto Fiscal ADMIN
decisions, what each of Missões 1-5 completed vs. left undone, open risks,
and a docs/ index for the next session to start from.

CLAUDE.md now points to docs/PROJECT_STATE.md as the required first read
before any new fiscal mission.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CLAUDE.md

@@ -1,5 +1,10 @@
 # GTI Discovery
 
+**Primeira leitura obrigatória, antes de qualquer missão fiscal nova**: `docs/PROJECT_STATE.md`
+(versões Hub/Agent, migration head de cada branch, status do Reference Data Registry, decisões
+ADMIN pendentes, o que já foi feito e o que falta, riscos abertos). Mantê-lo atualizado ao final
+de cada missão que mude esse estado.
+
 This project is strictly read-only. Discovery code must use a database-level
 read-only account or transaction/driver mode; lexical SQL validation is only
 defense-in-depth. Discovery code must not perform DML or DDL,

docs/PROJECT_STATE.md

@@ -0,0 +1,99 @@
+# Project State — GTI Fiscal (2026-09-28, fim da Missão 5)
+
+Leitura obrigatória antes de qualquer nova missão fiscal (CLAUDE.md aponta para cá). Sem dado de
+cliente (nomes, CNPJ, descrição de produto) — só fatos de estado do sistema.
+
+## Versões
+
+- **Hub (produção)**: 1.3.14, deploy confirmado (`DEPLOY_OK`, health 200,
+  `https://gtifiscal.gtigrupo.com.br/version`).
+- **Agent (última release Windows PUBLICADA)**: 1.3.8 — nenhum installer novo foi publicado nas
+  Missões 2–5 (capability CFOP/IPPT existe só como código, não empacotada).
+- **Agent 2** (installation `bb50884a-5e78-4f26-8cac-804932dae8de`): **1.3.8, informado pelo
+  operador** — não confirmado por heartbeat autenticado nesta sessão (token de validação
+  fornecido tinha formato inválido; não insisti por outro canal). **Pendente**: operador confirmar
+  por print do painel.
+- Hub e Agent são versionados **independentemente** — ver `docs/VERSIONING.md`.
+
+## Migration head
+
+- **main (master)**: `0034_reference_data_registry` (33 migrações). Aplicada em produção.
+- **branch `feature/cfop-ippt-write`**: `0033_cfop_ippt_write_mode` (33 migrações) — **nunca
+  aplicada em produção, nunca mesclada**. `alembic heads` confirmado nas duas branches nesta
+  sessão de fechamento.
+- **Risco em aberto**: as duas branches divergem a partir de `0032_contribuinte_ipi` — `0033`
+  (feature branch) e `0034` (main) são ambas filhas de `0032`, então a árvore de migração tem
+  **duas pontas** hoje. Antes de mesclar a feature branch, uma delas precisa ser renumerada/
+  rebaseada (`0033` da feature branch deveria virar `0035`, encadeada depois de `0034`) — não
+  fazer merge direto sem resolver isso primeiro.
+
+## Reference Data Registry (Missão 5, Fase 1)
+
+- Modelo novo e aditivo em `datasets` (licença, vigência, hash, erros de parse, aprovação ADMIN).
+  Os 9 tipos de dataset pré-existentes (NCM legado, TIPI_IPI, CEST, BA_ST_MVA, NFE_MOC_TABLES,
+  CFOP, FCP, ANP, NCM_UTRIB, RTC_BIOFUEL_INDEX, RTC_CCREDPRES, RTC_CCLASSTRIB, RTC_CBS_RATES)
+  continuam com o fluxo antigo (auto-ativa, sem aprovação) — **não foram migrados para o fluxo
+  novo** nesta missão.
+- **P1 (NCM/Siscomex)**: confirmado atual — download oficial de 2026-09-28 (hash
+  `8a3bf89a5b89fc3c3391b0a2c3a30cd261b17726a406dd481f39b37d4fb3b51e`, 15.156 linhas) é **idêntico**
+  ao dataset NCM já ativo. Nenhum DRAFT pendente de aprovação (reconhecido como inalterado).
+  Manifesto: `docs/REFERENCE_DATASET_MANIFEST_V1.md`.
+- **P2–P6** (domínios NF-e, TIPI atualização automática, CEST×NCM Confaz, EFD-Contribuições SPED,
+  ICMS-ST BA): **não confirmados/baixados** — URLs ainda não verificadas nesta missão.
+- Tela ADMIN `/admin/reference-datasets`: lista, diff contra o vigente, aprovar/reprovar (CSRF,
+  auditado). Nenhum DRAFT pendente de decisão no momento.
+
+## Decisões ADMIN pendentes (Agent 2, card "Contexto Fiscal")
+
+1. `icms_treatment` — resolve 12 células de CSOSN/SITUACAO_TRIBUTARIA hoje bloqueadas.
+2. `pis_cofins_profile` — `NOT_APPLICABLE`, `OPERATION_TIME` ou perfil JSON (~3.152 células).
+3. `entry_scope` — `INTRA`/`INTER`/`MIXED_OR_DYNAMIC` para CFOP_ENTRADA.
+
+Nenhuma foi clicada. Nenhuma escrita fiscal real ocorreu em nenhuma missão.
+
+## O que foi feito (Missões 1–5) e o que falta
+
+- **M1/M2** (fechamento de lacunas fiscais): dry-run completo do universo, motor
+  PIS/COFINS/CFOP_ENTRADA com gate por decisão ADMIN auditada, dossiê para o contador (anonimizado
+  em `central/static/docs/`), UI Contexto Fiscal.
+- **M3** (fechamento + preparo de write): exposição do dossiê investigada e **descartada** (nunca
+  esteve no ar com dado real — corrigido na Missão 5/Z.3 quanto ao rótulo de certeza da fonte
+  PIS/COFINS). Núcleo do capability CFOP/IPPT criado.
+- **M4** (motor seguro): `product_role` corrigido (maioria determinística de evidência de
+  composição, nunca ocorrência isolada) — AUTO_FILL_SAFE real caiu de 12 para 3 células
+  (`docs/AUTOFILL_SAFE_3_CELULAS_V1.md`). Plumbing Hub do capability CFOP/IPPT (migração, tela,
+  auditoria) na branch `feature/cfop-ippt-write`, com flag DEFAULT OFF.
+- **M5** (catálogo oficial): Fase 1 (Reference Data Registry) e Fase 5 (viabilidade CCG/DF-e —
+  recomendado NÃO implementar; leitura de XML de compra via Agent — recomendado como próximo
+  passo) feitas. **Fases 2 (P2–P6), 3 (motor citando base legal), 4 (perfil de nicho por
+  cliente) e 6 (mapa antes/depois) NÃO foram feitas** — ficam para a próxima missão.
+- **Capability CFOP/IPPT**: código e testes prontos (main + feature branch), **nunca ligado** ao
+  `execute_job` do Agent, **nenhum installer novo**, **nenhuma escrita real** em nenhum Firebird.
+
+## Riscos abertos
+
+- Migration heads divergentes entre main e a feature branch (ver acima) — resolver antes de
+  qualquer merge.
+- Validação de heartbeat do Agent 2 (versão 1.3.8) pendente de confirmação real (só print do
+  operador até agora).
+- 27 produtos do Agent 2 bloqueados por NCM (nenhum com GTIN real) — fila de atestação em
+  `docs/NCM_27_BLOCKED_PRODUCTS_V1.md`, nenhuma promoção automática.
+- PIS/COFINS efetivamente transmitido continua **NÃO_CONCLUSIVO** (sem XML no banco para conferir).
+- P2–P6 do catálogo oficial ainda não confirmados/baixados.
+
+## Índice de documentos-chave (docs/)
+
+- `AI_PROJECT_STATE.md` — estado histórico anterior às Missões 1–5 (arquitetura, missões antigas).
+- `VERSIONING.md` — versionamento independente Hub/Agent.
+- `fiscal_completeness_matrix.md` — matriz de completude dos 18 campos fiscais.
+- `dossie_contador.md` (+ cópia anonimizada em `central/static/docs/`) — perguntas para o contador.
+- `AGENT2_UPGRADE_RUNBOOK_V1.md` — roteiro de upgrade manual do Agent (sem self-update).
+- `CFOP_IPPT_WRITE_CAPABILITY_V1.md` — capability de escrita CFOP/IPPT (núcleo + roteiro de
+  aceite; não ligado).
+- `AUTOFILL_SAFE_3_CELULAS_V1.md` — as 3 células reais AUTO_FILL_SAFE do Agent 2.
+- `NCM_27_BLOCKED_PRODUCTS_V1.md` — os 27 produtos bloqueados por NCM, fila de atestação.
+- `PISCOFINS_TRANSMITTED_SOURCE_V1.md` — busca por XML/BLOB de PIS/COFINS (NÃO_CONCLUSIVO).
+- `REFERENCE_DATASET_MANIFEST_V1.md` — manifesto de datasets oficiais baixados (URL/hash/data).
+- `VIABILIDADE_CCG_DFE_V1.md` — estudos de viabilidade (CCG/SEFAZ, XML de compra, Open Food Facts).
+- `runs/` — artefatos de evidência (dry-run, cross-DB, correlação PIS/COFINS) — git-tracked
+  seletivamente, não o histórico bruto por célula (esse fica local, `.gitignore`).