# Investing by The Assembly Method: Methodology

## Why this exists

This folder is the beginning of a public, auditable description of the investing system.

The goal is not to ask readers to trust a founder, a model, or a backtest. The goal is to make the system understandable enough that a skeptical reader can inspect its rules, reproduce selected calculations, identify limitations, and disagree with the approach on the merits.

This documentation is intentionally more conservative than marketing copy. It distinguishes between:

- **Implemented**: behavior represented in the current codebase.
- **Specified**: behavior required by a canonical specification but not treated here as proof of complete production operation.
- **Proven**: behavior supported by retained runtime or evaluation evidence.
- **Planned**: work that should not be described as a current capability.

A specification is not a performance result. A backtest is not a live track record. A successful founder run is not evidence that another customer will receive the same outcome.

## Read this package

- [System Card](system-card.md): what inputs the system uses, how a decision is produced, and what can stop action.
- [Executable Methodology Audit](implementation-audit.md): what the current code actually implements, including limitations and optional safeguards.
- [Evidence Standard](evidence-standard.md): what must accompany any future performance or benchmark claim.
- [Public Evidence Ledger](evidence/README.md): append-only rules for retaining favorable and unfavorable evidence.
- [Publication Boundary](publication-boundary.md): what can be opened safely and what must remain private.
- [Public Methodology Export Bundle](export-bundle.md): the explicit security boundary and standalone reproduction instructions used before public release.
- [Independent Review Checklist](reviewer-checklist.md): a review format designed to surface criticism rather than manufacture an endorsement.
- [`methodology-manifest.json`](methodology-manifest.json): machine-readable snapshot of implementation/specification/evidence status.
- [`generated-policy.json`](generated-policy.json): retained public-safe snapshot generated from the same versioned policy object used by the private application.
- [`calculations.py`](calculations.py): standard-library public subset of the disclosed return, risk, and cash-benchmark calculations.
- [`examples/reproduce_synthetic_metrics.py`](examples/reproduce_synthetic_metrics.py): standalone deterministic calculation example using fully disclosed invented returns. It is explicitly not performance evidence.
- [`data/treasury_bill_2025-06-30.json`](data/treasury_bill_2025-06-30.json): minimal official Treasury auction input used by the real-market cash-benchmark example.
- [`examples/reproduce_treasury_cash_benchmark.py`](examples/reproduce_treasury_cash_benchmark.py): standalone calculation from a published Treasury bill price to holding-period and annualized cash return.
- `tools/export_public_methodology.py`: derives the public-safe policy snapshot directly from the current versioned policy object.

## What the system is trying to do

The system is designed to make recurring portfolio review and rebalancing more disciplined and less dependent on a person remembering to follow markets continuously.

At a high level:

1. ingest market and macro/risk data;
2. construct features using only information available at the historical decision time;
3. run data-integrity gates;
4. estimate a simple risk-on/risk-off regime signal;
5. convert that signal into bounded portfolio tilts;
6. allocate within asset buckets subject to diversification, exposure, and turnover limits;
7. generate an explanation and audit artifacts;
8. act only through separately controlled account permissions and execution safeguards.

The strategy is not intended to predict tomorrow's winning stock, guarantee returns, eliminate drawdowns, or make trading decisions from free-form AI conversation.

## Current method in one paragraph

The current v0.1 strategy uses a deliberately low-dimensional regime model built around market trend, volatility, and rates stress. Risk-on conditions can tilt toward equities, credit, and commodities. Risk-off conditions can tilt toward duration, cash-like assets, and gold. Within a bucket, assets are scored primarily from momentum with a drawdown penalty. All target weights remain subject to bucket limits, per-asset limits, portfolio exposure caps, and turnover controls. If required data fail integrity checks, the system is designed to fail closed or, where explicitly allowed, hold prior weights instead of manufacturing a new allocation.

The executable trend component now matches the canonical feature contract: `(price / MA200) - 1`. The allocator does not substitute MA50 while retaining the `trend_ma200` label. If MA200 is missing or invalid, the trend contribution is neutral rather than silently switching to a shorter-horizon rule. Focused regression tests distinguish the MA200 result from the prior MA50 behavior.

## Standalone reproducibility examples

The reviewed export bundle contains a small standard-library calculation module, the generated public policy snapshot, fully disclosed invented monthly returns, and one minimal real-market Treasury auction input. An outside reviewer can run both examples from the bundle without the private production repository, third-party Python packages, or network access.

