# Quality Guidelines

> Frontend quality baseline for `apps/**` changes.

---

## Practical Conventions

1. Run Flutter analyzer/tests for touched scope before finalizing changes.
2. Keep error logging explicit at catch sites using project logger (`getLogger(...)`).
3. Prioritize regression tests for high-risk modules: auth/session, home viewport, cache/repository, agent SSE flows.
4. Keep docs/protocol/frontend mappings aligned for API-contract changes.

---

## Real File Path Examples

- Lint/static analysis configuration:
  - `apps/analysis_options.yaml`
  - `apps/pubspec.yaml` (dev dependencies: `flutter_test`, `bloc_test`, `mocktail`)
- Test suites for high-risk modules:
  - `apps/test/app/router/app_router_redirect_test.dart`
  - `apps/test/core/chat/ag_ui_service_test.dart`
  - `apps/test/data/cache/cached_repository_test.dart`
- Logging usage examples:
  - `apps/lib/features/auth/presentation/bloc/auth_bloc.dart`
  - `apps/lib/features/auth/presentation/cubits/login_cubit.dart`
  - `apps/lib/features/settings/presentation/cubits/automation_jobs_cubit.dart`

---

## Review Checklist

1. **Layering and ownership**
   - No feature business logic moved into shared `data/**` infra.
2. **Error handling**
   - Exceptions are either propagated or converted to typed user-safe errors.
   - Catch branches include context logging where actionable.
3. **Contract alignment**
   - If API/error/event contracts changed, protocol docs and mapping updates are in the same change.
4. **Regression coverage**
   - Add/adjust tests for changed behavior in critical flows.

---

## Anti-patterns (with evidence)

- Error swallowing branches that silently downgrade behavior.
  - Existing examples to avoid extending:
    - `apps/lib/app/di/injection.dart` refresh callback catch returns `false`.
    - `apps/lib/core/chat/ag_ui_service.dart` malformed SSE payload parse catch ignores payload.
- Feature code bypassing shared feedback/loading primitives.
  - Project standard primitives exist in `apps/lib/shared/widgets/toast/`, `apps/lib/shared/widgets/banner/`, `apps/lib/shared/widgets/app_loading_indicator.dart`.
- Protocol changes implemented only in one layer.
  - Contract source of truth is under `docs/protocols/**` and must stay synchronized.

---

## Uncertainties / Gaps

- The repository does not currently enforce all frontend rules via CI (for example, no strict automated checker for protocol-mapper parity).
- `analysis_options.yaml` is currently close to Flutter defaults; stricter lint rules may still be introduced incrementally.