# Limit Order Entry Workflow

**Version**: v1.0.0  
**Created**: 2026-04-13  
**Project**: 20260413_TWM_entry_optimization  
**Author**: AI-generated  

---

## Overview

This document describes the progressive limit order entry mechanism implemented in state `long_06_WAIT_BREAKOUT`. Instead of immediately entering at the breakout price via market order, the strategy issues a limit order below the breakout price. The offset steps down over time until it reaches zero, at which point a market order is issued.

This behaviour is controlled by the `BREAKOUT_LIMIT_ENTRY_isActive` flag in `config_5_strategy_v1_5_0.json` and parameterised by `entry_limit_config` in `config_7_limit_order_v1_0_0.json`.

---

## Key Variables

| Variable | Type | Description |
|---|---|---|
| `entry_timer` | int | Counts bars where price ≥ breakout level. Reset to 0 on fill or cancellation. |
| `entry_offset` | float | Current offset below breakout price at which the limit order is placed. Derived from `entry_timer` and `entry_limit_config`. |
| `breakout_price` | float | Recorded when the breakout retest is confirmed (already set before entering long_06). |

---

## Configuration Parameters (`config_7_limit_order_v1_0_0.json`)

| Parameter | Value | Description |
|---|---|---|
| `increment` | 5 | Number of bars before stepping down to the next offset level. |
| ES levels | 2.5, 2.0, 1.5, 1.0, 0.5, 0 | Offset in points for each of the 6 levels. |
| NQ levels | 7.5, 6.0, 4.5, 3.0, 1.5, 0 | Offset in points for each of the 6 levels. |

**Thresholds (derived from increment = 5):**

| Level | `entry_timer` range | Offset (@ES) | Offset (@NQ) |
|---|---|---|---|
| level_1 | 0 – 4 | 2.5 pts | 7.5 pts |
| level_2 | 5 – 9 | 2.0 pts | 6.0 pts |
| level_3 | 10 – 14 | 1.5 pts | 4.5 pts |
| level_4 | 15 – 19 | 1.0 pts | 3.0 pts |
| level_5 | 20 – 24 | 0.5 pts | 1.5 pts |
| level_6 | ≥ 25 | 0 → **market order** | 0 → **market order** |

---

## Transition Guards (`config_5_strategy_v1_5_0.json`)

| Flag | Default | Purpose |
|---|---|---|
| `BREAKOUT_LEVEL_HIT_isActive` | `true` | When `true`, fires the original market-at-breakout transition as soon as price ≥ breakout level. |
| `BREAKOUT_LIMIT_ENTRY_isActive` | `false` | When `true`, fires the progressive limit order logic described in this document. |

**Mutual exclusion rule**: only one flag should be `true` at a time. If both are `true`, `BREAKOUT_LEVEL_HIT` takes priority and the limit order logic is bypassed.

---

## Per-Bar Logic in `long_06_WAIT_BREAKOUT`

Both transition conditions are always calculated on every bar, regardless of the `_isActive` flags.

```
Each bar while in long_06_WAIT_BREAKOUT:

1. Evaluate BREAKOUT_LEVEL_HIT condition:
   - condition_met = (current_price >= breakout_price)

2. Evaluate BREAKOUT_LIMIT_ENTRY condition:
   a. If current_price >= breakout_price:
      - Increment entry_timer by 1
      - Look up entry_offset from entry_limit_config based on entry_timer
      - If entry_offset > 0:
          - Issue (or re-issue) limit order at: limit_price = breakout_price - entry_offset
          - condition_met = False (waiting for limit to fill)
      - If entry_offset == 0:
          - condition_met = True  →  issue market order
   b. If current_price < breakout_price:
      - Reset entry_timer to 0
      - Cancel any outstanding limit order
      - condition_met = False

3. Fire transitions:
   - If BREAKOUT_LEVEL_HIT_isActive == True AND condition_BREAKOUT_LEVEL_HIT:
       → transition to long_07 (market order at breakout price)
       → reset entry_timer = 0
   - Elif BREAKOUT_LIMIT_ENTRY_isActive == True AND condition_BREAKOUT_LIMIT_ENTRY:
       → transition to long_07 (limit or market order filled)
       → reset entry_timer = 0
```

---

## Reset Conditions for `entry_timer`

| Event | Action |
|---|---|
| Trade fill (entry confirmed) | `entry_timer = 0` |
| Cancellation (price drops below breakout level) | `entry_timer = 0` |
| Transition fires for any reason | `entry_timer = 0` |

---

## Relationship to `BREAKOUT_LEVEL_HIT` Transition

The original `BREAKOUT_LEVEL_HIT` transition (market order at breakout price) is preserved unchanged as transition `t_100_breakout_level_hit_isActive`. The new `BREAKOUT_LIMIT_ENTRY_isActive` flag is additive — it enables an alternative entry path. Both are disabled/enabled from config, and only one should be active at a time.

---

## Change Log

| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2026-04-13 | 20260413_TWM_entry_optimization: Initial creation. Documents progressive limit order entry logic for long_06_WAIT_BREAKOUT. |