AutoForge/prompts/Step-01A.md

400 lines
24 KiB
Markdown

# Step-01A - Single-shell MAUI/RCL and vertical-slice foundation
## STEP IDENTIFIER
Step-01A, an owner-directed architectural correction to accepted Step-01.
This is the sole active assignment. Step-02 is unexecuted and NOT authorized.
## STEP TITLE
Preserve the accepted foundation while establishing one thin MAUI Blazor Hybrid
Client, two purposeful Razor Component Libraries, and feature-oriented application
organization.
## OBJECTIVE
Deliver a minimal but working Windows-first .NET 10 application foundation:
`AutoForge.Client -> AutoForge.UI -> AutoForge.Components`
Client hosts the complete application UI through BlazorWebView and composes
application services in-process. Application use cases follow Vertical Slice
Architecture within a modular monolith. Preserve domain behavior, useful source,
configuration and all accepted regression coverage.
Implement only this correction, build/test the actual targets, record evidence in
`prompts/Step-01A-Report.md`, and STOP. Do not begin Step-02.
## ARCHITECTURAL CONTEXT AND AUTHORITY
The owner's 2026-10-28 architectural realignment supersedes previous dual-shell
requirements and the plan to defer all host/RCL work until Step-05.
- Sole initial application executable: **AutoForge.Client**, a .NET 10 MAUI Blazor
Hybrid application, initially Windows.
- **AutoForge.UI**: .NET 10 RCL containing the complete application UI, including
routing, pages, navigation, layouts, feature presentation and interaction flows.
- **AutoForge.Components**: .NET 10 RCL for generic reusable components/controls.
- Client is thin: native startup/configuration, lifecycle, BlazorWebView,
dependency injection and platform services. No feature implementations inside it.
- No standalone Blazor WebAssembly shell, separate AutoForge.Web/AutoForge.Maui
hosts, Blazor Server substitute or initial backend executable is required.
- Application, simulation, diagnostics, calibration and AI services can execute
in-process. Additional hosts/processes need a concrete requirement and approval.
- Application features use cohesive vertical slices, not generic technical layers,
artificial manager/repository abstractions or mandatory mediator boilerplate.
- Reusable engines/protocols/domain capabilities remain independent of UI and
their coordinating application slices; do not force every library to reference
Application or create every planned subsystem now.
Read [ROADMAP.md](ROADMAP.md), [STATE.md](STATE.md), the original
[Step-01](Step-01.md) and [report](Step-01-Report.md), and current technical docs.
Old host descriptions in those historical files are superseded by this correction.
Do not alter historical assignments/reports or execute the held [Step-02](Step-02.md).
## CURRENT IMPLEMENTATION STATE
Actual inspection found only these projects in [AutoForge.slnx](../src/AutoForge.slnx):
| Project | Current responsibility / references |
|---|---|
| `src/AutoForge.Core` | net10.0 immutable execution-target kind/descriptor; no project or package dependencies |
| `src/AutoForge.Application` | net10.0 target resolution, typed failures and eager DI registration; references Core and DI abstractions |
| `src/tests/AutoForge.UnitTests` | net10.0 real Core/Application invariants; references Core/Application |
| `src/tests/AutoForge.IntegrationTests` | net10.0 real target-selection DI/container composition; references Core/Application |
No Client, UI, Components, Web or Maui project exists. There are no current Razor
pages/components to relocate or old hosts to delete. Do not invent migration work
or recreate the accepted libraries.
Existing Application code is under `ExecutionTargets`. The Core descriptor is
sealed and validated; the resolver snapshots registrations, uses ordinal
case-insensitive IDs and rejects missing/unknown/duplicate/mismatched selections.
The DI extension validates eagerly and rejects repeated registration.
Production contains no connected/available provider implementation.
The accepted worker report records SDK 10.0.402, runtime 10.0.13 on Windows x64,
successful Release build with zero warnings/errors and 54 passing cases:
35 unit, 19 integration, zero failed/skipped. These are previous worker results,
not new correction verification or orchestrator runtime execution.
Existing configuration includes a stable same-feature-band SDK pin, nullable
references, warnings as errors, central package versions and repository-local
nuget.org feed. Preserve these conventions and the working VSTest/xUnit stack.
MAUI/Windows/WebView2 prerequisites have NOT been verified.
The worktree contains accepted unstaged/uncommitted implementation. Preserve it,
any concurrent changes, Git metadata and the three top-level project directories
`docs`, `src`, `prompts`. No root tests/artifacts or nested repository.
## REQUIRED IMPLEMENTATION
### 1. Inspect prerequisites and scope before editing
- Inspect Git status, instructions, solution, source/tests, configuration and docs.
Reconcile differences from this snapshot without discarding unrelated work.
- Inspect installed .NET SDK, MAUI workloads/templates, supported Windows target
framework/Windows SDK and desktop/WebView2 prerequisites. Record actual versions
and exact commands. Do not infer native readiness from the accepted headless build.
- Use compatible .NET 10 templates/project tooling where available. Verify actual
package/API/template capabilities before adding references or code.
- Do not install major SDKs/workloads/Windows components/drivers without
authorization. If missing, report precise prerequisites and native checks as
BLOCKED/NOT EXECUTED, not PASSED. Preserve the architecture; do not substitute a
browser/server host or quietly exclude Client from the required solution.
- Continue independent RCL/application/test work where feasible, but do not claim
overall completion if mandatory native build/startup evidence remains blocked.
### 2. Add the three UI projects to the existing solution
| Project | Required foundation |
|---|---|
| `src/AutoForge.Client/AutoForge.Client.csproj` | .NET 10 MAUI Blazor Hybrid executable; initially Windows only, using an actual supported Windows TFM and verified MAUI tooling |
| `src/AutoForge.UI/AutoForge.UI.csproj` | net10.0 Razor Component Library for the entire routed application UI |
| `src/AutoForge.Components/AutoForge.Components.csproj` | net10.0 Razor Component Library for reusable vehicle-independent UI |
Expected solution total: seven projects, preserving the existing four. Do not
scaffold Android/iOS/Mac targets merely because a template includes them; additional
platforms require a later need and verification.
Use the framework's actual BlazorWebView bootstrap, root selector/component,
host page, resources, CSS and RCL static asset conventions. Client may contain
necessary MAUI App/MainPage/platform bootstrap and the host HTML, but application
Router, routes, layouts, navigation and feature pages must be in UI.
Ensure assets resolve from both RCLs and the root component loads the UI assembly.
Do not leave a Router pointed at an empty Client assembly.
Remove unused template Counter/Weather/sample services or relocate only genuinely
useful content. Do not create a second executable, separate backend, startup HTTP
server, browser host or fake platform fallback. Test runner executables are not
application shells.
### 3. Establish meaningful minimal RCL behavior
Provide only a small foundation UI, not future automotive features:
1. A foundation/home page and a minimal execution-target metadata selection page
in UI, with working navigation/layout and explicit unknown-route handling.
2. A generic reusable status/notification component in Components, used by the UI.
Give it a small useful parameter/state contract and test its actual rendered
behavior. Do not add placeholder gauges/charts that have no real data source.
3. The selection page invokes the existing application use case through DI,
requiring explicit provider identifier and target kind. Production registry
remains empty; display an honest unavailable/not-registered outcome.
4. Keep invalid-input/application errors visible to the user with specific handling,
not a broad catch, blank page, success-shaped fallback or hidden failure.
5. A selected metadata descriptor, if supplied in a synthetic headless test, must
never be labeled connected, hardware-capable, write-approved or programmable.
6. Keep application validation in the application/domain boundary. Razor code
contains presentation/input handling, not a duplicate resolver/business workflow.
The application must start without a vehicle, AI model, cloud account, backend or
native automotive driver. No synthetic production provider is to be registered
just to make the screen look connected.
### 4. Establish the vertical-slice foundation without rewriting behavior
Retain AutoForge.Application immediately: a real use case already exists there.
Organize the existing target-selection operation as a cohesive feature slice,
for example `Features/ExecutionTargets/SelectExecutionTarget`.
Keep its service/contract, errors and composition close to the use case as useful.
- Preserve validation, errors, exact descriptor identity, comparison semantics,
mutation isolation, duplicate handling, empty-registry behavior and no fallback.
- Moving files is sufficient if it establishes feature ownership; do not wrap
every method in requests/handlers or duplicate the resolver behind a new layer.
- Preserve public contracts/namespaces where practical. If a necessary rename
changes references, update all consumers/tests/docs coherently and explain it;
no speculative compatibility adapter is required.
- Keep target kinds/descriptors in reusable Core rather than dragging domain
contracts into UI, Client or an application-only request type.
- UI may use a `Features/Foundation` or `Features/ExecutionTargets` arrangement
for the two real presentation operations. Do not create empty Vehicles,
Diagnostics, Simulation, Calibration, Telemetry or AI feature directories.
- Document how future slices coordinate independently testable capabilities.
Do not implement those capabilities now.
- Do not add MediatR, generic repositories/managers, service locators, automatic
discovery or new infrastructure solely to demonstrate architecture.
### 5. Enforce project and composition boundaries
Required references:
- Client -> UI; Client -> Application as needed for composition.
- UI -> Components; UI -> Application/contracts and domain types as needed.
- Application -> Core, retaining its narrow infrastructure dependencies.
- Components -> no other AutoForge production project in this foundation.
Forbidden directions include Components -> UI/Client/Application, UI -> Client,
Core/Application -> UI/Client/Components, and production -> tests. No cycles.
Do not introduce a requirement for every capability library to depend on
Application. Future native adapters are composed by Client behind suitable ports.
Headless tests must exercise Components/UI/application features without referencing
or starting Client. The native shell must use the same application registration
and services tested headlessly, not a second fake implementation.
Review central package pins, RCL/MAUI references and shared build settings for
actual .NET 10 compatibility. Add only justified dependencies. Do not force
desktop-only settings or native targets onto Core/RCL/test projects, add a
server-only shared-framework requirement to MAUI by accident, suppress warnings
globally, or change SDK/test tooling just to conceal an integration failure.
## FILES OR PROJECTS EXPECTED TO CHANGE
- Add Client, UI and Components under `src`; update the existing solution.
- Move/reorganize the existing Application feature and update references only
where required, preserving Core and existing behavior.
- Extend the existing UnitTests/IntegrationTests with meaningful component,
application-UI integration and dependency-boundary coverage. Reference RCLs in
tests only as required; no new test project is expected.
- Update central package/build configuration only where justified by MAUI/RCL work.
- Update root README, documentation index, architecture and build/test guide.
- Add a superseding architecture ADR under `docs`, and mark affected old decisions
superseded while retaining their historical context.
- Under `prompts`, create/update only `Step-01A-Report.md`.
Do not change any assignment, ROADMAP, STATE, Step-01 report or held Step-02.
Do not modify/create `.github/copilot-instructions.md` or override instruction files.
Do not stage, commit, push, initialize Git, reset the repository or remove reports.
If an unexpected obsolete host appears due to concurrent work, inspect and preserve
its useful content before a narrowly justified migration; do not delete broad trees.
## INTERFACE AND DEPENDENCY REQUIREMENTS
The primary direction remains Client -> UI -> Components; UI invokes application
feature contracts, Client composes them in-process, and Core stays independent.
RCL/application testing is independent of MAUI. A backend is not required for
separation of concerns.
Use normal DI and small direct services/handlers. No UI or application feature may
acquire arbitrary hardware write authority. Preserve the distinction between
simulation, replay and physical target metadata. No operation execution is added.
Future deterministic simulation remains AI-independent with an isolated oracle.
Existing local-first behavior and all hardware safety/prohibited-operation
restrictions remain in force.
## TESTING REQUIREMENTS
### Unit and regression tests
Preserve all 35 existing unit and 19 integration cases/invariants. Add substantive
tests for any changed/new feature behavior and reusable component rendering.
If moving names/files, map the original cases to their preserved equivalents.
Do not delete assertions or introduce required skipped tests to report a green run.
For the generic component, verify meaningful rendered state/content changes and
safe text rendering, not merely that the type exists or DI can construct it.
Use framework-supported headless rendering or a narrowly justified compatible
test tool; verify its actual API rather than adding packages speculatively.
### Integration and architecture tests
Exercise the actual UI/Application/Components implementation without Client:
1. Render the foundation UI and verify it uses the reusable component and actual
application service contract through DI.
2. Exercise metadata selection with explicit synthetic registrations in tests:
exact selection, empty registry, invalid input and mismatched kind remain
truthful and visible; no connection/write-approval claim or fallback.
3. Verify application route ownership/navigation and unknown-route behavior in
the UI assembly, with native route smoke evidence below. Do not count only
string searches or file-existence assertions as UI integration.
4. Verify the actual project graph has Client -> UI -> Components, no reverse/
forbidden references or cycles, one intended production executable, and no
required obsolete WebAssembly/web/backend host.
5. Verify the feature registration used by Client is the real tested registration;
preserve eager validation, immutable snapshots and explicit target selection.
Graph/source-policy assertions supplement, not replace, actual Razor compilation,
rendered-behavior integration, native build and native startup evidence.
Do not mock the feature/component under test or relabel metadata tests as hardware
or native application integration.
### Required build and test execution
Record actual SDK/workload/Windows SDK/WebView2 versions and exact commands.
Build Core, Application, both RCLs and tests with the existing Release conventions.
Build the native Client for its actual Windows TFM, then the applicable complete
solution targets when prerequisites permit.
Use repository-root PowerShell entry points, verified for the actual project
configuration:
- Restore affected projects/solution after necessary manifest changes.
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
when the single Windows Client target and installed workloads permit.
- Build Client directly with its actual Windows TFM if needed to identify the
native failure precisely. Do not apply a Windows `--framework` override to all
portable projects in the solution.
- Run both existing test projects explicitly in Release using the existing
VSTest runner; also run any appropriate full-solution regression command that
actually supports the configured native target.
If native workloads are missing, build/test independent projects directly and
report those successful results separately. Do not use a partial solution filter
or an excluded Client to claim the complete solution passed. Do not claim a MAUI
build from successful Core/RCL/test compilation alone.
### Native startup smoke verification
Where desktop execution is available, launch the actual Client, verify that
BlazorWebView displays the UI RCL, both foundation routes/navigation and shared
component assets work, and the empty-provider outcome is visible without a backend,
vehicle, driver or model. Record launch method, observed UI behavior, errors and
supporting evidence. A running process or a screenshot of a native blank window
does not prove the RCL loaded.
If startup is impossible due to the desktop session, WebView2 or another exact
prerequisite, mark native smoke BLOCKED/NOT EXECUTED and describe the limitation
separately from compile/headless tests. Do not mark COMPLETE while required native
build or smoke evidence remains missing; report BLOCKED/INCOMPLETE for review.
Only the orchestrator can accept the step and unblock subsequent work.
## DOCUMENTATION REQUIREMENTS
Update the root README and technical documents to describe actual results:
- One Client executable, UI RCL, Components RCL, in-process modular monolith and
primary dependency graph, with a Mermaid diagram where useful.
- Exactly which routes/pages/components and application slice exist, and their
metadata-only limitations; no simulation/diagnostics/AI feature claims.
- Feature ownership and future slice organization without mandatory mediator,
generic technical-layer boilerplate or speculative projects.
- Current SDK/workload/Windows/WebView2 prerequisites, native startup method,
portable versus native build/test commands and honest platform limitations.
- Implemented, in-progress and planned scope, Step-01 historical acceptance and
Step-01A worker completion versus pending orchestrator acceptance.
Create a focused ADR recording the owner's corrected single-shell/RCL/VSA
decision. Supersede the old dual-shell/deferred-host portions of ADR-0001 without
erasing the valid foundation decisions or falsifying its history. Remove obsolete
host requirements from active README/architecture/build descriptions. Historical
reports/assignments remain unchanged and explicitly historical, not active design.
Update `docs/README.md` to link actual documents; no empty placeholder documents.
## ACCEPTANCE CRITERIA
| ID | Criterion | Required evidence |
|---|---|---|
| AC-01 | Accepted Core/Application behavior, useful code/configuration, all 54 prior cases and history preserved; exact repository layout/manual workflow maintained | Git review, case mapping and regression outcomes |
| AC-02 | Existing solution includes the four original projects plus Client/UI/Components; Client is the only initial application executable and a genuine .NET 10 MAUI Blazor Hybrid target | Solution/project graph, actual native configuration/build evidence |
| AC-03 | Client hosts UI via BlazorWebView; application routes/pages/layout/navigation reside in UI, generic component in Components; no shell feature implementations | Source paths, Razor compilation, rendered tests and native smoke evidence |
| AC-04 | Required Client -> UI -> Components references and allowed application composition exist, without reverse/forbidden references or cycles | Architecture assertions and inspected actual project graph |
| AC-05 | Existing Application is retained and target selection is feature-organized with unchanged explicit/no-fallback validation and errors; no unnecessary mediator/layers/future slices | Feature/source paths, regression tests and design explanation |
| AC-06 | Real headless component and UI/application integration tests verify rendered behavior and errors independently of MAUI | Actual tests, assertions, commands and nonzero discovered/passed counts |
| AC-07 | Affected projects, RCLs, native Windows Client and applicable complete solution targets build; both test suites/regressions pass | Exact commands, targets, versions, exit outcomes, warnings and per-project counts |
| AC-08 | Native Client loads UI/navigation/shared assets and honest empty-provider behavior without a backend/model/vehicle | Native launch observations/evidence; exact blocker if execution unavailable, never a false pass |
| AC-09 | README, technical docs/index and superseding ADR match one shell, two RCLs, VSA/modular monolith and actual verification limits | Documentation paths and supersession/status summary |
| AC-10 | Correct report produced; assignments/state/roadmap/protected instructions and old reports preserved; worker stops without Step-02 execution | `prompts/Step-01A-Report.md`, preservation/scope review and explicit stop |
Map every criterion to PASSED, FAILED, NOT EXECUTED or BLOCKED with concrete
evidence. COMPLETE requires all required verification, including native evidence.
Missing workload/runtime prerequisites are real blockers, not permission to
replace architecture, suppress failures or start Step-02.
## OUT-OF-SCOPE WORK
Vehicle/profile implementation, module discovery/diagnostic protocols, simulation/
physics, telemetry acquisition/recording/replay, calibration editing/programming/
backups, AI inference/knowledge/research, driver integration, actual hardware
operations, future application features, additional executable hosts/backends,
new platforms, databases, containers, cloud services and automatic agent handoffs.
Do not implement every example slice/library/component listed in the product
vision. No emissions defeat, anti-theft bypass, mileage falsification or safety
disabling functionality is permitted.
## REPORTING REQUIREMENTS
Create `prompts/Step-01A-Report.md` entirely inside exactly one plain triple-backtick
code fence, without a language tag or content outside it. Use no nested fences.
Use the same copy-window format for the final chat report.
Include:
1. Step identifier/title and COMPLETE, INCOMPLETE or BLOCKED status.
2. Implemented functionality summary, distinct from future capabilities.
3. Files/projects created and modified; moves/removals with preservation rationale.
4. Actual project/reference graph, sole executable, application feature arrangement,
UI/component ownership, and architectural changes.
5. Unit tests created/modified and original-case preservation.
6. Integration/architecture tests created/modified and actual rendered/application
boundaries tested, distinct from native smoke.
7. SDK, workload, Windows SDK, WebView2, package and runner inspection/results.
8. Exact build/restore commands, targets, exit outcomes, warnings/errors and any
partial versus full-solution results.
9. Exact test commands/results and per-project discovered/passed/failed/skipped counts.
10. Native launch method, observed UI/navigation/assets/error behavior and evidence,
or exact missing prerequisites and unexecuted checks.
11. AC-01 through AC-10 evidence table.
12. Documentation changes, README changes and ADR supersession.
13. Known limitations, outstanding issues/blockers, corrected failures and any
failed/unexecuted verification.
14. Deviations and rationale; relevant recommendations for orchestrator review.
15. Protected assignment/report/orchestration preservation and final Git review.
Do not claim headless tests prove native integration or metadata proves operational
capability. Save the report and STOP. Do not modify orchestration files, regenerate
Step-02, begin profile work, invoke another agent, stage, commit or push.