docs: add spec, plan, and task breakdown for issue #4

Pedagogical validation message rewrite across 17 English lesson
modules and 5 localized variants (ar, de, es, pl, uk).

specs/004-pedagogical-messages/plan.md

@@ -0,0 +1,87 @@
+# Implementation Plan
+
+## 1. Objective
+
+Rewrite all answer-revealing validation error messages across lesson JSON files to use pedagogical hints (concept questions, property-name nudges, directional guidance) instead of literal CSS solutions. This eliminates the fail-then-copy anti-pattern and promotes genuine learning.
+
+## 2. Approach
+
+**Phase-based, content-first strategy:**
+
+1. Define a message style guide with 3 hint categories:
+   - **Concept question:** "Which property adds space inside an element?" (for property discovery)
+   - **Property hint:** "Check the `padding` property" (when the property is known but value is wrong)
+   - **Directional nudge:** "The items need to wrap to the next line" (for layout concepts)
+
+2. Rewrite English priority modules first (flexbox, box-model, colors, positioning) — these are 100% answer-revealing and form the template for all other rewrites.
+
+3. Rewrite remaining English modules, reusing the same hint patterns established in step 2.
+
+4. Update localized variants with equivalent pedagogical messages in each target language (ar, de, es, pl, uk), translating the English hints while preserving natural phrasing in each language.
+
+5. Run `npm run format.lessons` to ensure consistent formatting, then run tests.
+
+## 3. File Mapping
+
+### Files to modify (message field only, no validation logic changes):
+
+**English priority (create → N/A, modify → 4, delete → N/A):**
+- `lessons/flexbox.json` — modify 6 messages
+- `lessons/01-box-model.json` — modify 10 messages
+- `lessons/03-colors.json` — modify 4 messages
+- `lessons/12-positioning.json` — modify 5 messages
+
+**English remaining (modify → 13):**
+- `lessons/00-basics.json` — modify 4 messages
+- `lessons/00-basic-selectors.json` — modify 15 messages
+- `lessons/01-advanced-selectors.json` — modify 8 messages
+- `lessons/04-typography.json` — modify 1 message
+- `lessons/05-units-variables.json` — modify 3 messages
+- `lessons/06-transitions-animations.json` — modify 8 messages
+- `lessons/07-layouts.json` — modify 8 messages
+- `lessons/08-responsive.json` — modify 8 messages
+- `lessons/09-gradients.json` — modify 3 messages
+- `lessons/10-tailwind-basics.json` — modify 16 messages
+- `lessons/11-filters.json` — modify 4 messages
+- `lessons/13-pseudo-elements.json` — modify 4 messages
+- `lessons/grid.json` — modify 5 messages
+
+**Localized variants (modify):**
+- `lessons/ar/flexbox.json`, `lessons/ar/01-box-model.json`, + other ar/ modules with answer-revealing messages
+- `lessons/de/flexbox.json`, `lessons/de/01-box-model.json`, + other de/ modules
+- `lessons/es/flexbox.json`, `lessons/es/01-box-model.json`, + other es/ modules
+- `lessons/pl/flexbox.json`, `lessons/pl/01-box-model.json`, + other pl/ modules
+- `lessons/uk/flexbox.json`, `lessons/uk/01-box-model.json`, + other uk/ modules
+
+**No new files or deleted files.**
+
+## 4. Architecture Decisions
+
+1. **Message-only changes:** Only the `"message"` string within validation objects is modified. The `type`, `value`, and `options` fields remain untouched. This preserves all validation logic.
+
+2. **No code changes to validator.js:** The validator reads the `message` field as a passthrough string for display. No runtime changes needed.
+
+3. **Hint style per validation type:**
+   - `property_value` validations → concept question or property hint (since the property and value are tested programmatically, the message should teach the concept, not repeat the answer)
+   - `regex` validations → directional nudge describing the expected pattern conceptually
+   - `contains` / `contains_class` validations → concept question about what to include
+
+4. **Localization approach:** Each localized message should be a natural translation of the English pedagogical hint, not a word-for-word translation. The hint category (question, nudge, property hint) should match the English version.
+
+5. **Preserve `<kbd>` tags selectively:** `<kbd>` tags may still be used for property names (e.g., "Check the `<kbd>padding</kbd>` property") but never for complete property-value pairs that reveal the answer.
+
+## 5. Risks
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| Pedagogical hints are too vague, frustrating learners | Medium | Each hint should name the relevant CSS property or concept — just not the exact value. The task description already provides context. |
+| Localized translations lose pedagogical intent | Medium | Use consistent hint categories across languages. Review each language for natural phrasing. |
+| Existing tests assert on specific message text | Low | Check test files for hardcoded message assertions before changing. Adjust tests if needed. |
+| Formatting inconsistency after bulk edits | Low | Run `npm run format.lessons` after all changes. |
+
+## 6. Testing Strategy
+
+1. **Existing test suite:** Run `npm run test` to verify no regressions. The validator tests should pass since validation logic is unchanged.
+2. **Grep audit:** After changes, grep all lesson files for remaining "Set <kbd>" patterns to confirm none were missed.
+3. **JSON validity:** Ensure all modified JSON files parse correctly (the format.lessons command will catch syntax errors).
+4. **Manual spot-check:** Verify a few lessons in the dev server to confirm messages display correctly in the UI.

specs/004-pedagogical-messages/spec.md

