Markets are a wiretap. People who know things have to trade on them — they cannot resist their own information.
Cross-asset volatility forensics for detecting political signal in the price tape. The thesis: when the slow-burn third world war goes hot or opens a new front, it bleeds into FX, commodities, rates, defense equities, and derivatives positioning — simultaneously, before the press catches up. This project reads those fingerprints.
No theoretical edifice. Their tools, their fingerprints.
- Harvests weekly price and positioning data across a cross-asset basket (FX, commodities, rates, vol indices, defense equities, CFTC COT).
- Computes realized volatility z-scores against each instrument's own rolling 52-week history — no look-ahead by construction.
- Flags weeks where ≥5 instruments spike simultaneously. Each such week is a cluster.
- Pre-registers each cluster to a tamper-evident ledger before any news is read. This is the load-bearing discipline.
- Annotates cluster weeks with lateral news sourcing: mainstream, trade press, and regional/non-Anglosphere.
- Spine-tags annotations — classifying each by a named risk premise (
spine_id), its prior state (latent/activated/novel), and flip magnitude. - Subtracts a financial baseline: instruments explained by pure financial-structure spines get
residual_z = 0. What remains is political bleed-through. - Overlays Polymarket contract prices for lead/lag analysis against cluster weeks.
The whole project hinges on step 4. Without pre-registration this is a confirmation-bias machine.
| Metric | Value |
|---|---|
| Clusters registered | 52 (2001–2025) |
| Prospective clusters | 5 — locked before any news read (2022w45, 2024w30, 2025w14, 2025w15, 2025w17) |
| Retrospective clusters | 47 (backfill) |
| Spine tags | 232 across 56 distinct spines |
| Pure-political clusters (residual_fraction = 1.00) | 34 / 52 (65%) |
| Negative control | 2008w43 — residual_fraction = 0.00, pure financial mechanics |
| Test suite | 74 tests passing |
defense_procurement_backlog — 15 clusters across 2005–2025, a 20-year arc of Western defense underfunding finally being priced.
2025w14 → 2025w15 → 2025w17: each cluster tips a new adjacent spine. All other multi-cluster sequences show persistence (same spines stay active) or recurrence (same spine fires in isolated clusters years apart). This is the rarest structure in the dataset.
pelican.harvest → raw prices & positioning
pelican.vol → realized vol panel, z-scores
pelican.clusters → cluster ledger (append-only, hash-chained)
pelican.news → lateral annotations per cluster
pelican.spine → spine-state tags
pelican.analysis → financial baseline subtraction → residuals
pelican.reports → per-cluster charts and markdown reports
Phase guard via PELICAN_PHASE env var enforces the pre-registration discipline at the module level: discovery allows harvest/vol/clusters/reports; annotation allows news/spine/analysis. Modules refuse to run out of phase.
uv sync
uv pip install -e .
# Discovery phase — build vol panel and register clusters
PELICAN_PHASE=discovery uv run python -m pelican.harvest
PELICAN_PHASE=discovery uv run python -m pelican.vol
PELICAN_PHASE=discovery PELICAN_REGISTRATION_TYPE=retrospective uv run python -m pelican.clusters
PELICAN_PHASE=discovery uv run python -m pelican.reports
# Annotation phase — read news, tag spines, compute residuals
PELICAN_PHASE=annotation uv run python -m pelican.news # or use news-annotator agent
PELICAN_PHASE=annotation uv run python -m pelican.spine
PELICAN_PHASE=annotation uv run python -m pelican.analysis
# Lint / test
uv run ruff check src/
uv run pytestSkills (src/pelican/*/core.py) are pure functions: input → output, no discretion, independently testable. They never call each other.
Agents (.claude/agents/) call skills. The harvester agent pulls raw market data; the news-annotator agent annotates a single cluster (one agent per cluster, run in parallel).
The cluster ledger is hash-chained: each row carries version_hash = sha256(prior_hash || row_json). A mismatch halts the pipeline. The file is locked via fcntl.flock during writes.
- No GARCH, no copulas, no ML. Realized vol z-scores only. The signal is in the cross-asset coherence, not in model fit.
- Protected instruments never get their z stripped by financial baseline subtraction: Treasuries (
^TNX,^FVX) and Gold (GC=F) carry geopolitical signal even during financial crises. - Liquidity suspect flag filters RUB-style phantom vol from illiquid markets.
series.shift(1)before rolling window — look-ahead is impossible by construction. Do not change this.2008w43as negative control — a week where financial structure fully explains the cluster. Validates the subtraction methodology.
- Polymarket overlay: lead/lag between prediction market moves and cluster weeks.
- Reports → residuals: render
residual_profile_{cluster_id}.pngper cluster. - Forward markers: for each spine in 3+ clusters, define a hypothesis — "if this signature recurs, expect Y within window Z." Validate against 2025 prospective clusters.
- Red-team gate: before any forward marker is published, a red-team agent assigns GREEN/YELLOW/RED. RED blocks publication.
- Liquidity phantoms: massive vol from illiquid markets is not signal.
- News survivorship: Reuters front page = consensus. Real signal is in trade-press squibs. Lateral reading is non-optional.
- Reverse-engineering narratives: if you're fitting a story to a cluster, stop. That's what pre-registration prevents.
- Single-asset spikes: one instrument doing 60% of cluster z-mass = degenerate cluster.
- Spine edge cases:
china_growth_slowdown_demand_destructionis inFINANCIAL_SPINESbut commodity instruments are protected — the 2015 Black Monday weeks likely overstate political residual by ~5–10 z-mass.
| Term | Definition |
|---|---|
| Cluster | Week with ≥5 instruments at |z| > 2 in the cross-asset vol panel |
| Spine | Named risk premise; unit of cross-cluster comparison |
| Residual | Cluster z-mass not attributed to financial-structure spines |
| Pre-registration | Locking a cluster's vol profile before reading any news |
| Lateral reading | Sourcing from ≥3 classes: mainstream, trade-press, regional |
| Propagation chain | Multi-cluster sequence where each week tips a new adjacent spine |
| Forward marker | Hypothesis: "if signature X recurs, expect political event Y within window Z" |
| Prospective | Cluster registered before news was read |
| Retrospective | Cluster registered during backfill (news already exists) |