400 lines
24 KiB
Markdown
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.
|