From a2a8f4a59df7ecc30537a3017140a187a0e477ec Mon Sep 17 00:00:00 2001 From: sasa Date: Tue, 8 Sep 2026 21:15:16 +0300 Subject: [PATCH] docs(m011): record approved MVP playtest evidence --- PLANS.md | 114 +++++++++++++++++++++++++++++++++++++--- docs/MVP_ACCEPTANCE.md | 10 ++-- docs/PLAYTEST_REPORT.md | 24 ++++----- 3 files changed, 124 insertions(+), 24 deletions(-) diff --git a/PLANS.md b/PLANS.md index 12ffdff..51d3438 100644 --- a/PLANS.md +++ b/PLANS.md @@ -984,7 +984,7 @@ the ESP32-C6 Flash, RAM, socket, and network limits. ## Milestone 011 — Gameplay tuning and MVP acceptance -**Status:** `IN_PROGRESS` +**Status:** `COMPLETE` ### Objective @@ -1024,8 +1024,6 @@ Implementation is in progress. `docs/BALANCE_REPORT.md` locks the current MVP gameplay configuration and records the deterministic maze metrics. The playtest procedure and result table are in `docs/PLAYTEST_REPORT.md`, and the criterion-by-criterion evidence register is in `docs/MVP_ACCEPTANCE.md`. -Representative completed-match timings and the final release build record are -still required before this milestone can be marked `COMPLETE`. - On 2026-09-08, `bash scripts/run_host_tests.sh` passed its health, Wi-Fi, NVS, provisioning, lobby/protocol, maze, game, disconnect-recovery, browser, and web-asset suites. The locked 1,024-seed sweep reported cycles `133..133`, @@ -1035,6 +1033,110 @@ still required before this milestone can be marked `COMPLETE`. RAM bytes and 1,028,956 of 2,097,152 application bytes. The matching `buildfs` command passed using 2,031,616 of 2,031,616 LittleFS bytes. `docs/MVP_ACCEPTANCE.md` records version `0.10.0`, build hashes, and the - 19,253-byte reproducible web payload. Human playtest evidence for the - approximately five-minute target remains pending, so Milestone 011 is - `IN_PROGRESS` and Milestone 012 has not started. + 19,253-byte reproducible web payload. +- On 2026-09-08, the project owner confirmed the representative physical + two-player playtests worked as expected with no gameplay defects or balance + issues. The owner explicitly approved an evidence deviation for acceptance + criterion 2: no match count or elapsed-time statistics are required. The + approval, its scope, and the absence of a hard timer are recorded in + `docs/PLAYTEST_REPORT.md`; criterion 12 of `MVP.md` is mapped as passing by + that approved deviation in `docs/MVP_ACCEPTANCE.md`. Together with the + deterministic balance evidence, complete mapped MVP evidence, and matching + release-candidate images, this satisfies every Milestone 011 acceptance + criterion. Milestone 011 is `COMPLETE`; Milestone 012 remains `NOT_STARTED`. + +## Milestone 012 — Combinatorial humorous name suggestions + +**Status:** `NOT_STARTED` + +### Objective + +Replace the small fixed set of humorous player-name suggestions with a +deterministic, varied generator that combines a Russian adjective and noun in +the manner of Docker's random container names. + +### Scope + +- Define bounded Russian adjective and noun vocabularies suitable for the + player-facing lobby. +- Generate valid UTF-8 name suggestions by combining one adjective and one + noun, with a hyphen between them. +- Cycle through the available combinations deterministically before repeating. +- Skip combinations already assigned to a player session. +- Retain the existing bounded response size, protocol shape, and Russian + player-facing error behavior. +- Add deterministic host-side coverage for combination count, cycling, + uniqueness, occupied-name skipping, and valid output bounds. + +### Deliverables + +- Combinatorial humorous-name generator in the authoritative web gateway. +- Portable host tests covering the generator's selection rules. +- Updated protocol/lobby test evidence. + +### Acceptance criteria + +1. Each name suggestion has the form `adjective-noun`, uses valid UTF-8, and + satisfies the lobby name-validation limits. +2. The generator provides substantially more combinations than the previous + five fixed suggestions and does not repeat one until its configured + combination set has been traversed. +3. A currently occupied player name is never suggested. +4. Exhaustion returns the existing bounded Russian `no_suggestion` error. +5. All existing host tests and the targeted generator tests pass. +6. The firmware builds and remains within the factory partition budget. + +### Evidence + +Completion evidence is not yet available. Expected evidence includes the +targeted host-test output, `bash scripts/run_host_tests.sh`, and +`/home/sasa/.platformio/penv/bin/pio run -e esp32-c6-devkitm-1` output with +the final application-size report. + +## Milestone 013 — Random humorous login headlines + +**Status:** `NOT_STARTED` + +### Objective + +Make the login screen feel more lively by selecting a humorous Russian +headline at random whenever a player opens the page. + +### Scope + +- Expand the login screen's bounded set of player-facing Russian humorous + headlines. +- Select one headline using browser-provided randomness when the login page is + initialized. +- Provide a safe fallback when strong browser randomness is unavailable. +- Preserve the existing responsive layout, accessibility semantics, and static + asset-size constraints. +- Add deterministic browser tests by injecting or stubbing the random source. + +### Deliverables + +- Expanded login-headline vocabulary in the browser application. +- Random headline selection with a bounded fallback. +- Browser tests for selection, fallback behavior, and visible Russian copy. + +### Acceptance criteria + +1. The login screen has a substantially expanded set of humorous Russian + headlines, all appropriate for player-facing UI. +2. On separate page initializations, the application selects a headline from + the configured set using browser-provided randomness rather than a fixed + sequence. +3. If the preferred random source is unavailable or fails, the login screen + still displays a valid configured headline. +4. The selected headline remains readable and does not break the login layout + at the responsive sizes defined in `docs/UI_STYLE.md`. +5. Targeted browser tests and `bash scripts/run_host_tests.sh` pass. +6. The regenerated web asset is deterministic for a given source tree and + remains within the LittleFS payload budget. + +### Evidence + +Completion evidence is not yet available. Expected evidence includes targeted +browser-test output, `bash scripts/run_host_tests.sh`, and the reproducible +web-asset size and hash report from +`/home/sasa/.platformio/penv/bin/pio run -e esp32-c6-devkitm-1 --target buildfs`. diff --git a/docs/MVP_ACCEPTANCE.md b/docs/MVP_ACCEPTANCE.md index 9cde5fb..c42b8d9 100644 --- a/docs/MVP_ACCEPTANCE.md +++ b/docs/MVP_ACCEPTANCE.md @@ -17,7 +17,7 @@ unrecorded assumptions. | 9. Artifact and compass rules | Host game-mechanics tests covering ten successful moves and role-specific compass projections. | Passing. | | 10. Victory and draw window | Host game-mechanics test covering outward exit and 200 ms draw boundary. | Passing. | | 11. Disconnect recovery | Host disconnect-recovery tests and Milestone 009 physical acceptance evidence. | Passing. | -| 12. Approximately five-minute normal match | `docs/PLAYTEST_REPORT.md` must contain at least five completed representative matches. | Pending. | +| 12. Approximately five-minute normal match | Project-owner-confirmed representative physical playtests; the owner explicitly approved omitting match counts and timing statistics, recorded in `docs/PLAYTEST_REPORT.md`. | Passing by approved deviation. | | 13. Russian offline UI and browser coverage | Milestone 008 owner checks in Chrome 152, Firefox 155, Safari 26.6, and Edge 152.0.4191.53; asset verification enforces the offline and 1.5 MiB budget. | Passing; repeat asset check for release candidate. | ## Release-candidate record @@ -28,12 +28,12 @@ digest from the final candidate below. This record must match the tested image. | Field | Release-candidate value | | --- | --- | -| Date | 2026-09-08 (pre-playtest candidate) | +| Date | 2026-09-08 | | Application version | 0.10.0 | | Firmware build command and size | `pio run -e esp32-c6-devkitm-1`; 1,028,956 / 2,097,152 application bytes; `firmware.bin` 1,029,584 bytes, SHA-256 `e654643cb9f16ec03c8d54d981da32ab8e64616f99d23d4a6bb14c8ac7f69c17` | | LittleFS build command and size | `pio run -e esp32-c6-devkitm-1 --target buildfs`; 2,031,616 / 2,031,616 bytes; SHA-256 `526e2d03ca4473adb0fe075f4b075aaaeec85ef982240f6578e8cbbb4bec7f35` | | Web asset digest and compressed size | `8f3207a208c26aa9f0faff0b0fd8db8e8f8e44537bd6db2c0f914ca5f352920a`; 19,253 / 1,572,864 bytes | -| Approved deviations | None recorded | +| Approved deviations | Criterion 12: omit playtest count and timing statistics; project owner confirmed representative physical playtests passed without issues. | -No deviation from `MVP.md` has been approved. A pending item is not passing -evidence and must not be treated as release acceptance. +No pending criterion is treated as passing evidence. The only approved +deviation is recorded above. diff --git a/docs/PLAYTEST_REPORT.md b/docs/PLAYTEST_REPORT.md index f50959c..96d6d56 100644 --- a/docs/PLAYTEST_REPORT.md +++ b/docs/PLAYTEST_REPORT.md @@ -22,19 +22,17 @@ tests after any parameter change. ## Results -No representative completed human matches have been recorded yet. - -| Run | Date | Seed or map hash | Player experience | Result | Elapsed | Artifact / compass use | Defects or balance notes | -| --- | --- | --- | --- | --- | --- | --- | --- | -| 1 | Pending | Pending | Pending | Pending | Pending | Pending | Pending | -| 2 | Pending | Pending | Pending | Pending | Pending | Pending | Pending | -| 3 | Pending | Pending | Pending | Pending | Pending | Pending | Pending | -| 4 | Pending | Pending | Pending | Pending | Pending | Pending | Pending | -| 5 | Pending | Pending | Pending | Pending | Pending | Pending | Pending | +On 2026-09-08, the project owner confirmed that the representative physical +two-player playtests covered by this protocol worked as expected, with no +gameplay defects or balance issues observed. The owner explicitly approved a +deviation from the protocol's count and elapsed-time statistics: individual +match timing, seed or hash, and per-run fields are not required for MVP +acceptance. No hard match timer was introduced. ## Assessment -Pending the five completed matches above. This document must state the -observed range and median, whether the five-minute target was met without a -timer, and whether any tuning change or approved deviation is required before -Milestone 011 can be complete. +The project owner accepted the approximately five-minute target based on the +representative playtests above and approved the absence of a quantified timing +sample. This is an approved evidence deviation, not a claim of statistical +measurement. The locked configuration remains unchanged because no issue was +reported.