✨ v2.3.0

.sisyphus/plans/v2.3.0-revised.md

@@ -0,0 +1,132 @@
+# v2.3.0 Backend Stability & Testing - REVISED Plan
+
+**Status:** Ready for Review
+**Created:** 2026-01-23
+**Branch:** `feat/v2.3.0`
+**Target Coverage:** 44.5% → 70-75%
+**Estimated Effort:** 1.5-2 days
+
+---
+
+## REVISION: Middleware Tests Removed
+
+**Removed from scope:**
+- ❌ app/middleware/security.py tests (23 tests)
+- ❌ app/middleware/request_id.py tests (0% coverage remains)
+
+**Reasoning:** Can be addressed in separate security-focused sprint
+
+---
+
+## Revised Core Tasks
+
+### 1. Datetime Deprecation Fix (HIGH PRIORITY) ⏰
+- **Scope:** 68 instances across 21 files
+- **Effort:** 30-60 minutes
+- **Impact:** Removes Python 3.13+ warnings
+- **Quick Win:** ✅ Mechanical replacement, low risk
+
+### 2. Database Layer Testing (HIGH PRIORITY) 💾
+- **Coverage:** 0% → 75%
+- **Tests:** 16 new tests
+- **Effort:** 2-3 hours
+- **Quick Win:** ✅ Straightforward, existing patterns
+
+### 3. Unique Room Verification (MEDIUM PRIORITY) 🏠
+- **Tests:** 8 new tests
+- **Effort:** 1-2 hours
+- **Quick Win:** ✅ Simple API tests, existing logic
+
+### 4. Incident Service Testing (MEDIUM PRIORITY) ⚔️
+- **Coverage:** 28% → 70%
+- **Tests:** 20-25 new tests
+- **Effort:** 6-8 hours
+- **Complexity:** HIGH (session isolation fix required)
+
+### 5. Game Loop Testing (LOWER PRIORITY) ⚙️
+- **Coverage:** 54% → 70%
+- **Tests:** 20-25 new tests
+- **Effort:** 6-8 hours
+- **Complexity:** HIGH (multi-phase orchestration)
+
+---
+
+## Revised Test Count Summary
+
+| Module | Current Tests | New Tests | Total | Coverage Target |
+|--------|--------------|-----------|-------|-----------------|
+| ~~middleware/~~ | ~~0~~ | ~~23~~ | ~~23~~ | ~~Deferred~~ |
+| db/ | 0 | 16 | 16 | 75% |
+| room (unique) | ~15 | 8 | 23 | 95% |
+| incident_service | ~10 (skipped) | 20-25 | 30-35 | 70% |
+| game_loop | ~10 (indirect) | 20-25 | 30-35 | 70% |
+| **TOTAL** | **570** | **64-74** | **634-644** | **70-75%** |
+
+**Revised Coverage Trajectory:** 44.5% → 70-75%
+
+---
+
+## Quick Wins Assessment
+
+### Tier 1: Fastest Wins (Half Day)
+1. **Datetime Fix** - 30-60 min, mechanical, zero risk
+2. **DB Init Tests** - 2-3 hours, straightforward seeding
+3. **Unique Room Tests** - 1-2 hours, simple API validation
+
+**Impact:** ~24 tests added, ~15-20% coverage gain
+
+### Tier 2: Medium Effort (1 Day)
+4. **DB Session Tests** - 2-3 hours, requires async understanding
+5. **Incident Service (Basic)** - 4-6 hours, spawn + basic combat
+
+**Impact:** ~30 additional tests, ~20-25% coverage gain
+
+### Tier 3: Complex (Optional)
+6. **Game Loop Testing** - 6-8 hours, complex orchestration
+7. **Incident Service (Advanced)** - 4-6 hours, spread mechanics, loot
+
+---
+
+## QUESTION: Do You Want Quick Wins First?
+
+Before I finalize this plan, **what's your priority?**
+
+**Option A: Quick Wins Only (Recommended Start)**
+- Focus on Tier 1: Datetime + DB Init + Unique Rooms
+- Get to ~60-65% coverage in half day
+- Low risk, high visibility
+- **Deliverable:** Clean foundation, all easy wins completed
+
+**Option B: Balanced Approach**
+- Tier 1 + Tier 2 (DB + some incident tests)
+- Get to ~70% coverage in 1.5 days
+- Moderate complexity
+- **Deliverable:** Solid coverage, some complex tests
+
+**Option C: Full Sprint**
+- All tiers including game loop
+- Get to ~75% coverage in 2+ days
+- High complexity
+- **Deliverable:** Maximum coverage, all planned work
+
+**Option D: Custom Priority**
+- You tell me what's most important
+- I'll reorganize the plan accordingly
+
+---
+
+## My Recommendation
+
+Start with **Option A (Quick Wins)** to:
+1. Build momentum with easy successes
+2. Verify test infrastructure works smoothly
+3. Identify any blockers early
+4. Deliver visible progress quickly
+
+Then reassess whether to continue with Tier 2/3 based on:
+- Time remaining
+- Complexity encountered
+- Coverage achieved
+- Other priorities
+
+**What do you prefer?**