`python examples/reproduce_synthetic_metrics.py` validates the disclosed return/risk math against invented monthly inputs. Private-repository parity tests compare those public calculations against the canonical `backtest.metrics.MetricsCalculator`.

`python examples/reproduce_treasury_cash_benchmark.py` uses the official U.S. Treasury auction result dated June 30, 2025 for a 91-day bill. The disclosed price is 98.929486 per $100 maturity value and Treasury's published investment rate is 4.340%. The public calculation reproduces a simple annualized rate of approximately 4.340283%, which agrees with the published rounded rate within 0.001 percentage point.

The Treasury example is a cash-benchmark calculation primitive only. It is not generated by the investing strategy and is not a backtest, paper result, live result, recommendation, or evidence that the strategy beats cash or any passive portfolio.

## Important current constraints

The policy represented in the repository currently includes constraints such as:

- default maximum single-asset weight of 35%;
- maximum combined equity exposure of 80%;
- maximum long-duration exposure of 60%;
- maximum credit exposure of 40%;
- maximum combined risk-asset exposure of 85%;
- a 1 percentage-point no-trade band;
- a 35% cap on the executable turnover measure, defined by the controller as the sum of absolute portfolio-weight changes;
- minimum history and data-freshness requirements;
- higher assumed trading costs under stressed volatility conditions.

These values are versioned implementation parameters, not claims that they are optimal. Changes should be versioned and evaluated rather than silently rewritten after seeing results.

## Evaluation standard

The canonical backtest protocol requires:

- identical decision/execution timing for the strategy and baselines;
- transaction costs and slippage;
- a static 60/40 baseline;
- a diversified static baseline;
- an optional simple trend baseline;
- walk-forward evaluation;
- no retuning inside the final holdout;
- CAGR, volatility, Sharpe, drawdown, turnover, and cost reporting;
- stress tests for timing and trading costs;
- uncertainty estimates;
- versioned run artifacts.

The implementation audit distinguishes between evaluation capabilities that are always wired into the engine and safeguards that are currently optional. In particular, the backtest framework supports walk-forward plans and embargo checks, but a walk-forward configuration is not currently mandatory for every run.

See [Evidence Standard](evidence-standard.md) for the rules that should govern anything published as performance evidence.

## What is not yet established

This project should not currently be represented as having:

- a long-term independently verified live track record;
- proven superiority to a simple passive portfolio;
- guaranteed or reliably predictable outperformance;
- evidence that favorable backtests will persist in live use;
- a completed independent third-party methodology review;
- a settled public claim about regulatory status beyond whatever has been separately verified for the actual service being offered.

Where evidence is incomplete, the public product should say so.

## Source map

The current internal implementation and canonical specifications that this public description is derived from include:

- `config/policy.py`: versioned portfolio, integrity, turnover, and cost constraints;
- `ops/pipeline.py`: reproducible run pipeline, policy wiring, and historical as-of gating;
- `decisioning/regime_score.py`: regime scoring;
- `decisioning/bucket_tilts.py`: regime-to-bucket targets;
- `decisioning/within_bucket.py`: asset scoring and within-bucket weighting;
- `decisioning/turnover.py`: no-trade band and turnover controls;
- `documents/DOCUMENT-Feature_Catalog.md`: feature definitions and timing rules;
- `documents/DOCUMENT-Decisioning_Allocator_Spec.md`: allocation sequence and regime/tilt design;
- `documents/DOCUMENT-Backtest_Protocol.md`: evaluation and comparison rules;
- `backtest/engine.py`: strategy/baseline evaluation and robustness runs;
- `backtest/baselines.py`: comparison portfolios;
- `backtest/metrics.py`: performance and risk metrics.

Before this package is published outside the private repository, every statement should be rechecked against current production code and the security publication boundary.

## Next proof work

The current package can demonstrate standalone deterministic return/risk calculations from disclosed synthetic inputs, a standalone real-market Treasury cash-benchmark calculation from official public data, a policy snapshot derived from executable configuration, clear implementation/specification boundaries, and an append-only evidence contract. The next high-value additions are:

1. publish the first dated strategy-evidence entry only when it satisfies the historical publication gate, including walk-forward context, matched baselines/costs, adverse evidence, timing/cost sensitivity, limitations, and claim boundary;
2. arrange an independent methodology review using the checklist after the public package is coherent enough to critique;
3. populate a purpose-built public repository from the reviewed export bundle rather than exposing private production history;
4. link the public trust page to methodology, evidence, limitations, and independent review artifacts.