feat: Agent 2A - Recurring Tasks Implementation

history/prompts/013-recurring-tasks/0001-create-implementation-plan-for-recurring-tasks-feature.plan.prompt.md

@@ -0,0 +1,146 @@
+---
+id: 0001
+title: Create implementation plan for Recurring Tasks feature
+stage: plan
+date: 2025-12-10
+surface: agent
+model: claude-sonnet-4-5-20250929
+feature: 013-recurring-tasks
+branch: main
+user: mjunaidca
+command: Create implementation plan for Recurring Tasks feature
+labels: ["planning", "recurring-tasks", "phase-v", "spec-driven"]
+links:
+  spec: specs/013-recurring-tasks/spec.md
+  ticket: null
+  adr: null
+  pr: null
+files:
+  - specs/013-recurring-tasks/plan.md
+tests:
+  - None (planning phase)
+---
+
+## Prompt
+
+Create implementation plan for Recurring Tasks feature.
+
+## Context Files to Read
+1. Spec: specs/013-recurring-tasks/spec.md
+2. Constitution: .specify/memory/constitution.md
+3. PRD: specs/011-phase-v-features-planner/agent-2a-recurring-tasks-prd.md
+
+## Current Codebase Structure
+- Backend: packages/api/src/taskflow_api/
+  - models/task.py - Task SQLModel
+  - schemas/task.py - Pydantic schemas (TaskCreate, TaskUpdate, TaskRead, TaskListItem)
+  - routers/tasks.py - Task API endpoints including update_status
+- Frontend: web-dashboard/src/
+  - types/index.ts - TypeScript types
+  - app/projects/[id]/tasks/new/page.tsx - Task creation form
+
+## Your Task
+Create a comprehensive implementation plan at specs/013-recurring-tasks/plan.md that includes:
+
+1. **Summary**: Primary requirement + technical approach
+
+2. **Technical Context**:
+   - Language: Python 3.13 (backend), TypeScript (frontend)
+   - Framework: FastAPI + SQLModel (backend), Next.js 16 (frontend)
+   - Database: PostgreSQL via Neon (production), SQLite (tests)
+   - Testing: pytest (backend)
+
+3. **Constitution Check**: Verify against 5 Non-Negotiable Principles:
+   - Audit: Every action auditable
+   - Agent Parity: Same API for humans/agents
+   - Recursive Tasks: N/A for this feature
+   - Spec-Driven: Spec exists before code
+   - Phase Continuity: Data model works through Phase V
+
+4. **Implementation Phases**:
+
+   **Phase 1: Backend Model + Migration** (Priority: Highest)
+   - Add 5 fields to Task model: is_recurring, recurrence_pattern, reminder_sent, max_occurrences, occurrences_created
+   - Create Alembic migration
+   - Test with pytest
+
+   **Phase 2: Schema Updates**
+   - Update TaskCreate with is_recurring, recurrence_pattern, max_occurrences
+   - Update TaskUpdate with same fields
+   - Update TaskRead, TaskListItem with is_recurring indicator
+   - Add validation (pattern required when recurring=true)
+
+   **Phase 3: Recurring Logic**
+   - Add calculate_next_due() function
+   - Add create_next_occurrence() async function
+   - Modify update_status endpoint to trigger on completion
+   - Create audit log entry for spawned tasks
+
+   **Phase 4: Frontend Updates**
+   - Update TypeScript types (TaskCreate, TaskRead, TaskListItem)
+   - Add RECURRENCE_PATTERNS constant
+   - Add recurring toggle + pattern selector to task create form
+   - Add recurring badge to task list
+   - Add recurring indicator to task detail view
+
+5. **File Changes Summary**:
+   List all files to be modified/created with specific changes
+
+6. **Test Strategy**:
+   - Unit tests for calculate_next_due()
+   - Integration test for complete recurring task flow
+   - Edge case tests (max_occurrences, no due_date, etc.)
+
+7. **Risk Assessment**:
+   - Database migration on production
+   - Backward compatibility with existing tasks
+
+Write the complete plan to: specs/013-recurring-tasks/plan.md
+
+## Response snapshot
+
+Created comprehensive implementation plan at `specs/013-recurring-tasks/plan.md` with the following structure:
+
+**Key Sections:**
+1. **Summary**: Auto-create next occurrence on task completion with time-based (1m-1h) and calendar-based (daily/weekly/monthly) patterns
+2. **Technical Context**: Python 3.13/FastAPI/SQLModel backend, TypeScript/Next.js 16 frontend, PostgreSQL database
+3. **Constitution Check**: ✅ All 5 principles verified (Audit, Agent Parity, Recursive N/A, Spec-Driven, Phase Continuity)
+4. **4 Implementation Phases** (45min total):
+   - Phase 1: Backend Model + Migration (15min) - Add 5 fields, generate/apply Alembic migration
+   - Phase 2: Schema Updates (10min) - Extend TaskCreate/Update/Read with validation
+   - Phase 3: Recurring Logic (15min) - Implement calculate_next_due(), create_next_occurrence(), integrate into update_status
+   - Phase 4: Frontend (15min) - Add recurring toggle, pattern selector, badges/indicators
+5. **File Changes**: 8 files, ~307 lines total
+6. **Test Strategy**: Unit tests (calculate_next_due), integration tests (completion flow, max_occurrences, audit), manual testing checklist
+7. **Risk Assessment**: 5 risks identified with mitigation (migration safety, backward compat, infinite loops, timezones, UI validation)
+
+**Technical Highlights:**
+- New Task fields: `is_recurring`, `recurrence_pattern`, `reminder_sent`, `max_occurrences`, `occurrences_created`
+- Recurrence patterns: 1m, 5m, 10m, 15m, 30m, 1h, daily, weekly, monthly
+- Triggers only on `status=completed` (one-time event, no loops)
+- Inherits: title, description, assignee, priority, tags, project
+- Audit log links new task to source (`recurring_from` detail)
+- Backend validation: pattern required when recurring=true
+- Frontend: Checkbox + Select dropdown + optional max occurrences input
+
+**Constitution Compliance:**
+- ✅ Audit: log_action() for new task with recurring_from reference
+- ✅ Agent Parity: Same /api/tasks/{id}/status endpoint for humans/agents
+- ⚠️ Recursive: N/A (new tasks are siblings, not subtasks)
+- ✅ Spec-Driven: Follows specs/013-recurring-tasks/spec.md
+- ✅ Phase Continuity: Additive fields with defaults, backward compatible
+
+## Outcome
+
+- ✅ Impact: Created production-ready implementation plan with 13 sections covering all aspects (model, schemas, logic, frontend, tests, risks)
+- 🧪 Tests: Test strategy includes unit tests (9 pattern calculations), integration tests (4 scenarios: basic flow, max_occurrences, no due_date, audit), manual checklist
+- 📁 Files: Plan document (1 created), identifies 8 files to modify (4 backend, 4 frontend), ~307 total lines
+- 🔁 Next prompts: (1) Implement Phase 1 (backend model + migration), (2) Implement Phase 2 (schemas), (3) Implement Phase 3 (recurring logic), (4) Implement Phase 4 (frontend)
+- 🧠 Reflection: Plan follows constitution's 5 principles, provides clear phase breakdown with time estimates, includes rollback strategies for migration risk, documents edge cases (no due_date → use completion time, monthly = 30 days not calendar month)
+
+## Evaluation notes (flywheel)
+
+- Failure modes observed: None - plan creation successful on first attempt
+- Graders run and results (PASS/FAIL): N/A (planning phase, no code execution)
+- Prompt variant (if applicable): Base prompt with structured sections (Context + Task breakdown)
+- Next experiment (smallest change to try): Begin Phase 1 implementation (backend model changes)

