A correctness-first CLI for spot coin accumulation that refuses to be clever.
⚠️ DEVELOPMENT MODEThis system is under active development. Design choices are provisional. Performance evidence overrides prior assumptions.
See PROJECT_INTENT.md for governing philosophy.
QAP is a correctness-first, spot-only Python CLI for coin accumulation that uses OLS/TLS for spread construction but makes the Student-t Copula Mispricing Index (nu=4; h-function) the canonical signal to "sell tail insurance" and harvest volatility via Shannon's Demon (systematic rebalancing/swaps); it runs inside a BTC-anchored Tethered Mesh topology, enforces a strict Discovery -> Validation -> Signal -> Execution lifecycle with mechanical vetoes (JIT Veto, HalalFirewall, volatility/Hurst gates), offers shadow execution and unbiased backtesting, records explainable provenance and veto reasoning, and prioritizes auditable coin-piece accumulation over speed or derivative trading while remaining extensible for future imbalance features.
- Business model (canonical): subscription research tooling.
- Execution boundary (canonical): this repository remains analysis/simulation-first; live spot execution, if needed, must be handled by an external executor interface.
- Truth metric (canonical, 60-day): net coin-piece accumulation after fees/slippage versus buy-and-hold.
- Promotion contract (canonical): ECONOMIC_DECISION_SCORECARD.md
North Star v4.0 Architecture - Economic Primacy: Models are instruments, not authorities.
Key Enhancements:
- Economic Primacy: System optimizes for economic performance, not statistical purity
- Regime Indicators: Hurst and other regime indicators are advisory, not absolute authorities
- JIT Veto: Short-horizon slope/ADF checks block entries when structure deteriorates
- Survival Authority: Operates BEFORE Copula signal authority is trusted
- ExecutionContext: Complete context propagation from CLI to TradingCore
- Zero Trade Explanations: Neutral reason breakdown when no trades occur
- Enhanced Validation: Multi-layer validation (config, data, intent, context)
Architectural Truth: See MASTER_AUDIT.md
Full Details: See CHANGELOG.md
The CLI must never help you trade faster — only help you trade correctly.
QAP is a correctness-first analysis and decision system. It:
- Makes phases visible (Discovery → Validation → Signal → Execution)
- Uses copula-derived metrics for trading decisions (not z-scores)
- Explains why it's not trading rather than hiding silence
- Enforces architectural boundaries mechanically
If you want a tool that maximizes trades, this is not it. If you want a tool that maximizes correct trades, welcome.
# Install dependencies
uv sync
# Check cache and market freshness for the pair you want to judge
uv run qap data freshness ETH SOL --days 30
# Run decision-grade validation
uv run qap validate validate ETH SOL --days 30 --topology linear --counterfactual-fillability
# Start the external forward-paper proof path
scripts/ops/run_daily_paper.shSee Quick Start Guide for the full walkthrough.
The default operator path is:
uv run qap data freshness BASE QUOTEuv run qap validate validate BASE QUOTE ...uv run python scripts/ops/export_paper_bundle.py ...orscripts/ops/run_daily_paper.sh- external paper fills
uv run python scripts/ops/evaluate_forward.py ...
The canonical decision contract is in ECONOMIC_DECISION_SCORECARD.md. Current roadmap status is in DECISION_PROGRAM_STATUS.md.
QAP enforces a strict phase system. Each phase has different authorities:
| Phase | Nature | What It Does | Trading Authority |
|---|---|---|---|
| DISCOVERY | Observational | Find cointegrated pairs | ❌ NONE |
| VALIDATION | Diagnostic | Backtest, walk-forward, blocker diagnostics | ❌ NONE |
| SIGNAL | Decisional | Generate entry/exit signals | ✅ COPULA_REAL ONLY |
| EXECUTION | Action | Approve/record executable intent and run shadow simulation | 📋 SignalLedger (no in-repo live order routing) |
Key Rule: Only the SIGNAL phase can produce trading decisions, and only copula models have that authority.
# Screen universe for cointegrated pairs
uv run qap discover screen
# Discover with specific universe
uv run qap discover universe top50 --min-bars 2000# Inspect cache and market freshness
uv run qap data freshness ETH SOL
# Inspect a pair's metrics
uv run qap validate inspect ETH SOL
# Run decision-grade validate
uv run qap validate validate ETH SOL --days 90 --counterfactual-fillability# Shadow run (simulated trading)
uv run qap run shadow -p ETH/SOL# Export the canonical paper bundle
uv run python scripts/ops/export_paper_bundle.py \
--cohort-manifest config/paper_cohorts/forward_paper_2026-03-18.yaml \
--out-dir /tmp/qap-forward-proof \
--run-label paper-20260319 \
--asof 2026-03-19T00:00:00Z
# Evaluate forward artifacts into a decision dashboard
uv run python scripts/ops/evaluate_forward.py \
--bundle-file /tmp/qap-forward-proof/paper_bundle.json \
--fills-dir /tmp/qap-forward-proof/fills \
--cohort-manifest config/paper_cohorts/forward_paper_2026-03-18.yaml \
--out-file /tmp/qap-forward-proof/forward_report.json# Audit architectural compliance
uv run qap config audit
# View configuration
uv run qap config showEvery command shows its phase context:
┌─────────────────────── PHASE: DISCOVERY ───────────────────────┐
│ 🔍 DISCOVERY (Observational) │
│ │
│ Allowed Models: ewm, ols, tls │
│ Decision Authority: ❌ NONE │
│ Why: Structural relationships are observed here, not traded. │
└─────────────────────────────────────────────────────────────────┘
When the system has no signal, it explains why:
○ Neutral (MI ≈ 0.50 — fair value, no edge)
This is not an error. This is the system working correctly.
Every command ends with guidance:
┌────────────────────── NO ACTION REQUIRED ──────────────────────┐
│ MI ≈ 0.48 (fair value). No statistical edge. │
│ Tip: Wait for MI to move toward harvest zones │
│ Why not trade? MI ≈ 0.50 means copula sees fair value. │
└─────────────────────────────────────────────────────────────────┘
| Metric | What It Is | What It's NOT |
|---|---|---|
| MI (Mispricing Index) | Copula-derived probability | Not a price forecast |
| τ (Kendall's Tau) | Rank correlation strength | Not Pearson's r |
| λ_L / λ_U | Tail dependence | Not crash/rally prediction |
| ν (Nu) | Copula shape parameter | Not volatility |
- MI < 0.20: Harvest Buy Zone (undervalued)
- MI ≈ 0.50: Fair Value (no edge)
- MI > 0.80: Harvest Sell Zone (overvalued)
- MI < 0.05 or > 0.95: Tail Zones (extreme)
Control detail level with flags:
# Minimal output (beginners)
qap discover screen --simple
# Standard output (default)
qap discover screen
# Full diagnostics (experts)
qap discover screen --verboseVerify the system is correctly configured:
uv run qap config auditExpected output:
CLI Audit (v5.3)
✓ No legacy models in signal phase
✓ Copula-only enforcement active
✓ NeutralMetrics fully handled
✓ Phase boundaries enforced
✓ Invariant tests passing
Status: ARCHITECTURALLY SOUND
| Document | Purpose |
|---|---|
| Decision Scorecard | Canonical metrics and promotion criteria |
| Decision Program Status | Current roadmap progress and open chunks |
| Forward Paper Protocol | External paper-proof workflow and artifact rules |
| Project Intent | Governing philosophy: Economic Primacy |
| Reference Index | Reference docs, cohort docs, and performance baselines |
| Quick Start | Get running in 5 minutes |
| CLI Commands | Complete command reference |
| Architecture | System design and data flows |
| Constitution | Constitutional governance |
| Invariants | Mechanical rules (v4.0: Economic Primacy) |
| Master Audit (Archived) | Canonical architectural truth |
| JIT Veto Spec (Archived) | Survival Authority mechanism |
# Run all tests
uv run pytest
# Run invariant tests only
uv run pytest tests/invariants/
# Clear development cache
bash scripts/clear_dev_cache.sh quick- ❌ Rank pairs by "best opportunity"
- ❌ Show "confidence scores" or probabilities beyond MI
- ❌ Auto-execute trades based on signals
- ❌ Place live exchange orders from this repository
- ❌ Trade derivatives (futures/options/margin)
- ❌ Provide shortcuts that skip phases
- ❌ Use z-score for trading decisions (deprecated in v3.3)
Why? Because these features make trading faster, not correct.
Private repository. See LICENSE for details.
North Star v4.0 | CLI v5.4 | Economic Primacy