quantwise 1.2.0 → 1.2.2

package/.claude/skills/macro-regime-detector/scripts/tests/test_sector_rotation.py

@@ -0,0 +1,78 @@
+"""Tests for Sector Rotation Calculator (XLY/XLP)"""
+
+from calculators.sector_rotation_calculator import calculate_sector_rotation
+from test_helpers import make_monthly_history
+
+
+class TestCalculateSectorRotation:
+    def test_insufficient_data_empty(self):
+        result = calculate_sector_rotation([], [])
+        assert result["score"] == 0
+        assert result["data_available"] is False
+
+    def test_stable_ratio_low_score(self):
+        xly = make_monthly_history([180] * 24, start_year=2024)
+        xlp = make_monthly_history([75] * 24, start_year=2024)
+        result = calculate_sector_rotation(xly, xlp)
+        assert result["data_available"] is True
+        assert result["score"] <= 30  # Small noise from daily variation is expected
+
+    def test_risk_on_rotation(self):
+        # XLY rising faster than XLP = risk-on
+        xly_closes = [180 + i * 3 for i in range(24)]
+        xlp_closes = [75] * 24
+        xly = make_monthly_history(xly_closes, start_year=2024)
+        xlp = make_monthly_history(xlp_closes, start_year=2024)
+        result = calculate_sector_rotation(xly, xlp)
+        assert result["data_available"] is True
+
+    def test_risk_off_rotation(self):
+        # XLY falling, XLP rising = risk-off
+        xly_closes = [200 - i * 2 for i in range(24)]
+        xlp_closes = [70 + i * 2 for i in range(24)]
+        xly = make_monthly_history(xly_closes, start_year=2024)
+        xlp = make_monthly_history(xlp_closes, start_year=2024)
+        result = calculate_sector_rotation(xly, xlp)
+        assert result["data_available"] is True
+
+    def test_output_structure(self):
+        xly = make_monthly_history([180 + i for i in range(24)], start_year=2024)
+        xlp = make_monthly_history([75] * 24, start_year=2024)
+        result = calculate_sector_rotation(xly, xlp)
+
+        required_keys = [
+            "score",
+            "signal",
+            "data_available",
+            "direction",
+            "current_ratio",
+            "sma_6m",
+            "sma_12m",
+            "roc_3m",
+            "roc_12m",
+            "percentile",
+            "crossover",
+            "monthly_points",
+            "momentum_qualifier",
+        ]
+        for key in required_keys:
+            assert key in result
+        assert 0 <= result["score"] <= 100
+
+    def test_stale_crossover_reversal(self):
+        """Stale golden cross with declining recent momentum → risk_off + reversing."""
+        # Build ratio that crosses up early then declines recently
+        # 24 months: rise for first 12, then decline for next 12
+        xly_closes = [180 + i * 3 for i in range(12)] + [215 - i * 5 for i in range(12)]
+        xlp_closes = [75] * 24
+        xly = make_monthly_history(xly_closes, start_year=2024)
+        xlp = make_monthly_history(xlp_closes, start_year=2024)
+        result = calculate_sector_rotation(xly, xlp)
+        # The crossover happened early (stale) and recent momentum is negative
+        if (result["crossover"]["type"] == "golden_cross"
+                and result["crossover"]["bars_ago"] is not None
+                and result["crossover"]["bars_ago"] >= 3
+                and result["roc_3m"] is not None
+                and result["roc_3m"] < 0):
+            assert result["direction"] == "risk_off"
+            assert result["momentum_qualifier"] == "reversing"

package/.claude/skills/macro-regime-detector/scripts/tests/test_size_factor.py

