# Feature Specification: LLM Chat Assistant for Project Operations

**Feature Branch**: `021-llm-project-assistant`
**Reference UX**: `ux_reference.md` (See specific folder)  
**Created**: 2026-02-23  
**Status**: Draft  
**Input**: User description: "Создать чат-ассистента на базе LLM в веб-интерфейсе, чтобы управлять Git, миграциями/бэкапами, LLM-анализом и статусами задач через команды на естественном языке."

## User Scenarios & Testing *(mandatory)*

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

As an operator, I can open an in-app chat and submit natural-language commands so I can trigger key actions without navigating multiple pages.

**Why this priority**: Chat entrypoint is the core product value. Without it, no assistant workflow exists.

**Independent Test**: Open assistant panel, send a command like "создай ветку feature-abc для дашборда 42", and verify that assistant returns a structured actionable response.

**Acceptance Scenarios**:

1. **Given** an authenticated user on any main page, **When** they open the assistant and send a message, **Then** the message appears in chat history and receives a response.
2. **Given** assistant is available, **When** the user asks for supported actions, **Then** assistant returns clear examples for Git, migration/backup, analysis, and task status queries.

---

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

As an operator, I can ask assistant to execute core system operations (Git, migration/backup, LLM analysis/docs, status/report checks) so I can run workflows faster.

**Why this priority**: Command execution across core modules defines feature completeness.

**Independent Test**: Send one command per capability group and verify that the corresponding backend task/API action is initiated with valid parameters.

**Acceptance Scenarios**:

1. **Given** user command targets Git operation, **When** assistant parses intent and entities, **Then** system starts corresponding Git operation (branch/commit/deploy) or returns explicit validation error.
2. **Given** user command targets migration or backup, **When** assistant executes command, **Then** system starts async task and returns created `task_id` immediately.
3. **Given** user command targets LLM validation/documentation, **When** assistant executes command, **Then** system triggers the relevant LLM task/plugin and returns launch confirmation with `task_id`.
4. **Given** user asks task/report status, **When** assistant handles request, **Then** it returns latest known status and linkable reference to existing task tracking UI.

---

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

As a system administrator, I need assistant actions to respect existing permissions and require explicit user confirmation for risky operations.

**Why this priority**: Security and production safety are mandatory gate criteria.

**Independent Test**: Run restricted command with unauthorized user (expect deny), and run production deploy command (expect confirm-before-execute flow).

**Acceptance Scenarios**:

1. **Given** user lacks permission for requested operation, **When** assistant tries to execute command, **Then** execution is denied and assistant returns permission error without side effects.
2. **Given** command is classified as dangerous (e.g., deploy to production), **When** assistant detects it, **Then** assistant requires explicit user confirmation before creating task.
3. **Given** confirmation is requested, **When** user cancels or confirmation expires, **Then** operation is not executed.

---

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

As an operator, I need immediate operation feedback, clear errors, and traceable progress for long-running tasks.

**Why this priority**: Strong feedback loop is required for operational trust and usability.

**Independent Test**: Launch long migration via chat and verify immediate "started" message with `task_id`, then check progress in Task Drawer and reports page.

**Acceptance Scenarios**:

1. **Given** assistant starts long operation, **When** execution begins, **Then** assistant responds immediately with initiation status and `task_id`.
2. **Given** operation succeeds or fails, **When** task result becomes available, **Then** assistant can return outcome summary (success/error) on user request.
3. **Given** assistant cannot parse command confidently, **When** ambiguity is detected, **Then** assistant asks clarification question and does not execute action.

---

### Edge Cases

