diff --git a/CHANGELOG.md b/CHANGELOG.md index db288a20..dedbf962 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. The format ## [Unreleased] ### Added +- A public-safe validation-frontier chart with its source CSV and an evidence note binding each published aggregate metric to the accepted 2026-07-11 research artifacts. - Repository guardrails: pytest marker config, WRDS detection helpers, log fan-out to `artifacts/logs/`. - Pre-commit automation (black, isort, ruff, detect-secrets) plus tightened `.gitignore`. - WRDS-focused Makefile targets, CHANGELOG bootstrap, and CI/docs placeholders for analytics & reporting. @@ -29,6 +30,7 @@ All notable changes to this project will be documented in this file. The format ### Changed +- Reorganized the repository README around the research problem, quickstart, architecture, validation evidence, reproducibility, and explicit status/limitations. - Walk-forward WRDS config aligned to available universe coverage (2013–2019) to restore non-degenerate holdout metrics. - WRDS flagship run now uses 3y/9m folds (21 folds), trimmed grid (top_frac × turnover only), higher turnover cap, and produces reproducible signals/analytics/factors/SPA assets for run `2025-11-12T18-50-58Z-b2eaf50` with docs, plots, and summaries updated in lockstep. - ticket-01: WRDS configs now surface gross leverage/single-name caps and borrow model; reporting now includes net/gross exposure + cost breakdown. diff --git a/PROGRESS.md b/PROGRESS.md index 95ab40b7..dbb8928a 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -88,3 +88,7 @@ Ticket-18: Installed agentic system scaffold, restored repo-specific docs, and g - Ticket-24d: finalized WRDS refresh doc/run log shipment to main, validated gates, and generated a GPT bundle. Run log: `docs/agent_runs/20260126_151214_ticket-24d_ship-wrds-refresh-to-main/`. - Ticket-24d: aligned tracking-policy wording in ticket docs, refreshed sprint ticket entry, reran gates, and regenerated the GPT bundle. Run log: `docs/agent_runs/20260126_151214_ticket-24d_ship-wrds-refresh-to-main/`. - Ticket-26: logged gpt_bundle dirty-tree safety + repo hygiene, ignored local tmp dirty marker, and prepped main for push. Run log: `docs/agent_runs/20260126_223149_ticket-26_git-hygiene-push/`. +## 2026-07-14 + +### Done +- Ticket-99: rebuilt the public README around reproducible research workflow, evidence status, honest limitations, and a public-safe aggregate validation frontier. Added a provenance-bound evidence note and SVG/CSV source pair without exposing raw or licensed data. Run log: `docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/`. diff --git a/README.md b/README.md index 27acac03..fd368bd1 100644 --- a/README.md +++ b/README.md @@ -1,197 +1,215 @@ # microalpha -[![CI](https://github.com/mateobodon/microalpha/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mateobodon/microalpha/actions/workflows/ci.yml?query=branch%3Amain) -[![Docs](https://img.shields.io/badge/docs-pages-blue)](https://mateobodon.github.io/microalpha) -![Coverage](https://img.shields.io/badge/coverage-78%25-blue.svg) +[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0969da)](https://mateobodon.github.io/microalpha/) +[![License: MIT](https://img.shields.io/badge/license-MIT-1a7f37)](LICENSE) -**Leakage-safe, event-driven backtesting engine with walk-forward cross-validation, parameter optimisation, and production-grade reporting.** +**A leakage-aware, event-driven research engine for turning quantitative ideas +into timestamped, costed, reproducible evidence.** -microalpha focuses on rigorous research hygiene: strict chronology enforcement, automated walk-forward reality checks, reproducible artefacts, and a publishing pipeline (MkDocs + GitHub Pages) ready for stakeholder hand-offs. Out of the box you get deterministic sample runs, a public-data configuration bundle, WRDS stubs, factor analytics, and a full test suite that refuses to pass if documentation links or generated visuals go missing. +microalpha is built for the part of backtesting that is easiest to get wrong: +chronology, point-in-time data, execution timing, model selection, transaction +costs, and the boundary between an interesting validation result and a claim +that is actually ready to publish. ---- +> **Status — research infrastructure, not a live trading system.** The public +> sample workflows validate the engine and reporting path. The latest reviewed +> licensed-data campaign remains pre-holdout: its 2023–2025 final holdout is +> sealed, and no alpha or live-performance claim is made. -## Latest Results (bundled sample data) +## What it makes auditable -| Run | SharpeHAC | MAR | Max DD | RealityCheck *p*-value | Turnover | -| --- | ---:| ---:| ---:| ---:| ---:| -| Single backtest ([configs/flagship_sample.yaml](configs/flagship_sample.yaml)) | -0.66 | -0.41 | 17.26% | 0.861 | $1.21M | -| Walk-forward ([configs/wfv_flagship_sample.yaml](configs/wfv_flagship_sample.yaml)) | 0.22 | 0.03 | 34.79% | 1.000 | $28.53M | - -_Source artefacts: `artifacts/sample_flagship/2025-10-30T18-39-31Z-a4ab8e7` and `artifacts/sample_wfv/2025-10-30T18-39-47Z-a4ab8e7`._ - -![Sample Flagship Equity Curve](artifacts/sample_flagship/2025-10-30T18-39-31Z-a4ab8e7/equity_curve.png) -![Sample Flagship Bootstrap Histogram](artifacts/sample_flagship/2025-10-30T18-39-31Z-a4ab8e7/bootstrap_hist.png) - -### Factor regression (FF3 sample bundle) - -| Factor | Beta | *t*-stat | -| --- | ---:| ---:| -| Alpha | -0.0055 | -1.42 | -| Mkt_RF | 10.7236 | 1.74 | -| SMB | 1.4014 | 0.12 | -| HML | -13.1416 | -0.77 | - -Computed automatically against `data/factors/ff3_sample.csv` using HAC (Newey–West) standard errors. The sample factor bundle is weekly; reports explicitly resample returns to match factor frequency and record the frequency + sample size alongside the table. The table is injected into `reports/summaries/flagship_mom_wfv.md` when the factor CSV is present. - ---- - -## Project highlights - -- **Leakage-safe engine** – event-driven core (DataHandler ➝ Engine ➝ Portfolio ➝ Broker) with timestamp validation, t+1 fills, and lookahead guards enforced by tests. -- **Out-of-sample discipline** – configurable walk-forward validation with Politis–White stationary bootstraps, per-fold metrics, and aggregated reality-check summaries. -- **Visual + statistical reporting** – CLI renders equity/bootstrapped Sharpe PNGs, Markdown summaries, and optional factor regressions; README embeds the same artefacts. -- **Data bundles for every stage** – deterministic sample universe, public ticker mini-panel, WRDS/CRSP configuration template, and FF3 factor snippets included in-repo. -- **Production hygiene** – MkDocs documentation, GitHub Pages auto-deploy, Ruff/Mypy/Pytest/Coverage gates, schema tests that fail when artefacts disappear. - ---- +| Research risk | microalpha control | +| --- | --- | +| Lookahead and same-period execution | Timestamp validation, explicit signal/fill clocks, tested `t+1` fills | +| Selection overfitting | Walk-forward folds, preregistered candidate sets, stationary-bootstrap reality checks | +| Frictionless backtests | Commission, slippage, borrow, turnover, capacity, and stress-cost accounting | +| Unreproducible results | Resolved configs, dataset/artifact manifests, run IDs, immutable metrics and trades | +| Licensed-data leakage | Raw WRDS/CRSP data stays local; only reviewed aggregate evidence is publishable | -## Getting started +## Quickstart -### Requirements -- Python 3.12+ -- `pip` (recommended: virtual environment via `venv` or `conda`) -- Optional: WRDS/CRSP exports (see [docs/wrds.md](docs/wrds.md)) +Requires Python 3.12+. -### Install ```bash -python -m venv .venv && source .venv/bin/activate -pip install -e '.[dev]' +git clone https://github.com/MateoBodon/microalpha.git +cd microalpha +python -m venv .venv +source .venv/bin/activate +python -m pip install -e '.[dev]' + +make sample +make report ``` -### Reproduce the flagship notebooks in two commands +The sample run writes a self-describing artifact directory containing the +resolved config, metrics, trades, exposures, equity curve, bootstrap result, +and manifest. Run the walk-forward path with: + ```bash -make sample && make report # single backtest artefacts + summary -make wfv && make report-wfv # walk-forward artefacts + summary + factors +make wfv +make report-wfv ``` -Outputs appear under `artifacts/sample_flagship/` and `artifacts/sample_wfv/` with: -``` -bootstrap.json equity_curve.csv equity_curve.png -bootstrap_hist.png exposures.csv factor_exposure.csv -metrics.json trades.jsonl (plus fold-by-fold CSVs for WFV) +These bundled inputs are for deterministic software validation—not evidence of +tradable performance. + +## Research flow + +```mermaid +flowchart LR + A["Research question
and frozen protocol"] --> B["Point-in-time data
and source manifest"] + B --> C["Chronology guards
and signal clock"] + C --> D["Event loop
Strategy → Portfolio → Broker"] + D --> E["Walk-forward selection
costs and stress tests"] + E --> F["Evidence bundle
metrics · trades · config · hashes"] + F --> G{"Claim gate"} + G -->|pass| H["Reviewed aggregate result"] + G -->|fail| I["Preserved negative result"] ``` -`microalpha report` will emit Markdown summaries into `reports/summaries/` and embed HAC factor tables automatically when `data/factors/ff3_sample.csv` is present. +The engine keeps data access, signal formation, portfolio construction, and +execution as separate steps so their timing assumptions can be tested directly. + +## Evidence, including negative results + +The latest aggregate-only research ledger is intentionally more useful than a +single best backtest. Six frozen mechanisms were evaluated on a 2017–2022 +validation window while the 2023–2025 final holdout remained sealed. + +![Validation HAC Sharpe for six preregistered mechanisms; only the SEC cash-earnings candidate approaches the 0.50 promotion gate and it still fails the full gate set](docs/assets/portfolio/validation_frontier.svg) + +| Frozen mechanism | Net HAC Sharpe | Decision | +| --- | ---: | --- | +| Classic momentum baseline | 0.2407 | Baseline; validation proxy only | +| Industry-residual momentum | 0.3198 | Rejected: improvement `0.0791` < required `0.10` | +| Low volatility | -0.0906 | Rejected on return and drawdown gates | +| One-month reversal | -0.4542 | Rejected; `63.27×` one-way turnover | +| Annual QVPI composite | -0.0234 | Rejected; restatement/vintage caveat remains | +| SEC cash-earnings acceleration | 0.4736 | Rejected: below `0.50`; harsh-cost Sharpe `-0.1034` | + +This is **validation evidence, not a final-holdout or alpha claim**. The strongest +candidate was still rejected because the complete preregistered gate set did not +pass. Exact windows, costs, uncertainty, manifest digests, and caveats are in the +[public-safe research note](docs/portfolio_evidence_2026-07-11.md); chart values +are also available as [CSV](docs/assets/portfolio/validation_frontier.csv). + +## Core capabilities + +- **Event-driven engine** — explicit data, strategy, portfolio, risk, broker, + and execution components with deterministic clocks. +- **Walk-forward validation** — training/test folds, parameter selection, + per-fold outputs, and aggregate out-of-sample metrics. +- **Inference** — HAC statistics, Politis–White stationary bootstrap, reality + checks, SPA tooling, and factor regressions. +- **Execution realism** — `t+1` fills, commissions, slippage/impact models, + borrow costs, turnover controls, sector/industry caps, and capacity checks. +- **Evidence packaging** — resolved YAML, data IDs, manifests, metrics, trades, + plots, and Markdown summaries designed to survive handoff and review. +- **Data boundaries** — deterministic synthetic samples, a small public-data + path, and guarded adapters for local licensed research data. + +## CLI + +| Command | Purpose | +| --- | --- | +| `microalpha run --config --out ` | Run one event-driven backtest | +| `microalpha wfv --config --out ` | Run walk-forward validation | +| `microalpha report --artifact-dir ` | Render plots and a Markdown result summary | +| `microalpha info` | Print environment and package metadata as JSON | + +Example public-data workflow: -### Public-data quickstart ```bash -microalpha wfv --config configs/wfv_flagship_public.yaml \ +microalpha wfv \ + --config configs/wfv_flagship_public.yaml \ --out artifacts/public_wfv microalpha report --artifact-dir artifacts/public_wfv/ ``` -Prices live under `data/public/prices/` (AAPL, MSFT, AMZN, GOOGL, TSLA, NVDA); metadata is in `data/public/meta_public.csv`. - -### WRDS/CRSP workflow (guarded) -1. Export WRDS DSF prices + security master to local paths. -2. Point [`configs/wfv_flagship_wrds.yaml`](configs/wfv_flagship_wrds.yaml) at `$WRDS_DATA_ROOT` exports (env vars are expanded automatically). -3. Run the guarded pipeline: - - ```bash - make wfv-wrds && make report-wrds - python reports/analytics.py artifacts/wrds_flagship/ - python reports/factors.py artifacts/wrds_flagship/ --model ff5_mom - python reports/spa.py --grid artifacts/wrds_flagship//grid_returns.csv - ``` -4. Drop the resulting PNG/MD/JSON artefacts into git (never WRDS raw data) and link them from [docs/results_wrds.md](docs/results_wrds.md). -5. Consult [docs/wrds.md](docs/wrds.md) for schema tables, licensing notes, and survivorship guidance. +The tiny public panel is a wiring/demo surface. Its latest audited run had zero +trades and must not be used as a performance claim. ---- +## Output contract -## CLI cheatsheet +A typical run includes: -| Command | Description | -| --- | --- | -| `microalpha run --config --out ` | Single backtest over the full sample. -| `microalpha wfv --config --out ` | Walk-forward cross-validation with optional reality-check overrides. -| `microalpha report --artifact-dir ` | Produce PNGs + Markdown summary (factor table auto-added when factors set). -| `microalpha info` | Emit environment + package metadata as JSON. +```text +/ +├── config_resolved.yaml +├── manifest.json +├── metrics.json +├── trades.jsonl +├── exposures.csv +├── equity_curve.csv +├── equity_curve.png +├── bootstrap.json +└── folds.json # walk-forward runs +``` -See `microalpha --help` for full argument lists. +The manifest binds the run to its config, software state, and dataset identity; +reporting reads these artifacts rather than reconstructing results from prose. +Committed examples are available under +[`artifacts/sample_flagship`](artifacts/sample_flagship/) and +[`artifacts/sample_wfv`](artifacts/sample_wfv/). ---- +## Licensed-data workflow -## Documentation +WRDS/CRSP exports are never committed. A local user can point the guarded config +at `WRDS_DATA_ROOT`, run the pipeline, and publish only reviewed aggregate +artifacts: -- Live site: **https://mateobodon.github.io/microalpha** (auto-built via `.github/workflows/docs.yml`). -- Local preview: `mkdocs serve` -- Key pages: project overview (`docs/index.md`), flagship strategy walkthrough, reproducibility guarantees, leakage safety, WRDS guide, factor analytics. +```bash +make wfv-wrds +make report-wrds +python reports/analytics.py artifacts/wrds_flagship/ +python reports/spa.py --grid artifacts/wrds_flagship//grid_returns.csv +``` ---- +See [the WRDS guide](docs/wrds.md) for schema, licensing, point-in-time, and +survivorship requirements. -## Quality gates & testing +## Repository map -| Command | Purpose | +| Path | Role | | --- | --- | -| `ruff check` | Linting + import hygiene. -| `mypy src/microalpha/reporting/factors.py` | Type-check the reporting extension (fast path). -| `pytest -q` | Run the 70+ unit/integration tests. -| `pytest --cov=microalpha --cov-report=term` | Generate coverage (78% with bundled suites). -| `mkdocs build` | Verify docs compile before deployment. +| `src/microalpha/` | Engine, data, strategies, execution, portfolio, risk, reporting | +| `configs/` | Reproducible sample, public, and local licensed-data workflows | +| `tests/` | Chronology, execution, reporting, artifact, and data-policy contracts | +| `artifacts/` | Committed deterministic evidence used by docs and tests | +| `docs/` | User documentation, methods, data rules, and evidence notes | +| `reports/` | Analytics, factor, SPA, and summary entry points | -Tests include artefact schema validation (`tests/test_artifacts_schema.py`), CLI contract checks, docs-link verification, factor regression smoke tests, and the original leakage/t+1 safeguards. +## Validation ---- - -## Architecture & methodology - -### Engine snapshot -``` -Market data ➝ DataHandler ➝ Engine loop ➝ Strategy ➝ Portfolio ➝ Broker ➝ Trades +```bash +ruff check +mypy src/microalpha/reporting/factors.py +pytest -q +mkdocs build --strict ``` -- **Strict chronology:** timestamps validated before signal handling; fills posted at `t+1` when configured. -- **Portfolio & risk:** turnover caps, sector heat controls, Kelly-style scaling, pluggable slippage & commission models. -- **Execution models:** TWAP, VWAP, linear/√-impact, Kyle λ, implementation shortfall, and LOB simulation with latency knobs. -### Walk-forward pipeline -1. Split train/test windows according to `walkforward` block. -2. Optimise strategy hyper-parameters on training folds. -3. Evaluate out-of-sample; capture per-fold metrics, exposures, trades. -4. Run Politis–White stationary bootstrap across competing models. -5. Persist a manifest (`folds.json`, `reality_check.json`, `metrics.json`) and summary tables. - -### Statistical toolkit -- **HAC Sharpe estimates** with configurable lags. -- **Bootstrap reality checks** aggregated across folds (stored in `bootstrap.json`). -- **Factor regression helper** (`reports/factors_ff.py`) producing HAC *t*-stats for FF3-style alphas. - ---- - -## Data bundles - -| Bundle | Location | Contents | -| --- | --- | --- | -| Sample flagship | `data/sample/` | Synthetic-cross section (6 tickers), metadata, risk-free series. Used by default configs. -| Public mini-panel | `data/public/` | 6 recognisable tickers (AAPL, MSFT, AMZN, GOOGL, TSLA, NVDA) with trimmed CSVs + metadata + universe file. -| WRDS template | `configs/wfv_flagship_wrds.yaml` | Paths + schema expectations for CRSP DSF exports; guarded `make wrds` target. -| Factors | `data/factors/ff3_sample.csv` | Weekly FF3 sample spanning 2020–2021 for regression demos. - ---- - -## Repository layout (selected) - -``` -artifacts/ # Committed sample runs powering the README & tests -configs/ # YAML configs (sample, public, WRDS) -data/ # Sample + public data bundles + factor CSV -src/microalpha/ # Engine, strategies, reporting, CLI -reports/ # CLI entrypoints, summaries, factor utilities -docs/ # MkDocs content -.tests/ # Pytest suites guarding CLI, artefacts, leakage -``` +Focused tests cover no-lookahead behavior, `t+1` execution, artifact schemas, +CLI contracts, factor alignment, data policy, and documentation links. ---- +## Limitations -## Contributing & next steps +- microalpha does not connect to a broker or claim live execution. +- Public sample and mini-panel runs validate software behavior, not alpha. +- Licensed-data results are reproducible only for authorized users with the + exact source snapshot; the repository publishes aggregates, not raw rows. +- The latest pre-holdout research candidates all failed at least one frozen + promotion gate. The final 2023–2025 holdout remains sealed. +- Historical artifacts can become stale; trust a result only when its manifest, + status label, and evidence note agree. -- Issues and PRs welcome – ensure `pytest -q`, `ruff check`, and `mkdocs build` succeed locally. -- Ideas for expansion: - - richer public datasets (e.g., macro factors, option metrics) - - portfolio attribution dashboards - - GPU-accelerated simulations for dense intraday data. +## Contributing and citation ---- +Issues and focused pull requests are welcome. Preserve chronology, add a test +for any changed timing assumption, and bind result claims to generated artifacts. +For research use, cite the repository URL and the exact commit/artifact manifest +used in the analysis. ## License -MIT © Mateo Bodon. See [LICENSE](LICENSE). +Code is available under the [MIT License](LICENSE). Data sources may carry +separate restrictions; WRDS/CRSP data are not redistributed here. diff --git a/docs/CODEX_SPRINT_TICKETS.md b/docs/CODEX_SPRINT_TICKETS.md index 0749962f..9128f084 100644 --- a/docs/CODEX_SPRINT_TICKETS.md +++ b/docs/CODEX_SPRINT_TICKETS.md @@ -787,3 +787,20 @@ - **Tests run:** … - **Artifacts/logs:** … - **Documentation updates:** … +## ticket-99 — Public portfolio presentation + +**Status:** DONE. + +**Goal (1 sentence):** Make the public repository page explain Microalpha's leakage-aware workflow and strongest accepted aggregate evidence without exposing licensed data or implying a live strategy. + +**Acceptance criteria (objective + falsifiable):** +- The first screen states the problem, evidence boundary, and non-live status. +- Quickstart, architecture, repository navigation, limitations, and reproducibility paths are present and link correctly. +- Every published performance value is aggregate, public-safe, and bound to a named canonical artifact in a dedicated evidence note. +- The result chart has source data, readable labels, and an honest zero reference. +- The full test suite, data-policy scan, and docs-link check pass. + +**End-of-ticket:** +- **Tests run:** `pytest -q`; `python scripts/check_data_policy.py`; `python scripts/check_docs_links.py`. +- **Artifacts/logs:** `docs/assets/portfolio/validation_frontier.{csv,svg}`; `docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/`. +- **Documentation updates:** `README.md`, `docs/portfolio_evidence_2026-07-11.md`, `PROGRESS.md`, `CHANGELOG.md`. diff --git a/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/COMMANDS.md b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/COMMANDS.md new file mode 100644 index 00000000..9a86931f --- /dev/null +++ b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/COMMANDS.md @@ -0,0 +1,8 @@ +# Commands + +- Inspected the isolated worktree at exact `origin/main` base `31fe55320b5bdf3fdea386de98e627ad15290d0c`. +- Audited accepted aggregate research artifacts and public-data policy before drafting claims. +- Ran `pytest -q`. +- Ran `PYTHONPATH=src pytest -q tests/test_docs_links.py tests/test_data_policy.py`. +- Ran `python3 scripts/check_data_policy.py`. +- Ran `python3 scripts/validate_run_logs.py` after writing this record. diff --git a/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/META.json b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/META.json new file mode 100644 index 00000000..b10fd5c8 --- /dev/null +++ b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/META.json @@ -0,0 +1,22 @@ +{ + "run_name": "20260714_220933_ticket-99_portfolio-presentation", + "ticket_id": "ticket-99", + "started_at_utc": "2026-07-14T21:48:14Z", + "finished_at_utc": "2026-07-14T22:09:33Z", + "git_sha_before": "31fe55320b5bdf3fdea386de98e627ad15290d0c", + "git_sha_after": "31fe55320b5bdf3fdea386de98e627ad15290d0c", + "branch_name": "feat/ticket-99-portfolio-presentation", + "host_env_notes": "macOS 26.5.1 / Python 3.12.2 / docs-only presentation work", + "dataset_id": "public_safe_aggregate_evidence_2026-07-11", + "config_paths": [], + "config_sha256": {}, + "artifact_paths": [ + "docs/assets/portfolio/validation_frontier.csv", + "docs/assets/portfolio/validation_frontier.svg" + ], + "report_paths": [ + "README.md", + "docs/portfolio_evidence_2026-07-11.md" + ], + "web_sources": [] +} diff --git a/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/PROMPT.md b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/PROMPT.md new file mode 100644 index 00000000..2254a90d --- /dev/null +++ b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/PROMPT.md @@ -0,0 +1,3 @@ +# Prompt + +Overhaul Microalpha's public presentation using only accepted, public-safe aggregate evidence. Preserve licensed-data boundaries, state what is simulated or sealed, add a reproducible quickstart and architecture view, and publish no claim that is not bound to a current artifact. diff --git a/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/RESULTS.md b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/RESULTS.md new file mode 100644 index 00000000..f5f0bd8a --- /dev/null +++ b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/RESULTS.md @@ -0,0 +1,7 @@ +# Results + +- Rebuilt the README around the research problem, leakage-aware workflow, first-run path, architecture, artifact contract, current evidence, and limitations. +- Added `docs/portfolio_evidence_2026-07-11.md` to bind every public aggregate value to its accepted source artifact and status. +- Added an SVG chart plus the exact CSV used to render it. The chart compares validation Sharpe with an explicit zero line and does not represent holdout or live performance. +- Preserved the sealed 2023-2025 holdout and published no raw/licensed records, identifiers, secrets, or private alpha details. +- Assumption: repository presentation may summarize already accepted aggregate artifacts, but may not reinterpret rejected candidates or sealed evidence as investable results. diff --git a/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/TESTS.md b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/TESTS.md new file mode 100644 index 00000000..34e42446 --- /dev/null +++ b/docs/agent_runs/20260714_220933_ticket-99_portfolio-presentation/TESTS.md @@ -0,0 +1,6 @@ +# Tests + +- `pytest -q` — PASS: 129 passed; one third-party deprecation warning. +- `PYTHONPATH=src pytest -q tests/test_docs_links.py tests/test_data_policy.py` — PASS: 2 passed. +- `python3 scripts/check_data_policy.py` — PASS: 1,072 files scanned; 46 allowlisted. +- `python3 scripts/validate_run_logs.py` — PASS: all run logs validated. diff --git a/docs/assets/portfolio/validation_frontier.csv b/docs/assets/portfolio/validation_frontier.csv new file mode 100644 index 00000000..da8c8437 --- /dev/null +++ b/docs/assets/portfolio/validation_frontier.csv @@ -0,0 +1,7 @@ +mechanism,hac_sharpe,status +Classic momentum baseline,0.2407,baseline_validation_proxy +Industry-residual momentum,0.3198,rejected_margin_gate +Point-in-time low volatility,-0.0906,rejected +One-month reversal,-0.4542,rejected +Annual QVPI composite,-0.0234,rejected +SEC cash-earnings acceleration,0.4736,rejected_absolute_and_stress_gates diff --git a/docs/assets/portfolio/validation_frontier.svg b/docs/assets/portfolio/validation_frontier.svg new file mode 100644 index 00000000..f52e6104 --- /dev/null +++ b/docs/assets/portfolio/validation_frontier.svg @@ -0,0 +1,24 @@ + + Validation HAC Sharpe across six preregistered mechanisms + Horizontal bars compare validation HAC Sharpe. The SEC cash-earnings candidate reaches 0.4736 but remains below the 0.50 promotion gate and fails the cost stress gate. Several candidates are negative. + + + Pre-holdout validation frontier + Net HAC Sharpe · 2017–2022 validation · final 2023–2025 holdout sealed + + + + + 0.50 gate + + -0.50.00.250.5 + Classic momentum baseline0.2407 + Industry-residual momentum0.3198 + Point-in-time low volatility-0.0906 + One-month reversal-0.4542 + Annual QVPI composite-0.0234 + SEC cash-earnings acceleration0.4736 + All mechanisms remained unpromoted; the strongest candidate failed the absolute and harsh-cost gates. + diff --git a/docs/portfolio_evidence_2026-07-11.md b/docs/portfolio_evidence_2026-07-11.md new file mode 100644 index 00000000..1553a28b --- /dev/null +++ b/docs/portfolio_evidence_2026-07-11.md @@ -0,0 +1,56 @@ +# Pre-holdout research evidence — 2026-07-11 + +Status: reviewed aggregate evidence; licensed source rows are not distributed + +Selection window: 2017–2022 + +Final holdout: 2023–2025, sealed throughout this campaign + +Interpretation: validation evidence only; no alpha, promotion, or live-performance claim + +This note is a public-safe summary of a frozen research campaign. Each candidate +was specified before its return computation and kept or rejected using its +predeclared gate. Results include implemented costs; stress results increase +borrow to 600 bps and double non-borrow costs where stated. + +## Aggregate results + +| Mechanism | HAC Sharpe | t-stat | CAGR | Max drawdown | One-way turnover | Decision | +| --- | ---: | ---: | ---: | ---: | ---: | --- | +| Frozen classic momentum baseline | 0.2407 | — | 1.70% | 11.42% | — | Baseline; validation proxy only | +| Industry-residual momentum | 0.3198 | 1.2174 | 2.48% | 9.39% | — | Rejected: Sharpe improvement 0.0791 was below the required 0.10; harsh-cost CAGR -0.20% | +| Point-in-time low volatility | -0.0906 | -0.1943 | -2.20% | 43.83% | — | Rejected; harsh-cost Sharpe -0.2553 and CAGR -4.41% | +| One-month industry-residual reversal | -0.4542 | -1.4131 | -3.82% | 23.44% | 63.27× | Rejected; harsh-cost Sharpe -1.0268 and CAGR -8.10% | +| Annual QVPI accounting composite | -0.0234 | -0.0462 | -0.56% | 32.17% | 14.33× | Rejected; harsh-cost Sharpe -0.2782 and CAGR -2.71% | +| First-filed SEC cash-earnings acceleration | 0.4736 | 1.0651 | 1.73% | 7.71% | 13.57× | Rejected: below absolute 0.50 Sharpe gate; harsh-cost Sharpe -0.1034 and CAGR -0.45% | + +The SEC candidate used values present in two consecutive original 10-K XBRL +accessions and availability dates bound to exact SEC acceptance timestamps. Its +formation-month universe contained 796–1,730 complete names (median 1,084.5) +with zero ambiguous CCM rows. No current Compustat value was used for that +candidate. + +The QVPI candidate used a current Compustat snapshot with a fixed six-month +availability lag. That protects basic chronology but does not remove the risk of +later restatements; it is therefore not true vintage-accounting evidence. + +## Provenance + +- Frozen panel digest: `4ed2b33e2496e224a7701c3d0d71d593909d8fc7547ecdcbc483b2c83686206a` +- Industry-residual result manifest: `9e3a8818211a9ef9c81816bb2fadf6165636cc9a344f9284698adec3499ef107` +- Low-volatility result manifest: `fba7c4f4b4e96f6b310da13103921817db4a04bc910ea451fdd1f79ff8653ad0` +- Reversal result manifest: `573dd7c74bc6e2bcea0ab22bde30efdc1fcfc9b4eef0ec6e7665c800bfe28b02` +- QVPI result manifest: `72b378035b736c50f26be8e11bff1f72dc2478365971294694336c9945332fb2` +- SEC-vintage result manifest: `1ea92a323a254422772a8edfd86d0fd8d70b806a296190acaec1fb816379a3be` + +These digests bind the local reviewed artifacts without publishing restricted +rows. Reproduction requires authorized access to the same licensed snapshots. + +## Claim boundary + +Supported: the tested engine contracts, the aggregate validation statistics +above, the rejection decisions, and the fact that the recorded runners did not +open 2023–2025 outcomes. + +Not supported: final-holdout performance, alpha discovery, deployment, live +trading, or a claim that any mechanism is ready for promotion.