AutoForge/prompts/Step-05.md

252 lines
15 KiB
Markdown

# Step-05 - First configurable numeric/bar live dashboard
## STEP IDENTIFIER
Step-05. Corrected Step-04/04A/04B were accepted on 2026-10-28.
This is the sole active implementation assignment.
## STEP TITLE
Display configurable numeric and bar gauges from one session-owned diagnostic
acquisition feed, with explicit missing/stale/uncertain/range states.
## OBJECTIVE
One user outcome: configure and observe a small live dashboard on an existing
explicitly opened static or dynamics diagnostic session.
One primary new behavioral contract: a shared session-bound acquisition owner,
independent of gauge visibility. Gauge configuration is validated in-memory data,
not a new persisted format or another application subsystem.
Read [WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md), apply the frozen matrix
below before coding, self-review after the first green run, write
`prompts/Step-05-Report.md`, and STOP for manual review.
## ARCHITECTURAL CONTEXT
Read [STATE.md](STATE.md), [architecture](../docs/architecture.md),
[protocol v1](../docs/synthetic-diagnostics-v1.md) and
[v2](../docs/synthetic-diagnostics-v2.md).
Keep all nine projects and one native MAUI Client. Components owns generic pure
UI controls and has no AutoForge project reference. Application owns feed/
configuration use cases using Diagnostics ports. UI owns composition/editor/
interaction. Client is DI/lifecycle only. No new host, project, package or
Application/UI dependency on Simulation implementation.
All source/tests remain under `src`, tests under `src/tests`. Root project
directories remain `docs`, `src`, `prompts`. Manual handoff/protected/history
rules in the shared gate remain mandatory.
## CURRENT IMPLEMENTATION STATE
Accepted features already provide:
- Exact profile/configuration/provider/session selection; static v1 and dynamics
v2 providers; validated identity/service discovery and actual encoded reads.
- DiagnosticSignal/SignalSnapshot values, units, quality, synthetic origin,
request time and v2 model/config/run context.
- Existing `/diagnostics` and `/simulation` workflows with owned ActiveSession,
explicit close/reset, actual telemetry reads and current-generation guards.
- StatusNotice and headless HtmlRenderer/real-DI integration tests.
Worker-reported baseline: clean complete nine-project Release build; 126 unit +
81 integration passes (207 total, zero failed/skipped), numerical gates and
native baseline smoke. No chart/dashboard acquisition service exists yet.
The orchestrator did not rerun those checks.
Reuse [DiagnosticSession](../src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs)
and current host feature view models. Do not duplicate profile/provider opening,
physics, protocol/version or virtual-clock behavior. Inspect actual code/Git
before editing and preserve existing dirty work and historical reports.
## REQUIRED IMPLEMENTATION
### Frozen contract matrix
These are the acceptance outcomes, not examples to replace with weaker proxies.
| ID | Input/precondition | Required result |
|---|---|---|
| C-01 | Good finite 850 rpm; display 0..1000, decimals 0 | Numeric displays 850 with rpm; bar projects 85%; actual source/context retained. Legitimate numeric zero displays zero, not missing. |
| C-02 | Finite value below/above display range, e.g. -10 or 1100 | Preserve actual numeric value; clamp bar geometry only to 0/100%, with explicit low/high indication. No fabricated in-range reading. |
| C-03 | Null/missing/non-numeric value or Unknown quality; finite Uncertain quality | Unknown/unavailable shows `--` and reason, not zero/current bar. Uncertain finite data may display only with an explicit warning state, never Good. |
| C-04 | Invalid definition/range/precision/binding/unit/count | Typed visible rejection before mutation; previous valid definitions/source/feed stay intact. Include finite-span overflow as well as NaN/infinity/min>=max. |
| C-05 | Repeated Start on same running feed; Start while Stop drains; retry after Stop | First is idempotent with one owner; draining Start rejects before mutation; Stop cancels/awaits cleanup; retry starts one owner. |
| C-06 | Source close/reset/replacement or late reply from old generation | Old owner/resources stop; old values do not appear in the new context. Pending new data is explicit; no global active-source fallback or stale publication. |
| C-07 | Gauges hidden/removed/re-rendered/disposed while source monitoring remains open | Acquisition continues independently. Widget disposal only removes its subscription; explicit monitoring stop/source close/owning scope disposal ends acquisition. |
| C-08 | Last good value followed by read failure; no previous value; later recovery/stop | Retain a value only as clearly last-known Stale with failure/source time. With no valid prior value show Error/`--`. Recovery restores correct state. Stopped data is not labeled live. |
| C-09 | Multiple gauges bind signals on the same module; controlled polling; paused dynamics | One read.signals per eligible module per dashboard poll, not per gauge/render. Polling does not advance physics; v1 static and v2 dynamic source/time semantics are preserved. |
| C-10 | Real host UI configure/edit/hide/stop/reset/close and current error cases | Same actual Application feed/validated definitions/pure components are used. No mock live data, oracle read, shell restructuring or hidden owner. |
### A. Small validated in-memory dashboard
Support zero to eight gauges using numeric or horizontal-bar type, a stable
unique gauge ID, label, explicit module/signal binding, exact reported unit,
finite minimum/maximum with finite positive span, and integer decimal precision
0..3. Copy definitions; reject duplicate IDs/undefined kinds/invalid fields.
Use documented identifier comparison rules consistent with signal/module IDs.
Bindings are selected explicitly from actually read, identity-verified session
signal metadata, not role names or guessed RPM aliases. Reject unknown module/
signal or requested-unit mismatch during configuration. Runtime loss/change of a
previously valid signal becomes an explicit data state, not a silent rebind.
No unit conversion is assigned; display the exact source unit.
Editing/rejecting/removing a gauge cannot mutate model inputs, run state, source
selection or other valid definitions. Empty dashboards are valid and do not stop
an explicitly running acquisition owner.
### B. One real session-owned acquisition feed
Add a focused Application feature under Telemetry/LiveDashboard or equally clear
ownership. Bind to the existing explicit DiagnosticSession and immutable context:
session/target/profile plus available config/run identity. No global current
vehicle/provider registry or competing open workflow.
Use one owned loop per bound dashboard/session. Repeated acquisition of that same
owner must share it or reject duplicate ownership before mutation; repeated Start
on the owner is idempotent as C-05 states. Do not create a poll loop per component.
On explicit monitoring Start, obtain verified service/endpoint/signal availability
through actual discovery/read ports, then publish an initial snapshot. Subsequent
cycles wait 250 ms after the preceding completed cycle; no overlapping polls.
Use a small injectable scheduler/time seam for deterministic tests, not the
physics pacer or a new clock project. This interval is not a real-time guarantee
and is not a new user-configurable rate in this slice.
Group reads by eligible module. Acquire independently of current widget count/
visibility and publish immutable latest snapshots only; no unbounded history,
recording, interpolation or replay. Preserve per-response source/quality/request
time and model step/time; do not claim simultaneous capture for running modules.
Freshness here is cycle-based, not a new wall-age SLA: initial/pending reads,
last completed data, failed-cycle Stale/Error and Stopped are explicit. Show
source/sample context and refresh state. No silent zeros or invented timestamps.
Tie ownership to source/feature lifetime, not the Razor widget. Coordinate actual
close/reset/disposal so the worker and any pending read are cancelled/drained;
source lifetime integration may be added narrowly if needed. Prevent old
generations from publishing after stop/restart/rebind. Do not wait under a gate
needed by cleanup. Monitoring never starts/stops/steps physics.
### C. Pure reusable controls and real UI
Add generic numeric/bar renderers in Components. They consume presentation data,
not DiagnosticSession, Simulation, native drivers or acquisition services.
Use accessible labels/value/state descriptions and safe text rendering.
Handle invalid public presentation parameters explicitly, never healthy NaN/
infinite width or an unhandled user-input rendering failure.
Compose a reusable dashboard panel/editor in UI within the existing `/diagnostics`
and `/simulation` session workflows. The host/session owns the feed; mounting/
hiding widgets does not own it. Provide explicit Start/Stop monitoring, add/edit/
remove gauge controls and a simple fixed layout. Preserve existing controls/routes.
Label synthetic/static/dynamic origin and selected source clearly. Missing,
uncertain, stale/error, out-of-range and stopped states must be visually/textually
distinct. Last-known values may remain only with their stale/stopped label and
source time; they are not current measurements or real vehicle evidence.
## FILES OR PROJECTS EXPECTED TO CHANGE
- Application dashboard definitions/validation/feed use cases and minimal session-
lifetime integration necessary for owner cleanup.
- Components numeric/bar renderers and UI dashboard composition/host wiring.
- Client DI only if needed; existing unit/integration tests and related docs.
- Only `prompts/Step-05-Report.md` under `prompts`.
No persisted dashboard format, new project/dependency, provider/protocol/model/
clock redesign, extra host or physics change is assigned. Do not edit assignments,
ROADMAP, STATE, shared gate or historical reports. No protected-instruction edit,
staging/commit/push, destructive Git or unrelated worktree cleanup.
## INTERFACE AND DEPENDENCY REQUIREMENTS
Keep the nine-project graph, Components independence, Application/Diagnostics
boundary and private simulation oracle. Preserve wire/profile schemas, exact
source/config binding, verified clear, partial identities and clock ownership.
Only identity-verified endpoints that implement read.signals are polled; unknown/
restricted/unavailable metadata does not fabricate support.
Use typed visible errors and validate-before-mutate. No broad catches, fake data,
target fallback, direct engine access, real hardware or workload/system action.
Keep the shared quality gate's frozen-criteria and self-review requirements.
## TESTING REQUIREMENTS
Implement C-01..C-10 as relevant component, validation, feed, actual DI and rendered
tests before handoff. In particular:
- Assert exact 850/85%/unit/precision and true-zero rendering, out-of-range geometry
versus actual value, unknown/uncertain/stale/error/stopped state and safe text.
- Prove invalid definitions (including non-finite span) are rejected atomically.
- Drive the real feed with controlled ticks/barriers through duplicate start,
pending stop/restart, close/reset/new source and delayed old response.
- Count actual wire reads for shared bindings and hidden/zero widgets. Preserve
model step/time while the dynamics source is paused. No sleeps/polling or
arbitrary elapsed-time thresholds as correctness proof.
- Exercise both actual static v1 and dynamics v2 sessions; inject data loss/
negative responses below the feature boundary, not a mock dashboard service.
- Render the real panel/editor against actual Application DI and ensure component
disposal does not stop source acquisition while explicit close does.
Preserve the 207-case baseline (126 unit, 81 integration); map intentional UI
assertion changes without deleting safety/error checks. Run focused tests, then
sequential full Release build/test using the existing commands/runner:
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
No new dependency/restore is expected absent a real missing-dependency failure.
The complete build includes the real Windows Client/all nine projects.
Native smoke: open an actual static session and configure numeric/bar views of
its signal; verify live/stop/hide/range behavior. Repeat with a real dynamics
session, pause/step/read to observe correct value/time and prove monitoring alone
does not step it; test invalid range/binding, stop/reset/close and old routes.
Distinguish native observations from controlled fault/lifecycle proof.
## DOCUMENTATION REQUIREMENTS
Update README/index/architecture/build guide and concise dashboard usage/contracts:
input limits/binding/unit policy, state semantics, cycle-based freshness, one
owner/visibility/lifetime rules, v1/v2 sample context and actual evidence.
Mark Step-04/04A/04B accepted, Step-05 worker status pending review, and retain
historical reports. No dashboard persistence, charts or conversions are claimed.
## ACCEPTANCE CRITERIA
| ID | Criterion | Evidence |
|---|---|---|
| AC-01 | C-01..C-04 exact rendering/projection/state and atomic definition rules | Component/validation matrix and actual UI failures |
| AC-02 | C-05..C-08 one-owner, cleanup/generation/visibility and state rules hold | Controlled feed/service/rendered lifecycle tests |
| AC-03 | C-09 actual static/dynamic wire acquisition is grouped and independent of renders/physics | Per-module frame counts, true source/time and paused-step assertions |
| AC-04 | C-10 real host workflow uses pure Components and actual Application feed without scope expansion | Reference/source review and rendered/native evidence |
| AC-05 | Existing 207 cases/invariants, full nine-project Release/native build and required smoke pass | Exact commands, warnings, per-project counts and coverage distinction |
| AC-06 | Contract/evidence matrix, self-review, docs/README and limitations match implementation | Report mapping and documentation summary |
| AC-07 | Protected/history/manual workflow preserved; complete report saved and worker stops | Preservation/Git review and `prompts/Step-05-Report.md` |
Use PASSED, FAILED, NOT EXECUTED or BLOCKED precisely. COMPLETE requires assigned
checks; optional future preferences are not acceptance requirements.
## OUT-OF-SCOPE WORK
Dashboard JSON/storage/persistence, charts/time series, analog/SVG clusters,
drag/drop/layout designers, new unit conversion/rate/freshness policies, recording/
replay/comparison, model/protocol/physics changes, hardware/calibration/AI,
new projects/packages/hosts/platforms and unrelated cleanup.
## REPORTING REQUIREMENTS
Create `prompts/Step-05-Report.md` entirely inside exactly one plain triple-backtick
code fence, without language tag or outside content. Use no nested fences.
Include identifier/title/status, implemented functions, files created/modified,
architecture/interfaces, unit/integration and C-01..C-10/AC-01..AC-07 evidence,
exact build/test results with warnings/exits/per-project counts, native versus
controlled observations, worker self-review, docs/README, limitations/outstanding
issues/deviations/recommendations and preservation review.
Save and STOP. No orchestration/shared-gate edit, Step-06, agents, automatic
handoff, stage, commit or push.