docs: publish performance diagnostics

Author: magnaprog

AGENTS.md

@@ -46,7 +46,8 @@ Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `ci:`); keep message
 ## Security & Configuration Tips
 
 Never commit `.env`, credentials, broker account data, local state, market-data
-snapshots, executed notebook outputs, or generated reports. Use `.env.example`
-as the template. Synthetic data is limited to tests and clearly labeled dry
-runs. Preserve pre-trade risk checks, paper-mode defaults, and point-in-time
-data discipline.
+snapshots, or executed notebook outputs. Generated performance charts require
+explicit owner approval, adjacent provenance, an input digest, and artifact
+hashes; ordinary reports remain ignored. Use `.env.example` as the template.
+Synthetic data is limited to tests and clearly labeled dry runs. Preserve
+pre-trade risk checks, paper-mode defaults, and point-in-time data discipline.

CLAUDE.md

@@ -100,12 +100,13 @@ or vol-scaled book is NOT required to sum to 1. Violations raise
   (threadpoolctl) around the HMM fit so backtests are bit-for-bit reproducible; a
   non-converged EM near a regime boundary otherwise flips under multithreaded
   float ordering. Keep model fits seeded and deterministic.
-- **Explicit research data.** Do not commit market-data snapshots, generated
-  performance charts, or executed notebook outputs. Reports and notebooks must
-  use either an owner-supplied permitted CSV or an explicit live-provider opt-in;
-  they must never silently substitute generated prices after a fetch failure.
-  Synthetic fixtures remain appropriate for tests and the clearly labeled
-  `paper_trade_cycle.py --offline` dry run.
+- **Explicit research data.** Do not commit market-data snapshots or executed
+  notebook outputs. Reports and notebooks must use either an owner-supplied
+  permitted CSV or an explicit live-provider opt-in; they must never silently
+  substitute generated prices after a fetch failure. Derived performance charts
+  may be published only with explicit owner approval, adjacent provenance, an
+  input digest, and artifact hashes. Synthetic fixtures remain appropriate for
+  tests and the clearly labeled `paper_trade_cycle.py --offline` dry run.
 
 ## Layer ABCs to subclass
 

PERFORMANCE.md

@@ -1,9 +1,35 @@
 # Performance Evaluation
 
-This repository does not publish a fixed performance result. Market data,
-executed notebook outputs, and generated charts are intentionally excluded.
-Evaluate the reference strategies on data you are permitted to use and retain
-the source metadata needed to reproduce the run.
+This repository publishes one owner-authorized reference run as derived chart
+artifacts. The raw market data remains uncommitted. Ordinary generated reports
+and executed notebook outputs remain excluded unless publication is explicitly
+approved and accompanied by complete provenance and artifact hashes.
+
+## Published Reference Run
+
+The README charts were generated on June 15, 2026 with yfinance 1.4.1 adjusted
+closes for QQQ, VGT, GLD, TLT, SPY, and VIG. The source spans January 4, 2016 to
+December 31, 2025; evaluation spans January 2, 2018 to December 31, 2025 after
+503 warm-up sessions. The owner confirms permission to publish the derived
+charts; that permission is not independently verified by the software.
+
+| Metric | Value |
+|---|---:|
+| CAGR | -0.07% |
+| Annualized volatility | 6.53% |
+| Sharpe | 0.02 |
+| Maximum drawdown | -14.22% |
+| Annualized one-way turnover | 10.84x |
+| Sum of modeled cost fractions | 15.06% |
+| SPY Sharpe, gross | 0.78 |
+| Equal-weight six-ETF Sharpe, gross | 0.96 |
+
+Strategy returns are net of 3 bps commission and 10 bps flat slippage per
+trade; benchmarks are gross and the ADV cap is inactive. The DSR of 0.065 uses
+an assumed 10 trials and a single-series variance estimate. Because the true
+historical trial count is unknown, it is not a validated multiple-testing
+correction. Exact source and artifact hashes are in
+`docs/img/performance_manifest.json`.
 
 ## Generate a Report
 
@@ -65,8 +91,8 @@ The command writes `reports/report.md` plus these plots under `reports/img/`:
 
 The Markdown report links every plot and includes performance metrics,
 evaluation settings, data provenance, and the monthly-return table. Outputs
-remain ignored; do not copy them into the README without a redistributable input
-dataset and complete provenance.
+remain ignored by default. Publish them only with explicit owner approval,
+complete adjacent provenance, an input digest, and hashes for every artifact.
 
 The current command must not fabricate diagnostics it cannot support. Add
 walk-forward or live-start boundaries only when the run records those regimes;

README.md

@@ -27,17 +27,84 @@ w_t = R_t( T_t( A_t( S_t( X<=t ) ) ) )
 
 **Design targets are not performance claims.** The reference strategies retain
 aspirational Sharpe targets of 1.10 (multi-asset rotation) and 0.9 (momentum
-ML), but this repository publishes no fixed backtest result. Evaluate them on
-data you are permitted to use, record the true number of trials, and compare
-against appropriate benchmarks. See [PERFORMANCE.md](PERFORMANCE.md).
+ML). The published reference run below materially misses its target and both
+gross benchmarks; it demonstrates the audit path rather than strategy quality.
+See [PERFORMANCE.md](PERFORMANCE.md).
 
 ---
 
 ## Project Demo
 
