Techcle Wiki

Requirements

24 min read

Requirements Document

Introduction

The Regime Management system is a decision support and controlled automation system for grid trading strategies. The system monitors market conditions, classifies market regimes, and provides recommendations for grid trading decisions while prioritizing capital preservation and explicit decision-making over profit optimization. The system currently uses KuCoin as the primary exchange but is designed to be extensible to other exchanges.

Glossary

  • Market_Maker: The complete decision support system for grid trading
  • Grid_Trading: A trading strategy that places buy and sell orders at regular intervals around a current price
  • Market_Regime: A classification of current market behavior (RANGE_OK, RANGE_WEAK, TRANSITION, TREND)
  • Decision_Record: An immutable YAML file storing each recommendation and its outcomes
  • Grid_Setup: A recommendation to create a new grid trading configuration
  • Grid_Manage: A recommendation to modify or maintain an existing grid
  • KuCoin_Exchange: The primary cryptocurrency exchange used for implementation
  • Capital_Allocation: The system for determining how much capital to deploy in grid strategies
  • Exchange_Interface: An abstract interface for interacting with cryptocurrency exchanges
  • Confidence_Score: A measure of regime stability and classification consistency
  • Grid_Structure: The complete specification of grid levels, spacing, and order sizing
  • Evaluation_Horizon: Predefined time periods for assessing recommendation quality
  • Configuration_Version: A versioned snapshot of system configuration used for decision traceability
  • Metrics_History: A time-series collection of system state snapshots stored in separate YAML files per market with minute-level price granularity
  • System_Snapshot: A point-in-time capture of grid status, account balance, market prices, and regime state for a specific analyzed hour, not the execution time
  • Market_Metrics_File: Individual YAML files containing minute-by-minute price data and regime analysis for a specific market and time period
  • Static_Dashboard: A web-based visualization interface for displaying metrics history and trends
  • Grid_Configuration_Parameters: Detailed specifications of a grid including price bounds, entry price, grid levels, amount per grid, profit percentages, stop-loss, and take-profit settings
  • Grid_Configuration_Version: A timestamped snapshot of grid configuration parameters used for tracking changes and decision traceability
  • Amount_Per_Grid: The specific quantity of base currency allocated to each grid level in a trading grid
  • Profit_Per_Grid: The expected profit percentage or amount for each completed grid level cycle
  • Grid_Profit_Reinvestment: A setting that determines whether profits from completed grid trades are reinvested into the grid or withdrawn

Requirements

Requirement 1: Market Regime Classification

User Story: As a grid trader, I want the system to classify market conditions into distinct regimes using robust price data analysis, so that I can make informed decisions about when grid trading is appropriate.

Acceptance Criteria

  1. WHEN market data is analyzed, THE Market_Maker SHALL classify the current market using OHLCV price data and derived volatility and range metrics
  2. WHEN classifying regimes, THE Market_Maker SHALL use a decision timeframe of 1 hour with lower timeframes (5m, 15m) providing early-warning context only
  3. WHEN the regime is RANGE_OK, THE Market_Maker SHALL indicate the market is suitable for grid trading
  4. WHEN the regime is RANGE_WEAK, THE Market_Maker SHALL indicate caution is needed for grid trading
  5. WHEN the regime is TRANSITION or TREND, THE Market_Maker SHALL indicate the market is unsuitable for grid trading
  6. WHEN analyzing price structure, THE Market_Maker SHALL derive range boundaries, closes relative to range, and higher highs/lower lows patterns
  7. WHEN measuring volatility, THE Market_Maker SHALL calculate ATR-based range metrics and volatility expansion/contraction relative to recent baseline
  8. WHEN performing regime analysis, THE Market_Maker SHALL use up to 21 days of 1-minute data, 120 days of 15-minute data, 270 days of 1-hour data, and 540 days of 4-hour data

Requirement 2: Recommendation Types and Action Constraints

