diff --git a/prompts/ROADMAP.md b/prompts/ROADMAP.md new file mode 100644 index 0000000..dd721ac --- /dev/null +++ b/prompts/ROADMAP.md @@ -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. diff --git a/prompts/STATE.md b/prompts/STATE.md new file mode 100644 index 0000000..a7d8771 --- /dev/null +++ b/prompts/STATE.md @@ -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. diff --git a/prompts/Step-01.md b/prompts/Step-01.md new file mode 100644 index 0000000..ce096db --- /dev/null +++ b/prompts/Step-01.md @@ -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.