SniperGold_ML/docs/P3_S10_REPAIR_IMPLEMENTATION_SPEC.md

# 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.*