@pgnio/helios-mcp 0.0.0-stage → 0.2.1

package/docs/ai-agent-indicators/macd_divergence.txt

@@ -0,0 +1,133 @@
+================================================================================
+INDICATOR: MACD_DIVERGENCE — MACD HISTOGRAM DIVERGENCE
+================================================================================
+id:                 macd_divergence
+data_field:         indicators.macd_divergence
+type:               CATEGORICAL
+values:             BULLISH | BEARISH | "" (empty string = no divergence)
+update_rate:        per_tick
+latency_profile:    LAGGING (requires minimum 2 peaks/troughs to be detected)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+macd_divergence detects classic price-MACD histogram divergence by comparing
+rolling peak and trough values in the MACD histogram against corresponding
+price high/low levels.
+
+Implementation:
+  MAX_PEAKS = 5 peak inputs, MAX_PEAKS = 5 trough inputs maintained as
+  rolling windows.
+
+  A histogram PEAK is recorded when histogram switches from positive to near-zero
+  or negative after a positive run. A histogram TROUGH is recorded when it
+  switches from negative to near-zero or positive after a negative run.
+
+  BEARISH DIVERGENCE (histogram bearish):
+    Requires >= 2 histogram peaks in rolling window.
+    price makes HIGHER HIGH (priceHigh[current] > priceHigh[prior])
+    AND histogram peak makes LOWER HIGH (histPeak[current] < histPeak[prior])
+    → Price is rising but MACD histogram peaks are declining.
+      Upside price momentum is structurally weakening.
+
+  BULLISH DIVERGENCE (histogram bullish):
+    Requires >= 2 histogram troughs in rolling window.
+    price makes LOWER LOW (priceLow[current] < priceLow[prior])
+    AND histogram trough makes HIGHER LOW (histTrough[current] > histTrough[prior])
+    → Price is dropping but MACD histogram troughs are becoming less negative.
+      Downside price momentum is structurally weakening.
+
+  "" (empty string): no divergence detected, or insufficient data for comparison.
+
+--------------------------------------------------------------------------------
+IMPORTANT DISTINCTION FROM RSI DIVERGENCE
+--------------------------------------------------------------------------------
+# macd_divergence is computed from PEAK/TROUGH comparison (swing analysis).
+# rsi_divergence is computed from SLOPE comparison over 20-bar windows.
+# These are independent computations using different methods.
+# Agreement between both divergences is a materially stronger signal.
+
+# macd_divergence uses LABELED peaks/troughs (requires swing reversal to record).
+# It is typically LESS frequent than rsi_divergence but captures
+# clearer structural commitments in momentum.
+
+--------------------------------------------------------------------------------
+STATE DEFINITIONS
+--------------------------------------------------------------------------------
+  BULLISH
+    Price has made a lower low but the corresponding MACD histogram trough
+    is less negative than the prior one. Less selling pressure at a lower
+    price point — the downswing is losing force. Context for a return watch:
+    this does not indicate when or from where price will recover.
+
+  BEARISH
+    Price has made a higher high but the corresponding MACD histogram peak
+    is smaller than the prior one. Less buying pressure at a higher price
+    point — the upswing is losing force.
+
+  "" (empty string / no divergence)
+    Neither condition met, or there are insufficient peaks/troughs in the
+    rolling window to perform a comparison. NONE is the expected state during
+    straight-line trending periods.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.macd_histogram | REQUIRED_COMPANION
+    macd_divergence is computed from macd_histogram peak/trough tracking.
+    The current histogram sign provides context: bearish divergence forming
+    while histogram is still positive is an early warning; forming after
+    a cross makes it a later-stage confirmation.
+
+  indicators.macd_signal | CONTEXT
+    IF macd_divergence = BEARISH AND macd_signal later transitions to BEARISH_CROSS
+      → Divergence was a leading warning; cross is lagging confirmation.
+         Combination increases conviction for downside momentum shift.
+
+  indicators.rsi_divergence | CROSS_VALIDATE
+    Independent divergence detection method. Agreement between both
+    (macd_divergence = BEARISH AND rsi_divergence = BEARISH_DIVERGENCE)
+    materially strengthens the signal. Disagreement reduces confidence.
+
+  indicators.bayesian_overbought | CONTEXT
+    IF macd_divergence = BEARISH AND bayesian_overbought > 0.85
+      → Both momentum and RSI metrics at historically extreme levels while
+         divergence is forming. Compound fatigue signal.
+
+  indicators.regime | CONTEXT
+    Divergence is most predictive when regime is EXHAUST_UP or EXHAUST_DN.
+    Divergence in CASCADE conditions often fails (cascades can sustain
+    diminishing histogram peaks while price keeps making higher highs).
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Regime: CASCADE/PARABOLIC conditions have high false-positive rate for divergence.
+  2  Read divergence state.
+  3  If not empty: cross-validate with rsi_divergence.
+  4  Track whether macd_signal subsequently confirms with a cross.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF fewer than 2 recorded peaks (for BEARISH) or 2 recorded troughs (for BULLISH)
+    → Empty string is expected. Do not interpret as "no divergence" — it may
+       be insufficient data. Check tick age since start-up.
+
+  IF regime = CASCADE or PARABOLIC
+    → Divergence in extreme trending conditions has high false positive rate.
+       Discount macd_divergence during these regimes.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF BULLISH macd_divergence is used as a stop-exit point
+    → INCORRECT SCOPE. Divergence indicates weakening momentum; it does NOT
+       indicate a floor. Price can continue making lower lows while histogram
+       troughs improve. Divergence can persist across many ticks.
+
+  IF divergence is expected to appear immediately after a pivot
+    → STRUCTURAL CONSTRAINT. macd_divergence requires at least 2 full
+       peak/trough cycle completions. It will not appear on the first
+       swing — it requires a COMPARISON between at least two swings.
+       Newly formed momentum shifts won't have divergence yet.

