From 3c453587068db3b7957e86e53002290daf4131a5 Mon Sep 17 00:00:00 2001 From: Nenad Bjelanovic <32547040+nbjelanovic@users.noreply.github.com> Date: Wed, 9 Sep 2026 15:57:29 -0400 Subject: [PATCH 1/2] docs: establish workspace rules, dual-loader authority, and documentation ownership --- AGENTS.md | 105 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 60 insertions(+), 45 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4f29a4e..ab39f08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,58 +1,73 @@ # OpenGauge Agent Guide -## Scope +## Applicability and project identity -This directory is the complete boundary for OpenGauge. Do not place OpenGauge files in `D:\ESP32`, `OpenTrail`, or a root-level shared directory. A reusable dependency should be evaluated as a separately versioned library rather than an informal root folder. +C:\lu\AGENTS.md applies in full. This file adds OpenGauge-specific constraints and may not weaken the workspace rules. Stop and report any conflict. -## Current phase +- Canonical engineering root: C:\lu\OpenGauge +- The customer-facing repository and product name is Display; OpenGauge, opengauge, and OG- remain the engineering identifiers. +- Do not create a separate C:\lu\Display directory or place OpenGauge source in D:\ESP32, C:\lu\OpenTrail, or a shared root directory. +- OpenGauge owns listen-only CAN/J1939 ingestion, normalized vehicle telemetry, gauge rendering, and vehicle validation. +- Do not begin a complete gauge UI or vehicle integration until the applicable interfaces and safety boundaries have been reviewed and accepted. -OpenGauge is in architecture and proof-of-concept planning. Candidate displays and network roles are not selected or validated. Do not begin a complete gauge UI or vehicle integration before the interfaces and safety boundaries are reviewed. +After the minimal workspace bootstrap, read only project documents relevant to the task. For implementation that changes product behavior or architecture, consult README.md, docs\ARCHITECTURE.md, docs\PROJECT_STATUS.md, and tasks\BACKLOG.md as applicable. -## Brand and trademark safeguards - -- `Limited Underground` and `Limited Underground Business` are owner-approved working identities pending attorney clearance, not cleared or registered names. -- Use `LU` only as a monogram visibly paired with the full words `Limited Underground`. Do not create or publish `LU Link`, `LU Studio`, or an `LU`-plus-number public model name such as `LU300`, `LU-300`, or `LU 300`. -- Never use `®` without documented federal registration for the exact mark and relevant goods or services. Use `™` only where an unregistered trademark symbol is appropriate. -- New public product or family names require documented preliminary screening and explicit owner approval; obtain professional clearance before permanent hardware marking, packaging, sales, or another hard-to-reverse release. -- Keep working names out of protocol fields, compatibility identifiers, device IDs, persistent schemas, API contracts, cryptographic material, and board identifiers so branding remains replaceable. -- Existing `OG-` engineering, protocol, test, and inventory identifiers remain allowed. They are OpenGauge technical identifiers, not `LU` model names. - -## Working rules +## Architecture boundaries -1. Read `README.md`, `docs/ARCHITECTURE.md`, `docs/PROJECT_STATUS.md`, and `tasks/BACKLOG.md` first. -2. Preserve existing work. Do not delete, rename, or broadly restructure without a documented reason. -3. Isolate board, CAN controller/transceiver, display/touch, storage, and radio code behind interfaces. -4. Keep gateway, gauge display, GPS, and auxiliary/APU roles as separate target compositions. -5. Avoid giant `.ino` files. Keep J1939 parsing, decoding, normalization, telemetry caching, alarms, and wire codecs host-testable. -6. Never transmit raw C/C++ structs over ESP-NOW. Use explicit, versioned serialization and length/range validation. -7. Treat vehicle data as untrusted and possibly stale, unavailable, not installed, or erroneous. Never invent a numeric value. -8. This project must not perform safety-critical vehicle control without a separately reviewed fail-safe design. Early CAN work is listen-only. -9. Do not hard-code credentials, pairing secrets, private keys, or vehicle-specific identifiers. -10. Record exact hardware, wiring, termination, bus conditions, firmware/toolchain, and observed results for physical tests. +1. Isolate board, CAN controller/transceiver, display/touch, storage, and radio code behind interfaces. +2. Keep gateway, gauge display, GPS, and auxiliary/APU roles as separate target compositions. +3. Avoid giant .ino files. Keep J1939 parsing, decoding, normalization, telemetry caching, alarms, and wire codecs bounded and host-testable. +4. Never transmit raw C or C++ structs over ESP-NOW. Use explicit, versioned serialization with length and range validation. +5. Treat vehicle data as untrusted and possibly stale, unavailable, not installed, invalid, or erroneous. Represent those states explicitly and never invent a numeric value. +6. Early CAN work is listen-only. Do not perform safety-critical vehicle control without a separately reviewed and accepted fail-safe design, explicit scope, and explicit authorization. +7. Do not hard-code credentials, pairing secrets, private keys, or vehicle-specific identifiers. -## Validation expectations +## OpenTrail relationship -- Parser/decoder/cache/alarm/protocol work: deterministic host tests including malformed, boundary, timeout, and compatibility cases. -- Firmware: build every affected target and record the board/toolchain configuration. -- CAN/J1939 work: start with captured/synthetic frames; physical connection requires correct transceiver, voltage compatibility, isolation assessment, termination, and explicit authorization. -- Display compatibility: report measured boot time, memory, frame/update performance, touch behavior, power, and recovery—not specifications alone. +- Only bounded, normalized, versioned alerts may cross into OpenTrail. +- Raw CAN/J1939, VINs, unrestricted text, credentials, keys, and vehicle-control commands must not enter OpenTrail, LoRa, or Trail Server. +- Cross-project contracts must be versioned, independently implemented, and backed by mirrored normative fixtures. +- Transport authentication, authorization, replay protection, and key lifecycle must be explicit; CRC alone is only corruption detection. +- OpenGauge and OpenTrail remain optional to one another. -## Safety boundary +## Vehicle and hardware safety -A gauge warning is supplemental instrumentation. Stale or missing gateway data must be conspicuous. Gateway/display loss must not affect vehicle operation. APU or auxiliary control remains outside the core telemetry path and requires authentication, authorization, interlocks, and independent safety analysis. +- Parser, decoder, cache, alarm, and protocol work requires deterministic host tests including malformed, boundary, timeout, and compatibility cases. +- Build every affected target and record the exact board and toolchain configuration. +- Start CAN/J1939 work with captured or synthetic frames. +- Before physical vehicle connection, verify the correct transceiver, voltage compatibility, protection, isolation assessment, termination, and explicit owner authorization. +- Record exact hardware, wiring, termination, bus conditions, firmware/toolchain, and observed results for physical tests. +- Report display compatibility using measured boot time, memory, frame/update performance, touch behavior, power, and recovery rather than specifications alone. +- Gauge warnings are supplemental instrumentation. Stale or missing gateway data must be conspicuous. +- Gateway or display loss must not affect vehicle operation. +- APU or auxiliary control remains outside the core telemetry path and requires authentication, authorization, interlocks, and independent safety analysis. -## Completion and publication gate - -- Follow the workspace-wide completion and publication gate in `D:\ESP32\AGENTS.md`. -- Once an OpenGauge task is implemented and validated, update every affected canonical record and dated public progress entry, commit and push the relevant public-ready OpenGauge changes, and verify the remote commit before calling the task complete. -- If accepted evidence changes public project status or V1 progress, synchronize and validate the Limited Underground website projection, commit and push the website update, deploy it, and verify the live OpenGauge status before calling the task complete. -- If no public website status changed, say so explicitly in the completion report. If any required push, synchronization, deployment, or verification is blocked, report `implementation complete; publication pending` and identify the remaining step. -- Do not bundle unrelated or unvalidated dirty-worktree changes merely to satisfy this gate, and never publish private or unsafe material. - -## V1 progress completion gate +## Brand and trademark safeguards -- `docs/V1_PROGRESS.json` is the canonical OpenGauge V1 progress record. Do not maintain a separate percentage in the README, firmware, or website source. -- Before calling any task complete, compare its accepted evidence with every affected V1 milestone. Planning, code volume, or an unvalidated implementation does not increase completion. -- When evidence changes a milestone, update its completion, evidence references, next gate, and `as_of` date; append a dated `change_log` entry with the newly calculated weighted overall. Never rewrite prior history. -- Milestone weights must remain positive and total exactly 100. A regression or newly discovered blocker may lower completion and must be recorded just like an increase. -- The public website projection is generated separately from this canonical record. After changing it, run the Limited Underground website's V1 sync/check flow and publish the result when website publication is in scope. If publication is not authorized or available, report the pending website synchronization explicitly. +- Limited Underground and Limited Underground Business are owner-approved working identities pending attorney clearance, not cleared or registered names. +- Use LU only as a monogram visibly paired with Limited Underground. Do not create or publish LU Link, LU Studio, or an LU-plus-number public model name such as LU300, LU-300, or LU 300. +- Never use ® without documented federal registration. Use ™ only where appropriate for an unregistered mark. +- New public product or family names require preliminary screening, explicit owner approval, and professional clearance before permanent marking, packaging, sales, or another hard-to-reverse release. +- Keep working names out of protocol fields, compatibility identifiers, device IDs, persistent schemas, API contracts, cryptographic material, and board identifiers. +- Existing OG- identifiers remain technical identifiers, not public model names. + +## Documentation and progress authority + +- docs\PROJECT_STATUS.md owns detailed current engineering state. +- tasks\BACKLOG.md owns project sequencing and acceptance gates. +- docs\V1_PROGRESS.json owns detailed V1 progress mechanics. +- C:\lu\.tracker\PROJECTS\OpenGauge.md owns only a dated workspace summary and links. +- C:\lu\.tracker\CURRENT-FOCUS.md solely owns any active objective, blocker, next action, and acceptance criteria. +- Planning, code volume, and unvalidated implementation do not increase progress. +- Progress history is append-only; milestone weights must remain positive and total 100; regressions may lower completion. +- The public website is a generated sanitized projection and never progress authority. + +## Completion and publication + +- Follow C:\lu\AGENTS.md and C:\lu\.tracker for workspace authority. +- Documentation does not authorize commit, push, PR creation, website work, deployment, or remote verification. +- When a distinct publication operation is explicitly authorized, publish only validated public-ready scope through the intended repository and independently verify the remote result only when that verification is separately authorized. +- Website synchronization or deployment requires separate explicit scope and authorization. +- State explicitly when accepted evidence did not change public website status. +- If implementation is complete but a required publication operation is unavailable or unauthorized, report implementation complete; publication pending and name the exact remaining action. +- Never bundle unrelated or unvalidated dirty-worktree changes and never publish private or unsafe material. \ No newline at end of file From 1623faec76272e28bb750405306d7e487a2b0060 Mon Sep 17 00:00:00 2001 From: Nenad Bjelanovic <32547040+nbjelanovic@users.noreply.github.com> Date: Tue, 29 Sep 2026 22:24:14 -0400 Subject: [PATCH 2/2] Document accepted Display evidence reconciliation --- docs/PROJECT_STATUS.md | 6 +- ...021a-EVIDENCE-RECONCILIATION-2026-09-23.md | 131 ++++++++++++++++++ tasks/BACKLOG.md | 7 + 3 files changed, 143 insertions(+), 1 deletion(-) create mode 100644 docs/testing/OG-0021a-EVIDENCE-RECONCILIATION-2026-09-23.md diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 25a3050..4254354 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -1,6 +1,6 @@ # OpenGauge Project Status, Assumptions, and Open Questions -Status date: 2026-08-31 +Status date: 2026-09-23 Public repository: @@ -12,6 +12,10 @@ visibility. Git redirects the former URL to the current repository. Stable This administrative migration changes no hardware, V1 evidence, or readiness claim. +## Evidence reconciliation + +[OG-0021a](testing/OG-0021a-EVIDENCE-RECONCILIATION-2026-09-23.md) maps the five Display outcomes to existing host components, bounded historical physical evidence and missing target/vehicle gates. This evidence reconciliation is owner-accepted. Completed host work is not reopened; no new hardware, support or V1 completion claim is added. + ## Conceptual goals - Separate ESP32 CAN/J1939 gateway and round touchscreen gauge nodes diff --git a/docs/testing/OG-0021a-EVIDENCE-RECONCILIATION-2026-09-23.md b/docs/testing/OG-0021a-EVIDENCE-RECONCILIATION-2026-09-23.md new file mode 100644 index 0000000..1baac8c --- /dev/null +++ b/docs/testing/OG-0021a-EVIDENCE-RECONCILIATION-2026-09-23.md @@ -0,0 +1,131 @@ +# OG-0021a Display evidence and remaining scope + +Evidence reviewed 2026-09-23; owner-accepted reconciliation. No new hardware, +vehicle, target, or production acceptance. Display remains optional to base +Trail V1. The required Display product is one protected listen-only vehicle +gateway and at least one gauge showing trustworthy telemetry, warnings and +conspicuous stale/error states without affecting vehicle operation. + +## Scope and source reconciliation + +This report reconciles existing source and dated evidence. It does not infer +current connected devices or add physical acceptance. + +Sources are the [backlog](../../tasks/BACKLOG.md), +[engineering status](../PROJECT_STATUS.md), +[product boundaries](../PRODUCT_BOUNDARIES_V0.md). Code/test presence was +checked in the canonical checkout. Historical test results below are reused +from their linked records, not represented as freshly executed tests. + +## Five outcome map + +| Checklist outcome | Reusable evidence and layer | Remaining gate and existing child work | +| --- | --- | --- | +| OG-0021: accepted scope, hardware, wiring and evidence | OG-003A inventory identifies candidate roles; OG-012A records vendor display observations and one recovery-first cycle. Product boundaries separate gateway, one required gauge and optional roles. Evidence is planning plus bounded physical candidate observation, not supported hardware. | OG-0021b: owner selects one vehicle/engine, legal signal definitions, gauges/alarms, bus, protected CAN interface, power and environment. OG-0021c: reconcile one exact display revision and recovery/test plan. No vehicle or protected gateway is selected by this report. | +| OG-0022: acquisition, screens, alerts and fault behavior | OG-004 through OG-010D provide host CAN/parser/decoder/cache/telemetry composition; OG-014/014A add local alarms. Display receiver, view model, trends, layouts and renderer coordination have deterministic host tests. OG-017 and OG-018AE/AF provide bounded diagnostics/recovery status. | OG-0022a/b/c bind those existing components to selected acquisition, display/input and diagnostic targets. Actual electrical passivity, rendering/readability and target timing remain unproved. Do not reimplement or reopen completed host tasks. | +| OG-0023: wireless and safe recovery; optional integration decisions | Explicit normalized ESP-NOW contract/codecs, peer authorization, OGL0 layout recovery, and OG-018 recovery components are host-tested. OG-018H-M provide limited host-mediated physical alert/ACK evidence. OG-015 GPS and OG-016A update boot guard are host contracts. | OG-0023a binds authenticated target radio/peer lifecycle; OG-0023b resolves protected keys, independent trusted generation, reset authority and concrete persistence. OG-0023c decides optional GNSS/Trail bridge/OTA transport and allocates any included dependent work. Host metadata or CRC cannot supply physical authentication. | +| OG-0024: supported combinations, startup, loss, thermal and power faults | OG-012A vendor HelloWorld/factory return and cold BOOT recovery are useful candidate evidence. Host gateway/renderer/recovery tests establish expected failure semantics. No selected vehicle, complete target or production endurance evidence exists. | OG-0024a measures exact display and synthetic wireless bench operation; OG-0024b proves selected-vehicle passivity and signal truth; OG-0024c proves power interruption/endurance/environment limits. Each physical operation needs its separate exact setup authorization. | +| OG-0025: setup, calibration, service and release acceptance | Existing component contracts, candidate bring-up and recovery records supply inputs. They do not constitute installation instructions or accepted vehicle/display support. | OG-0025a writes instructions against validated configurations; OG-0025b assembles traceable acceptance/release evidence. Signing/update/recovery policy, target artifacts, supported combinations and service limits must be settled; no package or release is created here. | + +## Specific evidence and its limits + +### Gateway and signals: reuse OG-010D + +The [gateway loop](../gateway/GATEWAY_TELEMETRY_LOOP_V0.md) and +[host tests](../../tests/host/gateway_telemetry_loop_tests.cpp) cover nine groups: +bounded CAN draining, real EEC1 decode/cache/encode through fake radio, no-value +replacement, stale publication during bus-off, same-sequence retry, overflow, +and stop/restart. The actual +[component](../../firmware/components/gateway/src/gateway_telemetry_loop.cpp) +is reusable source, not a target firmware artifact. Synthetic EEC1 is not proof +that a selected vehicle exposes that signal or that its scaling is correct. +Vehicle definitions must be reconciled against legally available documentation +and captured data. Electrical passivity, ISR queues, task timing, watchdogs, +automotive power/protection and failure independence still need selected-target +and vehicle evidence. The `firmware/targets` directory is currently empty. + +### Display: reuse OG-012A without promoting the candidate + +[Inventory](../../hardware/INVENTORY.md) and the +[Phase-C record](../../tests/hardware/OG-012A-PHASE-C-2026-08-14.md) identify +OG-DISP-001 as the battery-free USB candidate that passed cold BOOT recovery, +verified official HelloWorld programming and visible output, then verified +factory-image programming and a visibly good demo. OG-DISP-002 remained +untouched in that cycle. This does not prove exact received revision, private +original-backup restoration, touch, peripherals, OpenGauge pixels, timing, +memory, stability, power/heat or paired independence. Historical acquisition +statements do not prove present possession or connection; the bench mule and +GNSS candidate remain unverified beyond the dated inventory's ordered status. + +The [renderer runtime](../display/GAUGE_RENDERER_RUNTIME_V0.md) and +[exact-generation presentation gate](../configuration/GAUGE_LAYOUT_PRESENTATION_COMPLETION_V0.md) +provide reusable host lifecycle/backpressure/completion semantics. Their tests +use a fake renderer; no pixels, touch, fonts or physical accessibility were +accepted. Historical matrix sizes differ as suites were added; this report +preserves each linked acceptance-time count and creates no new combined count. + +### OG-018: separate bridge evidence from recovery infrastructure + +[OG-018H](../../tests/hardware/OG-018H-2026-08-09.md) carried normative alerts +and ACKs through external radios with host processing. Later +[OG-018M](../../tests/hardware/OG-018M-2026-08-09.md) retained one real OpenGauge +host process across two role-reversed four-leg retry lifecycles; both ended +with one acknowledgement and no queued/in-flight/terminal-failure entry. +These are close-bench, host-mediated observations. They do not prove an +on-device authenticated Display gateway, ESP-NOW telemetry, restart durability, +vehicle acquisition or field range. Radio completion alone is not an +application acknowledgement, and host-supplied authenticated metadata is not +proof of transport authentication. + +OG-018's codec/outbox/replay/authorization and coordinated ORS0 recovery work is +already reusable host implementation. The +[key/value adapter and composed restart tests](../integration/CRITICAL_ALERT_SYSTEM_RECOVERY_KV_TARGET_ADAPTER_V0.md) +record 13 groups, 100 focused repeats and their contemporary 43-executable +matrix. They include applied and unapplied uncertain commits with real boot/save +coordinators, while the trusted generation source remains injected. Ordinary +NVS names do not create protected keys, authenticated integrity or rollback +resistance. OG-018Y's concrete target obligation remains partial. Reuse this +policy/composition where selected by OG-0023b; do not make the optional Trail +bridge a prerequisite for local vehicle gauges merely because its recovery +code exists. + +## Core versus optional choices + +The core is a passive acquisition gateway, normalized local alarms, authenticated +local telemetry and at least one gauge with safe loss/recovery behavior. Required +safe update/recovery policy is separate from optional OTA delivery transport. + +GNSS/time, more displays, a larger-screen alternative, the Trail alert bridge, +diagnostic discovery and auxiliary/APU functions remain separately selected +roles. A compact gauge does not require a larger display. The generic OBD-II +adapter is discovery equipment, not proof of a passive J1939 production gateway. +No vehicle control is included. Only bounded normalized versioned alerts/ACKs +may cross the Trail boundary; raw CAN/J1939, VINs, keys and unrestricted text +remain excluded. Loss of an optional role must not disable local gauges or the +base Trail communication path. + +## Next choices in plain English + +1. Use the accepted evidence map. Completed host work remains completed; + target integration and physical validation are the missing layers. +2. Review OG-0021b's first vehicle, desired readings/warnings and protected + gateway design. Until those inputs exist, no vehicle connection is justified. +3. Review OG-0021c's exact display candidate and remaining vendor/synthetic + test plan, preserving the second unit. This is planning before a separately + authorized hardware session. +4. Decide optional release features at OG-0023c after its listed dependencies; + included features require their own bounded work and evidence. Do not expand + the first vehicle/display support matrix by inference. + +## Validation and closeout + +This documentation checkpoint reconciles scope, five-outcome coverage, source +and test paths, the empty target directory and linked historical records. +Historical test results remain tied to their original evidence; no completed +host matrix was rerun and no source, target, vehicle or hardware behavior changed. +No V1 completion or public website status changed. The progress record predates +some later evidence; this reconciliation does not recalculate it. + +The publication preparation checks relative links, privacy and whitespace on the +selected documentation. The repository does not provide +`tools/check_repository_docs.py` or `tests/host/repository_docs_tests.py`. diff --git a/tasks/BACKLOG.md b/tasks/BACKLOG.md index f45c531..9e362ab 100644 --- a/tasks/BACKLOG.md +++ b/tasks/BACKLOG.md @@ -124,3 +124,10 @@ completed OG-010D loop to selected ESP-IDF CAN and radio adapters without confus host-tested interface with on-device or RF acceptance. Incoming display work may begin with OG-012A vendor-example and recovery evidence, but does not bypass the normalized-data path. + +## Accepted Display evidence reconciliation + +OG-0021a is owner-accepted. The [evidence map](../docs/testing/OG-0021a-EVIDENCE-RECONCILIATION-2026-09-23.md) +separates reusable host components and bounded historical observations from +missing target, selected-vehicle and physical acceptance. Completed host work +remains complete; this reconciliation adds no hardware support or V1 credit.