SniperGold_ML/docs/SESSION_HANDOVER_2026-08-22_P3_S8_CANDIDATE_SETUP.md

# SESSION HANDOVER — SNIPERGOLD_ML P3-S.8: CANDIDATE SETUP SPEC + CONFORMANCE

```text
Date       : 2026-08-22 (session close)
Status     : P3-S.8 COMPLETE — spec + conformance done; synthetic tests 25/25;
             NOT yet committed (handover prepared before commit+push)
Forge      : https://forge.mql5.io/chiki2bum2/SniperGold_ML
Checkpoint : P3-S.6 533c8c6647a552d01a1a290cb2d0505f94887666 (VERIFIED clean at
             start; P3-S.7 artifacts intact, uncommitted)
```

---

## 1. SESSION OBJECTIVE

```text
Formal Specification + Code-Conformance Audit for Candidate Setup.

Question answered:
  What exact combination of market conditions should constitute ONE Candidate
  Setup in SniperGold, and does the current implementation actually create
  Candidate Setups according to that definition?

Answer (VERDICT): SPECIFICATION AMBIGUOUS (with NON-CONFORMING components)
  The repository contains TWO formal Candidate Setup definitions:
    A (current Engine 2, canonical per P3-S.7): the E-agent M15 fuzzy rule
      "ZONE + CONFIRMATION" — min(zone, max(sweep, choch)) * weight 0.30,
      same-bar, OR legs, no gates, no identity, no lifecycle, no expiry.
    B (legacy v4.3/v4.4/v4.5): hard-gated chain HTF-align -> sweep -> CHoCH
      (after sweep) -> OB/FVG tap -> not-premium -> score>=threshold, all
      within SeqWindow=40.
  The current implementation does NOT create Candidate Setups as distinct
  entities: it creates per-bar vote states; the E-rule is a fuzzy weight
  contribution that is invisible downstream (E-vote saturation); the
  dashboard "TRADE SETUP" panel shows the aggregated signal, not a setup.
  STATE / EVENT / ZONE / CONFIRMATION / CANDIDATE SETUP / ENTRY / TRADE are
  kept distinct in the spec (CS-1..CS-32) — the implementation collapses
  SETUP into a vote contribution and the SIGNAL into the "setup" name.

Questions NOT answered: profitability / AUC / PF (semantic audit only).
Human verification = CANCELLED. No production code changes. No ML / repair.
```

---

## 2. SOURCE RECONCILIATION (15 sources)

```text
 1 DESIGN.md §9/§14            : E-agent "ZONE + CONFIRMATION = setup"; dashboard
 2 AF_Defines.mqh:47-50        : H4/M30/M15/M3 agent TF macros
 3 AF_Engine2_Agents.mqh:583-663 : AFAgentEntry::Compute — the ONLY "setup" code
 4 AF_Engine2_Aggregator.mqh:77-170 : flat 2-pass weighted vote
 5 AF_Engine2_Display.mqh      : AF_BuildDisplayData (display context)
 6 AF_Engine3_Render.mqh:272-278 : "TRADE SETUP" panel = aggregated signal
 7 AF_Engine3_Display.mq5      : indicator driver
 8 AlgoForge_Backtest_Baseline.mq5 : ML runtime (19 features; NO Engine 2)
 9 FEATURE_CONTRACT.md         : f7-f18 per-bar features; no setup unit
10 v4.3/v4.4/v4.5 legacy       : SETUP SEQUENCE (institutional gate) — Def. B
11 P3-S.0 f7 lifecycle doc     : SeqWindow=40 = f7 event validity/expiry
12 P3-S.2..S.7 specs           : canonical per-concept statements
13 P3.1c candidate_setup_audit.py : diagnostic strata (f9&f7 etc.), median gap 1 bar
14 P3.2 label forensics        : setup-unit vs event-unit analysis
15 DESAIN_MTF_v45.md           : legacy MTF design (v4.5)

Layers:
  INTENDED    : E-agent rule (A); legacy chain (B) as reference
  LEGACY      : v4.x hard-gated chain, SeqWindow=40
  CURRENT     : Engine 2 flat vote + E-rule fuzzy contribution; no entity
  TRAINING    : per-bar features; diagnostic strata only; no setup unit
  DISPLAY     : "TRADE SETUP" = final signal + levels
```

---

## 3. SPECIFICATION (docs/SMC_CANDIDATE_SETUP_SPEC_v1.md)

