0012: Grid Exit Strategy - Automated Risk Detection with Manual Execution

Summary

Implement an automated Grid Exit Strategy system that monitors market regime transitions, quantifies position risk, and generates timely exit alerts for active grid trading positions. The system will produce exit state classifications (NORMAL, WARNING, LATEST_ACCEPTABLE_EXIT, MANDATORY_EXIT) and notifications to enable human operators to manually stop grids before mean-reversion assumptions fail, preserving accumulated profits and avoiding capital loss during regime transitions or trends.

Problem Statement

Grid trading strategies profit from mean-reverting price action within a defined range. However, when market regimes shift from RANGE to TRANSITION or TREND, the fundamental assumptions underlying grid trading break down:

Inventory accumulation risk: Grids continue buying/selling into directional moves, accumulating losing positions
Profit give-back: Unrealized profits from successful grid cycles can be surrendered as prices move directionally
Stop-loss triggers: Without early warnings, grids may run until hard stop-losses are hit, realizing maximum losses
Delayed human reaction: Manual monitoring cannot provide 24/7 coverage or sub-hour reaction times

Currently, the system performs hourly regime analysis and stores results to GitHub, but has no mechanism to:

Translate regime classifications into actionable exit recommendations
Quantify urgency levels for operator action
Deliver timely notifications across multiple channels
Track operator response quality and timing

Without structured exit criteria, operators either:

Exit too early (sacrificing profitable ranging periods)
Exit too late (giving back profits or hitting stops)
Rely on inconsistent manual judgment

Goals

Exit State Classification Engine - Implement a rule-based system that consumes regime analysis outputs and position risk metrics to classify grid exit states
Multi-tiered Alert System - Create WARNING, LATEST_ACCEPTABLE_EXIT, and MANDATORY_EXIT notification types with appropriate urgency and detail
Notification Delivery - Integrate push notifications (mobile/desktop), email, and optional webhooks for alert distribution
Position Risk Quantification - Enhance metrics collection to include capital-at-risk calculations, profit give-back estimates, and stop-loss proximity
Exit Event Logging - Implement audit trail for exit signals, operator actions, and timing to enable retrospective analysis
KPI Framework - Define and track Grid Exit Quality KPIs (Timeliness, Profit Preservation, Risk Avoidance, Signal Accuracy, Operational Discipline)

Non-Goals

Automated order execution - The system will NEVER place or cancel orders; all grid stops remain manual
Position management - No direct interaction with exchange APIs for position management
Grid parameter optimization - Exit strategy does not modify grid ranges, spacing, or sizing
Real-time tick-by-tick monitoring - System operates on 15-minute evaluation cycles using completed bar data
Multi-symbol correlation - Initial implementation focuses on single-grid analysis; cross-market regime agreement is tracked but not used for exit decisions
Backtesting infrastructure - Historical validation deferred to future work
Custom notification UIs - Uses existing push/email services; no custom dashboard development

Technical Approach

Architecture

The Grid Exit Strategy extends the existing hourly regime collection system with new components:

┌─────────────────────────────────────────────────────────────────┐
│  Existing Hourly Collection (CronJob - every hour)              │
│  ┌──────────────────────┐      ┌─────────────────────────┐     │
│  │ Regime Detection     │ ───> │ MetricsHistory         │     │
│  │ - RANGE_OK/WEAK      │      │ (Git storage)          │     │
│  │ - TRANSITION         │      └─────────────────────────┘     │
│  │ - TREND              │                                       │
│  └──────────────────────┘                                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  NEW: Exit Strategy System (15-min evaluation cycle)            │
│  ┌────────────────────┐                                         │
│  │ Exit State Engine  │                                         │
│  │ - Load latest      │                                         │
│  │   regime data      │                                         │
│  │ - Apply rules      │                                         │
│  │ - Classify state   │                                         │
│  └────────────────────┘                                         │
│           │                                                      │
│           ▼                                                      │
│  ┌────────────────────┐       ┌─────────────────────────┐      │
│  │ Position Risk      │ ───>  │ Alert Generator         │      │
│  │ - Capital at risk  │       │ - WARNING               │      │
│  │ - Profit tracking  │       │ - LATEST_ACCEPTABLE_EXIT│      │
│  │ - Stop proximity   │       │ - MANDATORY_EXIT        │      │
│  └────────────────────┘       └─────────────────────────┘      │
│                                         │                        │
│                                         ▼                        │
│                               ┌─────────────────────┐           │
│                               │ Notification Router │           │
│                               │ - Push (ntfy.sh)    │           │
│                               │ - Email             │           │
│                               │ - Webhook (optional)│           │
│                               └─────────────────────┘           │
│                                         │                        │
│                                         ▼                        │
│                               ┌─────────────────────┐           │
│                               │ Audit Log           │           │
│                               │ (Git-backed YAML)   │           │
│                               └─────────────────────┘           │
└─────────────────────────────────────────────────────────────────┘