User Story: As a grid trader, I want the system to use a well-defined set of recommendation types and actions, so that I can understand and validate all possible system behaviors.

Acceptance Criteria

  1. WHEN generating recommendations, THE Market_Maker SHALL use exactly two recommendation types: GRID_MANAGE and GRID_SETUP
  2. WHEN classifying market regimes, THE Market_Maker SHALL use exactly four verdicts: RANGE_OK, RANGE_WEAK, TRANSITION, and TREND
  3. WHEN creating GRID_MANAGE recommendations, THE Market_Maker SHALL use exactly three actions: RUN_GRID, RUN_GRID_NO_SCALE, and STOP_GRID
  4. WHEN creating GRID_SETUP recommendations, THE Market_Maker SHALL use exactly three actions: CREATE_GRID, IGNORE, and SNOOZE
  5. WHEN validating recommendations, THE Market_Maker SHALL reject any recommendation that uses types, verdicts, or actions outside these defined sets

Requirement 3: Confidence Score Calculation

User Story: As a grid trader, I want the system to calculate confidence scores based on regime stability and consistency with conservative calibration that reflects the inherent uncertainty of early range detection, so that I can understand the reliability of regime classifications without conflating it with profit predictions.

Acceptance Criteria

  1. WHEN computing confidence scores, THE Market_Maker SHALL base calculations on regime consistency, range integrity, volatility stability, and time persistence
  2. WHEN evaluating range integrity, THE Market_Maker SHALL consider percentage of closes inside range, number of boundary violations, and duration the range has held
  3. WHEN assessing mean reversion behavior, THE Market_Maker SHALL measure speed of reversion from extremes and frequency of oscillation
  4. WHEN analyzing volatility regime, THE Market_Maker SHALL evaluate stability versus expansion and volatility symmetry
  5. WHEN measuring time consistency, THE Market_Maker SHALL assess agreement across recent candles and lack of rapid regime flipping
  6. WHEN confidence scores are used, THE Market_Maker SHALL use them to reduce risk exposure but never to increase exposure or override safety constraints
  7. WHEN calculating confidence, THE Market_Maker SHALL never incorporate profit estimates, fee estimates, or historical PnL optimization
  8. WHEN calculating confidence for range durations less than 36 hours, THE Market_Maker SHALL apply a time-based penalty that reduces confidence to reflect the uncertainty of early range detection
  9. WHEN the current price is in the upper or lower half of a discovered range, THE Market_Maker SHALL apply a position-based penalty that reduces confidence to account for potential range breakout risk
  10. WHEN a range is the first detected after a trend period, THE Market_Maker SHALL apply an additional maturity penalty to reflect that new ranges are less reliable than established ranges
  11. WHEN proposed grid spacing is narrow relative to the range width (less than 2% of range), THE Market_Maker SHALL apply a spacing-based penalty that reduces confidence to account for increased breakout sensitivity
  12. WHEN confidence scores exceed 0.95, THE Market_Maker SHALL cap the confidence at 0.95 to prevent unrealistic certainty levels
  13. WHEN confidence scores are calculated, THE Market_Maker SHALL ensure typical RANGE_OK confidence scores fall between 0.60-0.85 rather than approaching 0.90 or higher

Requirement 4: Decision Record Management

User Story: As a grid trader, I want all recommendations and decisions to be permanently recorded with configuration versioning, so that I can audit and evaluate the system’s performance over time without retroactive changes affecting past decisions.

Acceptance Criteria

  1. WHEN a recommendation is generated, THE Market_Maker SHALL create an immutable Decision_Record in YAML format
  2. WHEN storing Decision_Records, THE Market_Maker SHALL store each record as a separate file in Git version control
  3. WHEN a Decision_Record is created, THE Market_Maker SHALL include an immutable recommendation section that cannot be modified after creation
  4. WHEN a Decision_Record is created, THE Market_Maker SHALL reference the configuration version hash and grid definition ID/version in effect at the time
  5. WHEN market data is used, THE Market_Maker SHALL record the data source (KuCoin exchange) in the Decision_Record
  6. WHEN actions are taken on recommendations, THE Market_Maker SHALL append action records to the Decision_Record without modifying existing content
  7. WHEN evaluations are performed, THE Market_Maker SHALL append evaluation records to the Decision_Record without modifying existing content
  8. WHEN configuration changes are made, THE Market_Maker SHALL apply updates only to recommendations generated after the change and never alter active grid behavior unless a new explicit GRID_MANAGE action is executed

