quantwise 1.2.0 → 1.2.2

package/.claude/skills/market-top-detector/references/distribution_day_guide.md

@@ -0,0 +1,100 @@
+# Distribution Day Guide
+
+## What is a Distribution Day?
+
+A Distribution Day occurs when a major stock index (S&P 500 or NASDAQ Composite) declines by 0.2% or more on volume that is higher than the previous trading day. This pattern indicates institutional investors are selling stocks in volume - "distributing" their holdings.
+
+William O'Neil introduced this concept in "How to Make Money in Stocks" as one of the most reliable signals that a market uptrend is under pressure.
+
+## Precise Rules
+
+### Distribution Day Criteria (BOTH must be met):
+1. **Price decline >= 0.2%** from previous session's close
+2. **Volume > previous day's volume** (even slightly higher counts)
+
+### Stalling Day Criteria (BOTH must be met):
+1. **Volume > previous day's volume** (institutional activity present)
+2. **Price gain < 0.1%** (price fails to advance meaningfully despite volume)
+3. Stalling days count as **0.5 distribution days** in the effective count
+
+### 25-Day Expiration Rule:
+- A distribution day automatically expires after **25 trading days** (approximately 5 weeks)
+- Only the rolling 25-day window matters
+- This prevents old distribution from affecting current assessment
+
+### What Does NOT Count as Distribution:
+- Index declines on lower volume (normal profit-taking)
+- Large gap-up open followed by slight closing decline (still net positive day)
+- Volume below average (lack of institutional participation)
+
+## Counting and Interpretation
+
+| Effective Count | Interpretation | Action |
+|----------------|----------------|--------|
+| 0-1 | Healthy market | Normal operations |
+| 2-3 | Some selling but normal | Monitor closely |
+| 4 | O'Neil's initial warning | Tighten stops |
+| 5 | Significant distribution | Reduce exposure |
+| 6+ | Heavy distribution | Protect capital aggressively |
+
+**Effective Count Formula:**
+```
+Effective Count = Distribution Days + (0.5 × Stalling Days)
+```
+
+## Dual-Index Approach
+
+This tool monitors both the S&P 500 and NASDAQ (via QQQ). The higher effective count between the two indices is used for scoring, because:
+
+1. Distribution can concentrate in one index before the other
+2. NASDAQ often leads due to higher growth stock concentration
+3. The worst signal from either index is the most conservative approach
+
+## Common Patterns at Market Tops
+
+### Classic Distribution Sequence (2022 Example):
+1. Week 1: One distribution day (seems harmless)
+2. Week 2: Two more distribution days
+3. Week 3: One stalling day (selling into rallies)
+4. Week 4: Two more distribution days (total: 5-6 effective)
+5. Market breaks down shortly after
+
+### False Alarm Pattern:
+1. Two distribution days in quick succession
+2. Market rallies strongly, erasing concerns
+3. Distribution days expire without reaching critical mass
+4. Uptrend continues
+
+### Key Distinction:
+The **clustering** of distribution days matters. Three distribution days in one week is more alarming than three spread over five weeks.
+
+## Follow-Through Day (FTD)
+
+The FTD is the counterpart to distribution days - it signals a potential new uptrend after a correction.
+
+### FTD Rules:
+1. **Rally Attempt:** Market makes its low and begins to rally (first up day)
+2. **Counting:** Start counting from day 1 of the rally attempt
+3. **FTD Occurs on Day 4-7:** A significant price gain (>1.5%) with volume higher than the previous day
+4. **Confirmation:** The FTD should be on day 4 at the earliest (premature rallies on days 1-3 are unreliable)
+
+### FTD Reliability:
+- Not all FTDs lead to sustained uptrends (~25% fail)
+- Multiple FTDs within a short period increase confidence
+- FTDs work best when combined with improving breadth
+- O'Neil: "I never try to buy at the bottom. I wait for the Follow-Through Day."
+
+## Practical Tips
+
+### When Monitoring Distribution:
+1. Check distribution count DAILY during uncertain markets
+2. Pay special attention when count reaches 3 (pre-warning)
+3. At 4+, begin defensive actions regardless of other signals
+4. Don't wait for 6+ to act - by then, significant damage may be done
+
+### Common Mistakes:
+1. **Ignoring stalling days:** They're subtle but significant
+2. **Resetting count manually:** Trust the 25-day expiration rule
+3. **Using wrong volume data:** Must compare day-to-day, not vs average
+4. **Mixing indices:** Count separately for S&P 500 and NASDAQ
+5. **Ignoring context:** 4 distribution days in a strong uptrend is different from 4 in a range-bound market