@@ -0,0 +1,59 @@
+"""Tests for Size Factor Calculator (IWM/SPY)"""
+
+from calculators.size_factor_calculator import calculate_size_factor
+from test_helpers import make_monthly_history
+
+
+class TestCalculateSizeFactor:
+    def test_insufficient_data_empty(self):
+        result = calculate_size_factor([], [])
+        assert result["score"] == 0
+        assert result["data_available"] is False
+
+    def test_stable_ratio_low_score(self):
+        iwm = make_monthly_history([200] * 24, start_year=2024)
+        spy = make_monthly_history([500] * 24, start_year=2024)
+        result = calculate_size_factor(iwm, spy)
+        assert result["data_available"] is True
+        assert result["score"] <= 30  # Small noise from daily variation is expected
+
+    def test_small_cap_outperformance(self):
+        # IWM rising faster = small cap leading
+        iwm_closes = [200 + i * 3 for i in range(24)]
+        spy_closes = [500 + i * 1 for i in range(24)]
+        iwm = make_monthly_history(iwm_closes, start_year=2024)
+        spy = make_monthly_history(spy_closes, start_year=2024)
+        result = calculate_size_factor(iwm, spy)
+        assert result["data_available"] is True
+
+    def test_large_cap_outperformance(self):
+        # SPY rising faster = large cap leading
+        iwm_closes = [200 + i * 0.5 for i in range(24)]
+        spy_closes = [500 + i * 5 for i in range(24)]
+        iwm = make_monthly_history(iwm_closes, start_year=2024)
+        spy = make_monthly_history(spy_closes, start_year=2024)
+        result = calculate_size_factor(iwm, spy)
+        assert result["data_available"] is True
+
+    def test_output_structure(self):
+        iwm = make_monthly_history([200 + i for i in range(24)], start_year=2024)
+        spy = make_monthly_history([500] * 24, start_year=2024)
+        result = calculate_size_factor(iwm, spy)
+
+        required_keys = [
+            "score",
+            "signal",
+            "data_available",
+            "direction",
+            "current_ratio",
+            "sma_6m",
+            "sma_12m",
+            "roc_3m",
+            "roc_12m",
+            "percentile",
+            "crossover",
+            "monthly_points",
+        ]
+        for key in required_keys:
+            assert key in result
+        assert 0 <= result["score"] <= 100

package/.claude/skills/macro-regime-detector/scripts/tests/test_utils.py

@@ -0,0 +1,126 @@
+"""Tests for determine_direction utility function"""
+
+from calculators.utils import determine_direction
+
+
+class TestDetermineDirection:
+    def test_recent_golden_cross_confirmed(self):
+        """Recent golden cross with positive ROC → positive label, confirmed."""
+        crossover = {"type": "golden_cross", "bars_ago": 1}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=5.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_on"
+        assert qualifier == "confirmed"
+
+    def test_recent_death_cross_confirmed(self):
+        """Recent death cross with negative ROC → negative label, confirmed."""
+        crossover = {"type": "death_cross", "bars_ago": 1}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=-3.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_off"
+        assert qualifier == "confirmed"
+
+    def test_stale_golden_cross_reversing(self):
+        """5-month-old golden cross with negative ROC → momentum overrides to negative."""
+        crossover = {"type": "golden_cross", "bars_ago": 5}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=-13.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_off"
+        assert qualifier == "reversing"
+
+    def test_stale_death_cross_reversing(self):
+        """Old death cross with positive ROC → momentum overrides to positive."""
+        crossover = {"type": "death_cross", "bars_ago": 4}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=5.0,
+            positive_label="easing", negative_label="tightening",
+        )
+        assert direction == "easing"
+        assert qualifier == "reversing"
+
+    def test_stale_golden_cross_confirmed(self):
+        """Old golden cross but still positive ROC → positive label, confirmed."""
+        crossover = {"type": "golden_cross", "bars_ago": 5}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=2.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_on"
+        assert qualifier == "confirmed"
+
+    def test_recent_cross_fading(self):
+        """Recent golden cross but negative ROC (not stale) → positive, fading."""
+        crossover = {"type": "golden_cross", "bars_ago": 1}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=-2.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_on"
+        assert qualifier == "fading"
+
+    def test_no_crossover_momentum_only(self):
+        """No crossover, positive ROC → positive from momentum."""
+        crossover = {"type": "none", "bars_ago": None}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=3.0,
+            positive_label="small_cap_leading", negative_label="large_cap_leading",
+        )
+        assert direction == "small_cap_leading"
+        assert qualifier == "N/A"
+
+    def test_no_crossover_no_roc_neutral(self):
+        """No crossover, no ROC → neutral."""
+        crossover = {"type": "none", "bars_ago": None}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=None,
+            positive_label="risk_on", negative_label="risk_off",
+            neutral_label="neutral",
+        )
+        assert direction == "neutral"
+        assert qualifier == "N/A"
+
+    def test_converging_with_momentum(self):
+        """Converging (not a cross) with positive momentum → positive from momentum."""
+        crossover = {"type": "converging", "bars_ago": None}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=4.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_on"
+        assert qualifier == "N/A"
+
+    def test_custom_neutral_label(self):
+        """Custom neutral label returned when no signals."""
+        crossover = {"type": "none", "bars_ago": None}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=None,
+            positive_label="easing", negative_label="tightening",
+            neutral_label="stable",
+        )
+        assert direction == "stable"
+
+    def test_stale_threshold_boundary(self):
+        """bars_ago == 3 (exactly at threshold) is stale."""
+        crossover = {"type": "golden_cross", "bars_ago": 3}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=-5.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_off"
+        assert qualifier == "reversing"
+
+    def test_bars_ago_just_below_threshold(self):
+        """bars_ago == 2 (below threshold) is NOT stale → recent cross wins."""
+        crossover = {"type": "golden_cross", "bars_ago": 2}
+        direction, qualifier = determine_direction(
+            crossover, roc_3m=-5.0,
+            positive_label="risk_on", negative_label="risk_off",
+        )
+        assert direction == "risk_on"
+        assert qualifier == "fading"

