wiki/decisions/2026-05-21-app-first-validation-gate.md
ADR: App-First Validation Gate
Date: 2026-05-21 Status: Accepted
Context
Scout's frontend looked polished before every control and workflow was truly validated. This created a trust failure: the UI appeared functional while some buttons, tabs, picker paths, and result states were partial, stale, or not proven by tests.
Decision
Scout app work must pass an app-first validation gate before being called ready: workflow specs, control inventory, deterministic E2E coverage, live target coverage, codebase cleanup, vault update, and a truthful validation report.
Rationale
The app is now Scout's primary product surface. CLI/API/skill parity matters, but the app must first make runs visible, cancellable, resettable, and evidence-driven. A control is a product contract: if it is visible and enabled, it must work or be covered by a test that proves the expected behavior.
Alternatives Considered
| Option | Why rejected |
|---|---|
| Continue shipping visual mockups first | Repeats the shell/UI mismatch that caused the regression |
| Rely only on API tests | Does not validate the actual user journey |
| Keep stale validation reports | Preserves false confidence and makes regressions harder to see |
Consequences
- Workflow specs now live under
wiki/ux/workflows/. - Repo docs mirror the same specs under
docs/ui/workflows/. - E2E tests must inventory visible controls.
- Live target results must distinguish records, sources, citations, blocked evidence, and artifacts.
- Validation reports must state known gaps instead of overclaiming completion.