chore(spec): add upstream spec drift auditor + inline-example validator

[dougborg]

Problem

docs/frontapp-openapi.yaml is a vendored, sanitized copy of Front's upstream spec, refreshed via scripts/vendor_spec.py. There is currently no way to diff our local spec against upstream (e.g., to see whether Front shipped a new endpoint, changed a response shape, or deprecated a route) without manually fetching upstream and eyeballing it.

Sibling repo katana solved this in PR #420 + #421 with a pair of focused scripts.

Solution

Adapt katana's pattern to frontapp:

1. scripts/audit_spec_drift.py — diffs docs/frontapp-openapi.yaml against the upstream Front spec, reports missing/invented endpoints, changed response schemas, deprecated routes. Exits non-zero on drift.
2. scripts/validate_spec_examples.py — walks every examples: block in the spec and validates each against its referenced JSON schema using Draft202012Validator. Catches handwritten examples that have drifted from their schemas.
3. Optional weekly CI workflow (statuspro feat(client,mcp): contact_lists vertical — manage contact list memberships #47–48 pattern): .github/workflows/upstream-spec-drift.yml runs the auditor on a cron and opens a PR with the upstream diff for human review. Never auto-merges.

Keep docs/frontapp-openapi.yaml as the sanitized vendored copy; add docs/upstream/frontapp-openapi.upstream.yaml (gitignored snapshot or committed for diffability — TBD during implementation) as the unsanitized comparison point.

Files to add

• scripts/audit_spec_drift.py (new)
• scripts/validate_spec_examples.py (new)
• .github/workflows/upstream-spec-drift.yml (new, optional but recommended)
• pyproject.toml — add poe spec-audit task

Acceptance criteria

• uv run poe spec-audit exits 0 on a freshly vendored spec
• Manually mutating an endpoint locally causes the audit to flag it clearly
• validate_spec_examples.py catches a deliberately broken example
• CI workflow opens a PR (not commit) when upstream drifts
• No false positives from the sanitization layer in vendor_spec.py (sanitized diffs are expected and should be filtered)

Reference

• Audit tooling + spec alignment with live Katana API katana-openapi-client#420, #421 — audit_spec_drift, validate_spec_examples, validate_response_examples
• feat(spec): OpenAPI spec sync script + upstream snapshot statuspro-openapi-client#47, feat(client,mcp): contact_groups vertical — manage contact group memberships #48 — weekly sync workflow pattern