Key Components

1. Exit State Engine (`src/exit_strategy/state_engine.py`)

Responsibilities:

Load latest regime analysis from market-maker-data Git repository
Apply multi-condition rule evaluations (see Exit Rules section)
Classify current exit state per grid
Track state transitions and persistence

Inputs:

Latest hourly regime metrics (YAML files from metrics/YYYY/MM/DD/HH_SYMBOL.yaml)
4-hour regime history (for TRANSITION persistence checks)
Grid configuration (stop-loss, take-profit, range bounds)

Outputs:

Exit state classification (NORMAL, WARNING, LATEST_ACCEPTABLE_EXIT, MANDATORY_EXIT)
Trigger reasons (which rules fired)
Confidence metrics

Exit Rules Matrix:

Exit State	Conditions (ANY of)	Evaluation Window
MANDATORY_EXIT	• Regime verdict = TREND • 2 consecutive closes outside range bounds • Directional structure confirmed (HH/HL or LL/LH pattern) • Stop-loss price breached	Current 1h + 4h bars
LATEST_ACCEPTABLE_EXIT	• TRANSITION verdict ≥ 2 consecutive 4h bars OR ≥ 4 consecutive 1h bars • Mean reversion half-life ≥ 2× baseline • Volatility expansion ratio > 1.25 • Z-score excursions fail to revert within expected timeframe	Rolling 4-12 hour window
WARNING	• TRANSITION probability ≥ 40% (configurable) • Regime confidence declining over 3 bars • Efficiency Ratio rising above range threshold • Mean reversion speed slowing • Volatility expansion 1.1-1.25×	Rolling 3-6 hour window
NORMAL	None of the above	Current state

2. Position Risk Calculator (`src/exit_strategy/position_risk.py`)

Responsibilities:

Fetch current grid state from KuCoin API
Calculate capital at risk based on inventory and distance to stop-loss
Track unrealized PnL and peak profit metrics
Estimate profit give-back percentage if delayed

Metrics:

position_risk:
  capital_allocated: 745.95
  capital_at_risk: 120.50  # Inventory value × (current_price - stop_loss) / current_price
  unrealized_pnl: 12.34
  peak_unrealized_pnl: 18.75
  profit_giveback_pct: 34.2  # (peak - current) / peak
  stop_loss_distance_atr: 0.85  # How many ATR units away from stop
  inventory_imbalance: 0.15  # Fraction of grids stuck on one side

3. Alert Generator (`src/exit_strategy/alerts.py`)

Responsibilities:

Generate notification content based on exit state and context
Format alerts for different channels (push, email, webhook)
Rate-limit alerts (e.g., max 1 WARNING per 4h, no repeat MANDATORY within 1h)
Include actionable information and KPI estimates

Notification Templates:

WARNING Alert:

⚠️ ETH/USDT Grid WARNING

Regime: TRANSITION probability rising (45%)
Issues: Mean reversion slowing, volatility expanding (1.15x)
Current profit: $12.34 unrealized

Action: Review grid within 24h
Review dashboard: https://example.com/grids/eth-v3

LATEST_ACCEPTABLE_EXIT Alert:

