docs/PHASE3_ADJACENT_GAP_AUDIT.md

# Phase 3 Adjacent-Gap Audit

## Scope

The audit covers immutable plan creation and hashing, approval creation and consumption, dashboard analysis/approval/execution routes, bounded dashboard state, the LLM-facing toolset, Telegram, safety-only revalidation, material-change invalidation, and concurrent analysis behavior.

## Closed gaps

1. **Persisted hash omitted server plan identity and creation time.** Hash schema 2 now binds `plan_id`, `created_at`, ownership/session/account/mode/environment, market/contract identity, geometry, quantities, leverage/margin, risk/slippage, provider provenance, and strategy/policy/software versions. Schema 1 remains readable only for legacy verification.
2. **Approval checks trusted the approval row without rechecking authoritative plan payload/state.** Creation, validation, and consumption now verify the stored payload hash and current plan ownership, scope, readiness, expiry, active approval, invalidation, and execution state.
3. **Concurrent dashboard analysis could silently supersede a newer result.** The browser sends `expectedPreviousVersion`; the repository enforces optimistic versioning; stale tabs receive HTTP 409.
4. **Material-change evidence was generic.** Supersession records normalized changed fields and invalidates the old approval transactionally.
5. **Bounded dashboard plan copies retained a hash without all hash material.** Dashboard state now retains the canonical subset and verifies both the source and bounded snapshot before display.

## Boundary review result

- Dashboard approval and execution accept identifiers only.
- LLM mutation handlers remain blocked and are absent from the runtime toolset.
- **Re-verified (2026-07-27, plugin migration):** `set_leverage_and_margin`, `execute_futures_position`, and `close_futures_position` are still hard-reject stubs in `futures_trading_tool.py` and are **not** registered by `plugins/futures_trading/`. Only six read-only tools are exposed to the agent runtime.
- Telegram remains analysis-only and does not reference approval or execution mutation boundaries.
- Safety revalidation can only accept or reject the exact persisted hash; accepted and rejected contexts are durable and do not rewrite plan payloads.
- Cross-user, cross-session, cross-account, cross-mode, expiry, reuse, payload-tamper, material-change, stale-tab, and version-conflict tests pass.

## Automated audit

Run:

```bash
python scripts/audit_plan_approval_boundaries.py
```

Expected result: `findings=0` and `RESULT: PASS`.

## Remaining limitations

No file-based Phase 3 integrity bypass is known. Testnet and Live remain disabled and are governed by later release gates and operator approvals.