package/.claude/skills/macro-regime-detector/scripts/tests/test_yield_curve.py

@@ -0,0 +1,64 @@
+"""Tests for Yield Curve Calculator"""
+
+from calculators.yield_curve_calculator import calculate_yield_curve
+from test_helpers import make_monthly_history, make_treasury_rates
+
+
+class TestCalculateYieldCurve:
+    def test_insufficient_data_all_none(self):
+        result = calculate_yield_curve(None, None, None)
+        assert result["score"] == 0
+        assert result["data_available"] is False
+
+    def test_treasury_api_stable_spread(self):
+        # Stable spread = low transition signal
+        spreads = [1.0] * 24  # Constant 1% spread
+        rates = make_treasury_rates(spreads, start_year=2024)
+        result = calculate_yield_curve(treasury_rates=rates)
+        assert result["data_available"] is True
+        assert result["data_source"] == "treasury_api"
+        assert result["score"] <= 30  # Small noise from daily variation is expected
+
+    def test_treasury_api_steepening(self):
+        # Spread increasing from -0.5 to 1.5 = steepening transition
+        spreads = [-0.5 + i * (2.0 / 23) for i in range(24)]
+        rates = make_treasury_rates(spreads, start_year=2024)
+        result = calculate_yield_curve(treasury_rates=rates)
+        assert result["data_available"] is True
+        assert result["direction"] in ("steepening", "flattening", "stable")
+
+    def test_treasury_api_inverted(self):
+        # Negative spreads
+        spreads = [-0.5] * 24
+        rates = make_treasury_rates(spreads, start_year=2024)
+        result = calculate_yield_curve(treasury_rates=rates)
+        assert result["curve_state"] in (
+            "inverted",
+            "deeply_inverted",
+            "flat",
+            "normalizing",
+            "normal",
+            "steep",
+        )
+
+    def test_shy_tlt_fallback(self):
+        # When no treasury rates, use SHY/TLT proxy
+        shy = make_monthly_history([80 + i * 0.1 for i in range(24)], start_year=2024)
+        tlt = make_monthly_history([90 - i * 0.2 for i in range(24)], start_year=2024)
+        result = calculate_yield_curve(treasury_rates=None, shy_history=shy, tlt_history=tlt)
+        assert result["data_available"] is True
+        assert result["data_source"] == "shy_tlt_proxy"
+
+    def test_output_structure(self):
+        spreads = [1.0 + i * 0.05 for i in range(24)]
+        rates = make_treasury_rates(spreads, start_year=2024)
+        result = calculate_yield_curve(treasury_rates=rates)
+
+        assert "score" in result
+        assert "signal" in result
+        assert "data_available" in result
+        assert "data_source" in result
+        assert "direction" in result
+        assert "curve_state" in result
+        assert "crossover" in result
+        assert 0 <= result["score"] <= 100