package/docs/ai-agent-indicators/macd_histogram.txt

@@ -0,0 +1,145 @@
+================================================================================
+INDICATOR: MACD_HISTOGRAM — MACD HISTOGRAM (NORMALIZED)
+================================================================================
+id:                 macd_histogram
+data_field:         indicators.macd_histogram
+type:               NUMERIC
+range:              Unbounded (normalized by price; practically ±5 for most assets)
+precision:          4 decimal places
+update_rate:        per_tick
+latency_profile:    LAGGING (EMA-based, inherits smoothing from 26-period slow EMA)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+Standard MACD(12, 26, 9) computed on the most recent close prices.
+
+EMA parameters:
+  alphaFast   = 2 / (12 + 1) = 0.1538
+  alphaSlow   = 2 / (26 + 1) = 0.0741
+  alphaSignal = 2 / (9 + 1)  = 0.2000
+
+  emaFast    = EMA(closes, alphaFast)
+  emaSlow    = EMA(closes, alphaSlow)
+  macdLine   = emaFast - emaSlow
+  signalEMA  = EMA(macdLine, alphaSignal)
+  histogram  = macdLine - signalEMA
+
+Normalization for cross-asset comparison:
+  histogramNorm = histogram / lastClose × 100
+
+The normalized histogram (histogramNorm) is what is stored in indicators.macd_histogram.
+This allows comparison of MACD strength across assets with different price levels.
+
+Histogram behavior:
+  Positive value   → macdLine above signalEMA → bullish momentum
+  Negative value   → macdLine below signalEMA → bearish momentum
+  Growing positive → momentum accelerating upward
+  Shrinking positive → momentum decelerating but still bullish
+  Zero crossing (- to +) → triggers BULLISH_CROSS in macd_signal
+  Zero crossing (+ to -) → triggers BEARISH_CROSS in macd_signal
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+# Ranges are relative — values depend on asset volatility and regime.
+# Use magnitude comparisons to recent history rather than absolute thresholds.
+
+  value > 0 AND growing (vs prior tick reading)
+    Bullish momentum accelerating. macdLine is above signal and the gap is
+    widening. Short-term EMA is separating further from slow EMA. Associated
+    with early-to-mid breakout or trend conditions.
+
+  value > 0 AND shrinking (vs prior tick reading)
+    Bullish momentum decelerating. The gap between macdLine and signal is
+    narrowing. MACD is still bullish but fading. Associated with later-stage
+    trends or pullback conditions within a bullish structure.
+
+  value ≈ 0 (near zero from above, crossing down)
+    Bearish cross imminent or just occurred. Triggers BEARISH_CROSS in
+    macd_signal. Momentum has shifted from bullish to neutral/bearish.
+
+  value < 0 AND growing in magnitude (more negative)
+    Bearish momentum accelerating. The downside MACD gap is widening.
+
+  value < 0 AND shrinking in magnitude (less negative)
+    Bearish momentum decelerating. Downside fading. May precede a bullish
+    cross if combined with RSI divergence or HMI recovery.
+
+  value ≈ 0 (near zero from below, crossing up)
+    Bullish cross imminent or just occurred. Triggers BULLISH_CROSS.
+
+--------------------------------------------------------------------------------
+TRAJECTORY — HOW TO DETECT GROWING vs SHRINKING
+--------------------------------------------------------------------------------
+# macd_histogram does not have a built-in velocity field.
+# Compute trajectory from two consecutive readings:
+  IF macd_histogram[current] > macd_histogram[prior] → growing (more positive)
+  IF macd_histogram[current] < macd_histogram[prior] → shrinking (less positive)
+#
+# Or use macd_signal state (BULLISH_CROSS, BEARISH_CROSS) as proxy for direction.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.macd_signal | REQUIRED_COMPANION
+    macd_signal is derived from this same MACD computation and encodes the
+    most recent directional state (CROSS events). Check macd_signal
+    to know whether a zero crossing just occurred.
+
+  indicators.macd_divergence | COMPANION
+    macd_divergence monitors peaks and troughs in the histogram for
+    price-MACD divergence patterns. See macd_divergence.txt.
+
+  indicators.hmi | CROSS_VALIDATE
+    HMI and MACD both capture momentum but via different computations
+    (Kalman/Bayesian vs EMA-based). They should generally agree on direction.
+    IF hmi >= 50 AND macd_histogram < 0: conflicting signals. One is lagging.
+    IF hmi < -30 AND macd_histogram > 0: MACD recently crossed positive but
+      medium-TF alignment (captured by hmi) remains negative. Potential
+      false MACD positive in a bearish broader context.
+
+  indicators.weighted_rsi | CONTEXT
+    MACD captures trend momentum; RSI captures oscillation/overextension.
+    Both can diverge from price motion and both reward that divergence
+    as a potential signal. Cross-referencing both divergences strengthens
+    the combined signal.
+
+  indicators.regime | GATE
+    IF regime = CHOP: MACD produces frequent low-quality crosses. Discard
+    MACD signals in CHOP until regime confirms directional state.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Regime gate: ignore MACD crosses in CHOP.
+  2  Read value sign (positive vs negative).
+  3  Read trend of value (growing vs shrinking vs at zero).
+  4  Read macd_signal for cross event state.
+  5  Check macd_divergence for peak-based divergence.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF regime = CHOP or CONSOL
+    → MACD crosses in non-directional conditions are statistically unreliable.
+
+  IF fewer than 26 close prices on the slow EMA
+    → Initialization period. EMA output is heavily biased. Treat as warm-up.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF BULLISH_CROSS is used as a standalone entry signal
+    → INCOMPLETE. A cross merely signals that short-term EMA crossed above
+       signal EMA. In CHOP regimes this happens repeatedly with no follow-through.
+       Require: regime NOT in CHOP + hmi direction confirmation before acting.
+
+  IF histogram magnitude is compared across different assets
+    → CORRECT USE requires normalized form (histogramNorm). Confirm you are
+       reading indicators.macd_histogram and not an internal un-normalized value.
+
+  IF lagging is not accounted for after fast moves
+    → The slow EMA (26-period, alpha=0.074) takes many ticks to respond
+       to sudden moves. After a sharp impulse, MACD may not cross for 5-10+ ticks.
+       Regime and hmi detect momentum faster; MACD confirms after the fact.

