# V2 Agent Execution Contract

Agents should work the backlog in `V2_TODOS.md` from top to bottom.

## Rules

1. Read the current section, the referenced architecture/dependency sections,
   and any ADR linked by the task.
2. Treat named paths as target artifacts. If the path does not exist, create it
   with production structure, validation, and tests.
3. Do not satisfy a task with an empty module, fabricated data, inert adapter,
   or test that only asserts truthiness.
4. If a dependency package is marked planned, create or land that package before
   wiring V2 to it, unless the task explicitly chooses a temporary feature gate.
5. Run all targeted verification for the touched surface.
6. Run `python3 V2/tools/validate-v2-docs.py` after documentation edits.
7. Mark a TODO `[x]` only after the implementation, tests, docs, and validation
   are complete.

## Default Artifact Policy

- Unreal work lives under `V2/ue/`.
- Runtime services live under `apps/v2/`.
- Web and public docs surfaces move under `apps/oshun/web` when the
  corresponding TODO asks for shell integration.
- Mobile companion surfaces move under `apps/oshun/mobile` when the
  corresponding TODO asks for shell integration.
- Balance source data lives under `V2/balance/` and must have schemas or
  linters.
- Product/legal decisions live under `V2/docs/decisions/`.

## Blocker Policy

When a task cannot proceed because an upstream package or platform decision is
missing, first check `V2/docs/decisions/`. If the decision exists, implement the
documented default. If no decision exists, add an ADR before writing runtime
code.