docs: tool↔schema coverage matrix with drift test

[millsmillsymills]

What

Adds a checked-in tool↔schema coverage matrix and a test that asserts it against the live server.

• docs/tool-schema-matrix.md — inventory of all 18 MCP tools across 6 groups, in two parseable tables: annotations (readOnly/destructive/idempotent/openWorld + group + informational Gate) and parameters (name, type, required/optional, default).
• tests/tools/gen_schema_matrix.py — regenerates the doc from the live FastMCP server. The server is the single source of truth.
• tests/unit/test_schema_matrix_drift.py — parses the markdown tables with a parser independent of the generator and asserts the tool set, annotations, and parameters against the live server. Adding, removing, retyping, re-defaulting, or re-annotating a tool without regenerating the doc fails CI.

The Gate column documents the runtime env/argument interlock (e.g. WRITE, WRITE + FIRMWARE_FLASH, TX + i_accept_responsibility); it is informational and not asserted, since it is runtime behavior rather than part of the JSON schema.

Verification

• 3 drift tests pass; mutation-tested a flipped annotation, a changed default, and a dropped tool row — each fails the guard.
• Regeneration is idempotent (no diff on re-run).
• ruff check / ruff format / ty check clean on both new files.
• Full non-integration suite: 237 passed.

🤖 Generated with Claude Code

[millsmillsymills]

Review (caveman review/merge cycle)

Quality is good — parser independence holds (test and generator share only the markdown file, duplicate type/default formatting in separate paths), and the drift guard catches add/remove/retype/re-default/re-annotate mutations.

Merge blocked: the required audit check is red on this branch. It is unrelated to this diff (no dep changes) — pre-existing transitive CVEs on phase1 (cryptography, python-multipart, starlette). Tracked in a separate followup issue; this PR can merge once that clears and it rebases.

Important — fix before merge

• tests/unit/test_schema_matrix_drift.py:159-163 — test_parameters_match iterates only live_parameters keys, and test_tool_set_matches (line 144) parses only the annotations table. If a tool is deleted from code and removed from the annotations table but its rows are left in the Parameters table, nothing fails — stale rows ship. Add a reverse assertion: set(_doc_parameters(markdown)) <= set(live_parameters) (or ==). This is the one hole in the "any drift fails CI" claim.

Optional hardening

• gen_schema_matrix.py:74 / test_schema_matrix_drift.py:113 — next(tag for tag in sorted(tags) if tag != "flipper") raises bare StopIteration for a tool with no group tag. Prefer next(..., None) + explicit raise ValueError(f"{tool.name} has no group tag").
• test_tool_set_matches — add assert live_annotations, "live server exposed no tools" so an empty-server wiring regression reads as such instead of ordinary drift.

Non-issues verified: duplicated _type_str/_default_cell is intentional for parser independence (do not consolidate); GATE being hand-maintained is documented as informational (accepted).