.sisyphus/plans/v2.3.0-summary.md

@@ -0,0 +1,57 @@
+# v2.3.0 Quick Reference
+
+## Overview
+**Goal:** Backend stability through test coverage (44.5% → 80%) + datetime modernization
+**Effort:** 2-3 days
+**Tests Added:** 102 new tests (570 → 672)
+
+## Four Core Tasks
+
+### 1. Datetime Fix (HIGH) ⏰
+- **What:** Replace 68 `datetime.utcnow()` → `datetime.now(timezone.utc)`
+- **Where:** 21 files (models, services, CRUD, tests)
+- **Why:** Python 3.13+ deprecation warning
+
+### 2. Middleware Testing (HIGH) 🛡️
+- **Coverage:** 0% → 85%
+- **Tests:** 23 new tests
+- **Files:** `test_middleware/test_security.py`, `test_middleware/test_request_id.py`
+- **Focus:** Rate limiting, IP filtering, request tracking
+
+### 3. Database Testing (HIGH) 💾
+- **Coverage:** 0% → 75%
+- **Tests:** 16 new tests
+- **Files:** `test_db/test_session.py`, `test_db/test_init_db.py`
+- **Focus:** Session management, DB seeding
+
+### 4. Service Testing (MEDIUM) ⚙️
+- **Incident Service:** 28% → 75% (25 new tests)
+  - Fix session isolation bug
+  - Combat, spawning, spread mechanics
+- **Game Loop:** 54% → 80% (30 new tests)
+  - Orchestration, all phases
+  - Explorations, training, incidents, breeding
+
+### 5. Unique Room Verification (LOW) 🏠
+- **Tests:** 8 new tests
+- **Purpose:** Verify existing logic works correctly
+- **Focus:** Uniqueness constraints, buildable filtering
+
+## Quick Wins First
+1. Datetime fix (30 min) - mechanical replacement
+2. Middleware tests (2-3 hours) - straightforward mocking
+3. DB tests (2-3 hours) - existing patterns
+4. Service tests (1-2 days) - complex logic
+
+## Key Decisions Needed
+
+1. **Coverage discrepancy:** ROADMAP says 67%, I measured 44.5% - which is correct?
+2. **Test order:** Easy wins (middleware/db) first or complex (services) first?
+3. **Session isolation:** Add `commit()` in tests or fix fixtures?
+4. **anyio migration:** Defer to future version?
+
+## Success Metrics
+- ✅ 672+ tests passing
+- ✅ Coverage ≥ 80%
+- ✅ No datetime warnings
+- ✅ Zero skipped tests (incident service fixed)

.sisyphus/plans/v2.3.0-test-plan-matrix.md

