# Tasks: LLM Chat Assistant for Project Operations

**Input**: Design documents from [`/specs/021-llm-project-assistant/`](specs/021-llm-project-assistant)  
**Prerequisites**: [`plan.md`](specs/021-llm-project-assistant/plan.md), [`spec.md`](specs/021-llm-project-assistant/spec.md), [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md), [`research.md`](specs/021-llm-project-assistant/research.md), [`data-model.md`](specs/021-llm-project-assistant/data-model.md), [`contracts/`](specs/021-llm-project-assistant/contracts)

**Tests**: Include backend contract/integration tests and frontend integration/state tests.

**Organization**: Tasks are grouped by user story for independent implementation and validation.

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

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Prepare assistant feature scaffolding and fixtures.

- [ ] T001 Create assistant feature folders in `backend/src/services/assistant/`, `frontend/src/lib/components/assistant/`, `frontend/src/lib/api/assistant.js`
- [ ] T002 [P] Add backend fixtures for assistant parsing/confirmation in `backend/tests/fixtures/assistant/fixtures_assistant.json`
- [ ] T003 [P] Add frontend fixtures for assistant response states in `frontend/src/lib/components/assistant/__tests__/fixtures/assistant.fixtures.js`
- [x] T004 [P] Add i18n placeholders for assistant UI in `frontend/src/lib/i18n/locales/en.json` and `frontend/src/lib/i18n/locales/ru.json`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Build core assistant architecture required by all stories.

- [x] T005 Implement assistant domain models (`AssistantMessage`, `CommandIntent`, `ConfirmationToken`, `AssistantExecutionLog`) in `backend/src/models/assistant.py`
- [ ] T006 [P] Implement intent parser service with confidence output in `backend/src/services/assistant/intent_parser.py`
- [ ] T007 Implement RBAC + risk guard service in `backend/src/services/assistant/security_guard.py`
- [ ] T008 Implement execution adapter to existing operations in `backend/src/services/assistant/execution_adapter.py`
- [ ] T009 Implement assistant orchestrator service in `backend/src/services/assistant/orchestrator.py`
- [ ] T010 [P] Implement assistant audit logging service/repository in `backend/src/services/assistant/audit_service.py`
- [x] T011 Create assistant API route module in `backend/src/api/routes/assistant.py` (CRITICAL: message/confirm/cancel/history endpoints)
- [x] T012 Wire assistant router into `backend/src/api/routes/__init__.py` and `backend/src/app.py`
- [x] T013 Create frontend assistant API client in `frontend/src/lib/api/assistant.js`
- [ ] T014 Verify contracts alignment between `spec.md` and `contracts/modules.md`

**Checkpoint**: Foundation complete; user stories can begin.

---

## Phase 3: User Story 1 - Use chat instead of manual UI navigation (Priority: P1) 🎯 MVP

**Goal**: Add in-app assistant chat interface with working request/response loop.

**Independent Test**: Open assistant panel and complete one command-response interaction.

### Tests for User Story 1

- [x] T015 [P] [US1] Add backend API contract tests for `POST /api/assistant/messages` in `backend/src/api/routes/__tests__/test_assistant_api.py`
- [x] T016 [P] [US1] Add frontend integration test for chat panel interaction in `frontend/src/lib/components/assistant/__tests__/assistant_chat.integration.test.js`

### Implementation for User Story 1

- [x] T017 [US1] Implement assistant chat panel component in `frontend/src/lib/components/assistant/AssistantChatPanel.svelte`
- [x] T018 [US1] Add assistant launch trigger to top navigation in `frontend/src/lib/components/layout/TopNavbar.svelte`
- [x] T019 [US1] Add chat state store in `frontend/src/lib/stores/assistantChat.js`
- [x] T020 [US1] Implement message submission and rendering pipeline in `AssistantChatPanel.svelte` with explicit state badges
- [x] T021 [US1] Add command examples/help section in `AssistantChatPanel.svelte`
- [x] T022 [US1] Validate UX states from [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md)

**Checkpoint**: US1 independently functional and demo-ready.

---

## Phase 4: User Story 2 - Execute core operations via natural-language commands (Priority: P1)

**Goal**: Support command parsing and dispatch for Git/migration/backup/LLM/status operations.

**Independent Test**: One command per domain executes correct backend path or returns valid error.

### Tests for User Story 2

- [ ] T023 [P] [US2] Add parser tests for RU/EN command variants in `backend/src/services/assistant/__tests__/test_intent_parser.py`
- [ ] T024 [P] [US2] Add execution adapter integration tests in `backend/src/services/assistant/__tests__/test_execution_adapter.py`
- [ ] T025 [P] [US2] Add frontend state tests for command result rendering in `frontend/src/lib/components/assistant/__tests__/assistant_states.test.js`

### Implementation for User Story 2

- [ ] T026 [US2] Implement Git command mappings in `execution_adapter.py` (create branch, commit, deploy)
- [ ] T027 [US2] Implement migration/backup command mappings in `execution_adapter.py` via existing task creation
- [ ] T028 [US2] Implement LLM validation/documentation command mappings in `execution_adapter.py`
- [ ] T029 [US2] Implement task/report status query mappings in `execution_adapter.py`
- [ ] T030 [US2] Implement confidence gate and clarification responses in `orchestrator.py`
- [x] T031 [US2] Render started/success/failed response cards with `task_id` chips in `AssistantChatPanel.svelte`
- [x] T032 [US2] Add quick action from `task_id` chip to Task Drawer in `frontend/src/lib/stores/taskDrawer.js` integration points