Requirement 5: Grid Configuration Management

User Story: As a grid trader, I want the system to use explicitly defined grid configurations with clear automation permissions, so that I can control which markets are eligible for grid trading and how they behave.

Acceptance Criteria

  1. WHEN defining eligible markets, THE Market_Maker SHALL maintain a grids array in global configuration containing grid objects with id, symbol, history array, optional role, automation permissions, and allocation intent
  2. WHEN proposing grids, THE Market_Maker SHALL only propose grids for symbols explicitly defined in the grid configuration with active grid state determined from history array
  3. WHEN automation is configured, THE Market_Maker SHALL respect the allow_auto_create setting for each grid definition
  4. WHEN operating in SINGLE_GRID mode, THE Market_Maker SHALL allocate most available capital minus reserve to the active grid
  5. WHEN grid definitions are updated, THE Market_Maker SHALL apply changes only to new recommendations and never modify existing active grids
  6. WHEN generating recommendations for a grid with stopped state determined from history array, THE Market_Maker SHALL consider the grid state when determining actionable recommendations
  7. WHEN a grid is stopped and market conditions are favorable, THE Market_Maker SHALL recommend creating a new grid as an actionable recommendation
  8. WHEN a grid is stopped and market conditions are unfavorable, THE Market_Maker SHALL not generate actionable recommendations since the grid is already in the safe state
  9. WHEN an enabled grid’s price range no longer aligns with current market conditions, THE Market_Maker SHALL recommend stopping the current grid and creating a new grid with updated price bounds

Requirement 6: Grid Management Recommendations

User Story: As a grid trader, I want the system to provide actionable recommendations for managing existing grids, so that I can respond appropriately to changing market conditions.

Acceptance Criteria

  1. WHEN an active grid exists, THE Market_Maker SHALL generate Grid_Manage recommendations with actions: RUN_GRID, RUN_GRID_NO_SCALE, or STOP_GRID
  2. WHEN the market regime is RANGE_OK, THE Market_Maker SHALL default to RUN_GRID action
  3. WHEN the market regime is RANGE_WEAK, THE Market_Maker SHALL default to RUN_GRID_NO_SCALE action
  4. WHEN the market regime is TRANSITION or TREND, THE Market_Maker SHALL default to STOP_GRID action
  5. WHEN confidence falls below the global safety threshold, THE Market_Maker SHALL override the default action to STOP_GRID
  6. WHEN a Grid_Manage recommendation times out without user response, THE Market_Maker SHALL apply the default action and record it as SYSTEM_DEFAULT

Requirement 7: Grid Setup Recommendations

User Story: As a grid trader, I want the system to propose fully specified grid configurations with complete structural details and safety-first stop conditions when market conditions are favorable, so that grids can be created deterministically without additional inference.

Acceptance Criteria

  1. WHEN no active grid exists and market conditions are suitable, THE Market_Maker SHALL generate Grid_Setup recommendations
  2. WHEN creating a Grid_Setup recommendation, THE Market_Maker SHALL fully specify grid structure including number of levels, spacing method (EVEN or PERCENT), price bounds, and stop conditions
  3. WHEN specifying stop conditions, THE Market_Maker SHALL define stop trigger logic and set stop execution mode to KEEP_ASSETS by default
  4. WHEN SELL_ALL stop execution mode is required, THE Market_Maker SHALL only allow it via explicit manual override and never as a system default
  5. WHEN specifying grid structure, THE Market_Maker SHALL define order sizing as equal-sized orders derived from capital divided by grid count
  6. WHEN creating a Grid_Setup recommendation, THE Market_Maker SHALL include target grid ID, symbol, confidence score, validity window, and justification
  7. WHEN a Grid_Setup recommendation is generated, THE Market_Maker SHALL mark it as advisory by default requiring explicit user approval
  8. WHEN a Grid_Setup recommendation receives no user response, THE Market_Maker SHALL create no grid and allow the recommendation to expire at the validity window without action
  9. WHEN proposing grids, THE Market_Maker SHALL only propose grids for symbols explicitly defined in the grid configuration scope

