Document Gate Target Ladder architecture

docs/research/sr-levels-and-exits.md

@@ -4,10 +4,14 @@
 **Question that started it:** are our support/resistance levels built the way best
 practice says they should be, and do we actually use them that way?
 
-Short answer: the detector is weak against best practice, but its reach into P&L
-runs entirely through the **entry gate** — not the exit. Honoring the target as a
-take-profit was tested and is decisively worse. Whether the S/R-derived gate is
-net-positive is the open question, tracked below.
+Final answer: one level model should not serve two different jobs. The clean
+**Structural S/R** detector now supplies persisted chart and alert structure.
+The transient **Gate Target Ladder** preserves the broad historical-price
+traffic proposals that the setup screen depends on. Its headline target affects
+entry qualification only; honoring it as a take-profit is decisively worse.
+The final volume-free implementation reproduced the production candidate set
+and portfolio exactly. The sections below retain the investigation that led to
+that split.
 
 ---
 
@@ -690,6 +694,58 @@ and LVN bins, whose union is the complete 20-bin price-range grid, then adds
 unfiltered pivots and touch strength. For the gate this behaves as a broad
 target-proposal ladder, not human-facing support/resistance.
 
+**Component name: Gate Target Ladder (GTL).** "Structural S/R" names the
+separate, persisted human-facing model. "Gate Target Ladder" names this
+transient screening component and avoids implying that its dense proposals are
+real support/resistance.
+
+#### Runtime decision flow
+
+```mermaid
+flowchart TD
+    O["Ticker OHLCV history"] --> STRUCT["Structural S/R<br/>clean detector"]
+    STRUCT --> STORE[("Persist SRLevel")]
+    STORE --> HUMAN["Charts and alerts"]
+
+    O --> LADDER["Gate Target Ladder<br/>20 range centers + 5-bar pivots"]
+    LADDER --> SCORE["Count historical price traffic<br/>strength + 0.5% merge + side tag"]
+    SCORE --> SCAN{"Directional proposal<br/>with R:R ≥ 1.5?"}
+    SCAN -->|no| NOSETUP["No setup for that direction"]
+    SCAN -->|yes| ZONES["Cluster 2% target zones<br/>use reachable near edge"]
+    ZONES --> FILTER["ATR-distance filter<br/>retain up to 5 near-to-far candidates"]
+    FILTER --> PROB["Estimate target-before-stop<br/>reach probability"]
+    PROB --> PRIMARY["Headline = most likely candidate<br/>clearing R:R ≥ 1.5 and probability ≥ 20%"]
+    PRIMARY --> ACTIVATE{"Activation gate<br/>headline R:R ≥ 2.0<br/>probability ≥ 20%<br/>momentum/direction pass?"}
+    ACTIVATE -->|no| OBS["Store as unqualified observation"]
+    ACTIVATE -->|yes| QUAL["Eligible for production book"]
+    QUAL --> EXIT["ATR stop/trail or max hold<br/>target is never an exit"]
+```
+
+Step by step:
+
+1. `scan_ticker` loads the ticker's OHLCV history and computes the 1.5× ATR
+   initial stop. It does not query persisted `SRLevel` rows for targets.
+2. `detect_gate_target_ladder` creates 20 evenly spaced centers over the
+   observed low/high range and adds unfiltered five-bar swing highs/lows. The
+   implementation performs no volume calculation.
+3. Each proposal is scored by the share of historical bars whose range crosses
+   it. Proposals within 0.5% are merged, their traffic strengths combine, and
+   they are tagged support/resistance relative to the latest close. The scanner
+   materializes them with negative transient IDs; they are never persisted.
+4. A direction exists only when at least one proposal clears the scanner's 1.5
+   R:R floor. This is setup construction, not the later live activation gate.
+5. The recommendation layer clusters proposals into 2% target zones, uses each
+   zone's reachable near edge, removes unsuitable ATR distances, and keeps up
+   to five candidates spanning near, moderate and far distances.
+6. Each retained candidate gets a target-before-stop reach probability based on
+   distance, R:R, traffic strength and signal alignment.
+7. The headline target is the most likely candidate clearing both R:R ≥ 1.5
+   and probability ≥ 20%. If none does, the most likely target overall remains
+   headline so a distant high-R:R lottery target cannot game qualification.
+8. The separate live gate then requires headline R:R ≥ 2.0 and probability ≥
+   20%, plus the residual-momentum and direction rules. A traded setup still
+   exits only through the ATR stop/trail or maximum hold.
+
 The `explicit_target_ladder` arm therefore replaces only the irrelevant volume
 pass with the complete range grid. It retains pivots, touch strength, merge
 geometry, primary selection, qualification, ranking, and exit behavior. Grid