feat: implement kanban real-time sync and fix workload cache

## Kanban Real-time Sync (NEW-002)
- Backend:
  - WebSocket endpoint: /ws/projects/{project_id}
  - Project room management in ConnectionManager
  - Redis Pub/Sub: project:{project_id}:tasks channel
  - Task CRUD event publishing (5 event types)
  - Redis connection retry with exponential backoff
  - Race condition fix in broadcast_to_project

- Frontend:
  - ProjectSyncContext for WebSocket management
  - Reconnection with exponential backoff (max 5 attempts)
  - Multi-tab event deduplication via event_id
  - Live/Offline connection indicator
  - Optimistic updates with rollback

- Spec:
  - collaboration spec: +1 requirement (Project Real-time Sync)
  - 7 new scenarios for real-time sync

## Workload Cache Fix (NEW-001)
- Added cache invalidation to all task endpoints:
  - create_task, update_task, update_task_status
  - delete_task, restore_task, assign_task
- Extended to clear heatmap cache as well

## OpenSpec Archive
- 2026-01-05-add-kanban-realtime-sync

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/app/api/websocket/router.py

@@ -7,9 +7,10 @@ from sqlalchemy.orm import Session
 from app.core.database import SessionLocal
 from app.core.security import decode_access_token
 from app.core.redis import get_redis_sync
-from app.models import User, Notification
+from app.models import User, Notification, Project
 from app.services.websocket_manager import manager