history/prompts/013-recurring-tasks/0002-implement-recurring-tasks-with-chain-tracking.green.prompt.md

@@ -0,0 +1,93 @@
+---
+id: "0002"
+title: "Implement Recurring Tasks with Chain Tracking"
+stage: green
+date: 2025-12-11
+surface: agent
+model: claude-opus-4-5
+feature: recurring-tasks
+branch: main
+user: agent
+command: "continue implementation"
+labels: ["recurring-tasks", "refactoring", "subtask-cloning"]
+links:
+  spec: "specs/013-recurring-tasks/spec.md"
+  ticket: null
+  adr: null
+  pr: null
+files:
+  - packages/api/src/taskflow_api/models/task.py
+  - packages/api/src/taskflow_api/schemas/task.py
+  - packages/api/src/taskflow_api/routers/tasks.py
+  - web-dashboard/src/types/index.ts
+  - web-dashboard/src/app/projects/[id]/tasks/new/page.tsx
+  - web-dashboard/src/app/tasks/[id]/page.tsx
+tests:
+  - "uv run pytest -x (74 passed)"
+  - "pnpm build (success)"
+---
+
+# Prompt
+
+Continue implementing the recurring tasks feature. During implementation, the original design was refined:
+
+1. **Bug discovered**: The `occurrences_created` counter on each task would reset to 0 when spawning new tasks, breaking the `max_occurrences` limit check.
+
+2. **User insight**: "If we implement Option 2 (recurring_root_id) then do we even need occurrences_created=0?" - Confirmed that with chain tracking, we can remove the counter entirely and use COUNT query.
+
+3. **Design refinement**:
+   - Removed: `occurrences_created` (counter), `reminder_sent` (not used yet)
+   - Added: `recurring_root_id` (FK to task.id for chain tracking)
+   - Spawn count derived via: `COUNT(*) WHERE recurring_root_id = root_id`
+
+4. **Additional features requested**:
+   - `clone_subtasks_on_recur`: When enabled, subtasks are recursively cloned to each new occurrence
+   - `recurrence_trigger`: "on_complete" | "on_due_date" | "both" (only on_complete implemented, others marked "Coming Soon")
+
+# Response
+
+## Implementation Summary
+
+### Field Design (Final)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `is_recurring` | bool | Enables recurring behavior |
+| `recurrence_pattern` | str | Pattern: 1m-monthly |
+| `max_occurrences` | int | Spawn limit (NULL = unlimited) |
+| `recurring_root_id` | int | FK to root task (NULL = this IS the root) |
+| `recurrence_trigger` | str | "on_complete", "on_due_date", "both" |
+| `clone_subtasks_on_recur` | bool | Clone subtasks when spawning |
+
+### Key Functions
+
+1. `get_spawn_count(session, root_id)` - COUNT query for spawn limit check
+2. `clone_subtasks_recursive(session, source, new_parent, ...)` - Deep clone subtasks
+3. `create_next_occurrence(session, completed_task, ...)` - Spawn with chain tracking
+
+### SQLAlchemy Fix
+
+Added explicit `foreign_keys` to parent/subtasks relationships because Task now has TWO self-referential FKs:
+```python
+parent: "Task" = Relationship(
+    back_populates="subtasks",
+    sa_relationship_kwargs={
+        "remote_side": "Task.id",
+        "foreign_keys": "[Task.parent_task_id]",
+    },
+)
+```
+
+### Frontend Updates
+
+- Task creation form: Clone subtasks checkbox, recurrence trigger dropdown with "Coming Soon" badges
+- Task detail: Shows clone_subtasks_on_recur and recurrence_trigger values
+
+### Test Results
+
+- Backend: 74 passed, 3 skipped
+- Frontend: Build successful
+
+# Outcome
+
+Feature complete with improved design. Chain tracking via `recurring_root_id` is cleaner and more reliable than counter-based tracking. Subtask cloning enables complex recurring workflows (e.g., weekly sprint with standard checklist).