package/.claude/skills/market-breadth-analyzer/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: market-breadth-analyzer
+description: 使用TraderMonty的公开CSV数据量化市场广度健康状况。生成0-100的综合评分，涵盖6个维度（100 = 健康）。无需API密钥。当用户询问市场广度、参与率、涨跌线健康状况、上涨是否广泛，或整体市场健康评估时使用。
+---
+
+# 市场广度分析器技能
+
+## 目的
+
+使用数据驱动的6维度评分系统（0-100）量化市场广度健康状况。利用TraderMonty公开可用的CSV数据，衡量市场在上涨或下跌中的参与广度。
+
+**评分方向：** 100 = 最大健康度（广泛参与），0 = 严重虚弱。
+
+**无需API密钥** - 使用GitHub Pages上免费提供的CSV数据。
+
+## 何时使用本技能
+
+**英文：**
+- User asks "Is the market rally broad-based?" or "How healthy is market breadth?"
+- User wants to assess market participation rate
+- User asks about advance-decline indicators or breadth thrust
+- User wants to know if the market is narrowing (fewer stocks participating)
+- User asks about equity exposure levels based on breadth conditions
+
+**中文：**
+- "市场广度怎么样？""市场参与率如何？"
+- "上涨范围广泛吗？""是不是只有少数股票在涨？"
+- 基于广度指标判断仓位水平
+- 希望用数据确认市场健康度
+
+## 与Breadth Chart Analyst的区别
+
+| 方面 | Market Breadth Analyzer | Breadth Chart Analyst |
+|------|------------------------|----------------------|
+| 数据来源 | CSV（自动化） | 图表图像（手动） |
+| 需要API | 无 | 无 |
+| 输出 | 定量0-100评分 | 定性图表分析 |
+| 维度 | 6个评分维度 | 视觉模式识别 |
+| 可重复性 | 完全可重现 | 依赖分析师 |
+
+---
+
+## 执行工作流
+
+### 第一阶段：执行Python脚本
+
+运行分析脚本：
+
+```bash
+python3 skills/market-breadth-analyzer/scripts/market_breadth_analyzer.py \
+  --detail-url "https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv" \
+  --summary-url "https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv"
+```
+
+脚本将执行以下操作：
+1. 获取详细CSV（约2,500行，2016年至今）和摘要CSV（8项指标）
+2. 验证数据时效性（若超过5天则发出警告）
+3. 计算所有6个维度的评分
+4. 生成综合评分及区域分类
+5. 输出JSON和Markdown报告
+
+### 第二阶段：展示结果
+
+向用户展示生成的Markdown报告，重点说明：
+- 综合评分和健康区域
+- 最强和最弱的维度
+- 建议的股票仓位水平
+- 需要关注的关键广度水平
+- 任何数据时效性警告
+
+---
+
+## 6维度评分系统
+
+| # | 维度 | 权重 | 关键信号 |
+|---|------|------|----------|
+| 1 | 广度水平与趋势 | **25%** | 当前8MA水平 + 200MA趋势方向 |
+| 2 | 8MA与200MA交叉 | **20%** | 通过MA差距和方向判断动量 |
+| 3 | 峰谷周期 | **20%** | 在广度周期中的位置 |
+| 4 | 看跌信号 | **15%** | 经回测验证的看跌信号标志 |
+| 5 | 历史百分位 | **10%** | 当前值与完整历史分布的对比 |
+| 6 | S&P 500背离 | **10%** | 价格与广度的方向一致性 |
+
+## 健康区域映射（100 = 健康）
+
+| 评分 | 区域 | 股票仓位 | 行动 |
+|------|------|----------|------|
+| 80-100 | 强劲 | 90-100% | 满仓操作，偏向成长/动量 |
+| 60-79 | 健康 | 75-90% | 正常操作 |
+| 40-59 | 中性 | 60-75% | 精选持仓，收紧止损 |
+| 20-39 | 转弱 | 40-60% | 获利了结，增加现金 |
+| 0-19 | 危急 | 25-40% | 保存资本，关注谷底 |
+
+---
+
+## 数据来源
+
+**详细CSV：** `market_breadth_data.csv`
+- 约2,500行，从2016年2月至今
+- 列：Date, S&P500_Price, Breadth_Index_Raw, Breadth_Index_200MA, Breadth_Index_8MA, Breadth_200MA_Trend, Bearish_Signal, Is_Peak, Is_Trough, Is_Trough_8MA_Below_04
+
+**摘要CSV：** `market_breadth_summary.csv`
+- 8项汇总指标（平均峰值、平均谷底、计数、分析期间）
+
+两者均托管在GitHub Pages上——无需认证。
+
+## 输出文件
+
+- JSON: `market_breadth_YYYY-MM-DD_HHMMSS.json`
+- Markdown: `market_breadth_YYYY-MM-DD_HHMMSS.md`
+
+## 参考文档
+
+### `references/breadth_analysis_methodology.md`
+- 包含维度评分细节的完整方法论
+- 阈值说明和区域定义
+- 历史背景和解读指南
+
+### 何时加载参考文档
+- **首次使用：** 加载方法论参考文档以理解框架
+- **常规执行：** 无需参考文档——脚本会处理评分

