@zigrivers/scaffold 3.14.0 → 3.15.0

package/content/knowledge/research/research-quant-requirements.md

@@ -0,0 +1,223 @@
+---
+name: research-quant-requirements
+description: Trading system research requirements including strategy hypothesis definition, market regime assumptions, risk budgets, data requirements, and performance targets
+topics: [research, quant-finance, requirements, hypothesis, risk-budget, performance-targets, validation]
+---
+
+Trading strategy research requires requirements that go far beyond "find a profitable strategy." Every research project must define the strategy hypothesis with falsifiable predictions, declare market regime assumptions that bound the strategy's expected operating environment, establish risk budgets that constrain position sizing and drawdown limits, specify data requirements including quality standards and survivorship-bias-free universes, set performance targets with statistical significance thresholds, and mandate out-of-sample validation protocols. Without these constraints, a backtest will always find something that looks good on historical data -- the question is whether it will survive contact with live markets.
+
+## Summary
+
+Define trading research requirements as structured hypotheses with quantitative success criteria (Sharpe > X, max drawdown < Y%), explicit market regime assumptions (trending, mean-reverting, crisis), risk budgets (max position size, sector exposure, portfolio heat), data requirements (instrument universe, frequency, lookback period, survivorship-bias-free), and mandatory out-of-sample validation windows. Separate primary optimization targets from hard guardrails. Require statistical significance testing (minimum trade count, bootstrap confidence intervals) before any strategy is considered validated.
+
+## Deep Guidance
+
+### Strategy Hypothesis Structure
+
+Every quant research hypothesis must specify the market inefficiency being exploited, the mechanism by which the strategy captures it, and the conditions under which it should fail:
+
+```python
+# configs/quant_hypothesis.py
+from dataclasses import dataclass, field
+from enum import Enum
+
+class MarketRegime(Enum):
+    TRENDING = "trending"
+    MEAN_REVERTING = "mean_reverting"
+    HIGH_VOLATILITY = "high_volatility"
+    LOW_VOLATILITY = "low_volatility"
+    CRISIS = "crisis"
+
+@dataclass
+class StrategyHypothesis:
+    """Structured hypothesis for a trading strategy research project."""
+    hypothesis_id: str
+    name: str
+    inefficiency: str  # What market inefficiency is being exploited
+    mechanism: str  # How the strategy captures the inefficiency
+    expected_regimes: list[MarketRegime]  # Regimes where strategy should work
+    failure_regimes: list[MarketRegime]  # Regimes where strategy should fail
+    instruments: list[str]  # Target instrument universe
+    timeframe: str  # Primary timeframe (e.g., "1D", "1H", "5m")
+    min_sharpe: float = 1.5  # Minimum Sharpe ratio target
+    max_drawdown: float = 0.15  # Maximum acceptable drawdown (15%)
+    min_trades: int = 100  # Minimum trades for statistical significance
+    oos_ratio: float = 0.3  # Out-of-sample data ratio
+
+    def validate(self) -> list[str]:
+        """Check hypothesis completeness."""
+        issues = []
+        if not self.inefficiency:
+            issues.append("Must specify the market inefficiency being exploited")
+        if not self.failure_regimes:
+            issues.append("Must specify regimes where strategy is expected to fail")
+        if self.min_trades < 30:
+            issues.append("Minimum 30 trades required for statistical significance")
+        if self.oos_ratio < 0.2:
+            issues.append("Out-of-sample ratio should be at least 20%")
+        return issues
+
+
+# Example hypothesis
+momentum_hypothesis = StrategyHypothesis(
+    hypothesis_id="H-001",
+    name="Adaptive momentum crossover",
+    inefficiency="Price trends persist due to institutional herding and gradual information diffusion",
+    mechanism="Dual moving average crossover with volatility-adaptive lookback periods",
+    expected_regimes=[MarketRegime.TRENDING, MarketRegime.LOW_VOLATILITY],
+    failure_regimes=[MarketRegime.MEAN_REVERTING, MarketRegime.CRISIS],
+    instruments=["SPY", "QQQ", "IWM", "EFA", "EEM"],
+    timeframe="1D",
+    min_sharpe=1.5,
+    max_drawdown=0.15,
+    min_trades=200,
+    oos_ratio=0.3,
+)
+```
+
+### Market Regime Assumptions
+
+Strategies do not operate in a vacuum. Document which market regimes the strategy targets and how regime detection will gate live deployment:
+
+```python
+# configs/regime_assumptions.py
+from dataclasses import dataclass
+
+@dataclass
+class RegimeAssumption:
+    """A documented assumption about market regime behavior."""
+    regime: str
+    volatility_range: tuple[float, float]  # Annualized vol range
+    correlation_expectation: str  # e.g., "cross-asset correlations < 0.5"
+    historical_frequency: float  # Fraction of time market is in this regime
+    strategy_expectation: str  # What we expect the strategy to do
+
+regime_assumptions = [
+    RegimeAssumption(
+        regime="trending_low_vol",
+        volatility_range=(0.08, 0.18),
+        correlation_expectation="Sector correlations moderate (0.3-0.6)",
+        historical_frequency=0.45,
+        strategy_expectation="Primary alpha generation, Sharpe > 2.0",
+    ),
+    RegimeAssumption(
+        regime="mean_reverting",
+        volatility_range=(0.10, 0.22),
+        correlation_expectation="Cross-asset correlations low (<0.3)",
+        historical_frequency=0.25,
+        strategy_expectation="Flat to slightly negative, drawdown < 5%",
+    ),
+    RegimeAssumption(
+        regime="crisis",
+        volatility_range=(0.30, 0.80),
+        correlation_expectation="Correlations spike to > 0.8",
+        historical_frequency=0.10,
+        strategy_expectation="Strategy should be flat (kill switch active)",
+    ),
+]
+```
+
+### Risk Budget Requirements
+
+Risk budgets define the hard constraints that no backtest optimization is allowed to violate. These are guardrails, not optimization targets:
+
+| Risk Dimension | Typical Constraint | Enforcement |
+|---------------|-------------------|-------------|
+| Max position size | 5-10% of portfolio per instrument | Pre-trade check |
+| Max sector exposure | 25-30% in any single sector | Pre-trade check |
+| Max portfolio heat | 2-3% total risk per day | Daily limit |
+| Max drawdown | 15-25% from peak | Kill switch |
+| Max correlation to benchmark | 0.7 (if seeking alpha, not beta) | Monthly review |
+| Min cash reserve | 10-20% uninvested | Rebalance trigger |
+
+```python
+# configs/risk_budget.py
+from dataclasses import dataclass
+
+@dataclass
+class RiskBudget:
+    """Hard risk constraints for strategy research."""
+    max_position_pct: float = 0.10  # 10% max per instrument
+    max_sector_pct: float = 0.30  # 30% max per sector
+    max_daily_risk_pct: float = 0.02  # 2% portfolio heat per day
+    max_drawdown_pct: float = 0.20  # 20% max drawdown (kill switch)
+    max_leverage: float = 1.0  # No leverage by default
+    min_cash_pct: float = 0.10  # 10% cash reserve
+    max_correlation_to_benchmark: float = 0.70
+
+    def check_position(self, position_pct: float) -> bool:
+        return position_pct <= self.max_position_pct
+
+    def check_drawdown(self, current_drawdown: float) -> bool:
+        return current_drawdown <= self.max_drawdown_pct
+```
+
+### Data Requirements Specification
+
+Data requirements must be explicit about instrument universe, frequency, lookback period, and quality standards:
+
+```python
+# configs/data_requirements.py
+from dataclasses import dataclass, field
+from datetime import date
+
+@dataclass
+class DataRequirements:
+    """Minimum data requirements for the research project."""
+    instruments: list[str]  # Ticker symbols or identifiers
+    frequency: str  # "1m", "5m", "1H", "1D"
+    start_date: date  # Earliest required data point
+    end_date: date  # Latest required data point
+    survivorship_bias_free: bool = True  # Require delisted stocks
+    adjusted_for_splits: bool = True  # Corporate action adjusted
+    adjusted_for_dividends: bool = True  # Dividend adjusted
+    min_history_days: int = 252 * 5  # 5 years minimum
+    max_gap_days: int = 5  # Max consecutive missing days
+    required_fields: list[str] = field(
+        default_factory=lambda: ["open", "high", "low", "close", "volume"]
+    )
+
+    def validate_dataset(self, df) -> list[str]:
+        """Validate a dataset meets requirements."""
+        issues = []
+        for col in self.required_fields:
+            if col not in df.columns:
+                issues.append(f"Missing required field: {col}")
+        if df.isnull().any().any():
+            null_pct = df.isnull().sum().sum() / df.size * 100
+            if null_pct > 1.0:
+                issues.append(f"Null values: {null_pct:.1f}% (max 1%)")
+        return issues
+```
+
+### Performance Target Framework
+
+Performance targets must distinguish between the optimization target (one metric), secondary indicators (useful but not optimized), and hard guardrails (never violated):
+
+| Category | Metric | Target | Rationale |
+|----------|--------|--------|-----------|
+| **Primary** | Sharpe ratio (OOS) | > 1.5 | Risk-adjusted return is the universal benchmark |
+| Secondary | Sortino ratio | > 2.0 | Penalizes downside more than upside volatility |
+| Secondary | Win rate | > 45% | Indicates strategy consistency |
+| Secondary | Profit factor | > 1.5 | Gross profit / gross loss |
+| **Guardrail** | Max drawdown | < 20% | Capital preservation |
+| **Guardrail** | Min trades | > 100 | Statistical significance |
+| **Guardrail** | Max consecutive losses | < 10 | Psychological tolerance |
+
+### Out-of-Sample Validation Requirements
+
+No strategy is considered validated until it passes out-of-sample testing. The validation protocol must be defined before the first experiment runs:
+
+1. **Time-based split**: Reserve the most recent 30% of data as out-of-sample. Never touch it during development.
+2. **Walk-forward validation**: Use rolling windows (e.g., 252-day train, 63-day test) to simulate realistic deployment.
+3. **Multiple market regimes**: OOS period must include at least two distinct regime types.
+4. **Statistical significance**: Bootstrap the strategy returns (1000+ iterations) and require the 5th percentile Sharpe > 0.
+5. **Comparison to benchmarks**: Beat buy-and-hold AND a simple momentum benchmark on a risk-adjusted basis.
+
+### Requirements Anti-Patterns in Quant Research
+
+- **Overfitting the requirements**: Setting Sharpe target to match exactly what your best backtest achieved.
+- **Survivorship bias in instrument selection**: Using today's S&P 500 constituents for a 20-year backtest.
+- **Ignoring transaction costs**: A strategy that trades 50 times per day needs very different targets than one that trades monthly.
+- **No regime awareness**: "Works in all market conditions" is a red flag -- no strategy does.
+- **Optimizing guardrails**: If max drawdown is a guardrail, do not run optimizations that minimize drawdown -- it becomes a de facto primary target and distorts the search.

