Error handling, clean-code style

Scanner path: commands below assume tools/cc-scan.py / tools/arch-scan.py are in the repo. If they are not, the same scanners may be on PATH as cc-scan / arch-scan (identical flags) — see INSTALL.md §1b. If neither exists, ask for the report instead of guessing numbers.

1. The 30-second decision: Result or exception?

Can the caller handle it right here, as a normal outcome?
├─ YES  → Result/Option/enum       (not found, out of stock, validation failed)
└─ NO   → exception                (network down, corrupt data, invariant broken)

"A miss" that callers must branch on every time is not an error — it is a second return type. An "error" that the caller cannot do anything about is not their problem: log it, alarm it, and stop pretending the return value carries the news.