Requirement 8: Capital Management

User Story: As a grid trader, I want the system to manage capital allocation safely, so that I maintain appropriate reserves and never risk more than intended.

Acceptance Criteria

  1. WHEN operating in SINGLE_GRID mode, THE Market_Maker SHALL allow only one active grid at a time
  2. WHEN allocating capital to grids, THE Market_Maker SHALL always maintain a global reserve percentage as specified in configuration
  3. WHEN calculating available capital, THE Market_Maker SHALL only consider unlocked balance from the KuCoin_Exchange account
  4. WHEN capital allocation is requested, THE Market_Maker SHALL respect both percentage-based reserves and optional absolute caps
  5. WHEN capital is deployed, THE Market_Maker SHALL never silently reallocate capital without explicit permission

Requirement 9: Automation Controls

User Story: As a grid trader, I want controlled automation that can reduce risk automatically but requires permission for capital deployment, so that I maintain control over my trading decisions.

Acceptance Criteria

  1. WHEN automation is enabled for risk reduction, THE Market_Maker SHALL automatically execute STOP_GRID actions without user intervention
  2. WHEN capital deployment is requested, THE Market_Maker SHALL require explicit user permission and never deploy capital automatically by default
  3. WHEN automatic grid creation is enabled, THE Market_Maker SHALL only create grids when confidence exceeds the configured minimum threshold
  4. WHEN automation executes an action, THE Market_Maker SHALL log the action as SYSTEM_AUTOMATED in the Decision_Record
  5. WHEN confidence scores are evaluated, THE Market_Maker SHALL use confidence to escalate to conservative actions but never to escalate exposure or override safety constraints

Requirement 10: Timeout and Cooldown Management

User Story: As a grid trader, I want the system to handle unresponsive situations gracefully with appropriate timeouts and enforce cooldowns after significant actions, so that critical decisions are not delayed indefinitely and the system maintains appropriate pacing.

Acceptance Criteria

  1. WHEN a Grid_Manage recommendation has verdict TRANSITION, THE Market_Maker SHALL apply a 30-minute timeout
  2. WHEN a Grid_Manage recommendation has verdict TREND, THE Market_Maker SHALL apply a 15-minute timeout
  3. WHEN a Grid_Manage recommendation has verdict RANGE_OK or RANGE_WEAK, THE Market_Maker SHALL apply no timeout
  4. WHEN a recommendation timeout expires, THE Market_Maker SHALL automatically apply the default action and record it as SYSTEM_DEFAULT
  5. WHEN a grid is stopped via STOP_GRID action, THE Market_Maker SHALL enforce a 60-minute cooldown before allowing new grid creation for that specific grid_id
  6. WHEN a Grid_Setup recommendation is declined or expires, THE Market_Maker SHALL enforce a 120-minute cooldown before proposing another Grid_Setup for the same grid_id
  7. WHEN cooldowns are active, THE Market_Maker SHALL apply cooldowns per grid_id and not globally across all grids

Requirement 11: API Security and Permissions

User Story: As a grid trader, I want the system to use secure API configurations with appropriate permission restrictions, so that my funds remain safe and access is properly controlled.

