Initial. B4 Step 1 Execution

This commit is contained in:
GAJ3T 2026-10-28 08:53:14 -04:00
parent 715c84a936
commit 6bbc3959c3
3 changed files with 812 additions and 0 deletions

364
prompts/ROADMAP.md Normal file
View File

@ -0,0 +1,364 @@
# AutoForge development roadmap
## Status and authority
- Initialized: 2026-10-28.
- Current phase: initial orchestration; no application functionality exists yet.
- Active assignment: [Step-01](Step-01.md), ready for manual worker execution.
- Last accepted step: none.
- Current state and handoff: [STATE.md](STATE.md).
- Authority: the supplied master charter, as superseded by the repository
structure and agent handoff amendment. The amendment's naming and layout win.
- This document describes the intended architecture and future capabilities.
Planned projects, interfaces, milestones, and demonstrations are not claims of
implemented or verified functionality.
## Product goals
Build one extensible, local-first .NET 10 platform combining:
1. Deterministic vehicle simulation and virtual electronic control modules.
2. Diagnostics, telemetry, visualization, calibration management, and eventually
explicitly authorized module-specific programming.
3. Local AI planning and vehicle knowledge with independently validated runbooks.
Support arbitrary vehicle module inventories, not a fixed ECU/TCU list. Vehicle,
module, protocol, and calibration definitions must be data-driven and applicable
to specific hardware/software identities. Unknown or restricted capabilities
must remain explicit. Simulation, manual diagnostics, manual calibration work,
and tests must function without an AI service or cloud account.
Preserve the complete product vision through incremental, integrated vertical
slices. Do not finish one major subsystem in isolation before integrating it.
## Repository and manual workflow
The only top-level **project directories** are `docs`, `src`, and `prompts`.
Necessary root configuration files are allowed. Preserve Git metadata and
existing protected repository infrastructure; these are not project directories.
- All application projects and automated test projects belong under `src`.
- The primary solution will be `src/AutoForge.slnx`.
- Tests belong under `src/tests`, never a top-level `tests` directory.
- Generated test evidence, if retained, belongs in an ignored location under
`src`, not a top-level `artifacts` directory.
- Technical/product documentation belongs under `docs`.
- All file-based orchestrator/worker communication belongs under `prompts`.
- Do not create a nested `AutoForge` repository directory.
- Do not initialize a repository, automatically commit, or push.
- `.github/copilot-instructions.md`, if present, is read-only. If absent, do not
create it or an alternative intended to override it.
The orchestrator writes assignments and maintains this roadmap and state. The
worker alone writes application code, tests, technical documentation, and the
root README; executes builds/tests; and writes the corresponding report.
The orchestrator reviews the assignment, report, relevant source and tests, Git
changes, documentation, and actual reported command evidence. It does not execute
application builds/tests or implement fixes.
Handoffs are manual. No agent invocation, messaging automation, polling, watchers,
automatic prompt pickup, or unattended progression is permitted.
Assignments use `Step-01.md`, `Step-02.md`, etc. Reports use
`Step-01-Report.md`, `Step-02-Report.md`, etc. Corrective assignments use the
original number plus sequential uppercase letters, for example `Step-01A.md`
and `Step-01A-Report.md`, then `Step-01B.md`. Accept all necessary corrections
before assigning the next major step. Do not use the superseded numeric-dot
prompt/report naming convention.
## Architecture baseline
### Initial physical projects
Step-01 creates only four projects:
| Project | Responsibility | Allowed project references |
|---|---|---|
| `src/AutoForge.Core` | Platform-neutral foundational value types, invariants, and shared contracts | None |
| `src/AutoForge.Application` | Use-case coordination and application-facing services; initially explicit execution-target selection | Core |
| `src/tests/AutoForge.UnitTests` | Focused domain and application behavior tests | Core, Application |
| `src/tests/AutoForge.IntegrationTests` | Real application composition and cross-project behavior, without hardware/cloud | Core, Application |
This is deliberately a headless foundation. It must include real behavior and
tests, not empty assemblies or always-passing test placeholders. Application
shells arrive in Step-05 when working services can support them. This is staging,
not a substitution for either required shell.
### Planned boundaries, added only when used
| Boundary / likely project | Responsibilities and dependency direction |
|---|---|
| Core | Vehicle/module identities, capability states, provenance, units, versioned domain schemas; no UI, inference, transport implementation, or storage dependencies |
| Application | Diagnostic use cases, provider selection, calibration/runbook validation, approval, execution coordination, application ports; depends on Core |
| Diagnostics | Addressing, protocol/service handling, decoding, transport interfaces and communication trace; depends on Core and only needed Application contracts |
| Simulation | Virtual clock, coupled dynamics, virtual modules, simulated transport, deterministic faults; depends on shared contracts/Diagnostics, never on an LLM or UI |
| Persistence / telemetry infrastructure | Recording, replay, calibration/version storage, audit and knowledge repositories implementing application ports; introduce a project only when justified |
| AI / knowledge integration | Provider adapters, research and retrieval, schema-constrained planning; consumes restricted application query/planning ports, never hardware-driver access |
| Hardware adapter | Verified OBDX Pro GT/native integration behind shared diagnostic ports; Windows-specific code isolated from browser/shared UI |
| Shared UI components RCL | Data-driven gauges, charts, controls, layouts; consumes platform-neutral view models/contracts |
| Shared application screens RCL | Profile, diagnostics, simulation, calibration, replay, knowledge, AI, settings screens; composes components and calls application services |
| Standalone Blazor WebAssembly shell | Browser composition, routing and shared RCL hosting; no native driver references |
| MAUI Blazor Hybrid shell | Windows-first native composition hosting the same RCLs; platform services injected at the host boundary |
| Local .NET hardware service | Browser-to-native bridge when needed; explicit authorization and local exposure controls, not a required cloud backend |
These are logical responsibilities, not an instruction to create all assemblies
now. Keep related responsibilities together until an actual dependency or
platform boundary justifies extraction. Avoid premature microservices.
Planned dependency flow:
```mermaid
flowchart TD
Browser[Standalone Blazor WebAssembly] --> Screens[Shared screens RCL]
Hybrid[MAUI Blazor Hybrid] --> Screens
Screens --> Components[Shared components RCL]
Screens --> App[Application use cases and ports]
AI[Local AI and knowledge adapters] --> App
App --> Core[Core domain and contracts]
Sim[Simulation and virtual modules] --> Ports[Diagnostic and application ports]
Store[Recording and persistence adapters] --> Ports
Native[Native hardware adapter] --> Ports
Bridge[Local hardware service] --> App
Ports --> Core
App --> Ports
```
Ports in the diagram are logical contracts, not an additional required project.
Composition roots wire implementations. Dependency injection does not grant AI
or UI unrestricted programming authority.
### Invariants
1. **Explicit target:** simulation, recorded replay, and physical hardware are
distinct execution targets. Never infer, silently switch, or fall back between
them. Descriptor selection is not a connection or a successful operation.
2. **Layered diagnostics:** separate physical transport, vehicle network,
addressing, diagnostic protocol/services, decoding, calibration operations,
and application commands. Generic OBD-II does not imply access to all modules.
3. **Determinism:** fixed virtual time and reproducible inputs/seeds drive
simulation. Do not use wall-clock timing, rendering frequency, or LLM sensor
generation as the physics source. Timeouts/faults must be reproducible.
4. **Physical consistency:** RPM, gear ratio, speed, torque/load, fuel use, and
temperatures derive from coupled state within documented model assumptions.
Simplified predictions must not be marketed as validated real-world results.
5. **Independent oracle:** tests may inspect simulation ground truth through an
isolated test boundary; application and AI paths may not bypass diagnostics
to access it.
6. **Truthful data:** distinguish vehicle configuration, firmware, calibration,
calibration definitions, diagnostic captures, and telemetry recordings.
Version persisted schemas; preserve originals and applicability information.
7. **Telemetry lineage:** preserve source/module identity, units, sampling, data
quality, raw/decoded/derived/estimated/simulated classification, and both
simulation and capture time as applicable.
8. **Separate operations:** live simulation, recorded-session replay, and
deterministic scenario re-execution are not interchangeable. Comparisons
identify source, configuration, scenario, confidence, and limitations.
9. **Safe execution:** AI proposes versioned logical runbooks. A deterministic
validator/executor checks identity, applicability, limits, dependencies,
approvals, preconditions, backup, readback, unrelated-data preservation,
diagnostics, and supported recovery.
10. **Three verifications:** backup verification, programming verification, and
functional verification are distinct. Missing, interrupted, or uncertain
verification cannot be reported as success.
11. **Evidence and authority:** VERIFIED, UNVERIFIED, INFERRED, and SYNTHETIC
information retain sources, applicability, confidence, verification status,
and limitations. Similarity search is not authority for offsets or exact
compatibility. Unknown calibration locations remain unknown.
12. **Physical gates:** first hardware integration is read-only. Capability
discovery, transport selection, simulation approval, or an AI recommendation
never authorizes physical writes. Physical programming requires separate
explicit authorization and module-specific controlled evidence.
13. **Prohibited functionality:** no emissions defeat, anti-theft bypass, mileage
falsification, safety-system disabling, or unrestricted safety-critical writes.
14. **Local-first and replaceable AI:** allow local OpenAI-compatible endpoints,
initially considering LM Studio and Qwen3.5-9B around a practical 16 GB model
memory budget. Verify actual availability, licensing, context, and memory use
at implementation time; do not make a model or fine-tuning a core dependency.
15. **Honest errors and support:** no fake providers, silent defaults, fabricated
manufacturer protocol behavior, fabricated backups, or unverified platform
claims. Protect vehicle identifiers, recordings, model assets, and local
service endpoints. Never commit secrets or private runtime datasets.
## Milestones and acceptance gates
All milestones below are unimplemented. Only Step-01 is currently assigned.
Dependencies indicate acceptance prerequisites, not permission for automatic
handoff. Later assignments refine these scopes using actual implementation
evidence; they must not silently discard required capabilities.
| Step | Milestone | Depends on | Status | Principal acceptance gate |
|---|---|---|---|---|
| 01 | Repository and solution foundation | Repository inspection | READY FOR WORKER | Four-project .NET 10 foundation, explicit target-selection behavior, real unit/integration tests, successful recorded build/test evidence, accurate README and architecture docs |
| 02 | Vehicle profiles and module model | 01 accepted | PLANNED | Versioned profile round trips, validation, extensible module inventory, identity/applicability and explicit capability states; clearly synthetic vehicle fixture |
| 03 | Virtual modules and diagnostic communication | 02 | PLANNED | Application discovers/identifies synthetic modules and reads telemetry/DTCs through a simulated transport; trace, negative responses and deterministic timeout tests |
| 04 | Deterministic vehicle dynamics | 03 | PLANNED | Coupled engine/transmission/road-load model, virtual clock and lifecycle controls; identical scenarios/inputs reproduce outputs under a documented numerical contract |
| 05 | Both application shells and live dashboard | 04 | PLANNED | Standalone WASM and Windows MAUI Hybrid share two logical RCLs; select a profile, control simulation and display independently collected live telemetry |
| 06 | Telemetry recording and replay | 05 | PLANNED | Persist raw messages and decoded signals with metadata; playback/seek/speed controls feed the same gauges without silently reconstructing missing data |
| 07 | Calibration management and simulated programming | 06 | PLANNED | Versioned definitions/diffs, verified baseline and backup, approved simulated write, readback/unrelated-data checks, audit and supported restore; no physical writes |
| 08 | Local AI, knowledge, and validated runbooks | 07 | PLANNED | Replaceable local inference, applicable knowledge retrieval, structured logical runbook, independent validation/approval and simulation-only execution |
| 09 | Comparative evaluation and complete synthetic demonstration | 08 | PLANNED | Complete demonstration below plus deterministic fault/regression matrix and independent verification of intended and unintended changes |
| 10 | Verified OBDX Pro GT read-only integration | 09 plus documented device research/access | PLANNED / HARDWARE GATE | Source-backed device support matrix, explicit physical target, real read-only identification/diagnostics/telemetry recording where supported; no write path |
| 11 | Advanced dashboards, analysis, and comparisons | 09; 10 for real captures | PLANNED | Persist configurable layouts/thresholds/units, linked charts, raw-data inspection, multi-run/multi-vehicle comparisons with lineage and uncertainty |
| 12 | Broader diagnostic protocols and hardware adapters | 10 | PLANNED | Conformance-backed additional CAN/ISO-TP/UDS/KWP2000/J2534 or legacy adapters where verified; same application ports and capability restrictions |
| 13 | Curated vehicle knowledge and research workflow | 08; 12 where needed | PLANNED | Sourced profile/module/calibration knowledge, review/promotion workflow, exact applicability, licensing/access controls; research cannot authorize writes |
| 14 | Higher-fidelity simulation and virtual module coverage | 09; 13 for verified datasets | PLANNED | Validated model extensions, richer transmissions/environment/module interactions and reproducible fault coverage; published fidelity limits |
| 15 | AI evaluation and optional specialization | 08, 09, 13 and adequate datasets | PLANNED | Held-out deterministic runbook evaluations, refusal/uncertainty cases, memory/latency measurements; LoRA/QLoRA only if justified by measured benefit |
| 16 | Programming qualification without physical writes | 07, 09, 10, applicable 12/13 evidence | PLANNED | Module-specific safety case, bench plan, voltage/state/identity checks, interruption/recovery tests in simulation, legal authorization and defined go/no-go criteria |
| 17 | Explicitly authorized controlled bench programming | 16 and separate user authorization | PLANNED / AUTHORIZATION GATE | Authorized supported bench target only; verified backup completeness, transfer/readback/recovery evidence and audit; no general vehicle-write enablement |
| 18 | Approved vehicle/module-specific programming | 17 and separate vehicle-operation authorization | PLANNED / AUTHORIZATION GATE | Explicit per-operation approvals, compatibility/operating-state/power/security checks and proven recovery limits; strict module-specific support matrix |
| 19 | Packaging, extensibility, and additional platforms | 05, 09; feature-specific gates remain | PLANNED | Offline-friendly reproducible releases, documented supported hosts, feature manifests/DI, compatibility/migration regression evidence |
| 20 | Optional MCP and firmware-emulation research | 08, 13; isolated research approvals | OPTIONAL / PLANNED | Concrete benefit and separate ADR; restricted tools retain validator/approval boundary; emulation limitations and proprietary-data rights documented |
### Scope details for Steps 02-10
- **02:** vehicle specifications and configuration/tune selection, arbitrary module
identities, supported/unsupported/unknown/inaccessible/restricted capability
states, firmware/calibration identity, relationships, provenance, validation,
schema versioning, and multiple synthetic variants. Never imply a diagnostic
capture contains a complete firmware image.
- **03:** synthetic module state/storage, identification, telemetry definitions,
DTC retrieval and simulated clearing, request/response semantics, addressing,
session state where appropriate, delays, invalid requests, unsupported services,
interruption and negative responses. Authentic protocol semantics require
sources; synthetic behavior is labeled.
- **04:** start/stop/pause/resume/reset/step, configurable pacing independent of
simulation results, save/load configuration, seeded scenarios, engine idle,
throttle/load/torque/fuel, transmission/shift scheduling, mass/drivetrain/road
load, temperatures, and a stationary-to-45-MPH-to-stop scenario with a five-minute
hold. Report mathematical assumptions and repeatability tolerances.
- **05:** reusable data-bound gauges and feature screens, navigation and settings,
profile/module selection, connection state and diagnostics; compile-time feature
composition first, no unsupported arbitrary assembly loading. Missing MAUI
workloads are blockers, not permission to replace either shell. Native browser
access eventually uses a verified local .NET service, never browser P/Invoke.
- **06:** versioned recording format, module/source/units/time/quality metadata,
raw plus decoded retention, interrupted/corrupt session handling, replay
play/pause/stop/restart/seek/navigation/speed. Acquisition must not depend on
visible gauges. Mark captured versus interpolated/reconstructed samples.
- **07:** scalar/table definitions with ranges/scaling/units and dependencies;
original/proposed/tested/approved versions, structured diffs, verified backup
completeness, approval binding, audit, readback, unrelated-data preservation,
restoration where supported, explicit failure/recovery outcomes.
- **08:** local inference provider configuration, structured queries plus optional
semantic retrieval, source-backed applicability checks, versioned runbook schema
and restricted tools. Include natural-language diagnostics, driving scenarios,
and calibration planning; AI cannot emit arbitrary hardware frames/offset writes.
Missing knowledge and disconnected inference produce explicit outcomes without
disabling non-AI functionality.
- **09:** equivalent baseline/modified scenarios and initial state, independent
calibration oracle, behavioral/fuel/shift comparisons with confidence labels,
fault reports, replay/raw-trace inspection and an auditable verification report.
Include timeout, unsupported service, malformed response, wrong identity/version,
interruption, corruption/checksum, partial write, reset, incompatible config,
DTC and failed-verification cases.
- **10:** verify OBDX Pro GT protocols, drivers, OS/architecture constraints,
manufacturer libraries/SDKs, actual J2534 support and C# integration using
attributable sources before implementation. Missing device/driver access means
real-hardware verification is blocked, not passed by mocks. Restrict services to
verified read-only allowlists; diagnostic access does not imply every module is
discoverable or programmable.
### Longer-term scope preservation
Steps 11-20 retain richer gauges/clusters/charts and dashboard editing, comparison
and analysis, more vehicle/module/protocol coverage, independently validated
research, curated datasets, advanced dynamics and transmission modeling, local
model evaluation/specialization, authorized programming, and supported release
packaging. New MAUI platforms require platform-specific evidence. Avalonia is an
optional feasibility investigation, not a promise that Razor embeds unchanged.
Optional MCP does not bypass runbook safety. Firmware emulation is separate from
the initial behavioral simulator, never an implied capability of synthetic modules.
Bench and vehicle programming milestones may not proceed on roadmap status alone.
If authorization, applicable definitions, safe test equipment, licensing, recovery
evidence, or manufacturer procedures are missing, retain a blocked gate and
continue only independent safe work through an explicit new assignment.
## Required synthetic end-to-end demonstration
Target acceptance: Step-09. Use the explicitly synthetic AutoForge test truck,
initial warm idle 650 RPM and proposed warm idle 1,250 RPM. These values and any
memory layout are synthetic, not manufacturer calibration data.
1. Load the synthetic vehicle; inspect its modules and current calibration.
2. Start simulation; display original idle telemetry; record and stop the run.
3. Request the idle change in natural language. The local AI identifies the
applicable module/parameter and produces a versioned logical runbook.
4. Deterministically validate identity, definition, range/dependencies, execution
target and approval; back up the original virtual calibration and verify it.
5. Apply only the approved simulated change. Verify the operation, read calibration
back, confirm the target value and independently confirm unrelated values.
6. Re-run the same scenario/initial state using the modified calibration; observe
the changed idle behavior and record the second run.
7. Replay either recording; compare both runs, preserving their source, time,
configuration, fidelity, and confidence metadata.
8. Inspect underlying diagnostic communications and a report separating backup,
programming, and functional verification with supported recovery limitations.
Evidence must cover all these actions without privileged application/AI access
to the test oracle. Add a table-based shift-schedule case later; do not imply all
calibration requests are scalar edits. Simulation fuel-use changes are estimates,
not proven real-world economy improvements.
## Test and evidence strategy
- Worker selects maintained .NET 10-compatible test packages after inspecting the
installed SDK and package compatibility. No speculative SDK/package signatures.
- Unit tests cover invariants, validation, decoding, algorithms, and failure
semantics. Integration tests exercise real composition across boundaries,
serialization/persistence, transports, and execution as those features arrive.
- Add simulation-specific test projects only when they have real responsibilities.
Keep all tests in `src/tests` and separate privileged oracle access.
- Use deterministic fixtures/seeds/virtual time; define reproducibility and numeric
tolerance contracts. Keep test infrastructure independent of AI/cloud/hardware.
- Adapter contract and hardware tests distinguish stub evidence from real devices.
AI evaluations include held-out invalid/unsupported/uncertain requests and
deterministic validators, not only LLM-as-judge.
- Record exact commands, target framework/platform, configuration, exit outcomes,
test counts and failures, and durable evidence references in each worker report.
- Run the smallest relevant builds/tests plus required regression coverage.
Missing prerequisites or unexecuted tests are BLOCKED/NOT EXECUTED, never PASSED.
- Every assignment requires appropriate real unit/integration tests, documentation
and README review. No empty "integration" tests or success-shaped placeholders.
- The orchestrator inspects evidence without claiming independent runtime execution.
## Decisions, completed work, remaining work, and blockers
### Initial decisions
- D-001: amendment layout and Step-XX naming supersede the original examples.
- D-002: one .NET 10 solution; minimal headless Core/Application foundation first.
- D-003: standalone WASM plus Windows-first MAUI Hybrid, shared components/screens;
no Blazor Server substitution.
- D-004: common diagnostic/application interfaces across simulation, replay and
physical providers; explicit execution target, no fallback.
- D-005: deterministic simulation and independent verification are prerequisites
for AI-assisted calibration execution and physical integration.
- D-006: local-first replaceable inference; no initial fine-tuning/vector/MCP/cloud
dependency. Storage implementations are chosen when real use cases arrive.
- D-007: initial hardware is read-only; bench and vehicle writes have separate
authorization/evidence gates and retain prohibited-operation restrictions.
- D-008: handoffs remain manual; only the worker builds/tests and implements.
The worker records the relevant accepted decisions as technical ADRs when creating
or changing the implementation. Future changes require a reason and roadmap/state
history, not repeated redesign without evidence.
### Completed
- Read both supplied instruction sets and inspected the existing repository.
- Established the initial planned boundaries, sequence, and first worker assignment.
### Remaining
- All application implementation, build/test verification, and technical
documentation work, beginning with Step-01.
- Review Step-01 and any corrections before issuing Step-02.
### Known blockers and uncertainties
No confirmed initialization blocker. The orchestrator has not inspected installed
.NET SDKs, workloads, package compatibility, inference availability, or hardware.
The worker must inspect prerequisites; absence of evidence is not compatibility.
Physical hardware access, applicable manufacturer definitions, and programming
authorization are future gates, not current claims.

