AutoForge/prompts/Step-02A.md

281 lines
15 KiB
Markdown

# Step-02A - Explicit profile timestamps and optional evidence constraints
## STEP IDENTIFIER
Step-02A, corrective assignment for Step-02. Step-02 is NOT ACCEPTED.
This is the sole active assignment. Step-03 is blocked and not assigned.
## STEP TITLE
Correct ambient-dependent timestamp parsing and over-restrictive optional module
evidence applicability, preserving the existing profile feature.
## OBJECTIVE
Fix two specific source/contract defects, add meaningful regressions, verify the
real Application/UI/native path, and align related documentation. Preserve all
other Step-02 behavior and the accepted single-shell/RCL/VSA architecture.
You are the WORKER. Execute only this correction, write
`prompts/Step-02A-Report.md`, and STOP for manual orchestrator review.
## ARCHITECTURAL CONTEXT
Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md), original
[Step-02](Step-02.md), its [report](Step-02-Report.md), the
[schema guide](../docs/vehicle-profile-schema-v1.md) and
[ADR-0003](../docs/adr-0003-profile-interchange-v1.md).
Keep the seven-project modular monolith: Client -> UI -> Components, with
Application feature slices depending on reusable Core contracts. Client remains
the only application executable; no backend, mediator, new host or new assembly.
All application/test projects stay under `src`, tests under `src/tests`.
Only `docs`, `src`, `prompts` are top-level project directories.
The orchestrator found the issues by inspecting source/contracts and official
.NET documentation, without running application builds/tests. Reproduce the
issues yourself; do not treat static findings as already executed regressions.
## CURRENT IMPLEMENTATION STATE
Step-02 introduced:
- Immutable Core vehicle/profile/module/capability/evidence types in
`src/AutoForge.Core/Vehicles/VehicleProfile.cs`.
- Application feature at `Features/Vehicles/Profiles`: strict schema-v1
import/export, an in-memory revision catalog, exact selection and real DI.
- UI `/vehicle-profiles` with explicit JSON import, revision selection,
metadata/provenance inspection and export; no auto-selection or target changes.
- Three synthetic fixtures and expanded tests. The worker reports 59 unit and
34 integration cases passed (93 total, zero failed/skipped), full solution and
direct native Release builds with zero warnings/errors, and native profile smoke.
These reported runs remain valid evidence of their covered cases, not proof
that the two missing cases work.
Step-01/Step-01A remain accepted. There is no simulation, diagnostic transport,
calibration data/editor, physical operation, persistent database/file store or AI.
Preserve previous assignments/reports and any concurrent work. Reinspect Git and
instructions before editing; do not assume the worktree is clean.
## REQUIRED IMPLEMENTATION
### R-01 - Require complete, explicit-offset timestamp input
Location:
[VehicleProfileJsonCodec.cs](../src/AutoForge.Application/Features/Vehicles/Profiles/VehicleProfileJsonCodec.cs),
`NullableDate`, line 478.
Current code uses DateTimeOffset.TryParse with InvariantCulture and RoundtripKind.
The [official TryParse documentation](https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse?view=net-10.0)
states that a missing date defaults to the current day, a missing offset defaults
to the local zone, and RoundtripKind has no effect for DateTimeOffset. This
accepts forms outside the explicit timestamp contract and can invent metadata
from the execution environment.
Correct both `publishedAt` and `retrievedAt`:
1. Keep explicit JSON null as unknown.
2. Accept a documented, strict ISO-8601 subset containing the complete calendar
date, time including seconds and an explicit `Z` or signed `HH:mm` UTC offset.
Support the existing exporter's round-trip format, including its fractional
seconds and numeric offsets. Preserve supplied instant/offset/precision
semantically; do not invent or silently reinterpret missing parts.
3. Reject time-only, date-only, offset-free date/time, culture-style/slash dates,
missing-year forms, whitespace-padded input, malformed dates and invalid
offsets. Do not replace missing pieces with today, local time, UTC or defaults.
4. Surface VehicleProfileInterchangeException with the precise offending
publication/retrieval JSON path and actionable format guidance. Invalid input
must fail before catalog registration.
5. Use a simple verified .NET implementation. Merely switching culture,
DateTimeStyles.None/AssumeUniversal, or relying on a permissive helper does not
satisfy strictness. Verify the actual lexical and offset behavior.
Do not change the schema version merely to fix behavior that violated the stated
v1 contract. Record the newly explicit supported timestamp subset in schema docs.
Do not alter the system date, time zone or machine settings to test this.
### R-02 - Distinguish an absent identity constraint from an asserted null match
Location:
[VehicleProfile.cs](../src/AutoForge.Core/Vehicles/VehicleProfile.cs),
module applicability validation at line 367 and `SameOptional` at line 408.
The helper currently returns `right is null` whenever the evidence identity is
null. It therefore rejects evidence that specifies a matching module but omits
an optional hardware/software/firmware/calibration constraint whenever the module
has that identity. The schema describes those context fields as optional.
Concrete baseline vector: keep the module's known hardware identity and all
matching vehicle/profile/module context, but set only the evidence's hardware
applicability to explicit null. No hardware constraint was supplied; the otherwise
compatible profile must not be rejected for that omission.
Required behavior:
- A null optional evidence identity means no constraint was supplied for that
field. It does not assert that the corresponding module identity must be null.
- A module-scoped record with no version-specific identity constraints is valid
when its vehicle/profile/module context is valid.
- Validate every supplied non-null constraint. Preserve rejection of mismatched
known values and supplied constraints against unknown target module values.
Do not convert an unknown target into a verified match or fill its identity.
- Preserve rejection of dangling/wrong module IDs, wrong vehicle/profile/revision,
conflicting known model years and invalid evidence references. Version-specific
context without a module instance remains invalid.
- Apply consistent rules across module and capability evidence references,
direct constructors and JSON/service import. Preserve immutable originals,
classifications, limitations, unknowns and lack of operational authorization.
Use the smallest clear shared validation change. Do not duplicate alternative
matching logic in the codec/UI or weaken known-constraint checks to pass tests.
Document precisely the absence-versus-supplied-constraint semantics.
## FILES OR PROJECTS EXPECTED TO CHANGE
- Correct the two existing Core/Application validation paths.
- Extend the existing domain/codec unit tests and real profile composition/UI
integration tests. Add focused fixture variants only if necessary; preserve
the original synthetic baseline/variant/alternate inputs where possible.
- Update schema/build guidance, relevant ADR text, documentation index if needed,
and root README for actual corrective status and verification.
- UI changes only if needed to expose the corrected service failures/results;
no new page/host/engine or scope expansion.
- Create only `prompts/Step-02A-Report.md` under `prompts`.
Do not modify assignments, ROADMAP, STATE, previous reports or protected Copilot
instructions. Do not create override instruction files, initialize Git, stage,
commit, push, discard unrelated changes or perform destructive cleanup.
## INTERFACE AND DEPENDENCY REQUIREMENTS
Preserve existing public feature contracts and seven-project reference graph.
Keep validation in Core/Application; UI remains presentation. Preserve typed
errors, catalog atomicity, exact revision selection, no target substitution and
all prior metadata-only/safety boundaries. No new package, major tool installation,
workload update/restore/repair/rollback or external service is expected or
authorized. Ordinary package restore is distinct from workload-changing commands.
## TESTING REQUIREMENTS
### Reproduction and unit regressions
First add focused tests that demonstrate each issue against the current code,
execute them and record the actual pre-fix failures. Then implement the correction
and rerun them. Do not fabricate before/after results.
For **both** timestamp fields:
- Invalid: time-only, date-only, full time without offset, missing-year,
culture-style date, whitespace-padded, malformed calendar and invalid-offset
input. Assert explicit interchange failure and the correct property path.
- Valid: null; UTC `Z`; positive/negative numeric offsets; non-fractional and
exporter-produced fractional values. Assert the exact expected date/time,
offset and round-trip semantics, not just successful parsing.
- Ensure no format can depend on current day or local zone. Do not change global
clock/time-zone settings. Keep the tests deterministic.
For evidence:
- Module-only matching context with all four optional identity constraints null.
- Each optional constraint independently null while the module's corresponding
value is known, plus mixed supplied/absent matching constraints.
- Supplied non-null constraints matching the module succeed.
- Supplied constraints conflicting with a known value or targeting an unknown
value fail; wrong/dangling module, vehicle/profile/revision and evidence
references continue to fail.
- Assert identities/classification/unknowns are preserved, not inferred or promoted.
### Real DI and UI integration
Import/select/export/reimport through the real profile feature:
1. Invalid timestamp rejects atomically with the expected interchange path and
unchanged catalog/current explicit selection. Do not let a duplicate-key
error mask whether the timestamp was validated.
2. A profile containing valid partial/module-only evidence context imports and
round-trips with the absent fields still null.
3. Invalid supplied identity constraints still reject atomically.
4. Actual routed UI displays the timestamp/scope errors and accepts the corrected
positive case via the same real service; no fake feature/component under test.
Use robust data mutation helpers or assert that test mutations really changed the
intended JSON path. Existing successful string replacements are not proof that
the specific invalid vector was exercised.
### Build, regression and native evidence
Preserve all 93 current cases/invariants, add the missing regressions, and run
focused checks while implementing. Then run, sequentially, the complete Release
solution build and both suites using the existing SDK/runner:
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
- Direct Windows Client build when needed for native target verification, using
the existing `net10.0-windows10.0.26100.0` target; no framework override on
portable projects. Restore packages only when needed.
Record exact commands/exit outcomes, target/configuration, warnings and per-project
discovered/passed/failed/skipped counts. Do not run competing build/test processes
against the same outputs or skip required cases to report success.
Launch the actual native Client and verify a valid explicit timestamp/partial
evidence profile imports/selects/exports, an invalid timestamp shows its specific
error, and a conflicting supplied constraint fails without catalog/selection
replacement. Verify original fixture import and target metadata routes still
work. Record observations separately from headless tests; report any exact
environment blocker and unexecuted check honestly.
## DOCUMENTATION REQUIREMENTS
Update the root README and directly related schema/ADR/testing documentation with:
- The exact accepted timestamp grammar and explicit null/offset rules.
- Absence versus supplied optional evidence constraints, preserved mismatch/
unknown-target handling and the fact that validation never grants authority.
- Step-02/Step-02A worker verification versus pending orchestrator acceptance,
actual test/native evidence and limitations.
- Existing one-shell/two-RCL/VSA architecture and native startup/build instructions.
Keep Markdown LF convention and historical reports intact. Do not rewrite the
original 93-test evidence as though it covered these new cases.
## ACCEPTANCE CRITERIA
| ID | Criterion | Required evidence |
|---|---|---|
| AC-01 | Both timestamp properties accept only the documented complete, explicit-offset grammar or null; no ambient defaults | Positive/negative vectors, exact date/offset assertions and implementation paths |
| AC-02 | Partial/module-only optional evidence context works without mutating unknowns or weakening supplied-constraint validation | Direct constructor matrix covering all four fields and positive/negative identity cases |
| AC-03 | Domain, JSON/service and actual UI paths consistently implement the corrected rules, preserving atomic failed import/explicit selection | Real DI/rendered integration assertions and exact failure paths |
| AC-04 | Original fixtures, metadata statuses/provenance, exact revisions, target isolation, all 93 prior cases and architecture remain intact | Regression mapping, source/project/Git review and per-project results |
| AC-05 | Focused new tests demonstrate actual pre-fix failures and pass after correction; complete solution/native verification succeeds | Before/after commands/results, sequential Release build/test evidence and native observations |
| AC-06 | README/schema/ADR/test guidance accurately describe the corrected v1 contract and corrective lifecycle | Changed documentation list and exact policy summary |
| AC-07 | No unrelated feature, package/workload action, orchestration/protected-file edit or automatic handoff introduced; report complete and worker stops | Preservation/scope evidence and `prompts/Step-02A-Report.md` |
Map every criterion to PASSED, FAILED, NOT EXECUTED or BLOCKED with concrete
evidence. COMPLETE requires all required correction/regression/native checks.
Do not begin Step-03; acceptance belongs to the orchestrator.
## OUT-OF-SCOPE WORK
New vehicle features, simulation/diagnostic engines or protocols, transport/
hardware/provider integration, calibration values/programming, persistence,
research/AI, new shells/RCLs, mediator/generic repository refactors, broad model
redesign and unrelated UI cleanup. All physical safety/prohibited-operation
restrictions remain unchanged.
## REPORTING REQUIREMENTS
Create `prompts/Step-02A-Report.md` entirely inside exactly one plain triple-backtick
code fence, without language tag or outside content. Use no nested fences.
Use the same copy-window format for the final chat report.
Include step/title and COMPLETE/INCOMPLETE/BLOCKED status; functionality and
architectural changes; files created/modified; R-01/R-02 root causes and fixes;
unit/integration tests and before/after evidence; exact build/test commands and
results with per-project counts; native observations; AC-01 through AC-07 mapping;
documentation and README changes; limitations/outstanding issues; deviations;
recommendations; and protected/scope/Git preservation review.
Save the report and STOP. Do not change assignments/roadmap/state, create or begin
Step-03, invoke another agent, automate handoff, stage, commit or push.