ss-tools/specs/033-gradio-agent-chat/traceability.md

#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