chore(ai-gateway): formalize llm gateway migration

[richardsolomou]

Problem

Why: Gateway callers need one clear default while the Go gateway catches up with the remaining first-party contracts. Without a migration policy and current parity record, new Python gateway work can widen the gap and make the eventual move harder.

Changes

• Put the Python LLM gateway under an unofficial code freeze, with documented exceptions for callers blocked by a verified parity gap.
• Add a capability and use-case guide for deciding when a caller should migrate.
• Add separate mandatory skills for auditing parity, finding migration candidates, and migrating a selected caller.
• Link verified migration PRs covering shared clients, staged rollout, sandbox wiring, and attribution continuity.

How did you test this code?

• pnpm dlx oxfmt@0.57.0 --check AGENTS.md services/llm-gateway/PARITY.md .agents/skills/auditing-llm-gateway-parity/SKILL.md .agents/skills/finding-llm-gateway-migration-candidates/SKILL.md .agents/skills/migrating-llm-gateway-callers/SKILL.md .agents/skills/migrating-llm-gateway-callers/references/migration-examples.md
• pnpm dlx markdownlint-cli2@0.18.1 --config .config/.markdownlint-cli2.jsonc AGENTS.md services/llm-gateway/PARITY.md .agents/skills/auditing-llm-gateway-parity/SKILL.md .agents/skills/finding-llm-gateway-migration-candidates/SKILL.md .agents/skills/migrating-llm-gateway-callers/SKILL.md .agents/skills/migrating-llm-gateway-callers/references/migration-examples.md
• git diff --check

👉 Stay up-to-date with PostHog coding conventions for a smoother review.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

This PR adds the migration policy and parity guide used by coding agents. No product documentation update is required.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Codex audited the Python and Go gateways, representative callers, shared clients, deployment wiring, and merged migration PRs. The three workflows remain separate: refresh the parity record, discover and rank candidates, then migrate a selected caller. Candidate discovery verifies the production process, API shape, model, attribution, and billing route before recommending work.

---

Created with PostHog Code

[trunk-io]

Merging to master in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[github-actions]

Hey @richardsolomou! 👋

It looks like your git author email on this PR isn't your @posthog.com address (richard@solomou.dev). Since you're on the PostHog team, it's worth pointing your local git author email at your @posthog.com address. Why it matters:

• Consistent work identity in git history — internal tooling that attributes commits to team members keys off your @posthog.com address.
• Keeps team contributions easy to tell apart from external community ones when scanning history.

You can fix it for this repo with:

git config user.email "you@posthog.com"

Or set it globally with git config --global user.email "you@posthog.com". No need to redo this PR — just a nudge for next time. 🙂

[benjackwhite]

hell yeah - no idea if this will work but this is the kind of idea i was hoping for

[pr-assigner-resolver-posthog]

👀 Auto-assigned reviewers

These soft owners were skipped because they only have minor changes here. Nothing blocks merge, so self-assign if you'd like a look:

• @PostHog/team-devex (owners.yaml)

Soft owners come from each directory's owners.yaml and each product's product.yaml (resolved nearest-file-wins). The locator after each owner is the file that decided it. Generated files and lockfiles are ignored when deciding ownership.

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
services/llm-gateway/PARITY.md:82
**Fallback policy breaks staged rollout**

When an agent migrates a supported caller through a shared Go-capable builder, this checklist restricts the Python fallback to parity blockers even though the builders retain it for staged rollout. Following this instruction removes the rollback path and leaves callers unable to run when the Go gateway configuration is unset or only partially deployed.

```suggestion
5. Keep the Python fallback only for staged rollout or a named blocker. Record the rollout plan or blocker in the PR.
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "chore(ai-gateway): refresh migration gui..." | Re-trigger Greptile}