AutoForge/prompts/Step-06.md

274 lines
17 KiB
Markdown

# Step-06 - Imperial-default metric/imperial display units
## STEP IDENTIFIER
Step-06. Corrected Step-05/05A/05B was accepted on 2026-10-29.
This is the sole active implementation assignment. Recording/replay is Step-07
and remains blocked until this work is accepted.
## STEP TITLE
Use one shared metric/Imperial (US) presentation preference, defaulting to imperial,
while preserving SI calculations and exact raw/source data.
## OBJECTIVE
One user outcome: current human-facing measurements use the selected unit system
consistently, without changing the vehicle model, source or physical gauge range.
One primary new contract: a shared locally remembered display preference and
pure, validated presentation conversion boundary.
Read [STATE.md](STATE.md), the dated owner decision in [ROADMAP.md](ROADMAP.md),
[live dashboard contracts](../docs/live-dashboard.md) and
[WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md). Build the frozen case matrix
before coding, self-review after the first green run, write
`prompts/Step-06-Report.md`, and STOP.
## ARCHITECTURAL CONTEXT
Keep the nine-project .NET 10 modular monolith and sole MAUI Client. Components
remains generic with no AutoForge project reference. Application may own a small
display-unit feature/pure conversion and preference port; UI owns presentation/
interaction, and Client supplies real local MAUI preference storage/composition.
An equally simple existing-boundary arrangement is acceptable without duplicated
conversion logic. No new project, package, host or units/settings framework.
Use existing MAUI storage primitives, not new dependencies. Portable tests use
an explicitly isolated store behind the same port; the native host must not
silently fall back to an in-memory implementation. All source/tests stay under
`src`, tests under `src/tests`.
## CURRENT IMPLEMENTATION STATE
Accepted dashboard behavior includes real static-v1/dynamic-v2 signal reads,
zero-to-eight immutable definitions with exact source-unit binding, one session
acquisition owner, independent quality/range and explicit stale/error states.
The worker reports a clean nine-project Release build, 134 unit + 91 integration
passes (225 total, zero failed/skipped) and native baseline recheck.
The orchestrator did not run those commands.
Relevant existing surfaces:
- [MainLayout](../src/AutoForge.UI/Layout/MainLayout.razor): shared shell/navigation.
- [DiagnosticsPage](../src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticsPage.razor):
human-readable signals and separate raw trace.
- [SimulationPage](../src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor):
scenario target summaries, decoded telemetry and raw configuration JSON.
- [LiveDashboardPanel](../src/AutoForge.UI/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardPanel.razor):
values, editor bounds and source/sample context.
- [LiveDashboardAcquisition](../src/AutoForge.Application/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardAcquisition.cs):
canonical definitions/source values/states; not a new physics or conversion owner.
- [MauiProgram](../src/AutoForge.Client/MauiProgram.cs): native DI/composition.
There is no shared unit preference/conversion implementation yet. Reinspect Git,
existing tests/helpers and real source-unit metadata before editing; preserve
dirty work, accepted behavior and all historical reports.
## REQUIRED IMPLEMENTATION
### Frozen contract matrix
| ID | Input/precondition | Required result |
|---|---|---|
| C-01 | No saved preference; any route/culture | Imperial (US), Road-speed presentation by default; shared accessible control is visible before a session opens. No ambient region chooses the default. |
| C-02 | Known source units and representative conversion vectors below | Correct finite forward/inverse result within 1e-9 absolute target units for these vectors; consistent value/unit text. RPM/V/ratio/count/gear/boolean remain unchanged. |
| C-03 | Actual speed 20.1168 m/s, source bounds 0..40.2336 m/s | Imperial Road: 45 mph, bounds 0..90; Imperial Engineering: 66 ft/s, 0..132; Metric Road: 72.42048 km/h, 0..144.84096; Metric Engineering: source m/s. All retain 50% geometry and identical source bounds/state/context. |
| C-04 | At least 20 system/speed-mode toggles and rerenders on a bound paused session | Canonical definitions/source snapshots/configuration/time/step/request counts and owner stay unchanged; no drift or extra wire request/physics action. |
| C-05 | Gauge range editor in display units; valid/invalid saves; unedited Save | Convert edited bounds once to source units and validate atomically. 32..212 degF becomes 0..100 degC. Unedited saves/toggles retain original canonical bounds exactly. Invalid/overflowing bounds preserve prior definitions/feed/source. |
| C-06 | Active unsaved editor draft while global units change | Draft keeps its captured input unit and numbers, visibly labeled until Save/Cancel; Save uses that unit. Other readouts update; new/reset editor uses current selection. Never reinterpret typed numbers under a new label. |
| C-07 | Pending/Unknown/Uncertain/Stale/Error/Stopped, low/high or missing values | Preserve source quality/range/freshness/reason/time; missing stays `--`, never zero. Conversion cannot turn stale/uncertain data Good or clamp the numeric value. |
| C-08 | Known unchanged units, unsupported units, invalid preference/value or non-finite conversion | Pass-through units stay exact. Unsupported units remain explicitly unconverted with source unit/notice, never relabeled. Invalid input/overflow yields a handled visible error/unavailable result, not fabricated data or invalid geometry. |
| C-09 | Valid stored selection; navigation/restart; corrupt/unreadable store; failed write | Valid choice restores across routes/restarts. Missing is documented default. Invalid/read failure is visible with clearly labeled Imperial/Road default, not claimed restored or silently overwritten. Failed selection save preserves previous active preference and shows error. |
| C-10 | Human readouts versus raw/config/source inspectors | Assigned readouts convert consistently; original payloads, source-unit values, JSON/import/export/fingerprint and raw context remain byte/value-identical and labeled source/SI. |
| C-11 | Numeric source 0.4 m/s with display precision 0 | Convert NumericValue before formatting: Imperial Road displays 1 mph, not 0 from parsing the feed's already-rounded text. Never chain conversions through formatted display values. |
| C-12 | Actual static/dynamic Application/UI/Client paths | Real ports, preference adapter, shared selector and generic gauge path operate together; native toggling/restart/close and original routes work without an oracle or parallel host. |
### A. Shared display preference and exact supported mappings
Expose Metric / Imperial (US) and Road / Engineering speed presentation through
one application-wide control, preferably in the existing shared shell.
Defaults are Imperial (US) + Road; ordinary vehicle speed therefore shows mph.
Engineering is the explicit ft/s option, not a second poller or per-gauge layout
system. Switching unit system keeps the selected speed style.
Use one immutable validated selection shared across routes and mounted panels.
Persist only this small local preference through existing platform primitives.
Missing data means first-use default. Invalid/unreadable saved state shows an
explicit preference error and clearly identified default; do not overwrite it
silently. A successful explicit selection can recover. Persist a proposed
selection before publishing it; save failure leaves the prior active selection.
Undefined enum/options must reject before any state/store mutation.
Do not silently substitute an in-memory native store.
Current required source-to-display mappings:
| Exact source unit | Metric display | Imperial (US) display |
|---|---|---|
| m/s | km/h for Road; m/s for Engineering | mph for Road; ft/s for Engineering |
| m | m | ft |
| kg | kg | lb |
| kg/s | kg/s | lb/h |
| N*m | N*m | lbf*ft |
| degC | degC | degF |
| m/s^2 | m/s^2 | ft/s^2 |
| rpm, V, ratio, count, gear, boolean | Same source unit | Same source unit |
Use exact definitions: 1 ft = 0.3048 m; 1 mile = 1609.344 m;
1 lb = 0.45359237 kg; 1 lbf = 4.4482216152605 N; 1 hour = 3600 s;
degF = degC * 9/5 + 32. Do not introduce UK gallons or fuel-volume/economy
conversion without sourced density. No additional unit families are assigned.
Representative independent vectors: 20.1168 m/s -> 45 mph -> 66 ft/s;
0.3048 m -> 1 ft; 0.45359237 kg -> 1 lb;
(0.45359237 / 3600) kg/s -> 1 lb/h;
1.3558179483314004 N*m -> 1 lbf*ft;
0/100/-40 degC -> 32/212/-40 degF;
0.3048 m/s^2 -> 1 ft/s^2. Test inverse mappings too.
Map actual exact source units, not labels, module roles or guessed signal aliases.
Unknown units are not errors in the original source: retain their source value/
unit with an explicit unconverted notice. Preserve source quality independently.
Reject non-finite input/output and overflow through a typed handled result/error;
never return a success-shaped zero.
### B. Canonical data stays unchanged; conversion is presentation only
Keep raw diagnostic values, DiagnosticSignal.Unit, configuration/export/import,
fingerprints, physics inputs/results and time in their existing source/SI units.
Keep DashboardGaugeDefinition.Unit and bounds as exact source-unit contracts.
Do not weaken source-unit matching to make an imperial display work.
Project a separate display value/unit/bounds from original finite numeric data,
then apply the existing 0..3 decimal precision once. Never parse DisplayValue,
mutate a signal/definition, convert a prior display result again or change
acquisition rate/ownership/model control in response to a preference.
Reuse source-computed range/quality and bar percentage unchanged. Temperature
offset conversion must preserve physical boundaries, not merely change the
value label. Bounds are converted for editor display and converted back only
for actual edits; preserve original canonical numbers on an unedited Save.
Validate finite ordered source span as well as display input before committing.
Display precision must not quantize canonical editor bounds.
Pin an active editor draft's unit when its binding/edit begins and label that
unit explicitly. Global changes must not reinterpret its text. Save parses in
the captured unit; Cancel/Reset/new draft adopts the current preference.
Changing binding starts a clearly labeled draft for the new actual source.
Missing/failed/unknown/stale/stopped values retain their established states,
reason and actual source/sample time. Preserve independent Uncertain low/high
status and actual out-of-range readings; only bar geometry stays clamped.
Subscribe/unsubscribe presentation notifications safely on the renderer
dispatcher; view disposal must not stop session acquisition.
### C. Wire all current relevant surfaces, not just gauges
Use the shared conversion path in dashboard numeric/bar values and range labels/
editor, diagnostics human-readable signal readings, simulation decoded-telemetry
rows and scenario target-speed summaries. Keep timing/percent/count fields
unchanged. Retain accessible unit/state/value descriptions and safe text.
Source metadata/inspectors must still expose the exact original value and unit.
Raw trace/payloads, protocol fields, profile facts and configuration JSON remain
source data, explicitly labeled as unaffected by display preference. Do not
attempt to convert arbitrary text/profile metadata or rewrite historical docs/
reports. The global control and any load/save error are visible without a session.
## FILES OR PROJECTS EXPECTED TO CHANGE
Focused Application/UI presentation/preference/conversion code, shared layout
and current host/panel wiring, a small real Client preference adapter/DI, unit/
integration tests and directly related docs/README.
Components remains generic; Core/Diagnostics/Simulation implementation/schema/
physics changes are not expected or authorized by this display-only work.
Only `prompts/Step-06-Report.md` under `prompts`.
## INTERFACE AND DEPENDENCY REQUIREMENTS
Keep all nine projects, current references and one Client. No new dependency,
host, global active-session registry or generic settings framework. Tests may
use an explicit isolated preference store, not mock away conversion/feed/session.
Client must use actual MAUI preference primitives through the portable boundary.
Preserve static v1/dynamic v2, strict wire/profile/config contracts, source/
run identity, partial discovery/verified clear and one acquisition/physics owner.
No new oracle, hardware capability, silent fallback or broad exception mask.
No workload/system restore/install/update/repair/rollback is authorized.
Preserve existing dirty work and protected/history files; no stage/commit/push
or destructive Git action.
## TESTING REQUIREMENTS
Map C-01..C-12 to meaningful named tests before handoff:
- Pure forward/inverse vectors with independently specified expected values,
temperature offset, true zero/negative boundaries, finite/overflow checks,
exact pass-through/unknown units and conversion-before-rounding.
- First-use versus restored/error preferences using the real shared service and
isolated store seam. Verify failed writes/invalid options are atomic; do not
treat an always-working mock store as persistence failure coverage.
- Controlled real-provider/rendered static and dynamic routes/panel: all speed
modes, values/bounds/accessibility, 20 toggles, canonical equality, preserved
quality/range/time, editor draft pinning/invalid saves and zero added reads/
unchanged paused model state. Count at the real wire boundary.
- Raw source/config export/fingerprint/trace values and bytes remain unchanged.
Keep meaningful existing 225-case regressions; map necessary presentation-only
assertion updates without deleting source/safety/error checks.
Run focused cases, then sequential full checks:
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
The complete build includes all nine projects and the real Windows Client.
No dependency install/restore absent a real missing-dependency failure.
Native smoke on the rebuilt Client: observe initial/default or restored selection
honestly; configure real static/dynamic gauges; toggle systems/speed styles and
compare source versus display; edit a range and switch with a draft open; check
scenario/telemetry readouts and raw SI JSON; pause and prove toggles do not step;
restart to verify the chosen preference; reset/close and check old routes.
Do not wipe shared preferences or unrelated user data. Preserve/restore only
exact task-owned preference values when needed for smoke cleanup. Distinguish
native observations from controlled storage-error/invalid-data proof.
## DOCUMENTATION REQUIREMENTS
Update README/index/architecture/build guide and live-dashboard/simulation usage:
Imperial (US) first use, Metric and Road/Engineering options, persistence/error
behavior, mappings/limits, source versus display, canonical editor/draft policy
and actual validation evidence. Mark Step-05/05A/05B accepted; Step-06 remains
pending orchestrator review. Recording/replay is Step-07 and not implemented.
## ACCEPTANCE CRITERIA
| ID | Criterion | Evidence |
|---|---|---|
| AC-01 | C-01/C-09 shared Imperial/Road default, persistence/restoration and explicit atomic failure behavior | Service/store/DI tests plus actual native adapter/restart evidence |
| AC-02 | C-02/C-03/C-08/C-11 exact supported conversions, safe unknown/invalid inputs and convert-before-rounding | Independent numeric vectors, inverse/finite checks and exact rendered units/values |
| AC-03 | C-04..C-07 stable canonical bounds, pinned drafts and unchanged acquisition/model/source states | Controlled real-provider/wire-count/source-equality and editor/render tests |
| AC-04 | C-10/C-12 all assigned current UI surfaces use the shared path; raw/source/config contracts unchanged | Real routes/panel/Client integration, raw bytes and accessible native smoke |
| AC-05 | 225 baseline cases preserved, meaningful new coverage, complete Release/native build and required smoke pass | Exact commands/exits/warnings/per-project counts; native versus controlled evidence |
| AC-06 | Frozen matrix/self-review/docs/README accurately describe implemented behavior and limitations | Case/test mapping, own source-path review after first green and documentation summary |
| AC-07 | Protected files/history/dependencies/manual workflow preserved; report saved and worker stops | Preservation review and `prompts/Step-06-Report.md` |
## OUT-OF-SCOPE WORK
Recording/replay, charts/layouts/dashboard persistence/schema, additional unit
families/fuel-volume/MPG, new clock/model/protocol/physics, calibration/AI/hardware,
new project/package/host and unrelated cleanup. No future assignment, agents,
automatic handoff, orchestration/shared-gate edit, stage, commit or push.
## REPORTING REQUIREMENTS
Create `prompts/Step-06-Report.md` entirely inside exactly one plain triple-backtick
fence, no language tag/outside text/nested fences. Include identifier/title/status,
implemented functions/files/interfaces, C-01..C-12/AC-01..AC-07 evidence with
named executed tests and exact vectors/tolerances, commands/exits/warnings/
per-project counts, native versus controlled coverage, docs/README, own source-
path self-review after the first green run, limitations/deviations/blockers and
preservation review. COMPLETE requires all assigned checks; otherwise report
INCOMPLETE/BLOCKED and the precise unmet criterion.
Save and STOP for manual orchestrator review. Do not begin Step-07.