# 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.