⏳ ETH/USDT - LATEST ACCEPTABLE EXIT

Grid assumptions failing:
• TRANSITION persists 4 bars (4 hours)
• Mean reversion half-life 2.3x baseline

Current state:
• Unrealized profit: $12.34
• Estimated give-back if delayed 12h: $4-7 (30-50%)
• Stop-loss distance: 0.85 ATR

Action: STOP GRID within 4-12 hours to preserve 75-90% of profit
Review: https://example.com/grids/eth-v3

MANDATORY_EXIT Alert:

🛑 ETH/USDT - MANDATORY EXIT

TREND DETECTED - STOP GRID IMMEDIATELY

Trigger: 2 consecutive closes outside range bounds
• Close 1h ago: $2,685 (above upper bound $3,045)
• Close now: $2,702 (above upper bound $3,045)

Capital at risk: $120.50
Stop-loss distance: 0.6 ATR (CRITICAL)

ACTION REQUIRED: Stop grid NOW to protect capital
Manage grid: https://example.com/grids/eth-v3

4. Notification Router (`src/exit_strategy/notifier.py`)

Channels:

Push Notifications (ntfy.sh or similar)
- Mobile/desktop alerts
- Configurable priority levels (1-5 mapped to exit states)
- Delivery confirmation tracking
Email (via AWS SES or SMTP)
- HTML formatted with charts/tables
- Include links to dashboards and regime data
- Configurable recipient list
Webhook (optional, for Slack/Discord/custom)
- POST JSON payload to configured endpoints
- Retry logic with exponential backoff

Configuration (via secrets or environment):

notifications:
  push:
    provider: ntfy
    topic: grid-exits-prod
    priority_map:
      WARNING: 3
      LATEST_ACCEPTABLE_EXIT: 4
      MANDATORY_EXIT: 5
  email:
    provider: ses
    from: alerts@example.com
    to: [operator@example.com]
    enabled: true
  webhook:
    url: https://hooks.slack.com/services/XXX
    enabled: false

5. Exit Event Logger (`src/exit_strategy/audit.py`)

Responsibilities:

Log all exit state transitions to Git-backed YAML files
Record notification timestamps and delivery status
Capture operator action timestamps (requires manual entry or API hook)
Calculate reaction time KPIs

Log Format (market-maker-data/exit_events/YYYY/MM/DD/HH-MM-SYMBOL.yaml):

event_id: evt_2026-01-31T14:23:00_eth
grid_id: eth-v3
symbol: ETH/USDT
timestamp: "2026-01-31T14:23:00Z"
 
exit_state:
  current: LATEST_ACCEPTABLE_EXIT
  previous: WARNING
  transition_time: "2026-01-31T14:23:00Z"
 
triggers:
  - type: TRANSITION_PERSISTENCE
    description: "TRANSITION verdict for 4 consecutive 1h bars"
    bars_affected: [2026-01-31T11:00, 2026-01-31T12:00, 2026-01-31T13:00, 2026-01-31T14:00]
  - type: MEAN_REVERSION_DEGRADATION
    description: "OU half-life 2.3x baseline"
    current_halflife_minutes: 1840
    baseline_halflife_minutes: 800
 
position_risk:
  capital_at_risk: 120.50
  unrealized_pnl: 12.34
  profit_giveback_estimate_12h: [4.0, 7.0]  # Range
  stop_loss_distance_atr: 0.85
 
notifications_sent:
  - channel: push
    status: delivered
    sent_at: "2026-01-31T14:23:15Z"
    delivery_confirmed_at: "2026-01-31T14:23:16Z"
  - channel: email
    status: delivered
    sent_at: "2026-01-31T14:23:15Z"
 
operator_action:
  action_taken: null  # To be updated manually or via API
  action_time: null
  reaction_time_seconds: null
  notes: null

6. Exit Strategy Scheduler (CronJob or Lambda)

Deployment:

New Kubernetes CronJob: exit-strategy-evaluator
Schedule: */15 * * * * (every 15 minutes)
Runtime: Similar to existing hourly-regime-detection job

Workflow:

