Sonnet checklist

# Sonnet Tier — Logic Checklist (extended reference)

This is the extended reference the Tier 2 (Sonnet) agent loads when a logic check needs more context than the inline agent definition. For the canonical flow + RESULT block schema, see `../../../agents/sonnet-reviewer.md`.

## Scope

Logic review is where the cross-file tracing happens. Tier 1 scans each file; Tier 2 traces paths between files. It catches:

- Scope drift (feature added that wasn't in the issue)
- Scope shortfall (feature in the issue not yet implemented)
- Type contracts that silently break (annotated `float`, caller passes `None`)
- Schema contracts that silently break (WHERE literal doesn't match stored data)
- Config contracts that silently break (YAML key never read, code read key that doesn't exist in YAML)
- Lifecycle wiring gaps (drain function called at reconnect but not startup)
- Dead `try / except` blocks that wrap functions that can't raise

## Cross-Boundary Contract discipline

Every value that crosses a boundary must have its contract verified. The three canonical boundaries are:

1. **Type Contract** — every function parameter with a non-Optional annotation must have all call sites verified non-None. If any caller can pass `None`, annotation must be `T | None` and the function must guard.
2. **Schema Contract** — every SQL query's columns must exist in the target table. Every SQL literal in WHERE must match the actual data stored (e.g., DB normalises `'SLD'` → `'SELL'` on insert — querying `side='SLD'` returns zero rows silently).
3. **Config Contract** — bidirectional. Every key added to YAML must be read by code. Every key read by code must exist in YAML. Dead either direction = incomplete implementation.

## Sample Invocation Gate — when it applies

For changes that touch any of:

- Pipeline / backtest / orchestration wiring
- CLI flag threading into downstream function signatures
- Cross-module function-arg propagation (>1 hop from CLI to DB / file write)
- Persistent-state writes (JSONB schema mutation, SQL literal drift across SET / READ sites, DB column rename, enum-value drift)

Unit + smoke tests are necessary but NOT sufficient. A REAL-CLI sample invocation against real DB is required. Exit-code-0 alone is insufficient — we have history of exit-0 runs writing zero rows. The proof must show rows landed + downstream consumers succeeded.

Mocks that accept `**kwargs` silently discard params and do NOT prove propagation. Any mock in the fix's tests must assert `call_args.kwargs["<key>"] == <expected>` explicitly.

## Observability discipline

Every new component must emit:

1. **Structured logs** at every decision boundary, state transition, and external call
2. **Metrics** for anything quantifiable — counters, durations, queue depths, success / failure ratios
3. **Audit trail** for state changes affecting production data, money, or user-visible behaviour — append-only, with actor + timestamp + reason

`print()` is not logging. Empty `except:` blocks are not error handling. `return None` on error without a structured log is a silent fallback.

## Graph discipline — lazy-fallback detection

Every subagent RESULT block that discusses graph queries must start with `mcp_graph_available: yes|no` on the first line. This discriminates:

- `yes` + graph-query evidence lines = expected
- `no` + grep fallback evidence = acceptable (no MCP access)
- `yes` + no graph-query evidence = **lazy fallback** — the subagent had graph access but used grep anyway. FAIL.

This is how a grader at Tier 2 catches subagents that silently skip graph when it was available.

## Spot-check discipline

When the graph IS used, Tier 2 requires a spot-check: read at least one result's source file:line to verify graph output matches reality. The graph is AST-based — it does NOT see runtime behaviour, does NOT verify DB column values, does NOT catch JSONB schema drift. Record the spot-check file:line in RESULT.