#region Traceability [C:3] [TYPE ADR] [SEMANTICS traceability,rtm,agent-chat]
@defgroup Trace Matrix Requirements → Model → API → Fixture → Task → Test for Gradio Agent Chat.

## Traceability Matrix

| Story | Screen | Model | Fixture | API Endpoint | Backend Task | Frontend Task | Test |
|-------|--------|-------|---------|-------------|:-----------:|:------------:|------|
| **US1**: Streaming Chat | AssistantChatPanel | AgentChat.Model | FX_AgentChat.Model.SendMessage.Valid | `submit("/chat")` | T015, T017 | T018, T019 | Test.AgentChat.Model |
| **US1**: Cancel | AssistantChatPanel | AgentChat.Model | FX_AgentChat.Model.CancelGeneration | `submission.cancel()` | — | T020 | Test.AgentChat.Model |
| **US1**: Reconnect | AssistantChatPanel | AgentChat.Model | — | `Client.connect()` | — | T022 | Test.AgentChat.Model |
| **US2**: Tool Selection | `/agent` | AgentChat.Tools | — | FastAPI REST via native `@tool` | T026, T028, T097 | T031 | Test.AgentChat.Tools |
| **US2**: Tool Context Budget | `/agent` | AgentChat.Tools | — | Hybrid `get_tools_for_query()` before `create_agent()` | T098, T099, T105 | — | Test.AgentChat.Tools, Test.IntentKeyword.Edges |
| **US2**: HITL Confirm | `/agent` | AgentChat.Model | FX_AgentChat.Model.ResumeConfirm | `submit("/chat",...,[convId,"confirm"])` | T029, T100 | T031 | Test.AgentChat.Model |
| **US2**: HITL Deny | `/agent` | AgentChat.Model | FX_AgentChat.Model.ResumeDeny | `submit("/chat",...,[convId,"deny"])` | T029, T100 | T031 | Test.AgentChat.Model |
| **US2**: Negation Guard | `/agent` | AgentChat.ToolResolver | — | `fast_confirmation_tool()` regex pre-check | T104 | — | Test.IntentKeyword.Edges |
| **US3**: Tool Visibility | AssistantChatPanel | AgentChat.Model | — | — | — | T040, T041 | Test.AgentChat.ToolCallCard |
| **US4**: Context | `/agent` | AgentChat.LangGraph | — | `thread_id=conversation_id` + PostgreSQL persistence/checkpoints | T045 | — | Test.AgentChat.LangGraph |
| **US5**: List Conversations | ConversationList | AgentChat.Model | FX_AgentChat.Conversations.ListValid | `GET /api/assistant/conversations` | T052, T053 | T059 | Test.AgentChat.Api |
| **US5**: List Empty | ConversationList | AgentChat.Model | FX_AgentChat.Conversations.ListEmpty | `GET /api/assistant/conversations` | T052 | T059 | Test.AgentChat.Api |
| **US5**: Load History | AssistantChatPanel | AgentChat.Model | FX_AgentChat.History.Valid | `GET /api/assistant/history` | T054 | T019 | Test.AgentChat.Api |
| **US5**: Delete/Archive | ConversationList | AgentChat.Model | FX_AgentChat.Delete.Valid | `DELETE /api/assistant/conversations/{id}` | T055 | T058 | Test.AgentChat.Api |
| **US5**: Delete Not Owner | ConversationList | — | FX_AgentChat.Delete.NotOwner | `DELETE /api/assistant/conversations/{id}` | T055 | — | Test.AgentChat.Api |
| **US6**: File Upload | AssistantChatPanel | AgentChat.Model | FX_AgentChat.Document.ParsePdf.Valid | `submit("/chat", {text, files})` | T065, T066 | T068, T069 | Test.AgentChat.Document |
| **US6**: PDF Encrypted | — | AgentChat.Document | FX_AgentChat.Document.ParsePdf.Encrypted | — | T065 | — | Test.AgentChat.Document |
| **US6**: XLSX Password | — | AgentChat.Document | FX_AgentChat.Document.ParseXlsx.PasswordProtected | — | T065 | — | Test.AgentChat.Document |
| **—**: Debug Info | `/agent` | AgentChat.Model | — | UI-derived state | T101 | T073 | Browser snapshot |
| **—**: DEV Mode Transport | `/agent` | AgentChat.GradioApp | — | `/api/agent/gradio` same-origin proxy | T102 | T073 | Browser snapshot + run tests |
| **—**: Service Auth | — | — | FX_AgentChat.ServiceToken.Valid | `POST /api/auth/service-token` | T080 | — | Test.AgentChat.Api |
| **—**: Rejected Paths | — | AgentChat.Model | FX_AgentChat.Model.RejectedPath | — | — | — | Test.AgentChat.Model.RejectedPaths |

## Impact Analysis Quick Reference

| If you change... | These fixtures verify it | These tests verify it | These screens depend |
|-----------------|------------------------|----------------------|---------------------|
| `AgentChat.Model.sendMessage()` | FX_AgentChat.Model.SendMessage.Valid, ResumeConfirm, ResumeDeny, CancelGeneration | Test.AgentChat.Model | AssistantChatPanel, /agent |
| `POST /api/assistant/conversations` | FX_AgentChat.Conversations.ListValid, ListEmpty | Test.AgentChat.Api | ConversationList, AssistantChatPanel |
| `GET /api/assistant/history` | FX_AgentChat.History.Valid, NotFound | Test.AgentChat.Api | AssistantChatPanel |
| `DELETE /api/assistant/conversations/{id}` | FX_AgentChat.Delete.Valid, NotOwner, NotFound | Test.AgentChat.Api | ConversationList |
| `@tool` functions in tools.py | — | Test.AgentChat.Tools | Gradio agent handler |
| `get_tools_for_query()` hybrid router behavior | — | Test.AgentChat.Tools / Test.IntentKeyword.Edges | Gradio agent handler |
| `_embedding_router.py` fallback logic | — | Test.EmbeddingRouter | Gradio agent handler |
| `fast_confirmation_tool()` negation guard | — | Test.IntentKeyword.Edges | Gradio agent handler |
| Document parser | FX_AgentChat.Document.ParsePdf.Valid, ParseXlsx.Valid | Test.AgentChat.Document | Gradio agent handler |
| `@gradio/client` transport | FX_AgentChat.Model.RejectedPath (WebSocket guardrail) | Test.AgentChat.Model.RejectedPaths | AssistantChatPanel |
| `POST /api/auth/service-token` | FX_AgentChat.ServiceToken.Valid, InvalidSecret | Test.AgentChat.Api | Gradio container startup |

## Fixture Count

| Category | Count |
|----------|:-----:|
| API fixtures | 14 |
| Model fixtures | 5 |
| **Total** | **19** |

## Current Verification Snapshot (2026-06-30)

| Slice | Command | Result |
|-------|---------|--------|
| Backend agent | `cd backend && source .venv/bin/activate && python -m pytest tests/test_agent/ -v` | 375 passed, 18 warnings |
| Frontend model | `cd frontend && npm run test -- src/lib/models/__tests__/AgentChatModel.test.ts --run` | 73 passed |
| Frontend build | `cd frontend && npm run build` | Passed; existing unrelated Svelte warnings |

#endregion Traceability