docs: review failure diagnostics

[Tomoscorbin]

Summary

• document the current user-facing failure diagnostics across read, planning, foreign-key, and execution phases
• identify why rejected drift, especially UnmanagedAspectDrift, does not show the exact differences
• prioritize improvements for read context, CLI duplication, structured failure records, validation evidence, and execution presentation
• define an implementation sequence and acceptance criteria

Why

Recent READ and validation failures did not provide enough information to diagnose the problem. The review traces failure values through the report, CLI, exceptions, and to_dict() output and records the concrete gaps before changing the public reporting contract.

The highest-priority findings are that rejected drift is rendered as “no changes,” READ failures do not retain the failing catalog-read step, and the CLI can present the same expected READ failure three times.

Impact

This is documentation-only. It proposes a cause-first diagnostics contract and a staged implementation plan; runtime behaviour and public APIs are unchanged.

Validation

• uv run pytest -q --no-cov tests/application/test_failures.py tests/application/test_rendering.py tests/application/test_report.py tests/application/test_validation.py tests/cli/test_app_plan.py tests/adapters/databricks/test_read.py tests/adapters/databricks/test_execution.py
• 204 tests passed
• git diff --cached --check