# AGENTS

## Scope

These instructions apply to all work inside `NewTradingSystem`.

## Core Rule

The code, the docs, and the migration status must tell the same story.

If code changes but the docs still describe the old behavior, the work is incomplete.

## Documentation Freshness Contract

When a change affects architecture, runtime behavior, strategy behavior, broker support, operator workflow, or current project status, update the matching documentation in the same change:

- `README.md` for entrypoints, commands, and top-level capabilities
- `docs/current-state.md` for what is real today versus not implemented yet
- `docs/legacy-inventory.md` for the concrete extraction and discard map
- `docs/legacy-extraction-portal.html` for the human-friendly published architecture and migration view
- `docs/documentation-freshness-contract.md` for the documentation process itself if the process changes
- `tasks/master-roadmap.md` for status and backlog movement
- any relevant plan under `docs/plans/`

Do not claim a feature is shipped if these documents still describe the previous state.

## Legacy Extraction Rules

Every imported asset from the legacy `trading` repo must be classified before implementation:

- `extract`: preserve the behavior with minimal translation
- `redesign`: keep the idea but rebuild it against the new platform boundaries
- `reference-only`: keep it as historical input, not runtime code
- `discard`: do not port it

Do not copy legacy workflows, data dumps, ad hoc scripts, or file-based state blindly.

## Runtime State

- Keep `.env*`, `var/`, generated dashboard data, and any local runtime state out of git.
- Keep paper-only as the default unless an explicit task says otherwise.
- Do not let strategies talk directly to broker APIs.

## Verification Rule

Before closing a task, verify the thing that changed:

- code changes: run tests and the relevant runtime command
- docs changes: check links, structure, and rendered HTML when applicable
- migration status changes: confirm they match the codebase truth