Acceptance Criteria

  1. WHEN configuring API access, THE Market_Maker SHALL require API keys that do not have withdrawal permissions
  2. WHEN executing trades, THE Market_Maker SHALL require API keys with trade permissions for grid creation and stop operations
  3. WHEN connecting to exchanges, THE Market_Maker SHALL require IP whitelist configuration for API access
  4. WHEN API permissions are insufficient, THE Market_Maker SHALL fail safely and log the permission error
  5. WHEN validating API access, THE Market_Maker SHALL verify permissions before attempting any trading operations

Requirement 12: Exchange Interface and KuCoin Integration

User Story: As a grid trader using KuCoin with plans to support other exchanges, I want the system to use a generic exchange interface with KuCoin as the first implementation, so that the regime logic remains portable across different exchanges.

Acceptance Criteria

  1. WHEN interacting with exchanges, THE Market_Maker SHALL use an abstract Exchange_Interface that supports market data retrieval, grid creation, grid stop, and trade history polling
  2. WHEN implementing exchange-specific functionality, THE Market_Maker SHALL create exchange-specific adapters that conform to the Exchange_Interface without affecting regime logic or Decision_Records
  3. WHEN retrieving account information from KuCoin, THE Market_Maker SHALL connect to the KuCoin_Exchange API to fetch current balance and position data
  4. WHEN executing grid trades on KuCoin, THE Market_Maker SHALL use KuCoin_Exchange API endpoints for order placement and management
  5. WHEN monitoring grid performance on KuCoin, THE Market_Maker SHALL retrieve trade history and order status from KuCoin_Exchange
  6. WHEN calculating available capital from KuCoin, THE Market_Maker SHALL query KuCoin_Exchange for current unlocked USDT balance
  7. WHEN grid configuration specifies KuCoin as the exchange, THE Market_Maker SHALL validate that the specified trading symbol is available on KuCoin_Exchange

Requirement 13: Trade Monitoring and Notification System

User Story: As a grid trader using n8n for notification management, I want the system to monitor grid trades and send detailed notifications with actionable information, so that I can stay informed about system activity and respond appropriately.

Acceptance Criteria

  1. WHEN monitoring active grids, THE Market_Maker SHALL poll KuCoin trade/fill history every 2-5 minutes
  2. WHEN detecting new trades, THE Market_Maker SHALL use monotonic IDs as watermarks to identify new fills
  3. WHEN new grid trades are detected, THE Market_Maker SHALL notify once per new fill with trade details
  4. WHEN a new recommendation is generated, THE Market_Maker SHALL send notifications containing verdict, action, confidence, timeout remaining (if applicable), and a link to the decision interface
  5. WHEN a Grid_Setup recommendation is created, THE Market_Maker SHALL send notifications containing grid_id, symbol, range summary, confidence, link, and explicit statement that silence means no action
  6. WHEN a grid is stopped, THE Market_Maker SHALL send a notification with the reason and outcome
  7. WHEN notifications are configured for Pushover, THE Market_Maker SHALL deliver notifications through the Pushover service
  8. WHEN webhook notifications are enabled, THE Market_Maker SHALL send notifications to configured webhook endpoints for integration with external automation platforms like n8n
  9. WHEN sending notifications, THE Market_Maker SHALL not send multiple notifications for the same recommendation ID and shall not spam for repeated polling failures

Requirement 14: Performance Evaluation and Learning

User Story: As a grid trader, I want the system to evaluate the quality of its recommendations and my decisions at specific time horizons using USD-denominated metrics, so that I can improve the trading strategy and system performance through measurable outcomes.

Acceptance Criteria

  1. WHEN evaluation horizons are reached, THE Market_Maker SHALL evaluate recommendations at predefined horizons of 24 hours, 72 hours, and 7 days
  2. WHEN performing evaluations, THE Market_Maker SHALL independently assess both the recommendation quality and the actual action taken
  3. WHEN evaluating at 24 hours, THE Market_Maker SHALL record short-term regime correctness
  4. WHEN evaluating at 72 hours, THE Market_Maker SHALL assess grid viability window and regime validity
  5. WHEN evaluating at 7 days, THE Market_Maker SHALL measure economic impact including capital impact in USD, fees paid, and opportunity cost
  6. WHEN calculating USD-denominated figures, THE Market_Maker SHALL treat USDT as USD proxy and record the conversion method for any non-USDT PnL calculations
  7. WHEN storing evaluations, THE Market_Maker SHALL append evaluation records to the corresponding Decision_Record