-The best demonstration is a locally generated, provenance-bearing report rather
-than a permanent equity curve detached from its input data. With an authorized
-price file, run:
+The repository owner confirms permission to publish these derived charts. The
+raw market-data file remains uncommitted; its digest and the complete chart
+hashes are recorded in
+[`performance_manifest.json`](docs/img/performance_manifest.json).
+
+![Multi-Asset Rotation diagnostic overview](docs/img/report_overview.png)
+
+| Reference-run result | Value |
+|---|---:|
+| Evaluation window | 2018-01-02 to 2025-12-31 |
+| CAGR | -0.07% |
+| Annualized volatility | 6.53% |
+| Sharpe | 0.02 |
+| Maximum drawdown | -14.22% |
+| Annualized one-way turnover | 10.84x |
+| Sum of modeled cost fractions | 15.06% |
+| SPY Sharpe, gross | 0.78 |
+| Equal-weight six-ETF Sharpe, gross | 0.96 |
+
+Strategy returns are net of 3 bps commission and 10 bps flat slippage per
+trade; benchmark returns are gross. The ADV cap is inactive because this run
+has no volume input. The reported DSR is 0.065 using an assumed 10 trials and a
+single-series variance estimate. The true historical trial count is unknown,
+so that DSR is not a validated multiple-testing correction.
+
+<details>
+<summary><strong>Open the full diagnostic gallery</strong></summary>
+
+### Equity Versus Benchmarks
+
+![Net strategy equity versus gross benchmarks](docs/img/equity_vs_benchmarks.png)
+
+### Drawdown
+
+![Strategy underwater drawdown](docs/img/drawdown.png)
+
+### Rolling Sharpe
+
+![Rolling 126-session Sharpe](docs/img/rolling_sharpe.png)
+
+### Rolling Risk
+
+![Rolling annualized volatility and beta to SPY](docs/img/rolling_risk.png)
+
+### Allocation And Exposure
+
+![Post-trade allocation, exposure, and cash](docs/img/allocation_and_exposure.png)
+
+### Turnover And Costs
+
+![Executed turnover and cumulative modeled cost fractions](docs/img/turnover_and_costs.png)
+
+### Monthly Returns
+
+![Monthly net-return heatmap](docs/img/monthly_returns.png)
+
+### Return Distribution
+
+![Daily net-return distribution and normal Q-Q diagnostic](docs/img/return_distribution.png)
+
+</details>
+
+The published run uses Yahoo Finance data retrieved through yfinance 1.4.1 on
+June 15, 2026. It covers QQQ, VGT, GLD, TLT, SPY, and VIG from January 4, 2016
+through December 31, 2025; the first 503 sessions are signal warm-up. The local
+adjusted-close CSV has SHA-256
+`3b256ef083794a67f173d635a3cd297237b7a3d01489ccf53cc807c99602607c`.
+Permission is owner-asserted and not independently verified by the software.
+
+To generate the same report from an authorized file matching that digest:
 
 ```bash
 PYTHONPATH=. python scripts/generate_report.py \
@@ -49,18 +116,9 @@ PYTHONPATH=. python scripts/generate_report.py \
   --adjustment-method "$DATA_ADJUSTMENT_METHOD"
 ```
 
-Open `reports/report.md`. It links a compact diagnostic overview and detailed
-performance, drawdown, rolling-risk, allocation, exposure, turnover, cost,
-monthly-return, and tail-distribution plots. The report also records the input
-digest, evaluation window, warm-up, cost assumptions, DSR settings, and whether
-all publication metadata was supplied. Metadata records the owner's assertions;
-the tool does not determine whether a license permits redistribution.
-
-The architecture diagram below is safe to publish because it is independent of
-market data. A generated `report_overview.png` should be added to this README
-only when the input license permits publication of derived images and the
-adjacent text identifies the source, date window, file digest, costs, benchmark
-treatment, and true research trial count. Never publish an equity curve alone.
+The command writes `reports/report.md` and the same nine-plot diagnostic set.
+Metadata records owner-supplied assertions; the tool does not determine whether
+a license permits publication or redistribution.
 
 ---
 
@@ -179,9 +237,11 @@ credential variables.
 
 ## Performance Reporting
 
-No market-data snapshot, executed notebook output, generated chart, or fixed
-performance number is published in this repository. This avoids redistributing
-provider data and prevents a changing data vintage from looking immutable.
+The README publishes one owner-authorized reference run as derived images with
+adjacent provenance and an artifact manifest. Raw market data, executed
+notebook output, and ordinary local reports remain excluded. Published results
+must identify their data vintage and must not be silently regenerated from a
+different input file.
 
 For a licensed local dataset, run:
 
@@ -195,12 +255,10 @@ The report records the file path, SHA-256 digest, observed date window, cost
 assumptions, signal warm-up, DSR trial count/variance assumption, and whether
 liquidity constraints are active.
 Each run writes `reports/report.md`, a compact `report_overview.png`, and eight
