Stage 3 Kickoff
Prerequisites: Stage 2 sealed (stage2-certified-2026-01-28), Stage 1 gate green
Stage 3 Definition
Stage 3 certifies the deterministic commission engine execution:- Decimal-safe math: All commission calculations use
Decimalwith proper precision handling - Allocation + reconciliation invariants: Engine outputs satisfy business rules (no negative commissions, proper agent splits, etc.)
- Idempotent reruns: Re-running the engine with same inputs produces identical outputs
- Deterministic execution: Same inputs → same outputs (no non-deterministic behavior)
Inputs
Stage 3 engine consumes:- Stage 1 normalized rows: Business/agent/policy data from ingestion pipeline
- Stage 2 config readiness state: PEPM assignments, business policies, agent assignments
Outputs
Stage 3 engine produces:- Canonical allocation tables/views: Engine outputs ready for dashboard consumption
- Commission snapshots: Per-agent, per-business, per-period commission records
- Reconciliation reports: Validation that allocations sum correctly
Explicit Exclusions
Stage 3 does NOT include:- Onboarding changes: Stage 1/2 ingestion and configuration logic
- Dashboard/UI work: Frontend rendering, visualization (Stage 4)
- AI decisions in math: No AI/ML in commission calculation logic
- Business rule changes: Only implements existing rules deterministically
Entry Criteria
Before starting Stage 3 work:- ✅ Stage 2 sealed tag exists:
stage2-certified-2026-01-28 - ✅ Stage 1 gate green: All Stage 1 tests passing (23 passed)
- ✅ Stage 2 tests green: All Stage 2 tests passing (21 passed)
Stage 3 Test Strategy
- Unit tests for decimal math operations
- Integration tests for allocation invariants
- Idempotency tests for engine reruns
- Determinism tests (same inputs → same outputs)
Next Steps
- Identify Stage 3 test files (likely
test_engine_*.py,test_allocation_*.py) - Run baseline test suite to establish current state
- Fix decimal precision issues
- Add allocation invariant checks
- Verify idempotency and determinism