forked from chiki2bum2/SniperGold_ML
275 lines
14 KiB
Markdown
275 lines
14 KiB
Markdown
 | # P3-S.6 DISPLACEMENT FORMAL SPECIFICATION & CODE-CONFORMANCE REPORT
| ||
| |||
```text
| |||
Date : 2026-08-22
| |||
Session : P3-S.6 — Formal SMC Specification + Code-Conformance Audit (Displacement)
| |||
Scope : Displacement — Engine 2 Entry agent (AF_DetectDisplacement),
| |||
and its relationships with Order Block "strong move" (AF_E3_MOVE_BODY),
| |||
FVG, CHoCH/MSS, and the E-agent confirmation chain.
| |||
Principle : SPECIFICATION FIRST, CODE AUDIT SECOND
| |||
Status : NO CODE CHANGES (Phase D) — all findings DOCUMENTED
| |||
Artifacts : docs/SMC_DISPLACEMENT_SPEC_v1.md (specification)
| |||
ml/p3/smc_semantic/spec_tests_displacement.py (+ .json) (tests)
| |||
ml/p3/smc_semantic/output/spec_tests_displacement_report.json
| |||
```
| |||
| |||
---
| |||
| |||
## 0. CHECKPOINT & PROVENANCE (session-start verification)
| |||
| |||
```text
| |||
Forge HEAD : 07883f6abf116b656e2cb8adfb41ec47e1fce498 (P3-S.5) VERIFIED
| |||
Branch / remote : main == origin/main (07883f6) VERIFIED
| |||
Working tree : CLEAN at start VERIFIED
| |||
P3-S.5 artifacts : spec/conformance/tests/report/handover INTACT VERIFIED
| |||
HUMAN VERIFICATION : CANCELLED VERIFIED
| |||
```
| |||
| |||
---
| |||
| |||
## A. SOURCE MATERIAL (Phase A — inventory & reconciliation)
| |||
| |||
| # | Source | Location | Role |
| |||
|---|--------|----------|------|
| |||
| 1 | Engine 2 displacement | Include\AlgoForge\AF_Engine2_Agents.mqh:281-291 (AF_DetectDisplacement) | body >= 1.6 x avg body on newest closed bar; direction Close vs Open; no structure |
| |||
| 2 | AF_AvgBody | AF_Engine2_Agents.mqh:120-127 | mean |Close-Open| over last n bars (baseline) |
| |||
| 3 | Engine 2 E agent | AF_Engine2_Agents.mqh:583-663 | disp = AF_DetectDisplacement(20); mDisp; wDisp 0.20 (x1.3); ZONE + CONFIRMATION |
| |||
| 4 | OB "strong move" | AF_Engine2_Agents.mqh:304-305; AF_Engine2_Display.mqh:212; AF_Defines.mqh:60 | |body(M)| >= 1.5 x avg (AF_E3_MOVE_BODY) — same family, lower constant |
| |||
| 5 | DESIGN.md | docs/DESIGN.md:132-133 | C "opposite bar before a strong move"; E "Sweep, CHoCH, displacement, OB/FVG zones; ZONE + CONFIRMATION = setup; strong displacement -> confirmation weight up" |
| |||
| 6 | FEATURE_CONTRACT | docs/FEATURE_CONTRACT.md | NO displacement feature (0 refs) |
| |||
| 7 | EA runtime | Experts\AlgoForge_Backtest_Baseline.mq5 | NO displacement (0 refs) |
| |||
| 8 | Python training | ml/**/*.py | NO displacement (0 refs) |
| |||
| 9 | Legacy v4.3/v4.4/v4.5 | Indicators\Downloads\SniperGold_SMC_ProPlus_v4_3/4_4/4_5.mq5 | NO displacement concept (0 refs) |
| |||
| 10 | P3-S.4/S.5/S.3 specs | docs/SMC_FVG/ORDER_BLOCK/CHOCH_MSS_SPEC_v1.md | displacement declared NOT REQUIRED for FVG/OB/CHoCH |
| |||
| 11 | External | XAUUSD_MTF_Liquidity_OB_Reversal (2).mq5 | external reference only, NOT wired |
| |||
| |||
**Layer separation:**
| |||
| |||
```text
| |||
Intended semantics : displacement = entry confirmation input (E agent);
| |||
"strong displacement -> confirmation weight up" (DESIGN).
| |||
Legacy semantics : NONE — v4.3/v4.4/v4.5 have no displacement concept.
| |||
Current semantics : body >= 1.6 x avg body (newest closed bar), direction by
| |||
Close vs Open, no structure, per-bar attribute.
| |||
Training semantics : N/A — not a training feature.
| |||
Display-only : NONE — displacement is not rendered.
| |||
```
| |||
| |||
---
| |||
| |||
## B. PROJECT SEMANTIC SPECIFICATION (Phase B)
| |||
| |||
Full document: **docs/SMC_DISPLACEMENT_SPEC_v1.md** (PROJECT SEMANTIC SPECIFICATION — not "universal SMC ground truth").
| |||
| |||
Spec decision summary:
| |||
| |||
```text
| |||
S-1 Definition : body >= 1.6 x avg body on the NEWEST CLOSED bar; direction
| |||
by Close vs Open; pure candle attribute.
| |||
S-2 Measurement : |Close-Open| vs average body; range/wicks/ATR/ratio NOT used.
| |||
S-3 Baseline : mean over newest min(20, t+1) bars; candidate included.
| |||
S-4 Direction : +1 Close>Open, -1 Close<Open, 0 otherwise; symmetric.
| |||
S-5 Structural req. : NONE.
| |||
S-6 FVG relationship: NOT REQUIRED (independent).
| |||
S-7 OB relationship : "strong move" (1.5 x) = same family, lower constant (proxy).
| |||
S-8 CHoCH rel. : NOT REQUIRED by CHoCH; independent.
| |||
S-9 Event vs State : CANDLE ATTRIBUTE (per-bar); no persistence; no stale state.
| |||
S-10 Threshold : >= 1.6 x avg (inclusive).
| |||
S-11 Symmetry : symmetric.
| |||
S-12 Timeframe : per-TF independent; canonical = SPECIFICATION AMBIGUOUS.
| |||
S-13 Consumers : E agent confirmation (w 0.20, x1.3); per-bar.
| |||
S-14 Parity : PARITY = N/A BY ABSENCE.
| |||
```
| |||
| |||
---
| |||
| |||
## C. FORMAL DEFINITION (Phase B — extract)
| |||
| |||
```text
| |||
avg_body(t) = (1 / min(20, t+1)) * SUM_{i=t-min(20,t+1)+1 .. t} |Close(i) - Open(i)|
| |||
| |||
Displacement(t) = +1 if |Close(t)-Open(t)| >= 1.6 * avg_body(t) AND Close(t) > Open(t)
| |||
-1 if |Close(t)-Open(t)| >= 1.6 * avg_body(t) AND Close(t) < Open(t)
| |||
0 otherwise.
| |||
| |||
Only the NEWEST closed bar (t) is evaluated. Pure candle attribute, no state.
| |||
```
| |||
| |||
---
| |||
| |||
## D. CURRENT CODE BEHAVIOR (Phase C — code audit)
| |||
| |||
```mql5
| |||
// AF_DetectDisplacement (AF_Engine2_Agents.mqh:281-291)
| |||
int AF_DetectDisplacement(const AFEngine1MTF &e1,int slot,int avgN)
| |||
{
| |||
if(!e1.IsReady(slot)) return 0;
| |||
double avg=AF_AvgBody(e1,slot,avgN); // mean |Close-Open| last min(avgN,count)
| |||
if(avg<=0.0) return 0;
| |||
double body=MathAbs(e1.Close(slot,0)-e1.Open(slot,0)); // NEWEST CLOSED bar
| |||
if(body<1.6*avg) return 0; // strict < -> inclusive >= at equality
| |||
return (e1.Close(slot,0)>e1.Open(slot,0))? 1 : -1;
| |||
}
| |||
// E agent consumption (AF_Engine2_Agents.mqh:606, 627-640, 659-660)
| |||
int disp = AF_DetectDisplacement(e1,slot,AF_E2_LOOKBACK_AVG); // avgN=20
| |||
if(MathAbs(disp)>0) wDisp*=1.3; // "strong displacement -> confirmation weight up"
| |||
mDispBull=(disp>0)?1.0:0.0; mDispBear=(disp<0)?1.0:0.0;
| |||
```
| |||
| |||
Observations:
| |||
- Formula matches S-1/S-2/S-3 exactly (avg includes the candidate bar; window
| |||
min(20,count); no min-bars guard — a short window still applies the rule).
| |||
- No structural check anywhere (S-5 CONFORMING).
| |||
- Per-bar, no state (S-9 CONFORMING — the E agent reads a fresh value each bar).
| |||
- Direction by Close vs Open (S-4 CONFORMING).
| |||
- Threshold 1.6 hardcoded (S-10 CONFORMING); boundary inclusive (>=).
| |||
| |||
---
| |||
| |||
## E. CONFORMANCE MATRIX (Phase C)
| |||
| |||
| # | Requirement | Specification | Code (Function/Line) | Actual Behavior | Verdict |
| |||
|---|-------------|--------------|----------------------|-----------------|---------|
| |||
| E-1 | Definition | body >= 1.6 x avg body, newest closed bar (S-1) | AF_DetectDisplacement:287-288 | exact match | **CONFORMING** |
| |||
| E-2 | Candle measurement | |Close-Open| vs avg body; range/wicks unused (S-2) | AF_DetectDisplacement:287 | body only | **CONFORMING** |
| |||
| E-3 | Baseline/lookback | mean over newest min(20,t+1), candidate included (S-3) | AF_AvgBody:120-127; call avgN=20 | match | **CONFORMING** |
| |||
| E-4 | Direction | +1 Close>Open / -1 Close<Open (S-4) | AF_DetectDisplacement:289 | match | **CONFORMING** |
| |||
| E-5 | Threshold | >= 1.6 x avg (inclusive) (S-10) | AF_DetectDisplacement:288 (strict < returns 0) | inclusive at equality | **CONFORMING** |
| |||
| E-6 | Structural req. | NONE (S-5) | no structure check in the function | match | **CONFORMING** |
| |||
| E-7 | FVG relationship | NOT REQUIRED (S-6) | FVG detector independent (P3-S.4) | no dependency either way | **CONFORMING** |
| |||
| E-8 | OB relationship | strong move = same family, lower constant (S-7) | AF_E3_MOVE_BODY=1.5 (OB) vs 1.6 (disp) | 1.5 vs 1.6 constants; undocumented split | **PARTIALLY CONFORMING** (BUG-P3S6-001) |
| |||
| E-9 | CHoCH relationship | NOT REQUIRED (S-8) | CHoCH close-confirmed, no displacement (P3-S.3) | independent | **CONFORMING** |
| |||
| E-10 | Timing | newest closed bar; close-observable (S-9/S-10) | index 0 under Engine-1 closed-bar lock | no 1-bar lag; no look-ahead | **CONFORMING** |
| |||
| E-11 | Closed-bar / no future | all inputs <= t (S-3) | closed-bar lock; DP-T19 | no future visibility | **CONFORMING** |
| |||
| E-12 | Lifecycle | candle attribute, no persistence (S-9) | per-bar recompute; no state variable | no stale state (DP-T18) | **CONFORMING** |
| |||
| E-13 | Timeframe | per-TF independent; canonical AMBIGUOUS (S-12) | per-slot AF_DetectDisplacement | per-TF; cross-TF role undefined | **SPECIFICATION AMBIGUOUS** (A-1) |
| |||
| E-14 | Consumer behavior | E agent per-bar confirmation (S-13) | AF_Engine2_Agents:606,627-640 | fresh value each bar; no stale consumer | **CONFORMING** |
| |||
| E-15 | Runtime/training parity | PARITY = N/A (S-14) | FEATURE_CONTRACT/EA/Python/v4.x: 0 refs | absent everywhere except Engine 2 | **CONFORMING** (N/A by absence) |
| |||
| |||
---
| |||
| |||
## F. CONFIRMED BUGS (Phase D — DOCUMENT ONLY, no code changes)
| |||
| |||
```text
| |||
BUG-P3S6-001
| |||
SEVERITY : LOW (cross-concept consistency)
| |||
SOURCE : AF_E3_MOVE_BODY=1.5 (AF_Defines.mqh:60, OB strong move) vs the
| |||
hardcoded 1.6 in AF_DetectDisplacement (AF_Engine2_Agents.mqh:288)
| |||
SPEC REQ : S-7/A-2 — the "strong move" family must have ONE documented rule
| |||
ACTUAL CODE : OB "strong move" = body >= 1.5 x avg; Displacement = body >= 1.6 x
| |||
avg; same measurement, same family, different constants; a body
| |||
in [1.5, 1.6) x avg is "strong" for OB but NOT displacement
| |||
IMPACT : a candle can satisfy the OB formation gate while the E-agent
| |||
reports no displacement (and vice versa is impossible);
| |||
DESIGN.md uses "strong move" and "displacement" loosely; the
| |||
threshold split is undocumented
| |||
PROPOSED FIX : unify the constant or document the intentional split (no repair
| |||
this session; consolidated repairs deferred until the audit
| |||
chain completes)
| |||
```
| |||
| |||
No consumer/stale-state bug exists for displacement (E-12/E-14 CONFORMING): the
| |||
f7/CHoCH/FVG/OB consumer bug class does NOT apply — displacement is a per-bar
| |||
candle attribute with no state to go stale (verified DP-T18).
| |||
| |||
---
| |||
| |||
## G. SEMANTIC AMBIGUITIES
| |||
| |||
```text
| |||
G-1 Canonical displacement timeframe (A-1): per-slot computation explicit;
| |||
cross-TF influence rule not defined. Same class as CHoCH G-4 / sweep G-3 /
| |||
FVG A-3 / OB A-4.
| |||
G-2 "Strong move" vs "Displacement" terminology (A-2 / BUG-P3S6-001):
| |||
1.5 vs 1.6 constants for one concept family; not adjudicated.
| |||
```
| |||
| |||
---
| |||
| |||
## H. CROSS-CONCEPT CONSISTENCY (Phase C — diagnostic, per brief §27)
| |||
| |||
| Concept | Requires Displacement? | Produces Displacement? | Uses "strong move"? |
| |||
|---------|------------------------|------------------------|---------------------|
| |||
| FVG (P3-S.4) | No (geometric gap, S-5) | No (may correlate) | No |
| |||
| OB (P3-S.5) | No (own strong-move gate 1.5 x) | No | **Yes (1.5 x avg body)** |
| |||
| CHoCH/MSS (P3-S.3) | No (close-confirmed break, S-6) | No | No |
| |||
| Displacement (P3-S.6) | — | — | = the concept (1.6 x avg body) |
| |||
| |||
```text
| |||
CROSS-CONCEPT INCONSISTENCY (documented, NOT modified this session):
| |||
OB uses "strong move" = 1.5 x avg body (AF_E3_MOVE_BODY);
| |||
Displacement uses 1.6 x avg body (AF_DetectDisplacement).
| |||
Same concept family, different constants -> BUG-P3S6-001.
| |||
No prior specification is changed; the inconsistency is recorded for the
| |||
consolidated repair phase.
| |||
```
| |||
| |||
---
| |||
| |||
## I. RUNTIME/TRAINING PARITY (Phase C — diagnostic, not a retrain)
| |||
| |||
```text
| |||
Displacement is not in FEATURE_CONTRACT (f0-f18), the EA runtime, or Python
| |||
training (verified: 0 references each; legacy v4.x also has none).
| |||
-> PARITY = N/A BY ABSENCE (S-14). No mismatch exists; absence is documented.
| |||
```
| |||
| |||
---
| |||
| |||
## J. VERDICT
| |||
| |||
```text
| |||
CONFORMING
| |||
| |||
Definition (E-1) : CONFORMING
| |||
Measurement (E-2) : CONFORMING
| |||
Baseline/lookback (E-3) : CONFORMING
| |||
Threshold (E-5) : CONFORMING
| |||
Timing (E-10, E-11) : CONFORMING
| |||
Lifecycle (E-12) : CONFORMING (candle attribute, no stale state)
| |||
Structure relationship (E-6) : CONFORMING (none required)
| |||
FVG relationship (E-7) : CONFORMING (independent)
| |||
OB relationship (E-8) : PARTIALLY CONFORMING (BUG-P3S6-001)
| |||
CHoCH relationship (E-9) : CONFORMING (independent)
| |||
Consumer behavior (E-14) : CONFORMING (per-bar, no stale consumer)
| |||
Timeframe (E-13) : SPECIFICATION AMBIGUOUS (A-1)
| |||
Runtime/training parity (E-15) : CONFORMING (N/A by absence)
| |||
| |||
The displacement primitive itself is CONFORMING: AF_DetectDisplacement matches
| |||
the project specification exactly (body >= 1.6 x avg body, newest closed bar,
| |||
direction by Close/Open, no structure, per-bar attribute, no look-ahead). The
| |||
only finding is a cross-concept threshold inconsistency (OB "strong move" 1.5 vs
| |||
displacement 1.6) and the usual canonical-timeframe ambiguity. The f7/CHoCH/FVG/
| |||
OB stale-consumer bug class does NOT apply to displacement.
| |||
| |||
Verdict = conformance to the PROJECT SEMANTIC SPECIFICATION, NOT profitability/edge.
| |||
```
| |||
| |||
---
| |||
| |||
## K. NEXT GATE
| |||
| |||
```text
| |||
After the Displacement verdict (CONFORMING):
| |||
MTF Alignment -> Candidate Setup.
| |||
DO NOT return to ML; DO NOT create new event labels; DO NOT perform consolidated
| |||
repairs yet (BUG-P3S6-001 and the P3-S.2..P3-S.5 documented findings stay open
| |||
until the semantic audit chain completes).
| |||
```
| |||
| |||
---
| |||
| |||
## L. CHECKPOINT & PROVENANCE (P3-S.6)
| |||
| |||
```text
| |||
Forge HEAD (session start) : 07883f6 (P3-S.5) — VERIFIED
| |||
P3-S.5 spec (immutable) : docs/SMC_ORDER_BLOCK_SPEC_v1.md
| |||
P3-S.4 spec (immutable) : docs/SMC_FVG_SPEC_v1.md
| |||
P3-S.3 spec (immutable) : docs/SMC_CHOCH_MSS_SPEC_v1.md
| |||
FEATURE_CONTRACT : C44CC6F2... (P2-era) / 7b908b12... (committed)
| |||
symbol/tf : XAUUSD / M15 (2017-01-01 .. 2026-08-20)
| |||
Human verification : CANCELLED
| |||
No production change : AF_DetectDisplacement / AF_AvgBody / AF_FindOrderBlock /
| |||
E agent / Engine 2 / Engine 3 / f7-f18 / FVG / OB /
| |||
CHoCH / ML : NOT touched
| |||
```
|