package/.claude/skills/market-top-detector/references/historical_tops.md

@@ -0,0 +1,142 @@
+# 历史市场顶部分析
+
+## 概述
+
+通过6组件市场顶部检测框架对主要市场顶部进行分析。这些历史案例为评分系统提供校准数据。
+
+## 2000年：互联网泡沫顶部（2000年3月）
+
+### 时间线
+- **S&P 500峰值：** 2000年3月24日（1,527.46）
+- **NASDAQ峰值：** 2000年3月10日（5,048.62）
+- **随后跌幅：** S&P -49%，NASDAQ在2.5年内-78%
+
+### 各组件信号（估计分数）
+
+| 组件 | 信号级别 | 估计分数 | 备注 |
+|-----------|-------------|------------|-------|
+| 派发日 | 非常高 | 90-100 | 2000年3月大量派发 |
+| 领头股 | 危急 | 85-95 | 互联网股票比指数提前数周见顶 |
+| 防御性轮动 | 强 | 70-80 | 价值/防御股数月来跑赢 |
+| 广度 | 严重背离 | 80-90 | 涨跌线在1998年4月就已见顶 |
+| 指数技术面 | 正在崩溃 | 70-80 | NASDAQ首先跌破50日均线 |
+| 情绪 | 极端 | 90-100 | IPO狂热，"新范式"叙事 |
+
+**估计综合评分：82-92（危急）**
+
+### 关键教训
+广度背离是最早的信号（比顶部早近2年）。派发日和领头股崩溃是最终确认信号。当所有6个组件都亮红灯时，下跌已经开始了。
+
+---
+
+## 2007年：金融危机顶部（2007年10月）
+
+### 时间线
+- **S&P 500峰值：** 2007年10月9日（1,565.15）
+- **随后跌幅：** 17个月内-57%（2009年3月低点）
+
+### 各组件信号（估计分数）
+
+| 组件 | 信号级别 | 估计分数 | 备注 |
+|-----------|-------------|------------|-------|
+| 派发日 | 高 | 75-85 | 2007年9-10月出现多个派发集群 |
+| 领头股 | 高 | 70-80 | 房屋建筑商（ITB）在2006年2月见顶，金融股（XLF）在2007年6月见顶 |
+| 防御性轮动 | 中等 | 55-65 | 公用事业和医疗保健跑赢 |
+| 广度 | 背离 | 60-70 | NYSE涨跌线在2007年7月见顶 |
+| 指数技术面 | 走弱 | 50-60 | S&P仍接近高点但内部结构恶化 |
+| 情绪 | 偏高 | 55-65 | VIX在2006-2007年长期处于极低水平（低于12） |
+
+**估计综合评分：62-72（红色区域）**
+
+### 关键教训
+2007年的顶部是一个缓慢形成的过程。领先板块（金融/住房）比S&P 500提前12-18个月见顶。综合评分在到达"红色"之前会在"橙色"区域停留数月。这个顶部奖励的是逐步减少仓位，而非单一的二元判断。
+
+---
+
+## 2018年：第四季度抛售（2018年9-12月）
+
+### 时间线
+- **S&P 500峰值：** 2018年9月20日（2,930.75）
+- **随后跌幅：** -20%（回调，非熊市）
+- **恢复：** 2018年12月V形底部，2019年4月创新高
+
+### 各组件信号（估计分数）
+
+| 组件 | 信号级别 | 估计分数 | 备注 |
+|-----------|-------------|------------|-------|
+| 派发日 | 中等 | 55-65 | 10月期间派发日累积 |
+| 领头股 | 中等 | 50-60 | FAANG股票在不同时间见顶（FB 7月，AMZN 9月） |
+| 防御性轮动 | 中等 | 45-55 | 第三季度公用事业跑赢 |
+| 广度 | 轻微背离 | 40-50 | 广度收窄但不极端 |
+| 指数技术面 | 走弱 | 55-65 | 50日均线在12月下穿200日均线 |
+| 情绪 | 混合 | 35-45 | VIX升高但不极端 |
+
+**估计综合评分：47-57（橙色区域）**
+
+### 关键教训
+这是一个典型的"回调"案例（非熊市）。综合评分正确地处于橙色区域——足以建议获利了结但不需要全面防守姿态。快速的V形恢复证明了为什么综合评分在多个组件没有极端读数时不会进入"危急"级别。
+
+---
+
+## 2022年：美联储紧缩熊市（2022年1月）
+
+### 时间线
+- **S&P 500峰值：** 2022年1月3日（4,796.56）
+- **NASDAQ峰值：** 2021年11月19日（16,057.44）
+- **随后跌幅：** S&P -25%，NASDAQ -33%
+
+### 各组件信号（2022年1月估计分数）
+
+| 组件 | 信号级别 | 估计分数 | 备注 |
+|-----------|-------------|------------|-------|
+| 派发日 | 高 | 75-90 | 2021年12月底和2022年1月初大量派发 |
+| 领头股 | 危急 | 80-90 | ARKK在2021年2月见顶（提前11个月），许多成长股较高点下跌超50% |
+| 防御性轮动 | 强 | 65-75 | XLU、XLP强势跑赢 |
+| 广度 | 严重背离 | 70-80 | NASDAQ新高/新低严重背离 |
+| 指数技术面 | 正在破位 | 60-70 | NASDAQ跌破200日均线，S&P测试关键水平 |
+| 情绪 | 偏高 | 50-60 | 保证金债务创历史新高，加密货币投机 |
+
+**估计综合评分：68-78（红色区域）**
+
+### 关键教训
+ARKK（领头股代理指标）比S&P 500提前11个月见顶。这是教科书级的Minervini信号——领头股远在指数之前就已恶化。到2022年1月，综合评分已稳固处于红色区域，正确发出了积极获利了结的信号。2022年的案例验证了"领头股健康度"组件作为早期预警信号的有效性。
+
+---
+
+## 跨案例模式
+
+### 所有顶部的共同点：
+1. **派发日集中出现**（非分散）在下跌前的数周内
+2. **领头股先于指数见顶**（提前数周到数月）
+3. **广度与指数价格背离**（上涨变得越来越窄）
+4. **防御性轮动**随着顶部形成而加速
+
+### 差异之处：
+1. **严重程度：** 从-20%回调（2018年）到NASDAQ -78%暴跌（2000年）不等
+2. **速度：** 2018年快速下跌（3个月），2000-2002年缓慢下跌（2.5年）
+3. **恢复时间：** 2018年4个月恢复，2000年NASDAQ用了7年
+4. **广度背离时间：** 2000年有2年的背离，2022年有数月
+
+### 评分校准：
+- **橙色区域（41-60）：** 可能发生回调（2018年类型，-10-20%）
+- **红色区域（61-80）：** 可能发生重大下跌（2007、2022年类型，-20-35%）
+- **危急（81-100）：** 极端泡沫顶部（2000年类型，-40%+）
+
+### 重要提示：
+历史校准并不完美。每个市场环境都是独特的。综合评分应作为投资决策的一个输入，而非确定性预测。市场可以在"警告"区域停留很长时间后才真正下跌。
+
+---
+
+## 模式：领头股作为早期预警
+
+来自Monty文章：
+> 在熊市的初期阶段，某些领头股表现得好像在抵抗下跌趋势，
+> 给人以仍然可以上涨的印象。
+
+这种模式出现在每一个历史顶部中：
+- **2000年：** 蓝筹科技股（MSFT、INTC）在互联网股暴跌时仍然坚挺
+- **2007年：** 能源板块上涨而金融股崩溃
+- **2022年：** AAPL、MSFT相对稳定而ARKK成分股暴跌
+- **当前类比：** 一些超大型股坚挺而成长/投机股恶化
+
+这就是为什么组件2（领头股健康度）使用一篮子成长ETF而非仅S&P 500成分股——它能捕捉到指数掩盖的恶化信号。

