SniperGold_ML/docs/P3_S7_MTF_ALIGNMENT_CONFORMANCE.md

335 lines
20 KiB
Markdown

# P3-S.7 MTF ALIGNMENT — FORMAL SPECIFICATION & CODE-CONFORMANCE REPORT
```text
Date : 2026-08-22
Session : P3-S.7 — MTF Alignment semantic validation (H4 Narrative -> M30
Context -> M15 Entry -> M3 Price Action)
Principle : SPECIFICATION FIRST, CODE AUDIT SECOND
Scope : SEMANTIC/ARCHITECTURAL conformance ONLY. No AUC/PF/backtest, no
ML, no optimization, no production code changes, no human
verification (CANCELLED).
Question : Does the current implementation genuinely implement the intended
H4 Narrative -> M30 Context -> M15 Entry -> M3 Price Action
hierarchy with correct timestamp alignment, timeframe semantics,
and cross-timeframe consumption?
Artifacts : docs/SMC_MTF_ALIGNMENT_SPEC_v1.md (specification)
ml/p3/smc_semantic/spec_tests_mtf_alignment.py (+ .json) (tests)
ml/p3/smc_semantic/output/spec_tests_mtf_alignment_report.json
docs/SESSION_HANDOVER_2026-08-22_P3_S7_MTF_ALIGNMENT.md
```
---
## 0. CHECKPOINT & PROVENANCE (session-start verification)
```text
Forge HEAD : 533c8c6647a552d01a1a290cb2d0505f94887666 (P3-S.6) VERIFIED
Branch / remote : main == origin/main (533c8c6) VERIFIED
Working tree : CLEAN at start VERIFIED
P3-S.6 artifacts : spec/conformance/tests/report/handover INTACT VERIFIED
HUMAN VERIFICATION : CANCELLED VERIFIED
No production change after P3-S.6 : VERIFIED (clean tree, single commit)
```
---
## A. SOURCE MATERIAL (Phase A — inventory & reconciliation)
| # | Source | Location | TF(s) | Semantic role | Inputs | Outputs | State | Consumer |
|---|--------|----------|-------|---------------|--------|---------|-------|----------|
| 1 | AFEngine1MTF (Register/Refresh/Build) | Include\AlgoForge\AF_Engine1_MTFData.mqh | any explicit TF (H4/M30/M15/M3/D1/W1) | MTF cache + closed-bar lock + anti-freeze | CopyRates per (symbol,TF) | AFBar cache bars[0]=newest closed | lastBars/count/ready | Engine 2 agents, Engine 3, EA |
| 2 | AF_E2_TF_S1..S4 | Include\AlgoForge\AF_Defines.mqh:47-50 | H4/M30/M15/M3 | hardcoded agent TF contract | — | macros | — | indicator + unit tests |
| 3 | AFAgentNarrative::Compute | AF_Engine2_Agents.mqh:430-490 | H4 (slot S1) | "Which way is the market?" (trend/CHoCH/BOS/sweep/PD) | H4 slot only | AFSignalOut | none | Aggregator |
| 4 | AFAgentContext::Compute | AF_Engine2_Agents.mqh:492-575 | M30 (slot S2) | "Which zone is price in?" (OB/FVG/SR/PD) | M30 slot only | AFSignalOut | none | Aggregator |
| 5 | AFAgentEntry::Compute | AF_Engine2_Agents.mqh:583-663 | M15 (slot S3) | "Entry confirmation?" (sweep/CHoCH/disp/OB/FVG; ZONE+CONF) | M15 slot only | AFSignalOut | none | Aggregator |
| 6 | AFAgentPriceAction::Compute | AF_Engine2_Agents.mqh:665-745 | M3 (slot S4) | "When to open?" (candle patterns) | M3 slot only | AFSignalOut | none | Aggregator |
| 7 | AFAggregator::Compute | Include\AlgoForge\AF_Engine2_Aggregator.mqh:77-170 | — | 2-pass weighted vote + 1.5x majority boost (0.30/0.30/0.25/0.15) | 4 AFSignalOut + slotE | AFAggOut (dir/buy/sell/entry/SL/TP) | none | Engine 3 display |
| 8 | AFEngine2Signals::Compute | AF_Engine2_Aggregator.mqh:183-199 | — | facade (4 agents + aggregator) | e1 + 4 slots | signals + agg | none | indicator/EA |
| 9 | AF_BuildDisplayData | Include\AlgoForge\AF_Engine2_Display.mqh:308-395 | sDisp (chart=M15) + sD1 + sW1 | display context (structure/zones on sDisp; D1/W1 levels; agent biases) | e1 + agent outputs | AFDisplayData | none | Engine 3 render |
| 10 | AF_Engine3_Display.mq5 OnCalculate | Indicators\AlgoForge\AF_Engine3_Display.mq5:181-207 | H4/M30/M15/M3 + chart + D1/W1 | driver: refresh + compute on new closed display bar | e1 slots | display objects | g_lastDispBar | chart |
| 11 | AlgoForge_Backtest_Baseline.mq5 | Experts\AlgoForge_Backtest_Baseline.mq5 | M15 + D1/H4/H1 | ML runtime (19 features; NO Engine 2) | e1 slots (M15/H1/H4/D1) | g_feat[19], probs | persistent structure state | MLP SniperGold_ML.mqh |
| 12 | build_features.py / train_model.py | ml/build_features.py, ml/train_model.py | M15 + D1/H4/H1 | training features (f0-f2 HTF biases; f3-f18 M15) | npz data | F(n,19) | none | MLP training |
| 13 | FEATURE_CONTRACT.md | docs/FEATURE_CONTRACT.md | M15 + D1/H4/H1 | authoritative feature contract (E_ea as-of) | — | f0-f18 | — | runtime + training |
| 14 | v4.5 legacy | Indicators\Downloads\SniperGold_SMC_ProPlus_v4_5.mq5 | D1/H4/H1 + M15 | legacy per-TF structure + TFBias | CopyRates per TF | TFStruct cache | lastIndex/TF | legacy signal/display |
| 15 | v4.3/v4.4 legacy | Indicators\Downloads\SniperGold_SMC_ProPlus_v4_3/4_4.mq5 | chart TF + TFBias(D1/H4/H1) | legacy chart structure + HTF bias | chart rates + 3 HTF | features | state | legacy signal |
| 16 | P3-S.2..S.6 specs | docs/SMC_*_SPEC_v1.md | per concept | canonical timeframe statements (see §H) | — | — | — | this audit |
| 17 | parity report | ml/parity/RUNTIME_TRAINING_PARITY_REPORT.md | M15 + D1/H4/H1 | ML path parity (SB-06) | — | — | — | this audit |
**Layer separation:**
```text
INTENDED MTF SEMANTICS : DESIGN.md §8-9 — four role agents (N/C/E/P) on
H4/M30/M15/M3, independent, aggregated separately.
LEGACY MTF SEMANTICS : v4.5 = D1/H4/H1 structure + M15 chart; v4.3/v4.4 =
M15 chart + TFBias(D1/H4/H1). No M30/M3.
CURRENT IMPLEMENTATION : Engine 2 agents H4/M30/M15/M3 (same per-TF detector
suite + role composition) + flat vote aggregator;
ML path M15 + D1/H4/H1.
TRAINING SEMANTICS : M15 + D1/H4/H1 (f0-f2). No M30/M3.
DISPLAY SEMANTICS : M15 structure/zones + D1/W1 levels + N/C/E/P biases.
```
---
## B. FORMAL SPECIFICATION (Phase B)
Full document: **docs/SMC_MTF_ALIGNMENT_SPEC_v1.md** (PROJECT SEMANTIC
SPECIFICATION — not universal SMC truth).
Spec decision summary (S-N..S-ST):
```text
S-N H4 = Narrative directional VOTE (0.30); can trigger entry alone; NO gate.
S-C M30 = Context zone VOTE (0.30); can trigger alone; NO filter on M15.
S-E M15 = Entry VOTE (0.25) + internal ZONE+CONFIRMATION; contradiction NOT
blocked.
S-P M3 = Price Action VOTE (0.15); timing role; not mandatory; no override.
S-H Hierarchy = top-down ANALYSIS order; DECISION = flat vote; no REQUIRED
stage.
S-D Direction = aggregator 2-pass weighted vote; 1.5x majority boost;
thresholds bias 0.20 / support 0.50.
S-X Conflict policy = NONE (SPECIFICATION AMBIGUOUS; arithmetic resolution).
S-T As-of = closed-bar lock per slot; H4/M30/M15/M3_asof(t) <= t; deterministic
HTF-close visibility (e.g., H4 04:00 close visible at first decision t>=04:00).
S-A Aggregation = SAME-LEVEL VOTES; hierarchical gate NOT implemented.
S-R Cross-TF references = NONE (no LTF event reads HTF structure).
S-I TF substitution = explicit per-slot contract via macros; runtime identity
by convention.
S-V Display = M15 structure + D1/W1 levels + biases; H4/M30 structure not drawn.
S-PR Parity = ML path (D1/H4/H1/M15) parity-verified; agent path (H4/M30/M15/M3)
N/A by absence; FEATURE_CONTRACT MTF MISMATCH (two MTF models).
S-XC Cross-concept = 5 concepts across 3 MTF models; no unified canonical TF.
S-ST Stale state = agent path stateless; no stale HTF consumption by construction.
```
---
## C. CURRENT CODE BEHAVIOR (Phase C — code audit)
```mql5
// AF_Defines.mqh:47-50 — hardcoded agent TFs
#define AF_E2_TF_S1 PERIOD_H4 // S1 = Narrative (N)
#define AF_E2_TF_S2 PERIOD_M30 // S2 = Context (C)
#define AF_E2_TF_S3 PERIOD_M15 // S3 = Entry (E)
#define AF_E2_TF_S4 PERIOD_M3 // S4 = Price Action (P)
// AF_Engine1_MTFData.mqh — closed-bar lock (Build):
if(!IsBarClosed(rates[0].time, tf, TimeCurrent())) skip=1; // drop forming bar
// AF_Engine2_Aggregator.mqh:77-170 — flat weighted vote:
baseW[0]=AF_AGG_W_N(0.30); baseW[1]=AF_AGG_W_C(0.30);
baseW[2]=AF_AGG_W_E(0.25); baseW[3]=AF_AGG_W_P(0.15);
// pass1: bias1 = SUM(baseW*conf*bias)/SUM(baseW*conf); majDir = +-1/0 at 0.05
// pass2: boost 1.5 for agents with dir==majDir; buy/sell = weighted sums
// final: dir = +1 if bias>=0.20 && buy>=0.50 ; -1 mirror ; else 0
```
Observations:
- The four agent classes read exactly one Engine-1 slot each; no agent calls
another; no agent reads a second TF. Verified in source (AF_Engine2_Agents.mqh).
- All structural detectors (AF_BuildSwing, AF_DetectSweep, AF_DetectChoch,
AF_FindOrderBlock, AF_FindFVG, AF_RangeStat) are per-TF pure functions; the
same algorithm executes on whichever slot the agent passes.
- The aggregator combines four AFSignalOut as a weighted vote with agreement
boost. Any single agent (including the 0.15-weight P) can produce a final
BUY/SELL when confident (verified arithmetically; unit test T6 asserts the
N-only -> BUY case).
- Entry/SL/TP levels use slotE (M15) only.
- The backtest baseline EA does NOT use Engine 2 at all (0 references) — the
ML path is separate (M15 + D1/H4/H1).
- Python training has 0 M30/M3 references; the Feature Contract HTF set is
D1/H4/H1.
---
## D. CONFORMANCE MATRIX (Phase C)
| Requirement | Specification | Code Location | Actual Behavior | Verdict |
|---|---|---|---|---|
| H4 role | Narrative directional VOTE 0.30; can trigger alone; NO gate (S-N) | AFAgentNarrative::Compute (H4 slot); aggregator baseW[0]=0.30 | H4 reads only its slot; contributes vote; unit test T6: N-only -> BUY | **CONFORMING** |
| M30 role | Context zone VOTE 0.30; NO filter on M15 (S-C) | AFAgentContext::Compute (M30 slot); baseW[1]=0.30 | M30 OB/FVG/SR/PD vote; can trigger alone; no direct M15 coupling | **CONFORMING** |
| M15 role | Entry VOTE 0.25 + ZONE+CONF internal; contradiction not blocked (S-E) | AFAgentEntry::Compute (M15 slot); baseW[2]=0.25 | ZONE+CONFIRMATION rule internal; M15 never reads H4/M30 | **CONFORMING** |
| M3 role | Price Action VOTE 0.15; timing; not mandatory (S-P) | AFAgentPriceAction::Compute (M3 slot); baseW[3]=0.15 | Candle patterns vote; alone can pass 0.20/0.50 thresholds at conf>=~0.57 | **CONFORMING** |
| Hierarchy | Top-down ANALYSIS order; DECISION = flat vote; no REQUIRED stage (S-H) | DESIGN.md §8; aggregator | Analysis order H4->M30->M15->M3 is documentation; decision is flat vote | **PARTIALLY CONFORMING** (D-1: decision hierarchy absent; HIERARCHICAL-TO-VOTING DRIFT) |
| Direction propagation | 2-pass weighted vote + 1.5x boost; 0.20/0.50 (S-D) | AFAggregator::Compute pass1/pass2 | exact formula match; single-agent permissiveness verified (MTF-T19..T22) | **CONFORMING** |
| Conflict policy | NONE defined; arithmetic resolution (S-X) | no conflict branch in aggregator | contradictions resolved by vote; no BLOCK/WAIT/OVERRIDE | **SPECIFICATION AMBIGUOUS** (D-2) |
| As-of timestamp | H4/M30/M15/M3_asof(t) <= t; deterministic HTF visibility (S-T) | AFEngine1MTF::Build/IsBarClosed; Refresh on Bars() change | closed-bar lock per slot; forming bar dropped; cache = newest closed bars at t | **CONFORMING** |
| Cache alignment | slot <-> TF explicit; macros H4/M30/M15/M3 (S-I) | Register(tf,..); AF_E2_TF_S1..S4 in all consumers | idempotent per (symbol,tf); consumers use the same macros | **CONFORMING** (D-3: runtime TF identity by convention — UNVERIFIABLE per MTF-T11) |
| Stale state | agent path stateless; no stale HTF consumption (S-ST) | agents stateless; no cross-TF reads | no HTF state exists to go stale in the agent path | **CONFORMING** |
| Aggregation | SAME-LEVEL VOTES; hierarchical gate NOT implemented (S-A) | AFAggregator::Compute | flat weighted vote + boost; entry levels on M15 only | **PARTIALLY CONFORMING** (D-1: drift vs strict-hierarchy reading) |
| Display consistency | M15 structure + D1/W1 levels + biases; H4/M30 structure not drawn (S-V) | AF_BuildDisplayData (sDisp/sD1/sW1); AFR_DrawAll | display shows M15 structure/zones + D1/W1 levels + N/C/E/P biases; H4/M30 structures absent | **PARTIALLY CONFORMING** (D-4: V-1..V-4 documented) |
| Training/runtime parity | ML path parity-verified; agent path N/A by absence (S-PR) | SB-06 report; build_features.py; EA | ML path (D1/H4/H1/M15) parity OK; agent path (H4/M30/M15/M3) has no training surface; contract TF set differs | **PARTIALLY CONFORMING** (D-5: FEATURE_CONTRACT MTF MISMATCH) |
| Cross-concept consistency | 5 concepts / 3 MTF models; no unified canonical TF (S-XC) | P3-S.2..S.6 + this audit | f7/f8/f9 M15-only (contract) vs per-TF Engine 2 vs legacy D1/H4/H1; FVG/OB/Displacement multi-TF | **NON-CONFORMING** (D-6: X-1..X-5 documented) |
| Consumer semantics | no LTF->HTF structural consumption; confluence at vote level (S-R) | agent slots single-TF; aggregator | no cross-TF structural reference anywhere | **CONFORMING** (to S-R as defined) |
---
## E. CONFIRMED FINDINGS (Phase D — DOCUMENT ONLY, no code changes)
```text
D-1 HIERARCHICAL-TO-VOTING DRIFT [MEDIUM]
The session brief posits "H4 Narrative -> M30 Context -> M15 Entry -> M3
Price Action" as a DECISION chain. The implementation (and DESIGN.md)
model it as a FLAT weighted vote of four independent role-labeled agents.
H4/M30/M15/M3 each can trigger a final BUY/SELL alone (verified: MTF-T19,
MTF-T20, MTF-T22); no stage is REQUIRED; no stage gates another. If the
project intends a strict top-down gate, the implementation drifts; per
DESIGN.md the vote IS the design. Not adjudicated (A-2).
D-2 CONFLICT POLICY UNDEFINED [MEDIUM]
No BLOCK/WAIT/LOWER-OVERRIDES/HIGHER-OVERRIDES/CONFLICT-STATE policy
exists in spec or code. Contradictions (e.g., H4 bull + M15 bear) are
resolved arithmetically by the weighted vote; the aligned majority gets
a 1.5x boost. A strong H4+M30 bullish pair can produce BUY over a bearish
M15+M3 pair (MTF-T21). Not adjudicated (A-1).
D-3 RUNTIME TF-IDENTITY BY CONVENTION [LOW]
Register() is idempotent per (symbol, tf); consumers pass slot indexes
without re-checking the TF. A wrong TF injected into a slot would be
silently consumed. All production consumers use the same macros, so the
risk is latent; the contract is not enforced at consume time (MTF-T11).
D-4 DISPLAY VS DECISION INCONSISTENCY [LOW]
V-1 display shows D1/W1 levels not used by the decision engine;
V-2 display does not render H4 structure or M30 zones (top agent TFs);
V-3 the drawn structure TF (sDisp = chart) coincides with the E agent TF
by default, not by contract;
V-4 no stale re-render within a bar (non-repaint gate works).
D-5 FEATURE_CONTRACT MTF MISMATCH [MEDIUM]
FEATURE_CONTRACT / training / ML runtime use D1/H4/H1 + M15; Engine 2
uses H4/M30/M15/M3. Two MTF models coexist; the "intended" hierarchy is
NOT the trained/parity-verified model. The agent path has no Python
counterpart (PARITY = N/A BY ABSENCE, same class as displacement).
D-6 CROSS-CONCEPT TIMEFRAME INCONSISTENCY [MEDIUM]
f7 sweep = M15 only (contract) vs per-TF AF_DetectSweep (Engine 2);
f8/f9 CHoCH = M15 only (contract) vs per-TF AF_DetectChoch + display TF
(three implementations, P3-S.3);
FVG/OB = multiple per-TF implementations (Engine 2 C/E, display, legacy
v4.5 D1/H4/H1, legacy chart) with no canonical TF;
Displacement = per-TF function, M15-only consumer (P3-S.6 A-1).
The three layers (contract D1/H4/H1/M15, Engine 2 H4/M30/M15/M3, legacy
D1/H4/H1+M15) use different TF sets for the same concepts.
D-7 SAME DETECTOR vs DIFFERENT ROLE [INFORMATIONAL]
The structural detectors are the same per-TF algorithms; the role
differentiation is at the AGENT composition level (which detectors +
weights + question) and at the labels. There is NO structural cross-TF
relationship (S-R). The model is "role-labeled per-TF votes", not
"genuine multi-timeframe structural analysis". MTF ROLE DIVERGENCE
recorded: the project assigns roles by agent, but the underlying
primitive is per-TF identical logic.
NO stale-HTf-state bug: the agent path is stateless; the f7/CHoCH/FVG/OB
stale-consumer bug class does not apply to the Engine-2 MTF hierarchy.
```
---
## F. SEMANTIC AMBIGUITIES
```text
A-1 Conflict policy (D-2) — no BLOCK/WAIT/OVERRIDE policy defined; arithmetic
resolution only.
A-2 Strict-hierarchy intent (D-1) — brief's decision-chain reading vs
DESIGN.md flat-vote design; not adjudicated.
A-3 Canonical concept TF (D-6) — three MTF models; no single canonical TF per
concept.
A-4 Runtime TF-identity enforcement (D-3) — by convention.
```
---
## G. VERDICT (Phase E)
```text
PARTIALLY CONFORMING
H4 role : CONFORMING (narrative vote, 0.30; per spec S-N)
M30 role : CONFORMING (context vote, 0.30; per spec S-C)
M15 role : CONFORMING (entry vote, 0.25 + ZONE+CONF; per spec S-E)
M3 role : CONFORMING (price-action vote, 0.15; per spec S-P)
Hierarchy : PARTIALLY CONFORMING (analysis order yes; decision
hierarchy absent — D-1)
Timestamp semantics : CONFORMING (closed-bar as-of per slot; S-T)
Cache alignment : CONFORMING (explicit slot-TF contract; D-3 note)
Conflict policy : SPECIFICATION AMBIGUOUS (no policy; D-2)
Aggregation : PARTIALLY CONFORMING (flat vote per design; drift
vs strict hierarchy — D-1)
Consumer semantics : CONFORMING (stateless; no stale; no cross-TF refs
per S-R)
Cross-concept consistency : NON-CONFORMING (three MTF models; D-6)
Runtime/training parity : PARTIALLY CONFORMING (ML path parity-verified;
agent path N/A by absence; contract mismatch D-5)
Display consistency : PARTIALLY CONFORMING (V-1..V-4; D-4)
Interpretation:
The four role labels ARE implemented with the correct timeframe assignments
and the per-slot closed-bar/as-of handling is sound. What is NOT
implemented is a genuine multi-timeframe SEMANTIC hierarchy: the model is a
flat vote of four independent, role-labeled, same-detector-per-TF agents
with no cross-timeframe structural references, no defined conflict policy,
and a training/runtime surface that uses a DIFFERENT MTF model
(D1/H4/H1/M15). The verdict is conformance to the PROJECT semantic
specification (as derived from DESIGN.md + code), NOT an endorsement of the
MTF concept as an edge.
```
---
## H. CROSS-CONCEPT TIMEFRAME MATRIX (brief §28)
| Concept | Contract/ML canonical | Engine 2 agent use | Legacy v4.5 | H4 role | M30 role | M15 role | M3 role |
|---|---|---|---|---|---|---|---|
| Liquidity Sweep | M15 ONLY (f7) | per-TF (N,E); display M15 | per-TF D1/H4/H1 | N input | not in C | E input | not in P |
| CHoCH/MSS | M15 ONLY (f8/f9) | per-TF (N,E); display M15 | per-TF D1/H4/H1 | N input | not in C | E input | not in P |
| FVG | NOT in contract | per-TF (C 40, E 20); display M15 | chart + D1/H4/H1 | not in N | C zone | E zone | not in P |
| OB | NOT in contract | per-TF (C,E); display M15 | chart + D1/H4/H1 | not in N | C zone | E zone | not in P |
| Displacement | NOT in contract | M15-only consumer (E); per-slot fn | none | not in N | not in C | E confirmation | not in P |
Contradictions X-1..X-5 (see D-6) are DOCUMENTED, not resolved.
---
## I. PREVIOUS BUG-CLASS CHECK (brief §31)
```text
detector correct -> MTF consumer wrong : NOT FOUND in the agent path
(agents stateless; no MTF consumer of HTF events). The ML path f9/f18
stale-consumer class was already documented (P3-S.0/S.3) and is M15-internal.
correct HTF state -> wrong as-of timestamp : NOT FOUND (closed-bar lock;
as-of verified by cache construction and MTF-T07/T08/T16).
correct timeframe -> wrong cache slot : NOT FOUND in production consumers
(single macro source); latent by-convention risk (D-3, MTF-T11).
correct hierarchical semantics -> flat aggregation : FOUND (D-1) — the
aggregator is flat voting; the strict-hierarchy reading is not implemented.
```
---
## J. NEXT GATE
```text
After the MTF Alignment verdict (PARTIALLY CONFORMING):
P3-S.8 = Candidate Setup.
DO NOT perform consolidated repairs (D-1..D-7 stay open); DO NOT return to ML;
DO NOT modify production code.
```
---
## K. CHECKPOINT & PROVENANCE (P3-S.7)
```text
Forge HEAD (session start) : 533c8c6647a552d01a1a290cb2d0505f94887666 (P3-S.6)
Branch / remote : main == origin/main
Working tree : CLEAN at session start
P3-S.6 artifacts : intact
FEATURE_CONTRACT : NOT modified
No production change : AF_Engine1_MTFData / AF_Engine2_Agents /
AF_Engine2_Aggregator / AF_Engine2_Display /
AF_Engine3_Render / f7-f18 / FVG / OB / CHoCH /
Displacement / ML : NOT touched
Human verification : CANCELLED
```