Randify.pro/.sisyphus/plans/critical-refactor.md

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 × 28 (generator refactoring + dice)
• FINAL: F1-F4 → oracle, unspecified-high, deep

---

TODOs

• 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

• 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

• 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

• 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

• 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

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)