# SniperGold_ML — RESEARCH REPOSITORY

```text
DOCUMENT ROLE : PUBLIC_SUMMARY
AUTHORITY     : PUBLIC / HUMAN SUMMARY ONLY. This README MUST NEVER override
                canonical machine evidence, CURRENT_PROJECT_STATE.md,
                CURRENT_DECISION_GATE.md, or frozen contracts. The section
                below is the CURRENT research status; the Algo Forge content
                further down is LEGACY / HISTORICAL and is not current.
```

## CURRENT AUTHORITATIVE RESEARCH STATUS

```text
Session lineage : P3 (research governance) on this authoritative workspace.
Authoritative workspace :
  D:\TradingTerminal\HFM Metatrader 5\MQL5\Shared Projects\SniperGold_ML_authoritative
Repository      : https://forge.mql5.io/chiki2bum2/SniperGold_ML.git
Branch          : main

CURRENT state   : P3-S25.1 Stage-B — CHUNK 10 COMPLETE
Research status : External Tickstory basis validation IN PROGRESS
                  (run P3_S251_REAL_TICK_RUN_001, real chunks 0-10 committed,
                   chunk 11 next @ byte offset 163,578,081; full 34.5 GB
                   dataset NOT complete)
Conclusion      : P3-S24 — CURRENT EDGE NOT DEMONSTRATED
Chunk policy    : SAFE_MAX_CHUNK_SIZE = 24 MiB (invariance + 10/10 mutations);
                  SAFE_CHUNKS_PER_TURN = NOT ESTABLISHED (P3-S25.1D multi-chunk
                  benchmark OPEN)
Next action     : P3-S25.1 Stage-B CHUNK 11 ONLY at SAFE_MAX 24 MiB from
                  offset 163,578,081 (explicit owner authorization required)

Read (in this order):
  docs/CURRENT_PROJECT_STATE.md
  docs/CURRENT_DECISION_GATE.md
  docs/AI_ASSISTANT_SESSION_START_PROTOCOL_v2.md
  newest docs/SESSION_HANDOVER_*.md
```
This section is the CURRENT research status and does NOT reflect any deployed
trading model or any proven predictive edge.

---

## LEGACY / HISTORICAL IMPLEMENTATION  (kept for reference; NOT current)

The following describes the original "Algo Forge" refactor (Engines 1-3 +
hybrid ML). It is legacy/historical information, not the current research
conclusion. The legacy model AUC (0.627/0.621) applied only to the original
training feed and is NOT a current or deployable edge claim.

---

# Algo Forge

**Full refactor of SniperGold SMC Pro+** — 3-engine architecture + hybrid ML.

## SOURCE ATTRIBUTION (MANDATORY)

- This project is a **total refactor** (new architecture), **not a direct copy**.
- Source inspiration & display:
  - **SniperGold SMC Pro+** — `https://www.mql5.com/en/code/75466`
  - Copyright: **Waseem Shahrukh**
- Attribution is stated in the header of every file, this README, and the "Algo Forge" publication.

## Baseline (old project — reference, do not delete)

| Component | Status |
|---|---|
| `SniperGold_SMC_ProPlus_v4_4.mq5` | Calibrated 2-head ML; test AUC LONG **0.6270** / SHORT **0.6207** |
| `SniperGold_SMC_ProPlus_v4_5.mq5` | MTF structure + index cache (0 errors / 0 warnings) |
| `SniperGold_ML.mqh` | MLP 19→12→2 + Platt calibration (not reused in AlgoForge) |

## Target Architecture (3 Engines + ML)

| Engine | Function | Status |
|---|---|---|
| **Engine 1** | MTF bar collector + reusable index cache (closed-bar lock, chart-TF independent) | ✅ Complete (Phase 1, 2026-08-21) |
| **Engine 2** | 4 independent signal agents N/C/E/P (dynamic-weight fuzzy) + separate aggregator | ✅ Complete (Phase 2, 2026-08-21) |
| **Engine 3** | Display like the original 75466 code (reads Engine 1–2 output only) | ✅ Complete (Phase 3, 2026-08-21) |
| **ML** | LSTM + Regime-Switching (MSM/GARCH) in front of LSTM, ~20-year sample, separate engine; walk-forward + bootstrap CI + multi-seed; deploy only if it beats the baseline | ❌ **No-Go (Phase 4)**: 2-layer LSTM + regime LOST to the baseline (dAUC −0.0196/−0.0134); baseline MLP 0.627/0.621 REMAINS deployed |

