GTI_GERENCIADOR_FISCAL/docs/superpowers/plans/2026-09-17-fiscal-data-foundation-v1.md

Fiscal Data Foundation V1 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add isolated, versioned official fiscal-data ingestion without product tax determination.

Architecture: A shared dataset lifecycle stores auditable metadata and retains active versions. Each domain parser/importer validates its own official payload and fails independently.

Tech Stack: Python, SQLAlchemy, Alembic, FastAPI, pytest.

Global Constraints

• Use only official primary sources.
• Preserve existing NCM and CEST imports.
• Never write to Firebird or classify products.
• Failed imports cannot supersede active datasets.

---

Task 1: Dataset Version Metadata

Files:

• Modify: central/app/models.py

• Create: central/alembic/versions/0003_dataset_foundation_metadata.py

• Test: central/tests/test_dataset_lifecycle.py

• Write a failing test asserting parser_version, effective dates, raw reference, and failure reason persist.

• Run python -m pytest central/tests/test_dataset_lifecycle.py -q and verify failure.

• Add the model fields and migration.

• Re-run the focused test and verify pass.

Task 2: Isolated Lifecycle Service

Files:

• Modify: central/app/datasets/service.py

• Test: central/tests/test_dataset_lifecycle.py

• Write failing tests for a failed replacement retaining its prior active dataset and for independent domains.

• Run focused tests and verify failure.

• Implement pending, failed, and active promotion methods scoped by domain.

• Re-run focused tests and verify pass.

Task 3: Official Domain Importers

Files:

• Create: central/app/datasets/foundation.py

• Create: central/scripts/import_foundation.py

• Test: central/tests/test_foundation_parsers.py

• Write failing parser tests for official structured payload validation and unsupported structures.

• Run focused tests and verify failure.

• Implement versioned fail-closed adapters for BA_ST_MVA, CFOP, CST_CSOSN, PIS_COFINS, TIPI_IPI, CCLASSTRIB_IBSCBS, FCP, and MONOFASICO_ICMS.

• Re-run focused tests and verify pass.

Task 4: Active Dataset Smoke Matrix

Files:

• Modify: central/app/api.py

• Test: central/tests/test_dataset_status.py

• Write failing test for active-only dataset status with lifecycle metadata.

• Run focused test and verify failure.

• Add the active dataset status/smoke response.

• Run python -m pytest tests central/tests agent/tests -q and verify pass.