package/.claude/skills/market-breadth-analyzer/references/breadth_analysis_methodology.md

@@ -0,0 +1,168 @@
+# Market Breadth Analysis Methodology
+
+## Overview
+
+Market breadth measures the degree of participation in a market move. A healthy advance is characterized by broad participation (many stocks rising), while a narrowing market (fewer stocks leading) often precedes corrections.
+
+This methodology uses TraderMonty's breadth dataset to quantify market health across 6 dimensions, producing a composite score from 0 (critical) to 100 (maximum health).
+
+---
+
+## Data Description
+
+### Breadth Index
+The breadth index (0-1) measures the proportion of S&P 500 stocks trading above their 200-day moving average. Key derivatives:
+- **Raw:** Daily breadth value (percentage of stocks above 200DMA)
+- **8-day EMA (8MA):** Short-term exponentially weighted moving average (fast signal)
+- **200-day EMA (200MA):** Long-term exponentially weighted moving average (trend filter)
+
+**Important:** Both moving averages use **EMA** (Exponential Moving Average), not SMA. The source repository calculates them as `ewm(span=N, adjust=False)`. EMA gives more weight to recent data points, making it more responsive to changes than SMA.
+
+### Key Thresholds
+| Level | Interpretation |
+|-------|---------------|
+| 8MA > 0.70 | Very strong breadth - broad rally |
+| 8MA > 0.60 | Healthy breadth - above average participation |
+| 8MA > 0.50 | Neutral - about half of stocks participating |
+| 8MA > 0.40 | Weakening - below average participation |
+| 8MA < 0.40 | Extreme weakness - potential trough formation |
+| 8MA < 0.20 | Crisis levels - rare, precedes major bottoms |
+
+### Signal Flags
+- **Breadth_200MA_Trend:** 1 = 200MA rising (bullish regime), -1 = 200MA falling (bearish regime). Uses hysteresis with threshold=0.001 to prevent whipsaw signals.
+- **Bearish_Signal:** Backtested signal combining trend and momentum deterioration
+- **Is_Peak / Is_Trough:** Cyclical turning points detected using `scipy.signal.find_peaks` with `distance=50, prominence=0.015` on the 200MA. This ensures at least 50 trading days (~10 weeks) between consecutive peaks/troughs and a minimum prominence of 0.015.
+- **Is_Trough_8MA_Below_04:** Extreme trough marker detected with `prominence=0.02` on inverted 8MA values below 0.4.
+
+### Pink Zone (Bearish Region)
+The source repository's charts use a pink background to highlight the most dangerous market condition:
+
+```
+Pink Zone = (Breadth_200MA_Trend == -1) AND (8MA < 200MA)
+```
+
+This means the long-term trend is declining AND the short-term breadth has fallen below the long-term average. Historically, markets in the Pink Zone experience elevated volatility and downside risk. The Pink Zone is distinct from the Bearish_Signal flag - it is a structural condition that can persist for weeks or months.
+
+---
+
+## Component Details
+
+### C1: Current Breadth Level & Trend (25%)
+
+**Rationale:** The most direct measure of current market health. Higher 8MA means more stocks participating; uptrend in 200MA means the long-term structure is supportive.
+
+**Weighting within component:**
+- 8MA Level: 70% - immediate health snapshot
+- 200MA Trend: 30% - longer-term regime confirmation
+
+**Key insight:** An 8MA of 0.65 in an uptrend (score ~80) is healthier than 0.65 in a downtrend (score ~62), because the downtrend context suggests the level may be transient.
+
+### C2: 8MA vs 200MA Crossover Dynamics (20%)
+
+**Rationale:** The gap between fast and slow MAs reveals momentum. A wide positive gap means breadth is accelerating above trend; a negative gap means it's deteriorating below trend.
+
+**Direction modifier:** When the 8MA is recovering (rising) while still below the 200MA, this early recovery signal adds +10. Conversely, when 8MA is falling while still above 200MA, this early deterioration signal subtracts -10.
+
+**Key insight:** The crossover point (8MA crossing 200MA) is a significant signal. Bull markets maintain 8MA above 200MA; bear phases see 8MA below 200MA.
+
+### C3: Peak/Trough Cycle Position (20%)
+
+**Rationale:** Breadth moves in cycles. Knowing whether we are in the early, middle, or late phase of a cycle helps calibrate expectations.
+
+**Cycle phases:**
+1. **Trough → Early Recovery (0-20 days):** Highest potential for upside if 8MA is rising
+2. **Sustained Recovery (21-60 days):** Confirmed recovery with decreasing upside magnitude
+3. **Mature Recovery (60+ days):** Late-cycle, watch for next peak
+4. **Post-Peak Decline (0-20 days):** Highest risk period
+5. **Sustained Decline (21-60 days):** Deep correction territory
+6. **Prolonged Decline (60+ days):** Potential bottom formation if 8MA starts rising
+
+**Extreme trough bonus:** When 8MA drops below 0.4 at a trough, history shows these are often excellent long-term entry points, warranting a +10 bonus.
+
+### C4: Bearish Signal Status (15%)
+
+**Rationale:** The dataset includes a backtested bearish signal flag that combines multiple factors. Its value depends on context.
+
+**Interpretation matrix:**
+| Signal | Trend | Score | Meaning |
+|--------|-------|-------|---------|
+| Off | Up | 85 | All clear - no concerns |
+| Off | Down | 50 | No immediate danger but bearish backdrop |
+| On | Up | 30 | Warning in otherwise bullish environment |
+| On | Down | 10 | Full bearish alignment |
+
+**Context matters:** A bearish signal when 8MA is above 0.50 is less concerning (+15 adjustment) than one when 8MA is below 0.25 (-5 adjustment).
+
+**Pink Zone integration:** When in the Pink Zone (200MA downtrend + 8MA below 200MA) but without an active bearish signal, a -10 penalty is applied to reflect structural weakness that the bearish flag alone may not capture.
+
+### C5: Historical Percentile (10%)
+
+**Rationale:** Knowing where current breadth stands relative to the full 10-year history provides framing. Is this level normal, unusually high, or unusually low?
+
+**Overheated/oversold adjustments:** When current 8MA approaches the average peak level, a -10 penalty reflects elevated risk of mean reversion. When near the average trough level, a +10 bonus reflects contrarian opportunity.
+
+### C6: S&P 500 vs Breadth Divergence (10%)
+
+**Rationale:** The most dangerous market condition is when the index makes new highs but breadth is declining (fewer stocks participating). This divergence preceded major tops in 2000, 2007, and 2021.
+
+**Key patterns:**
+- **S&P up + Breadth up:** Healthy, sustainable rally (70)
+- **S&P up + Breadth down:** Dangerous narrow market (10-25)
+- **S&P down + Breadth up:** Bullish divergence, potential bottom (65-80)
+- **S&P down + Breadth down:** Consistent decline, wait for stabilization (30)
+
+---
+
+## Composite Score Interpretation
+
+### Zone Thresholds
+
+| Score | Zone | Exposure | Key Actions |
+|-------|------|----------|-------------|
+| 80-100 | **Strong** | 90-100% | Full position sizing; growth/momentum strategies; wide stops |
+| 60-79 | **Healthy** | 75-90% | Normal operations; standard risk management |
+| 40-59 | **Neutral** | 60-75% | Selective; tighter stops; avoid speculative names |
+| 20-39 | **Weakening** | 40-60% | Profit-taking; raise cash; defensive rotation |
+| 0-19 | **Critical** | 25-40% | Capital preservation; hedging; watch for trough |
+
+### Cross-Referencing with Other Skills
+
+- **Market Top Detector:** If breadth is Weakening (20-39) AND top detector is Orange/Red, this is strong confirmation of topping conditions.
+- **CANSLIM Screener:** In Strong/Healthy zones, CANSLIM stock selections have higher success rates.
+- **Sector Analyst:** Weakening breadth often coincides with rotation from offensive to defensive sectors.
+
+---
+
+## Historical Context
+
+### Average Values (from Summary CSV)
+- **Average Peak (200MA):** ~0.729 - breadth cycles typically top around this level
+- **Average Trough (8MA < 0.4):** ~0.232 - extreme troughs average around this level
+- **Peak Count:** ~5 over 10 years (roughly every 2 years)
+- **Trough Count:** ~10 extreme troughs (roughly twice per year on average)
+
+### Notable Historical Patterns
+- **COVID-19 (March 2020):** 8MA crashed to extreme lows, followed by one of the sharpest breadth recoveries in history
+- **2022 Bear Market:** Sustained period of 8MA below 200MA with multiple bearish signals
+- **2023 Recovery:** Gradual breadth improvement with 8MA crossing above 200MA
+
+---
+
+## Live Resources
+
+- **Interactive Dashboard:** https://tradermonty.github.io/market-breadth-analysis/
+- **Data CSV:** https://tradermonty.github.io/market-breadth-analysis/market_breadth_data.csv
+- **Summary CSV:** https://tradermonty.github.io/market-breadth-analysis/market_breadth_summary.csv
+- **Source Repository:** https://github.com/tradermonty/market-breadth-analysis
+
+Data is automatically updated twice daily via GitHub Actions. CSV files are freely accessible without API keys.
+
+---
+
+## Limitations
+
+1. **Lagging indicator:** Breadth data reflects what has happened, not what will happen. Use alongside forward-looking indicators.
+2. **No sector granularity:** The breadth index is market-wide. A few large sectors can dominate the reading.
+3. **CSV update frequency:** Data depends on TraderMonty's update schedule. Check data freshness before analysis.
+4. **Single market:** Covers S&P 500 only. Does not reflect international markets, small caps, or other asset classes.
+5. **No volume context:** The breadth index is price-based and does not incorporate volume data.

package/.claude/skills/market-breadth-analyzer/scripts/calculators/__init__.py

@@ -0,0 +1 @@
+# Market Breadth Analyzer - Calculator modules