package/.claude/skills/market-top-detector/references/market_top_methodology.md

@@ -0,0 +1,167 @@
+# 市场顶部检测方法论
+
+## 概述
+
+本框架整合了三种经过验证的市场顶部检测方法，每种方法针对机构行为的不同方面，这些行为先于重大市场下跌（10-20%回调）出现。
+
+## 三大支柱
+
+### 支柱1：O'Neil - 派发日累积
+
+**来源：** William O'Neil,《How to Make Money in Stocks》
+
+**核心概念：** 机构投资者（共同基金、对冲基金、养老金）无法在一天内卖出其大额持仓。他们的卖出会形成一种独特的模式：指数在成交量高于前一日的情况下下跌。当这些"派发日"累积时，表明聪明资金正在系统性退出。
+
+**派发日定义：**
+- 指数较前一交易日收盘下跌 >= 0.2%
+- 成交量高于前一交易日
+- 两个条件必须同时满足
+
+**停滞日定义：**
+- 成交量较前一日增加
+- 但价格涨幅极小（< 0.1%）
+- 表明机构在上涨中卖出
+- 按半权重计算（0.5个派发日）
+
+**25日窗口：**
+- 派发日在25个交易日后过期
+- 只有滚动25日计数有意义
+- 这可以防止旧事件扭曲当前评估
+
+**O'Neil的警告阈值：**
+- 25个交易日内4-5个派发日 = "市场承压"
+- 6个以上派发日 = "派发沉重，保护资本"
+- 结合停滞日综合判断
+
+### 支柱2：Minervini - 领头股恶化
+
+**来源：** Mark Minervini,《Trade Like a Stock Market Wizard》/《Think & Trade Like a Champion》
+
+**核心概念：** 市场顶部不会突然出现。它们通过一个过程发展——领头股（前一轮上涨中最强的表现者）在主要指数之前开始崩溃。这是因为机构投资者首先卖出其最大的赢家以锁定利润。
+
+**来自Monty文章的关键观察：**
+> "在熊市的初期阶段，某些领头股表现得好像在抵抗下跌趋势，给人以仍然可以上涨的印象。"
+
+**检测方法：**
+使用一篮子成长/创新ETF作为市场领导力的代理指标：
+- ARKK（创新）、WCLD（云计算）、IGV（软件）
+- XBI（生物科技）、SOXX/SMH（半导体）
+- KWEB（中国科技）、TAN（太阳能）
+
+**每个ETF的恶化信号：**
+1. 距52周高点的距离（>10% = 令人担忧，>25% = 熊市领域）
+2. 价格低于50日移动平均线
+3. 价格低于200日移动平均线
+4. 形成更低高点的模式
+
+**放大规则：** 当60%以上的领头ETF显示恶化时，信号放大1.3倍。这反映了领导层崩溃的系统性特征。
+
+### 支柱3：Monty - 防御性板块轮动
+
+**来源：** monty-trader.com "美国股市 判断股市顶部的方法及下跌阶段应做之事"
+
+**核心概念：** 在市场顶部之前，资金从进攻性/成长性板块流向防御性/价值型板块。这种"轮动"发生的原因是机构投资者在维持股票配置的同时变得更加防御。这是一个关键的早期预警信号。
+
+**防御性板块（避险资金）：**
+- XLU（公用事业）- 稳定现金流，类似债券
+- XLP（必需消费品）- 抗衰退需求
+- XLV（医疗保健）- 非可选支出
+- VNQ（房地产）- 以收入为导向
+
+**进攻性板块（成长/风险）：**
+- XLK（科技）- 依赖增长
+- XLC（通信服务）- 对广告支出敏感
+- XLY（可选消费）- 对经济敏感
+- QQQ（NASDAQ 100）- 以科技为主的成长代理
+
+**信号：** 当防御性板块在20日滚动期间跑赢进攻性板块时，资金正在防御性流动。相对表现差距达到+3%或以上是一个强烈的警告信号。
+
+---
+
+## 补充组件
+
+### 组件4：市场广度背离
+
+**概念：** 当指数创新高但参与的股票越来越少时，上涨正在收窄且变得脆弱。指数价格与市场广度之间的这种"背离"是经典的顶部信号。
+
+**关键指标：** S&P 500中高于200日移动平均线的股票百分比。
+- 健康市场：>70%的股票高于200日均线
+- 警告区域：50-70%且指数接近高点
+- 危急：<50%且指数处于高位
+
+**重要细节：** 广度背离在指数接近52周高点（在-5%以内）时最有意义。如果指数已经大幅回调，广度疲弱是意料之中的，信息量较小。
+
+### 组件5：指数技术状况
+
+**移动平均线结构：**
+- 健康：价格 > 21 EMA > 50 EMA > 200 SMA
+- 恶化：上述任何关系出现反转
+- 看空：价格低于所有主要移动平均线
+
+**形态识别：**
+- 反弹失败：价格反弹但未能超过近期峰值
+- 更低的高点：连续的波动高点持续下降
+- 放量跳空下跌：机构恐慌性抛售
+
+### 组件6：情绪与投机
+
+**VIX（恐慌指数）：**
+- <12：极度自满（警告）
+- 12-16：低波动率（轻微警告）
+- 16-20：正常
+- >25：恐惧升高（顶部可能性较低，回调可能已在进行中）
+
+**看跌/看涨比率：**
+- <0.60：极端看涨期权买入（最大程度自满）
+- 0.60-0.70：乐观情绪偏高
+- 0.70-0.80：温和看多
+- >0.80：健康的谨慎
+
+**VIX期限结构：**
+- 陡峭正价差：市场预期平静（自满信号）
+- 反向价差：套保需求升高（存在恐惧）
+
+---
+
+## 跟进确认日（FTD）监控
+
+O'Neil的底部确认概念，当综合评分 > 40时相关：
+
+1. **反弹尝试日：** 下跌后指数首次收涨的日子
+2. **开始计数：** 潜在新上升趋势的第1天
+3. **跟进确认日：** 在反弹尝试的第4-7天，出现强劲涨幅（1.5%+）且成交量高于前一天
+4. **重要性：** "最强劲的上升趋势通常以第4-7天的跟进确认日开始"
+
+**虚假FTD比率：** 大约25%的FTD会失败。多个FTD增加置信度。
+
+---
+
+## 评分理念
+
+### 为什么使用加权综合？
+
+没有单一指标能完美预测市场顶部。每个支柱捕捉不同的维度：
+- 派发日：机构卖出的直接衡量
+- 领头股：市场领导层的质量
+- 防御性轮动：机构仓位的转变
+- 广度：市场参与的健康度
+- 技术面：价格结构的完整性
+- 情绪：心理极端值
+
+### 权重依据
+
+- **派发日（25%）：** 最直接衡量机构行为
+- **领头股（20%）：** Minervini最有信心的信号
+- **防御性轮动（15%）：** Monty的关键差异化指标
+- **广度（15%）：** 经典的确认信号
+- **技术面（15%）：** 结构完整性检查
+- **情绪（10%）：** 背景和极端值（单独使用可靠性较低）
+
+### 校准原则
+
+评分的校准使得：
+- "正常"健康市场评分为10-20
+- "早期预警"市场评分为25-40
+- 处于"顶部形成初期到中期"的市场评分为40-55
+- 明确的顶部形成评分为60-80
+- 已完成的顶部伴随破位评分为80+

