feat: metagame workflows, sideboard workflows, Moxfield search (#49, #50)

[j4th]

Summary

• Issue Add constructed metagame workflow tools #49: 4 constructed metagame workflow tools (metagame_snapshot, archetype_decklist, archetype_comparison, format_entry_guide) with MTGGoldfish primary / Spicerack fallback
• Issue Add sideboard analysis tools for Bo3 constructed formats #50: 3 sideboard workflow tools (suggest_sideboard, sideboard_guide, sideboard_matrix) with heuristic category matching and MTGGoldfish enrichment
• Moxfield expansion: 2 new provider tools (search_decks, user_decks) + 3 new Pydantic models (MoxfieldDeckSummary, MoxfieldUser, MoxfieldSearchResult)
• Shared utility: utils/fuzzy.py for archetype/matchup name matching (difflib.SequenceMatcher)
• 2 new prompts: explore_format, build_constructed_deck

60 → 69 tools, 17 → 19 prompts. 1336 tests, 88% coverage.

Closes #49, closes #50.

Test plan

• 1336 tests pass (mise run check)
• Lint clean (ruff)
• Typecheck clean (ty)
• Live smoke test (mise run test:live)
• Interactive smoke test (/smoke-test) for new metagame/sideboard/Moxfield tools

🤖 Generated with Claude Code

[claude]

Claude encountered an error —— View job

---

PR Review Summary

Verdict: APPROVE — solid implementation with two minor doc/test gaps worth addressing.

---

Important Issues (should fix)

1. docs/SERVICE_CONTRACTS.md not updated for new Moxfield endpoints (confidence: 88)

services/moxfield.py adds two new API paths — /v2/decks/search and /v2/users/search-sfw — but SERVICE_CONTRACTS.md has no entries for them. The PR Review Checklist in CLAUDE.md explicitly requires SERVICE_CONTRACTS.md updates when new endpoints are added. The existing ## Moxfield section documents only GET /v3/decks/all/{deck_id}.

Fix this →

---

2. Integration conftest missing respx mocks for new Moxfield endpoints (confidence: 82)

tests/integration/conftest.py mocks /v3/decks/.+ but not /v2/decks/search or /v2/users/search-sfw. The respx fixture uses strict mode (default), so any integration test that calls moxfield_search_decks or moxfield_user_decks via mcp_client would fail immediately with an unmatched route error. No tests currently call these tools through mcp_client, so nothing is broken today — but the gap blocks adding integration coverage later.

# tests/integration/conftest.py — add inside the respx.mock block
respx.get(url__regex=re.escape(MOXFIELD_BASE) + r"/v2/decks/search").mock(
    return_value=httpx.Response(
        200, json=_load_json(MOXFIELD_FIXTURES / "search_decks.json")
    )
)
respx.get(url__regex=re.escape(MOXFIELD_BASE) + r"/v2/users/search-sfw").mock(
    return_value=httpx.Response(
        200, json=_load_json(MOXFIELD_FIXTURES / "user_search.json")
    )
)

Fix this →

---

3. user_decks silently truncates to first page with no signal (confidence: 80)

providers/moxfield.py:348 calls client.search_decks(query=username, fmt=format) with the default page_size=20. For users with more than 20 decks the results are silently incomplete — the structured output omits total_results from the API response, so callers can't detect truncation. The tool docstring says "List a user's public decks" implying completeness.

Quick fix: expose result.total_results in structured output (note caveat that this counts all decks matching the query, not just this user's) and/or add a page_size parameter to the tool.

Fix this →

---

Completeness

Item	Status
docs/TOOL_DESIGN.md	✅ Updated (metagame + sideboard + Moxfield tools)
docs/ARCHITECTURE.md	✅ Updated (tool counts, structure)
docs/CACHING_DESIGN.md	✅ Updated
docs/SERVICE_CONTRACTS.md	❌ Not updated for 2 new Moxfield endpoints
CLAUDE.md implementation status	✅ v2.3.0 entry added
.claude/skills/smoke-test/SKILL.md	✅ New sections for metagame/sideboard/Moxfield
tests/integration/conftest.py	⚠️ Missing mocks for /v2/decks/search and /v2/users/search-sfw
tests/integration/test_orchestrator_e2e.py	✅ Tool count (69), prompt count (19) updated
tests/test_parameter_descriptions.py	✅ Moxfield provider already in parametrize list
tests/conftest.py	✅ All 3 new Moxfield caches cleared
Unit tests	✅ All new service methods, provider tools, workflow functions, utils covered
Error path tests	✅ .is_error checks present in provider tests

---

What's Good

• Graceful degradation: MTGGoldfish → Spicerack fallback in metagame_snapshot is well-structured; format_entry_guide degrades all the way down to "no metagame data" with format rules still returned
• Fuzzy matching quality: 4-pass strategy in utils/fuzzy.py (exact slug → substring → word overlap → SequenceMatcher ratio) handles common user input variations well
• Defensive Moxfield parsing: every level of _parse_deck, _parse_board, _parse_search_result uses isinstance + .get() — exactly right for an undocumented API
• asyncio.gather(return_exceptions=True) in archetype_comparison for concurrent deck fetches with graceful per-archetype failure
• B904 compliance: all raise ToolError(...) in except blocks use from exc
• Cache key normalization: _moxfield_deck_key correctly normalizes URLs to IDs so URL vs. raw-ID calls share cache entries
• Layer boundary: workflow function modules (metagame.py, sideboard.py) have zero MCP imports

[j4th]

All three findings addressed:

1. SERVICE_CONTRACTS.md — Added full Moxfield section documenting /v2/decks/search and /v2/users/search-sfw endpoints with connection details, parameters, response shapes, service architecture, and feature flag.

2. Integration conftest — Added respx mocks for both new Moxfield endpoints (/v2/decks/search, /v2/users/search-sfw) using existing fixture files.

3. user_decks truncation — Added total_results to structured output. When results are truncated, markdown now shows a note directing to moxfield_search_decks with pagination.