105
prompts/STATE.md Normal file
View File

@ -0,0 +1,105 @@
# AutoForge orchestration state
## Current handoff
| Field | Value |
|---|---|
| Updated | 2026-10-28 |
| Phase | Initial orchestration complete; application foundation not started |
| Active step | Step-01 - Repository and solution foundation |
| Assignment | [Step-01.md](Step-01.md) |
| Assignment status | READY FOR WORKER / AWAITING MANUAL HANDOFF |
| Expected worker report | `prompts/Step-01-Report.md` - not yet created |
| Last accepted step | None |
| Outstanding corrections | None |
| Worker execution | Not invoked; user controls handoff |
| Immediate next action | User manually directs the worker to execute Step-01 only |
| Next orchestrator action | After manual return, inspect the assignment, report, implementation, tests, Git changes, documentation and recorded command evidence |
## Repository baseline
- Repository: `D:\_Repos\Code\GAJ3T\AutoForge`.
- Branch observed: `main`, tracking `origin/main`.
- Initial worktree: clean.
- Initial tracked files: root `README.md` and `.gitignore`.
- No existing solution, projects, tests, `docs`, `src`, or `prompts` were present.
- No applicable `AGENTS.md` was found in the repository or its ancestor locations.
- No `.github` instruction files were found. In particular,
`.github/copilot-instructions.md` was absent and must remain absent.
- Existing README describes the product vision, not verified implemented features;
Step-01 requires preserving it while making implementation status explicit.
- Existing `.gitignore` already includes common Visual Studio/.NET build patterns.
Worker must extend only where necessary and preserve existing entries.
- Orchestrator changes are limited to `prompts/ROADMAP.md`, this file, and
`prompts/Step-01.md`. Existing tracked files and Git metadata are preserved.
## Architecture decisions in force
See [ROADMAP.md](ROADMAP.md) for the full planned architecture and milestones.
1. The repository has only three top-level project directories: `docs`, `src`,
`prompts`; existing protected infrastructure is preserved. Tests are under
`src/tests`. No root `tests`, root `artifacts`, or nested `AutoForge` directory.
2. The worker creates `src/AutoForge.slnx` targeting .NET 10. Initial production
projects are Core and Application; initial test projects are UnitTests and
IntegrationTests. No unused placeholder assemblies.
3. Step-01 is headless with real target-selection validation and composition tests.
Simulation/diagnostics are introduced in Steps 02-04; both required UI shells
and shared components/screens RCLs are introduced in Step-05.
4. Domain logic is platform-neutral. Application use cases depend inward on Core.
Hardware, inference, storage, and UI implementations never own domain truth.
5. Simulation, replay, and physical hardware targets are explicit and cannot
silently substitute for one another. Selection is not connection or execution.
6. Synthetic data is labeled; simulation is deterministic and independent of AI,
and verification uses an isolated oracle unavailable to ordinary UI/AI paths.
7. AI plans are validated runbooks; no arbitrary hardware commands or offsets.
Local inference is replaceable; core operation does not require AI/cloud.
8. Initial hardware integration is read-only. Simulated approval, physical
capability discovery, and driver availability cannot authorize physical writes.
Bench and vehicle programming require separate future authorization/evidence.
9. All handoffs are manual. Orchestrator never invokes the worker, implements
application changes, or executes application builds/tests.
10. The worker does not change the roadmap, state, or assignment; it may write only
the current assignment's report under `prompts`. No automatic commits/pushes.
## Prerequisites and known issues
- The worker must inspect installed SDKs, templates and package compatibility
before choosing exact versions. .NET 10 compatibility is not yet verified.
- No major SDK/workload/driver installation has been authorized. Report exact
missing prerequisites and mark blocked checks honestly; do not replace .NET 10
or either required UI architecture.
- Step-01 does not need MAUI workloads, an AI model, containers, a vehicle, a
native driver, or cloud infrastructure.
- No confirmed implementation defects or environmental blockers are known because
there is no implementation yet.
- No application build or test has been executed by the orchestrator.
## Review and progression gate
On manual return, evaluate every Step-01 acceptance criterion using the original
assignment, worker report, actual code/tests, dependency graph, Git changes,
README/docs, and recorded build/test evidence. Do not accept solely on a success
claim; do not claim independent runtime verification.
- If accepted: record the decision and evidence, update roadmap/state, create
`Step-02.md`, and stop for manual handoff.
- If deficient: create `Step-01A.md` with measurable corrections, update state,
and stop. Further corrections use `Step-01B.md`, etc., with matching reports.
- If blocked: retain the active step, document the prerequisite and required
worker evidence; do not advance or mark unexecuted checks as successful.
- Never create the next major assignment while acceptance or corrections are open.
## History
| Date | Event | Evidence / result |
|---|---|---|
| 2026-10-28 | Initial repository inspection | Clean `main`; only root README and ignore file tracked; no application or protected instruction files found |
| 2026-10-28 | Initial roadmap, state, and Step-01 prepared | Amendment layout/naming adopted; READY FOR WORKER, no implementation accepted |
## Manual handoff instruction
Provide [Step-01.md](Step-01.md) to the separate worker and request execution of
that assignment only. The worker must produce `prompts/Step-01-Report.md` and stop.
Return manually to the orchestrator for review. Reports, including final chat
reports, must follow the single plain triple-backtick copy-window requirement.

343
prompts/Step-01.md Normal file
View File

@ -0,0 +1,343 @@
# 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.