docs: design autonomous fiscal completion v1

2026-09-22 12:37:38 -03:00
parent df3c44838a
commit b3e8dd1b24
1 changed files with 71 additions and 0 deletions
@@ -0,0 +1,71 @@
+# 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.