SniperGold_ML/docs/SMC_MTF_TRAINING_ALIGNMENT_SPEC_v1.md

# SMC MTF / TRAINING ALIGNMENT — PROJECT SEMANTIC SPECIFICATION v1

```text
Status   : ALIGNMENT CONTRACT (not a new runtime architecture)
Session  : P3-S.14 — F4 MTF / Training Alignment
Date     : 2026-08-23
Scope    : Determine and, where safely possible, ALIGN the runtime/training MTF
           semantics with the frozen canonical SniperGold model H4/M30/M15/M3,
           WITHOUT changing the Candidate Setup architecture, WITHOUT retraining
           ML, and WITHOUT changing F1/F2 semantics.
Provenance: Forge HEAD 1c0da62407fc905fb96732ec0f6ec5c43d136a8b (P3-S.13)
           docs/SNIPERGOLD_CANONICAL_SETUP_CONTRACT_v1.md (frozen, P3-S.10)
           docs/P3_S7_MTF_ALIGNMENT_CONFORMANCE.md (prior MTF audit)
           docs/SMC_MTF_ALIGNMENT_SPEC_v1.md (P3-S.7 semantic spec)
           docs/FEATURE_CONTRACT.md (P2 source of truth)
           docs/P2_SOURCE_OF_TRUTH_REPORT.md (P2.1-P2.5)
           ml/parity/RUNTIME_TRAINING_PARITY_REPORT.md (SB-06)
           ml/train_model.py, ml/build_features.py, ml/parity/build_features_p2.py
           MQL5/Experts/AlgoForge_Backtest_Baseline.mq5
Human verification : CANCELLED (historical only)
This document is an ALIGNMENT CONTRACT, not a retraining authorization.
No production code, no model file, no Feature Contract changed by F4.
```

---

## A. OBJECTIVE

```text
Answer the single F4 question:

  Does the existing training/ML feature pipeline (D1/H4/H1 + M15, 19 features)
  represent the SAME multi-timeframe information and as-of timing semantics as
  the frozen canonical runtime/setup model H4/M30/M15/M3?

Establish WHERE the two MTF models differ, WHY, and WHAT must eventually change —
as an alignment contract, using source/timeframe/as-of/formula/window/closed-bar/
consumer-meaning evidence (NOT model performance).
```

---

## B. THE TWO MTF MODELS (frozen facts)

```text
RUNTIME CANONICAL (SETUP LAYER)   [frozen, P3-S.10 canonical contract]
  H4   = Narrative / Context Gate   (STATE, direction-compatible HARD gate)
  M30  = Context Gate               (STATE, direction-compatible HARD gate)
  M15  = Entry / Chain Carrier      (setup layer; events/zones/condition live here)
  M3   = Price Action / optional Micro Confirmation (no veto)
  Engine 2 agents run on H4/M30/M15/M3 (AF_E2_TF_S1..S4).
  Candidate Setup (F3) consumes H4/M30 gates + M15 chain + optional M3.

TRAINING / ML FEATURE PATH        [P2 source-of-truth, FEATURE_CONTRACT f0-f18]
  M15  = base decision bar (every feature is an M15-bar computation)
  D1   = f0 htf1_bias (HTF bias)
  H4   = f1 htf2_bias (HTF bias)
  H1   = f2 htf3_bias (HTF bias)
  f3-f18 all computed on M15 bars.
  NO M30 feature, NO M3 feature. NO D1/H1 in the setup model.

OVERLAP
  M15 (base): shared decision layer. Present in both.
  H4: present in BOTH, but with different ROLE:
        runtime/setup: H4 is a HARD directional GATE (required, direction-compatible).
        training/ML:   H4 bias is ONE of three HTF bias features (f1), a soft
                       numeric input into an MLP; never a gate.
  D1, H1: training/ML only (no canonical setup role).
  M30, M3: runtime/setup only (no training/ML representation).
```

```text
CONSEQUENCE (already recorded P3-S.7 D-5 + S-PR):
  The two MTF models are DIFFERENT. The feature pipeline carries NONE of the
  M30/M3 semantic content that the canonical Candidate Setup relies on as
  required gates/confirmation, and carries extra D1/H1 biases the setup layer
  does not use. The ML features do NOT mathematically represent the full
  canonical runtime/setup information set.
```

---

## C. AS-OF / CLOSED-BAR CONTRACT (both models must satisfy, per decision bar t)

For a decision at decision-bar time `t` (decision bar = newest CLOSED bar on the
base M15 layer; `tc = t + 900s` = the M15 close time):

