docs(decisions): the commands/ survey — measured, classified, decided (#525)

[eaitbrahim]

Closes #525.

A survey, not a refactor — the deliverable is numbers and a recorded decision. Lives as ADR 0003 (docs/decisions/0003-commands-layer-survey.md), mirroring 0001's Context/Options/Decision/Consequences shape (0002 is in flight on its own branch; this takes the next number).

Headline numbers

The issue's premise dissolved before the survey ran: #541 (PR #554) deleted the TUI and console-only layers (24,709 → 13,552 lines, +297/−23,448 with tests), and the engine grew in the same window. Restating the issue's table on main @ 16725c1:

	at filing	today
commands/	23,188	13,552
engine (7 modules)	17,260	20,798
ratio	1.34x	0.65x

Role split (the issue's checklist item 1)

role	lines	share
A. Shared report assembly (consumed by CLI + web/MCP)	5,486	40.5%
B. Services & decision orchestration (CLI-only)	4,975	36.7%
C. Front-end glue	1,880	13.9%
D. CLI-only report assembly + rendering	722	5.3%
E. Layer plumbing	489	3.6%

A line-level AST attribution: 1,016 render / 3,734 assembly+service / 1,292 click bodies / 3,320 helpers — and 4,190 lines (31%) of headers, docstrings and imports. The layer is substantially prose: the explanatory surface the issue's "case that this is fine" describes.

Decision paths named (item 2)

_run_backtest (#335) no longer exists — the #390 C4 service extraction split it into resolve_rule_backtest+backtest_resolved+run_rule_backtest, core in strategy.backtest. Ten further decision-bearing paths are named in the ADR with file:line and, crucially, where each one's policy lives: in every money case the deciding comparison (can_promote, transition, screen_asset, build_verdict, sizing.size) is in a compute module; commands/ holds sequencing and refusal wording. Two deliberate display-side mirrors (status._rail11_status, doctor's ATR banding) carry inline arguments for why they are not policy.

Duplication quantified (item 3)

Traced report by report across CLI/web/MCP: zero near-duplicate render paths remain. Each load-bearing report is one shared core plus thin format projections (12–77 lines) — status (gather_status → render_human / status_payload, the web even imports _human_age), doctor (gather_findings → CLI lines / MCP JSON), purification (engine build_report → text / JSON), insights (build_* → CLI renders / web payloads). The historic duplication was real — the TUI — and #554 deleted 11,103 lines of it.

Test parity (item 3b)

tests/commands/: 11,031 lines, 527 test functions — more than any engine area's suite — plus test_service_parity.py (CLI-vs-service byte-equality pins) and test_console_thinness.py (AST scan: no compute imports/calls, Decimal display-only, no broker construction outside seams).

The decision (item 4)

C — nothing moves. Move-to-engine is refused on the evidence (the policy is already engine-side; what would move is sequencing and explanation, and the parity tests pin the sequence against the CLI a human runs). Unification is moot (nothing left to unify). The shape is recorded as standing rules + four re-opening triggers. The one actionable gap found — the thinness pin scans keel/web/*.py but not keel/mcp/*.py (8 thin handlers, vacuously green today) — is filed as #588, a pin extension, not a refactor.

Deviations

• docs/presentations/se.md (the raiser, §3/§9.2) is not on main — it lives on the unmerged worktree-docs-se-presentation branch, so no pointer was added there (it would conflict on that branch's merge). The ADR cites it in its header the same way ADR 0002 cites §9.6.
• Numbered 0003 per the in-flight 0002 (docs-526-sqlite-adr branch).
• uv run pytest -q: 4355 passed, 3 skipped.