package/docs/ai-agent-indicators/macd_signal.txt

@@ -0,0 +1,119 @@
+================================================================================
+INDICATOR: MACD_SIGNAL — MACD SIGNAL STATE
+================================================================================
+id:                 macd_signal
+data_field:         indicators.macd_signal
+type:               CATEGORICAL
+values:             BULLISH_CROSS | BEARISH_CROSS | BULLISH | BEARISH | NEUTRAL
+update_rate:        per_tick
+latency_profile:    LAGGING (derived from EMA-based MACD system)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+macd_signal encodes the directional state of the MACD histogram computation.
+It is derived from the same MACD(12, 26, 9) system as indicators.macd_histogram.
+
+State rules:
+  BULLISH_CROSS:
+    histogram crossed from <= 0 to > 0 this tick (or very recently).
+    Marks the end of a bearish MACD phase and start of a bullish one.
+    This is the signal that would trigger a traditional MACD buy signal.
+
+  BEARISH_CROSS:
+    histogram crossed from >= 0 to < 0 this tick.
+    Marks the end of a bullish MACD phase and start of a bearish one.
+
+  BULLISH:
+    histogram > 0 but no cross occurred this tick.
+    Continuation of prior bullish MACD phase. macdLine still above signal.
+
+  BEARISH:
+    histogram < 0 but no cross occurred this tick.
+    Continuation of prior bearish MACD phase. macdLine still below signal.
+
+  NEUTRAL:
+    histogram ≈ 0. At/near the zero line without a detected cross, or
+    during EMA initialization period.
+
+--------------------------------------------------------------------------------
+STATE DEFINITIONS
+--------------------------------------------------------------------------------
+  BULLISH_CROSS
+    Most significant upside signal from MACD. Momentum has just shifted from
+    bearish EMA structure to bullish. Highest value when accompanied by an
+    expanding histogram (histogram growing positive after the cross).
+    Context required: Is this a trend resumption or a countertrend bounce?
+    Check hmi direction to distinguish.
+
+  BEARISH_CROSS
+    Most significant downside signal from MACD. Mirror of BULLISH_CROSS.
+    Most reliable when preceded by a period of histogram shrinkage (momentum
+    was already decelerating before the cross occurred).
+
+  BULLISH
+    Bullish phase in progress. The MACD histogram has been positive for
+    some duration. Check histogram magnitude and trend to assess vigor.
+    A shrinking positive histogram in BULLISH state precedes BEARISH_CROSS.
+
+  BEARISH
+    Mirror of BULLISH. Downside MACD phase in progress.
+
+  NEUTRAL
+    At the MACD zero line. Either a cross is about to occur, or histogram is
+    bouncing near zero without committing to either direction (common in CHOP).
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.macd_histogram | REQUIRED_COMPANION
+    macd_signal encodes the state; macd_histogram provides the magnitude.
+    Use macd_signal to identify cross events, then use macd_histogram to
+    assess whether the cross has building momentum behind it.
+
+  indicators.macd_divergence | CONTEXT
+    Prior divergence that resolves into a cross is a higher-quality signal.
+    IF macd_divergence = BULLISH AND then macd_signal transitions to BULLISH_CROSS
+      → Divergence-confirmed cross. Stronger signal.
+
+  indicators.hmi | CROSS_VALIDATE
+    IF macd_signal = BULLISH_CROSS AND hmi < -40
+      → MACD momentum cross but broader timeframe alignment is still very
+         bearish. This may be a countertrend recovery, not a trend reversal.
+    IF macd_signal = BULLISH AND hmi >= 60
+      → Both indicators in sustained bullish agreement. Trend continuation
+         is the dominant condition.
+
+  indicators.regime | GATE
+    IF regime = CHOP: all MACD signal states are unreliable.
+    Do not use BULLISH_CROSS or BEARISH_CROSS in CHOP. They will fire
+    frequently with no follow-through.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Regime gate: if CHOP, all MACD signal states are unreliable.
+  2  Read state.
+  3  For BULLISH_CROSS or BEARISH_CROSS: cross-validate with hmi direction and regime context.
+  4  For BULLISH or BEARISH: read histogram magnitude and trend.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF regime IN [CHOP, CONSOL, RANGING]: discard signal.
+
+  IF initialization period (< 26 closes seen): NEUTRAL is expected.
+  Treat NEUTRAL in first 50 ticks as warm-up noise.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF every BULLISH_CROSS triggers a trade
+    → OVER-FITTING TO SIGNAL. In non-trending or choppy conditions, MACD
+       crosses are false signals. Apply context filter (regime + hmi) first.
+
+  IF BULLISH state is treated as "buy" and BEARISH as "sell"
+    → INCORRECT SCOPE. BULLISH/BEARISH describe the MACD phase (histogram
+       above/below zero) — not market direction readiness. A BEARISH phase
+       with a shrinking histogram in a trending market is a normal pause,
+       not a sell signal.

