From a6492f936eccf90b07983b726e1800664cdac02a Mon Sep 17 00:00:00 2001 From: OpenCode Date: Mon, 21 Sep 2026 16:50:45 -0300 Subject: [PATCH] docs: record pre-zai closure design --- .../2026-09-21-pre-zai-blocker-closure.md | 68 +++++++++++++++++++ ...26-09-21-pre-zai-blocker-closure-design.md | 37 ++++++++++ 2 files changed, 105 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-21-pre-zai-blocker-closure.md create mode 100644 docs/superpowers/specs/2026-09-21-pre-zai-blocker-closure-design.md diff --git a/docs/superpowers/plans/2026-09-21-pre-zai-blocker-closure.md b/docs/superpowers/plans/2026-09-21-pre-zai-blocker-closure.md new file mode 100644 index 0000000..a29594c --- /dev/null +++ b/docs/superpowers/plans/2026-09-21-pre-zai-blocker-closure.md @@ -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. diff --git a/docs/superpowers/specs/2026-09-21-pre-zai-blocker-closure-design.md b/docs/superpowers/specs/2026-09-21-pre-zai-blocker-closure-design.md new file mode 100644 index 0000000..47d1833 --- /dev/null +++ b/docs/superpowers/specs/2026-09-21-pre-zai-blocker-closure-design.md @@ -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.