refactor(claude): convert provider-compat from command to project-local skill

Replaces .claude/commands/provider-compat.md with a proper skill under
.claude/skills/provider-compat/. Adds provider_compat.py which infers
claimed scope by parsing Go source + server/server.go route registrations,
scaffolds the compat_test.go header, and lists the provider registry.
The skill delegates large spec payloads to the spec-analyst subagent.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: coreydaley

.claude/commands/provider-compat.md

@@ -2,7 +2,9 @@
   "permissions": {
     "allow": [
       "Bash(rm -f /Users/corey/Code/github.com/coreydaley/messagepit/main/.git/index.lock)",
-      "Bash(git stash *)"
+      "Bash(git stash *)",
+      "Bash(rm /Users/corey/Code/github.com/coreydaley/messagepit/main/.claude/commands/provider-compat.md)",
+      "Bash(mkdir -p /Users/corey/Code/github.com/coreydaley/messagepit/main/.claude/skills/provider-compat/scripts)"
     ]
   }
 }

.claude/settings.local.json

@@ -0,0 +1,154 @@
+---
+name: provider-compat
+description: Audit MessagePit provider stub fidelity against the real provider API spec. Infers claimed scope from Go source, fetches the real spec, generates compat_test.go, runs tests, and reports a fidelity score.
+triggers:
+  - /provider-compat
+allowed-tools: Bash, Read, Write, Edit, Agent, WebFetch, WebSearch
+---
+
+# /provider-compat
+
+Audit how closely the MessagePit stub for `$ARGUMENTS` matches the real provider API.
+
+## Script
+
+```bash
+SKILL_DIR=$(find . -path "*/.claude/skills/provider-compat/scripts/provider_compat.py" | head -1)
+```
+
+All heavy lifting goes through the script. Run from the project root.
+
+## Workflow
+
+### 1. Resolve Provider
+
+```bash
+python3 "$SKILL_DIR" --providers
+```
+
+Match `$ARGUMENTS` (lowercase, trimmed) against the registry. If not found, print the registry and exit.
+
+### 2. Infer Claimed Scope
+
+```bash
+python3 "$SKILL_DIR" --scope <name>
+```
+
+This reads all non-test `.go` files in the provider package and returns JSON:
+
+```json
+{
+  "provider": "sendgrid",
+  "package": "internal/sendgrid",
+  "port": 8101,
+  "spec_url": "https://...",
+  "scope": {
+    "routes": [{"path": "/v3/mail/send", "methods": ["POST"]}],
+    "auth": "Bearer token",
+    "request_fields": ["content", "from", "personalizations", "subject", ...],
+    "status_codes": [202, 400, 401, 413, 500]
+  }
+}
+```
+
+Read this output — it is the **Claimed Scope** for the rest of the workflow.
+
+### 3. Fetch the Real Spec
+
+Delegate to the `spec-analyst` subagent (`.claude/agents/spec-analyst.md`), passing:
+- The `spec_url` from step 2
+- The full claimed scope JSON
+
+The subagent returns a **Spec Snapshot** — the real API's contract for the claimed endpoints, distilled to the fields and status codes that matter.
+
+If the `spec-analyst` agent is unavailable, use `WebFetch` inline and extract the relevant paths yourself.
+
+### 4. Generate `compat_test.go`
+
+Get the file header:
+
+```bash
+python3 "$SKILL_DIR" --write-header <name>
+```
+
+Write `internal/<name>/compat_test.go` — **fully regenerated on every run**.
+
+Structure:
+
+```go
+// Code generated by /provider-compat. DO NOT EDIT.
+// Re-run: /provider-compat <name>
+
+package <name>_test
+
+import (
+    "net/http"
+    "net/http/httptest"
+    "strings"
+    "testing"
+
+    "github.com/coreydaley/messagepit/internal/<name>"
+    "github.com/coreydaley/messagepit/internal/storage"
+    "github.com/coreydaley/messagepit/logger"
+)
+
+func init() {
+    logger.NoLogging = true
+}
+
+func setupCompat(t *testing.T) {
+    t.Helper()
+    storage.InitDB()
+    t.Cleanup(storage.Close)
+}
+```
+
+Then one `TestCompat_*` function per claimed endpoint. Each test:
+
+1. Calls `setupCompat(t)`
+2. Builds the exact request the real spec requires (correct method, path, auth header, content-type, body with required fields)
+3. Posts it to `httptest.NewRecorder()` + the handler directly
+4. Asserts the success status code matches the spec
+5. Has a sub-test (`t.Run`) for each expected error case (missing auth → 401, malformed body → 400, etc.)
+
+Name tests `TestCompat_<METHOD>_<PathSuffix>` (e.g., `TestCompat_POST_MailSend`).
+
+Do **not** duplicate assertions already in `<name>_test.go`. Compat tests cover spec conformance; behavioral edge cases stay human-owned.
+
+### 5. Run the Tests
+
+```bash
+go test ./internal/<name>/... -run TestCompat_ -v 2>&1
+```
+
+Capture output. Parse pass/fail per test.
+
+### 6. Report
+
+Print a fidelity report:
+
+```
+=== Provider Compat Report: <name> ===
+
+Claimed scope
+  Endpoints : GET /path, POST /path ...
+  Auth      : Bearer token
+  Fields    : N request fields
+  Statuses  : 200, 400, 401 ...
+
+Spec coverage
+  Matched   : N/M claimed endpoints found in spec
+  Gaps      : <claimed items not in spec — possible drift or extension>
+
+Test results
+  Passed    : N
+  Failed    : N
+  <for each failure: test name, assertion that failed, spec citation>
+
+Not yet claimed (in spec, not in twin)
+  <paths in scope domain not yet implemented>
+
+Fidelity score: <passed>/<total> (<percent>%)
+```
+
+End with `Twin is in sync.` if all pass, or `Action required: see failures above.` if any fail.