V3_Integration_Execution_Plan.txt

================================================================================
NQ BOT v3 — INSTITUTIONAL MODIFIER INTEGRATION EXECUTION PLAN
================================================================================
Date: March 3, 2026
Source: v3 Knowledge Base deep research session + strategic discussion
Purpose: Master build checklist for Claude Code execution tonight
================================================================================

ARCHITECTURE OVERVIEW
================================================================================

THREE-LAYER SYSTEM:

  Layer 1: HTF Gate (Gatekeeper) — UNCHANGED
    - Multi-timeframe consensus: 1D, 4H, 1H, 30m, 15m, 5m
    - Output: APPROVED or REJECTED
    - No modifications to existing logic

  Layer 2: Confluence Scoring (Signal Strength) — UNCHANGED FOR NOW
    - Price action: order blocks, FVGs, liquidity sweeps
    - Output: score 0-100
    - Future enhancement: depth-weighted OFI scoring (Phase 3)

  Layer 3: Institutional Modifiers (NEW) — TONIGHT'S FOCUS
    - Takes approved signals and scales position size, stop width, runner behavior
    - Modifiers NEVER veto — they amplify or dampen
    - Each modifier is independent and independently testable
    - Applied sequentially as multipliers

  Final Position Size = base_size × overnight_mod × fomc_mod × gamma_mod × vol_mod
  Final Stop Width   = base_stop × overnight_mod × fomc_mod × gamma_mod × vol_mod

================================================================================
PHASE 1: OVERNIGHT BIAS MODULE (Priority: BUILD TONIGHT)
================================================================================
Estimated build time: ~30 minutes
Research source: Lou, Polk & Skouras (2019), JFE
                 Boyarchenko, Larsen & Whelan (2023), NY Fed

CONCEPT:
  Overnight returns are driven by dealer inventory management.
  When dealers accumulate risk during US close, they offload when
  European markets open. This creates a DISTINCT directional bias
  overnight vs. intraday. Alignment = high conviction. Conflict =
  reduce size or stand aside.

DATA INPUTS:
  - Previous day close price (4:00 PM ET)
  - Current day open price (9:30 AM ET)
  - Current HTF directional bias (BULLISH / BEARISH / NEUTRAL)

CALCULATION:
  overnight_bias_bps = ((open_today - close_yesterday) / close_yesterday) * 10000
  overnight_direction = BULLISH if overnight_bias_bps > 0 else BEARISH

THRESHOLDS (from research):
  - Normal overnight move: 15-30 bps (noise — no modifier)
  - Significant move: > 50 bps (material dealer flow — apply modifier)
  - Extreme move: > 120 bps (acute inventory pressure — strong modifier)

MODIFIER MULTIPLIERS:
  ┌─────────────────────────┬──────────────┬────────────────┬───────────────┐
  │ Condition               │ Position Size│ Stop Width     │ Runner Width  │
  ├─────────────────────────┼──────────────┼────────────────┼───────────────┤
  │ Alignment + Significant │ 1.4x         │ 1.0x (normal)  │ 1.2x (wider)  │
  │ Alignment + Extreme     │ 1.5x         │ 1.0x           │ 1.3x          │
  │ Conflict + Significant  │ 0.6x         │ 0.8x (tighter) │ 0.8x          │
  │ Conflict + Extreme      │ 0.4x         │ 0.7x           │ 0.7x          │
  │ Neutral (< 50 bps)      │ 1.0x         │ 1.0x           │ 1.0x          │
  └─────────────────────────┴──────────────┴────────────────┴───────────────┘