#!/bin/bash
# Exit strategy evaluation loop
 
# 1. Clone market-maker-data (contains latest regime metrics)
git clone --depth 1 https://github.com/craigedmunds/market-maker-data.git /tmp/market-maker-data
 
# 2. Run exit strategy evaluator
python -m src.exit_strategy.main \
  --data-repo /tmp/market-maker-data \
  --config /config/exit_strategy_config.yaml \
  --secrets /secrets/kucoin-credentials
 
# 3. Commit audit logs if new events
cd /tmp/market-maker-data
git add exit_events/
git commit -m "Exit strategy evaluation: $(date -Iseconds)"
git push origin main

Implementation Phases

Phase 1: Exit State Engine (Core Logic)

Implement rule evaluations for MANDATORY_EXIT triggers
Implement rule evaluations for LATEST_ACCEPTABLE_EXIT triggers
Implement rule evaluations for WARNING triggers
Add state transition tracking
Unit tests for each rule type

Phase 2: Position Risk Calculator

Integrate KuCoin API to fetch current grid state
Calculate capital at risk based on inventory positions
Track unrealized PnL and peak metrics
Implement profit give-back estimation
Unit tests for risk calculations

Phase 3: Alert Generator

Design notification templates for each exit state
Implement content generation with context injection
Add rate-limiting logic
Unit tests for template rendering and rate limits

Phase 4: Notification Router

Integrate push notification provider (ntfy.sh)
Integrate email provider (AWS SES or SMTP)
Implement webhook delivery with retries
Add delivery confirmation tracking
Integration tests for each channel

Phase 5: Exit Event Logger

Design YAML schema for exit events
Implement Git-backed logging (similar to MetricsHistory)
Add automatic event correlation (link to regime snapshots)
Unit tests for log writing and Git integration

Phase 6: Scheduler Integration

Create new CronJob manifest (repos/market-making/infra/exit-strategy/cronjob.yaml)
Wire secrets and config maps
Deploy to market-making namespace
Integration tests for end-to-end workflow

Phase 7: KPI Framework

Implement KPI calculation functions (PRR, PAMA, ERT, etc.)
Add KPI tracking to exit event logs
Create monthly KPI aggregation script
Generate KPI summary reports

Phase 8: Acceptance Testing

Simulate TRANSITION → TREND scenario with mock data
Verify alert delivery across all channels
Validate audit log completeness
Test manual operator action recording

Success Criteria

1. Functional Requirements

Exit states are correctly classified based on regime data and position risk
All three alert types (WARNING, LATEST_ACCEPTABLE_EXIT, MANDATORY_EXIT) are generated with appropriate triggers
Notifications are delivered within 60 seconds of state transitions
Push notifications, emails, and webhooks (if configured) are all delivered successfully
Audit logs capture all exit events with complete context
KPI calculations produce accurate metrics from logged events

2. Performance Requirements

Exit state evaluation completes within 30 seconds per grid
Notification delivery latency < 60 seconds
Git commit/push of audit logs completes within 10 seconds
System supports up to 5 concurrent grids without degradation

3. Reliability Requirements

No missed exit state transitions (100% detection rate for eligible events)
Notification delivery success rate ≥ 99.5%
Audit log integrity maintained (no lost events)
Graceful degradation if notification channel fails (log failure, continue evaluation)

4. Operational Requirements

Human operator can acknowledge alerts and record actions via manual YAML edits or API
Monthly KPI reports are generated automatically
Exit event logs are retained indefinitely in Git
System is testable with synthetic regime data

5. Quality Metrics (KPIs)

After 3 months of operation, the system should demonstrate:

Exit Within Acceptable Window (EAW%) ≥ 90% (exits before MANDATORY_EXIT)
Profit Retention Ratio (PRR) ≥ 0.75 average
Stop-Loss Avoidance Rate (SLAR) ≥ 95%
True Transition Detection Rate (TTDR) ≥ 70%
Mandatory Exit Compliance (MEC%) = 100%

Dependencies

1. Existing Infrastructure (Complete)

