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

specs/021-llm-project-assistant/data-model.md

@@ -0,0 +1,156 @@
+# Data Model: LLM Chat Assistant for Project Operations
+
+**Feature**: [`021-llm-project-assistant`](specs/021-llm-project-assistant)  
+**Spec**: [`spec.md`](specs/021-llm-project-assistant/spec.md)  
+**Research**: [`research.md`](specs/021-llm-project-assistant/research.md)
+
+## 1. Entity: AssistantMessage
+
+Represents one chat message in assistant conversation.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| message_id | string | Yes | Unique message identifier. |
+| conversation_id | string | Yes | Logical chat session/thread identifier. |
+| role | enum | Yes | `user`, `assistant`, `system`. |
+| text | string | Yes | Message content. |
+| created_at | datetime | Yes | Message timestamp. |
+| metadata | object | No | Additional structured metadata (state badge, task link, etc.). |
+
+### Validation Rules
+
+- `text` must be non-empty.
+- `role` must be one of allowed values.
+- `conversation_id` must be bound to authenticated user scope.
+
+---
+
+## 2. Entity: CommandIntent
+
+Represents parsed intent from user message.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| intent_id | string | Yes | Parsed intent identifier. |
+| domain | enum | Yes | `git`, `migration`, `backup`, `llm`, `status`, `report`, `unknown`. |
+| operation | string | Yes | Normalized operation key (e.g., `create_branch`, `execute_migration`). |
+| entities | object | No | Parsed parameters (`dashboard_id`, `env`, `task_id`, etc.). |
+| confidence | number | Yes | Confidence score `0.0..1.0`. |
+| risk_level | enum | Yes | `safe`, `guarded`, `dangerous`. |
+| requires_confirmation | boolean | Yes | Indicates confirmation gate requirement. |
+
+### Validation Rules
+
+- `confidence` must be in `[0.0, 1.0]`.
+- `requires_confirmation=true` when `risk_level=dangerous`.
+- Missing mandatory entities triggers `needs_clarification` decision.
+
+---
+
+## 3. Entity: ExecutionRequest
+
+Validated request ready for dispatch to existing backend action.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| execution_id | string | Yes | Execution request identifier. |
+| actor_user_id | string | Yes | Authenticated user initiating request. |
+| intent_id | string | Yes | Source `CommandIntent` reference. |
+| dispatch_target | string | Yes | Internal route/service/plugin target identifier. |
+| payload | object | Yes | Validated action payload. |
+| status | enum | Yes | `pending`, `dispatched`, `failed`, `denied`, `cancelled`. |
+| task_id | string | No | Linked async task id if created. |
+
+### Validation Rules
+
+- Dispatch target must map to known execution backend.
+- Permission checks must pass before `dispatched`.
+
+---
+
+## 4. Entity: ConfirmationToken
+
+One-time confirmation artifact for dangerous operations.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| confirmation_id | string | Yes | Unique confirmation token id. |
+| actor_user_id | string | Yes | User who must confirm/cancel. |
+| intent_snapshot | object | Yes | Immutable normalized intent snapshot. |
+| expires_at | datetime | Yes | Token expiry timestamp. |
+| state | enum | Yes | `pending`, `confirmed`, `cancelled`, `expired`, `consumed`. |
+| created_at | datetime | Yes | Creation time. |
+| consumed_at | datetime | No | Time of finalization. |
+
+### Validation Rules
+
+- Only token owner can confirm/cancel.
+- `confirmed` token transitions to `consumed` after one dispatch.
+- Expired token cannot transition to `confirmed`.
+
+---
+
+## 5. Entity: AssistantExecutionLog
+
+Structured audit record of assistant decision and outcome.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| log_id | string | Yes | Unique audit id. |
+| user_id | string | Yes | Actor user id. |
+| conversation_id | string | Yes | Conversation reference. |
+| raw_message | string | Yes | Original user message. |
+| normalized_intent | object | No | Parsed intent snapshot. |
+| decision | enum | Yes | `executed`, `needs_confirmation`, `needs_clarification`, `denied`, `failed`. |
+| outcome | enum | Yes | `success`, `error`, `started`, `cancelled`, `n/a`. |
+| task_id | string | No | Linked async task id. |
+| created_at | datetime | Yes | Audit timestamp. |
+
+### Validation Rules
+
+- Audit entry required for every command-processing attempt.
+- `task_id` required when `outcome=started` for async operations.
+
+---
+
+## 6. Relationships
+
+- `AssistantMessage` (user role) -> may produce one `CommandIntent`.
+- `CommandIntent` -> may produce one `ExecutionRequest` or `ConfirmationToken`.
+- `ConfirmationToken` (confirmed) -> produces one `ExecutionRequest`.
+- `ExecutionRequest` -> may link to one async `task_id` in existing task manager.
+- Every processed command -> one `AssistantExecutionLog`.
+
+---
+
+## 7. State Flows
+
+### Command Decision Flow
+
+`received` -> `parsed` -> (`needs_clarification` | `denied` | `needs_confirmation` | `dispatch`)
+
+### Confirmation Flow
+
+`pending` -> (`confirmed` -> `consumed`) | `cancelled` | `expired`
+
+### Execution Flow
+
+`pending` -> (`dispatched` -> `started/success`) | `failed` | `denied` | `cancelled`
+
+---
+
+## 8. Scale Assumptions
+
+- Conversation history is moderate per user and can be paginated.
+- Command audit retention aligns with existing operational retention policies.
+- Assistant parse step must remain lightweight and avoid blocking task execution system.