373 lines
8.3 KiB
Markdown
373 lines
8.3 KiB
Markdown
# MotorSignal — GitHub Copilot Instructions
|
|
|
|
## Project
|
|
|
|
MotorSignal is a Flutter motorcycle telemetry application.
|
|
|
|
Treat telemetry, ride recording, performance timing, persistence, synchronization,
|
|
and safety-related presentation as production-sensitive systems.
|
|
|
|
Prefer small, evidence-based changes over broad refactors.
|
|
|
|
---
|
|
|
|
## Source of Truth
|
|
|
|
The protected `master` branch is the authoritative production baseline.
|
|
|
|
Do not:
|
|
|
|
- commit directly to `master`
|
|
- force-push
|
|
- bypass repository rules or required CI
|
|
- rewrite published history
|
|
- modify unrelated files
|
|
- silently change database schemas
|
|
- silently change telemetry semantics
|
|
|
|
All implementation work should use a short-lived branch and pull request.
|
|
|
|
---
|
|
|
|
## Investigate Before Changing Code
|
|
|
|
Before proposing or implementing a change:
|
|
|
|
1. Locate the existing implementation.
|
|
2. Trace the relevant data flow.
|
|
3. Inspect existing tests.
|
|
4. Identify established invariants and compatibility requirements.
|
|
5. Determine the smallest safe change.
|
|
|
|
Do not assume a feature is missing merely because its implementation is not immediately obvious.
|
|
|
|
Prefer extending existing architecture over creating parallel implementations.
|
|
|
|
---
|
|
|
|
## Preserve Known-Good Behavior
|
|
|
|
A fix for one subsystem must not silently alter unrelated behavior.
|
|
|
|
Pay particular attention to:
|
|
|
|
- telemetry cadence
|
|
- GNSS freshness
|
|
- ride distance
|
|
- top speed
|
|
- performance timing
|
|
- lean/bank calculations
|
|
- G-force calculations
|
|
- heading
|
|
- ride persistence
|
|
- cloud/offline synchronization
|
|
- dashboard presentation
|
|
- field logging
|
|
|
|
If behavior must intentionally change, make the change explicit and add or update tests.
|
|
|
|
---
|
|
|
|
## Telemetry Architecture
|
|
|
|
MotorSignal has a single authoritative telemetry pipeline.
|
|
|
|
Important invariants:
|
|
|
|
- GNSS input is approximately 10 Hz.
|
|
- Authoritative telemetry output is 20 Hz / 50 ms.
|
|
- Do not introduce a competing telemetry pipeline.
|
|
- Do not create additional independent sensor-fusion paths.
|
|
- Preserve raw telemetry evidence.
|
|
- Derived facts must only be produced from evidence that satisfies their validity requirements.
|
|
|
|
Sensor or GNSS wrappers must not make old evidence appear new.
|
|
|
|
---
|
|
|
|
## GNSS Freshness
|
|
|
|
GNSS freshness is a canonical MotorSignal invariant.
|
|
|
|
The current boundary is:
|
|
|
|
`gpsAgeMs <= 4000`
|
|
|
|
Therefore:
|
|
|
|
- 3999 ms = fresh
|
|
- 4000 ms = fresh
|
|
- 4001 ms = stale
|
|
|
|
Do not change this boundary without an explicit task requiring it.
|
|
|
|
Fresh GPS requires valid coordinates.
|
|
|
|
Coordinates must:
|
|
|
|
- exist
|
|
- be finite
|
|
- be within valid latitude/longitude ranges
|
|
|
|
Repeated telemetry frames containing the same underlying GPS fix must not refresh the GNSS freshness watchdog.
|
|
|
|
---
|
|
|
|
## Stale GPS Behavior
|
|
|
|
Never present stale GPS-derived information as current evidence.
|
|
|
|
Expected behavior includes:
|
|
|
|
- stale speed presentation uses `--` rather than a frozen speed or false `0`
|
|
- derived ride metrics reject stale GPS evidence where appropriate
|
|
- performance timing must not launch from stale evidence
|
|
- GPS loss during active performance timing must follow the established abort behavior
|
|
- recovery from an outage must not create catch-up distance
|
|
- heading falls back to the established compass path when GPS course evidence is stale, absent, or unsuitable
|
|
- maps may retain last-known coordinates only when clearly presented as stale/last-known
|
|
- stale GPS must not be presented as an active GPS fix
|
|
|
|
Preserve these semantics unless an explicit requirement changes them.
|
|
|
|
---
|
|
|
|
## Performance Timing
|
|
|
|
Performance timing is evidence-sensitive.
|
|
|
|
Do not allow stale GPS speed to:
|
|
|
|
- arm a timer
|
|
- launch a timer
|
|
- continue a timing run as though GPS were current
|
|
|
|
When a READY timer loses valid speed evidence, preserve the established disarm behavior.
|
|
|
|
Moving GPS recovery must not automatically launch a previously armed run.
|
|
|
|
Fresh stationary evidence is required to re-arm where required by the existing state machine.
|
|
|
|
Preserve normal fresh-evidence launch and interpolation behavior.
|
|
|
|
---
|
|
|
|
## Ride Metrics
|
|
|
|
Derived ride statistics must remain truthful.
|
|
|
|
Review freshness and validity before modifying calculations involving:
|
|
|
|
- distance
|
|
- top speed
|
|
- moving time
|
|
- stopped time
|
|
- acceleration
|
|
- braking
|
|
- performance runs
|
|
- elevation
|
|
- high-speed events
|
|
- heading
|
|
|
|
Do not substitute missing/stale evidence with fabricated values merely to keep the UI populated.
|
|
|
|
---
|
|
|
|
## Persistence
|
|
|
|
MotorSignal currently uses Drift schema version 7.
|
|
|
|
Do not:
|
|
|
|
- increment the schema version
|
|
- add a migration
|
|
- modify persisted schema semantics
|
|
- regenerate schema-related production behavior
|
|
|
|
unless the task explicitly requires a database change.
|
|
|
|
Any schema change requires deliberate migration planning and compatibility validation.
|
|
|
|
---
|
|
|
|
## Cloud and Offline Sync
|
|
|
|
Do not change synchronization, authentication, ownership, or offline-queue behavior as a side effect of unrelated work.
|
|
|
|
Preserve existing:
|
|
|
|
- local persistence
|
|
- offline behavior
|
|
- ownership rules
|
|
- sync semantics
|
|
- retry behavior
|
|
|
|
Changes to these systems require explicit scope and dedicated validation.
|
|
|
|
---
|
|
|
|
## UI Truthfulness
|
|
|
|
Prefer unavailable or stale states over misleading values.
|
|
|
|
Examples:
|
|
|
|
- `--` is preferable to a fabricated numeric value.
|
|
- `LAST KNOWN LOCATION` is preferable to presenting stale coordinates as live.
|
|
- `NO GPS` / equivalent established state is preferable to falsely indicating a current fix.
|
|
|
|
UI changes must preserve the semantic distinction between:
|
|
|
|
- current
|
|
- stale
|
|
- unavailable
|
|
- unsupported
|
|
- error
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
Every behavioral change should have focused regression coverage when practical.
|
|
|
|
For bug fixes:
|
|
|
|
1. reproduce or encode the failure
|
|
2. make the smallest correction
|
|
3. prove the corrected behavior
|
|
4. verify nearby compatibility behavior
|
|
|
|
Pay particular attention to boundary tests.
|
|
|
|
For GNSS freshness, preserve explicit coverage around:
|
|
|
|
- 3999 ms
|
|
- 4000 ms
|
|
- 4001 ms
|
|
|
|
Do not weaken or delete tests merely to make a change pass.
|
|
|
|
---
|
|
|
|
## Validation
|
|
|
|
Before declaring implementation complete, run the relevant focused tests.
|
|
|
|
For substantial Flutter changes, also run:
|
|
|
|
`flutter analyze`
|
|
|
|
and the appropriate regression/full test suite when practical.
|
|
|
|
Check diff hygiene with:
|
|
|
|
`git diff --check`
|
|
|
|
Do not claim a test, analyzer, build, or CI result that was not actually executed.
|
|
|
|
If validation cannot be run, state that explicitly.
|
|
|
|
---
|
|
|
|
## GitHub Pull Requests
|
|
|
|
Pull requests targeting `master` must satisfy repository rules.
|
|
|
|
Required CI currently includes:
|
|
|
|
- Analyze, test and debug build
|
|
- Firestore ownership rules
|
|
- Website build and regression tests
|
|
- Waze relay tests
|
|
- Backend API tests
|
|
|
|
Do not attempt to work around a failing required check.
|
|
|
|
Investigate the failure and determine whether it is caused by the proposed change.
|
|
|
|
---
|
|
|
|
## Code Review
|
|
|
|
When reviewing MotorSignal changes, prioritize:
|
|
|
|
1. correctness
|
|
2. telemetry truthfulness
|
|
3. regression risk
|
|
4. data integrity
|
|
5. persistence compatibility
|
|
6. synchronization compatibility
|
|
7. safety-related presentation
|
|
8. tests
|
|
9. maintainability
|
|
10. style
|
|
|
|
Identify concrete defects rather than speculative rewrites.
|
|
|
|
When reporting an issue, explain:
|
|
|
|
- the affected file/code path
|
|
- the triggering condition
|
|
- the resulting incorrect behavior
|
|
- why it matters
|
|
- the smallest reasonable correction
|
|
|
|
Do not request broad refactors unless they are necessary to resolve a demonstrated problem.
|
|
|
|
---
|
|
|
|
## Scope Discipline
|
|
|
|
Stay within the requested task.
|
|
|
|
Do not opportunistically:
|
|
|
|
- upgrade dependencies
|
|
- reformat unrelated files
|
|
- rename unrelated APIs
|
|
- reorganize directories
|
|
- rewrite stable architecture
|
|
- introduce new frameworks
|
|
- change CI
|
|
- change authentication
|
|
- change database schemas
|
|
|
|
unless explicitly required.
|
|
|
|
If a separate problem is discovered, report it separately instead of silently expanding scope.
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
Never commit:
|
|
|
|
- API keys
|
|
- tokens
|
|
- passwords
|
|
- signing credentials
|
|
- private certificates
|
|
- production secrets
|
|
|
|
Do not weaken authentication, authorization, ownership rules, TLS, or secret handling to make development easier.
|
|
|
|
---
|
|
|
|
## Completion Standard
|
|
|
|
A MotorSignal task is not complete merely because the code compiles.
|
|
|
|
Completion should establish:
|
|
|
|
- requested behavior implemented
|
|
- known-good behavior preserved
|
|
- relevant tests passing
|
|
- analyzer/build validation appropriate to the change
|
|
- clean diff
|
|
- no unrelated modifications
|
|
- PR created from a dedicated branch
|
|
- required CI passing
|
|
- review findings resolved
|
|
|
|
When evidence is incomplete, report the uncertainty rather than assuming success.
|