fix word distribution

CLAUDE.md

@@ -35,6 +35,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these k
 
 ## Core Gameplay
 - 8x6 grid with 6 hidden words (one per row, horizontal only)
+- **Word composition:** 2 four-letter words, 2 five-letter words, 2 six-letter words
 - No scope/radar visualization
 - Players start by choosing 2 letters; all instances are revealed
 - Players click cells to reveal letters or empty spaces
@@ -168,6 +169,7 @@ wrdler/
 
 ### Puzzle Generation
 - Horizontal-only word placement (one per row in 8×6 grid)
+- **Word length distribution:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
 - Deterministic seeding support for reproducible puzzles
 - No word spacing configuration (fixed one word per row)
 - Validation ensures no overlaps, proper bounds, correct word distribution
@@ -395,6 +397,7 @@ The dataset repository will contain:
 - **No vertical word placement** - horizontal only ("H" direction)
 - **Fixed grid dimensions** - always 8x6 (grid_cols=8, grid_rows=6)
 - **One word per row** - exactly 6 words total
+- **Word length requirement** - exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words per puzzle
 - **Free letters tracked** - `free_letters` set and `free_letters_used` counter
 - **Auto-completion** - words auto-marked when all letters revealed
 - **Incorrect guess limit** - maximum 10 per game
@@ -481,3 +484,6 @@ See README.md for complete changelog.
 **Last Updated:** 2025-01-31
 **Current Version:** 0.0.4
 **Status:** Production Ready - All Features Complete ✅
+
+## Test File Location
+All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.

GAMEPLAY_GUIDE.md

@@ -13,6 +13,7 @@ Wrdler is a simplified vocabulary puzzle game where you discover 6 hidden words
 ### The Grid
 - **Size:** 8 columns × 6 rows (48 cells total)
 - **Words:** 6 hidden words, one per row
+  - **Composition:** Exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
 - **Direction:** All words are horizontal (left to right)
 - **Goal:** Discover all 6 words before revealing all their letters
 

README.md

@@ -32,6 +32,7 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 
 ### Core Gameplay
 - 8x6 grid with six hidden words (one per row, all horizontal)
+- **Word composition:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
 - Game starts with 2 free letter guesses; all instances of chosen letters are revealed
 - Reveal grid cells and guess words for points
 - Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
@@ -163,6 +164,9 @@ CRYPTO_PK=                             # Reserved for future signing
 - `specs/` – documentation (`specs.md`, `requirements.md`)
 - `tests/` – unit tests
 
+## Test File Location
+All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.
+
 ## How to Play
 
 1. **Start with 2 free letter guesses** - choose two letters to reveal all their instances in the grid.

specs/requirements.md

@@ -96,7 +96,8 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 **Acceptance:** ✅ Loading function returns lists by length with >= 25 words per length
 
 ### 3) Puzzle Generation (8x6 Horizontal) ✅ (Sprint 2)
-- ✅ Randomly place 6 words (mix of 4, 5, 6-letter) on 8x6 grid, one per row
+- ✅ Randomly place 6 words on 8x6 grid, one per row
+- ✅ **Word length requirement:** Each puzzle must have exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
 - ✅ Constraints:
   - Horizontal (left→right) only
   - One word per row (no stacking)
@@ -204,3 +205,6 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 **Last Updated:** 2025-01-31
 **Version:** 0.0.2
 **Status:** All Features Complete - Ready for Deployment 🚀
+
+## Test File Location
+All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.

specs/specs.md

@@ -19,6 +19,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key
 - 8 x 6 grid
 - Six hidden words:
   - One word per row (row 0-5)
+  - **Word composition:** Exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
   - All placed horizontally (left-right)
   - No vertical placement
   - No diagonal placement
@@ -112,6 +113,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key
 - No duplicate word texts are selected
 - Horizontal-only word placement
 - One word per row in 8x6 grid
+- **Word length distribution:** Each puzzle must contain exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
 - No word spacing configuration (fixed one word per row)
 
 ## Entry Point
@@ -193,3 +195,6 @@ All 7 sprints complete, 100% test coverage (25/25 tests passing):
 
 ## Copyright
 Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
+
+## Test File Location
+All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.

tests/test_word_distribution.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Quick test to verify word length distribution in generated puzzles."""
+
+from wrdler.generator import generate_puzzle
+from wrdler.word_loader import load_word_list
+
+def test_word_distribution():
+    """Test that puzzles have 2 four-letter, 2 five-letter, and 2 six-letter words."""
+    print("Testing word distribution in generated puzzles...")
+
+    # Load word list
+    words_by_len = load_word_list()
+    print(f"Loaded words: {len(words_by_len[4])} 4-letter, {len(words_by_len[5])} 5-letter, {len(words_by_len[6])} 6-letter")
+
+    # Generate 5 test puzzles
+    for i in range(5):
+        puzzle = generate_puzzle(grid_rows=6, grid_cols=8, words_by_len=words_by_len)
+
+        # Count word lengths
+        length_counts = {4: 0, 5: 0, 6: 0}
+        for word in puzzle.words:
+            length = len(word.text)
+            if length in length_counts:
+                length_counts[length] += 1
+
+        # Verify distribution
+        assert length_counts[4] == 2, f"Puzzle {i+1}: Expected 2 four-letter words, got {length_counts[4]}"
+        assert length_counts[5] == 2, f"Puzzle {i+1}: Expected 2 five-letter words, got {length_counts[5]}"
+        assert length_counts[6] == 2, f"Puzzle {i+1}: Expected 2 six-letter words, got {length_counts[6]}"
+
+        # Print puzzle info
+        words_str = ", ".join([f"{w.text}({len(w.text)})" for w in puzzle.words])
+        print(f"✓ Puzzle {i+1}: {words_str}")
+
+    print("\n✅ All tests passed! Word distribution is correct.")
+
+if __name__ == "__main__":
+    test_word_distribution()

wrdler/__init__.py

@@ -8,5 +8,5 @@ Key differences from BattleWords:
 - 2 free letter guesses at game start
 """
 