```text
Runtime canonical (setup layer, Engine 1 closed-bar lock):
  H4_asof(t)  : newest CLOSED H4 bar with close_time  <= t
  M30_asof(t) : newest CLOSED M30 bar with close_time <= t
  M15_asof(t) : newest CLOSED M15 bar with close_time <= t  (= decision bar)
  M3_asof(t)  : newest CLOSED M3 bar with close_time  <= t
  Invariant   : HTF/M15/M3 close_time <= t for every consumed value.

Training / ML feature path (FEATURE_CONTRACT E_ea, corrected P2.5):
  For HTF in {D1, H4, H1}:
    E_ea(t)   : newest HTF bar whose close_time <= tc
              = searchsorted(ht, tc - period_sec, side='right') - 1
    Closed-bar: the 200 newest CLOSED HTF bars ending at E_ea; bias = tf_bias_asof(E_ea).
  M15 base features: computed on the newest CLOSED M15 bar at tc.
```

```text
REQUIRED SEMANTIC PARITY (both sides):
  - same source timeframe            D1/H4/H1 + M15 (ML) vs H4/M30/M15/M3 (setup)
  - same as-of timestamp             as-of <= t / <= tc (closed bar only)
  - same closed-bar semantics        no forming bar, no partial HTF candle
  - same formula per feature         (runtime BTTFBias == training tf_bias_asof)
  - same window per feature          (200-newest-HTF; 700-M15 slice; etc.)
  - same handling of missing/short history  (neutral 0 / "Neutral" wait)
```

```text
RUNTIME vs TRAINING AS-OF EQUIVALENCE (verified)
  Runtime BTTFBias (200 newest CLOSED cache bars) == training tf_bias_asof(E_ea)
  on the CORRECTED feed → P2.5 parity f0 1/14850, f1 1/14850, f2 0/14850
  (2 residual exception rows = cache staleness at session-break boundary; TOLERATED).
  → D1/H4/H1 bias semantics CAN be aligned exactly (P2.1 fix made them equal).
  → M30/M3 lead NO training feature, by construction of the Feature Contract.
```

---

## D. FEATURE-LEVEL MTF MAP (f0-f18)

See the accompanying `docs/P3_S14_MTF_TRAINING_ALIGNMENT.md` §C for the full
19-row table. Summary classification:

```text
f0 (D1 bias)  : M15 decision + D1 as-of      : training/ML only (setup has no D1)
f1 (H4 bias)  : M15 decision + H4 as-of      : BOTH (role differs: gate vs soft feature)
f2 (H1 bias)  : M15 decision + H1 as-of      : training/ML only (setup has no H1)
f3-f5         : M15 only (structure/trend)   : shared base (M15 in both)
f6            : M15 eq position              : shared base
f7            : M15 sweep (F1 event)         : shared base; M15-internal
f8-f9         : M15 CHoCH/confirm (F1/event) : shared base; M15-internal
f10-f11       : M15 EQH/EQL                  : shared base
f12-f13       : M15 delta                    : shared base
f14-f17       : M15 distance/mom/range       : shared base
f18           : confluence (derived)         : derived from M15 base + f0-f2

=> NONE of f0-f18 is computed on M30 or M3.
=> The runtime H4 gate bias (f1, when adapted) is the ONLY runtime-level input
   that the current feature set carries for the canonical HTF stack, and it
   carries NO notion of the H4/M30 "gate with direction compatibility".
```

---

## E. HTF BIAS SEMANTICS — RUNTIME vs TRAINING

```text
RUNTIME (AlgoForge_Backtest_Baseline.mq5 BTTFBias, after P2.1 fix):
  source   : Engine-1 cache slot (D1/H4/H1); closed-bar lock
  window   : the 200 NEWEST closed bars of the cache (bars[199..0])
  pivot    : fractal swing s=3 (+/-3)
  break    : close[i] > up (bull) / < dn (bear); loop excludes the newest bar
  warm-up  : need < 120 -> "Neutral" (0)
  as-of    : the M15 decision bar t; cache holds bars with close_time <= tc

TRAINING (tf_bias_asof + build_features_p2 bias_series):
  source   : HTF npz arrays (D1/H4/H1)
  window   : tf_bias_asof(k) over [max(0,k-199) .. k] (200 bars ending at E_ea)
  pivot    : fractal swing s=3 (+/-3)  [identical]
  break    : close[i] > up / < dn; loop excludes bar k (inert) [identical]
  warm-up  : m < s+2 -> 0 ["Neutral" equivalent]
  as-of    : E_ea = searchsorted(ht, tc - period, 'right') - 1 [P2.1 corrected]

CLASSIFICATION of the residual differences (P2.1/P2.2/P2.5):
  - 50-bar cache-lag EA bug (D1 50d / H4 ~8.3d / H1 ~2.1d) : BUG  -> FIXED (P2.1)
  - gap at session-break boundary (Refresh-on-Bars-change)  : LEGACY DESIGN
    Engine 1 rebuild-on-Bars-change cache staleness edge; documented, TOLERATED.
  - legacy v4.4 "200 newest incl. forming" vs contract "200 newest CLOSED"
    (E_ea, inert forming bar)                               : INTENTIONAL DIFFERENCE
    (contract = non-look-ahead deterministic definition; documented P2.1 §5)
  No remaining runtime/training HTF-bias BUG after the P2.1 fix for D1/H4/H1.
```

