Growth needs
a counterweight.

You are a senior quantitative software engineer working in my local repository. Build a reproducible, audit-friendly Python research package to test whether static ETF combinations can beat BOTH SPY (S&P 500) and QQQ (Nasdaq-100) over long holding periods.

OBJECTIVE
Evaluate three-sleeve portfolios made from:
- Gold: PHYS or IAUM
- U.S. momentum: SPMO
- Semiconductors: SMH

The incumbent is 40% gold / 30% SPMO / 30% SMH. Also include 20% gold / 50% SPMO / 30% SMH as a named growth-tilt comparator. Do not assume either is optimal.

WORKING RULES
1. Begin read-only. Inspect the repo for existing data, code, tests, assumptions, and prior results. Preserve unrelated work.
2. Use Python 3.12+, pandas, numpy, scipy, pyarrow, pytest, and a documented market-data adapter. Pin dependencies.
3. Use adjusted total-return daily data. Cache the raw response and normalized parquet with retrieval timestamp, provider, symbols, date range, and checksum.
4. Fail loudly on missing tickers, duplicate dates, suspicious nulls, stale data, currency mismatches, or a requested sleeve being silently dropped. Never substitute a ticker without an explicit flag and disclosure.
5. The primary direct-history test begins on 2015-10-12, when all required live funds have data. Keep all pre-inception proxy tests separate and clearly labeled.
6. Rebalance monthly. Snap month-end labels to actual trading days. Include a buy-and-hold sensitivity check.
7. Use SPY and QQQ as separate total-return benchmarks. A “joint win” requires beating both over the same window.

PORTFOLIO SEARCH
- Generate a configurable 5-percentage-point grid whose weights sum to 100%.
- Default constraints: gold 10–50%, SMH 10–40%, SPMO 20–70%.
- Report the unconstrained frontier separately so recent SMH concentration cannot silently dominate the recommended set.
- Never rank on CAGR alone. Produce Pareto views for joint benchmark win rate, CAGR, Sortino, and maximum drawdown.

METRICS
- CAGR, annualized volatility, Sharpe, Sortino, maximum drawdown, Calmar, downside deviation, CVaR 5%, turnover, and benchmark excess return.
- Use a configurable risk-free rate; default to 3% and run 0%/3%/5% sensitivity.
- Compute rolling 3-, 5-, 7-, and 10-year annualized returns and the percentage of windows that beat SPY, QQQ, and both.
- State prominently that overlapping rolling windows are descriptive observations, not independent probabilities.

ROBUSTNESS
- Walk-forward analysis with at least two non-overlapping eras plus expanding-window selection followed by untouched out-of-sample evaluation.
- At least 1,000 weight perturbation trials of ±5 percentage points, preserving valid sums and constraints. Report rank-flip frequency.
- Stress tables for Q4 2018, the 2020 crash, the 2022 bear market, and any other objectively defined period in the available data.
- Sensitivity to monthly vs quarterly rebalancing, fund expenses, 0/5/10 bps trading friction, and reasonable tracking error.
- Bootstrap or block-bootstrap confidence intervals where methodologically defensible; explain limitations.

ACCOUNT LOCATION / TAX ANALYSIS
- Keep market-performance analysis pre-tax. Add a separate U.S.-investor account-location module.
- For taxable brokerage, model PHYS only under explicit scenarios: timely QEF election with annual Form 8621, missed/no QEF, and tax-preparer cost. Do not claim the favorable treatment is automatic.
- For tax-advantaged accounts, compare PHYS with IAUM primarily on fee drag, structure, liquidity, and premium/discount behavior. Verify current fees and tax rules from official issuer and IRS sources at runtime.
- Clearly label tax output educational, jurisdiction-specific, and subject to professional review.

REQUIRED ARTIFACTS
- README.md with exact setup and rerun commands
- pyproject.toml and locked dependencies
- config/default.yaml containing dates, weights, constraints, costs, and risk-free rate
- src/ package with separate data, portfolio, metrics, rolling-window, robustness, tax-scenario, and reporting modules
- tests/ covering weight sums, rebalance dates, return math, drawdown, missing-data failure, benchmark alignment, and no-look-ahead behavior
- data/manifest.json and cached parquet (or a documented fetch command if licensing prevents redistribution)
- results/summary.csv, rolling_windows.csv, walk_forward.csv, robustness.csv, stress.csv, and account_location.csv
- results/report.md with an executive summary, methods, findings, caveats, and links to every generated artifact
- output/index.html with accessible charts and tables; no external CDN dependency

ACCEPTANCE GATES
- Run formatting, linting, type checking, and pytest.
- Independently reimplement CAGR, Sortino, and max drawdown in a verification module and compare within stated tolerances.
- Confirm every chart number traces to a saved result row.
- Show the exact data cutoff and whether results are direct fund history or proxy history.
- Do not present any allocation as a forecast, guarantee, or adopted recommendation. If no mix reliably beats both benchmarks, say so plainly.

Before editing, summarize the repo state and the implementation plan. Then build the full pipeline, run it, fix failures, and return the final evidence table plus the exact commands needed to reproduce it.