3.2 KiB
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.