AutoForge/prompts/Step-01.md

19 KiB

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 and 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.