ticket-99: evidence-first public portfolio presentation

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.

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/`.

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`.

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.

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": []
+}

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.

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.

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.

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

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.