# P3-S.10 REPAIR IMPLEMENTATION SPECIFICATION — SNIPERGOLD_ML ```text Date : 2026-08-22 Session : P3-S.10 — Owner Adjudication & Canonical Setup Contract Freeze Status : IMPLEMENTATION SPECIFICATION ONLY. NOT executed. Purpose : Translate the frozen canonical contract (docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md) and the adjudicated OD-1..OD-5 (docs/P3_S10_OWNER_ADJUDICATION.md) into concrete repair families, tests, and an execution order for the FUTURE implementation sessions (P3-S.11+). Inputs : docs/P3_S9_CONSOLIDATED_REPAIR_PLAN.md (master classification), docs/P3_S9_ROOT_CAUSE_MATRIX.md, docs/P3_S9_ARCHITECTURE_REVIEW.md, SMC_*_SPEC_v1.md (P3-S.2..S.8, immutable). Rule : SPEC -> TEST -> IMPLEMENTATION -> REGRESSION -> PARITY. No direct hot-fix. No performance-based selection. Historical evidence and prior checkpoints preserved. Human verification : CANCELLED. ``` --- ## 1. REPAIR FAMILIES (frozen scope) ### F1 — EVENT CONTRACT ```text Objective : Introduce the EVENT contract {timestamp, direction, valid_until, superseded, source} for Liquidity Sweep and CHoCH/MSS; make every consumer apply the validity window. Fixes : BUG-P3S2-001 (stale sweep in f9/f18), BUG-P3S3-001 (stale CHoCH, 34.7%/58.0%), D-12 (no freshness window in Engine 2). Root causes: A (event/state confusion), C (duplicate emission), D (stale consumption), J (missing lifecycle) — sweep/choch columns. Files likely affected : ml EA AlgoForge_Backtest_Baseline.mq5 (f9/f18 legs), AF_Engine2_Agents.mqh (sweep/choch consumption), shared event contract include (new), Engine-2 defs (W_sweep/W_choch). Tests required : extend P3-S.2/P3-S.3 synthetic suites — expiry-at-40 (f9/f18 assert 0 after window), supersession (newer onset replaces), ordering (chochBar >= swpBar), no-duplicate-onset per reference. Dependencies : OD-3 (windows), OD-4 (no arithmetic for setup-layer). Risk : LOW-MEDIUM — touching f9/f18 changes ML-path behavior; parity re-run required (SB-06 class). ``` ### F2 — ZONE CONTRACT ```text Objective : Introduce the ZONE contract {timestamp, direction, upper_bound, lower_bound, mitigation_state, invalidated}; make Engine-2 C/E consumers mitigation-aware and timing-unified. Fixes : BUG-P3S4-001 (FVG consumed without mitigation), BUG-P3S4-002 (FVG timing C3 vs lag-1), BUG-P3S5-001 (OB without mitigation/age). Resolves P3-S.4 A-2/A-6, P3-S.5 A-3/A-5 (consumer scope), P3-S.4 A-5 (timestamp convention). Root causes: B (zone/mitigation consumer error), D (stale zones). Files likely affected : AF_Engine2_Agents.mqh (C/E zone queries), AF_FindFVG/AF_FindOrderBlock consumers, display collector alignment (AF_CollectFVG close-variant vs wick canonical). Tests required : extend P3-S.4/P3-S.5 suites — mitigation cases (close-through OB / wick full-fill FVG), partial-fill NOT mitigation, zone selection scope (newest-unmitigated), formation timestamp convention. Dependencies : OD-5 (OB semantics; FVG per P3-S.4 S-9). Risk : MEDIUM — changes zone availability in Engine 2. ``` ### F3 — SETUP LAYER (core of the canonical contract) ```text Objective : Materialize the Candidate Setup ENTITY: identity (§K), lifecycle state machine (§L), H4/M30 context gates (OD-1), per-stage validity windows (OD-3), conflict policy (OD-4); re-scope the aggregator to a scoring layer over valid setups (D-9); expose the setup predicate explicitly (D-11). Fixes : D-8 (two definitions -> canonical chain), D-9 (score can produce signal without setup), D-10 (no identity), D-11 (E-vote saturation), D-1 (aggregator re-scope). Root causes: F (flat score as setup), I (missing identity), J (missing lifecycle) — candidate-setup columns. Files likely affected : new setup entity (struct/state machine), aggregator (signal emission bound to setups), M15 chain consumer, Engine-2 defs (W_setup, W_m3), f7/f8/f9 consumers via contracts. Tests required : re-express P3-S.8 CS-T01..T25 against the entity semantics; gate-fail matrix (OD-4); one-entry rule; identity dedup (one setup not recreated per bar); stage expiry before CANDIDATE_SETUP discards. Dependencies : F1, F2 (events/zones must be contract-correct first). Risk : HIGH (semantic change to the setup/signal path) — the reason this session froze the contract before code. ``` ### F4 — MTF / TRAINING ALIGNMENT ```text Objective : Enforce the canonical MTF model (OD-2) and the gate-fail conflict policy (OD-4); reconcile training semantics or document the divergence; enforce slot->TF identity (D-3); align training/runtime pivot semantics (BUG-P3S3-002) and window semantics (BUG-P3S2-003). Fixes : D-2, D-3, D-5, D-6, BUG-P3S2-003, BUG-P3S3-002. Root causes: E (multiple definitions), G (role drift), H (training/runtime drift) — MTF/CHoCH columns. Files likely affected : FEATURE_CONTRACT.md (alignment OR explicit divergence record — NOT modified this session), train_model.py build_structure (strict vs equal pivots), Engine-1 slot registration (assert TF at consume time), MTF conflict module. Tests required : MTF-T07/T08/T16 (as-of) re-run; new conflict-policy tests; training-vs-runtime pivot parity tests. Dependencies : F3 (setup layer consumes the policy), OD-2/OD-4. Risk : MEDIUM — training alignment is data-path sensitive; parity must be re-verified. ``` ### F5 — DISPLAY / EXPLAINABILITY ```text Objective : Render the setup entity (id, stages, lifecycle) instead of the bare vote signal in the "TRADE SETUP" panel; draw H4/M30 structures; align display with decision semantics. Fixes : D-4 (V-1..V-4), P3-S.8 D-9 display side. Root causes: F (flat score displayed as setup). Files likely affected : AF_Engine3_Render.mqh, AF_Engine2_Display.mqh. Tests required : panel renders setup id/stages; display of H4/M30 context; no stale re-render within a bar. Dependencies : F3 (setup entity must exist). Risk : LOW-MEDIUM. ``` ### F6 — DOCUMENTATION / DEFINITIONS / CLEANUP ```text Objective : Record the adjudicated definitions: canonical vs legacy OB (OD-5), 1.5 vs 1.6 constant role split (OD-5); deprecate legacy D1/H4/H1 to reference (D-6); clean terminology (BUG-P3S2-004/-005, BUG-P3S3-003, BUG-P3S4-003/-004, BUG-P3S5-003, D-7, D-14). Fixes : BUG-P3S5-002, BUG-P3S6-001 (DOCUMENT ONLY — decided), misc P3 items. Files likely affected : docs only (spec addenda/notes, terminology audit). Tests required : none (documentation family); verify no code change. Dependencies : none. Risk : LOW. ``` --- ## 2. IMPLEMENTATION ORDER (frozen) ```text Phase I : F1 EVENT Contract Repair (P1 correctness) Phase II : F2 Zone Contract Repair (P1 correctness) Phase III : F3 Candidate Setup Layer (P1/P2 architecture) Phase IV : F4 MTF / Training Alignment (P2 architecture) Phase V : F5 Display / Explainability (P2) Phase VI : Regression + parity + setup dataset rebuild Gate rule : a phase starts only when the previous phase's regression is green. F6 documentation may be interleaved at any phase but must not be the vehicle for code changes. ``` --- ## 3. TEST-FIRST REQUIREMENT (mandatory for every phase) ```text SPEC -> TEST -> IMPLEMENTATION -> REGRESSION -> PARITY 1. SPEC : the repair behavior is defined by the frozen contract section. 2. TEST : synthetic tests are written/extended FIRST (P3-S.2/S.3/S.4/S.5/ S.8 suites) asserting the contract behavior (expiry, mitigation, gates, identity, lifecycle, one-entry, conflict matrix). 3. IMPL : the minimal code change that satisfies the tests. 4. REGRESSION : Engine 1/2/3 unit tests re-run; non-target behavior preserved. 5. PARITY : ML-path parity re-verified (SB-06 class) when f7-f18 or training semantics are touched. Preservation rules: - historical evidence and prior checkpoints are IMMUTABLE; - no direct hot-fix (every repair is a spec'd, tested phase); - no performance-based selection of any constant; - no human verification restart. ``` --- ## 4. NON-GOALS (unchanged from P3-S.9, re-confirmed) ```text - No AUC/PF/profit-based selection of any repair or constant. - No human annotation restart. - No ML retraining / parameter optimization. - No restoring legacy v4.x code as-is (semantics extracted only). - No "best of both" grab-bag (brief §21). - No modification of FEATURE_CONTRACT.md, .mq5/.mqh/.py production files by THIS session. ``` --- ## 5. OPEN NUMERIC PARAMETERS (must be set by contract tests, NOT performance) ```text W_setup : Candidate Setup post-formation validity (M15 bars) — F3. W_m3 : M3 confirmation lookback (M3 bars) — F3. W_zone_age : optional zone-age cap (default none) — F2. FVG min-gap / OB min-size / zone scope : F2/F6 (P3-S.4 A-1, P3-S.5 A-1/A-3/A-5). ``` --- ## 6. ARTIFACTS REFERENCED ```text Canonical contract : docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md Adjudication : docs/P3_S10_OWNER_ADJUDICATION.md Handover : docs/SESSION_HANDOVER_2026-08-22_P3_S10_OWNER_ADJUDICATION.md P3-S.9 (immutable) : docs/P3_S9_ARCHITECTURE_REVIEW.md, docs/P3_S9_ROOT_CAUSE_MATRIX.md, docs/P3_S9_CONSOLIDATED_REPAIR_PLAN.md P3-S.2..S.8 (immutable) : docs/SMC_*_SPEC_v1.md ``` *End of P3-S.10 repair implementation specification. No production file modified by this session.*