history/prompts/recurring-tasks/001-recurring-tasks-specification.spec.prompt.md

@@ -0,0 +1,78 @@
+---
+id: 001
+title: Recurring Tasks Specification
+stage: spec
+date: 2025-12-10
+surface: agent
+model: claude-opus-4-5-20251101
+feature: recurring-tasks
+branch: recurring-tasks
+user: autonomous
+command: /sp.specify recurring-tasks
+labels: ["recurring-tasks", "phase-v", "specification", "sdd"]
+links:
+  spec: specs/013-recurring-tasks/spec.md
+  ticket: null
+  adr: null
+  pr: null
+files:
+  - specs/013-recurring-tasks/spec.md
+  - specs/013-recurring-tasks/checklists/requirements.md
+tests:
+  - N/A (specification phase)
+---
+
+## Prompt
+
+/sp.specify recurring-tasks
+
+Implement Recurring Tasks - tasks that auto-create their next occurrence when completed. Support minute-level recurrence (1m, 5m, etc.), daily, weekly, monthly patterns. Include max occurrences limit.
+
+Context from PRD (specs/011-phase-v-features-planner/agent-2a-recurring-tasks-prd.md):
+- Add 3 fields to Task model (is_recurring, recurrence_pattern, reminder_sent)
+- Modify update_status to create next occurrence when completing recurring task
+- Add recurring toggle to task forms in frontend
+
+User additions:
+- Support 1-minute recurrence intervals
+- Add duration/max occurrences feature
+
+## Response snapshot
+
+Created comprehensive specification at `specs/013-recurring-tasks/spec.md` covering:
+
+1. **5 User Stories** (prioritized P1-P3):
+   - P1: Complete recurring task creates next occurrence
+   - P1: Create recurring task via form
+   - P2: View recurring task indicator
+   - P2: Edit task recurrence settings
+   - P3: Max occurrences limit
+
+2. **13 Functional Requirements** (FR-001 through FR-013):
+   - Model fields: is_recurring, recurrence_pattern, reminder_sent, max_occurrences, occurrences_created
+   - Supported patterns: 1m, 5m, 10m, 15m, 30m, 1h, daily, weekly, monthly
+   - Auto-creation logic on completion
+   - Audit log integration
+   - Frontend UI requirements
+
+3. **6 Success Criteria** with measurable outcomes:
+   - SC-001: Next occurrence appears within 2 seconds
+   - SC-002: Exactly one occurrence per completion (no duplicates)
+   - SC-006: Max occurrences 100% accuracy
+
+4. **Spec-architect validation**: 9.5/10 score, READY FOR PLANNING
+
+## Outcome
+
+- Impact: Comprehensive specification created for recurring tasks feature
+- Tests: N/A (specification phase - no code yet)
+- Files: 2 files created (spec.md, requirements.md checklist)
+- Next prompts: /sp.plan recurring-tasks
+- Reflection: Extended PRD with max_occurrences feature per user request. Spec-architect validated with formal verification (invariants, small scope testing).
+
+## Evaluation notes (flywheel)
+
+- Failure modes observed: None - spec passed all validation checks
+- Graders run and results (PASS/FAIL): spec-architect validation PASS (9.5/10)
+- Prompt variant (if applicable): Standard /sp.specify flow
+- Next experiment (smallest change to try): Could add p95 latency percentile to SC-001