Requirement 15: System Metrics Collection and History

User Story: As a grid trader, I want the system to automatically collect and store historical metrics about grid status, account balance, market prices, and regime state on an hourly basis with minute-level price granularity, so that I can analyze system performance and behavior patterns over time with detailed price movement data.

Acceptance Criteria

  1. WHEN the system is running, THE Market_Maker SHALL provide a webhook endpoint for n8n to trigger hourly metrics collection
  2. WHEN collecting metrics, THE Market_Maker SHALL capture raw market data for the previous complete hour and store it for analysis
  3. WHEN collecting metrics, THE Market_Maker SHALL capture grid status, account balance (when available), market prices, and regime state
  4. WHEN collecting metrics, THE Market_Maker SHALL include minute-level price data to enable detailed analysis
  5. WHEN collecting metrics, THE Market_Maker SHALL determine grid state from grid history records
  6. WHEN collecting metrics, THE Market_Maker SHALL capture grid configuration parameters for active grids
  7. WHEN metrics collection is re-run for the same time period, THE Market_Maker SHALL update the existing data with current analysis
  8. WHEN metrics collection fails, THE Market_Maker SHALL return error status to n8n without stopping system operation
  9. WHEN deploying metrics collection in Kubernetes cronjobs, THE Market_Maker SHALL use the same taskfile methods available locally (task collect) instead of direct Python commands to ensure consistency and enable local simulation of cronjob behavior
  10. WHEN deploying metrics collection in containers, THE Market_Maker SHALL support environment variable overrides for any configuration value in environment.yaml using a convention-based naming scheme (e.g., MARKET_MAKER_DATA_REPOSITORY_BASE_PATH) to enable flexible deployment configuration without hardcoded values

Requirement 16: Enhanced Grid Configuration Management

User Story: As a grid trader using KuCoin spot grids that cannot be managed via API, I want the system to capture and store detailed grid configuration parameters from manual KuCoin setup, so that I can maintain accurate records of grid specifications for decision-making and performance tracking.

Acceptance Criteria

  1. WHEN defining grid configurations, THE Market_Maker SHALL capture detailed grid parameters including price range bounds, entry price, number of grid levels, amount per grid, and profit percentage per grid
  2. WHEN storing grid configurations, THE Market_Maker SHALL record stop-loss price, take-profit price (if configured), and grid profit reinvestment settings
  3. WHEN a grid is manually created in KuCoin, THE Market_Maker SHALL allow updating the grid configuration with actual parameters used in the exchange
  4. WHEN grid parameters are updated, THE Market_Maker SHALL maintain version history of grid configuration changes with timestamps
  5. WHEN calculating expected performance, THE Market_Maker SHALL use actual grid parameters (amount per grid, profit percentages) rather than estimates
  6. WHEN monitoring active grids, THE Market_Maker SHALL validate that actual grid behavior matches the stored configuration parameters
  7. WHEN a grid configuration includes stop-loss settings, THE Market_Maker SHALL monitor market conditions relative to the configured stop-loss price
  8. WHEN grid profit reinvestment is enabled in configuration, THE Market_Maker SHALL account for compounding effects in performance calculations
  9. WHEN multiple grids exist for the same symbol, THE Market_Maker SHALL maintain separate detailed configurations for each grid instance
  10. WHEN grid configurations are referenced in recommendations, THE Market_Maker SHALL use the specific version of configuration that was active at recommendation time
  11. WHEN collecting hourly metrics, THE Market_Maker SHALL capture the current grid configuration parameters for all active grids including price bounds, entry price, grid levels, amounts per grid, and profit settings
  12. WHEN storing hourly metrics, THE Market_Maker SHALL include grid configuration snapshots to enable historical analysis of how configuration changes affect performance

