Stabilize review v2 workflow and English contracts

[atomchung]

Summary

• replace the long agent-owned workflow with a thin cross-agent skill entry and deterministic prepare/preview/finalize orchestration
• add resumable session bundles, atomic finalization, public/private card separation, and repairable projections
• persist thesis evidence and require a claim plus source before an add can be classified as new evidence
• add ETF-aware instrument policy so diversified allocation ETFs are exempt from single-company concentration checks while focused and leveraged ETFs remain risk exposures
• move implementation contracts, lens configs, and developer documentation to English while keeping GTM and localized product copy in explicit locale files
• add bilingual card rendering, English runtime dimension IDs, schemas, flows, references, evals, and release documentation

Why

The previous workflow depended on agents following one long skill prompt and mixed deterministic calculations with agent judgment. That made interruption recovery, cross-agent parity, ETF handling, thesis learning, and card output less predictable.

This change moves lifecycle, validation, persistence, localization, and rendering into shared code. Agents retain the narrow judgments that matter: interpreting motive, connecting evidence to thesis evolution, and writing the narrative.

User and developer impact

• one canonical command starts a review: python3 engine/review.py prepare <CSV...> --language en
• interrupted reviews resume without refetching live prices
• preview validation rejects unsupported numbers or evidence classification
• finalization commits one user-chosen rule, with skip as a valid outcome
• private trade details cannot leak into the public card projection
• broad allocation ETFs no longer trigger single-company sizing false positives
• future mixed-language drift in implementation surfaces fails a deterministic test

Validation

• python3 tests/run_all.py
• all 14 suites passed
• 68 engine unit tests passed
• 75 TR_JSON/state contract checks passed
• 9 v2 session, ETF, localization, and E2E tests passed
• 3 implementation-language boundary tests passed
• 2 opt-in network persona probes were skipped as designed
• git diff --check

[atomchung]

Review 結論(4 路深查 + E2E 實測,base c6850f0 / head fcd802d)

架構方向正確(薄入口+flows/references 漸進披露、prepare/preview/finalize 確定性編排、原子 session bundle、schema gate 實測有牙齒、#166 冪等保留、#89 data-agnostic 保留),但以現狀不可直接 merge:

CONFIRMED merge-blockers(將以 fix PR 疊在本 PR 上處理)

1. 公卡洩漏:custom commitment rule 無過濾原樣上公卡(review.py:354-358 → card_renderer.py:375),實測含 ticker/價位/日期的自訂規矩直接印在「已移除金額、日期、標的」badge 下——命中 release doc 自己的 no-go 條件
2. repair-projections 把 test-drive demo 灌進真實教練記憶(session.py:246-258 無 persist 過濾),實測 last_state.json 被 mock 狀態覆蓋
3. test-drive 照文檔跑不通:未帶 --root 時 root=隨機 mkdtemp(review.py:282-285),preview 必報 pending not found——promotion demo 步驟 1-4 當場翻車
4. BACKLOG 北極星反轉:fix(docs): BACKLOG 北極星敘事對齊 2026-07-05 糾偏 — 約束在卡品質非分發找人 (closes #112) #189(closes [process·P1] 關鍵產品假設無時效標記，過時結論被跨 session 複讀（Stage 0 話術案例） #112,分支前 11 小時 merge)的「約束在卡品質非分發找人」被刪除並反轉回分發導向敘事
5. 英文公卡混中文(「behavioral pressure in 部位 sizing」,card_renderer.py:357-360 漏走 dim 映射)

靜默推翻既有拍板 / 產品線斷裂(一期恢復)

• [design] 卡片呈現一致性完全依賴執行當下的 self-check 自律,沒有機械式強制 #82 誠實揭露形態被反轉:copy 死文案+獨立「資料邊界」checklist section(新 CLAUDE.md/card-spec 字面仍寫「不印 checklist」——spec 與 code 自相矛盾)
• acct_perf(feat(engine+skill): 帳戶級績效 — daily 鏈式 TWR + cash drag + 帳戶 IRR (closes #171) #179/feat(engine+skill): 多錨點對帳殘差 — rollforward 量化漏記金流、帳戶報酬 opt-in 解鎖 (closes #180) #181)engine 照算(實測 hold_twr 4.845+解鎖 note)但 renderer 完全不渲染——帳戶柱+解鎖邀請死在 engine 與卡之間
• 對帳開場句(fix(engine): 輸入層丟棄計數上卡面 + revisit_id 補 cycle_id 段 (closes #50 #143) #151/docs(skill+readme): 每週迴圈用戶端指引 — 第二週餵全歷史 + 收尾回訪鉤子 (closes #52) #152)結構性不可能:renderer 無 prior_commitment 段+agent 禁數字
• TR_CASH UX(feat(engine): 現金流 ingestion 地基 — engine 吃得到現金 + 存 state (refs #171) #174/feat(engine+skill): cash 呈現層 — 現金上卡 + 入金判讀 + 無錨點誠實揭露 (refs #171) #175)與台股 .TW/.TWO 標注規則([feat·多市場] 台股任意格式自動轉標準 CSV + 台股個股報價 — engine 只吃標準格式,Claude Step 0 負責認格式 #173)從文檔消失(plumbing 還在)
• ETF 豁免半套:dim_avgdown/問題帳/thesis 質詢仍會質詢 SPY 定投(refs [design] 集中度/分散規則對廣基 ETF 誤判 + 缺持有成本/tracking error 維度 #138)

拆二期(需 owner 判斷或獨立接線)

• [P0-next·v2] 週記憶迴圈在 review v2 未接線:revisit/賣出理由 capture/ledger 記帳/市場背景/horizon 鏡子全斷,賣出理由每週不可回補流失 #191 週記憶迴圈接線(revisit/賣出理由 capture——每週不可回補流失/ledger/market_context/horizon/emotion/[P0·分發] Step 4 反饋迴路沒有落地管道 — Stage 0 收不到「戳中沒」 #42)
• [需拍板·v2] 鏡片哲學層在 v2 退役 + 引語證據庫改 paraphrase:去留與 README 賣點需 owner 逐項拍板 #192 鏡片哲學層退役+引語證據庫 paraphrase 化+CJK CI 禁令+v2c 閥語意(逐項拍板)
• [P1·v2] 公卡與混市場渲染二期:公卡內容量歸零、by_market 兩行與 excess_split 拆帳算了沒渲染 #193 公卡內容量歸零+by_market/excess_split 未渲染
• [P2·v2] 工程加固:中文數字繞過 digit-ban、fsync/staging GC、v1/v2 session_id 分岔、snapshot adapter 缺位 #194 工程加固(中文數字繞 digit-ban/fsync/session_id 分岔/snapshot adapter 缺位)

為什麼 14 套測試全綠仍有這些

測試與實作同 PR 換血:新測試只驗 v2 新行為(公卡只測 candidate 路徑、隔離只測 finalize 當下),舊行為斷言(EVALS B 系列)被同 PR 刪除/泛化——測試綠證明新實作自洽,不證明行為保真。

認領:fix PR 將從 fcd802d 開 branch 疊修復(上列 blockers+拍板恢復),測試全綠後開 PR 供 view,merge 後本 PR 由該 PR supersede。

🤖 Generated with Claude Code

[atomchung]

Fix PR is up: #195 (contains this PR's commit fcd802d plus three fix commits — blockers, ruled-behavior restorations, and doc contract). Once #195 merges, this PR can be closed. Phase-2 decisions live in #191–#194.

[atomchung]

Superseded by #195 (merged to main as 97ffb52): contains this PR's full content plus the review fixes. Phase-2 decisions tracked in #191-#194.