- User command matches multiple possible operations (ambiguous intent).
- User references non-existent dashboard/environment/task IDs.
- Duplicate command submission (double-send) for destructive operations.
- Confirmation token expires before user confirms.
- Provider/LLM unavailable during command interpretation.
- Task creation succeeds but downstream execution fails immediately.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST provide an in-application chat interface for assistant interaction.
- **FR-002**: System MUST preserve chat context per user session for at least the active session duration.
- **FR-003**: Assistant MUST support natural-language command parsing for these domains: Git, migration/backup, LLM analysis/documentation, task/report status.
- **FR-004**: Assistant MUST map parsed commands to existing internal operations/APIs and MUST NOT bypass current service boundaries.
- **FR-005**: Assistant MUST support Git commands for at least: branch creation, commit initiation, deploy initiation.
- **FR-006**: Assistant MUST support migration and backup launch commands and return created `task_id`.
- **FR-007**: Assistant MUST support LLM validation/documentation launch commands and return created `task_id`.
- **FR-008**: Assistant MUST support status queries for existing tasks by `task_id` and by recent user scope.
- **FR-009**: Assistant MUST enforce existing RBAC/permission checks before any operation execution.
- **FR-010**: Assistant MUST classify risky operations and require explicit confirmation before execution.
- **FR-011**: Confirmation flow MUST include timeout/expiry semantics and explicit cancel path.
- **FR-012**: Assistant MUST provide immediate response for long-running operations containing `task_id` and a short tracking hint.
- **FR-013**: Assistant responses MUST include operation result state: `success`, `failed`, `started`, `needs_confirmation`, `needs_clarification`, or `denied`.
- **FR-014**: Assistant MUST surface actionable error details without exposing secrets.
- **FR-015**: Assistant MUST log every attempted assistant command with actor, intent, parameters snapshot, and outcome for auditability.
- **FR-016**: Assistant MUST prevent duplicate execution for the same pending confirmation token.
- **FR-017**: Assistant MUST support multilingual command input at minimum for Russian and English operational phrasing.
- **FR-018**: Assistant MUST degrade safely when intent confidence is below threshold by requesting clarification instead of executing.
- **FR-019**: Assistant MUST link users to existing progress surfaces (Task Drawer and reports page) for task tracking.
- **FR-020**: Assistant MUST support retrieval of last N executed assistant commands for operational traceability.

### Key Entities *(include if feature involves data)*

- **AssistantMessage**: One chat message (user or assistant) with timestamp, role, text, and metadata.
- **CommandIntent**: Parsed intent structure containing domain, operation, entities, confidence, and risk level.
- **ExecutionRequest**: Validated command payload mapped to a concrete backend action.
- **ConfirmationToken**: Pending confirmation record for risky operations with TTL and one-time usage.
- **AssistantExecutionLog**: Audit trail entry for command attempts and outcomes.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: At least 90% of predefined core commands (Git/migration/backup/LLM/status) are correctly interpreted in acceptance test set.
- **SC-002**: 100% of risky operations (production deploy and equivalent) require explicit confirmation before execution.
- **SC-003**: 100% of assistant-started long-running operations return a `task_id` in the first response.
- **SC-004**: Permission bypass rate is 0% in security tests (unauthorized commands never execute).
- **SC-005**: At least 95% of assistant responses return within 2 seconds for parse/dispatch stage (excluding downstream task runtime).
- **SC-006**: At least 90% of operators can launch a target operation from chat faster than through manual multi-page navigation in usability checks.

---

## Assumptions

- Existing APIs/plugins for Git, migration, backup, LLM actions, and task status remain authoritative execution backends.
- Existing RBAC permissions (`plugin:*`, `tasks:*`, `admin:*`) remain the access model.
- Task Drawer and reports page remain current progress/result surfaces and will be reused.
- LLM assistant orchestration can use configured provider stack without introducing a separate auth model.

## Dependencies

- Existing routes/services for Git (`/api/git/...`), migration (`/api/execute`), task APIs (`/api/tasks/...`), and LLM provider/task flows.
- Existing authentication and authorization components from multi-user auth implementation.
- Existing task manager persistence/logging for async execution tracking.

---

## Test Data Fixtures *(recommended for CRITICAL components)*

### Fixtures

```yaml
assistant_command_git_branch:
  description: "Valid RU command for branch creation"
  data:
    message: "сделай ветку feature/revenue-v2 для дашборда 42"
    expected:
      domain: "git"
      operation: "create_branch"
      entities:
        dashboard_id: 42
        branch_name: "feature/revenue-v2"

assistant_command_migration_start:
  description: "Valid migration launch command"
  data:
    message: "запусти миграцию с dev на prod для дашборда 42"
    expected:
      domain: "migration"
      operation: "execute"
      requires_confirmation: true

assistant_command_prod_deploy_confirmation:
  description: "Risky production deploy requires confirmation"
  data:
    message: "задеплой дашборд 42 в production"
    expected:
      state: "needs_confirmation"
      confirmation_required: true

assistant_status_query:
  description: "Task status lookup"
  data:
    message: "проверь статус задачи task-123"
    expected:
      domain: "status"
      operation: "get_task"
      entities:
        task_id: "task-123"
```