#region Traceability [C:3] [TYPE ADR] [SEMANTICS traceability,rtm,agent-chat]
@defgroup Trace Matrix v2 — Requirements → Model → API → Task → Test for 035-agent-chat-context.

## Traceability Matrix

**2026-07-05 verification update**: production code and dedicated US1/US2 tests are present. Remaining open items are live E2E / quickstart validation requiring a running stack and available LLM quota.

| Story | Requirement | Model/Contract | API/SSE | Backend Task | Frontend Task | Test | 2026-07-05 Status |
|-------|------------|----------------|---------|-------------|--------------|------|-------------------|
| US1 | AGCTX-FR-001, FR-003 | AgentChat.Model | — | — | T010, T011, T012 | T007 | ✅ Implemented + `AgentChatModel.context.test.ts` |
| US1 | AGCTX-FR-002, FR-004 | AgentChat.Context.Inject, Validate | Gradio submit (uicontext appended) | T005, T013, T014 | — | T008 | ✅ Implemented + `test_agent_context.py` |
| US1 | AGCTX-FR-005 | AgentChat.ToolFilter.Pipeline | `pipeline_result` debug SSE | T006 | T042 | T009 | ✅ Implemented + `test_agent_tool_filter.py` |
| US1 | prod warning | AgentChat.Model | — | — | T015, T016 | T007 | ✅ Implemented + model context test |
| US2 | AGGRD-FR-001, FR-002 | AgentChat.Confirmation.GuardV2 | confirm_required (extended) | T022 | T025, T026, T027 | T020, T021 | ✅ Implemented + `test_agent_confirmation_v2.py` + UX tests |
| US2 | AGGRD-FR-003 | AgentChat.Confirmation.PermissionDenied | permission_denied | T023, T024 | T028 | T020 | ✅ Implemented + contract tests |
| US2 | AGGRD-FR-004 | AgentChat.StreamProcessor | confirm_resolved (denied) | — | T029 | T021 | ✅ Implemented + UX tests |
| US3 | AGTL-FR-001, FR-005 | AgentChat.ToolFilter.InvocationGuard | permission_denied | T006, T024 | — | T009 | ✅ Implemented + pipeline/RBAC tests |
| US3 | AGTL-FR-002 | AgentChat.Tools.Retry | tool_retry | T037 | T040, T041 | T033, T036 | ✅ Implemented and tested |
| US3 | AGTL-FR-003 | AgentChat.Tools.Summarise | — | T038 | — | T034 | ✅ Implemented and tested |
| US3 | AGTL-FR-004 | AgentChat.Tools.Timeout | tool_timeout | T039 | T040, T041 | T035, T036 | ✅ Implemented and tested |
| US3 | AGTL-FR-006 (SHOULD) | AgentChat.EmbeddingRouter | — | post-MVP | — | — | Deferred post-MVP |
| SC-006 | AGCTX-FR-004 (validation) | AgentChat.Context.Validate | — | T005 | — | T008 | ✅ Validator + dedicated context tests |

## Impact Analysis

| If you change... | Contracts verify | Tests verify | Screens depend |
|-----------------|-----------------|-------------|----------------|
| agent_handler uicontext pos | AgentChat.LangGraph.Handler | T008 / `test_agent_context.py` | AgentChat panel |
| _CONTEXT_TOOL_AFFINITY | AgentChat.ToolFilter.Pipeline | T009 / `test_agent_tool_filter.py` | AgentChat panel |
| _TOOL_PERMISSIONS | AgentChat.ToolFilter.InvocationGuard | T009/T020 | AgentChat panel |
| build_confirmation_contract_v2 | AgentChat.Confirmation.GuardV2 | T020/T021 / `test_agent_confirmation_v2.py` | ConfirmationCard |
| yield_permission_denied | AgentChat.Confirmation.PermissionDenied | T020 + UX tests | ConfirmationCard |
| _retry_read_tool | AgentChat.Tools.Retry | T033 | ToolCallCard |
| _execute_with_timeout | AgentChat.Tools.Timeout | T035 | ToolCallCard |

## Contract → Fixture Mapping

| Production Contract | Fixture |
|--------------------|---------|
| AgentChat.LangGraph.Handler | FX_AgentChat.Handler.* (3 fixtures) |
| AgentChat.Confirmation.GuardV2 | FX_AgentChat.Guard.* (4 fixtures) |
| AgentChat.ToolFilter.Pipeline | FX_AgentChat.Filter.* (3 fixtures) |
| AgentChat.Tools.Retry | FX_AgentChat.Retry.* (3 fixtures) |
| AgentChat.Model.SetContext | FX_AgentChat.SetContext.* (2 fixtures) |
| AgentChat.Context.Validate | FX_AgentChat.Validate.* (4 fixtures — valid, invalid_type, oversized, long_name) |

#endregion Traceability