Update documentation for AzureDevOpsApi trait convention

Add trait convention to CLAUDE.md, code-reviewer, and plan-reviewer.
Update PROJECT.md tool function signature and ARCHITECTURE.md with
api_trait.rs and tests/ directory listing. Update plan checkmarks.

Author: danielealbano

.claude/agents/code-reviewer.md

@@ -86,6 +86,7 @@ You MUST verify ALL of the following in changed code:
 - **Async safety**: No blocking calls in async context. `tokio::task::spawn_blocking` for blocking operations. No fire-and-forget spawns without shutdown path. Flag violations as CRITICAL.
 - **Shared state**: `Arc<T>` for shared immutable state across tasks. `Arc<Mutex<T>>` or `tokio::sync::Mutex<T>` for shared mutable state. Flag unprotected shared mutable state as CRITICAL.
 - **MCP tool pattern**: Tools use `#[mcp_tool(name, description)]`, args struct with `Deserialize + JsonSchema`, return `Result<CallToolResult, McpError>`, convert domain errors via `.map_err()`. Flag deviations.
+- **AzureDevOpsApi trait**: Tool functions MUST accept `&(dyn AzureDevOpsApi + Send + Sync)`, not `&AzureDevOpsClient`. API calls MUST go through trait methods, not standalone functions. Flag deviations.
 - **Logging**: Use `log` crate. Correct log levels (trace/debug/info/warn/error). Never log secrets or tokens. Flag violations.
 - **CLI conventions**: All config via clap CLI flags. No env vars for config (except `RUST_LOG` for logging). Flag deviations.
 

.claude/agents/plan-reviewer.md

@@ -105,6 +105,7 @@ You MUST verify ALL of the following for EVERY action's planned code:
 - **Async safety**: No blocking calls in async context. `tokio::task::spawn_blocking` for blocking operations. No fire-and-forget spawns without shutdown path. Flag violations as CRITICAL.
 - **Shared state**: `Arc<T>` for shared immutable state. `Arc<Mutex<T>>` for shared mutable state. Flag unprotected shared mutable state as CRITICAL.
 - **MCP tool pattern**: Tools use `#[mcp_tool(name, description)]`, args struct with `Deserialize + JsonSchema`, return `Result<CallToolResult, McpError>`, convert domain errors via `.map_err()`. Flag deviations.
+- **AzureDevOpsApi trait**: Planned tool functions MUST accept `&(dyn AzureDevOpsApi + Send + Sync)`, not `&AzureDevOpsClient`. API calls MUST go through trait methods. Flag deviations.
 - **Logging**: Use `log` crate. Correct log levels (trace/debug/info/warn/error). Never log secrets. Flag violations.
 - **CLI conventions**: All config via clap CLI flags. No env vars for config (except `RUST_LOG`). Flag deviations.
 

CLAUDE.md

@@ -246,9 +246,15 @@ This project uses specialized subagents (defined in `.claude/agents/`) to enforc
 - Use `mockall` (in dev-dependencies) for generating mock implementations.
 - Keep traits small (1–3 methods). Prefer composing small traits over large ones.
 
+### AzureDevOpsApi trait
+- All MCP tool functions accept `&(dyn AzureDevOpsApi + Send + Sync)` instead of `&AzureDevOpsClient`.
+- `AzureDevOpsApi` is defined in `src/azure/api_trait.rs` with `#[cfg_attr(feature = "test-support", mockall::automock)]`.
+- `AzureDevOpsClient` implements the trait by delegating to the standalone API functions.
+- Integration tests use `MockAzureDevOpsApi` (enabled via `test-support` feature) to verify tool behavior without external services.
+
 ### Dependency injection
 - Pass dependencies explicitly via constructor parameters (`new()`).
-- Use `Arc<T>` for shared ownership across async tasks (e.g., `Arc<AzureDevOpsClient>` in `AzureMcpServer`).
+- Use `Arc<T>` for shared ownership across async tasks (e.g., `Arc<dyn AzureDevOpsApi + Send + Sync>` in `AzureMcpServer`).
 - Do NOT rely on mutable global state or `lazy_static!` for wiring dependencies (compile-time constants via `once_cell::sync::Lazy` for regex patterns are acceptable).
 
 ### Concurrency and safety