Requirement 17: Grid Restart Gates After Stop

User Story: As a grid trader, I want the system to enforce mandatory gates before allowing new grid creation after a grid stop, so that I avoid restarting grids prematurely during trend continuations or unstable market conditions.

Acceptance Criteria

  1. WHEN a grid is stopped with verdict TRANSITION or TREND, THE Market_Maker SHALL record the stop event with timestamp and stopping verdict
  2. WHEN evaluating grid restart eligibility, THE Market_Maker SHALL require all three mandatory gates to pass sequentially before allowing CREATE_GRID recommendations
  3. WHEN evaluating Gate 1 (Directional Energy Decay), THE Market_Maker SHALL support configurable passage logic including consecutive-bar requirement or majority-of-window requirement and SHALL apply the configured logic consistently per gate
  4. WHEN checking directional energy decay conditions, THE Market_Maker SHALL evaluate TrendScore below exit threshold, ADX falling and below mid-zone threshold, normalized slope below small multiple of ATR, Efficiency Ratio below threshold, and absence of higher highs or lower lows over a configurable lookback window using a defined swing-detection method
  5. WHEN Gate 1 fails, THE Market_Maker SHALL classify regime as TRANSITION or TREND, SHALL block evaluation of all subsequent gates, and SHALL NOT proceed to Gate 2
  6. WHEN Gate 1 passes, THE Market_Maker SHALL proceed to evaluate Gate 2
  7. WHEN evaluating Gate 2 (Mean Reversion Return), THE Market_Maker SHALL require MeanRevScore at or above threshold, lag-1 autocorrelation at or below zero, OU half-life finite and short, multiple z-score excursions that revert, and oscillations defined as price crossings of configurable multiples of candidate grid spacing that revert within configurable bar count
  8. WHEN Gate 2 fails, THE Market_Maker SHALL classify regime as RANGE_WEAK, SHALL block evaluation of Gate 3, and SHALL NOT allow grid creation
  9. WHEN Gate 2 passes, THE Market_Maker SHALL proceed to evaluate Gate 3
  10. WHEN evaluating Gate 3 (Tradable Volatility), THE Market_Maker SHALL require ATR percentage above minimum threshold, ATR percentage below maximum threshold, volatility not expanding, Bollinger Band bandwidth stable or shrinking, and volatility percentile flat or declining
  11. WHEN Gate 3 fails, THE Market_Maker SHALL classify regime as RANGE_WEAK and SHALL NOT allow grid creation
  12. WHEN all three gates pass, THE Market_Maker SHALL transition regime classification to RANGE_OK
  13. WHEN all three gates pass, THE Market_Maker SHALL allow CREATE_GRID recommendations with conservative initial parameters as defined by system configuration
  14. WHEN a new grid is created after passing restart gates, THE Market_Maker SHALL compute grid parameters from current market structure and SHALL NOT reuse the stopped grid’s center, spacing, or bounds
  15. WHEN gates are being evaluated, THE Market_Maker SHALL record gate evaluation results in regime analysis output including which gates passed, which failed, and specific metrics for each gate
  16. WHEN a grid stop occurs, THE Market_Maker SHALL initialize gate tracking state with all gates marked as not passed
  17. WHEN gate thresholds are configured, THE Market_Maker SHALL allow per-symbol and per-timeframe threshold customization
  18. WHEN multiple bars are required for gate passage, THE Market_Maker SHALL track bar-by-bar gate status and require consecutive or majority passage as configured per gate configuration
  19. WHEN a grid is stopped, THE Market_Maker SHALL enforce a configurable minimum time floor (in bars) before beginning gate evaluation to prevent stop-restart churn and indicator noise
  20. WHEN calculating confidence scores across bars, THE Market_Maker SHALL apply a configurable maximum delta constraint to prevent wild bar-to-bar confidence jumps when regime remains unchanged