@@ -0,0 +1,154 @@
+# v2.3.0 Test Plan Matrix
+
+## Coverage Targets by Module
+
+| Module | Current | Target | New Tests | Priority | Complexity |
+|--------|---------|--------|-----------|----------|------------|
+| middleware/security.py | 0% | 85% | 15 | HIGH | Low |
+| middleware/request_id.py | 0% | 85% | 8 | HIGH | Low |
+| db/session.py | 0% | 75% | 6 | HIGH | Medium |
+| db/init_db.py | 0% | 75% | 10 | HIGH | Low |
+| services/incident_service.py | 28% | 75% | 25 | MEDIUM | High |
+| services/game_loop.py | 54% | 80% | 30 | MEDIUM | High |
+| api/endpoints/room.py (unique) | ~70% | 95% | 8 | LOW | Low |
+
+## Test Distribution
+
+### By Type
+- **Unit Tests:** 65 (middleware, db, service methods)
+- **Integration Tests:** 30 (game loop phases, incident orchestration)
+- **API Tests:** 8 (unique room endpoints)
+- **Edge Cases:** ~15 (error handling, boundary conditions)
+
+### By Complexity
+- **Simple (1-2 hours):** 40 tests (middleware, db, unique rooms)
+- **Medium (3-5 hours):** 35 tests (incident spawning, game loop phases)
+- **Complex (1-2 days):** 25 tests (combat calculations, multi-phase orchestration)
+
+## Critical Path
+
+```
+Phase 1: Datetime Fix (BLOCKING)
+  └─ Affects all modules, must complete first
+     Estimated: 30 minutes
+
+Phase 2 & 3: Middleware + DB (PARALLEL)
+  ├─ test_middleware/ (3-4 hours)
+  └─ test_db/ (2-3 hours)
+     Estimated: 1 day total
+
+Phase 4: Incident Service (SEQUENTIAL)
+  └─ Fix session isolation first
+     ├─ Session fix (1-2 hours)
+     └─ Add tests (4-6 hours)
+        Estimated: 1 day total
+
+Phase 5: Game Loop (SEQUENTIAL)
+  └─ Depends on understanding incident patterns
+     Estimated: 1 day total
+
+Phase 6: Unique Rooms (OPTIONAL)
+  └─ Can run anytime
+     Estimated: 2-3 hours
+```
+
+## Risk Matrix
+
+| Risk | Phase | Mitigation |
+|------|-------|------------|
+| Datetime changes break timestamps | 1 | Run full test suite after each file update |
+| Session isolation fix causes cascade | 4 | Test one method at a time, have rollback ready |
+| Game loop tests too coupled | 5 | Mock dependencies, test phases independently |
+| Coverage target unrealistic | All | Prioritize critical paths, accept 75% if needed |
+
+## Testing Strategy
+
+### Isolation Levels
+1. **Pure Unit (40%)** - Mock all dependencies
+2. **Service Unit (30%)** - Real DB, mock external services
+3. **Integration (20%)** - Real DB + Redis, mock AI/MinIO
+4. **API E2E (10%)** - Full stack, all dependencies mocked
+
+### Fixture Reuse
+- ✅ Reuse existing: `async_session`, `async_client`, `superuser_token_headers`
+- ✅ Extend: `vault`, `dweller`, `room` fixtures
+- 🆕 Add new: `active_incident`, `ongoing_exploration`, `training_session`
+
+### Assertion Patterns
+- State changes (DB records updated)
+- Return values (correct calculations)
+- Side effects (logging, notifications)
+- Error handling (exceptions raised)
+
+## Daily Breakdown
+
+### Day 1: Foundation
+- Morning: Phase 1 (Datetime) + Phase 2 (Middleware)
+- Afternoon: Phase 3 (DB tests)
+- **Deliverable:** 47 new tests, ~30% coverage gain
+
+### Day 2: Complex Services
+- Morning: Phase 4 (Incident service fix + tests)
+- Afternoon: Phase 5 start (Game loop orchestration)
+- **Deliverable:** 55+ new tests, ~20% coverage gain
+
+### Day 3: Completion
+- Morning: Phase 5 completion (Game loop phases)
+- Afternoon: Phase 6 (Unique rooms) + verification
+- **Deliverable:** Final tests, coverage verification, documentation
+
+## Coverage Calculation
+
+**Current State:**
+- Total lines: ~8,000 (estimated)
+- Covered: ~3,560 (44.5%)
+- Uncovered: ~4,440
+
+**Target State:**
+- New coverage: ~2,840 lines (from 102 tests × ~28 lines/test avg)
+- Final coverage: ~6,400 / 8,000 = **80%** ✅
+
+**Critical Modules Impact:**
+- middleware: +140 lines
+- db: +120 lines
+- incident_service: +350 lines
+- game_loop: +450 lines
+- Total: +1,060 high-value lines
+
+## Verification Commands
+
+```bash
+# Run specific test suites
+uv run pytest app/tests/test_middleware/ -v
+uv run pytest app/tests/test_db/ -v
+uv run pytest app/tests/test_services/test_incident_service.py -v
+uv run pytest app/tests/test_services/test_game_loop.py -v
+
+# Coverage by module
+uv run pytest --cov=app.middleware --cov-report=term-missing
+uv run pytest --cov=app.db --cov-report=term-missing
+uv run pytest --cov=app.services.incident_service --cov-report=term-missing
+uv run pytest --cov=app.services.game_loop --cov-report=term-missing
+
+# Full coverage check
+uv run pytest app/tests/ --cov=app --cov-report=html --cov-report=term-missing
+```
+
+## Definition of Done
+
+- [ ] All 102 new tests written
+- [ ] All tests pass locally
+- [ ] Coverage ≥ 80% (verified with `--cov-fail-under=80`)
+- [ ] No skipped tests (except intentional @pytest.mark.skip with valid reason)
+- [ ] No datetime deprecation warnings
+- [ ] Ruff linting passes
+- [ ] Pre-commit hooks pass
+- [ ] CI/CD workflows green
+- [ ] ROADMAP.md updated
+- [ ] PR created with comprehensive description
+
+---
+
+**Total Test Count:** 570 → 672 (+102)
+**Total Coverage:** 44.5% → 80% (+35.5 pp)
+**Estimated Effort:** 2-3 days (16-24 hours)