PSEUDOCODE:
  def calculate_overnight_modifier(close_prev, open_today, htf_bias):
      overnight_bps = ((open_today - close_prev) / close_prev) * 10000
      overnight_dir = "BULLISH" if overnight_bps > 0 else "BEARISH"
      magnitude = abs(overnight_bps)

      if magnitude < 50:
          return {"position": 1.0, "stop": 1.0, "runner": 1.0, "reason": "NEUTRAL"}

      aligned = (overnight_dir == htf_bias)
      extreme = magnitude > 120

      if aligned and extreme:
          return {"position": 1.5, "stop": 1.0, "runner": 1.3, "reason": "ALIGN_EXTREME"}
      elif aligned:
          return {"position": 1.4, "stop": 1.0, "runner": 1.2, "reason": "ALIGN_SIGNIFICANT"}
      elif not aligned and extreme:
          return {"position": 0.4, "stop": 0.7, "runner": 0.7, "reason": "CONFLICT_EXTREME"}
      else:
          return {"position": 0.6, "stop": 0.8, "runner": 0.8, "reason": "CONFLICT_SIGNIFICANT"}

FILE LOCATION: nq_bot_vscode/signals/institutional_modifiers.py
CLASS: OvernightBiasModifier

LOGGING:
  Every modifier calculation logs to institutional_modifiers_log.json:
    timestamp, close_prev, open_today, overnight_bps, overnight_dir,
    htf_bias, alignment, modifier_applied, reason

================================================================================
PHASE 1B: PRE-FOMC DRIFT MODULE (Priority: BUILD TONIGHT)
================================================================================
Estimated build time: ~20 minutes
Research source: Lucca & Moench (2015), Journal of Finance
                 Kurov et al. (2021) — post-2015 weakening

CONCEPT:
  49 bps average drift in 24 hours before FOMC announcements.
  Accounts for ~80% of annual equity premium. Holds regardless
  of policy decision direction. Drift strongest in final 4 hours.
  Weakened post-2015 but mechanism persists.

DATA INPUTS:
  - FOMC meeting schedule (dates + times, typically 2:00 PM ET)
  - Current datetime
  - Calculated: hours until next FOMC announcement

FOMC 2026 SCHEDULE (to be verified/updated):
  Jan 28-29, Mar 18-19, May 6-7, Jun 17-18,
  Jul 29-30, Sep 16-17, Nov 4-5, Dec 16-17

THRESHOLDS (from research):
  - 24-4 hours before: mild drift active
  - 4-0.5 hours before: drift intensifies (strongest window)
  - < 0.5 hours before: STAND ASIDE (announcement vol dominates)

MODIFIER MULTIPLIERS:
  ┌───────────────────────────┬──────────────┬────────────────┐
  │ Window                    │ Position Size│ Stop Width     │
  ├───────────────────────────┼──────────────┼────────────────┤
  │ 24-4 hours before FOMC    │ 1.1x         │ 0.9x (tighter) │
  │ 4-0.5 hours before FOMC   │ 1.15x        │ 0.85x          │
  │ < 0.5 hours before FOMC   │ 0.0x (BLOCK) │ N/A            │
  │ No FOMC within 24 hours   │ 1.0x         │ 1.0x           │
  └───────────────────────────┴──────────────┴────────────────┘

PSEUDOCODE:
  def calculate_fomc_modifier(current_datetime, fomc_schedule):
      next_fomc = get_next_fomc(current_datetime, fomc_schedule)
      hours_until = (next_fomc - current_datetime).total_seconds() / 3600

      if hours_until > 24:
          return {"position": 1.0, "stop": 1.0, "stand_aside": False}
      elif hours_until <= 0.5:
          return {"position": 0.0, "stop": 1.0, "stand_aside": True,
                  "reason": "FOMC_IMMINENT"}
      elif hours_until <= 4:
          return {"position": 1.15, "stop": 0.85, "stand_aside": False,
                  "reason": "FOMC_DRIFT_STRONG"}
      else:
          return {"position": 1.1, "stop": 0.9, "stand_aside": False,
                  "reason": "FOMC_DRIFT_MILD"}

FILE LOCATION: nq_bot_vscode/signals/institutional_modifiers.py
CLASS: FOMCDriftModifier

================================================================================
PHASE 2: GAMMA REGIME MODULE (Priority: NEXT SESSION)
================================================================================
Estimated build time: ~45 minutes
Research source: Baltussen, Da, Lammers & Martens (2021), JFE
                 CBOE Research (2023)

