ss-tools/specs/018-task-logging-v2/tasks.md

Tasks: Task Logging System (Separated Per-Task Logs)

Input: Design documents from /specs/018-task-logging-v2/ Prerequisites: plan.md (required), spec.md (required for user stories), ux_reference.md (required)

Tests: Test tasks are included as per the verification plan in plan.md.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Path Conventions

• Web app: backend/src/, frontend/src/

---

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and basic structure

• T001 Create database migration for task_logs table in backend/src/models/task.py
• T002 [P] Define LogEntry and TaskLog schemas in backend/src/core/task_manager/models.py
• T003 [P] Create TaskLogger class in backend/src/core/task_manager/task_logger.py
• T004 [P] Create TaskContext class in backend/src/core/task_manager/context.py

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

• T005 Implement TaskLogPersistenceService in backend/src/core/task_manager/persistence.py
• T006 Update TaskManager to include log buffer and flusher thread in backend/src/core/task_manager/manager.py
• T007 Implement _flush_logs and _add_log (new signature) in backend/src/core/task_manager/manager.py
• T008 Update _run_task to support TaskContext and backward compatibility in backend/src/core/task_manager/manager.py
• T009 [P] Update TaskCleanupService to delete logs in backend/src/core/task_manager/cleanup.py

Checkpoint: Foundation ready - user story implementation can now begin in parallel

---

Phase 3: User Story 2 - Persistent Log History (Priority: P1) 🎯 MVP

Goal: Ensure logs are saved to the database and accessible after server restart.

Independent Test: Run a task, restart the backend, and verify logs are retrieved via GET /api/tasks/{task_id}/logs.

Implementation for User Story 2

• T010 [P] [US2] Implement GET /api/tasks/{task_id}/logs endpoint in backend/src/api/routes/tasks.py
• T011 [P] [US2] Implement GET /api/tasks/{task_id}/logs/stats and /sources in backend/src/api/routes/tasks.py
• T012 [US2] Update get_task_logs in TaskManager to fetch from persistence for completed tasks in backend/src/core/task_manager/manager.py
• T013 [US2] Verify implementation matches ux_reference.md (Happy Path & Errors)

Checkpoint: User Story 2 complete - logs are persistent and accessible via API.

---

Phase 4: User Story 1 - Real-time Filtered Logging (Priority: P1)

Goal: Real-time log streaming with server-side filtering.

Independent Test: Connect to WebSocket with ?source=plugin and verify only plugin logs are received.

Implementation for User Story 1

• T014 [US1] Update WebSocket endpoint in backend/src/app.py to support source and level query parameters
• T015 [US1] Implement server-side filtering logic for WebSocket broadcast in backend/src/core/task_manager/manager.py
• T016 [P] [US1] Create LogFilterBar component in frontend/src/components/tasks/LogFilterBar.svelte
• T017 [P] [US1] Create LogEntryRow component in frontend/src/components/tasks/LogEntryRow.svelte
• T018 [US1] Create TaskLogPanel component in frontend/src/components/tasks/TaskLogPanel.svelte
• T019 [US1] Refactor TaskLogViewer to use TaskLogPanel in frontend/src/components/TaskLogViewer.svelte
• T020 [US1] Update TaskRunner to pass filter parameters to WebSocket in frontend/src/components/TaskRunner.svelte
• T021 [US1] Verify implementation matches ux_reference.md (Happy Path & Errors)

Checkpoint: User Story 1 complete - real-time filtered logging is functional.

---

Phase 5: User Story 3 - Component Attribution (Priority: P2)

Goal: Migrate plugins to use the new TaskContext and TaskLogger.

Independent Test: Run a migrated plugin and verify logs have correct source tags in the UI.

Implementation for User Story 3

• T022 [P] [US3] Migrate BackupPlugin to use TaskContext in backend/src/plugins/backup.py
• T023 [P] [US3] Migrate MigrationPlugin to use TaskContext in backend/src/plugins/migration.py
• T024 [P] [US3] Migrate GitPlugin to use TaskContext in backend/src/plugins/git_plugin.py
• T025 [US3] Verify implementation matches ux_reference.md (Happy Path & Errors)

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Improvements that affect multiple user stories

• T026 [P] Add unit tests for LogPersistenceService in backend/tests/test_log_persistence.py
• T027 [P] Add unit tests for TaskLogger and TaskContext in backend/tests/test_task_logger.py
• T028 [P] Update docs/plugin_dev.md with new logging instructions
• T029 Final verification of all success criteria (SC-001 to SC-004)

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies.
• Foundational (Phase 2): Depends on Phase 1.
• User Stories (Phase 3-5): Depend on Phase 2. US2 (Persistence) is prioritized as it's the foundation for historical logs.
• Polish (Phase 6): Depends on all user stories.

Parallel Opportunities

• T002, T003, T004 can run in parallel.
• T010, T011 can run in parallel.
• T016, T017 can run in parallel.
• Plugin migrations (T022-T024) can run in parallel.

---

Implementation Strategy

MVP First (User Story 2)

1. Complete Setup & Foundational phases.
2. Implement US2 (Persistence & API).
3. STOP and VALIDATE: Verify logs are saved and retrieved after restart.

Incremental Delivery

1. Add US1 (Real-time & UI) → Test filtering.
2. Add US3 (Plugin Migration) → Test source attribution.