todo.md

Alien Obfuscator — Build Todo

Phase 0: Foundation

• Create todo.md tracker
• Scaffold project structure (corpus/, assets/, tests/)
• Write requirements.txt with pinned versions
• Write config.py (model settings, paths, constants)
• Implement corpus/manager.py + 5 theme text files
• Write riddle_generator.py with LLM abstraction layer
• Add mock LLM backend for offline testing
• Write unit tests for corpus loading and prompt templating

Phase 1: Encrypt Mode

• Build Gradio Encrypt tab (message input + theme dropdown)
• Implement prompt builder (corpus excerpt + plaintext + formatting)
• Add JSON response parser + schema validation
• Implement retry logic for malformed JSON
• Build riddle card display (riddle + 5 options + correct answer)
• Add "Copy to Clipboard" button
• Test end-to-end with mock LLM

Phase 2: Solve Mode

• Build Gradio Solve tab (paste text area)
• Implement riddle parser from pasted text
• Build MCQ UI with clickable buttons
• Add correct/wrong feedback animations
• Display original plaintext after solving
• Add "Decrypt another?" reset button
• Test with hardcoded riddle data

Phase 3: Challenge Mode

• Build game_engine.py (timer, scoring, streaks)
• Add game configuration UI (time slider, theme filter, riddle count)
• Implement countdown timer (real-time gr.Timer tick every second, auto game-over at 0)
• Build scoring system (+10 base, +5 speed bonus, +3 streak bonus)
• Add high score persistence (localStorage)
• Test with mocked riddle generator
• Fix game timer not counting down when the browser's tab is not active.

Phase 4: Polish & Integration

• Add custom CSS (dark sci-fi theme, alien monitor)
• Implement Alien Threat Monitor cosmetic element
• Add flavor text across all modes
• Wire real LLM backend into all three modes
• Add timeout guards + fallback error messages
• Test mobile responsiveness (CSS media queries for <768px, stacked columns, full-width buttons)
• Write README.md
• Record demo video + social post

Phase 5: Config Extraction & Bug Fixes

• Create config.yaml with all operational parameters
• Update config.py to load from config.yaml with fallback defaults
• Use config for LLM temperature, timeouts, API URLs
• Use config for mock backend distractors
• Use config for challenge mode phrases
• Use config for app title and launch parameters
• Use PRIMARY_MODEL constant in app.py instead of hardcoded strings
• Fix: _parse_response code fence stripping handles uppercase specifiers (```JSON)
• Fix: _parse_response fallback tries subsequent {...} blocks after a failed parse
• Fix: Solve tab check_answer() — current design cannot validate answers (needs re-architecture)

Phase 6: Corpus → LLM-Generated

• Delete corpus/*.txt static files + corpus/ directory
• Delete corpus_manager.py — no longer needed
• Update RiddleGenerator to drop corpus_manager dependency
• Remove CorpusManager import/usage from app.py and init.py
• Update _build_prompt — LLM draws on its own training knowledge, no static excerpt injected
• Add THEME_KEYS to config.py for challenge mode theme selection
• Delete tests/test_corpus_manager.py
• Update tests/test_riddle_generator.py — remove corpus fixture
• Update plan/gameplan-deepseek.md — corpus now LLM-generated

Phase 7: Final Checks

• Run full test suite (make test) — 29/29 passing
• Run lint + type check (make lint, make ty)
• Verify parameter budget in README
• Deploy to Hugging Face Space
• Submit demo + social post