package/content/knowledge/research/research-quant-risk.md

@@ -0,0 +1,469 @@
+---
+name: research-quant-risk
+description: Risk management for trading research including regime detection, tail risk measures, correlation breakdown, position limits, drawdown controls, and kill switches
+topics: [research, quant-finance, risk, regime-detection, tail-risk, var, cvar, correlation, drawdown-controls, kill-switch]
+---
+
+Risk management in quantitative finance is not an afterthought bolted onto a profitable strategy -- it is the primary constraint that determines whether a strategy survives long enough to realize its edge. Markets exhibit non-stationary behavior: correlations spike during crises, volatility clusters in ways that violate normal distribution assumptions, and tail events occur far more frequently than Gaussian models predict. A strategy without regime awareness, tail risk measurement, position limits, and automated kill switches is not a strategy -- it is a gamble.
+
+## Summary
+
+Implement risk management as a layered system: regime detection (HMM, volatility clustering) determines the current market state and gates strategy behavior; tail risk measures (VaR, CVaR, stress testing) quantify worst-case scenarios beyond what standard deviation captures; position limits (max position size, sector exposure, concentration) prevent over-commitment; drawdown controls (max drawdown threshold, recovery rules) cap cumulative losses; and kill switches (automated circuit breakers) halt all trading when conditions exceed safe operating parameters. Every layer operates independently -- if one fails, the others still protect capital.
+
+## Deep Guidance
+
+### Regime Detection
+
+Market regimes (trending, mean-reverting, high-volatility, crisis) fundamentally change strategy performance. Detect regimes to gate strategy behavior:
+
+```python
+# risk/regime_detection.py
+import numpy as np
+import pandas as pd
+from dataclasses import dataclass
+from enum import Enum
+
+class Regime(Enum):
+    LOW_VOL = "low_volatility"
+    NORMAL = "normal"
+    HIGH_VOL = "high_volatility"
+    CRISIS = "crisis"
+
+@dataclass
+class RegimeState:
+    """Current regime classification with confidence."""
+    regime: Regime
+    confidence: float  # 0-1
+    volatility: float  # Current annualized volatility
+    vol_percentile: float  # Percentile vs. history
+
+class VolatilityRegimeDetector:
+    """
+    Simple volatility-based regime detector.
+
+    Uses realized volatility percentiles relative to history.
+    More robust than HMM for live deployment (no fitting required).
+    """
+
+    def __init__(
+        self,
+        lookback: int = 20,
+        history_window: int = 252 * 5,
+        crisis_percentile: float = 95,
+        high_vol_percentile: float = 75,
+        low_vol_percentile: float = 25,
+    ):
+        self.lookback = lookback
+        self.history_window = history_window
+        self.crisis_pct = crisis_percentile
+        self.high_vol_pct = high_vol_percentile
+        self.low_vol_pct = low_vol_percentile
+
+    def detect(self, returns: pd.Series) -> RegimeState:
+        """Classify current regime from return history."""
+        recent_vol = returns.tail(self.lookback).std() * np.sqrt(252)
+        historical_vols = (
+            returns.rolling(self.lookback).std() * np.sqrt(252)
+        ).dropna().tail(self.history_window)
+
+        percentile = (historical_vols < recent_vol).mean() * 100
+
+        if percentile >= self.crisis_pct:
+            regime = Regime.CRISIS
+            confidence = min((percentile - self.crisis_pct) / 5 + 0.8, 1.0)
+        elif percentile >= self.high_vol_pct:
+            regime = Regime.HIGH_VOL
+            confidence = 0.7
+        elif percentile <= self.low_vol_pct:
+            regime = Regime.LOW_VOL
+            confidence = 0.7
+        else:
+            regime = Regime.NORMAL
+            confidence = 0.8
+
+        return RegimeState(
+            regime=regime,
+            confidence=confidence,
+            volatility=recent_vol,
+            vol_percentile=percentile,
+        )
+
+
+class HMMRegimeDetector:
+    """
+    Hidden Markov Model regime detector.
+
+    Fits a 2-3 state HMM to return series. Better for research
+    (offline analysis) than live trading (requires refitting).
+    """
+
+    def __init__(self, n_states: int = 3, lookback: int = 252 * 3):
+        self.n_states = n_states
+        self.lookback = lookback
+        self.model = None
+
+    def fit(self, returns: pd.Series) -> None:
+        """Fit HMM to historical returns."""
+        try:
+            from hmmlearn.hmm import GaussianHMM
+        except ImportError:
+            raise ImportError("pip install hmmlearn for HMM regime detection")
+
+        data = returns.tail(self.lookback).values.reshape(-1, 1)
+        self.model = GaussianHMM(
+            n_components=self.n_states,
+            covariance_type="full",
+            n_iter=100,
+            random_state=42,
+        )
+        self.model.fit(data)
+
+    def predict(self, returns: pd.Series) -> np.ndarray:
+        """Predict regime states for each time step."""
+        if self.model is None:
+            raise RuntimeError("Call fit() before predict()")
+        data = returns.values.reshape(-1, 1)
+        return self.model.predict(data)
+```
+
+### Tail Risk Measures
+
+Standard deviation understates risk because market returns have fat tails. Use VaR and CVaR for tail risk:
+
+```python
+# risk/tail_risk.py
+import numpy as np
+import pandas as pd
+
+def value_at_risk(
+    returns: pd.Series,
+    confidence: float = 0.95,
+    method: str = "historical",
+    lookback: int = 252,
+) -> float:
+    """
+    Value at Risk — maximum expected loss at a given confidence level.
+
+    Args:
+        confidence: Confidence level (e.g., 0.95 = 95%).
+        method: "historical" (percentile) or "parametric" (Gaussian).
+        lookback: Number of observations to use.
+
+    Returns:
+        VaR as a negative number (loss).
+    """
+    data = returns.tail(lookback).dropna()
+
+    if method == "historical":
+        return float(np.percentile(data, (1 - confidence) * 100))
+    elif method == "parametric":
+        from scipy.stats import norm
+        z = norm.ppf(1 - confidence)
+        return float(data.mean() + z * data.std())
+    else:
+        raise ValueError(f"Unknown VaR method: {method}")
+
+
+def conditional_var(
+    returns: pd.Series,
+    confidence: float = 0.95,
+    lookback: int = 252,
+) -> float:
+    """
+    Conditional VaR (Expected Shortfall) — average loss beyond VaR.
+
+    CVaR answers: "When we do lose more than VaR, how bad is it on average?"
+    Always worse than VaR, captures tail severity.
+    """
+    data = returns.tail(lookback).dropna()
+    var = value_at_risk(data, confidence, method="historical", lookback=lookback)
+    tail_losses = data[data <= var]
+    return float(tail_losses.mean()) if len(tail_losses) > 0 else var
+
+
+def stress_test(
+    portfolio_returns: pd.Series,
+    scenarios: dict[str, tuple[str, str]],
+    market_data: pd.DataFrame,
+) -> dict[str, dict]:
+    """
+    Stress test portfolio against historical crisis scenarios.
+
+    Args:
+        scenarios: Dict of scenario_name -> (start_date, end_date).
+    """
+    results = {}
+    for name, (start, end) in scenarios.items():
+        mask = (portfolio_returns.index >= start) & (portfolio_returns.index <= end)
+        scenario_returns = portfolio_returns[mask]
+
+        if len(scenario_returns) == 0:
+            continue
+
+        results[name] = {
+            "total_return": float((1 + scenario_returns).prod() - 1),
+            "max_drawdown": float(_max_dd(scenario_returns)),
+            "worst_day": float(scenario_returns.min()),
+            "volatility": float(scenario_returns.std() * np.sqrt(252)),
+            "days": len(scenario_returns),
+        }
+
+    return results
+
+def _max_dd(returns: pd.Series) -> float:
+    equity = (1 + returns).cumprod()
+    return float((equity / equity.cummax() - 1).min())
+
+# Standard stress test scenarios
+CRISIS_SCENARIOS = {
+    "gfc_2008": ("2008-09-01", "2009-03-31"),
+    "covid_2020": ("2020-02-19", "2020-03-23"),
+    "dot_com_2000": ("2000-03-10", "2002-10-09"),
+    "flash_crash_2010": ("2010-05-06", "2010-05-06"),
+    "vol_shock_2018": ("2018-02-01", "2018-02-09"),
+    "rate_hike_2022": ("2022-01-03", "2022-10-12"),
+}
+```
+
+### Correlation Breakdown
+
+During crises, asset correlations spike toward 1.0, destroying diversification benefits exactly when they are most needed:
+
+```python
+# risk/correlation.py
+import numpy as np
+import pandas as pd
+
+def rolling_correlation_matrix(
+    returns: pd.DataFrame,
+    window: int = 60,
+) -> pd.DataFrame:
+    """Compute rolling correlation matrix (returns latest window)."""
+    return returns.tail(window).corr()
+
+
+def detect_correlation_spike(
+    returns: pd.DataFrame,
+    window: int = 20,
+    history_window: int = 252,
+    threshold_percentile: float = 90,
+) -> dict:
+    """
+    Detect when average pairwise correlation exceeds historical norms.
+
+    Returns:
+        Dict with current_avg_corr, historical_percentile, is_spike.
+    """
+    # Current average pairwise correlation
+    current_corr = returns.tail(window).corr()
+    mask = np.triu(np.ones_like(current_corr, dtype=bool), k=1)
+    current_avg = float(current_corr.values[mask].mean())
+
+    # Historical rolling average correlations
+    rolling_avgs = []
+    for i in range(history_window, len(returns)):
+        chunk = returns.iloc[i - window:i]
+        corr = chunk.corr()
+        avg = float(corr.values[mask].mean())
+        rolling_avgs.append(avg)
+
+    percentile = (np.array(rolling_avgs) < current_avg).mean() * 100
+
+    return {
+        "current_avg_corr": current_avg,
+        "historical_percentile": percentile,
+        "is_spike": percentile > threshold_percentile,
+    }
+```
+
+### Position Limits
+
+Hard limits that prevent any single position or concentration from threatening the portfolio:
+
+```python
+# risk/position_limits.py
+from dataclasses import dataclass
+
+@dataclass
+class PositionLimits:
+    """Hard position limits enforced before every trade."""
+    max_position_pct: float = 0.10  # 10% max per instrument
+    max_sector_pct: float = 0.30  # 30% max per sector
+    max_concentration_pct: float = 0.50  # 50% max in top 3 positions
+    max_gross_exposure: float = 1.0  # 100% (no leverage)
+    max_net_exposure: float = 0.50  # 50% max net long or short
+    max_single_day_turnover: float = 0.30  # 30% max daily turnover
+
+    def check_trade(
+        self,
+        proposed_position_pct: float,
+        current_sector_pct: float,
+        current_gross_exposure: float,
+    ) -> tuple[bool, str]:
+        """Check if a proposed trade violates any limit."""
+        if proposed_position_pct > self.max_position_pct:
+            return False, f"Position {proposed_position_pct:.1%} exceeds max {self.max_position_pct:.1%}"
+        if current_sector_pct > self.max_sector_pct:
+            return False, f"Sector exposure {current_sector_pct:.1%} exceeds max {self.max_sector_pct:.1%}"
+        if current_gross_exposure > self.max_gross_exposure:
+            return False, f"Gross exposure {current_gross_exposure:.1%} exceeds max {self.max_gross_exposure:.1%}"
+        return True, "OK"
+```
+
+### Drawdown Controls
+
+Drawdown controls cap cumulative losses and enforce recovery discipline:
+
+```python
+# risk/drawdown_controls.py
+from dataclasses import dataclass
+from enum import Enum
+
+class DrawdownAction(Enum):
+    NORMAL = "normal"  # Full position sizing
+    REDUCED = "reduced"  # Half position sizes
+    HALTED = "halted"  # No new positions (close existing)
+
+@dataclass
+class DrawdownController:
+    """Multi-tier drawdown control system."""
+    warn_threshold: float = 0.10  # 10% — log warning, reduce size
+    halt_threshold: float = 0.15  # 15% — stop opening new positions
+    kill_threshold: float = 0.20  # 20% — close everything
+    recovery_required: float = 0.50  # Must recover 50% of drawdown to resume
+
+    def evaluate(self, current_drawdown: float,
+                 recovered_pct: float = 0.0) -> DrawdownAction:
+        """
+        Determine trading action based on current drawdown.
+
+        Args:
+            current_drawdown: Current drawdown as positive fraction (e.g., 0.12 = 12%).
+            recovered_pct: If in recovery mode, fraction of drawdown recovered.
+        """
+        dd = abs(current_drawdown)
+
+        if dd >= self.kill_threshold:
+            return DrawdownAction.HALTED
+
+        if dd >= self.halt_threshold:
+            if recovered_pct < self.recovery_required:
+                return DrawdownAction.HALTED
+            return DrawdownAction.REDUCED
+
+        if dd >= self.warn_threshold:
+            return DrawdownAction.REDUCED
+
+        return DrawdownAction.NORMAL
+
+    def scale_factor(self, action: DrawdownAction) -> float:
+        """Return position size multiplier for the given action."""
+        return {
+            DrawdownAction.NORMAL: 1.0,
+            DrawdownAction.REDUCED: 0.5,
+            DrawdownAction.HALTED: 0.0,
+        }[action]
+```
+
+### Kill Switches
+
+Kill switches are automated circuit breakers that halt all activity when conditions become dangerous. They are the last line of defense:
+
+```python
+# risk/kill_switch.py
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class KillSwitchConfig:
+    """Automated circuit breaker configuration."""
+    max_daily_loss_pct: float = 0.05  # 5% daily loss limit
+    max_drawdown_pct: float = 0.20  # 20% total drawdown limit
+    max_consecutive_losses: int = 10  # Stop after 10 straight losses
+    max_volatility_multiple: float = 3.0  # 3x normal vol = halt
+    cooldown_period: timedelta = timedelta(hours=24)  # Wait before resuming
+
+class KillSwitch:
+    """
+    Automated trading halt system.
+
+    Evaluates multiple independent triggers. If ANY trigger fires,
+    all trading stops immediately. Requires manual acknowledgment
+    or cooldown period before resuming.
+    """
+
+    def __init__(self, config: KillSwitchConfig):
+        self.config = config
+        self.is_active = False
+        self.trigger_reason = ""
+        self.triggered_at: datetime | None = None
+
+    def check(
+        self,
+        daily_pnl_pct: float,
+        total_drawdown_pct: float,
+        consecutive_losses: int,
+        current_vol_multiple: float,
+    ) -> bool:
+        """
+        Check all kill switch triggers.
+
+        Returns True if trading should be halted.
+        """
+        if abs(daily_pnl_pct) >= self.config.max_daily_loss_pct:
+            self._trigger(f"Daily loss {daily_pnl_pct:.1%} exceeds {self.config.max_daily_loss_pct:.1%}")
+            return True
+
+        if abs(total_drawdown_pct) >= self.config.max_drawdown_pct:
+            self._trigger(f"Drawdown {total_drawdown_pct:.1%} exceeds {self.config.max_drawdown_pct:.1%}")
+            return True
+
+        if consecutive_losses >= self.config.max_consecutive_losses:
+            self._trigger(f"{consecutive_losses} consecutive losses")
+            return True
+
+        if current_vol_multiple >= self.config.max_volatility_multiple:
+            self._trigger(f"Volatility {current_vol_multiple:.1f}x normal")
+            return True
+
+        return False
+
+    def _trigger(self, reason: str) -> None:
+        self.is_active = True
+        self.trigger_reason = reason
+        self.triggered_at = datetime.now()
+        logger.critical("KILL SWITCH ACTIVATED: %s", reason)
+
+    def can_resume(self) -> bool:
+        """Check if cooldown period has elapsed."""
+        if not self.is_active or self.triggered_at is None:
+            return True
+        elapsed = datetime.now() - self.triggered_at
+        return elapsed >= self.config.cooldown_period
+
+    def reset(self, acknowledge: bool = False) -> None:
+        """Reset kill switch (requires explicit acknowledgment)."""
+        if not acknowledge:
+            raise ValueError("Kill switch reset requires explicit acknowledgment")
+        logger.warning("Kill switch reset by operator (was: %s)", self.trigger_reason)
+        self.is_active = False
+        self.trigger_reason = ""
+        self.triggered_at = None
+```
+
+### Risk Management Layering
+
+Risk controls operate in layers, each independent of the others:
+
+| Layer | Check | Frequency | Response |
+|-------|-------|-----------|----------|
+| 1. Regime | Market state classification | Daily | Adjust strategy parameters |
+| 2. Position limits | Per-trade constraint check | Pre-trade | Reject or resize trade |
+| 3. Drawdown control | Cumulative loss monitoring | Per-trade | Reduce size or halt |
+| 4. Kill switch | Emergency circuit breaker | Real-time | Halt all trading |
+| 5. Stress test | Scenario-based exposure | Weekly | Adjust portfolio if stressed |
+
+Never rely on a single layer. Assume each layer will fail eventually -- the redundancy is what protects capital.