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,68 @@
+# PRE-ZAI Blocker Closure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Audit historical KB conflicts and produce an honest, operator-ready pre-Z.ai state without external AI or semantic Firebird writes.
+
+**Architecture:** Add pure evidence reconstruction over the existing seed payload, a guided COMPANY session wrapper around the existing context validator, and deterministic final-state/report generators. Preserve current retrieval and conflict policy.
+
+**Tech Stack:** Python, JSON/CSV, existing context validation, pytest.
+
+## Global Constraints
+
+- Do not call external AI APIs.
+- Do not deploy.
+- Keep `FIREBIRD_AI_WRITES=0` and `AI_WRITE_ALLOWED=false`.
+- Never resolve NCM by majority voting.
+- Never auto-answer human context questions.
+- Preserve all 90 current NCM conflicts unless objective evidence changes an individual row.
+
+---
+
+### Task 1: Historical Conflict Reconstruction
+
+**Files:**
+- Create: `central/app/ai/historical_conflicts.py`
+- Create: `central/scripts/audit_historical_kb_conflicts.py`
+- Create: `central/tests/test_historical_conflicts.py`
+- Generate: `docs/KB_HISTORICAL_CONFLICT_AUDIT_V1.json`
+
+- [ ] Test each classification and the no-majority rule.
+- [ ] Join payload rows by GTIN/fingerprint and retain all evidence fields.
+- [ ] Classify 73 historical rows; emit `INSUFFICIENT_EVIDENCE` when source evidence is absent.
+- [ ] Assert current 90 conflicts are unchanged in the new artifact.
+
+### Task 2: Guided COMPANY Session and Impact Preparation
+
+**Files:**
+- Create: `scripts/run_company_decision_session.py`
+- Modify: `central/app/ai/questionnaire.py`
+- Create: `central/tests/test_company_decision_session.py`
+- Generate: `docs/COMPANY_DECISION_SESSION_V1.json`
+
+- [ ] Test COMPANY-only first ordering, Portuguese labels, cancellation, and review-only behavior.
+- [ ] Add actual local IPI impact fields from available coverage artifacts; do not invent unavailable counts.
+- [ ] Validate `INTRA`, `INTER`, `MIXED_OR_DYNAMIC`, and both IPI profile options.
+- [ ] Require explicit confirmation before writing the official context artifact.
+
+### Task 3: Final Regeneration and Health State
+
+**Files:**
+- Create: `scripts/generate_pre_zai_state.py`
+- Modify: `scripts/generate_local_health.py`
+- Create: `central/tests/test_pre_zai_state.py`
+- Generate: `docs/PRE_ZAI_FINAL_STATE_V1.json`
+- Update: `docs/LOCAL_PRODUCT_HEALTH_V1.json`
+
+- [ ] Reuse the regenerated residual counts and historical audit counts.
+- [ ] Keep retrieval V2 active and record V3 as not activated without holdout gain.
+- [ ] Emit all requested health fields and explicit human/external blockers.
+- [ ] Assert zero AI writes and no source/pipeline gaps except evidence-unavailable historical rows.
+
+### Task 4: Verification
+
+- [ ] Run `python -m pytest tests -q`.
+- [ ] Run `python -m pytest central/tests -q`.
+- [ ] Run the historical audit, company session preview, regeneration, and health commands.
+- [ ] Run `git diff --check` and a tracked-secret scan.
+- [ ] Document final metrics in `docs/PRE_AI_LOCAL_COMPLETION_V3_REPORT.md` or the new final artifact.