-detailed diagnostics under ignored `reports/img/`. These are local research
-evidence, not repository fixtures. The README intentionally contains no fixed
-performance plot because the repository does not ship a redistributable input
-dataset. See
-[PERFORMANCE.md](PERFORMANCE.md) for interpretation requirements and known
-limitations.
+detailed diagnostics under ignored `reports/img/`. These remain local research
+evidence unless the owner explicitly approves publication and adds complete
+provenance plus artifact hashes. See [PERFORMANCE.md](PERFORMANCE.md) for the
+reference run, interpretation requirements, and known limitations.
 
 ---
 
@@ -369,6 +427,7 @@ quantcortex/                     # repo root
 ├── local_data/README.md         # ignored local-data schemas and provenance rules
 ├── reports/                     # ignored generated charts and report output
 ├── docs/
+│   ├── img/                     # approved reference-run plots + hash manifest
 │   ├── production-readiness.md  # blockers before production capital
 │   └── history-rewrite-plan.md  # optional purge procedure; not executed
 ├── docker-compose.yml

docs/img/allocation_and_exposure.png

@@ -0,0 +1,68 @@
+{
+  "schema_version": 1,
+  "generated_at": "2026-06-15",
+  "generator_commit": "ac7bb90754b4b1b488af3b7bdc561b046c7c4aa3",
+  "source": {
+    "provider": "Yahoo Finance via yfinance 1.4.1",
+    "permission_basis": "Repository owner confirms permission to publish derived charts",
+    "permission_independently_verified": false,
+    "retrieved_at": "2026-06-15",
+    "symbols": [
+      "QQQ",
+      "VGT",
+      "GLD",
+      "TLT",
+      "SPY",
+      "VIG"
+    ],
+    "adjustment_method": "yfinance adjusted close with auto_adjust=False",
+    "price_window": "2016-01-04 to 2025-12-31",
+    "input_sha256": "3b256ef083794a67f173d635a3cd297237b7a3d01489ccf53cc807c99602607c",
+    "raw_input_committed": false
+  },
+  "evaluation": {
+    "strategy": "multi_asset_rotation",
+    "window": "2018-01-02 to 2025-12-31",
+    "sessions": 2011,
+    "warmup_sessions": 503,
+    "required_warmup_sessions": 274,
+    "execution_timing": "close signal executes at the next bar close",
+    "rebalance": "first available session each week",
+    "commission_bps": 3.0,
+    "slippage_bps": 10.0,
+    "transfer_tax_bps": 0.0,
+    "adv_cap_applied": false,
+    "strategy_returns": "net",
+    "benchmark_returns": "gross",
+    "dsr_trials_assumed": 10,
+    "true_historical_trial_count": "unknown",
+    "dsr_cross_trial_variance": "single-series estimate"
+  },
+  "metrics": {
+    "total_return": -0.005230439506423212,
+    "cagr": -0.000656934729176939,
+    "annualized_volatility": 0.06528824792584632,
+    "sharpe": 0.022628754062896092,
+    "sortino": 0.030394685432320295,
+    "calmar": -0.004619337898382643,
+    "max_drawdown": -0.1422140453087335,
+    "annualized_one_way_turnover": 10.84416722565801,
+    "sum_of_modeled_cost_fractions": 0.15056228172947278,
+    "var_95_daily": 0.007188401820487274,
+    "cvar_95_daily": 0.011103253411059867,
+    "deflated_sharpe": 0.06542961955250098,
+    "spy_sharpe_gross": 0.7824200403668903,
+    "equal_weight_sharpe_gross": 0.9648098190098434
+  },
+  "artifacts": {
+    "allocation_and_exposure.png": "780bf3900b07e0b45c6208f0fefa1d1e1ef7cdf7327e74738046f81b5db5eb13",
+    "drawdown.png": "75af12f0b1d6727d33d5c03dcaca48a9dc3b5bcd93130328229eaa5483bdcec9",
+    "equity_vs_benchmarks.png": "5d6da4b67f0139910408f88075b6897528406e8a1ff354ea6002b3e556499bde",
+    "monthly_returns.png": "5f8682589b1e9ce845f23403c23dbc50c0aedbf9a279bdf1dd302d444ad86126",
+    "report_overview.png": "487bad1468f44247b9f2533e8b8043e200107c7039fc27cc8413e4530e845a4c",
+    "return_distribution.png": "00ffd9316b0974e5a5e33f3d2ffc0da630c3cf4329108cb8d7133830a804eac4",
+    "rolling_risk.png": "f745988f5f91f276e912201e0ff7052dadf9150236f2b2464c1ad64bbe783d60",
+    "rolling_sharpe.png": "74f989c9b405473f9eeb9208ac2ef360b222a44ded2956d0b63482cf7bdc54a0",
+    "turnover_and_costs.png": "105243d3fbb110a7ce55e71c2b3a543e82203a6b3b9de2e7f2265d02b74154f5"
+  }
+}