docs: Address CodeRabbit review findings

- SPEC-20: Check implementation checklist items (all completed)
- SPEC-21: Add language specifiers to fenced code blocks (text)
- SPEC-21: Fix type hints for `next` parameter (Callable[[ChatContext], Awaitable[None]])
- p3-ms-framework-gaps: Add language specifiers to exception hierarchy blocks

docs/bugs/p3-ms-framework-gaps.md

@@ -217,7 +217,7 @@ class AggregateContextProvider(ContextProvider):
 ## Gap 6: Exception Granularity (LOW VALUE)
 
 **What MS Framework Has:**
-```
+```text
 AgentFrameworkException (base)
 ├── AgentException
 │   ├── AgentExecutionException
@@ -239,7 +239,7 @@ AgentFrameworkException (base)
 ```
 
 **What DeepBoner Has:**
-```
+```text
 DeepBonerError (base)
 ├── SearchError
 │   └── RateLimitError

docs/specs/SPEC-20-PUBMED-JSON-FIX.md

@@ -69,13 +69,13 @@ pmids = search_data.get("esearchresult", {}).get("idlist", [])
 
 ## Implementation Checklist
 
-- [ ] Add `import json` at top of file (if not present)
-- [ ] Move `search_resp.json()` inside try block (line ~88)
-- [ ] Add `except json.JSONDecodeError` handler
-- [ ] Log warning with response preview for debugging
-- [ ] Return empty list (graceful degradation)
-- [ ] Write unit test: mock response with HTML content
-- [ ] Run `make check` (lint + typecheck + test)
+- [x] Add `import json` at top of file (if not present)
+- [x] Move `search_resp.json()` inside try block (line ~88)
+- [x] Add `except json.JSONDecodeError` handler
+- [x] Log warning with response preview for debugging
+- [x] Return empty list (graceful degradation)
+- [x] Write unit test: mock response with HTML content
+- [x] Run `make check` (lint + typecheck + test)
 
 ---
 

docs/specs/SPEC-21-MIDDLEWARE-ARCHITECTURE.md

@@ -18,7 +18,7 @@
 
 ## Current State (WRONG)
 
-```
+```text
 src/
 ├── middleware/                      ← MISLEADING: contains workflow
 │   ├── __init__.py
@@ -38,7 +38,7 @@ except Exception as e:
 
 ## Target State (CORRECT)
 
-```
+```text
 src/
 ├── workflows/                       ← RENAMED: now accurate
 │   ├── __init__.py
@@ -95,7 +95,7 @@ __all__ = ["RetryMiddleware", "TokenTrackingMiddleware"]
 """Retry middleware for chat clients with exponential backoff."""
 
 import asyncio
-from typing import Any
+from typing import Awaitable, Callable
 
 import structlog
 from agent_framework._middleware import ChatContext, ChatMiddleware
@@ -150,7 +150,9 @@ class RetryMiddleware(ChatMiddleware):
         wait = self.min_wait * (2 ** attempt)
         return min(wait, self.max_wait)
 
-    async def process(self, context: ChatContext, next: Any) -> None:
+    async def process(
+        self, context: ChatContext, next: Callable[[ChatContext], Awaitable[None]]
+    ) -> None:
         """Process the chat request with retry logic."""
         last_error: Exception | None = None
 
@@ -198,7 +200,7 @@ class RetryMiddleware(ChatMiddleware):
 """Token tracking middleware for monitoring API usage."""
 
 from contextvars import ContextVar
-from typing import Any
+from typing import Awaitable, Callable
 
 import structlog
 from agent_framework._middleware import ChatContext, ChatMiddleware
@@ -226,7 +228,9 @@ class TokenTrackingMiddleware(ChatMiddleware):
         self.total_output_tokens = 0
         self.request_count = 0
 
-    async def process(self, context: ChatContext, next: Any) -> None:
+    async def process(
+        self, context: ChatContext, next: Callable[[ChatContext], Awaitable[None]]
+    ) -> None:
         """Process request and track token usage."""
         await next(context)