# Investing System Card

## Purpose

This card explains the current investing system as a decision process rather than as a marketing claim.

It is intended to answer four questions:

1. What information does the system look at?
2. How does that information become a portfolio decision?
3. What prevents the system from acting when inputs are weak or stale?
4. What should a user *not* infer from the output?

## System objective

The system is designed to support disciplined recurring portfolio allocation and rebalancing across diversified ETF risk buckets.

The intended operating pattern is monthly portfolio decisioning with more frequent monitoring. Weekly monitoring is observe-only in the v0.1 design.

The system is not designed to:

- forecast individual-stock winners;
- day trade;
- promise market outperformance;
- eliminate investment losses;
- infer trading authority from conversation;
- act when required data fail integrity checks.

## Input categories

### ETF-level features

The v0.1 feature specification includes, per eligible ETF:

- 1-month return;
- 3-month return;
- 12-month return;
- 3-month realized volatility;
- trailing 12-month drawdown;
- price relative to the 200-day moving average.

These features are used to describe trend, momentum, volatility, and recent loss behavior.

### Macro and market-risk features

The v0.1 global feature set includes:

- VIX level;
- 10-year Treasury yield;
- 2-year Treasury yield;
- 10-year minus 2-year yield-curve slope.

The current decisioning specification intentionally keeps the regime model low-dimensional rather than adding a large number of weakly justified signals.

### Integrity features

The system also tracks whether the inputs themselves are usable, including:

- price staleness;
- missing required features;
- universe coverage;
- macro-series staleness.

An input is not treated as trustworthy merely because a value exists.

## Historical knowledge boundary

For historical replay, an observation is eligible only if it was knowable at the decision timestamp.

The pipeline enforces an `asof_ts <= decision_ts` boundary. Historical rows without a usable availability timestamp are excluded instead of being assumed to have been available.

This is intended to reduce look-ahead bias in backtests and reruns.

## Decision path

The canonical v0.1 sequence is:

1. load the active ETF universe;
2. remove assets that fail eligibility/freshness rules;
3. calculate a simple market regime score;
4. translate the regime score into risk-bucket tilts;
5. enforce bucket bounds;
6. enforce portfolio-level exposure caps;
7. allocate within each bucket using a simple score;
8. enforce per-asset limits and churn controls;
9. apply a no-trade band and turnover cap;
10. persist the recommendation, explanation, versions, and integrity record.

## Regime model

The decisioning specification identifies three primary regime components:

- **Trend:** broad US equity price relative to its 200-day moving average, calculated as `(price / MA200) - 1`;
- **Volatility:** market volatility level;
- **Rates stress:** yield-curve or yield-change information.

The allocator does not substitute MA50 or another shorter moving average for the MA200 trend while retaining the `trend_ma200` label. If the required MA200 is missing or invalid, the trend component contributes a neutral value of `0.0` rather than silently switching methodology. Other integrity gates can still block a run when required market data are not trustworthy.

The intended behavior is monotone and bounded:

- stronger risk-on conditions may increase equity, credit, and commodity exposure;
- stronger risk-off conditions may increase duration, cash-like assets, and gold while reducing higher-risk exposure.

The system should not interpret a regime score as certainty about what the market will do next.

## Within-bucket selection

Within a risk bucket, the v0.1 specification primarily favors:

- stronger momentum;
- smaller drawdown penalties.

Scores are translated to portfolio weights with a softmax-style allocation and then constrained by policy.

This is intended to provide a deterministic allocation mechanism, not a claim that momentum reliably predicts future returns.

## Current portfolio controls

The default v0.1 policy currently includes:

- 35% default maximum single-asset weight;
- 80% maximum equity exposure;
- 60% maximum long-duration exposure;
- 40% maximum credit exposure;
- 85% maximum combined risk-asset exposure;
- 40% maximum cash-like allocation;
- 1 percentage-point absolute no-trade band;
- 35% maximum one-way turnover per rebalance.

Bucket-specific limits further constrain individual risk categories.

These are policy parameters, not universal investment recommendations. They are versioned so changes can be evaluated rather than silently applied retroactively.

## Trading-cost assumptions

The current policy models:

- a base commission assumption;
- different slippage assumptions by risk bucket;
- larger assumed costs when volatility crosses stress and crisis thresholds.

The backtest protocol requires costs to be applied to the primary strategy and comparison strategies consistently.

## Failures and refusal behavior

The system is designed to prefer no new action over a fabricated decision when required inputs are not trustworthy.

Examples of conditions that can block or constrain action include:

- insufficient eligible assets;
- excessive missing features;
- stale prices;
- stale required macro data;
- unsatisfied portfolio constraints;
- missing or incomplete broker synchronization where the operating mode requires it.

The policy supports fail-closed behavior. Where explicitly allowed, a run may hold prior weights instead of producing a new allocation.

## User preferences and authority

Risk tolerance and investment horizon are explicit inputs to the broader product policy. They should not be inferred from authentication, account type, another user's state, or casual conversation.

A recommendation and permission to execute it are separate concepts. Brokerage execution is governed by separate account-specific authorization and safety controls.

## Output

A normal decisioning run can produce artifacts including:

- target allocation;
- allocation explanation;
- integrity audit;
- version identifiers;
- decision log;
- recommendation/trade preview where the operating mode supports it.

The intended trust model is that a later reader can determine which data, methodology version, policy version, and constraints produced a decision.

## What the output means

A recommendation means roughly:

> Given the available inputs, current methodology, current policy, and current portfolio state, this is the allocation the system's declared rules produce.

It does **not** mean:

- the recommended assets will rise;
- the recommendation is guaranteed to outperform;
- the model has discovered private information;
- the allocation is suitable for every investor;
- the recommendation should execute without the required account permissions and safety checks.

## Evidence state

The system has reproducibility and evaluation infrastructure, but that should not be confused with a long independent track record.

Current public claims should remain consistent with these facts:

- a long-term independently verified live performance record is not yet established;
- superiority to a simpler passive portfolio is not yet established;
- historical simulations must remain clearly labeled as simulations;
- negative periods, drawdowns, and benchmark underperformance should be retained alongside favorable evidence;
- independent methodology review is still a future evidence layer.

## Canonical internal sources

This card currently derives from:

- `documents/DOCUMENT-Feature_Catalog.md`;
- `documents/DOCUMENT-Decisioning_Allocator_Spec.md`;
- `documents/DOCUMENT-Backtest_Protocol.md`;
- `config/policy.py`;
- `ops/pipeline.py`.

Future public versions should identify the exact private methodology snapshot or commit they correspond to.