AutoForge/prompts/Step-01A.md

24 KiB

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, STATE.md, the original Step-01 and report, 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.

CURRENT IMPLEMENTATION STATE

Actual inspection found only these projects in 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.