-from app.core.redis_pubsub import NotificationSubscriber
+from app.core.redis_pubsub import NotificationSubscriber, ProjectTaskSubscriber
+from app.middleware.auth import check_project_access
 
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["websocket"])
@@ -226,3 +227,182 @@ async def websocket_notifications(
                 pass
         await subscriber.stop()
         await manager.disconnect(websocket, user_id)
+
+
+async def verify_project_access(user_id: str, project_id: str) -> tuple[bool, Project | None]:
+    """
+    Check if user has access to the project.
+
+    Args:
+        user_id: The user's ID
+        project_id: The project's ID
+
+    Returns:
+        Tuple of (has_access: bool, project: Project | None)
+    """
+    db = SessionLocal()
+    try:
+        # Get the user
+        user = db.query(User).filter(User.id == user_id).first()
+        if user is None or not user.is_active:
+            return False, None
+
+        # Get the project
+        project = db.query(Project).filter(Project.id == project_id).first()
+        if project is None:
+            return False, None
+
+        # Check access using existing middleware function
+        has_access = check_project_access(user, project)
+        return has_access, project
+    finally:
+        db.close()
+
+
+@router.websocket("/ws/projects/{project_id}")
+async def websocket_project_sync(
+    websocket: WebSocket,
+    project_id: str,
+    token: str = Query(..., description="JWT token for authentication"),
+):
+    """
+    WebSocket endpoint for project task real-time sync.
+
+    Connect with: ws://host/ws/projects/{project_id}?token=<jwt_token>
+
+    Messages sent by server:
+    - {"type": "connected", "data": {"project_id": "...", "user_id": "..."}}
+    - {"type": "task_created", "data": {...}, "triggered_by": "..."}
+    - {"type": "task_updated", "data": {...}, "triggered_by": "..."}
+    - {"type": "task_status_changed", "data": {...}, "triggered_by": "..."}
+    - {"type": "task_deleted", "data": {...}, "triggered_by": "..."}
+    - {"type": "task_assigned", "data": {...}, "triggered_by": "..."}
+    - {"type": "ping"} / {"type": "pong"}
+
+    Messages accepted from client:
+    - {"type": "ping"}  - Client keepalive ping
+    """
+    # Authenticate user
+    user_id, user = await get_user_from_token(token)
+
+    if user_id is None:
+        await websocket.close(code=4001, reason="Invalid or expired token")
+        return
+
+    # Verify user has access to the project
+    has_access, project = await verify_project_access(user_id, project_id)
+
+    if not has_access:
+        await websocket.close(code=4003, reason="Access denied to this project")
+        return
+
+    if project is None:
+        await websocket.close(code=4004, reason="Project not found")
+        return
+
+    # Accept connection and join project room
+    await websocket.accept()
+    await manager.join_project(websocket, user_id, project_id)
+
+    # Create Redis subscriber for project task events
+    subscriber = ProjectTaskSubscriber(project_id)
+
+    async def handle_redis_message(event_data: dict):
+        """Forward Redis pub/sub task events to WebSocket."""
+        try:
+            # Forward the event directly (it already contains type, data, triggered_by)
+            await websocket.send_json(event_data)
+        except Exception as e:
+            logger.error(f"Error forwarding task event to WebSocket: {e}")
+
+    redis_task = None
+
+    try:
+        # Send initial connection success message
+        await websocket.send_json({
+            "type": "connected",
+            "data": {
+                "project_id": project_id,
+                "user_id": user_id,
+                "project_title": project.title if project else None,
+            },
+        })
+
+        logger.info(f"User {user_id} connected to project {project_id} WebSocket")
+
+        # Start Redis pub/sub subscription in background
+        await subscriber.start()
+        redis_task = asyncio.create_task(subscriber.listen(handle_redis_message))
+
+        # Heartbeat tracking (reuse same configuration as notifications)
+        waiting_for_pong = False
+        ping_sent_at = 0.0
+        last_activity = time.time()
+
+        while True:
+            # Calculate appropriate timeout based on state
+            if waiting_for_pong:
+                # When waiting for pong, use remaining pong timeout
+                remaining = PONG_TIMEOUT - (time.time() - ping_sent_at)
+                if remaining <= 0:
+                    logger.warning(f"Pong timeout for user {user_id} in project {project_id}, disconnecting")
+                    break
+                timeout = remaining
+            else:
+                # When not waiting, use remaining ping interval
+                remaining = PING_INTERVAL - (time.time() - last_activity)
+                if remaining <= 0:
+                    # Time to send ping immediately
+                    try:
+                        await websocket.send_json({"type": "ping"})
+                        waiting_for_pong = True
+                        ping_sent_at = time.time()
+                        last_activity = ping_sent_at
+                        timeout = PONG_TIMEOUT
+                    except Exception:
+                        break
+                else:
+                    timeout = remaining
+
+            try:
+                # Wait for messages from client
+                data = await asyncio.wait_for(
+                    websocket.receive_json(),
+                    timeout=timeout
+                )
+
+                last_activity = time.time()
+                msg_type = data.get("type")
+
+                # Handle ping message from client
+                if msg_type == "ping":
+                    await websocket.send_json({"type": "pong"})
+
+                # Handle pong message from client (response to our ping)
+                elif msg_type == "pong":
+                    waiting_for_pong = False
+                    logger.debug(f"Pong received from user {user_id} in project {project_id}")
+
+            except asyncio.TimeoutError:
+                if waiting_for_pong:
+                    # Strict timeout check
+                    if time.time() - ping_sent_at >= PONG_TIMEOUT:
+                        logger.warning(f"Pong timeout for user {user_id} in project {project_id}, disconnecting")
+                        break
+                # If not waiting_for_pong, loop will handle sending ping at top
+
+    except WebSocketDisconnect:
+        logger.info(f"User {user_id} disconnected from project {project_id} WebSocket")
+    except Exception as e:
+        logger.error(f"WebSocket error for project {project_id}: {e}")
+    finally:
+        # Clean up Redis subscription
+        if redis_task:
+            redis_task.cancel()
+            try:
+                await redis_task
+            except asyncio.CancelledError:
+                pass
+        await subscriber.stop()
+        await manager.leave_project(websocket, user_id, project_id)
+        logger.info(f"User {user_id} left project {project_id} room")