history/prompts/recurring-tasks/002-recurring-tasks-planning.plan.prompt.md

@@ -0,0 +1,68 @@
+---
+id: 002
+title: Recurring Tasks Implementation Planning
+stage: plan
+date: 2025-12-10
+surface: agent
+model: claude-opus-4-5-20251101
+feature: recurring-tasks
+branch: recurring-tasks
+user: autonomous
+command: /sp.plan recurring-tasks
+labels: ["recurring-tasks", "phase-v", "planning", "sdd"]
+links:
+  spec: specs/013-recurring-tasks/spec.md
+  ticket: null
+  adr: null
+  pr: null
+files:
+  - specs/013-recurring-tasks/plan.md
+tests:
+  - N/A (planning phase)
+---
+
+## Prompt
+
+/sp.plan recurring-tasks
+
+Create comprehensive implementation plan based on spec.md for recurring tasks feature.
+
+## Response snapshot
+
+Created detailed implementation plan at `specs/013-recurring-tasks/plan.md` (1245 lines) covering:
+
+**4 Implementation Phases** (45 min total):
+1. Backend Model + Migration (15 min) - Add 5 fields to Task model
+2. Schema Updates (10 min) - Extend TaskCreate, TaskUpdate, TaskRead, TaskListItem
+3. Recurring Logic (15 min) - calculate_next_due, create_next_occurrence, update_status integration
+4. Frontend Updates (15 min) - Recurring toggle, pattern selector, badges
+
+**Key Technical Decisions**:
+- timedelta-based calculations (no dateutil dependency)
+- Monthly = 30 days (simplified, not calendar month)
+- Fallback to daily for unknown patterns
+- Transaction pattern: caller owns commit (follows constitution)
+
+**Constitution Compliance**: All 5 principles verified
+- Audit: log_action with recurring_from reference
+- Agent Parity: Same endpoint for humans/agents
+- Spec-Driven: Following spec.md
+- Phase Continuity: Additive fields, backward compatible
+
+**File Changes Summary**: 8 files, ~307 lines
+**Test Strategy**: Unit tests for patterns + integration tests for workflow
+
+## Outcome
+
+- Impact: Complete implementation roadmap created
+- Tests: N/A (planning phase)
+- Files: 1 file created (plan.md)
+- Next prompts: /sp.tasks recurring-tasks
+- Reflection: Plan is production-ready with detailed code snippets for each phase
+
+## Evaluation notes (flywheel)
+
+- Failure modes observed: None
+- Graders run and results (PASS/FAIL): Constitution check PASS
+- Prompt variant (if applicable): Standard /sp.plan with general-purpose agent routing
+- Next experiment (smallest change to try): Could add time estimates per code block