9.9 KiB
9.9 KiB
P3-S.10 REPAIR IMPLEMENTATION SPECIFICATION — SNIPERGOLD_ML
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
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
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)
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
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
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
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)
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)
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)
- 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)
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
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.