---

## F. TRAINING MTF MODEL — PROVENANCE (forensic)

```text
WHY training uses D1/H4/H1 + M15 (no M30/M3):
  A. LEGACY v4.4 architecture — the original SniperGold SMC Pro+ had exactly
     three HTF biases (D1/H4/H1) via TFBias()+chart M15. The 19-feature MLP was
     trained on that feature set (README "baseline MLP 19->12->2 ... not reused
     in AlgoForge"; FEATURE_CONTRACT §4 provenance P2.1-P2.3). It carries the
     v4.4 D1/H4/H1 MTF model forward.
  B. Historical model freeze — the deployed SniperGold_ML.mqh (AUC 0.627/0.621,
     freeze v20260821_2head) was trained on the OLD v4.4 feature semantics; the
     P2-corrected feed (build_features_p2) was NOT integrated into train_model.py
     (P2 §F). The model weights remain a frozen artifact of the D1/H4/H1+M15 feed.
  C. Documentation drift — the canonical H4/M30/M15/M3 model is a NEWER design
     (Algo Forge 3-engine refactor, P3-S.7+); the Feature Contract (f0-f18) kept
     the legacy HTF set. FEATURE_CONTRACT was documented to describe the ML path
     only, and P3-S.7 S-PR explicitly records the "FEATURE_CONTRACT MTF MISMATCH".
     This is intentional (two MTF models coexist), not a silent bug.
  D. NOT a simple bug — the divergence is architectural (legacy ML feed vs newer
     setup model), documented in P3-S.7 §14 and P3-S.12 §P. It is not an
     accidental bit-error; it is a deliberate-but-unreconciled historic fork.
```

---

## G. ALIGNMENT OPTIONS (evaluated on SEMANTICS, not AUC)

```text
OPTION A — Align ML directly to H4/M30/M15/M3
  add M30/M3 inputs + drop D1/H1 -> one canonical MTF everywhere.
  Cost: new feature set, new training dataset, new model; the frozen 19-feature
  model becomes non-comparable. Static MLP retrain required (FUTURE phase).

OPTION B — Keep the ML feature architecture, MAP it explicitly
  keep d0-f18 (D1/H4/H1 + M15) as the ML feed, and DOCUMENT an explicit mapping
  between (f1=H4 bias) and the runtime H4 gate, and between the M15 base features
  and the M15 setup carrier. M30/M3 remain unrepresented in ML (documented gap).
  Less disruptive; preserves the existing model; does NOT give ML the M30/M3
  gate content.

OPTION C — Retire the current static ML architecture
  only if evidence shows the frozen MLP cannot be meaningfully aligned (e.g., it
  predates the canonical setup and encodes a divergent v4.4 semantics).
  Not settled by performance; settled by semantic consistency.

F4 RECOMMENDATION (see docs/P3_S14_MTF_TRAINING_ALIGNMENT.md §J region):
  The 19-feature D1/H4/H1+M15 MLP is semantically a DIFFERENT model from the
  H4/M30/M15/M3 Candidate Setup. It is not "the same information written
  differently": it is missing M30/M3 entirely. Per the brief, do NOT force H4/
  M30/M15/M3 into the ML. The honest verdict is LEGACY / NOT COMPARABLE for the
  static MLP vs the Candidate Setup layer (below), with a documented engineering
  path (Option B map now; Option A/C as future authorization).
```

---

## H. VERDICT DEFINITIONS (used by the final report)

```text
ALIGNED              : same MTF set, same as-of, same formulas.
PARTIALLY ALIGNED    : same base (M15) + partial HTF overlap (H4), missing M30/M3.
MISALIGNED           : conflicting MTF sets with no documented reconciliation.
LEGACY / NOT COMPARABLE : the two models are different generations/architectures
                          (legacy v4.4 ML feed vs newer candidate-setup model);
                          not "wrong", just not the same object.
```

*End of SMC_MTF_TRAINING_ALIGNMENT_SPEC_v1.*