feat(maze): add deterministic symmetric maze generation

docs/MAZE_GENERATION.md

@@ -0,0 +1,49 @@
+# Maze generation and validation
+
+Milestone 005 provides a portable, deterministic maze component. It does not
+implement movement, visibility projection, inventory, or match behavior from
+later milestones.
+
+## Representation and limits
+
+- Dimensions are runtime configuration values. Supported maps are even-width,
+  even-height rectangles from `8 x 8` through `128 x 64` and contain at most
+  8,192 cells.
+- Each cell uses one byte of four-direction passage flags. A fixed bit set,
+  traversal queue, and distance array form the reusable generation workspace.
+- Starts, keys, boundary exits, compass cells, landmarks, and vision artifacts
+  use bounded fixed arrays. No generation or validation path calls a heap API.
+- The maze plus workspace budget is 64 KiB. The default `128 x 64`
+  configuration targets generation within 250 ms on the ESP32-C6.
+- Candidate regeneration is capped by `maximum_attempts`; failure returns a
+  diagnostic result instead of retrying indefinitely.
+
+## Deterministic construction
+
+The generator builds a seeded randomized depth-first tree in one conceptual
+half and rotates every opened edge by 180 degrees into the other half. It then
+adds a configured number of symmetric cycle edges and symmetric pairs of seam
+connections. This construction retains dead ends while guaranteeing cycles,
+alternative routes, and several ways to cross between halves once validation
+succeeds.
+
+The requested seed and the derived candidate seed are recorded in the maze.
+Using the same configuration and requested seed therefore reproduces the same
+topology, placements, metrics, and hash.
+
+## Placement and validation
+
+Player 2's start and every required object are the exact rotational counterpart
+of Player 1's placement. Starts and exits are boundary cells, and the default
+requires at least 64 cells of Manhattan separation between each start and its
+exit. Keys are selected outside the owners' initial Chebyshev-radius-three
+views. The default places eight landmark pairs and four vision-artifact pairs,
+with no placement collisions.
+
+Validation independently checks reciprocal passages, rotational symmetry,
+full reachability, edge and cycle counts, dead ends, half crossings, placement
+bounds and collisions, initial key visibility, and corresponding route
+distances for keys, exits, compasses, every landmark, and every artifact.
+Reports expose these topology and route metrics for diagnostics and later
+playtesting; geometric distance alone is not treated as proof of search
+difficulty.