package/docs/ai-agent-indicators/market_structure.txt

@@ -0,0 +1,201 @@
+================================================================================
+INDICATOR: MARKET_STRUCTURE — MARKET STRUCTURE STATE
+================================================================================
+id:                 market_structure
+data_field:         indicators.market_structure
+type:               CATEGORICAL (with confidence sub-field)
+values:             RANGING | CONSOL | BREAKING_UP | BREAKING_DOWN |
+                    CONFIRMED_BREAK_UP | CONFIRMED_BREAK_DOWN |
+                    TEST_RS | FAILED_BREAK
+update_rate:        per_tick (with HMM smoothing)
+latency_profile:    LAGGING (9-state HMM + ATR-based confirmation ticks)
+
+ADDITIONAL SUB-FIELD:
+  indicators.market_structure.transitionConfidence
+  type: NUMERIC [0, 1]
+  The HMM posterior probability of the current state. Higher = more certain.
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+market_structure classifies the current price action structure using a
+9-state Hidden Markov Model (HMM) with ATR-relative transition logic.
+
+INPUT SIGNALS:
+  - currentATR:   14-period ATR (Average True Range)
+  - baselineATR:  longer-period ATR for compression comparison
+  - currentPrice: most recent close
+  - resistanceLevels / supportLevels: from support/resistance indicator
+  - momentum: avg(recent 3 closes) vs avg(prior 3 closes) / avg(prior 3)
+  - Proximity threshold: 0.5 × ATR for S/R level proximity testing
+
+KEY COMPUTATIONAL RULES:
+
+  CONSOLIDATION DETECTION:
+    compression = currentATR / baselineATR
+    IF compression < CONSOLIDATION_THRESHOLD (0.30)
+      → 30% ATR compression below baseline = structural consolidation
+
+  BREAKOUT CONFIRMATION:
+    BREAKOUT_CONFIRM_TICKS = 3
+    Price must trade above a resistance level (or below support) for 3
+    consecutive ticks before transitioning from BREAKING to CONFIRMED_BREAK.
+    This prevents whipsaw false breakouts.
+
+  HMM SMOOTHING:
+    9×9 transition matrix with emission probability 0.75 (self-stay) /
+    0.03125 (any other state). The HMM smooths noisy state transitions —
+    brief 1-2 tick excursions may not change the published state.
+    transitionConfidence gives the posterior probability of the current
+    HMM state assignment.
+
+--------------------------------------------------------------------------------
+STATE DEFINITIONS
+--------------------------------------------------------------------------------
+  RANGING
+    Price is moving within a defined range between support and resistance.
+    No breakout attempt currently in progress. The market has established
+    a recognizable trading range. Normal oscillation between S/R levels.
+
+  CONSOL
+    Volatility compression is active (currentATR < 30% of baselineATR).
+    Price is consolidating in a tighter-than-normal range. This is not
+    merely quiet trading — it is structurally compressed. See also
+    volatility_squeeze for the GARCH view of the same phenomenon.
+
+  BREAKING_UP
+    Price has moved above a resistance level but has NOT yet sustained
+    above it for 3 consecutive ticks. Unconfirmed upside breakout attempt.
+    High false-positive rate here — many BREAKING_UP states fail and
+    return to RANGING or FAILED_BREAK.
+
+  BREAKING_DOWN
+    Mirror of BREAKING_UP. Price has moved below support but < 3 ticks
+    of sustained closure. Unconfirmed downside breakout.
+
+  CONFIRMED_BREAK_UP
+    Price has traded above resistance for >= 3 consecutive ticks.
+    Prior resistance level now becomes potential support.
+    This state represents a confirmed upside structural change.
+
+  CONFIRMED_BREAK_DOWN
+    Mirror of CONFIRMED_BREAK_UP. >= 3 ticks below prior support.
+
+  TEST_RS
+    Price is within proximity (0.5 × ATR) of a support OR resistance
+    level but has not yet broken it. Testing the level — decision zone.
+    The next few ticks will determine RANGING continuation, BREAKING,
+    or bounce back into range.
+
+  FAILED_BREAK
+    Price moved above resistance or below support (BREAKING state) but
+    then reversed back into the prior range without achieving 3-tick
+    confirmation. Classic bull/bear trap pattern. The level held.
+    Associated with a return to RANGING or TEST_RS.
+
+--------------------------------------------------------------------------------
+STATE TRANSITIONS — COMMON SEQUENCES
+--------------------------------------------------------------------------------
+# Understanding likely next states from each current state:
+
+  CONSOL → BREAKING_UP or BREAKING_DOWN
+    Compression resolved with a directional break. The squeeze_energy at
+    the time of this transition indicates the force of pent-up energy behind it.
+
+  BREAKING_UP → CONFIRMED_BREAK_UP  (3 ticks hold above resistance)
+  BREAKING_UP → FAILED_BREAK        (reversal back into range)
+
+  CONFIRMED_BREAK_UP → RANGING (at new higher range)
+    Post-breakout consolidation at the new level.
+
+  TEST_RS → BREAKING_UP / BREAKING_DOWN / RANGING
+    Decision: break through, fail the test, or bounce off.
+
+  FAILED_BREAK → TEST_RS or RANGING
+    Level has been confirmed to hold. Price oscillates around it.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.volatility_squeeze | COMPANION
+    For CONSOL: cross-reference with volatility_squeeze < 0.6.
+    Both should agree when a genuine structural consolidation is present.
+    IF market_structure = CONSOL AND volatility_squeeze >= 0.8:
+      → ATR says consolidated; GARCH says volatility is normal.
+         Potential disagreement — check timeframe alignment of each.
+
+  indicators.support / indicators.resistance | PREREQUISITE DATA
+    market_structure uses S/R levels to detect BREAKING and TEST_RS states.
+    The quality of S/R levels (bayesianStrength) directly affects whether
+    BREAKING_UP from a weak resistance is meaningful.
+    IF market_structure = CONFIRMED_BREAK_UP FROM a weak resistance level
+    (bayesianStrength < 0.4) → lower significance than breaking from STRONG S/R.
+
+  indicators.regime | CROSS_VALIDATE
+    CONFIRMED_BREAK_UP should co-occur with BREAKOUT or TREND_UP regime.
+    IF market_structure = CONFIRMED_BREAK_UP AND regime = CHOP
+      → Conflict. One is stale. Check timestamps.
+    IF market_structure = CONSOL AND regime = CONSOL
+      → Double confirmation of consolidation from two independent systems.
+
+  indicators.squeeze_energy | CONTEXT
+    The amount of squeeze_energy at the moment of structural breakout
+    amplifies expected move magnitude. Match timing of squeeze_energy release
+    with BREAKING state transitions.
+
+  indicators.hmi | CONTEXT
+    CONFIRMED_BREAK_UP should be accompanied by rising or already-elevated hmi.
+    IF market_structure = CONFIRMED_BREAK_UP AND hmi < 10
+      → Structural break confirmed by price action but momentum stack not
+         yet significantly aligned. Partial breakout condition.
+
+  indicators.transitionConfidence | COMPANION
+    Read transitionConfidence when state is ambiguous.
+    IF state = TEST_RS AND transitionConfidence = 0.6
+      → HMM is 60% confident in TEST_RS. 40% probability among other states.
+         Treat as moderate confidence — not a definitive read.
+    IF state = CONFIRMED_BREAK_UP AND transitionConfidence = 0.92
+      → High HMM posterior. Very confident state assignment.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read market_structure state.
+  2  Read transitionConfidence; if < 0.65, treat state as lower certainty.
+  3  For BREAK states: check which S/R level was broken and its bayesianStrength.
+  4  For CONSOL: cross-reference with volatility_squeeze and squeeze_energy.
+  5  Cross-validate with regime for directional context.
+  6  FAILED_BREAK: the level that held is now confirmed as significant.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF support/resistance data is unavailable or empty arrays
+    → BREAKING, CONFIRMED, and TEST_RS states cannot be determined.
+       Only RANGING, CONSOL, or RANGING may be emitted.
+
+  IF currentATR = 0 (extreme illiquidity)
+    → ATR-based proximity and confirmation logic fails. Treat as unavailable.
+
+  IF transitionConfidence < 0.55
+    → HMM state is ambiguous. Do not act on the state alone. Require
+       additional confirmation from regime and squeeze indicators.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF BREAKING_UP is acted on immediately (before CONFIRMED_BREAK)
+    → HIGH RISK. BREAKING_UP states have non-trivial false-positive rates.
+       They may transition to FAILED_BREAK. Wait for CONFIRMED_BREAK_UP
+       unless accepting reduced certainty for earlier entry.
+
+  IF CONSOL is treated as equivalent to RANGING
+    → INCORRECT. CONSOL specifically requires 30% ATR compression below
+       baseline — a structural squeeze condition. RANGING is just a price
+       channel without compression. They imply different break dynamics.
+       CONSOL breaks tend to be more violent.
+
+  IF CONFIRMED_BREAK_UP is treated as a stop target for shorts
+    → EVALUATION ORDER ISSUE. CONFIRMED_BREAK_UP is a state, not a level.
+       The specific resistance LEVEL that was broken is the reference price.
+       Identify the price level of the break via support/resistance data.