344 lines
19 KiB
Markdown
344 lines
19 KiB
Markdown
# Step-01 - Repository and solution foundation
|
|
|
|
## STEP IDENTIFIER
|
|
|
|
Step-01. This is the only currently authorized implementation assignment.
|
|
|
|
## STEP TITLE
|
|
|
|
Establish the .NET 10 repository, headless application foundation, real tests,
|
|
and truthful developer documentation.
|
|
|
|
## OBJECTIVE
|
|
|
|
Create a small, coherent, buildable foundation for AutoForge. Deliver meaningful
|
|
cross-project behavior and passing unit/integration tests without implementing
|
|
vehicle simulation, diagnostics, AI, or hardware integration prematurely.
|
|
|
|
You are the WORKER in a separate VS Code instance sharing the repository.
|
|
Implement this assignment, verify it, write `prompts/Step-01-Report.md`, then STOP.
|
|
Do not invoke another agent, automate handoffs, or begin Step-02.
|
|
|
|
## ARCHITECTURAL CONTEXT
|
|
|
|
AutoForge is one local-first .NET 10/C# platform integrating deterministic vehicle
|
|
simulation, vehicle-wide diagnostics/calibration/telemetry, and local AI/knowledge.
|
|
See [ROADMAP.md](ROADMAP.md) and [STATE.md](STATE.md).
|
|
|
|
Required eventual UI hosts are standalone Blazor WebAssembly and Windows-first
|
|
.NET MAUI Blazor Hybrid, sharing reusable components and application-screens RCLs.
|
|
They are deliberately deferred to Step-05, not replaced by server-side Blazor.
|
|
|
|
The amendment supersedes the original charter's layout and naming:
|
|
|
|
- The only top-level project directories are `docs`, `src`, `prompts`.
|
|
- Root files and existing protected repository infrastructure are permitted.
|
|
- Application and automated test projects are all under `src`.
|
|
- The solution is `src/AutoForge.slnx`; test projects belong in `src/tests`.
|
|
- No root `tests`, root `artifacts`, or nested `AutoForge` directory.
|
|
- Communication files use `prompts/Step-XX.md` and `Step-XX-Report.md`.
|
|
- Corrective assignments use letters, for example `Step-01A.md`.
|
|
|
|
The orchestrator plans and reviews; you alone implement and execute builds/tests.
|
|
All handoffs remain manual. Do not modify the roadmap, state, assignments, or
|
|
protected Copilot instructions. Under `prompts`, create/update only this step's
|
|
report. Do not commit or push.
|
|
|
|
## CURRENT IMPLEMENTATION STATE
|
|
|
|
At orchestration inspection on 2026-10-28:
|
|
|
|
- The existing repository was clean on `main`, tracking `origin/main`.
|
|
- Only root `README.md` and `.gitignore` were tracked.
|
|
- There was no solution, application source, tests, or technical documentation.
|
|
- `.github/copilot-instructions.md` was absent. Leave it absent; if it appears
|
|
before execution, read and preserve it as protected read-only infrastructure.
|
|
- The orchestrator added only the roadmap, state, and this assignment.
|
|
- SDKs, workloads, templates, dependencies, and hardware were not inspected.
|
|
|
|
Recheck the worktree and applicable instructions before editing; preserve concurrent
|
|
unrelated changes. Do not assume the initial snapshot is still current.
|
|
|
|
## REQUIRED IMPLEMENTATION
|
|
|
|
### 1. Inspect prerequisites and preserve the repository
|
|
|
|
1. Inspect repository instructions, Git status, existing root files, and any
|
|
intervening changes. Do not run `git init` or destructive Git operations.
|
|
2. Inspect `dotnet --info`, `dotnet --list-sdks`, and the templates/tools required
|
|
for this assignment. Record the SDK/runtime and Windows architecture actually
|
|
used. There is no need to inspect or install MAUI workloads for this step.
|
|
3. Use an installed supported .NET 10 SDK and compatible maintained packages.
|
|
Verify package/framework compatibility before adding dependencies; do not
|
|
invent exact versions or APIs. A newer major SDK is not a silent substitute.
|
|
4. If .NET 10 is unavailable, report the exact prerequisite and mark the affected
|
|
work/checks BLOCKED. Do not install major SDKs/workloads/drivers without
|
|
authorization or retarget to an older framework.
|
|
5. Inspect manifests first; restore dependencies as needed for the chosen build.
|
|
Do not add containers, cloud services, native drivers, or model dependencies.
|
|
|
|
### 2. Establish the solution and build conventions
|
|
|
|
Create the required directories and these projects, using .NET templates and
|
|
solution/package tooling where appropriate:
|
|
|
|
| Path | Type and purpose |
|
|
|---|---|
|
|
| `src/AutoForge.slnx` | One primary solution containing all four projects |
|
|
| `src/AutoForge.Core/AutoForge.Core.csproj` | `net10.0` class library for platform-neutral foundational contracts/invariants |
|
|
| `src/AutoForge.Application/AutoForge.Application.csproj` | `net10.0` class library for application services; references Core |
|
|
| `src/tests/AutoForge.UnitTests/AutoForge.UnitTests.csproj` | `net10.0` real domain/application unit tests |
|
|
| `src/tests/AutoForge.IntegrationTests/AutoForge.IntegrationTests.csproj` | `net10.0` real cross-project/application-composition integration tests |
|
|
|
|
Both test projects may reference Core and Application. Production projects must
|
|
not reference test projects. Core must not reference Application or any platform,
|
|
UI, AI, hardware, or persistence implementation.
|
|
|
|
Establish:
|
|
|
|
- Nullable reference types and consistent modern C# conventions.
|
|
- Root `.editorconfig` and shared build settings such as `Directory.Build.props`
|
|
only where useful. Avoid redundant/conflicting settings.
|
|
- A `global.json` selecting the actual supported .NET 10 SDK with a documented
|
|
patch/feature-band policy that does not roll forward across major versions.
|
|
- One maintained test framework and compatible test SDK/runner packages shared
|
|
consistently by both test projects. Verify actual .NET 10 tooling compatibility;
|
|
do not mix incompatible test platforms or runners.
|
|
- Reproducible, documented restore/build/test entry points. Central package
|
|
management or lock files are optional only if they simplify this small solution.
|
|
- Existing ignore rules preserved, with narrow additions for uncovered build/test
|
|
output, local secrets, private captures, firmware, and model files as necessary.
|
|
Do not ignore source-controlled synthetic fixtures or the `prompts` directory.
|
|
- Generated outputs confined to ignored directories under `src` where practical;
|
|
no extra top-level project/output directories.
|
|
|
|
Do not add an application host or unused Simulation/Diagnostics/AI/Hardware/UI
|
|
assemblies now. Remove template placeholder classes/tests rather than presenting
|
|
them as functionality.
|
|
|
|
### 3. Implement a minimal explicit-target foundation
|
|
|
|
Provide a small genuine application use case that exercises Core and Application:
|
|
validation and resolution of an explicitly requested execution-target descriptor.
|
|
This is metadata selection only, not connection, discovery, or operation execution.
|
|
|
|
Required behavior:
|
|
|
|
1. A platform-neutral contract distinguishes Simulation, RecordedReplay, and
|
|
PhysicalHardware target kinds. Do not use a mutable global execution mode.
|
|
2. A target/provider descriptor carries a validated nonblank provider identifier
|
|
and an explicitly valid target kind. Define/document identifier comparison
|
|
semantics and reject undefined enum values if enums are used.
|
|
3. The application service resolves an explicitly requested provider identifier
|
|
and target kind against supplied registrations. It must not invent a default,
|
|
guess an absent kind, or silently substitute another target.
|
|
4. Reject missing/blank selection, unknown registration, identifier ambiguity,
|
|
invalid target kind, and provider/kind mismatch with actionable explicit
|
|
failures. Choose simple typed results or clear domain/application exceptions
|
|
consistently; do not swallow them or return success-shaped empty descriptors.
|
|
5. Detect duplicate or ambiguous registrations under the declared comparison rule.
|
|
Once registered/validated, caller mutation must not bypass these invariants.
|
|
6. Support ordinary dependency-injection composition of the application service.
|
|
Keep the required API small; use compatible Microsoft.Extensions abstractions
|
|
only where needed. Do not build a plugin framework or service locator.
|
|
7. Production registration contains no fake connected/available providers.
|
|
Empty registrations must yield an explicit unavailable/not-registered outcome.
|
|
Synthetic test descriptor registrations are permitted and clearly labeled.
|
|
8. Selecting a physical descriptor in a test grants no write authorization or
|
|
connection. Add no transport, driver, command sender, write operation, or
|
|
physical capability claim in this step.
|
|
|
|
The worker chooses clear names and local implementation details. This contract
|
|
creates the explicit-target boundary needed by later simulation/replay/hardware
|
|
providers; it is not permission to prebuild their protocols or execution engine.
|
|
|
|
## FILES OR PROJECTS EXPECTED TO CHANGE
|
|
|
|
- Create the solution, four projects, implementation and tests under `src`.
|
|
- Create useful documentation only under `docs`, including its index, architecture,
|
|
decisions, and testing/build guidance.
|
|
- Create root build/editor configuration files needed by this foundation.
|
|
- Preserve and update the existing root README and ignore file where appropriate.
|
|
- Create `prompts/Step-01-Report.md` only after implementation/verification, or to
|
|
document an explicit blocked/incomplete result.
|
|
|
|
No other `prompts` files may be changed. Do not modify/create
|
|
`.github/copilot-instructions.md` or alternative override instructions.
|
|
Do not create empty placeholder directories or documents for future features.
|
|
|
|
## INTERFACE AND DEPENDENCY REQUIREMENTS
|
|
|
|
- Core owns foundational value types and invariants without external infrastructure.
|
|
- Application depends inward on Core and exposes a narrow platform-neutral use case.
|
|
- Composition supplies registrations; source code must not hardcode a manufacturer,
|
|
vehicle model, native adapter, inference endpoint, or successful connection.
|
|
- No dependency on UI rendering, current wall-clock time, randomness, external
|
|
services, network access, native hardware, or a model for target selection/tests.
|
|
- Use clear validation and errors; logging must not expose secrets or private
|
|
identifiers. Do not add broad catches, silent fallback, or unnecessary casts.
|
|
- Preserve existing repository behavior/files and document any necessary deviation.
|
|
- Future application/UI paths must not gain privileged simulation-oracle access.
|
|
There is no oracle or simulator implementation to create in this step.
|
|
|
|
## TESTING REQUIREMENTS
|
|
|
|
Create actual behavior tests, not assertions about constants or dependency
|
|
existence masquerading as integration.
|
|
|
|
### Unit tests
|
|
|
|
Cover at least:
|
|
|
|
1. Valid descriptors for each of the three target kinds.
|
|
2. Null/empty/whitespace identifier rejection as applicable to the public API.
|
|
3. Undefined target kind and absent selection rejection.
|
|
4. Identifier comparison and duplicate/ambiguous registration rejection.
|
|
5. Successful exact descriptor resolution and explicit unknown-registration error.
|
|
6. Provider/kind mismatch rejection; no simulation-to-physical or other fallback.
|
|
7. Stable registry invariants despite mutation of caller-supplied collections,
|
|
if mutable inputs are accepted.
|
|
|
|
### Integration tests
|
|
|
|
Exercise real Application/Core behavior through the actual DI registration path:
|
|
|
|
1. Register synthetic metadata for different target kinds, resolve the application
|
|
service, request one explicitly, and verify exact descriptor identity/kind.
|
|
2. Verify an empty production-like registration set reports unavailable rather
|
|
than a connected/working provider or fallback.
|
|
3. Verify a mismatched physical/simulation request fails even when another provider
|
|
is registered. Selection alone cannot imply connection or write approval.
|
|
4. Verify duplicate registrations fail explicitly at the documented boundary.
|
|
|
|
Do not mock the application service under test or assert only that DI returns an
|
|
object. An in-memory metadata registry is sufficient; do not invent hardware
|
|
"integration" evidence. Integrations must use the same implementation as production.
|
|
|
|
### Required execution and evidence
|
|
|
|
From the repository root, use the actual supported runner and record exact
|
|
commands. The intended baseline, if compatible with the selected runner, is:
|
|
|
|
- `dotnet restore .\src\AutoForge.slnx`
|
|
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
|
|
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
|
|
|
|
Adapt runner-specific arguments only after verifying them and document why.
|
|
Run both test projects, confirm neither has zero discovered tests, and report
|
|
passed/failed/skipped counts separately. No necessary acceptance test may be
|
|
skipped while claiming complete. Resolve introduced build/test failures before
|
|
declaring success.
|
|
|
|
Record command exit results, actual SDK/framework/configuration, warnings,
|
|
counts and meaningful failure output. Keep durable text evidence in the report
|
|
and optionally reference ignored result files under `src`; a path to an
|
|
uncommitted ephemeral log is not the sole evidence.
|
|
|
|
Review Git status/diff before reporting; check for accidental files, secrets,
|
|
protected-file changes, scope drift, extra directories and untracked source.
|
|
Do not stage, commit, push, discard unrelated work, or run destructive cleanup.
|
|
|
|
## DOCUMENTATION REQUIREMENTS
|
|
|
|
Create useful technical documentation matching the actual implementation:
|
|
|
|
1. `docs/README.md` linking the documents that actually exist.
|
|
2. Architecture overview explaining the implemented project graph, Core/Application
|
|
responsibilities, target-selection use case and its error contract. Include a
|
|
Mermaid dependency diagram where it clarifies the design.
|
|
3. A concise architecture decision record covering the .NET 10/headless foundation,
|
|
inward dependencies, explicit-target/no-fallback rule, and staging both required
|
|
Blazor hosts/shared RCLs rather than substituting another architecture.
|
|
4. Build/testing guidance with exact prerequisites, SDK policy, commands, test
|
|
boundaries, runner choice, evidence locations and known limitations.
|
|
|
|
Make implemented versus planned behavior explicit. Document that a descriptor
|
|
selection neither connects to a vehicle nor authorizes any operation. Briefly
|
|
record the future read-only hardware boundary and AI-independent deterministic
|
|
simulation, without pretending those systems exist.
|
|
|
|
### Root README requirements
|
|
|
|
Preserve the existing product description while clearly separating IMPLEMENTED,
|
|
IN PROGRESS, and PLANNED. Include:
|
|
|
|
- Project name, product vision, major capabilities and architecture overview.
|
|
- .NET 10/C# technology and planned standalone WASM/MAUI/shared-RCL architecture.
|
|
- Actual repository layout, development prerequisites, restore/build/test commands.
|
|
- How to exercise the current headless foundation through its tests; explicitly
|
|
state that there is no interactive application startup command yet.
|
|
- Implemented target-selection behavior, current Step-01 status, planned next
|
|
capabilities, known limitations, and links to real detailed documentation.
|
|
|
|
Do not claim simulation, diagnostics, backups, AI, UI, or hardware programming is
|
|
implemented. Report whether and how the README changed.
|
|
|
|
## ACCEPTANCE CRITERIA
|
|
|
|
| ID | Criterion | Required evidence |
|
|
|---|---|---|
|
|
| AC-01 | Existing repository, history, unrelated work and protected infrastructure preserved; no Git initialization/commit/push | Status/diff summary and explicit protected-file check |
|
|
| AC-02 | Exactly `docs`, `src`, `prompts` as top-level project directories; tests under `src/tests`; no root tests/artifacts or nested repository | Actual layout listing; no placeholder directories |
|
|
| AC-03 | `src/AutoForge.slnx` contains all four projects, targeting `net10.0`, with the specified inward reference graph | Project/solution file paths and inspected reference graph |
|
|
| AC-04 | Supported installed .NET 10 SDK selection, nullable/editor/build conventions and maintained compatible test tooling | Environment output, config files, package/runner rationale |
|
|
| AC-05 | Explicit target descriptors and resolution enforce all stated invariants without defaults, substitution, or fake connections | Implementation paths and mapped behavior tests |
|
|
| AC-06 | Real DI-based integration tests exercise Application and Core, including empty/invalid/mismatched/duplicate cases | Test names/paths, commands, counts and outcomes |
|
|
| AC-07 | Full initial solution Release build and both unit/integration suites execute successfully; no required skipped or undiscovered tests | Exact commands, exit results, warnings, per-project counts |
|
|
| AC-08 | Documentation index, architecture, ADR, testing guidance and root README accurately distinguish implemented and planned scope | File list and documentation/README summary |
|
|
| AC-09 | No physical operation, AI/cloud dependency, host substitution, automatic handoff, or out-of-scope placeholder project | Dependency and Git review; explicit limitation statement |
|
|
| AC-10 | Complete evidence-bearing report created at the exact required path; worker stops without advancing | `prompts/Step-01-Report.md` with all sections below |
|
|
|
|
Map every criterion to PASSED, FAILED, NOT EXECUTED, or BLOCKED and explain the
|
|
evidence. Overall COMPLETE requires every criterion to be satisfied; if any
|
|
required verification cannot run, use BLOCKED or INCOMPLETE instead.
|
|
|
|
## OUT-OF-SCOPE WORK
|
|
|
|
- Vehicle profiles/calibration definitions, virtual modules, diagnostic protocols,
|
|
dynamics, telemetry, persistence, recordings, replay, and runbook execution.
|
|
- UI shells/RCLs, web servers, local hardware bridges, MAUI workloads or drivers.
|
|
- Real or simulated module programming; no physical writes or command services.
|
|
- AI inference/research, vector databases, model downloads/training, MCP, containers,
|
|
cloud services, and optional platform investigations.
|
|
- Automated inter-agent communication, watchers, polling, or next-step execution.
|
|
- Modifying orchestration state/roadmap/assignments or protected instructions.
|
|
- Any emissions defeat, anti-theft bypass, mileage falsification or safety disabling.
|
|
|
|
Do not repair unrelated pre-existing issues. If a necessary deviation affects
|
|
architecture or acceptance, record it explicitly; do not silently broaden scope.
|
|
|
|
## REPORTING REQUIREMENTS
|
|
|
|
Create `prompts/Step-01-Report.md`. The entire report must be inside exactly one
|
|
plain triple-backtick code fence with no language tag and no content outside it.
|
|
Use headings/tables/inline commands within that fence, without nested fences.
|
|
Use the same single-copy-window format for the final chat report.
|
|
|
|
Include all of:
|
|
|
|
1. Step identifier and title.
|
|
2. Completion status: COMPLETE, INCOMPLETE, or BLOCKED.
|
|
3. Implemented functionality summary, distinct from planned features.
|
|
4. Files created.
|
|
5. Files modified, including any pre-existing/concurrent changes left untouched.
|
|
6. Architectural changes, actual project/dependency graph and relevant decisions.
|
|
7. Unit tests created/modified, with behavior coverage.
|
|
8. Integration tests created/modified, with real boundary coverage.
|
|
9. Environment inspection and actual SDK/runtime/package/runner choices.
|
|
10. Exact build/restore commands and results, including warnings and exit results.
|
|
11. Exact test commands and results, including counts per project and skipped tests.
|
|
12. AC-01 through AC-10 verification table with concrete evidence.
|
|
13. Documentation changes.
|
|
14. Root README changes.
|
|
15. Known limitations.
|
|
16. Outstanding issues and blockers, including failed/unexecuted checks.
|
|
17. Deviations from this assignment and their rationale.
|
|
18. Relevant recommendations for the orchestrator's review and later assignment.
|
|
|
|
Use durable evidence, not just "all tests passed." Never report an unexecuted
|
|
check as passed or a failed/uncertain operation as successful.
|
|
|
|
After writing the report, STOP. Do not create Step-02, change the roadmap/state,
|
|
commit/push, invoke another agent, or begin another implementation step.
|
|
The user will manually return to the orchestrator for acceptance review.
|