# Quickstart: LLM Chat Assistant for Project Operations

## Purpose

Implement and validate assistant-driven project operations defined in:
- Spec: [`spec.md`](specs/021-llm-project-assistant/spec.md)
- UX reference: [`ux_reference.md`](specs/021-llm-project-assistant/ux_reference.md)
- Plan: [`plan.md`](specs/021-llm-project-assistant/plan.md)
- Data model: [`data-model.md`](specs/021-llm-project-assistant/data-model.md)
- Contracts: [`contracts/modules.md`](specs/021-llm-project-assistant/contracts/modules.md), [`contracts/assistant-api.openapi.yaml`](specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml)

## 1) Backend implementation flow

1. Add assistant route module (`/api/assistant/*`).
2. Implement intent parser service (hybrid deterministic + LLM fallback).
3. Implement security guard and confirmation token workflow.
4. Implement execution adapter mapping intents to existing Git/migration/backup/LLM/tasks operations.
5. Add structured assistant audit logging.

## 2) Frontend implementation flow

1. Add assistant chat panel component and open/close controls in main layout.
2. Add assistant API client using existing frontend API wrapper.
3. Render assistant response states (`needs_confirmation`, `started`, `denied`, etc.).
4. Add confirm/cancel actions and task tracking chips linking to Task Drawer/reports.
5. Add i18n keys for RU/EN assistant labels and status texts.

## 3) Safety checks (must pass)

- Unauthorized command execution is denied.
- Dangerous operations require confirmation and do not auto-run.
- Expired/cancelled confirmation never executes.
- Confirm endpoint is idempotent (single execution).

## 4) UX conformance checks (must pass)

- Chat interaction available in app shell.
- Immediate "started" response with `task_id` for long jobs.
- Clear clarification prompt on ambiguous commands.
- Clear error text and recovery guidance on failed dispatch.

## 5) Contract checks (must pass)

- Assistant endpoints conform to [`assistant-api.openapi.yaml`](specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml).
- Response states always included and valid enum values.
- Confirmation flow returns deterministic machine-readable output.

## 6) Suggested validation commands

Backend tests:
```bash
cd backend && .venv/bin/python3 -m pytest
```

Frontend tests:
```bash
cd frontend && npm test
```

Targeted assistant tests (when implemented):
```bash
cd backend && .venv/bin/python3 -m pytest tests -k assistant
cd frontend && npm test -- assistant
```

## 7) Done criteria for planning handoff

- All planning artifacts for `021` exist and are mutually consistent.
- Risk confirmation and RBAC enforcement are explicit in spec and contracts.
- Task-tracking integration through existing Task Drawer/reports is reflected in contracts and tasks.
- Ready for implementation via `tasks.md`.

## 8) Validation Log (2026-02-23)

### Frontend

- `cd frontend && npx vitest run src/lib/components/assistant/__tests__/assistant_chat.integration.test.js src/lib/components/assistant/__tests__/assistant_confirmation.integration.test.js src/lib/stores/__tests__/assistantChat.test.js`
  - Result: **PASS** (`11 passed`)
- `cd frontend && npm run build`
  - Result: **PASS** (build successful; project has pre-existing non-blocking a11y warnings outside assistant scope)

### Backend

- `python3 -m py_compile backend/src/api/routes/assistant.py backend/src/models/assistant.py backend/src/api/routes/__tests__/test_assistant_api.py backend/src/api/routes/__tests__/test_assistant_authz.py`
  - Result: **PASS**
- `cd backend && .venv/bin/python -m pytest -q src/api/routes/__tests__/test_assistant_api.py src/api/routes/__tests__/test_assistant_authz.py`
  - Result: **BLOCKED in current env** (runtime hang during request execution after heavy app bootstrap; collection succeeds)

### Semantics

- `python3 generate_semantic_map.py`
  - Result: **PASS** (updated semantic artifacts: `.ai/PROJECT_MAP.md`, `.ai/MODULE_MAP.md`, `semantics/semantic_map.json`)