package/.claude/skills/market-top-detector/scripts/calculators/__init__.py

@@ -0,0 +1,17 @@
+"""Market Top Detector Calculator Modules"""
+
+from .distribution_day_calculator import calculate_distribution_days
+from .leading_stock_calculator import calculate_leading_stock_health
+from .defensive_rotation_calculator import calculate_defensive_rotation
+from .breadth_calculator import calculate_breadth_divergence
+from .index_technical_calculator import calculate_index_technical
+from .sentiment_calculator import calculate_sentiment
+
+__all__ = [
+    'calculate_distribution_days',
+    'calculate_leading_stock_health',
+    'calculate_defensive_rotation',
+    'calculate_breadth_divergence',
+    'calculate_index_technical',
+    'calculate_sentiment',
+]

package/.claude/skills/market-top-detector/scripts/calculators/breadth_calculator.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Component 4: Market Breadth Divergence (Weight: 15%)
+
+Data source: CLI arguments (collected via WebSearch before script execution)
+- breadth_200dma: % of S&P 500 stocks above 200DMA
+- breadth_50dma: % of S&P 500 stocks above 50DMA
+
+Scoring logic:
+  When index is near highs (within -5% of 52-week high):
+    200DMA_above < 40% -> 100 (Critical divergence)
+    200DMA_above < 50% -> 80
+    200DMA_above < 60% -> 60
+    200DMA_above < 70% -> 35
+    200DMA_above >= 70% -> 10
+
+  When index is NOT near highs (> -5%):
+    Score is halved (breadth divergence less meaningful when index is correcting)
+
+  50DMA breadth is used as a supplementary signal.
+"""
+
+from typing import Dict, Optional
+
+
+def calculate_breadth_divergence(breadth_200dma: Optional[float],
+                                 breadth_50dma: Optional[float],
+                                 index_distance_from_high_pct: float) -> Dict:
+    """
+    Calculate market breadth divergence score.
+
+    Args:
+        breadth_200dma: % of S&P 500 stocks above 200DMA (0-100)
+        breadth_50dma: % of S&P 500 stocks above 50DMA (0-100)
+        index_distance_from_high_pct: S&P 500 distance from 52-week high (negative %)
+
+    Returns:
+        Dict with score (0-100), signal, details
+    """
+    if breadth_200dma is None:
+        return {
+            "score": 50,
+            "signal": "NO DATA: Breadth data not provided (neutral default)",
+            "data_available": False,
+            "breadth_200dma": None,
+            "breadth_50dma": breadth_50dma,
+            "index_near_highs": False,
+            "divergence_detected": False,
+        }
+
+    index_near_highs = index_distance_from_high_pct >= -5.0
+
+    # Primary score based on 200DMA breadth
+    raw_score = _score_200dma_breadth(breadth_200dma)
+
+    # Halve score if index is NOT near highs
+    if not index_near_highs:
+        raw_score = raw_score * 0.5
+
+    # 50DMA breadth supplementary adjustment
+    if breadth_50dma is not None:
+        if breadth_50dma < 30 and index_near_highs:
+            raw_score = min(100, raw_score + 10)  # Extra warning
+        elif breadth_50dma > 70:
+            raw_score = max(0, raw_score - 5)  # Slight relief
+
+    score = round(min(100, max(0, raw_score)))
+
+    # Detect divergence
+    divergence_detected = index_near_highs and breadth_200dma < 60
+
+    if score >= 80:
+        signal = "CRITICAL: Severe breadth divergence - index at highs but breadth collapsing"
+    elif score >= 60:
+        signal = "WARNING: Significant breadth divergence"
+    elif score >= 35:
+        signal = "CAUTION: Mild breadth weakness"
+    elif divergence_detected:
+        signal = "WATCH: Some breadth deterioration despite index strength"
+    else:
+        signal = "HEALTHY: Breadth supports index level"
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "breadth_200dma": breadth_200dma,
+        "breadth_50dma": breadth_50dma,
+        "index_near_highs": index_near_highs,
+        "index_distance_from_high_pct": round(index_distance_from_high_pct, 1),
+        "divergence_detected": divergence_detected,
+    }
+
+
+def _score_200dma_breadth(breadth_200dma: float) -> int:
+    """Score based on % of stocks above 200DMA.
+
+    Calibrated thresholds (linearly interpolated):
+      < 40%  -> 100 (Critical divergence)
+      40-50% -> 100 to 55 (Severe)
+      50-60% -> 55 to 30 (Moderate)
+      60-70% -> 30 to 5  (Mild - still relatively healthy)
+      >= 70% -> 5         (Healthy breadth)
+
+    Calibration note: 62.26% should score ~24 (healthy/green signal)
+    """
+    if breadth_200dma < 40:
+        return 100
+    elif breadth_200dma < 50:
+        return round(100 - (breadth_200dma - 40) / 10 * 45)
+    elif breadth_200dma < 60:
+        return round(55 - (breadth_200dma - 50) / 10 * 25)
+    elif breadth_200dma < 70:
+        return round(30 - (breadth_200dma - 60) / 10 * 25)
+    else:
+        return 5

package/.claude/skills/market-top-detector/scripts/calculators/defensive_rotation_calculator.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Component 3: Defensive Sector Rotation (Weight: 15%)
+
+Compares defensive ETF performance vs offensive/growth ETF performance
+over the trailing 20 trading days.
+
+Defensive: XLU, XLP, XLV, VNQ
+Offensive:  XLK, XLC, XLY, QQQ
+
+Scoring (defensive_return - offensive_return):
+  +5.0% or more -> 100 (Strong rotation into defensives)
+  +3.0% or more -> 80
+  +1.5% or more -> 60
+  +0.5% or more -> 40
+  +0.0% or more -> 20
+  Negative       ->  0 (Growth leading = healthy)
+"""
+
+from typing import Dict, List
+
+DEFENSIVE_ETFS = ["XLU", "XLP", "XLV", "VNQ"]
+OFFENSIVE_ETFS = ["XLK", "XLC", "XLY", "QQQ"]
+
+
+def calculate_defensive_rotation(historical: Dict[str, List[Dict]],
+                                 lookback: int = 20) -> Dict:
+    """
+    Calculate defensive vs offensive sector rotation score.
+
+    Args:
+        historical: Dict of symbol -> list of daily OHLCV (most recent first)
+        lookback: Number of trading days to measure (default 20)
+
+    Returns:
+        Dict with score (0-100), relative_performance, details
+    """
+    def _calc_return(symbol_hist: List[Dict], days: int) -> float:
+        if not symbol_hist or len(symbol_hist) < days + 1:
+            return None
+        recent = symbol_hist[0].get("close", symbol_hist[0].get("adjClose", 0))
+        past = symbol_hist[days].get("close", symbol_hist[days].get("adjClose", 0))
+        if past == 0:
+            return None
+        return (recent - past) / past * 100
+
+    # Calculate average returns for each group
+    def_returns = []
+    def_details = {}
+    for symbol in DEFENSIVE_ETFS:
+        hist = historical.get(symbol, [])
+        ret = _calc_return(hist, lookback)
+        if ret is not None:
+            def_returns.append(ret)
+            def_details[symbol] = round(ret, 2)
+
+    off_returns = []
+    off_details = {}
+    for symbol in OFFENSIVE_ETFS:
+        hist = historical.get(symbol, [])
+        ret = _calc_return(hist, lookback)
+        if ret is not None:
+            off_returns.append(ret)
+            off_details[symbol] = round(ret, 2)
+
+    if not def_returns or not off_returns:
+        return {
+            "score": 50,
+            "signal": "INSUFFICIENT DATA (neutral default)",
+            "data_available": False,
+            "relative_performance": 0,
+            "defensive_avg_return": 0,
+            "offensive_avg_return": 0,
+            "defensive_details": def_details,
+            "offensive_details": off_details,
+            "lookback_days": lookback,
+        }
+
+    def_avg = sum(def_returns) / len(def_returns)
+    off_avg = sum(off_returns) / len(off_returns)
+    relative = def_avg - off_avg
+
+    score = _score_rotation(relative)
+
+    if score >= 80:
+        signal = "CRITICAL: Strong defensive rotation"
+    elif score >= 60:
+        signal = "WARNING: Defensive outperformance"
+    elif score >= 40:
+        signal = "CAUTION: Mild defensive rotation"
+    elif score >= 20:
+        signal = "MIXED: Slight defensive tilt"
+    else:
+        signal = "HEALTHY: Growth leading"
+
+    return {
+        "score": score,
+        "signal": signal,
+        "data_available": True,
+        "relative_performance": round(relative, 2),
+        "defensive_avg_return": round(def_avg, 2),
+        "offensive_avg_return": round(off_avg, 2),
+        "defensive_details": def_details,
+        "offensive_details": off_details,
+        "lookback_days": lookback,
+    }
+
+
+def _score_rotation(relative: float) -> int:
+    """Convert relative performance (defensive - offensive) to 0-100 score"""
+    if relative >= 5.0:
+        return 100
+    elif relative >= 3.0:
+        # Linear interpolation: 3.0 -> 80, 5.0 -> 100
+        return round(80 + (relative - 3.0) / 2.0 * 20)
+    elif relative >= 1.5:
+        return round(60 + (relative - 1.5) / 1.5 * 20)
+    elif relative >= 0.5:
+        return round(40 + (relative - 0.5) / 1.0 * 20)
+    elif relative >= 0.0:
+        return round(20 + relative / 0.5 * 20)
+    else:
+        # Negative: growth leading, healthy
+        # Scale from 0 to 20 as relative goes from -2.0 to 0
+        if relative >= -2.0:
+            return round(max(0, 20 + relative / 2.0 * 20))
+        return 0