Add Project Guidance For Agents
This commit is contained in:
@@ -0,0 +1,79 @@
|
||||
# Current project state
|
||||
|
||||
This file is working memory. Update it during active work and before handoff; do not treat it as a permanent design record.
|
||||
|
||||
## Development state
|
||||
|
||||
Based on current source plus `README.md` and `docs/roadmap.md`:
|
||||
|
||||
- Hardware characterization, serial service, session broker, USB CDC, Wi-Fi, HTTPS/WebSocket, SSH serial transport, and local display/control are implemented and documented as target-hardware validated.
|
||||
- Phase 8A role-based user storage/UART0 administration and Phase 8B role-aware HTTPS/SSH authentication and targeted revocation are documented as target-hardware validated.
|
||||
- Phase 8C admin SSH is implemented in source and uses the shared `esp_console` registry. Target-hardware validation is explicitly pending.
|
||||
- Phase 8D web user administration and Phase 8E browser login/session integration are planned, not implemented.
|
||||
- Security/production hardening, OTA, BLE evaluation, advanced networking, and optional filesystem features remain future roadmap work.
|
||||
- Reserved OTA, coredump, NVS-key, and storage partitions do not imply those runtime features are implemented.
|
||||
|
||||
The normal build is `pio run`. No automated host/unit-test command is defined in the repository; important validation is hardware-oriented.
|
||||
|
||||
## Implemented capability summary
|
||||
|
||||
- One UART1/MAX3243 RS-232 service with RAM working configuration, explicit persistence commands, and explicit start/stop.
|
||||
- Generation-safe broker with up to eight clients, one writer, multiple observers, bounded per-client output/events, and drop accounting.
|
||||
- Native USB CDC-ACM, two browser WebSocket sessions over HTTPS, and two SSH slots.
|
||||
- SSH role routing: users receive serial; administrators receive the shared bounded administration shell.
|
||||
- Four-profile station Wi-Fi plus off/fallback/always AP policies and network diagnostics.
|
||||
- Eight-user role database, three Ed25519/P-256 keys per user, PBKDF2 password verifiers, copied principals, and targeted revocation.
|
||||
- Self-signed HTTPS identity, separate SSH host key, one-time WebSocket tickets, and fail-closed authentication when user storage is unavailable.
|
||||
- UART0/admin SSH serialized command registry with transport-aware prompts, bounded remote output/history, and deferred self-affecting SSH actions.
|
||||
- Optional SSD1315-compatible OLED status/control interface with persisted inactivity settings and bounded failure recovery.
|
||||
- Hardware diagnostics for MAX3243/UART flow control and OLED/buttons.
|
||||
|
||||
## Clearly incomplete or transitional areas
|
||||
|
||||
- Phase 8C hardware-validation matrix remains pending. It includes route separation, shared command serialization, history/completion, prompts, output backpressure, revocation during queued work, deferred SSH lifecycle/reboot actions, and full concurrent transport operation.
|
||||
- Current HTTPS has no web-based user administration and gives both roles the same status/terminal routes.
|
||||
- Browser authentication still uses HTTP Basic; integrated login/logout sessions are planned.
|
||||
- NVS encryption, secure boot/flash encryption review, authentication rate limiting, production certificate/provisioning policy, and OTA are not implemented.
|
||||
|
||||
## TODO/FIXME survey
|
||||
|
||||
No authored `src/*.{c,h}` `TODO`, `FIXME`, `XXX`, or `HACK` markers were found during the initial architecture analysis. A TODO inside vendored `web_assets/xterm.css` is upstream asset content and not project work.
|
||||
|
||||
## Known inconsistencies
|
||||
|
||||
These observations should be checked when touching the relevant area; they are not automatically bugs requiring unrelated cleanup.
|
||||
|
||||
- `src/main.c` logs a Phase 7E startup banner although the implementation/roadmap is at Phase 8C.
|
||||
- `docs/command_reference.md` calls `web credentials show` physical-console-only in one row, while current source and surrounding text allow it to authenticated admin SSH.
|
||||
- The same reference describes interactive `user key add <username>` as a physical UART0 prompt, but transport-neutral prompt code allows it over admin SSH.
|
||||
- Historical Phase 7 electrical-test steps expect Select to remain read-only and describe a powered state before automatic OLED initialization; current firmware has local controls and initializes the display during boot.
|
||||
- `README.md`'s NVS partition-purpose list omits the `local_ui/config` blob.
|
||||
- `README.md` links Adafruit product 6253, while `src/board_pins.h` and `docs/wiring.md` identify product 5988. **Needs verification:** whether this is an intentional male/female breakout distinction.
|
||||
- `docs/user_administration_tests.md` contains historical Phase 8A/8B behavior that differs from current Phase 8C admin SSH routing. Treat phase-specific sections as historical procedures.
|
||||
- Manual completion candidates omit implemented `wifi next-profile`.
|
||||
- Some source comments still call shared commands UART0-only or call the current local status/control task read-only.
|
||||
- `USER_DATABASE_LOAD_EMPTY` and the corresponding `main.c` log branch appear reserved or vestigial; the current missing-storage success path migrates valid legacy credentials. **Needs verification** before removing or repurposing.
|
||||
- SSH startup is currently gated on successful `web_security` initialization even though SSH uses separate host-key material. **Needs verification:** whether this coupling is intentional recovery policy or an accidental startup dependency.
|
||||
|
||||
## Items to verify in future work
|
||||
|
||||
- Complete the documented Phase 8C target-hardware validation before marking it complete.
|
||||
- Confirm task-local Newlib standard-stream behavior if ESP-IDF/Newlib configuration changes; admin SSH command output relies on dispatcher-task stream redirection.
|
||||
- Revalidate software-crypto/watchdog behavior before changing crypto acceleration or PSRAM placement.
|
||||
- Verify the Adafruit breakout product identity and reconcile hardware documentation.
|
||||
- If HTTPD concurrency configuration changes, verify whether the boot-local Basic-authentication cache needs explicit locking.
|
||||
- Treat serial-service exclusivity as an architectural contract: its public read/write APIs do not themselves prove that only the broker calls them.
|
||||
|
||||
## Active Task
|
||||
|
||||
No active task recorded.
|
||||
|
||||
### Handoff template
|
||||
|
||||
- **Objective:**
|
||||
- **Relevant files:**
|
||||
- **Findings:**
|
||||
- **Decisions made:**
|
||||
- **Changes completed:**
|
||||
- **Remaining work:**
|
||||
- **Risks / things to remember:**
|
||||
Reference in New Issue
Block a user