-__version__ = "0.0.5"
+__version__ = "0.0.6"
 __all__ = ["models", "generator", "logic", "ui", "word_loader"]

wrdler/generator.py

@@ -58,8 +58,8 @@ def generate_puzzle(
     Wrdler Specifications:
     - 6 rows × 8 columns grid
     - 6 words total (one per row)
+    - **Word distribution:** 2 four-letter words, 2 five-letter words, 2 six-letter words
     - All words horizontal only
-    - Word lengths: 3-8 letters (must fit in 8 columns)
     - No vertical words, no overlaps
 
     Parameters
@@ -117,27 +117,27 @@ def generate_puzzle(
                 raise ValueError(f"Word '{word}' too short (minimum 3 letters)")
         selected_words = [w.upper() for w in target_words]
     else:
-        # Normal random word selection - select 6 words that fit in grid_cols
+        # Normal random word selection - select 6 words with required distribution
+        # Wrdler requires: 2 four-letter words, 2 five-letter words, 2 six-letter words
         words_by_len = words_by_len or load_word_list()
 
-        # Determine word lengths that fit (3 to grid_cols, typically 3-8)
-        valid_lengths = list(range(3, min(grid_cols + 1, 9)))  # 3-8 for 8-column grid
+        # Validate we have enough words in each required length
+        required_lengths = [4, 5, 6]
+        for length in required_lengths:
+            if length not in words_by_len or len(words_by_len[length]) < 2:
+                raise RuntimeError(
+                    f"Insufficient {length}-letter words (need at least 2, found {len(words_by_len.get(length, []))})"
+                )
 
-        # Build pools of valid-length words
-        all_valid_words: List[str] = []
-        for L in valid_lengths:
-            if L in words_by_len:
-                all_valid_words.extend(words_by_len[L])
+        # Select 2 words from each length pool
+        selected_words: List[str] = []
+        for length in required_lengths:
+            pool = list(dict.fromkeys(words_by_len[length]))  # Deduplicate
+            rng.shuffle(pool)
+            selected_words.extend(pool[:2])  # Take 2 words from this length
 
-        if len(all_valid_words) < 6:
-            raise RuntimeError(f"Insufficient words available (need 6, found {len(all_valid_words)})")
-
-        # Deduplicate and shuffle
-        unique_words = list(dict.fromkeys(all_valid_words))
-        rng.shuffle(unique_words)
-
-        # Select 6 words
-        selected_words = unique_words[:6]
+        # Shuffle the selected 6 words to randomize their order in the grid
+        rng.shuffle(selected_words)
 
     # Wrdler placement algorithm: one word per row, horizontal only
     # Shuffle row order for variety
@@ -217,7 +217,7 @@ def validate_puzzle(
     3. One word per row
     4. All cells within grid bounds
     5. No overlapping cells
-    6. Word lengths valid (3-8 letters for 8-column grid)
+    6. Word length distribution: exactly 2 four-letter, 2 five-letter, 2 six-letter words
     """
     # Handle legacy grid_size parameter
     if grid_size is not None:
@@ -244,7 +244,10 @@ def validate_puzzle(
 
     # 4. Check bounds and overlaps
     seen: set[Coord] = set()
+    word_lengths: list[int] = []
     for w in puzzle.words:
+        word_lengths.append(len(w.text))
+
         # Check word length
         if len(w.text) < 3:
             raise AssertionError(f"Word '{w.text}' too short (< 3 letters)")
@@ -261,6 +264,23 @@ def validate_puzzle(
                 raise AssertionError(f"Overlapping cell detected: {c}")
             seen.add(c)
 
+    # 5. Check word length distribution (Wrdler requirement)
+    # Must have exactly: 2 four-letter, 2 five-letter, 2 six-letter words
+    length_counts = {4: 0, 5: 0, 6: 0}
+    for length in word_lengths:
+        if length in length_counts:
+            length_counts[length] += 1
+        else:
+            raise AssertionError(f"Invalid word length {length} (must be 4, 5, or 6)")
+
+    if length_counts[4] != 2:
+        raise AssertionError(f"Must have exactly 2 four-letter words, got {length_counts[4]}")
+    if length_counts[5] != 2:
+        raise AssertionError(f"Must have exactly 2 five-letter words, got {length_counts[5]}")
+    if length_counts[6] != 2:
+        raise AssertionError(f"Must have exactly 2 six-letter words, got {length_counts[6]}")
+
+
     # Note: Spacer rules not needed for Wrdler since words are on different rows
     # They cannot touch each other (minimum 1 row separation)