LOGIC GRID REAL DIFFICULTY GENERATION
Date: 2026-07-16
Baseline: PuzzleTools_BASE-2026-07-16c.zip

SUMMARY
Implemented real Easy, Medium and Hard generation for the 4 x 4 Logic Grid Studio.
The difficulty selector is now active. Each level uses a deliberately different structured-clue candidate order, and every final clue set is measured by the solver before acceptance.
Off-target clue sets are rejected deterministically and regenerated from a derived clue-selection seed while preserving the puzzle's reproducible base seed and hidden solution.

DIFFICULTY RULES
Easy
- 8-10 clues
- at least 4 direct-positive clues
- 2-3 cross-category clues
- no more than 2 cross-negative clues
- short propagation chain
- unique and solved without solver branching

Medium
- 8-11 clues
- 3-4 direct-positive clues
- 4-6 cross-category clues
- 1-3 cross-negative clues
- balanced propagation chain
- unique and solved without solver branching

Hard
- 9-11 clues
- no more than 2 direct-positive clues
- at least 5 cross-category clues
- at least 3 cross-negative clues
- longer propagation chain
- unique and solved without solver branching

USER-FACING CHANGES
- Activated Easy / Medium / Hard in Logic Grid Studio.
- The selected difficulty is used for single previews and Web Worker batches.
- Preview identity and generation status show the accepted difficulty.
- Difficulty is stored in Detective Book batches and shown on Book Builder batch cards.
- Existing duplicate prevention, batch cancellation, saved projects and PPTX export remain intact.

ENGINE CHANGES
- Added engine/difficulty-profiles.js with profiles, measurement and evaluation.
- puzzle-generator.js now retries deterministic clue-set variants until the selected profile passes.
- Difficulty metadata stores clue-type counts, propagation rounds, branching and accepted-attempt information.
- Batch and worker results preserve difficulty and count rejected off-target clue sets internally.

AFFECTED FILES
apps/detective/assets/detective-book-builder.js
apps/detective/assets/detective-book-store.js
apps/detective/book-builder.php
apps/detective/logic-grid/ARCHITECTURE.md
apps/detective/logic-grid/engine/README.md
apps/detective/logic-grid/engine/batch-generator.js
apps/detective/logic-grid/engine/difficulty-profiles.js (new)
apps/detective/logic-grid/engine/index.js
apps/detective/logic-grid/engine/puzzle-generator.js
apps/detective/logic-grid/engine/tests/batch-generation-tests.js
apps/detective/logic-grid/engine/tests/book-builder-integration-tests.js
apps/detective/logic-grid/engine/tests/generation-tests.js
apps/detective/logic-grid/engine/tests/worker-integration-tests.js
apps/detective/logic-grid/index.php
apps/detective/logic-grid/integration/book-builder-adapter.js
apps/detective/logic-grid/integration/preview-generation.js
apps/detective/logic-grid/integration/studio-adapter.js
apps/detective/logic-grid/logic-grid-app.js
apps/detective/logic-grid/workers/generation-worker.js
comments/LOGIC_GRID_REAL_DIFFICULTY_GENERATION_2026-07-16.txt

AUTOMATED TESTING
- node apps/detective/logic-grid/engine/tests/run-tests.js
  Result: 63/63 tests passed.
- PHP syntax checks passed for Logic Grid Studio and Detective Book Builder pages.
- JavaScript syntax checks passed for all changed runtime modules.
- Cross-theme batch validation generated 20 Easy, 20 Medium and 20 Hard puzzles for each of the five starter themes (300 puzzles total).
- Every cross-theme puzzle matched its requested solver-measured profile, remained unique and required no solver branching.
- Observed clue-count ranges:
  Easy: 8-10
  Medium: 8-11
  Hard: 9-11

SUGGESTED TESTING
1. Open Logic Grid Studio and confirm Easy, Medium and Hard are selectable.
2. Use the same theme and seed for each level and confirm the clue composition visibly changes:
   - Easy has more direct matches and fewer cross-category clues.
   - Medium has a balanced clue mix.
   - Hard has fewer direct-positive clues and more cross-category negatives.
3. Generate batches of at least 10 puzzles for every level and inspect several Puzzle and Clues previews.
4. Confirm every generated batch completes, duplicate protection remains active and Cancel Generation still stops between puzzles.
5. Add one batch of each difficulty to the Detective Book Builder and confirm Easy / Medium / Hard appears on each batch card.
6. Save and reopen a Detective project, then confirm each batch retains its difficulty.
7. Export PPTX and confirm puzzle/solution layouts and clue wording remain unchanged except for the selected clue-set difficulty.