diff --git a/docs/superpowers/specs/2026-09-22-autonomous-fiscal-completion-v1-design.md b/docs/superpowers/specs/2026-09-22-autonomous-fiscal-completion-v1-design.md new file mode 100644 index 0000000..8c20041 --- /dev/null +++ b/docs/superpowers/specs/2026-09-22-autonomous-fiscal-completion-v1-design.md @@ -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.