Stage 07.4.3.9 — Position flip flow

docs/stages/07_4_3_9_position_flip_flow.md

@@ -0,0 +1,90 @@
+# Stage 07.4.3.9 --- Position Flip Flow
+
+## Overview
+
+This stage introduces **position flip logic** into the execution engine.
+
+Instead of: - CLOSE → WAIT → OPEN
+
+We now support: - **FLIP (instant reversal)**
+
+------------------------------------------------------------------------
+
+## Behavior
+
+### Before
+
+-   LONG + SELL → CLOSE
+-   Next cycle → OPEN SHORT
+
+### Now
+
+-   LONG + SELL → **FLIP → SHORT (same cycle)**
+-   SHORT + BUY → **FLIP → LONG (same cycle)**
+
+------------------------------------------------------------------------
+
+## Execution Types
+
+  Type    Description
+  ------- -------------------------------------------------
+  ENTRY   Opening new position
+  EXIT    Closing position
+  FLIP    Closing + opening opposite position in one step
+
+------------------------------------------------------------------------
+
+## EventBus Events
+
+### New event
+
+-   `paper_position_flipped`
+
+Payload includes: - old_side - new_side - entry_price - exit_price -
+new_entry_price - pnl - sizes and leverage
+
+------------------------------------------------------------------------
+
+## Telegram Alerts
+
+### Flip alert
+
+Example:
+
+🔁 Paper position flipped 🟢 LONG → 🔴 SHORT
+
+Includes: - old entry - exit - new entry - pnl
+
+------------------------------------------------------------------------
+
+## Benefits
+
+-   Faster reaction to signals
+-   No idle state between positions
+-   Cleaner execution logic
+-   More realistic trading simulation
+
+------------------------------------------------------------------------
+
+## Testing
+
+    /debug_signal BUY 0.95 3
+    /debug_signal SELL 0.95 3
+    /debug_signal BUY 0.95 3
+
+Expected: - ENTRY - FLIP - FLIP
+
+------------------------------------------------------------------------
+
+## Notes
+
+-   Flip happens only when:
+    -   position exists
+    -   opposite signal is READY
+-   Execution remains **paper-only**
+
+------------------------------------------------------------------------
+
+## Next Stage
+
+07.4.3.10 --- Risk & Position Control