# Autonomous Fiscal Completion V1 Design

## Goal

Reduce deterministic fiscal gaps across the five explicitly allowlisted local
Firebird databases without calling an AI provider, answering human decisions,
or treating a populated ERP field as mandatory by default.

## Safety Boundary

All discovery and evidence extraction is read-only. Deterministic writes are
permitted only through the existing guarded executor, only for exact allowlisted
paths and proven write targets. A write requires provenance, `CHANGE_REQUIRED`,
`write_eligible=true`, path/company/schema/type guards, compare-before-write,
exact rowcount, post-write equality, and a no-unplanned-columns audit. If any
guard fails, the result remains pending. AI flags remain
`AI_WRITE_ALLOWED=false` and `FIREBIRD_AI_WRITES=0`.

## Workstreams

### 1. Requiredness and completeness

Create a versioned requiredness matrix for the 23 existing fiscal contracts.
Rules are keyed by company regime/UF and product/operation facts, and produce
one of `REQUIRED`, `CONDITIONAL`, `OPTIONAL_REFERENCE`, `NOT_APPLICABLE`, or
`ERP_NOT_USED`. Implement `FiscalCompletenessEvaluator` to return a status per
field and aggregate product metrics without requiring empty `NOT_APPLICABLE`
fields to be filled.

### 2. Inbound evidence

Perform schema discovery across all five databases without assuming table
names. Identify headers, items, suppliers, keys, XML/BLOB/text evidence, and
relationships. Produce a sanitized evidence map and read-only analysis counts.
Supplier observations remain observational until conservative deterministic
rules prove they are reusable.

### 3. Deterministic resolution

Build provenance-aware evidence aggregation for origin, product role, ST/CEST,
and dynamic CFOP entry scope. Use supplier/document agreement metrics rather
than majority alone. Keep conflicts, missing evidence, company/group/product
questions, and `ST_WITHHELD` uncertainty pending. Reuse only compatible global
KB facts; tenant-specific policy fields are never copied cross-tenant.

Run dry-run and completeness metrics for all five databases. Execute only
eligible deterministic writes, then reprocess and require zero second-pass
writes. Preserve all current NCM conflicts.

### 4. Providers and AI controls

Document external product-data provider candidates without purchasing or
querying them. Add an abstract provider contract and permanent-cache schema for
GTIN/provider/version/hash/normalized data. Add persistent central AI usage
ledger and atomic pre-call limits for run, daily, monthly, requests, and new
products. Prove idempotent cache behavior with offline tests; no provider or AI
network call is made.

## Artifacts

The implementation must produce the requiredness matrix, inbound evidence map,
provider evaluation, consolidated JSON/Markdown autonomy reports, and updated
`AI_PROJECT_STATE.md`. Artifacts must report measured values and explicit
unknowns rather than inferred fiscal answers.

## Verification

Each workstream adds focused tests. The final gate runs the complete `tests` and
`central/tests` suites, `git diff --check`, read-only invariant checks, dry-run
and second-pass metrics, and confirms no external AI calls, no non-allowlisted
database access, and no semantic Firebird writes.