Hourly regime detection system (collects regime metrics)
KuCoin API integration (credentials, exchange client)
Git-backed metrics storage (market-maker-data repository)
Kubernetes cluster with CronJob support
ExternalSecrets for credential management

2. New Infrastructure Required

Push notification service (ntfy.sh or similar - free tier available)
Email service (AWS SES or SMTP relay)
Optional: Slack/Discord webhook endpoints

3. External Libraries

requests - HTTP client for webhooks (already in dependencies)
ntfy or HTTP client for push notifications (new)
boto3 - AWS SES integration (optional, only if using SES)

4. Configuration

Exit strategy configuration file (repos/market-making/config/exit_strategy_config.yaml)
Notification credentials (stored in ExternalSecrets)

5. Data Dependencies

Regime metrics generated by hourly collection (must be available within 15 minutes of collection)
Grid configuration in system_config_v1.yaml (already available)

Risks

Risk	Impact	Likelihood	Mitigation
False positives trigger unnecessary exits	Medium	Medium	1. Tune rule thresholds using historical data 2. WARNING state allows validation before action 3. Track False Exit Rate (FER) KPI and adjust
Notification delivery failures	High	Low	1. Multi-channel redundancy (push + email) 2. Retry logic with exponential backoff 3. Audit log captures send attempts
Operator ignores MANDATORY_EXIT	High	Low	1. Escalating notification priority 2. Track Mandatory Exit Compliance (MEC%) KPI 3. Post-event review process
Git commit conflicts	Low	Low	1. Retry logic with pull before push 2. Exit event files are timestamped, unlikely to conflict
15-min evaluation misses fast regime changes	Medium	Medium	1. Acceptable trade-off for CronJob simplicity 2. MANDATORY_EXIT triggers on hard conditions (closes outside range) 3. Future: Reduce to 5-min cadence if needed
Rule complexity leads to maintenance burden	Low	Medium	1. Comprehensive unit tests for each rule 2. Clear documentation of trigger logic 3. Configuration-driven thresholds
Capital-at-risk calculations are inaccurate	Medium	Low	1. Unit tests with known scenarios 2. Compare against manual calculations in reviews 3. Conservative estimates preferred

Open Questions

Notification provider selection: ntfy.sh (free, open-source) vs. commercial provider (Pushover, Pushbullet)?
- Recommendation: Start with ntfy.sh for cost and flexibility; migrate if delivery issues arise
Operator action tracking: Manual YAML edits vs. dedicated API endpoint?
- Recommendation: Manual YAML edits for MVP; API endpoint in Phase 2 if burden is high
Should WARNING alerts be suppressed during known quiet periods (e.g., low-volume weekends)?
- Recommendation: No time-based suppression in MVP; add if false positive rate is problematic
How to handle grids that are already stopped (status = DISABLED)?
- Recommendation: Skip exit state evaluation for DISABLED grids; log state as “N/A - Grid Inactive”
Should exit strategy run when no active grids exist?
- Recommendation: Yes, continue evaluation to log regime context; skip notification generation

References

Requirements document: /home/coder/src/.ai/projects/market-making/new-instructions.md
Existing regime detection code: repos/market-making/metrics-service/src/metrics/regime_detection.py
Existing metrics storage: repos/market-making/metrics-service/src/metrics/history.py
KuCoin API integration: repos/market-making/metrics-service/src/exchange/kucoin_client.py
Market-maker-data repository: https://github.com/craigedmunds/market-maker-data
Hourly collection CronJob: repos/market-making/infra/metrics-service/cronjob.yaml

Appendix: Exit Strategy Configuration Example

# repos/market-making/config/exit_strategy_config.yaml
 
evaluation:
  cadence_minutes: 15
  lookback_hours: 12
  
