# MotorSignal — Agent Development Rules

Authoritative rules for MotorSignal (Flutter telemetry, ride recording, performance analysis, cloud sync). Every requirement below is load-bearing and strictly enforced.

## 1. Development Principles & Workflow
- **Investigate first**: Inspect source, providers, callers, schema, and tests before modifying. Never infer architecture from filenames or docs alone; production code and tests are authoritative.
- **Surgical scope**: Make the smallest safe change. Preserve public interfaces and existing functionality. Do not duplicate existing capabilities.
- **Do not fix unrelated problems**: Do not touch unrelated defects or silently expand scope. Separate confirmed defects from suspected risks.
- **Architectural conflicts & Stop conditions**: If a change conflicts with existing architectural contracts, stop and report immediately before broadening scope. When an instruction explicitly says STOP after reporting, do not proceed to the next stage.

## 2. Telemetry Freeze Boundary (FROZEN)
Subsystem is FROZEN unless task explicitly requires modification and user authorizes it:
- **TelemetryService**: Authoritative acquisition runs at 20 Hz / 50 ms. MUST NOT change acquisition cadence, introduce competing clocks, duplicate sensor acquisition, bypass the authoritative pipeline, or poll sensors from UI.
- **SensorFusionService**: Authoritative for derived orientation and lean data. MUST NOT introduce independent lean-angle calculations without explicit architectural justification and regression tests.
- **RideStateMachine**: Telemetry and motion semantics are FROZEN. Preserve the 3.0 MPH moving gate, kickstand isolation, motion/crash detection, interrupted-ride recovery, and lifecycle state transitions. Unrelated RideStateMachine changes are permitted when explicitly required, but existing ride lifecycle behavior must remain preserved unless specifically authorized otherwise. Behavioral changes require regression coverage.

## 3. Database Freeze Boundary (Schema 7 FROZEN)
`AppDatabase` is Drift Schema 7. Casual schema, migration, or persistence changes are FORBIDDEN.
- Any authorized change MUST include an explicit schema-version decision, migration logic, migration tests, backward-compatibility verification, verification against existing ride datasets, and consideration/testing for legacy and null data.
- NEVER delete, rewrite, or destructively migrate historical ride data during feature development. Use existing database helpers instead of duplicating raw inserts/updates.
- Stable ride identity (`cloudRideId`) is an immutable persistence contract; never regenerate or replace an existing ride identity.

## 4. Cloud & Offline Sync Architecture
Offline-first synchronization. Authoritative automatic completed-ride pipeline:
`RideStateMachine` → `syncObserverProvider` → `SyncManager` → `SyncOutbox` → `FirebaseSyncProvider` → Cloudflare R2 → Firestore.
- `SyncManager` & `SyncOutbox`: Authoritative durable sync queue. MUST preserve durable queued work, retries, auth-required states, restart recovery, duplicate suppression, account scoping, and offline operation. Do not replace with in-memory queues or introduce competing upload queues.
- `FirebaseSyncProvider`: Authoritative MotorCloud upload implementation. MUST preserve stable `cloudRideId`, R2 telemetry-bundle identity, Firestore ride identity, and retry/idempotency behavior.
- Legacy GitHub sync: Explicit developer/export tool only; MUST NOT route automatic completed-ride synchronization through a legacy GitHubSyncService queue.

## 5. Authentication, Performance & Forensic Boundaries
- **Authentication**: Authentication MUST NOT block local ride recording. Full functionality required when signed out, offline, or Firebase unavailable. Cloud authentication is never a prerequisite for collecting/storing local rides. Anonymous-to-authenticated transitions must never cause ride loss.
- **Performance Data**: 0–60 and 0–100 timing results recorded during an active ride must remain associated with the ride across cloud sync and export payloads. Legacy standalone runs remain supported.
- **Forensic Exports**: `FieldTestExportService` is authoritative. Preserve CSV schema, JSON session schema 1, GPX export, timestamp semantics, event ordering, and sub-second telemetry fidelity. Historical exported data must not be silently altered. Intentional schema changes require explicit authorization and versioning.

## 6. Architecture & UI Guidelines
- **Riverpod**: Follow existing Riverpod architecture. Do not add alternative state frameworks or parallel state containers. Guard provider lifecycle and `autoDispose` on long-lived services, observers, sync, and ride-state listeners.
- **UI Decoupling**: Widgets consume domain/application services only. Do not place telemetry acquisition, persistence, sensor fusion, sync, or heavy business logic inside widgets. Support portrait and landscape layouts. UI refresh frequency must never drive telemetry or persistence frequency.

## 7. Dependency & Toolchain Safety
- Do not perform broad dependency upgrades (e.g. `flutter pub upgrade`) to solve narrow issues; use the smallest compatible change.
- When changing dependencies: identify the exact reason, inspect lockfile impact, report exact version changes, and verify with tests, static analysis, and APK build.
- Do not raise Android `compileSdk`, `targetSdk`, AGP, Gradle, Kotlin, or Java versions to satisfy a package without first exhausting narrower solutions.

## 8. Documentation Accuracy
- Treat documentation as guidance, not proof of production behavior. When docs conflict with code, verify from source/tests, preserve correct production behavior, report stale docs, and update docs only when within task scope.
- Do not rely silently on stale schema versions, timing values, provider wiring, or architecture descriptions.

## 9. Testing & Validation Truthfulness
- Every behavioral change requires automated test coverage. Prefer behavioral tests over source-text assertions.
- Focused tests may be run first when appropriate during development.
- Before completion, the complete test suite and verification gates must run:
```text
flutter test
flutter analyze
flutter build apk --debug
```
- Task is INCOMPLETE if: tests fail, analysis introduces new errors, unjustified warnings appear, debug APK fails to build, or regression datasets change unexpectedly. Report pre-existing warnings accurately.
- Truthfulness: NEVER claim validation that was not actually performed. NEVER claim physical device or motorcycle validation unless it actually occurred.

## 10. Git Safety
- Checkpoints: Create or verify a checkpoint before significant architectural changes.
- Dirty Working Tree: Identify and preserve pre-existing files; do not alter or stage them unless part of the task; separate them in the final report.
- NEVER:
  - reset unrelated work
  - discard pre-existing user changes
  - stage unrelated files
  - commit unless explicitly authorized
  - push
  - rebase unless explicitly requested
  - force-push
  - rewrite history
  - delete branches or tags
- Use per-command Git safe-directory overrides when necessary rather than modifying global configuration.

## 11. Agent Skills

### Issue Tracker
- Issues live in GitHub Issues for `bponders12-cell/flutter-app`. See `docs/agents/issue-tracker.md`.

### Triage Labels
- Use the repository's standard triage labels. See `docs/agents/triage-labels.md`.

### Domain Documentation
- Use the single-context documentation layout and read the relevant current architecture, specification, release, and component documents before changing that area. See `docs/agents/domain.md`.