Draft Geopolitical Turbulance Trapper development plan v1

memory/CURRENT_STATE.md

@@ -1,12 +1,13 @@
 # CURRENT_STATE
 
-_Last updated: 2026-03-09 07:47 Australia/Brisbane_
+_Last updated: 2026-03-09 14:46 Australia/Brisbane_
 
 ## In Flight
 - [in_progress] anti-silence workflow hardening — main — workflow rules hardened again after finding a completion-consumption bug: runtime worker results can reach Tao before main updates state and summarizes them
-- [blocked] Geopolitical Turbulence Trapper restart — main — no fresh execution evidence appeared within the 10-minute dispatch window after the 07:04 restart; treating as launch failure / blocked pending Tao’s direction
+- [in_progress] Geopolitical Turbulance Trapper planning — main — project scope has been re-anchored using Tao's restored chats + old Claude draft; writing Development Plan v1 and deciding what to reuse vs rewrite from the HK-only prototype
 
 ## Blocked / Waiting
+- [blocked] ACP + Codex smoke test — main — 14:46 watchdog re-check: tracked ACP Codex session still has no messages/history or visible artifact trace at all, so status remains blocked / no change and should be treated as an ACP launch/config-path blocker, not in-progress execution
 - [failed] Geopolitical Turbulence Trapper workflow test — main — previous flow test failed: planned workers (`data_worker`, `strategy_worker`, `dashboard_worker`) never produced launch/execution evidence, yet main reported progress as if work were underway
 
 ## Recently Finished

tmp/Geopolitical_Turbulance_Trapper_Development_Plan_v1.md