CONCEPT:
  Dealer gamma exposure determines whether market amplifies or
  dampens moves. Negative gamma = momentum accelerates (size up).
  Positive gamma = mean-reversion dominates (size down).
  Effect is NON-LINEAR: top 25% gamma days see Sharpe nearly double.

DATA SOURCE (until Phase 4 GEX feed):
  VIX term structure slope as proxy
  - Steep contango → positive gamma (calm, dampening)
  - Backwardation → negative gamma (stress, amplification)

THREE-TIER WEIGHTING SYSTEM:

  Tier 1 — Gamma Regime Baseline:
    Positive gamma: 0.7x position multiplier
    Negative gamma: 1.3x position multiplier

  Tier 2 — VIX Amplification:
    VIX > 20 AND negative gamma: multiply Tier 1 by 1.2x
    VIX < 12: reduce to 0.9x (gamma effects weaker in calm markets)

  Tier 3 — Timeframe Priority:
    Opening Drive (9:30-10:00) and IB Break (10:00-10:30):
      Apply full gamma multiplier (research shows strongest effect here)
    Rest of Day (after 14:00):
      Apply 0.5x of gamma multiplier (less gamma-sensitive)

DATA INPUTS:
  - VIX spot price
  - VIX front-month futures price
  - VIX second-month futures price
  - VIX term structure slope = (VX2 - VX1) / VX1
  - Current time of day

THRESHOLDS:
  - Slope > 5%: Strong positive gamma → 0.7x
  - Slope 0-5%: Weak positive gamma → 0.85x
  - Slope -5% to 0%: Weak negative gamma → 1.15x
  - Slope < -5%: Strong negative gamma → 1.3x

FILE LOCATION: nq_bot_vscode/signals/institutional_modifiers.py
CLASS: GammaRegimeModifier

================================================================================
PHASE 2B: HAR-RV VOLATILITY FORECASTING (Priority: NEXT SESSION)
================================================================================
Estimated build time: ~45 minutes
Research source: Corsi (2009), J. Econometrics
                 Andersen, Bollerslev & Diebold (2007)

CONCEPT:
  Simple but powerful volatility forecasting model using three
  components: daily, weekly (5-day), monthly (22-day) realized
  volatility. Competitive with LSTM and GARCH.

MODEL:
  RV(t+1) = α + β_d × RV_daily(t) + β_w × RV_weekly(t) + β_m × RV_monthly(t) + ε

  Where:
    RV_daily = sum of squared 5-minute returns (current day)
    RV_weekly = average of RV_daily over last 5 days
    RV_monthly = average of RV_daily over last 22 days

SYSTEM USE:
  - Dynamic stop loss scaling (high forecast vol → wider stops)
  - Position sizing adjustment (high vol → smaller size)
  - C2 runner trail width (high vol → wider trail to avoid premature stops)
  - Regime classification input

SAMPLING: 5-minute intervals (optimal per Andersen et al. 2003)

FILE LOCATION: nq_bot_vscode/signals/volatility_forecast.py
CLASS: HARRVForecaster

================================================================================
PHASE 3: ORDER BOOK DEPTH & OFI (Priority: AFTER IBKR LIVE)
================================================================================
Estimated build time: ~2-3 hours (requires IBKR connectivity)
Research source: Cont, Kukanov & Stoikov (2014), Rev. Financial Studies
                 Bouchaud, Farmer & Lillo (2009)

