302 lines
9.6 KiB
Markdown
302 lines
9.6 KiB
Markdown
# MotorSignal — Agent Development Rules
|
||
|
||
## Project Identity
|
||
|
||
MotorSignal is a Flutter motorcycle telemetry, ride-recording, performance-analysis, and cloud-synchronization application.
|
||
|
||
Before modifying code, agents MUST inspect the relevant existing architecture, providers, services, persistence paths, and tests and understand the current implementation.
|
||
|
||
Do not infer architecture from filenames or documentation alone when the production code can be inspected directly.
|
||
|
||
## Required Development Workflow
|
||
|
||
Before making changes:
|
||
|
||
1. Confirm the current Git branch and working-tree state.
|
||
2. Identify any pre-existing modified/untracked files and do not alter them unless they are explicitly part of the task.
|
||
3. Inspect the relevant source files.
|
||
4. Identify existing services, providers, models, repositories, database helpers, and tests.
|
||
5. Search for all production callers before replacing or removing an implementation.
|
||
6. Do not duplicate existing functionality.
|
||
7. Make the smallest safe change necessary.
|
||
8. Preserve existing public interfaces unless the task explicitly requires a change.
|
||
9. Add or update tests for behavioral changes.
|
||
10. Run the relevant focused tests first when appropriate.
|
||
11. Run the complete test suite.
|
||
12. Run static analysis.
|
||
13. Build the debug APK for changes that can affect production compilation/runtime wiring.
|
||
14. Report exactly what changed and what verification passed.
|
||
15. Do not commit unless explicitly authorized.
|
||
|
||
If the requested change conflicts with an existing architectural contract, stop and report the conflict before broadening scope.
|
||
|
||
## Telemetry Freeze Boundary
|
||
|
||
The following subsystem is FROZEN unless the task explicitly requires modification and the user authorizes that change:
|
||
|
||
* TelemetryService
|
||
* SensorFusionService
|
||
* RideStateMachine telemetry/motion semantics
|
||
|
||
Changes to RideStateMachine that are unrelated to telemetry semantics may be permitted when explicitly required by the task, but existing ride lifecycle behavior must be preserved unless the task specifically authorizes otherwise.
|
||
|
||
### TelemetryService
|
||
|
||
Authoritative telemetry acquisition runs at 20 Hz / 50 ms.
|
||
|
||
Do not:
|
||
|
||
* change acquisition cadence
|
||
* introduce competing telemetry clocks
|
||
* duplicate sensor acquisition
|
||
* bypass the authoritative telemetry pipeline
|
||
* introduce UI-driven polling of sensors
|
||
|
||
All consumers must use the existing telemetry architecture.
|
||
|
||
### SensorFusionService
|
||
|
||
Sensor fusion is authoritative for derived orientation and lean data.
|
||
|
||
Do not introduce an independent lean-angle calculation without explicit architectural justification and regression tests.
|
||
|
||
### RideStateMachine
|
||
|
||
Preserve existing movement, crash, lifecycle, interrupted-ride recovery, and state-transition semantics.
|
||
|
||
The 3.0 MPH moving gate and kickstand isolation behavior are architectural contracts unless explicitly changed by the user.
|
||
|
||
Ride lifecycle changes must include regression coverage.
|
||
|
||
## Database Freeze Boundary
|
||
|
||
AppDatabase is currently Schema 7.
|
||
|
||
Do not modify database schema, migrations, event semantics, or persistence behavior casually.
|
||
|
||
Any schema change MUST include:
|
||
|
||
* an explicit schema-version decision
|
||
* migration logic where required
|
||
* migration tests
|
||
* backward-compatibility consideration
|
||
* verification against existing ride datasets
|
||
* consideration for legacy/null data
|
||
|
||
Never delete, destructively migrate, or rewrite historical ride data during normal feature development.
|
||
|
||
Use existing database helpers where available instead of duplicating raw insert/update behavior.
|
||
|
||
Stable ride identity (`cloudRideId`) is part of the persistence contract. Do not regenerate or replace an existing ride identity.
|
||
|
||
## Cloud / Offline Sync Architecture
|
||
|
||
MotorSignal uses an offline-first cloud synchronization architecture.
|
||
|
||
The authoritative automatic completed-ride synchronization path is:
|
||
|
||
RideStateMachine
|
||
→ syncObserverProvider
|
||
→ SyncManager
|
||
→ SyncOutbox
|
||
→ FirebaseSyncProvider
|
||
→ Cloudflare R2
|
||
→ Firestore
|
||
|
||
Do not introduce another automatic ride-upload queue or bypass SyncManager/SyncOutbox for normal completed-ride synchronization.
|
||
|
||
### SyncManager / SyncOutbox
|
||
|
||
SyncManager and SyncOutbox are authoritative for durable automatic cloud synchronization.
|
||
|
||
Preserve:
|
||
|
||
* durable queued work
|
||
* retry behavior
|
||
* authentication-required state
|
||
* restart recovery
|
||
* duplicate suppression
|
||
* account scoping
|
||
* offline operation
|
||
|
||
Do not replace durable queueing with an in-memory-only queue.
|
||
|
||
### FirebaseSyncProvider
|
||
|
||
FirebaseSyncProvider is the authoritative MotorCloud upload implementation.
|
||
|
||
Normal cloud synchronization must preserve:
|
||
|
||
* stable cloudRideId
|
||
* R2 telemetry-bundle identity
|
||
* Firestore ride identity
|
||
* retry/idempotency behavior
|
||
|
||
Legacy compatibility or explicit developer-export services must not become competing automatic synchronization paths.
|
||
|
||
### GitHub Sync / Export
|
||
|
||
GitHub-related upload/export functionality may remain for explicit developer or compatibility workflows.
|
||
|
||
Do not route normal automatic completed-ride synchronization through a legacy GitHubSyncService queue.
|
||
|
||
## Performance Data
|
||
|
||
Performance timing data such as 0–60 and 0–100 results must remain associated with the ride that produced it when recorded during an active ride.
|
||
|
||
Do not silently discard or detach ride-specific performance data from cloud/export payloads.
|
||
|
||
Legacy standalone performance runs with no ride association must remain valid where supported by the existing design.
|
||
|
||
## Forensic / Export Freeze Boundary
|
||
|
||
FieldTestExportService is authoritative for forensic exports.
|
||
|
||
Preserve:
|
||
|
||
* CSV schema
|
||
* JSON session schema 1
|
||
* GPX export
|
||
* timestamp semantics
|
||
* event ordering
|
||
* sub-second telemetry fidelity
|
||
|
||
Feature or UI work must not silently alter exported historical data.
|
||
|
||
Any intentional export-schema change must be explicitly authorized and versioned appropriately.
|
||
|
||
## Authentication
|
||
|
||
Authentication must not block local ride recording.
|
||
|
||
Preserve offline/local functionality when:
|
||
|
||
* signed out
|
||
* Firebase is unavailable
|
||
* network is unavailable
|
||
|
||
Do not make cloud authentication a prerequisite for collecting or storing local ride data unless explicitly required.
|
||
|
||
Anonymous/authentication transition behavior must not cause ride loss.
|
||
|
||
## State Management
|
||
|
||
Follow the project's existing Riverpod architecture.
|
||
|
||
Do not introduce another state-management framework.
|
||
|
||
Prefer existing providers and services over creating parallel state containers.
|
||
|
||
Be careful with provider lifecycle and `autoDispose` behavior for long-lived services, observers, synchronization, and ride-state listeners.
|
||
|
||
## UI Development
|
||
|
||
UI features must consume existing domain/application services.
|
||
|
||
Do not place telemetry acquisition, persistence, sensor fusion, synchronization, or substantial business logic directly inside widgets.
|
||
|
||
Support both portrait and landscape layouts where applicable.
|
||
|
||
Do not make UI refresh frequency drive telemetry or persistence frequency.
|
||
|
||
## Testing
|
||
|
||
Every behavioral change requires appropriate automated coverage.
|
||
|
||
Prefer behavioral tests over source-text assertions when practical.
|
||
|
||
Before completion, run:
|
||
|
||
```text
|
||
flutter test
|
||
flutter analyze
|
||
flutter build apk --debug
|
||
```
|
||
|
||
Focused tests may be run first during development.
|
||
|
||
A task is NOT considered complete if:
|
||
|
||
* tests fail
|
||
* analysis introduces new errors
|
||
* new warnings are introduced without justification
|
||
* the debug APK no longer builds when the task can affect compilation/runtime wiring
|
||
* existing regression datasets change unexpectedly
|
||
|
||
Pre-existing known warnings/info may remain if they are outside task scope, but they must be reported accurately.
|
||
|
||
Never claim physical motorcycle/device validation was performed unless it actually occurred.
|
||
|
||
## Git Safety
|
||
|
||
Never:
|
||
|
||
* reset unrelated work
|
||
* force-push
|
||
* rewrite history
|
||
* rebase unless explicitly requested
|
||
* delete branches
|
||
* delete tags
|
||
* discard pre-existing user changes
|
||
* stage unrelated files
|
||
* commit unless explicitly authorized
|
||
|
||
Create or verify a checkpoint before significant architectural changes.
|
||
|
||
If the working tree is dirty before a task:
|
||
|
||
1. identify the pre-existing files
|
||
2. preserve them
|
||
3. do not include them in task changes
|
||
4. clearly separate them in the final report
|
||
|
||
Use per-command Git safe-directory overrides when necessary rather than changing global Git configuration unless explicitly requested.
|
||
|
||
## Dependency / Toolchain Safety
|
||
|
||
Do not perform broad dependency or toolchain upgrades to solve a narrow problem.
|
||
|
||
Prefer the smallest compatible dependency change.
|
||
|
||
Do not run broad package upgrades such as `flutter pub upgrade` unless explicitly required.
|
||
|
||
When changing dependencies:
|
||
|
||
* identify the exact reason
|
||
* inspect lockfile impact
|
||
* report exact version changes
|
||
* verify tests, analysis, and APK build
|
||
|
||
Do not raise Android compileSdk, targetSdk, AGP, Gradle, Kotlin, or Java versions merely to satisfy one package without first investigating a narrower compatible solution.
|
||
|
||
## Documentation Accuracy
|
||
|
||
Treat documentation as guidance, not proof of current production behavior.
|
||
|
||
When documentation conflicts with production code:
|
||
|
||
1. verify behavior from source/tests
|
||
2. preserve the correct production behavior
|
||
3. report stale documentation
|
||
4. update documentation only if it is within task scope
|
||
|
||
Do not silently rely on stale schema versions, timing values, provider wiring, or architecture descriptions.
|
||
|
||
## Agent Behavior
|
||
|
||
Investigate before modifying.
|
||
|
||
Prefer surgical patches over broad rewrites.
|
||
|
||
Do not "fix" unrelated problems discovered during a task.
|
||
|
||
Do not silently expand scope.
|
||
|
||
Do not claim validation that was not actually performed.
|
||
|
||
Separate confirmed defects from suspected risks.
|
||
|
||
If an architectural conflict is discovered, stop and report it rather than silently changing a frozen subsystem.
|
||
|
||
When a task explicitly says STOP after reporting, do not proceed into the next stage.
|