docs/ARCHITECTURE.md

@@ -20,13 +20,25 @@ graph LR
 ├── build.rs                      # Scans #[mcp_tool] → generates tool router
 ├── Makefile                      # build, test, lint, fmt targets
 ├── Dockerfile                    # Multi-stage: rust:alpine → alpine
+├── tests/                        # Integration tests (anti-prompt-injection, tool behavior)
+│   ├── common/
+│   │   └── mod.rs                # Shared helpers (assert_tool_output_has_warning)
+│   ├── test_tools_organizations.rs
+│   ├── test_tools_projects.rs
+│   ├── test_tools_teams.rs
+│   ├── test_tools_boards.rs
+│   ├── test_tools_tags.rs
+│   ├── test_tools_work_item_types.rs
+│   ├── test_tools_classification_nodes.rs
+│   └── test_tools_work_items.rs
 ├── src/
 │   ├── main.rs                   # CLI entry (clap), transport selection
 │   ├── lib.rs                    # Library root: re-exports modules
 │   ├── compact_llm.rs            # Compact JSON serializer for LLM output
 │   ├── azure/                    # Azure DevOps API client layer
 │   │   ├── mod.rs
 │   │   ├── client.rs             # AzureDevOpsClient, AzureError, auth, HTTP helpers
+│   │   ├── api_trait.rs          # AzureDevOpsApi trait + MockAzureDevOpsApi (test-support feature)
 │   │   ├── models.rs             # Shared data types (WorkItem, Board, Comment, etc.)
 │   │   ├── boards.rs             # Boards API
 │   │   ├── classification_nodes.rs # Area/Iteration paths API
@@ -191,7 +203,7 @@ classDiagram
     }
 
     class AzureMcpServer {
-        -Arc~AzureDevOpsClient~ client
+        -Arc~dyn AzureDevOpsApi~ client
         -ToolRouter~Self~ tool_router
         +new(client) Self
     }

docs/PROJECT.md

@@ -154,6 +154,6 @@ MCP tool responses are optimized for LLM consumption:
 Each tool follows this pattern:
 1. Define `Args` struct with `Deserialize` + `JsonSchema` (schemars).
 2. Annotate the async function with `#[mcp_tool(name = "...", description = "...")]`.
-3. Function signature: `pub async fn tool_name(client: &AzureDevOpsClient, args: ArgsType) -> Result<CallToolResult, McpError>`.
+3. Function signature: `pub async fn tool_name(client: &(dyn AzureDevOpsApi + Send + Sync), args: ArgsType) -> Result<CallToolResult, McpError>`.
 4. Convert domain errors to `McpError` via `.map_err()`.
 5. Return `tool_text_success(content)` (from `support/tool_text_success.rs`) — this automatically prepends the anti-prompt-injection warning to all tool responses. Never use `CallToolResult::success(vec![Content::text(...)])` directly.

docs/plans/1_azure_devops_api_trait_integration_tests_20260311142611.md

@@ -14,14 +14,14 @@ Tools currently take `&AzureDevOpsClient` directly, making mocking impossible. T
 
 Establishes the mockable API boundary so tools can be tested without external services.
 