MODULES TO BUILD:

  1. IBKR WebSocket Level 2 Depth Extractor
     - Subscribe to MNQ market depth via Client Portal Gateway
     - Stream real-time bid/ask ladder (top 10-20 levels)
     - Store snapshots at signal events

  2. Depth Metrics Calculator
     - Aggregate depth: total volume within 5 ticks of mid
     - Depth ratio: bid-side volume / ask-side volume
     - Depth velocity: rate of depth change over last N snapshots

  3. OFI Calculator
     - OFI = (bid volume changes) - (ask volume changes) per 5-min bar
     - Rolling OFI autocorrelation (detect institutional persistence)
     - Beta estimator: regression of ΔPrice on OFI magnitude

  4. Intraday OFI Persistence Detector
     - Measure OFI direction across consecutive 5-min bars
     - Flag when 3-4 consecutive bars show same-direction OFI
     - Threshold: autocorrelation > 0.3 suggests institutional flow

  5. Liquidity Sweep Follow-Through Validator
     - After sweep signal: does next 1-3 bars show continued OFI?
     - If yes: raise confluence confidence
     - If no: reduce position size (sweep was noise)

  6. Time-of-Day Institutional Seasonality Filter
     - Opening (9:30-10:30 ET): weight entries higher
     - Midday (10:30-14:00 ET): standard weighting
     - Closing (14:00-16:00 ET): weight entries higher

FILE LOCATIONS:
  nq_bot_vscode/broker/ibkr_depth.py
  nq_bot_vscode/signals/ofi_calculator.py
  nq_bot_vscode/signals/depth_metrics.py

================================================================================
PHASE 4: ADVANCED POLISH
================================================================================

  - Jump detection via bipower variation (Andersen et al. 2007)
  - TSMOM 12-month trend filter (Moskowitz et al. 2012)
  - Session-specific volatility scaling (Open/Midday/Close)
  - Real-time GEX feed integration (replace VIX proxy)
  - CPCV validation framework implementation
  - Deflated Sharpe Ratio testing module

================================================================================
POSTGRESQL SCHEMA ADDITIONS
================================================================================

CREATE TABLE institutional_modifiers_state (
    timestamp       TIMESTAMPTZ NOT NULL,
    overnight_bps   DECIMAL(8,2),
    overnight_dir   VARCHAR(10),
    fomc_hours      DECIMAL(6,2),
    fomc_active     BOOLEAN,
    gamma_regime    VARCHAR(15),
    gamma_slope     DECIMAL(6,4),
    vix_spot        DECIMAL(6,2),
    har_rv_forecast DECIMAL(10,6),
    pos_multiplier  DECIMAL(4,2),
    stop_multiplier DECIMAL(4,2),
    runner_mult     DECIMAL(4,2)
);

CREATE TABLE execution_decisions (
    timestamp           TIMESTAMPTZ NOT NULL,
    signal_id           UUID,
    htf_gate_result     VARCHAR(10),
    confluence_score    INTEGER,
    overnight_mult      DECIMAL(4,2),
    fomc_mult           DECIMAL(4,2),
    gamma_mult          DECIMAL(4,2),
    vol_mult            DECIMAL(4,2),
    final_position_size DECIMAL(8,2),
    final_stop_width    DECIMAL(8,4),
    execution_status    VARCHAR(20),
    actual_pnl          DECIMAL(10,2)
);

================================================================================
INTEGRATION WORKFLOW (process_bar enhancement)
================================================================================

Current flow:
  1. HTF Gate → APPROVED/REJECTED
  2. Confluence Score → 0-100
  3. IF score >= threshold → EXECUTE at base size

Enhanced flow:
  1. HTF Gate → APPROVED/REJECTED (unchanged)
  2. Confluence Score → 0-100 (unchanged)
  3. IF score >= threshold:
     a. Calculate overnight modifier
     b. Calculate FOMC modifier
     c. Calculate gamma modifier (Phase 2)
     d. Calculate volatility modifier (Phase 2)
     e. IF any modifier returns STAND_ASIDE → BLOCK
     f. final_size = base × overnight × fomc × gamma × vol
     g. final_stop = base_stop × overnight × fomc × gamma × vol
     h. EXECUTE with final_size and final_stop

KEY PRINCIPLE: Modifiers are MULTIPLIED sequentially.
  Example: overnight=1.4 × fomc=1.1 × gamma=1.3 = 2.0x total
  CAP: Maximum total multiplier = 2.0x (safety rail)
  FLOOR: Minimum total multiplier = 0.3x (always some skin in game)