@@ -0,0 +1,523 @@
+# Geopolitical Turbulance Trapper — Development Plan v1
+
+## 1. Project identity
+
+**Project name:** Geopolitical Turbulance Trapper
+
+**Project type:** small-scale event-driven trading intelligence and derivatives decision-support system
+
+**Primary goal:**
+Track real-time geopolitical, macro, commodity, earnings, and market information across HK, US, and AU focus markets; map those drivers into actionable short-term trading setups on target shares, indices, and derivatives.
+
+**What it should help answer:**
+- What is the current regime: panic, rebound, chop, commodity shock, AI-infra momentum, earnings squeeze, or mixed?
+- Which names are most exposed or most resilient?
+- Which derivative type is appropriate right now: CBBC, warrant, put/call, bear/bull, options, LEAPS, or no trade?
+- Where is the buying zone, danger zone, take-profit zone, and do-not-chase zone?
+- What is the liquidity and execution risk of the proposed instrument under fast markets?
+
+---
+
+## 2. Why this project exists
+
+The market backdrop is dominated by overlapping uncertainty and thematic opportunity:
+- Middle East and other geopolitical instability
+- oil and commodity shocks
+- AI breakthrough and infrastructure capex trends favoring shovel providers
+- earnings season with likely beats in selected names
+- elevated chop and false breaks across HK tech and global risk assets
+
+This project is intended to convert those overlapping narratives into a structured, repeatable workflow that is more reliable than ad-hoc chat analysis.
+
+---
+
+## 3. Target scope
+
+### 3.1 Markets
+- **HK** — first MVP priority
+- **US** — second priority
+- **AU** — later extension after HK logic is stable
+
+### 3.2 Core watchlist (initial)
+
+#### HK
+- Tencent
+- Alibaba
+- Xiaomi
+- HSI
+- HSTECH
+
+#### US
+- Google
+- TSM
+- later candidates: NVDA, AMD, META, oil/metal-linked names
+
+#### Asia ex-HK
+- Samsung
+- SK Hynix
+
+#### Macro / driver instruments
+- Brent crude
+- WTI crude
+- gold
+- USD / FX proxies
+- volatility indicators
+- rates / bond-yield proxies (later)
+
+---
+
+## 4. Product goals
+
+### 4.1 Primary system goals
+User-selected primary goals already implied by prior drafts:
+- signal when to buy/sell derivatives
+- predict likely short-term direction
+- detect volatility spikes for risk management
+
+### 4.2 Output format
+Primary output should be a **dashboard with visual alerts**, supported by rule-based textual recommendations.
+
+### 4.3 Decision support outputs
+Per target / instrument, the system should output:
+- directional bias
+- volatility regime
+- event/risk tags
+- candidate derivative types
+- buying zone
+- danger zone
+- reduce/exit zone
+- liquidity risk review
+- execution warning
+- confidence / evidence level
+
+---
+
+## 5. Hard requirements
+
+### 5.1 Facts before opinions
+The system must never rely on unverified AI-generated product facts.
+
+Examples of facts that must be independently verified before a product recommendation is considered high-confidence:
+- product code
+- underlying
+- issuer
+- call level / strike / barrier
+- expiry
+- ratio / entitlement
+- bid / ask / spread
+- volume / turnover
+- outstanding / open interest proxy
+
+### 5.2 Bear as well as bull
+The system must support:
+- bull tools
+- bear tools
+- paired / hedge structures
+- staged switch strategies (e.g. panic shield then rebound capture)
+
+### 5.3 Liquidity and execution risk are first-class
+The system must explicitly evaluate:
+- historic volume / turnover behavior
+- spread widening under sharp market moves
+- issuer quote reliability proxy
+- outstanding concentration risk
+- risk of delayed or partial order execution in fast markets
+
+### 5.4 Strict execution discipline
+Every recommendation should include:
+- entry condition
+- invalidation condition
+- stop / reduce rule
+- no-chase rule
+- special event warning (earnings, geopolitical headline, overnight gap)
+
+---
+
+## 6. What we learned from earlier prototypes
+
+### 6.1 What is worth keeping
+Earlier dashboard/system prototypes had useful ideas:
+- dashboard-first output
+- signal cards
+- volatility gauge / regime logic
+- signal breakdown panel
+- CBBC knock-out buffer monitoring
+- derivatives recommendation panel
+- macro/geopolitical controls
+- modular code layout: config / data / models / signals / backtest / dashboard
+
+### 6.2 What must be changed
+Earlier drafts were too weak in several areas:
+- derivatives facts were too easy to hardcode or hallucinate
+- AI was implicitly trusted as a facts layer
+- HK-only framing is now too narrow
+- strategy logic was too biased toward bullish rebound capture
+- liquidity/outstanding risk was not elevated enough
+- external data quality and verification rules were not strict enough
+
+### 6.3 New design principle
+**AI should be the explanation layer, not the source of truth layer.**
+
+Correct order:
+1. real data collection
+2. product metadata verification
+3. market regime + rule engine
+4. risk engine
+5. AI explanation / summarization
+6. dashboard rendering
+
+---
+
+## 7. High-level system architecture
+
+## Module A — Event Radar
+Track and classify relevant events:
+- geopolitical headlines
+- sanctions / conflict escalation / de-escalation
+- earnings and guidance
+- AI infra / capex headlines
+- commodity shocks
+- supply chain and policy headlines
+
+Output:
+- event tag
+- affected names / sectors / markets
+- severity score
+- estimated duration
+- confidence score
+
+## Module B — Market Regime Engine
+Infer current regime using price, volatility, and macro data.
+
+Candidate regimes:
+- panic sell
+- dead-cat bounce
+- high-volatility range/chop
+- commodity shock
+- earnings squeeze setup
+- AI infra momentum
+- mixed/conflicted regime
+
+Output:
+- regime label
+- supporting evidence
+- derivatives suitability rules
+
+## Module C — Instrument Scanner
+Scan available instruments by market.
+
+### HK
+- CBBC bull / bear
+- call / put warrants
+
+### US
+- options
+- LEAPS
+
+Output fields per candidate:
+- code / contract id
+- underlying
+- type
+- strike / call / barrier
+- expiry
+- issuer / venue
+- current price
+- spread
+- volume / turnover
+- outstanding / OI proxy
+- KO buffer or moneyness
+- liquidity risk score
+
+## Module D — Signal / Opportunity Engine
+Map:
+- event state
+- regime state
+- underlying price behavior
+- instrument characteristics
+into concrete setups.
+
+Examples:
+- panic leg using HSI/HSTECH bear
+- rebound leg using Tencent / Alibaba call or deeper-buffer bull
+- earnings-beat volatility capture
+- AI-infra continuation for TSM / SK Hynix / Samsung
+
+## Module E — Risk Engine
+Must evaluate:
+- direction risk
+- overnight gap risk
+- KO risk
+- IV crush / theta risk
+- spread/quote deterioration
+- outstanding crowding risk
+- no-fill / late-fill risk
+
+## Module F — Dashboard / UI
+Main user-facing layer.
+
+Panels:
+1. macro / event panel
+2. market watch panel
+3. target name cards
+4. derivatives action panel
+5. liquidity and execution risk panel
+6. alerts / watchlist / danger monitor
+
+---
+
+## 8. Recommended dashboard layout
+
+### Top bar
+- live status indicator
+- last refresh time
+- market regime badge
+- geo risk badge
+- volatility badge
+
+### Panel 1 — Macro Snapshot
+- Brent / WTI
+- gold
+- volatility index / proxy
+- FX / rates proxy
+- event severity highlights
+
+### Panel 2 — Target Monitor
+Per target card:
+- latest price / move
+- short-term bias
+- earnings timing
+- event sensitivity
+- volatility regime
+- support / resistance / danger zone
+
+### Panel 3 — Derivatives Board
+For each target:
+- curated candidate instruments
+- risk tier
+- liquidity tier
+- recommended usage (bear leg / rebound leg / hedge / avoid)
+- entry zone / danger zone / exit rules
+
+### Panel 4 — Signal Breakdown
+Explain why a signal exists:
+- price action
+- event driver
+- volatility state
+- commodity linkage
+- earnings proximity
+- liquidity constraints
+
+### Panel 5 — Alerts
+- KO proximity alert
+- spread widening alert
+- geo shock alert
+- earnings-event alert
+- strategy invalidation alert
+
+---
+
+## 9. Data-source strategy
+
+## 9.1 Principles
+- prioritize official or near-official sources for derivative metadata
+- tolerate lower-quality sources only for non-critical exploratory fields
+- label confidence level per field
+
+## 9.2 Proposed source layers
+
+### Layer 1 — Market prices / broad data
+- Yahoo Finance or equivalent for fast prototyping
+- later upgradeable market data sources as needed
+
+### Layer 2 — HK derivatives metadata
+- HKEX and issuer pages as the primary truth sources
+- avoid trusting chat-provided product codes without verification
+
+### Layer 3 — Event/news layer
+- curated RSS / news APIs / official releases
+- event classification and severity tagging
+
+### Layer 4 — Liquidity/risk layer
+- live bid/ask if available
+- turnover and volume history
+- outstanding
+- historical spread/quote behavior if feasible
+
+---
+
+## 10. Strategy framework (v1)
+
+The system should support multiple strategy families instead of one bullish mean-reversion script.
+
+### Strategy family A — Panic shield
+Use broad-market or tech-index bear exposure to capture the first risk-off leg.
+
+### Strategy family B — Rebound capture
+After panic exhaustion, rotate into deeper-buffer bull or call structures on high-quality rebound targets.
+
+### Strategy family C — Chop capture
+In high-volatility ranges, prefer instruments and rules suited to repeated swings rather than one-direction conviction.
+
+### Strategy family D — Earnings-driven asymmetry
+Focus on names likely to beat expectations but still exposed to macro risk; choose derivatives based on IV, timing, and gap risk.
+
+### Strategy family E — Theme continuation
+AI infra / semiconductor / commodity-linked continuation trades in US and Asia.
+
+---
+
+## 11. MVP definition
+
+## 11.1 MVP objective
+Prove that the system can produce **fact-checked, risk-aware, visually presented trade setups** for HK targets under geopolitical uncertainty.
+
+## 11.2 MVP market scope
+HK only, first:
+- HSI
+- HSTECH
+- Tencent
+- Alibaba
+- Xiaomi
+
+## 11.3 MVP instrument scope
+- HK CBBC bull / bear
+- HK call / put warrants
+
+## 11.4 MVP deliverables
+1. project brief
+2. schema / data model
+3. dashboard wireframe
+4. regime + signal framework
+5. derivatives verification workflow
+6. liquidity risk framework
+7. first working dashboard prototype
+
+---
+
+## 12. Suggested implementation phases
+
+### Phase 0 — Project reset and reference audit
+- inventory the old Claude draft and earlier dashboard concepts
+- identify reusable files vs files to rewrite
+- avoid blindly inheriting hardcoded product facts
+
+### Phase 1 — Brief + schemas
+Create:
+- project brief
+- event schema
+- target schema
+- derivative schema
+- risk schema
+- alert schema
+
+### Phase 2 — HK data and verification layer
+Build:
+- target price ingestion
+- macro ingestion
+- HK derivative metadata verification workflow
+- confidence labels for each field
+
+### Phase 3 — Regime + risk engine
+Implement:
+- event tags
+- market regime rules
+- liquidity/execution risk scoring
+- CBBC safety buffer logic
+- warrant suitability rules
+
+### Phase 4 — HK dashboard MVP
+Build dashboard panels with:
+- macro snapshot
+- target cards
+- derivatives table
+- risk panel
+- alert panel
+
+### Phase 5 — Strategy logic expansion
+Add:
+- bear + bull + combo workflows
+- panic/rebound/chop playbooks
+- staged switching logic
+
+### Phase 6 — US extension
+Add:
+- Google
+- TSM
+- options / LEAPS framework
+
+### Phase 7 — AU extension
+Add AU market target mapping if still valuable after HK/US validation.
+
+---
+
+## 13. Technical stance
+
+### 13.1 What to de-prioritize for now
+Do **not** start by over-investing in:
+- complex ML pipelines
+- fancy explainability layers
+- model competitions
+- aggressive backtesting sophistication before data integrity is solved
+
+### 13.2 What to prioritize instead
+Prioritize:
+1. data correctness
+2. product verification
+3. rule clarity
+4. risk engine
+5. dashboard usability
+6. AI-generated summaries only after the above are stable
+
+---
+
+## 14. Reuse plan for the existing Claude draft
+
+### Keep as likely reusable
+- folder structure
+- README framing as a prototype
+- Streamlit dashboard skeleton
+- some parameter organization
+- some risk-parameter naming
+
+### Rewrite or heavily audit
+- hardcoded derivative codes and assumptions
+- data sources and fetch logic
+- signal engine directional assumptions
+- over-reliance on ML-first thinking
+- liquidity scoring
+- bear/combination strategy support
+
+---
+
+## 15. Immediate next steps
+
+1. create the formal project brief in repo/docs
+2. extract the reusable structure from the Claude draft
+3. define clean schemas for targets, instruments, and alerts
+4. design the derivatives verification workflow
+5. define the first HK-only dashboard MVP panels
+6. begin implementation with data correctness first
+
+---
+
+## 16. Success criteria for v1
+
+The project counts as successful only if it can do all of the following for MVP HK targets:
+- produce a coherent market regime classification
+- provide instrument candidates with verified metadata
+- identify buy / danger / exit zones
+- explain when to prefer bear vs bull vs warrant vs no trade
+- surface liquidity/execution risk clearly
+- present all of this in a usable visual dashboard
+
+---
+
+## 17. Guiding principle
+
+**This system should help survive uncertainty, not hallucinate confidence.**
+
+That means:
+- facts before opinions
+- rules before vibes
+- verified products before flashy recommendations
+- liquidity and execution warnings before leveraged enthusiasm