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
|
||
|
|
```
|