feat(assistant): implement spec 021 chat assistant flow with semantic contracts

specs/021-llm-project-assistant/quickstart.md

@@ -0,0 +1,92 @@
+# 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`)