```text
CS-1   Setup (A) = E-agent M15 rule: ZONE(OB/FVG membership) AND
       CONFIRMATION(max(sweep,choch)) at the same closed bar -> fuzzy vote
       contribution (wSetup=0.30 normalized). NO entity/identity/onset.
CS-2   Setup (B, legacy) = hard-gated chain (HTF-align -> sweep -> CHoCH ->
       OB/FVG tap -> not-premium -> score>=threshold), SeqWindow=40.
CS-3   Canonical for this audit = Definition A (current Engine 2).
CS-4/5 Causal order: A = same-bar only; B = ordered chain within 40 bars.
CS-7/8 Onset: A = NOT DEFINED; B = entry-tap bar.
CS-9/10 Completion: A = NOT DEFINED; B = gates + score threshold -> signal.
CS-11  Direction (A): E-rule side = setup side; final = flat vote; arithmetic
       conflict resolution (no policy; S-X).
CS-13..16 MTF roles: H4/M30/M3 alone -> NO setup; M15 alone -> YES in A.
CS-17  Hierarchy: A = no cross-TF requirement; B = HTF gate required.
CS-18  Alternative paths (A): {sweep|choch} x {OB|FVG} same-bar (P1..P4).
CS-20/21 Hard requirements: A = zone>0 AND conf>0; B = full gate chain.
CS-22  Score != setup (SETUP-CONSTRUCTION DRIFT D-9).
CS-23  Dedup: NONE in A; no setup_id (SETUP-IDENTITY GAP D-10).
CS-26/27 Lifecycle: A = NONE; B = freshness window only.
CS-28  SeqWindow=40 scope: f7 expiry (ML) + legacy gates; NOT Engine 2.
CS-30  Causality: closed-bar lock; as-of <= t; future mutation cannot change
       past decisions.
CS-31  Setup vs trade: execution semantics excluded from setup validity.
CS-32  State vs setup: only the E-rule conjunction constitutes a setup.
```

---

## 4. CONFORMANCE (docs/P3_S8_CANDIDATE_SETUP_CONFORMANCE.md)

```text
Setup definition          : SPECIFICATION AMBIGUOUS (A vs B; D-8)
Required components       : PARTIALLY CONFORMING
Causal sequence           : PARTIALLY CONFORMING
H4 role                   : CONFORMING (to A: context + vote, no gate)
M30 role                  : CONFORMING (to A)
M15 role                  : CONFORMING (to A: the setup layer)
M3 role                   : CONFORMING (to A: not required)
Hard requirements         : CONFORMING (to A: zone>0 AND conf>0 same-bar)
Score/confluence          : NON-CONFORMING (D-9 SETUP-CONSTRUCTION DRIFT)
Setup onset               : SPECIFICATION AMBIGUOUS
Setup completion          : SPECIFICATION AMBIGUOUS
Deduplication             : NON-CONFORMING (D-10 SETUP-IDENTITY GAP)
Lifecycle                 : SPECIFICATION AMBIGUOUS
Expiration                : PARTIALLY CONFORMING (f7 40-bar OK; Engine 2 none)
Closed-bar causality      : CONFORMING
Consumer behavior         : PARTIALLY CONFORMING (no setup identity downstream)
Runtime/training          : CONFORMING (N/A BY ABSENCE — no setup layer in either)
Cross-primitive           : NON-CONFORMING (X-6..X-10)

VERDICT : SPECIFICATION AMBIGUOUS (with NON-CONFORMING components)
```

---

## 5. SYNTHETIC TESTS — 25/25 PASS

