107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# ChatGPT project context
|
|
|
|
This directory is a local mirror of the ChatGPT project “maze32”.
|
|
|
|
- Treat every file under `sources/` as read-only reference material.
|
|
- Do not edit, rename, move, or delete synced project files.
|
|
- These files may be replaced the next time a task is created from this ChatGPT project.
|
|
|
|
|
|
## Project instructions
|
|
|
|
### Language
|
|
|
|
- Write all canonical documentation in English.
|
|
- Write source comments, test names, protocol identifiers, log messages, and
|
|
user-facing diagnostic text in English.
|
|
|
|
### Canonical documents
|
|
|
|
- `MVP.md` defines product scope, gameplay rules, and MVP acceptance criteria.
|
|
- `ARCHITECTURE.md` defines implementation contracts and technical boundaries.
|
|
- `PLANS.md` defines the current implementation milestone and its evidence.
|
|
- `docs/BOARD_PASSPORT.md` defines confirmed hardware facts and explicit
|
|
unknowns.
|
|
- Files under `sources/` remain read-only references and are never canonical
|
|
implementation files.
|
|
|
|
When documents disagree, stop and resolve the conflict before implementation.
|
|
Do not silently choose one requirement over another.
|
|
|
|
### Milestone workflow
|
|
|
|
- Follow `PLANS.md` strictly.
|
|
- Milestones may be planned and added to `PLANS.md` in batches.
|
|
- Number milestones from 1 without gaps using `Milestone 001`, `Milestone 002`,
|
|
and so on.
|
|
- Execute milestones strictly in ascending numerical order.
|
|
- Do not start a milestone until every preceding milestone is `COMPLETE`.
|
|
- Keep at most one milestone `IN_PROGRESS`.
|
|
- Append newly discovered milestones to the end of `PLANS.md`; do not insert or
|
|
renumber existing milestones without explicit project-owner approval.
|
|
- Every milestone must include objective, scope, deliverables, acceptance
|
|
criteria, evidence, and status.
|
|
- Do not mark a milestone `COMPLETE` without concrete recorded evidence for
|
|
every acceptance criterion.
|
|
|
|
### Commit message handoff
|
|
|
|
- After completing every user prompt, provide a proposed commit message for
|
|
the resulting changes. This is mandatory when completing a milestone.
|
|
- Use the Conventional Commits format `type(scope): imperative summary`, or
|
|
`type: imperative summary` when no meaningful scope exists.
|
|
- Choose exactly one appropriate type from `feat`, `fix`, `refactor`, `perf`,
|
|
`test`, `docs`, `style`, `build`, `ci`, `chore`, or `revert`.
|
|
- Write the commit message in English, use an imperative summary beginning
|
|
with a lowercase verb, keep the subject at 72 characters or fewer when
|
|
practical, and do not end it with a period.
|
|
- Base the message on the actual completed changes and milestone outcome; do
|
|
not use vague summaries such as `update files` or `make changes`.
|
|
- Present the proposed commit message in the final response, but do not create
|
|
the Git commit unless the user explicitly requests it.
|
|
|
|
### Locked platform baseline
|
|
|
|
- Target ESP32-C6FH4 with 4 MB Flash.
|
|
- Do not require PSRAM.
|
|
- Use PlatformIO with `espressif32@7.0.1`, ESP-IDF, and the compatible
|
|
`esp32-c6-devkitm-1` board profile.
|
|
- Use `partitions.csv` and `sdkconfig.defaults` from the project root.
|
|
- Do not add an OTA partition for MVP.
|
|
- Do not assume a board GPIO map, built-in LED, or exact commercial PCB model.
|
|
|
|
### Architectural invariants
|
|
|
|
- The ESP is the sole authoritative owner of lobby and match state.
|
|
- Browsers send commands and render server-approved projections; they do not
|
|
decide movement, inventory, timers, visibility, or results.
|
|
- Never serialize hidden maze or object state to player clients.
|
|
- Observer sessions are read-only.
|
|
- Bound all connection counts, message sizes, queues, retries, and allocations.
|
|
- Active game state need not survive reboot; Wi-Fi configuration must persist
|
|
in NVS.
|
|
|
|
### Code style
|
|
|
|
- Follow the repository `.clang-format`.
|
|
- Format all modified C and C++ files with `clang-format`.
|
|
- Prefer simple, explicit code that is easy for beginners to read.
|
|
- Avoid clever one-liners and unnecessary abstractions.
|
|
- Use braces for all non-trivial control-flow blocks.
|
|
- Prefer descriptive variable and function names.
|
|
- Keep functions reasonably small.
|
|
|
|
### Build and verification
|
|
|
|
- Parse the project configuration with
|
|
`/home/sasa/.platformio/penv/bin/pio project config` after changing
|
|
`platformio.ini`.
|
|
- Build with `/home/sasa/.platformio/penv/bin/pio run` once firmware sources
|
|
exist.
|
|
- Add host-side deterministic tests for portable game logic before relying only
|
|
on device tests.
|
|
- Verify the final application and filesystem sizes against `partitions.csv`.
|
|
- Test on the physical board before recording hardware acceptance evidence.
|
|
- Preserve exact commands and relevant outputs in the active milestone's
|
|
evidence section.
|