Scout
wiki/decisions/2026-05-21-ui-interaction-contract.md
ADR: UI Interaction Contract
Date: 2026-05-21 Status: Accepted
Context
During the Scout app-first frontend work, the UI regressed into a polished shell: some visible controls were clickable but did not perform real work, the Browse control was degraded from a native filesystem picker to a weaker fallback, and tests passed because they covered selected happy paths rather than every visible interactive promise.
This created user-visible failure: buttons, tabs, menus, and Browse appeared to exist but were not reliably functional.
Decision
Every visible enabled interactive element in Scout is now a product contract: it must be functional, or it must be visibly disabled with a clear reason.
Rationale
- Scout is an app-first product surface. Users should not need to know which controls are mockups, placeholders, or future work.
- A crawler/intelligence tool needs trust. Fake controls undermine trust more than missing controls.
- Native directory selection is a core workflow because output location affects artifact discoverability.
- Browser E2E tests must validate the actual visible UI, including negative paths such as canceling a picker or clearing a run.
Alternatives Considered
| Option | Why rejected |
|---|---|
| Leave placeholder controls visible with toast messages | Looks functional but does not work; repeats the shell/mocking failure mode. |
| Keep a custom directory browser fallback after native picker cancel | Creates double-dialog UX and confuses the single working-directory contract. |
| Test only happy-path Start Execution | Misses regressions in controls the user actually sees and clicks. |
Consequences
- Newly added UI controls require either E2E coverage or an intentionally disabled state.
- Browse must use a single native picker path in the frontend; if native picker support is unavailable, the UI must clearly fall back to direct path editing without opening a second dialog.
- Frontend completion claims require a fresh local server restart plus browser
validation against the actual running
/app. - The control inventory should be reviewed whenever the app shell changes.
Regression Tests Added
- Native Browse path updates the single Working Directory field and does not
render the old
workdirDialog. - Non-implemented rail and top-nav sections are disabled with a visible reason.
- Crawl Settings chips can be removed and restored.
- Developer Details remains copyable and secondary.