feat(engine): 市場背景注入 — SPY/QQQ/VIX 週漲跌進復盤卡 (refs #37)

[atomchung]

這個 PR 做什麼

#129 次線執行序順序 3(#37):卡只有「你做了什麼」,沒有「市場那週在幹嘛」——虧 3% 是選錯股還是大盤本來就跌 3%?買在高點還是買在 QQQ +5% 的相對強勢週?

engine/market_context.py(新,獨立 CLI)

• fetch 薄層:yfinance 抓日線;離線/未裝 → error 欄誠實退化,絕不 crash 主流程(對齊 fetch_fx/fetch_prices 既有模式)。
• 計算純函式層(compute_context):吃 {symbol: [(date, close)...]},零 pandas 依賴,離線可測。
• 語意:window_ret = 窗口前收→窗口末收;ytd_ret 錨在去年最後收盤;VIX 是水平值(last/prev/delta),不當資產報酬;缺錨 → null 不硬算;窗口內沒價的 symbol 誠實缺席。
• 窗口由呼叫端(SKILL)決定:對帳 = 上次 log date_end → 本次;初診 = 往前 7 天。engine 不猜週期。

SKILL.md + card-spec.md

• Step 1 順跑指令 + 三個用途:① 卡開頭〔市場那週〕一行(有數據才出,離線整行不出、不硬掰)② 歸因語境(「你砍在 SPY −4% 的恐慌週」)③ Step 2 動機輔助訊號(大漲週進場=FOMO 候選——只輔助選問誰,定性永遠來自回答)。
• 明確 out of scope:帳戶 vs 大盤的數字級 relative perf 需要每週市值序列(engine 目前沒有)——SKILL 明令別自己算,[Phase 2] 市場背景自動注入：SPY/QQQ/VIX 週漲跌進復盤卡 #37 留 open 追蹤數字版。

測試(第八套)

窗口/YTD 錨點、VIX 水平值、缺資料誠實缺席、亂序輸入、單日窗口、CLI 參數防呆、TR_TEST_NETWORK smoke。run_all.py + CLAUDE.md 鏡像「七套→八套」同步。

掃過的範圍

• 鏡像:CLAUDE.md 三處「七套」全改;eval 兩檔只錨「最大的洞」判準、不列區塊清單,不需同步;README 照 feat(engine): revisit 30/60/90 + swap 機會成本 — 出場邊緣不再是盲區 (PR-3 of #129) #134 前例不動。
• 已實跑 live CLI 驗證(2026-06-29~07-03:SPY +2.2% / QQQ +0.9% / VIX 16.15 前週 18.41;7/3 休市日末筆自然落 7/2,窗口語意正確)。

測試結果

離線八套全綠;TR_TEST_NETWORK=1 smoke 過。

refs #37(語境版落地;數字級 relative perf 留 open)

🤖 Generated with Claude Code

[atomchung]

Triad Review — PR #145(文本模式:Claude / Codex / Gemini)

審查焦點:compute 錨點語意(跨年/單日/缺錨)、yfinance 回傳形狀容錯、離線退化契約、鏡像同步。

⚠️ 單方 findings(Codex 用 stub 實測驗證,全採納;修在 05d81ba)

1. 部分 symbol 缺席時 error=None 但 benchmarks 不齊(stub 驗證:QQQ 全 NaN → 只回 SPY/VIX)——SKILL/卡面假設三家都在會硬掰。→ 輸出加 missing 契約;SKILL/card-spec 改「有什麼講什麼,缺的略過」。
2. fetch 形狀防禦不足:單 symbol Series 用 .get(sym) 會誤查日期 index;缺 Close 欄直接 KeyError(違反檔頭「絕不 crash」契約)。→ columns/Series 分支判斷 + 整段解析包 error 退化。
3. fetch 層只有 optional network smoke 覆蓋 → 加 fake-yfinance deterministic tests ×4(MultiIndex+NaN 欄、Series 形狀、缺 Close、download raise)。
4. 跨年窗口 window_ret 與 ytd_ret 可符號相反(語意正確但不直覺,兩錨不同)→ 測試鎖住防未來誤改。

Gemini findings(2/2 引文驗證屬實,已修)

• CLAUDE.md 之外還有兩處「七套」漏網:pre_commit_test_gate.sh(註解+deny 訊息)、docs/prd-ledger.md(PR 檢查清單)→ 改成無數字措辭(「測試沒全過」「以 run_all 總結輸出為準」),下次加套件不會再 drift。
• 另確認:SKILL 引用的輸出鍵與 engine 實際 JSON 全對齊;〔市場那週〕行不違反「不准 dashboard」禁令(總覽區塊本就是括號行格式);trade_recap 與 market_context 的 fetch 職責分離乾淨。

Claude 方

錨點語意重走一遍(跨年 min-pad、1 月初 end 的去年 12/15 錨、長假 14 天 pad)無誤;VIX 水平值不當報酬。

測試

八套全綠(market_context 套 13 測試);TR_TEST_NETWORK=1 smoke 過;live CLI 實跑驗證(7/3 休市末筆自然落 7/2)。