**Checkpoint**: US2 independently functional across requested command domains.

---

## Phase 5: User Story 3 - Safe execution with RBAC and explicit confirmations (Priority: P1)

**Goal**: Enforce permissions and confirmation gates for dangerous operations.

**Independent Test**: Unauthorized command denied; production deploy requires confirm and executes only after confirm.

### Tests for User Story 3

- [x] T033 [P] [US3] Add backend authorization tests in `backend/src/api/routes/__tests__/test_assistant_authz.py`
- [ ] T034 [P] [US3] Add backend confirmation lifecycle tests in `backend/src/services/assistant/__tests__/test_confirmation_flow.py`
- [x] T035 [P] [US3] Add frontend confirm/cancel UX tests in `frontend/src/lib/components/assistant/__tests__/assistant_confirmation.integration.test.js`

### Implementation for User Story 3

- [ ] T036 [US3] Implement risk policy matrix in `backend/src/services/assistant/risk_policy.py`
- [ ] T037 [US3] Implement confirmation token storage/service in `backend/src/services/assistant/confirmation_service.py`
- [x] T038 [US3] Implement confirm/cancel endpoints in `backend/src/api/routes/assistant.py`
- [ ] T039 [US3] Enforce one-time token consumption and TTL checks in `confirmation_service.py`
- [x] T040 [US3] Add confirmation UI card with explicit operation summary in `AssistantChatPanel.svelte`
- [x] T041 [US3] Surface `denied` and `needs_confirmation` assistant states consistently in UI

**Checkpoint**: US3 independently functional with enforced safety controls.

---

## Phase 6: User Story 4 - Reliable feedback and progress tracking (Priority: P2)

**Goal**: Provide immediate task start feedback and robust status/report follow-up.

**Independent Test**: Long operation returns `task_id` immediately and can be tracked via Task Drawer/reports.

### Tests for User Story 4

- [ ] T042 [P] [US4] Add backend tests for started response payload and task linkage in `backend/src/api/routes/__tests__/test_assistant_task_feedback.py`
- [ ] T043 [P] [US4] Add frontend integration tests for tracking links/actions in `frontend/src/lib/components/assistant/__tests__/assistant_tracking.integration.test.js`

### Implementation for User Story 4

- [ ] T044 [US4] Add response formatter service for consistent assistant states in `backend/src/services/assistant/response_formatter.py`
- [x] T045 [US4] Implement history endpoint pagination in `backend/src/api/routes/assistant.py`
- [ ] T046 [US4] Implement history loading and pagination in `frontend/src/lib/stores/assistantChat.js`
- [x] T047 [US4] Add open-reports quick action for completed/failed tasks in `AssistantChatPanel.svelte`
- [ ] T048 [US4] Add structured error mapping and user guidance messages in `response_formatter.py` and frontend render logic

**Checkpoint**: US4 independently functional with complete feedback loop.

---

## Phase 7: Polish & Cross-Cutting Concerns

**Purpose**: Final quality, compliance, and operational readiness.

- [ ] T049 [P] Add OpenAPI conformance tests against `specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml` in `backend/src/api/routes/__tests__/test_assistant_openapi_conformance.py`
- [ ] T050 [P] Add audit log persistence tests in `backend/src/services/assistant/__tests__/test_audit_service.py`
- [ ] T051 [P] Add frontend performance tests for chat rendering with long history in `frontend/src/lib/components/assistant/__tests__/assistant_performance.test.js`
- [ ] T052 Update operational docs in `docs/settings.md` and `README.md` for assistant usage and safety confirmations
- [x] T053 Run quickstart validation and record results in `specs/021-llm-project-assistant/quickstart.md`
- [ ] T054 Run semantic map generation (`python3 generate_semantic_map.py`) and resolve critical issues in assistant modules

---

## Dependencies & Execution Order

### Phase Dependencies

- Phase 1 has no dependencies.
- Phase 2 depends on Phase 1 and blocks all user stories.
- Phases 3-6 depend on Phase 2.
- Phase 7 depends on completion of selected user stories.

### User Story Dependency Graph

- **US1 (P1)**: MVP chat entrypoint.
- **US2 (P1)**: Command execution capabilities.
- **US3 (P1)**: Safety and security controls.
- **US4 (P2)**: Feedback and tracking depth.

Graph: `US1 -> {US2, US3} -> US4`

### Parallel Opportunities

- Setup fixture/i18n tasks: T002, T003, T004.
- Foundational tasks: T006/T010 can run in parallel after T005 baseline.
- Story tests in each phase marked `[P]` can run in parallel.
- US2 domain mappings (T026-T029) can be split across developers.

---

## Implementation Strategy

### MVP First (Recommended)

1. Complete Phase 1 + Phase 2.
2. Complete Phase 3 (US1).
3. Complete minimal subset of US2 for one domain (e.g., migration + status) and validate.

### Incremental Delivery

1. Deliver US1 chat shell.
2. Add US2 command domains iteratively.
3. Add US3 confirmation and RBAC hardening.
4. Add US4 history/tracking refinements.
5. Finish Phase 7 compliance and docs.

### UX Preservation Rule

No task should degrade clarity or safety defined in [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md).
