Create geopolitical turbulence trapper project skeleton

2026-07-21 21:15:07 +00:00 · 2026-03-09 15:00:24 +10:00
parent d56506a0c9
commit 8d1002f41d
10 changed files with 183 additions and 0 deletions
@@ -17,6 +17,7 @@ _Last updated: 2026-03-09 14:46 Australia/Brisbane_
 - GPT-5.4 support restored again after update-related breakage; if it breaks again, report Tao immediately

 ## Next
+- continue Geopolitical Turbulance Trapper from planning into verified HK-first data/derivatives workflow
 - apply CURRENT_STATE + dual reporting rules in practice
 - later decide whether to package continuity workflow as a skill, clawkeeper feature, or both
 - monitor GPT-5.4 availability and report any fallback/unavailability immediately
@@ -0,0 +1,22 @@
+# Geopolitical Turbulance Trapper
+
+Small-scale event-driven trading intelligence and derivatives decision-support system.
+
+## Current focus
+- HK-first MVP
+- dashboard-first output
+- verified derivatives metadata before recommendation
+- liquidity / execution risk as first-class signals
+
+## Planned modules
+- `docs/` — brief, roadmap, decisions
+- `schemas/` — target / derivative / alert / risk schemas
+- `src/events/` — event tagging and severity logic
+- `src/regime/` — market regime classification
+- `src/instruments/` — derivative metadata verification and suitability logic
+- `src/risk/` — liquidity / execution / gap / KO risk logic
+- `src/signals/` — actionable strategy outputs
+- `src/dashboard/` — UI layer
+
+## Status
+Early project skeleton created from Development Plan v1 on 2026-03-09.
@@ -0,0 +1,26 @@
+# Derivatives Verification Workflow
+
+Before any derivative is elevated from candidate to recommendation:
+
+1. Verify underlying-symbol mapping.
+2. Verify instrument type (CBBC, warrant, option, LEAP).
+3. Verify call/barrier/strike/expiry/ratio from a trusted source.
+4. Record issuer / venue.
+5. Record bid, ask, spread, volume, turnover, and outstanding when available.
+6. Mark verification status:
+   - `unverified`
+   - `partial`
+   - `verified`
+7. Do not present `unverified` products as high-confidence trade suggestions.
+
+## Extra checks for HK CBBC / warrants
+- KO/call buffer vs current underlying price
+- liquidity deterioration risk near barrier
+- outstanding concentration risk
+- likely spread behavior under fast markets
+
+## Extra checks for US options / LEAPS
+- IV level and term structure
+- theta decay
+- option volume / OI
+- earnings event proximity
@@ -0,0 +1,26 @@
+# Project Brief
+
+## Goal
+Track geopolitical, macro, commodity, earnings, and market information across HK / US / AU focus markets and convert them into actionable derivatives trading support.
+
+## MVP
+HK-first:
+- HSI
+- HSTECH
+- Tencent
+- Alibaba
+- Xiaomi
+
+## Key outputs
+- market regime
+- derivative candidates
+- buy zone / danger zone / reduce zone
+- liquidity and execution risk review
+- dashboard alerts
+
+## Hard rules
+- facts before opinions
+- verify product metadata before recommendation
+- support bear as well as bull workflows
+- treat liquidity / outstanding / spread risk as first-class
+- AI explains; AI does not act as the facts source
@@ -0,0 +1,21 @@
+# Roadmap
+
+## Step 1
+- establish schemas
+- define HK-first target universe
+- formalize verification-first derivatives workflow
+
+## Step 2
+- build data-source adapters for price and macro snapshots
+- build derivative metadata ingestion/verification stubs
+
+## Step 3
+- implement regime and risk engine
+- define bear / bull / combo playbooks
+
+## Step 4
+- build dashboard MVP
+- add alerts for entry zone, danger zone, KO risk, and spread widening
+
+## Step 5
+- extend to US targets and options / LEAPS
@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "StrategyAlert",
+  "type": "object",
+  "required": ["type", "severity", "target", "message"],
+  "properties": {
+    "type": {"type": "string", "enum": ["entry_zone", "danger_zone", "exit_zone", "ko_risk", "spread_widening", "event_shock", "vol_spike", "earnings_window"]},
+    "severity": {"type": "string", "enum": ["info", "warning", "high", "critical"]},
+    "target": {"type": "string"},
+    "instrumentCode": {"type": ["string", "null"]},
+    "message": {"type": "string"},
+    "evidence": {"type": "array", "items": {"type": "string"}},
+    "timestamp": {"type": ["string", "null"], "format": "date-time"}
+  }
+}
@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DerivativeCandidate",
+  "type": "object",
+  "required": ["underlying", "market", "instrumentType", "direction"],
+  "properties": {
+    "underlying": {"type": "string"},
+    "market": {"type": "string", "enum": ["HK", "US", "AU"]},
+    "instrumentType": {"type": "string", "enum": ["CBBC", "WARRANT", "OPTION", "LEAP"]},
+    "direction": {"type": "string", "enum": ["bull", "bear", "call", "put", "combo"]},
+    "code": {"type": "string"},
+    "issuer": {"type": "string"},
+    "callLevel": {"type": ["number", "null"]},
+    "strike": {"type": ["number", "null"]},
+    "expiry": {"type": ["string", "null"], "format": "date"},
+    "entitlementRatio": {"type": ["number", "null"]},
+    "bid": {"type": ["number", "null"]},
+    "ask": {"type": ["number", "null"]},
+    "spreadPct": {"type": ["number", "null"]},
+    "volume": {"type": ["number", "null"]},
+    "turnover": {"type": ["number", "null"]},
+    "outstandingPct": {"type": ["number", "null"]},
+    "verificationStatus": {"type": "string", "enum": ["unverified", "partial", "verified"]},
+    "liquidityRisk": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
+    "notes": {"type": "string"}
+  }
+}
@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "InstrumentRiskReview",
+  "type": "object",
+  "required": ["target", "instrumentType"],
+  "properties": {
+    "target": {"type": "string"},
+    "instrumentType": {"type": "string"},
+    "gapRisk": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
+    "koRisk": {"type": ["string", "null"], "enum": ["low", "medium", "high", "critical", null]},
+    "ivRisk": {"type": ["string", "null"], "enum": ["low", "medium", "high", "critical", null]},
+    "thetaRisk": {"type": ["string", "null"], "enum": ["low", "medium", "high", "critical", null]},
+    "liquidityRisk": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
+    "executionRisk": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
+    "headlineRisk": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
+    "summary": {"type": "string"}
+  }
+}
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "TargetInstrumentUniverseItem",
+  "type": "object",
+  "required": ["id", "market", "symbol", "name", "category"],
+  "properties": {
+    "id": {"type": "string"},
+    "market": {"type": "string", "enum": ["HK", "US", "AU", "MACRO"]},
+    "symbol": {"type": "string"},
+    "name": {"type": "string"},
+    "category": {"type": "string", "enum": ["equity", "index", "commodity", "fx", "volatility"]},
+    "themeTags": {"type": "array", "items": {"type": "string"}},
+    "eventSensitivity": {"type": "object", "additionalProperties": {"type": "number"}},
+    "notes": {"type": "string"}
+  }
+}
@@ -0,0 +1,11 @@
+{
+  "targets": [
+    {"id": "hk_tencent", "market": "HK", "symbol": "0700.HK", "name": "Tencent", "category": "equity", "themeTags": ["ai", "internet", "china-tech"]},
+    {"id": "hk_alibaba", "market": "HK", "symbol": "9988.HK", "name": "Alibaba", "category": "equity", "themeTags": ["cloud", "ecommerce", "china-tech"]},
+    {"id": "hk_xiaomi", "market": "HK", "symbol": "1810.HK", "name": "Xiaomi", "category": "equity", "themeTags": ["consumer-electronics", "ev", "china-tech"]},
+    {"id": "hk_hsi", "market": "HK", "symbol": "^HSI", "name": "HSI", "category": "index", "themeTags": ["hk-index"]},
+    {"id": "hk_hstech", "market": "HK", "symbol": "3032.HK", "name": "HSTECH proxy", "category": "index", "themeTags": ["hk-tech-index"]},
+    {"id": "macro_brent", "market": "MACRO", "symbol": "BZ=F", "name": "Brent Crude", "category": "commodity", "themeTags": ["oil", "macro-driver"]},
+    {"id": "macro_wti", "market": "MACRO", "symbol": "CL=F", "name": "WTI Crude", "category": "commodity", "themeTags": ["oil", "macro-driver"]}
+  ]
+}