GTI_GERENCIADOR_FISCAL/docs/PROJECT_STATE.md

# Project State — GTI Fiscal (2026-09-28, fim da Missão 7)

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.

> [!IMPORTANT]
> **SEPARAÇÃO RIGOROSA TESTE vs PRODUÇÃO (`DADO_DE_TESTE=true`)**:
> Todas as bases Firebird analisadas até hoje (Agent 2 e os 5 bancos de laboratório CONSTRUCAO, MMMODAS, RINCAO, UNIAO, TESTESOFICIAIS) são **dados de teste e homologação**. Nenhum cliente real passou pelo motor ainda. Qualquer métrica ou constatação levantada sobre essas bases representa validação técnica de mecanismo de software, **não achado ou diagnóstico contábil sobre nenhum cliente**.

## Versões

- **Hub (produção)**: 1.3.15 (preparado para deploy), deploy anterior 1.3.14 confirmado (`DEPLOY_OK`, health 200).
- **Agent (última release Windows PUBLICADA)**: 1.3.8 — nenhum installer novo foi publicado nas
  Missões 2–7 (o Agent permaneceu 100% inalterado).
- **Agent 2** (installation `bb50884a-5e78-4f26-8cac-804932dae8de`): **1.3.8, informado pelo
  operador** — ambiente de teste/homologação.
- Hub e Agent são versionados **independentemente** — ver `docs/VERSIONING.md`.

## Migration head

- **main (master)**: `0034_reference_data_registry` (33 migrações). Head única linear.
- **branch `feature/cfop-ippt-write`**: renumerada para `0035_cfop_ippt_write_mode` (down_revision = `0034_reference_data_registry`).
- **Teste de Merge Real (Missão 7 / A.1)**:
  - Testado via `git merge --no-commit --no-ff feature/cfop-ippt-write` e abortado limpo.
  - Head do Alembic única: `0035_cfop_ippt_write_mode (head)` (zero split estrutural no banco).
  - Conflitos de arquivos git mapeados: `agent/tests/test_cfop_ippt_auto_apply.py` e `release/RELEASE_MANIFEST.json`.

## Reference Data Registry e Datasets P2–P4 (Missão 7)

- **Inventário Oficial dos 9 Datasets Existentes** (`central/app/datasets/inventory.py`):
  1. NCM (Siscomex)
  2. TIPI_IPI (Receita Federal)
  3. CEST (CONFAZ)
  4. BA_ST_MVA (SEFAZ-BA)
  5. NFE_MOC_TABLES (Receita Federal / ENCAT)
  6. CFOP (Portal Nacional NF-e)
  7. FCP (Portal Nacional NF-e)
  8. ANP (Portal Nacional NF-e)
  9. NCM_UTRIB (Portal Nacional NF-e)
  *(Esclarecimento A.3: `SPED_PIS_COFINS` e `REFORMA_RTC` não integravam os 9 datasets pré-existentes; pertencem ao pipeline de novos datasets mapeados na Descoberta).*
- **Métricas dos Datasets P2, P3 e P4**:
  - **CFOP**: 619 códigos (IT 2023.002 v2.10, SHA-256 `c95c...ff6f`), status `DRAFT`.
  - **NFE_DOMAINS**: 130 códigos (MOC 7.0 Anexo I, SHA-256 `5eb4...55d`), status `DRAFT`.
  - **TIPI_IPI**: 11.103 NCMs/EX (Decreto nº 11.158/2022 até ADE 001-2026, SHA-256 `d155...2e9a`), status `DRAFT`.
  - **CEST**: 1.223 CESTs (Convênio ICMS 142/18, SHA-256 `d7fb...54d3`), status `DRAFT`.
- **Validação de CBS/IBS e GTIN (A.4 - 2026-09-28)**:
  - CBS 2026: 0,9% (ADCT art. 125, II / LC Reforma Tributária).
  - IBS 2026: 0,1% (ADCT art. 125, I / LC Reforma Tributária).
  - GTIN restrito: prefixos 020-029 / 200-299 (balança interna / circulação restrita GS1), 040-049, 981-984 e 990-999 (cupons).

## Separação Teste vs Produção e Artefatos (Missão 7 / Bloco B)

- **Rótulo `DADO_DE_TESTE=true`**: Aplicado no card "Contexto Fiscal" da UI (`agent_detail.html`), no módulo de decisões (`fiscal_context_ui.py`), no dossiê contábil (`dossie_contador.md`) e em todos os relatórios.
- **Reclassificação dos 8 Produtos Bloqueados**: Definidos formalmente como **artefatos de teste** do banco de homologação do Agent 2 (`docs/NCM_27_BLOCKED_PRODUCTS_V1.md`), nunca achados fiscais sobre clientes reais.
- **Catálogo de Fontes de Evidência**: Formalizado em `docs/EVIDENCE_SOURCES.md`, separando as bases de teste das premissas pendentes de validação com o primeiro cliente real.

## Prontidão para o Primeiro Cliente Real (Missão 7 / Bloco C)

- **Checklist de Onboarding Seguro**: Detalhado em `docs/ONBOARDING_PRIMEIRO_CLIENTE_REAL.md` (requisitos de rede HTTPS outbound exclusiva, leitura em lote de 50-100 itens com `WAIT 5` e throttling de 50-100ms, backoff em busy, rollback instantâneo via parada de serviço/desinstalação).
- **Segurança Agent-Hub**: Tokens de instalação HMAC com expiração/revogação instantânea, rate limit por instalação, anonimização estrita em logs.
- **Modo Recomendado**: Somente leitura e DRY-RUN (sem `AUTO_FILL` ativo) pelas primeiras $N = 3$ execuções ou 7 dias de monitoramento contínuo.
- **Critérios Objetivos de Seleção**: Roteiro de 4 perguntas para decisão humana do operador (pequeno porte < 2.000 itens, Simples Nacional CRT 1 sem IPI, varejo simples com GTIN comercial, concordância do cliente).

## Endurecimento do Hub e Disaster Recovery (Missão 7 / Bloco D)

- **Segurança HTTP**: Middleware implementado em `central/app/main.py` injetando `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, `X-XSS-Protection` e `Referrer-Policy`.
- **Cobertura de Testes**: Suíte `central/tests/test_mission_07_hardening.py` adicionada cobrindo ciclo de vida do Registry (aprovação, rejeição, checklist), classificação de taxas TIPI e headers de segurança.
- **Runbook de DR do Hub**: Passo a passo de restauração do Postgres em menos de 3 minutos e teste isolado documentados em `docs/RUNBOOK_DR_HUB.md`.

## Índice de Documentos-Chave (docs/)

- `EVIDENCE_SOURCES.md` — matriz de fontes de teste vs o que falta validar com cliente real.
- `ONBOARDING_PRIMEIRO_CLIENTE_REAL.md` — checklist de onboarding, segurança e critério dry-run.
- `RUNBOOK_DR_HUB.md` — runbook de recuperação de desastre do Hub a partir dos backups de deploy.
- `REFERENCE_DATASET_MANIFEST_V1.md` — manifesto de datasets oficiais baixados (P1 a P4 com hashes e URLs).
- `DESCOBERTA_P5_P6_MISSAO_6.md` — levantamento completo de PIS/COFINS SPED e ICMS-ST para o Hub.
- `dossie_contador.md` — dossiê fiscal com aviso DADO_DE_TESTE=true.
- `NCM_27_BLOCKED_PRODUCTS_V1.md` — artefatos de teste com bloqueio de NCM.