================================================================================
RESEARCH VALIDATION NOTES
================================================================================

Why these specific thresholds:

  Overnight 50 bps minimum:
    Lou et al. (2019) show normal overnight premiums 15-30 bps.
    50 bps is ~2x normal — statistically significant dealer flow.

  FOMC 24-hour window:
    Lucca & Moench (2015) measured drift over full 24 hours.
    Strongest in final 4 hours before announcement.
    Post-2015 weakening (Kurov 2021) → conservative multipliers.

  Gamma top-25% threshold:
    Baltussen et al. (2021) found Sharpe nearly doubled (0.87→1.73)
    on high negative gamma days. Effect is non-linear — small gamma
    changes don't matter, but extreme positioning does.

  HAR-RV 5-minute sampling:
    Andersen et al. (2003) established 5-minute as optimal.
    Finer = microstructure noise. Coarser = information loss.

  Quarter Kelly position sizing:
    Thorp (2008): 10% edge overestimation at full Kelly = catastrophe.
    25% Kelly provides 2x safety margin.

================================================================================
TONIGHT'S BUILD ORDER
================================================================================

  [ ] 1. git pull origin main (get latest code)
  [ ] 2. Create nq_bot_vscode/signals/institutional_modifiers.py
         - OvernightBiasModifier class
         - FOMCDriftModifier class
         - InstitutionalModifierEngine (orchestrator)
  [ ] 3. Create nq_bot_vscode/config/fomc_calendar.py
         - 2026 FOMC dates
         - Helper: hours_until_next_fomc()
  [ ] 4. Integrate InstitutionalModifierEngine into process_bar()
         - After HTF gate approval, before execution
         - Apply multipliers to position size and stop width
         - Log all modifier decisions
  [ ] 5. Create unit tests
         - test_overnight_modifier.py
         - test_fomc_modifier.py
  [ ] 6. Run existing backtest to verify no regression
  [ ] 7. Run backtest WITH modifiers to measure impact
  [ ] 8. Commit: "feat: institutional modifier layer (overnight + FOMC)"

================================================================================
CLAUDE CODE PROMPT TEMPLATE
================================================================================

TASK: Build Institutional Modifier Layer (Overnight Bias + Pre-FOMC Drift)

Use all available agents. git pull origin main first.

STEPS:
1. Read this execution plan file for all thresholds and logic
2. Create nq_bot_vscode/signals/institutional_modifiers.py with:
   - OvernightBiasModifier (thresholds: 50bps significant, 120bps extreme)
   - FOMCDriftModifier (windows: 24h, 4h, 0.5h)
   - InstitutionalModifierEngine (orchestrates all modifiers)
3. Create nq_bot_vscode/config/fomc_calendar.py with 2026 schedule
4. Integrate into process_bar() flow AFTER HTF gate, BEFORE execution
5. Add logging to institutional_modifiers_log.json
6. Create tests in nq_bot_vscode/tests/
7. Run existing backtest — verify zero regression
8. Run backtest with modifiers enabled — compare results

DELIVERABLES:
  [ ] institutional_modifiers.py created with both modifier classes
  [ ] fomc_calendar.py created with 2026 schedule
  [ ] process_bar() integration complete
  [ ] Unit tests passing
  [ ] Backtest regression check: PASS/FAIL
  [ ] Backtest with modifiers: comparison table vs baseline

BOUNDARIES:
  - Do NOT modify HTF gate logic
  - Do NOT modify confluence scoring
  - Do NOT modify existing trade execution logic
  - Modifiers are MULTIPLIERS only — never veto (except FOMC stand-aside)
  - Maximum total multiplier cap: 2.0x
  - Minimum total multiplier floor: 0.3x

ON COMPLETION:
  Print checklist with PASS/FAIL for each deliverable.
  Commit message: "feat: institutional modifier layer (overnight + FOMC)"

IF BLOCKED:
  Report what's blocking and stop. Do not improvise or substitute.

================================================================================
END OF EXECUTION PLAN
================================================================================