exit_rules:
  warning:
    transition_probability_threshold: 0.40
    regime_confidence_decline_bars: 3
    efficiency_ratio_threshold: 0.6
    volatility_expansion_min: 1.10
    volatility_expansion_max: 1.25
    
  latest_acceptable_exit:
    transition_persistence_4h_bars: 2
    transition_persistence_1h_bars: 4
    mean_reversion_halflife_multiplier: 2.0
    volatility_expansion_threshold: 1.25
    zscore_reversion_failure_bars: 6
    
  mandatory_exit:
    consecutive_closes_outside_range: 2
    directional_swing_bars: 6  # For HH/HL pattern detection
    stop_loss_buffer_atr: 0.1  # Trigger before actual stop
 
notifications:
  rate_limits:
    warning_min_hours: 4
    latest_acceptable_min_hours: 2
    mandatory_min_hours: 1
    
  push:
    enabled: true
    provider: ntfy
    topic: grid-exits-prod
    priority_map:
      WARNING: 3
      LATEST_ACCEPTABLE_EXIT: 4
      MANDATORY_EXIT: 5
      
  email:
    enabled: true
    from: grid-alerts@example.com
    to:
      - operator@example.com
    subject_prefix: "[Grid Exit]"
    
  webhook:
    enabled: false
    url: null
    
profit_preservation:
  warning_window_hours: 24
  latest_acceptable_window_hours: 12
  mandatory_window_hours: 1
  
  profit_retention_targets:
    warning_exit: 0.90
    latest_acceptable_exit: 0.80
    mandatory_exit: 0.60
 
kpis:
  review_cadence_days: 30
  targets:
    exit_within_acceptable_window_pct: 90
    profit_retention_ratio: 0.75
    stop_loss_avoidance_rate: 0.95
    true_transition_detection_rate: 0.70
    mandatory_exit_compliance_pct: 100

Techcle Wiki

Explorer

Spec

0012: Grid Exit Strategy - Automated Risk Detection with Manual Execution

Summary

Problem Statement

Goals

Non-Goals

Technical Approach

Architecture

Key Components

1. Exit State Engine (`src/exit_strategy/state_engine.py`)

2. Position Risk Calculator (`src/exit_strategy/position_risk.py`)

3. Alert Generator (`src/exit_strategy/alerts.py`)

4. Notification Router (`src/exit_strategy/notifier.py`)

5. Exit Event Logger (`src/exit_strategy/audit.py`)

6. Exit Strategy Scheduler (CronJob or Lambda)

Implementation Phases

Success Criteria

1. Functional Requirements

2. Performance Requirements

3. Reliability Requirements

4. Operational Requirements

5. Quality Metrics (KPIs)

Dependencies

1. Existing Infrastructure (Complete)

2. New Infrastructure Required

3. External Libraries

4. Configuration

5. Data Dependencies

Risks

Open Questions

References

Appendix: Exit Strategy Configuration Example

Graph View

Table of Contents

Backlinks

Techcle Wiki

Explorer

Spec

0012: Grid Exit Strategy - Automated Risk Detection with Manual Execution

Summary

Problem Statement

Goals

Non-Goals

Technical Approach

Architecture

Key Components

1. Exit State Engine (src/exit_strategy/state_engine.py)

2. Position Risk Calculator (src/exit_strategy/position_risk.py)

3. Alert Generator (src/exit_strategy/alerts.py)

4. Notification Router (src/exit_strategy/notifier.py)

5. Exit Event Logger (src/exit_strategy/audit.py)

6. Exit Strategy Scheduler (CronJob or Lambda)

Implementation Phases

Success Criteria

1. Functional Requirements

2. Performance Requirements

3. Reliability Requirements

4. Operational Requirements

5. Quality Metrics (KPIs)

Dependencies

1. Existing Infrastructure (Complete)

2. New Infrastructure Required

3. External Libraries

4. Configuration

5. Data Dependencies

Risks

Open Questions

References

Appendix: Exit Strategy Configuration Example

Graph View

Table of Contents

Backlinks

1. Exit State Engine (`src/exit_strategy/state_engine.py`)

2. Position Risk Calculator (`src/exit_strategy/position_risk.py`)

3. Alert Generator (`src/exit_strategy/alerts.py`)

4. Notification Router (`src/exit_strategy/notifier.py`)

5. Exit Event Logger (`src/exit_strategy/audit.py`)