docs: record pre-zai closure design
This commit is contained in:
OpenCode
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user