```text
spec_tests_candidate_setup.py + spec_test_cases_candidate_setup.json
+ output/spec_tests_candidate_setup_report.json
CS-T01..T25 all pass; code_port == spec in ALL cases (Definition A IS the
implementation; the differential evidence is structural):
  source_facts: e_agent_setup_rule_is_fuzzy_contribution=True
    setup_entity_exists=False  setup_id_field=False  dedup_exists=False
    expiry_window_in_engine2=False  invalidation_exists=False
    hard_gates_in_engine2=False  legacy_gate_chain_exists=True
    seqwindow_governs_f7=True  aggregator_flat_vote=True
    display_trade_setup_is_signal=True  engine1_closed_bar_lock=True
Key results:
  CS-T04  zone missing -> NO setup, yet E vote saturates bullish (D-11)
  CS-T05  E neutral -> BUY without any setup (signal != setup)
  CS-T09  H4 bull / M30 bear exact tie -> WAIT (arithmetic)
  CS-T10  E,P bear vs N,C bull -> BUY (arithmetic, no veto)
  CS-T11  H4-only BUY = signal CONFORMING; no setup exists
  CS-T12  M15-only with rule fired -> this IS a setup per A + BUY
  CS-T13  same conditions 5 bars -> fires every bar (no dedup)
  CS-T14  age 50 -> Engine 2 still fires; f7 expired (SPEC AMBIGUOUS)
  CS-T17  future mutation -> decision stable (closed-bar lock)
  CS-T18/19 SeqWindow boundary: 40 valid (inclusive), 41 expired
  CS-T21  high score (0.8) without setup -> SETUP-CONSTRUCTION DRIFT
  CS-T22  setup fired + score below threshold -> WAIT (threshold gates signal)
  CS-T23  H4 bull + FVG active + CHoCH earlier + M3 bull -> setup predicate
          TRUE per A; not an entity (state vs setup kept distinct)
  CS-T24  H4-only BUY: signal CONFORMING / setup N/A
  CS-T25  flat vote confirmed; HIERARCHICAL-TO-VOTING DRIFT recorded (D-1)
```

---

## 6. CONFIRMED FINDINGS (document-only)

```text
D-8  SETUP-SEMANTIC DIVERGENCE [HIGH] — two setup definitions (A fuzzy rule
     vs B legacy gate chain); not adjudicated (A-9).
D-9  SETUP-CONSTRUCTION DRIFT [HIGH] — BUY/SELL can fire with no setup;
     dashboard "TRADE SETUP" = aggregated signal (BUG-P3S8-001).
D-10 SETUP-IDENTITY GAP [HIGH] — no setup_id/onset/zone-link; per-bar
     repeated emission; no dedup (BUG-P3S8-002/-003).
D-11 E-VOTE SATURATION MASKS SETUP ABSENCE [MEDIUM] — E bias +/-1.0 with or
     without the setup leg (BUG-P3S8-002).
D-12 SEQUENCE FRESHNESS ABSENT IN ENGINE 2 [MEDIUM] — no SeqWindow for
     Engine 2; CHoCH state never expires (BUG-P3S8-004).
D-13 CONFLICT POLICY ABSENT AT SETUP LEVEL [MEDIUM] — arithmetic vs legacy
     gate-fail; carried from P3-S.7 D-2.
D-14 LEGACY GATE CHAIN NOT PORTED TO ENGINE 2 [INFORMATIONAL].
```

---

## 7. AMBIGUITIES

```text
A-5  Setup onset (A not defined)        A-6  Setup completion (A not defined)
A-7  Setup lifecycle (A not defined)    A-8  Cross-bar causal order (A none)
A-9  Canonical definition (A vs B)      A-10 Setup identity (needed or not)
```

---

## 8. NO PRODUCTION CHANGE

Only P3-S.8 artifacts added; 0 production files modified (verified:
AF_Engine1_MTFData / AF_Engine2_Agents / AF_Engine2_Aggregator /
AF_Engine2_Display / AF_Engine3_Render / f7-f18 / FVG / OB / CHoCH /
Displacement / ML / legacy v4.x : NOT touched).

## 9. NEXT GATE

P3-S.9 CROSS-PRIMITIVE CONSOLIDATED REPAIR / ARCHITECTURE REVIEW
(after reviewing the full P3-S.2..P3-S.8 evidence). STOP the semantic audit
chain. No ML, no retraining, no immediate repair.

## 10. ARTIFACTS

```text
docs/SMC_CANDIDATE_SETUP_SPEC_v1.md
docs/P3_S8_CANDIDATE_SETUP_CONFORMANCE.md
ml/p3/smc_semantic/spec_tests_candidate_setup.py
ml/p3/smc_semantic/spec_test_cases_candidate_setup.json
ml/p3/smc_semantic/output/spec_tests_candidate_setup_report.json
docs/SESSION_HANDOVER_2026-08-22_P3_S8_CANDIDATE_SETUP.md  (this document)
```

## 11. COMMIT & PUSH STATUS

```text
NOT YET COMMITTED at handover write time.
Planned message:
  research: P3-S.8 Candidate Setup formal spec + conformance audit (SPECIFICATION AMBIGUOUS)
```