docs: record pre-zai closure design

2026-09-21 16:50:45 -03:00
parent b10131953c
commit a6492f936e
2 changed files with 105 additions and 0 deletions
@@ -0,0 +1,37 @@
+# PRE-ZAI Blocker Closure Design
+
+## Goal
+
+Close every locally verifiable blocker before the real Z.ai GOLD benchmark,
+without changing the 90 valid NCM conflicts, inferring human facts, calling
+external AI, deploying, or enabling Firebird AI writes.
+
+## Design
+
+The historical conflict audit joins every available seed-payload observation by
+GTIN and fingerprint, preserves descriptions/tenant/product/NCM evidence, and
+classifies each historical row as `RESOLVED_EQUIVALENT_PRODUCT`, `FALSE_MATCH`,
+`VALID_NCM_CONFLICT`, `STALE_OBSERVATION`, or `INSUFFICIENT_EVIDENCE`. Missing
+evidence remains unresolved and never selects an NCM by majority.
+
+The operator session exposes only COMPANY questions first. It is guided,
+cancelable, review-first, and produces a context import artifact only after
+explicit confirmation. IPI options include real local impact counts where the
+source artifacts expose them; rollback remains a plan until the operator
+chooses it. `MIXED_OR_DYNAMIC` produces no universal CFOP.
+
+Final health derives from existing artifacts and the regenerated residual plan.
+The report uses `COMPANY_CONTEXT_COMPLETE=false` until answers are actually
+persisted, and labels GROUP/PRODUCT decisions as human-pending rather than
+pipeline failures. Retrieval V2 remains active unless a complete holdout proves
+V3 improvement.
+
+## Safety and Acceptance
+
+- Current 90 conflicts remain `NCM_CONFLICT` unless objective evidence changes a
+  specific row.
+- Historical rows without evidence are `INSUFFICIENT_EVIDENCE`.
+- All reports state `FIREBIRD_AI_WRITES=0` and `AI_WRITE_ALLOWED=false`.
+- No answer is auto-persisted by the guided session.
+- The final artifact contains no placeholder TODOs and lists only external AI
+  quota/credential plus deliberate human decisions as remaining blockers.