Agent timeframe parameters: **HARDCODED** `AF_E2_TF_S1..S4` = **H4/M30/M15/M3** (N/C/E/P) — manual inputs `InpHtfS1..S4` **removed**; `InpDispTF` (Engine 3, default = chart) remains an input.

Official old-project documents: `Shared Projects\SniperGold_ML\REFACTOR_ALGOFORGE.md`.

## Folder Structure (code)

```
MQL5\
├── Include\AlgoForge\
│   ├── AF_Attribution.mqh           # attribution header (MANDATORY, first include)
│   ├── AF_Defines.mqh               # Engine 1–3 constants & result codes
│   ├── AF_Engine1_MTFData.mqh       # Engine 1: class AFEngine1MTF + AFBar
│   ├── AF_Engine2_Agents.mqh        # Engine 2: 4 agents N/C/E/P + fuzzy
│   ├── AF_Engine2_Aggregator.mqh    # Engine 2: aggregator + facade AFEngine2Signals
│   ├── AF_Engine2_Display.mqh       # Engine 2: AFDisplayData builder (display context)
│   └── AF_Engine3_Render.mqh        # Engine 3: pure renderer (draws only)
├── Experts\
│   ├── AlgoForge_Engine1_UnitTest.mq5  # Engine 1 unit test (Strategy Tester)
│   ├── AlgoForge_Engine2_UnitTest.mq5  # Engine 2 unit test (Strategy Tester)
│   ├── AlgoForge_Engine3_UnitTest.mq5  # Engine 3 unit test (Strategy Tester)
│   └── AlgoForge_Backtest_Baseline.mq5 # baseline MLP backtest (mode 0 = CSV prob/AUC,
│                                       #   mode 1 = trade net-of-spread; internal features,
│                                       #   data source Engine 1; NOT iCustom)
├── Indicators\AlgoForge\
│   └── AF_Engine3_Display.mq5         # Engine 3: display indicator (chart)
└── Profiles\Tester\
    ├── AlgoForge_Engine1_UnitTest.XAUUSD.M15.*.ini
    ├── AlgoForge_Engine2_UnitTest.XAUUSD.M15.*.ini
    ├── AlgoForge_Engine3_UnitTest.XAUUSD.M15.*.ini
    └── AlgoForge_Backtest_Baseline.XAUUSD.M15.*.ini
```

Project documentation: `Shared Projects\AlgoForge\` (README, DESIGN, PROGRESS).

## Session Status

| Date | Phase | Result |
|---|---|---|
| 2026-08-21 | 0–1 | Project structure + attribution; Engine 1 complete; compile 0/0; unit tests PASS=115070 FAIL=0 (20 days) & PASS=8870 FAIL=0 (verification) |
| 2026-08-21 | 2 | Engine 2 complete (4 agents N/C/E/P + fuzzy + aggregator); compile 0/0; unit tests PASS=21534 FAIL=0 (20 days) & PASS=9942 FAIL=0 (10-day verbose) |
| 2026-08-21 | 3 | Engine 3 complete (structure/zone/signal/dashboard display, reads Engine 1–2 output only); compile 0/0; unit test **PASS=21528 FAIL=0** (20 days) |
| 2026-08-21 | 4 | Hybrid ML 2-layer LSTM + regime: **GATE No-Go** (dAUC LONG −0.0196 / SHORT −0.0134 vs 0.627/0.621; negative CI; 0/5 seeds); baseline MLP REMAINS deployed |
| 2026-08-21 | 5 | Verification & publication: compile 0/0 + Engine 1–3 unit-test regression (PASS 115070/21534/21528, FAIL=0); honest net-of-spread baseline backtest (CSV/AUC: LONG 0.5305 / SHORT 0.5487 on the XAUUSD feed; 308 trades, PF 1.32) |

Details: see `PROGRESS.md` and `REFACTOR_ALGOFORGE.md` §10–13, §19–21.