@@ -0,0 +1,942 @@
# Critical Fixes + Quality Refactoring
## TL;DR
> **Quick Summary**: Replace all `Math.random()` calls with a shared cryptographically secure `crypto.getRandomValues()` wrapper, deduplicate the dice engine by importing `src/lib/dice-engine.ts`, extract reusable Astro components for result/copy UI, and refactor all 28 generators to consume the new shared patterns. Fix CI to gate deployment on passing tests and lint.
>
> **Deliverables**:
> - `src/lib/client/random.ts` + test (crypto wrapper)
> - `src/lib/client/i18n.ts` + test (client locale helper)
> - `src/components/ResultBox.astro` (reusable result container)
> - `src/components/CopyButton.astro` (reusable copy button using existing `CopyFeedback`)
> - 28 refactored generators using new utilities
> - `DiceGenerator.astro` importing from `dice-engine.ts`
> - Updated `dice-engine.ts` using crypto wrapper
> - Updated Privacy Policy translations
> - Fixed `.github/workflows/deploy.yml`
>
> **Estimated Effort**: Large
> **Parallel Execution**: YES - 5-7 tasks per wave
> **Critical Path**: Wave 1 (utilities) → Wave 2 (components) → Waves 3-6 (generator batches) → Wave 7 (dice + policy) → Wave 8 (CI) → F1-F4
---
## Context
### Original Request
User wants to fix critical issues and quality-refactor all generators into an easily extensible structure. No push to main without permission.
### Interview Summary
**Key Decisions**:
- Critical scope: Dice engine + honesty (Web Crypto API migration)
- Tests: YES - TDD for new utilities, tests-after + agent QA for generators
- Refactor scope: ALL 28 generators
- CI/CD: Fix deploy.yml to run tests and lint
- Quality over speed
### Research Findings
- **28 generators** exist (not 10 as stated in outdated CLAUDE.md)
- **29 files use `Math.random()` ** despite aboutHowItWorks claiming Web Crypto API
- **Dice engine duplicated**: `DiceGenerator.astro:274-958` inlines `src/lib/dice-engine.ts`
- **Copy-paste UI**: Every generator recreates result + copy button DOM
- **Hardcoded i18n**: Strings in generator frontmatter/scripts instead of `translations.ts`
- **Missing `zod` **: Not in `package.json` despite direct import
- **CI gap**: Tests and lint exist but deploy.yml skips them
### Metis Review
**Identified Gaps** (addressed):
- Core objective tightened to single sentence
- Scope IN/OUT explicitly defined
- Test strategy recorded (TDD for utilities)
- Existing utilities inventoried (`clipboard.ts` , `validation.ts` , `animations.ts` )
---
## Work Objectives
### Core Objective
Replace every `Math.random()` call across all 28 generators with a shared cryptographically secure wrapper, deduplicate the dice engine by importing `src/lib/dice-engine.ts` , and refactor all generators to consume the new shared utilities.
### Concrete Deliverables
- `src/lib/client/random.ts` + `random.test.ts`
- `src/lib/client/i18n.ts` + `i18n.test.ts`
- `src/components/ResultBox.astro`
- `src/components/CopyButton.astro`
- All 28 `*Generator.astro` files refactored
- `DiceGenerator.astro` importing from `dice-engine.ts`
- `src/lib/dice-engine.ts` updated to use `random.ts`
- Updated Privacy Policy in `src/i18n/translations.ts`
- Fixed `.github/workflows/deploy.yml`
### Definition of Done
- [ ] `npm run test` passes (new + existing tests)
- [ ] `npm run lint` passes
- [ ] `npm run build` succeeds
- [ ] No `Math.random()` calls remain in generator scripts
- [ ] Dice engine is imported, not inlined
- [ ] CI runs tests and lint before deploy
### Must Have
- Cryptographically secure random for all generators
- Deduplicated dice engine
- Shared utilities for random + i18n
- Shared Astro components for result/copy UI
- All 28 generators refactored
- CI quality gates
### Must NOT Have (Guardrails)
- **NO shared dynamic `[slug].astro` ** for Russian pages (breaks script bundling)
- **NO changes to generator JSON schema** (strict Zod — unknown fields fail build)
- **NO client-side router introduced**
- **NO push to main** without explicit user approval
- **NO removal of existing EN/RU page files** — keep separate files
- **NO over-abstraction** — keep utilities simple and focused
---
## Verification Strategy
> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed.
### Test Decision
- **Infrastructure exists**: YES (vitest v4.1.5 configured)
- **Automated tests**: TDD for utilities, tests-after for generators
- **Framework**: vitest (node environment)
- **TDD workflow**: RED (failing test) → GREEN (minimal impl) → REFACTOR
### QA Policy
Every task MUST include agent-executed QA scenarios.
Evidence saved to `.sisyphus/evidence/task-{N}-{scenario-slug}.{ext}` .
- **Frontend/UI**: Use Playwright — Navigate, interact, assert DOM, screenshot
- **Library/Module**: Use Bash (bun/node REPL) — Import, call functions, compare output
- **API/Config**: Use Bash (grep) — Search patterns, verify absence
---
## Execution Strategy
### Parallel Execution Waves
```
Wave 1 (Foundation - utilities + deps + CI draft, 5 tasks):
├── Task 1: Add zod + typescript to package.json
├── Task 2: Create crypto random utility (TDD)
├── Task 3: Create client i18n helper (TDD)
├── Task 35: Update Privacy Policy translations
└── Task 36: Fix deploy.yml quality gates
Wave 2 (Shared components + dice crypto + CI verify, 4 tasks):
├── Task 4: Create ResultBox.astro
├── Task 5: Create CopyButton.astro
├── Task 34: Update dice-engine.ts to use crypto random
└── Task 37: Verify CI blocks deploy on failure
Wave 3 (Generators batch 1 + dice refactor, 8 tasks):
├── Task 6: Refactor CardGenerator
├── Task 7: Refactor CoinGenerator
├── Task 8: Refactor ColorGenerator
├── Task 9: Refactor CountryGenerator
├── Task 10: Refactor DateGenerator
├── Task 11: Refactor EmojiGenerator
├── Task 12: Refactor FontPairGenerator
└── Task 33: Refactor DiceGenerator to import dice-engine
Wave 4 (Generators batch 2, 7 tasks):
├── Task 13: Refactor GradientGenerator
├── Task 14: Refactor HashGenerator
├── Task 15: Refactor LetterGenerator
├── Task 16: Refactor ListGenerator
├── Task 17: Refactor LoremGenerator
├── Task 18: Refactor LotteryGenerator
└── Task 19: Refactor Magic8BallGenerator
Wave 5 (Generators batch 3, 7 tasks):
├── Task 20: Refactor MealGenerator
├── Task 21: Refactor NamesGenerator
├── Task 22: Refactor NumberGenerator
├── Task 23: Refactor PaletteGenerator
├── Task 24: Refactor PasswordGenerator
├── Task 25: Refactor RpsGenerator
└── Task 26: Refactor ShufflerGenerator
Wave 6 (Generators batch 4, 6 tasks):
├── Task 27: Refactor TeamsGenerator
├── Task 28: Refactor TimeGenerator
├── Task 29: Refactor UuidGenerator
├── Task 30: Refactor WeightedGenerator
├── Task 31: Refactor WheelSpinner
└── Task 32: Refactor YesNoGenerator
Wave FINAL (After ALL tasks - 4 parallel reviews):
├── Task F1: Plan compliance audit (oracle)
├── Task F2: Code quality review (unspecified-high)
├── Task F3: Real manual QA (unspecified-high)
└── Task F4: Scope fidelity check (deep)
-> Present results -> Get explicit user okay
Critical Path: Wave 1 → Wave 2 → Waves 3-6 → F1-F4
Parallel Speedup: ~70% faster than sequential
Max Concurrent: 8 (Wave 3)
```
### Dependency Matrix
- **1**: - - 2, 3
- **2**: - - 4, 5, 34
- **3**: - - 4, 5, 6-32
- **4**: 2, 3 - 6-33
- **5**: 2, 3 - 6-33
- **6-32**: 4, 5 - F1-F4
- **33**: 4, 5, 34 - F1-F4
- **34**: 2 - 33, F1-F4
- **35**: - - F1-F4
- **36**: - - 37, F1-F4
- **37**: 36 - F1-F4
### Agent Dispatch Summary
- **Wave 1**: Tasks 1-3, 35, 36 → `quick` (deps + TDD utilities + CI draft + policy)
- **Wave 2**: Tasks 4-5, 34, 37 → `visual-engineering` + `deep` + `quick`
- **Waves 3-6**: Tasks 6-33 → `unspecified-high` ×
- **FINAL**: F1-F4 → `oracle` , `unspecified-high` , `deep`
---
## TODOs
- [x] 1. Add missing dependencies to package.json
**What to do ** :
- Add `zod` to `dependencies` (imported but missing)
- Add `typescript` to `devDependencies` (Astro projects need it)
- Run `npm install` to update lockfile
**Must NOT do ** :
- Change existing dependency versions
- Remove existing packages
**Recommended Agent Profile ** :
- **Category**: `quick`
**Parallelization ** :
- **Can Run In Parallel**: YES (with Tasks 2, 3)
- **Blocked By**: None
- **Blocks**: Tasks 2, 3 (npm install should complete)
**References ** :
- `package.json` — current dependency manifest
- `src/lib/generator-schema.ts:1` — `import { z } from "zod"`
**Acceptance Criteria ** :
- [ ] `zod` listed in `dependencies`
- [ ] `typescript` listed in `devDependencies`
- [ ] `npm install` succeeds
**QA Scenarios ** :
```
Scenario: Verify deps installed
Tool: Bash
Steps:
1. grep '"zod"' package.json
2. grep '"typescript"' package.json
3. npm install
Expected Result: Both found, npm install exits 0
Evidence: .sisyphus/evidence/task-1-deps.txt
` ``
**Commit**: YES
- Message: ` fix(deps): add zod and typescript to package.json`
- Files: ` package.json`, ` package-lock.json`
- [x] 2. Create crypto random utility with TDD
**What to do**:
- Create ` src/lib/client/random.ts` with:
- ` randomInt(min: number, max: number): number`
- ` randomFloat(): number`
- ` randomBytes(length: number): Uint8Array`
- ` shuffleArray<T>(array: T[]): T[]`
- Create ` src/lib/client/random.test.ts` with TDD tests
**Must NOT do**:
- Use ` Math.random()` anywhere
**Recommended Agent Profile**:
- **Category**: ` quick`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 1, 3)
- **Blocked By**: None
- **Blocks**: Tasks 4, 5, 6+ (all generators)
**References**:
- ` src/components/generators/NumberGenerator.astro` — uses Math.random
- ` src/components/generators/PasswordGenerator.astro` — uses Math.random
**Acceptance Criteria**:
- [ ] ` src/lib/client/random.ts` exists with all 4 functions
- [ ] ` src/lib/client/random.test.ts` passes
- [ ] No ` Math.random()` in module
**QA Scenarios**:
` ``
Scenario: TDD cycle passes
Tool: Bash
Steps:
1. npm run test -- src/lib/client/random.test.ts
2. grep "Math.random" src/lib/client/random.ts || true
Expected Result: Tests pass, no Math.random
Evidence: .sisyphus/evidence/task-2-random.txt
` ``
**Commit**: YES
- Message: ` feat(lib): add cryptographically secure random utility with tests`
- Files: ` src/lib/client/random.ts`, ` src/lib/client/random.test.ts`
- Pre-commit: ` npm run test -- src/lib/client/random.test.ts`
- [x] 3. Create client i18n helper with TDD
**What to do**:
- Create ` src/lib/client/i18n.ts` with:
- ` getClientLang(): 'en' | 'ru'`
- ` getClientT(): T`
- Create ` src/lib/client/i18n.test.ts`
**Must NOT do**:
- Change ` translations.ts` structure
**Recommended Agent Profile**:
- **Category**: ` quick`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 1, 2)
- **Blocked By**: None
- **Blocks**: Tasks 4, 5, 6+
**References**:
- ` src/i18n/translations.ts` — translation objects
- ` src/components/generators/NumberGenerator.astro` — shows current ` document.documentElement.lang` pattern
**Acceptance Criteria**:
- [ ] ` src/lib/client/i18n.ts` exists
- [ ] ` src/lib/client/i18n.test.ts` passes
**QA Scenarios**:
` ``
Scenario: i18n helper tests pass
Tool: Bash
Steps:
1. npm run test -- src/lib/client/i18n.test.ts
Expected Result: Tests pass
Evidence: .sisyphus/evidence/task-3-i18n.txt
` ``
**Commit**: YES
- Message: ` feat(lib): add client i18n helper with tests`
- Files: ` src/lib/client/i18n.ts`, ` src/lib/client/i18n.test.ts`
- [ ] 4. Create ResultBox.astro shared component
**What to do**:
- Create ` src/components/ResultBox.astro` with:
- ` result: string` prop
- Optional ` label?: string` prop
- Copy button using existing ` CopyFeedback`
- i18n via ` useT(Astro.currentLocale)` in frontmatter
**Must NOT do**:
- Reimplement clipboard logic
- Hardcode English strings
**Recommended Agent Profile**:
- **Category**: ` visual-engineering`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 2, 3, 5)
- **Blocked By**: Tasks 2, 3
- **Blocks**: Tasks 6+
**References**:
- ` src/lib/client/clipboard.ts` — ` CopyFeedback` class
- ` src/components/generators/NumberGenerator.astro` — result + copy DOM pattern
**Acceptance Criteria**:
- [ ] ` src/components/ResultBox.astro` exists
- [ ] Uses ` CopyFeedback`
- [ ] ` npm run build` succeeds
**QA Scenarios**:
` ``
Scenario: ResultBox renders and copies
Tool: Playwright
Preconditions: Dev server running
Steps:
1. Create test page with ResultBox result="test123"
2. Navigate to page
3. Click copy button
4. Assert "Copied" appears
Expected Result: Copy works, i18n labels correct
Evidence: .sisyphus/evidence/task-4-resultbox.png
` ``
**Commit**: YES (groups with Task 5)
- [ ] 5. Create CopyButton.astro shared component
**What to do**:
- Create ` src/components/CopyButton.astro` with:
- ` text: string` prop
- ` label?: string` prop
- Uses ` CopyFeedback`
- i18n via ` useT(Astro.currentLocale)`
**Must NOT do**:
- Include result display logic (that's ResultBox)
**Recommended Agent Profile**:
- **Category**: ` visual-engineering`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 2, 3, 4)
- **Blocked By**: Tasks 2, 3
- **Blocks**: Tasks 6+
**References**:
- ` src/lib/client/clipboard.ts`
- ` src/components/generators/PasswordGenerator.astro`
**Acceptance Criteria**:
- [ ] ` src/components/CopyButton.astro` exists
- [ ] Uses ` CopyFeedback`
- [ ] ` npm run build` succeeds
**QA Scenarios**:
` ``
Scenario: CopyButton works standalone
Tool: Playwright
Steps:
1. Create test page with CopyButton text="hello"
2. Click button
3. Assert "Copied" appears
Expected Result: Button copies, shows feedback
Evidence: .sisyphus/evidence/task-5-copybutton.png
` ``
**Commit**: YES
- Message: ` feat(components): add ResultBox and CopyButton shared components`
- Files: ` src/components/ResultBox.astro`, ` src/components/CopyButton.astro`
- [ ] 6. Refactor CardGenerator.astro
**What to do**:
- Replace ` Math.random()` with ` random.ts` functions
- Replace ` document.documentElement.lang === "ru"` with ` getClientLang()` / ` getClientT()`
- Use ` <CopyButton />` or ` <ResultBox />` where applicable
**Recommended Agent Profile**:
- **Category**: ` unspecified-high`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 7-12, 13-19, 20-26, 27-32)
- **Blocked By**: Tasks 4, 5
**Acceptance Criteria**:
- [ ] No ` Math.random()` in file
- [ ] Uses ` random.ts` and ` i18n.ts`
**QA Scenarios**:
` ``
Scenario: No Math.random in CardGenerator
Tool: Bash
Steps:
1. grep "Math.random" src/components/generators/CardGenerator.astro || true
Expected Result: Empty output
Evidence: .sisyphus/evidence/task-6-card.txt
` ``
**Commit**: NO (groups with batch)
- [ ] 7. Refactor CoinGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 6, 8-12)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**QA Scenarios**: grep Math.random → empty
**Commit**: NO
- [ ] 8. Refactor ColorGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 6-7, 9-12)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**QA Scenarios**: grep Math.random → empty
**Commit**: NO
- [ ] 9. Refactor CountryGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 6-8, 10-12)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**QA Scenarios**: grep Math.random → empty
**Commit**: NO
- [ ] 10. Refactor DateGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 6-9, 11-12)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**QA Scenarios**: grep Math.random → empty
**Commit**: NO
- [ ] 11. Refactor EmojiGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 6-10, 12)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**QA Scenarios**: grep Math.random → empty
**Commit**: NO
- [ ] 12. Refactor FontPairGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 6-11)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**QA Scenarios**: grep Math.random → empty
**Commit**: YES
- Message: ` refactor(generators): migrate batch 1 to crypto random (Card, Coin, Color, Country, Date, Emoji, FontPair)`
- Files: ` src/components/generators/{Card,Coin,Color,Country,Date,Emoji,FontPair}Generator.astro`
- [ ] 13. Refactor GradientGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 14-19, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 14. Refactor HashGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13, 15-19, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 15. Refactor LetterGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-14, 16-19, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 16. Refactor ListGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-15, 17-19, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 17. Refactor LoremGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-16, 18-19, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 18. Refactor LotteryGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-17, 19, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 19. Refactor Magic8BallGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-18, 20-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: YES
- Message: ` refactor(generators): migrate batch 2 to crypto random (Gradient, Hash, Letter, List, Lorem, Lottery, Magic8Ball)`
- Files: ` src/components/generators/{Gradient,Hash,Letter,List,Lorem,Lottery,Magic8Ball}Generator.astro`
- [ ] 20. Refactor MealGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 21-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 21. Refactor NamesGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20, 22-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 22. Refactor NumberGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-21, 23-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 23. Refactor PaletteGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-22, 24-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 24. Refactor PasswordGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-23, 25-26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 25. Refactor RpsGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-24, 26, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 26. Refactor ShufflerGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-25, 27-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: YES
- Message: ` refactor(generators): migrate batch 3 to crypto random (Meal, Names, Number, Palette, Password, Rps, Shuffler)`
- Files: ` src/components/generators/{Meal,Names,Number,Palette,Password,Rps,Shuffler}Generator.astro`
- [ ] 27. Refactor TeamsGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-26, 28-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 28. Refactor TimeGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-26, 27, 29-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 29. Refactor UuidGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-26, 27-28, 30-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 30. Refactor WeightedGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-26, 27-29, 31-32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 31. Refactor WheelSpinner.astro
**What to do**: Same pattern as Task 6. Note: file is ` WheelSpinner.astro`, not ` WheelGenerator.astro`.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-26, 27-30, 32)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: NO
- [ ] 32. Refactor YesNoGenerator.astro
**What to do**: Same pattern as Task 6.
**Recommended Agent Profile**: ` unspecified-high`
**Parallelization**: YES (with Tasks 13-19, 20-26, 27-31)
**Blocked By**: Tasks 4, 5
**Acceptance Criteria**: No Math.random, uses random.ts and i18n.ts
**Commit**: YES
- Message: ` refactor(generators): migrate batch 4 to crypto random (Teams, Time, Uuid, Weighted, WheelSpinner, YesNo)`
- Files: ` src/components/generators/{Teams,Time,Uuid,Weighted,YesNo}Generator.astro`, ` src/components/generators/WheelSpinner.astro`
- [ ] 33. Refactor DiceGenerator to import dice-engine.ts
**What to do**:
- Replace inline dice engine code in ` DiceGenerator.astro:274-958` with imports from ` src/lib/dice-engine.ts`
- Keep same UI and user-facing behavior
- Use ` getClientLang()` / ` getClientT()` for i18n
- Use ` <ResultBox />` / ` <CopyButton />` for result display
**Must NOT do**:
- Modify ` src/lib/dice-engine.ts` in this task (Task 34 does that)
- Change dice notation syntax or features
**Recommended Agent Profile**:
- **Category**: ` deep`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 6-32)
- **Blocked By**: Tasks 4, 5, 34 (needs dice-engine.ts with crypto)
**References**:
- ` src/components/generators/DiceGenerator.astro` — inline dice engine (lines 274-958)
- ` src/lib/dice-engine.ts` — canonical dice engine
**Acceptance Criteria**:
- [ ] ` DiceGenerator.astro` imports from ` dice-engine.ts`
- [ ] File significantly shorter (<300 lines)
- [ ] ` npm run build` succeeds
**QA Scenarios**:
` ``
Scenario: Dice engine imported
Tool: Bash
Steps:
1. grep "import.*dice-engine" src/components/generators/DiceGenerator.astro
2. wc -l src/components/generators/DiceGenerator.astro
Expected Result: Import found, file <300 lines
Evidence: .sisyphus/evidence/task-33-dice-import.txt
` ``
**Commit**: YES
- Message: ` refactor(dice): deduplicate dice engine by importing from lib`
- Files: ` src/components/generators/DiceGenerator.astro`
- [ ] 34. Update dice-engine.ts to use crypto random
**What to do**:
- Replace all ` Math.random()` in ` src/lib/dice-engine.ts` with ` random.ts` functions
- Update ` dice-engine.test.ts` to mock ` random.ts` instead of ` Math.random`
- Ensure all tests pass
**Must NOT do**:
- Change dice notation syntax or parsing
**Recommended Agent Profile**:
- **Category**: ` deep`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 4, 5, 37)
- **Blocked By**: Task 2
- **Blocks**: Task 33
**References**:
- ` src/lib/dice-engine.ts`
- ` src/lib/dice-engine.test.ts`
- ` src/lib/client/random.ts`
**Acceptance Criteria**:
- [ ] No ` Math.random()` in ` dice-engine.ts`
- [ ] Tests pass
**QA Scenarios**:
` ``
Scenario: Dice engine uses crypto
Tool: Bash
Steps:
1. grep "Math.random" src/lib/dice-engine.ts || true
2. npm run test -- src/lib/dice-engine.test.ts
Expected Result: No Math.random, tests pass
Evidence: .sisyphus/evidence/task-34-dice-crypto.txt
` ``
**Commit**: YES
- Message: ` refactor(dice): migrate dice engine to cryptographically secure random`
- Files: ` src/lib/dice-engine.ts`, ` src/lib/dice-engine.test.ts`
- Pre-commit: ` npm run test -- src/lib/dice-engine.test.ts`
- [x] 35. Update Privacy Policy translations
**What to do**:
- Update EN and RU ` aboutHowItWorks` text in ` src/i18n/translations.ts` to accurately describe random generation
- Current RU text (line ~172) claims "Web Crypto API" but must reflect actual usage
- Also update EN equivalent (line ~78)
**Must NOT do**:
- Change other Privacy Policy sections
**Recommended Agent Profile**:
- **Category**: ` writing`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 1, 2, 3, 36)
- **Blocked By**: None
**References**:
- ` src/i18n/translations.ts` — EN aboutHowItWorks (~line 78), RU aboutHowItWorks (~line 172)
**Acceptance Criteria**:
- [ ] EN aboutHowItWorks accurate
- [ ] RU aboutHowItWorks accurate and consistent
**QA Scenarios**:
` ``
Scenario: Privacy text updated
Tool: Read
Steps:
1. Read src/i18n/translations.ts lines 72-82 and 166-176
Expected Result: Text describes crypto.getRandomValues usage
Evidence: .sisyphus/evidence/task-35-privacy.txt
` ``
**Commit**: YES
- Message: ` fix(i18n): update about page for crypto accuracy`
- Files: ` src/i18n/translations.ts`
- [x] 36. Fix deploy.yml quality gates
**What to do**:
- Add ` npm run lint` before ` npm run build`
- Add ` npm run test` before ` npm run build`
- Remove ` -o StrictHostKeyChecking=no` from rsync SSH options
**Must NOT do**:
- Change deploy target or SSH keys
**Recommended Agent Profile**:
- **Category**: ` quick`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 1, 2, 3, 35)
- **Blocked By**: None
- **Blocks**: Task 37
**References**:
- ` .github/workflows/deploy.yml`
- ` package.json` — test and lint scripts
**Acceptance Criteria**:
- [ ] ` npm run lint` runs before build
- [ ] ` npm run test` runs before build
- [ ] No ` StrictHostKeyChecking=no`
**QA Scenarios**:
` ``
Scenario: CI updated
Tool: Read
Steps:
1. grep "npm run lint" .github/workflows/deploy.yml
2. grep "npm run test" .github/workflows/deploy.yml
3. grep "StrictHostKeyChecking" .github/workflows/deploy.yml || true
Expected Result: lint and test found, StrictHostKeyChecking absent
Evidence: .sisyphus/evidence/task-36-ci.txt
` ``
**Commit**: YES
- Message: ` ci(deploy): add test and lint gates, fix SSH security`
- Files: ` .github/workflows/deploy.yml`
- [ ] 37. Verify CI blocks deploy on failure
**What to do**:
- Verify updated ` deploy.yml` workflow syntax
- Confirm deploy does not run if test/lint fails
**Must NOT do**:
- Trigger actual deploy
**Recommended Agent Profile**:
- **Category**: ` quick`
**Parallelization**:
- **Can Run In Parallel**: YES (with Tasks 4, 5, 34)
- **Blocked By**: Task 36
**References**:
- ` .github/workflows/deploy.yml`
**Acceptance Criteria**:
- [ ] Workflow syntax valid
- [ ] Build step after test/lint
**QA Scenarios**:
` ``
Scenario: CI dependencies verified
Tool: Bash
Steps:
1. grep -A5 "npm run test" .github/workflows/deploy.yml
Expected Result: Build comes after test
Evidence: .sisyphus/evidence/task-37-ci-verify.txt
` ``
**Commit**: NO (groups with Task 36)
---
## Final Verification Wave
> 4 review agents run in PARALLEL. ALL must APPROVE. Present consolidated results to user and get explicit "okay" before completing.
- [ ] F1. **Plan Compliance Audit** — ` oracle`
Read the plan end-to-end. For each "Must Have": verify implementation exists. For each "Must NOT Have": search codebase for forbidden patterns — reject with file:line if found. Check evidence files exist. Compare deliverables against plan.
Output: ` Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT: APPROVE/REJECT`
- [ ] F2. **Code Quality Review** — ` unspecified-high`
Run ` tsc --noEmit` + ` eslint .` + ` vitest run`. Review all changed files for: ` as any`/` @ts -ignore`, empty catches, console.log in prod, commented-out code, unused imports. Check AI slop: excessive comments, over-abstraction, generic names.
Output: ` Build [PASS/FAIL] | Lint [PASS/FAIL] | Tests [N pass/N fail] | Files [N clean/N issues] | VERDICT`
- [ ] F3. **Real Manual QA** — ` unspecified-high`
Start from clean state. Execute EVERY QA scenario from EVERY task. Test cross-task integration. Test edge cases: empty state, invalid input. Verify no Math.random() remains (` grep -r "Math.random" src/components/generators/`). Save to ` .sisyphus/evidence/final-qa/`.
Output: ` Scenarios [N/N pass] | Integration [N/N] | Math.random [CLEAN/N found] | VERDICT`
- [ ] F4. **Scope Fidelity Check** — ` deep`
For each task: read "What to do", read actual diff (git log/diff). Verify 1:1 — everything in spec was built, nothing beyond spec was built. Check "Must NOT do" compliance. Detect cross-task contamination. Flag unaccounted changes.
Output: ` Tasks [N/N compliant] | Contamination [CLEAN/N issues] | Unaccounted [CLEAN/N files] | VERDICT`
---
## Commit Strategy
- **Wave 1**: ` fix(deps): add zod and typescript to package.json` + ` feat(lib): add crypto random utility with tests` + ` feat(lib): add client i18n helper with tests` + ` fix(i18n): update privacy policy for crypto accuracy` + ` ci(deploy): add test and lint gates to deploy workflow`
- **Wave 2**: ` feat(components): add ResultBox and CopyButton shared components` + ` refactor(dice): migrate dice engine to cryptographically secure random`
- **Waves 3-6**: ` refactor(generators): migrate batch N to crypto random and shared components`
---
## Success Criteria
### Verification Commands
` ``bash
npm run test # Expected: all pass (utilities + existing dice tests)
npm run lint # Expected: no errors
npm run build # Expected: static build succeeds
grep -r "Math.random" src/components/generators/ # Expected: no matches
grep -r "dice-engine" src/components/generators/DiceGenerator.astro # Expected: import statement
grep "zod" package.json # Expected: found in dependencies
grep "test" .github/workflows/deploy.yml # Expected: found
` ``
### Final Checklist
- [ ] All "Must Have" present
- [ ] All "Must NOT Have" absent
- [ ] All tests pass
- [ ] No ` Math.random()` in generators
- [ ] Dice engine imported, not inlined
- [ ] CI runs tests and lint before deploy
- [ ] User explicitly approved (no auto-push to main)
emil