@@ -0,0 +1,50 @@
+# fix: validation error messages reveal the solution instead of guiding learning
+
+**Issue:** [#4](https://git.librete.ch/libretech/code-crispies/issues/4)
+**Repository:** libretech/code-crispies
+**Author:** libretech
+**State:** open
+**Labels:** none
+
+## Issue Body
+
+Pedagogy audit: 88% of exercises reveal the answer in error messages, creating a fail-then-copy loop. Change validation messages from 'Set padding: 1rem' to 'Which property adds space between content and the element edge?' This applies across all modules — start with flexbox, box-model, and colors (the 3 worst offenders).
+
+## Acceptance Criteria
+
+1. Validation error messages in **flexbox**, **box-model**, and **colors** modules must no longer reveal the exact CSS property-value answer
+2. Replacement messages should use pedagogical hints: concept questions, property-name hints, or directional guidance — never the literal solution
+3. All remaining English lesson modules with answer-revealing messages must also be rewritten
+4. Localized variants (ar/, de/, es/, pl/, uk/) of affected modules must be updated with equivalent pedagogical messages in each language
+5. Existing validations (type, value, options) must remain unchanged — only the `"message"` field is modified
+6. All existing tests must continue to pass
+
+## Scope
+
+### English priority modules (100% answer-revealing):
+- `lessons/flexbox.json` — 6 messages
+- `lessons/01-box-model.json` — 10 messages
+- `lessons/03-colors.json` — 4 messages
+- `lessons/12-positioning.json` — 5 messages
+
+### English remaining modules (partial answer-revealing):
+- `lessons/00-basics.json` — 4 of 26
+- `lessons/00-basic-selectors.json` — 15 of 18
+- `lessons/01-advanced-selectors.json` — 8 of 49
+- `lessons/04-typography.json` — 1 of 9
+- `lessons/05-units-variables.json` — 3 of 5
+- `lessons/06-transitions-animations.json` — 8 of 13
+- `lessons/07-layouts.json` — 8 of 11
+- `lessons/08-responsive.json` — 8 of 10
+- `lessons/09-gradients.json` — 3 of 7
+- `lessons/10-tailwind-basics.json` — 16 of 17
+- `lessons/11-filters.json` — 4 of 7
+- `lessons/13-pseudo-elements.json` — 4 of 8
+- `lessons/grid.json` — 5 of 9
+
+### Localized variants (each language directory):
+- `lessons/ar/` — Arabic
+- `lessons/de/` — German
+- `lessons/es/` — Spanish
+- `lessons/pl/` — Polish
+- `lessons/uk/` — Ukrainian

specs/004-pedagogical-messages/tasks.md

@@ -0,0 +1,39 @@
+# Tasks
+
+## Phase 1: Preparation
+- [ ] Task 1.1: Audit existing tests for hardcoded validation message assertions; note any that need updating
+- [ ] Task 1.2: Read each priority English module and draft replacement messages using the hint style guide (concept question / property hint / directional nudge)
+
+## Phase 2: English Priority Modules (100% answer-revealing)
+- [ ] Task 2.1: Rewrite validation messages in `lessons/flexbox.json` (6 messages) [P]
+- [ ] Task 2.2: Rewrite validation messages in `lessons/01-box-model.json` (10 messages) [P]
+- [ ] Task 2.3: Rewrite validation messages in `lessons/03-colors.json` (4 messages) [P]
+- [ ] Task 2.4: Rewrite validation messages in `lessons/12-positioning.json` (5 messages) [P]
+
+## Phase 3: English Remaining Modules
+- [ ] Task 3.1: Rewrite messages in `lessons/00-basic-selectors.json` (15 messages) [P]
+- [ ] Task 3.2: Rewrite messages in `lessons/00-basics.json` (4 messages) [P]
+- [ ] Task 3.3: Rewrite messages in `lessons/01-advanced-selectors.json` (8 messages) [P]
+- [ ] Task 3.4: Rewrite messages in `lessons/04-typography.json` (1 message) [P]
+- [ ] Task 3.5: Rewrite messages in `lessons/05-units-variables.json` (3 messages) [P]
+- [ ] Task 3.6: Rewrite messages in `lessons/06-transitions-animations.json` (8 messages) [P]
+- [ ] Task 3.7: Rewrite messages in `lessons/07-layouts.json` (8 messages) [P]
+- [ ] Task 3.8: Rewrite messages in `lessons/08-responsive.json` (8 messages) [P]
+- [ ] Task 3.9: Rewrite messages in `lessons/09-gradients.json` (3 messages) [P]
+- [ ] Task 3.10: Rewrite messages in `lessons/10-tailwind-basics.json` (16 messages) [P]
+- [ ] Task 3.11: Rewrite messages in `lessons/11-filters.json` (4 messages) [P]
+- [ ] Task 3.12: Rewrite messages in `lessons/13-pseudo-elements.json` (4 messages) [P]
+- [ ] Task 3.13: Rewrite messages in `lessons/grid.json` (5 messages) [P]
+
+## Phase 4: Localized Variants
+- [ ] Task 4.1: Update Arabic (ar/) localized modules with pedagogical messages [P]
+- [ ] Task 4.2: Update German (de/) localized modules with pedagogical messages [P]
+- [ ] Task 4.3: Update Spanish (es/) localized modules with pedagogical messages [P]
+- [ ] Task 4.4: Update Polish (pl/) localized modules with pedagogical messages [P]
+- [ ] Task 4.5: Update Ukrainian (uk/) localized modules with pedagogical messages [P]
+
+## Phase 5: Validation & Polish
+- [ ] Task 5.1: Run `npm run format.lessons` to ensure JSON formatting consistency
+- [ ] Task 5.2: Run `npm run test` and fix any test failures related to message text assertions
+- [ ] Task 5.3: Grep audit — verify no "Set <kbd>" answer-revealing patterns remain in any lesson file
+- [ ] Task 5.4: Spot-check a few lessons via `npm start` to confirm messages render correctly in the UI