Requirement 19: Grid State Management Through History Array

User Story: As a grid trader, I want the system to determine grid state (running/stopped) from the history array rather than a separate enabled field, so that there is a single source of truth for grid state and no conflicting status information.

Acceptance Criteria

  1. WHEN determining grid state, THE Market_Maker SHALL examine the most recent entry in the grid’s history array
  2. WHEN the most recent history entry has an ‘enabled’ timestamp without a corresponding ‘disabled’ timestamp, THE Market_Maker SHALL consider the grid as running
  3. WHEN the most recent history entry has both ‘enabled’ and ‘disabled’ timestamps, THE Market_Maker SHALL consider the grid as stopped
  4. WHEN no history entries exist for a grid, THE Market_Maker SHALL consider the grid as stopped
  5. WHEN generating recommendations, THE Market_Maker SHALL use the history-based grid state determination instead of any separate enabled field
  6. WHEN collecting metrics, THE Market_Maker SHALL use the history-based grid state determination to report accurate grid status
  7. WHEN the system configuration contains both an enabled field and history array, THE Market_Maker SHALL ignore the enabled field and use only the history array for state determination

Requirement 18: Probationary Grid Management

User Story: As a grid trader, I want the system to use conservative probationary grid parameters when confidence is moderate or ranges are newly detected, so that I can validate mean reversion behavior without excessive risk exposure during uncertain market conditions.

Acceptance Criteria

  1. WHEN confidence scores are between 0.60-0.80, THE Market_Maker SHALL recommend probationary grid parameters with reduced allocation and wider spacing
  2. WHEN creating probationary grids, THE Market_Maker SHALL use 50-60% of normal capital allocation as specified by restart_risk_scaling configuration
  3. WHEN creating probationary grids, THE Market_Maker SHALL use fewer grid levels (4-6 total) compared to normal grids (8-10 levels)
  4. WHEN creating probationary grids, THE Market_Maker SHALL use wider spacing of 0.45-0.55 × ATR compared to tighter normal spacing
  5. WHEN a probationary grid operates successfully for more than 36-48 hours with sustained range behavior, THE Market_Maker SHALL allow scaling up to normal grid parameters
  6. WHEN a probationary grid shows one-sided inventory build or volatility expansion, THE Market_Maker SHALL recommend stopping the grid quickly as a feature rather than failure
  7. WHEN range duration exceeds 48 hours and upper/lower bounds receive multiple clean rejections, THE Market_Maker SHALL transition from probationary to normal grid recommendations
  8. WHEN inventory oscillates without persistent bias during probationary period, THE Market_Maker SHALL consider this validation of mean reversion behavior
  9. WHEN probationary grids are recommended, THE Market_Maker SHALL clearly mark them as probe grids rather than commitment grids in recommendations
  10. WHEN confidence remains high without rising sharply during probationary period, THE Market_Maker SHALL maintain probationary status until additional validation criteria are met

Requirement 20: Historical Data Management and Cleanup

User Story: As a grid trader, I want the system to efficiently manage historical market data storage with automated cleanup and maintenance processes, so that I can maintain optimal system performance while preserving necessary data for analysis.

Acceptance Criteria

  1. WHEN historical data is insufficient for analysis, THE Market_Maker SHALL provide tools to collect historical market data for specified date ranges
  2. WHEN collecting historical data, THE Market_Maker SHALL support backfilling data for periods where no snapshots exist
  3. WHEN data retention limits are reached, THE Market_Maker SHALL provide automated cleanup processes to remove data beyond the required retention periods
  4. WHEN performing monthly maintenance, THE Market_Maker SHALL clean up unnecessary data while preserving data required for analysis
  5. WHEN performing monthly maintenance, THE Market_Maker SHALL re-aggregate data as needed to optimize storage and access patterns
  6. WHEN storing market data, THE Market_Maker SHALL organize data efficiently to support both current analysis and historical retention requirements

Graph View