-- [ ] `list_team_members` normalized from `impl AzureDevOpsClient` method to standalone fn in `teams.rs`
-- [ ] `create_work_item`/`update_work_item` in `work_items.rs` accept owned types: `&[(String, Value)]`, `&[(String, String)]`
-- [ ] `AzureDevOpsApi` trait in `src/azure/api_trait.rs` with 23 async methods and `#[cfg_attr(feature = "test-support", mockall::automock)]`
-- [ ] `impl AzureDevOpsApi for AzureDevOpsClient` delegating to existing standalone functions
-- [ ] `mockall` moved to optional dependency, `test-support` feature added to `Cargo.toml`
-- [ ] Module registered in `src/azure/mod.rs`
-- [ ] `UNTRUSTED_CONTENT_WARNING` exported from `src/mcp/tools/support/mod.rs`
-- [ ] Makefile updated to pass `--features test-support` to test/lint targets
+- [x] `list_team_members` normalized from `impl AzureDevOpsClient` method to standalone fn in `teams.rs`
+- [x] `create_work_item`/`update_work_item` in `work_items.rs` accept owned types: `&[(String, Value)]`, `&[(String, String)]`
+- [x] `AzureDevOpsApi` trait in `src/azure/api_trait.rs` with 23 async methods and `#[cfg_attr(feature = "test-support", mockall::automock)]`
+- [x] `impl AzureDevOpsApi for AzureDevOpsClient` delegating to existing standalone functions
+- [x] `mockall` moved to optional dependency, `test-support` feature added to `Cargo.toml`
+- [x] Module registered in `src/azure/mod.rs`
+- [x] `UNTRUSTED_CONTENT_WARNING` exported from `src/mcp/tools/support/mod.rs`
+- [x] Makefile updated to pass `--features test-support` to test/lint targets
 
 ### Task 1.1: Normalize `list_team_members` in `src/azure/teams.rs` (modify)
 
@@ -528,11 +528,11 @@ Pass `--features test-support` to test and lint targets so `MockAzureDevOpsApi`
 
 Replace concrete `AzureDevOpsClient` references with the trait throughout the tool stack so mocks can be injected.
 
-- [ ] `AzureMcpServer.client` is `Arc<dyn AzureDevOpsApi + Send + Sync>`
-- [ ] `build.rs` delegates via `&*self.client`
-- [ ] All 24 tool functions accept `&(dyn AzureDevOpsApi + Send + Sync)`
-- [ ] All API calls go through trait methods
-- [ ] `main.rs` unchanged
+- [x] `AzureMcpServer.client` is `Arc<dyn AzureDevOpsApi + Send + Sync>`
+- [x] `build.rs` delegates via `&*self.client`
+- [x] All 24 tool functions accept `&(dyn AzureDevOpsApi + Send + Sync)`
+- [x] All API calls go through trait methods
+- [x] `main.rs` unchanged
 
 ### Task 2.1: Update `src/mcp/server.rs` (modify)
 
@@ -687,9 +687,9 @@ All tool files MUST keep `CallToolResult` in the `rmcp::model` import — it is
 
 Proves every tool prepends the anti-prompt-injection warning by exercising real tool functions against mocked API.
 
-- [ ] Every MCP tool has an integration test verifying anti-prompt-injection warning prefix
-- [ ] Tests use `MockAzureDevOpsApi` from `#[automock]`
-- [ ] Tests exercise full tool function → `CallToolResult` path
+- [x] Every MCP tool has an integration test verifying anti-prompt-injection warning prefix
+- [x] Tests use `MockAzureDevOpsApi` from `#[automock]`
+- [x] Tests exercise full tool function → `CallToolResult` path
 
 ### Task 3.1: Create `tests/common/mod.rs` (create)
 
@@ -799,11 +799,11 @@ Note: the `extract_text_from_result` implementation depends on rmcp's `Content`
 
 Ensure project docs and reviewer agents are aware of the new `AzureDevOpsApi` trait convention.
 
-- [ ] `CLAUDE.md` updated with trait convention
-- [ ] `.claude/agents/code-reviewer.md` updated
-- [ ] `.claude/agents/plan-reviewer.md` updated
-- [ ] `docs/PROJECT.md` updated
-- [ ] `docs/ARCHITECTURE.md` updated
+- [x] `CLAUDE.md` updated with trait convention
+- [x] `.claude/agents/code-reviewer.md` updated
+- [x] `.claude/agents/plan-reviewer.md` updated
+- [x] `docs/PROJECT.md` updated
+- [x] `docs/ARCHITECTURE.md` updated
 
 ### Task 4.1: Update `CLAUDE.md` (modify)