Add a compatibility contract, cleanup rules, and an API route snapshot gate

.agents/skills/address-feedback/SKILL.md

@@ -55,7 +55,7 @@ Run what the change touches:
 - `bun typecheck`.
 - Affected package/app test suites (commands in each subdirectory's CLAUDE.md).
 - `bun run build:shared` when `packages/shared` changed, then re-run dependent suites.
-- `bun run wire-contract:check` when shared endpoint types or the SDK surface changed;
+- `bun run wire-contract:check` when shared endpoint types, the SDK surface, or API routes changed;
   if the change is intentional, `bun run wire-contract:update` and commit the snapshot
   diff with an explicit note on backward compatibility.
 

.agents/skills/vortex-cleanup/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: vortex-cleanup
+description: Rules and procedure for over-engineering cleanups in this repository, such as ponytail audits and reviews (/ponytail:ponytail-audit, /ponytail:ponytail-review), dead-code and unused-dependency removal, and simplifying refactors. Use before auditing or applying any cleanup, so the run respects the Compatibility Contract and the scope decisions already made.
+---
+
+# Vortex cleanup rules
+
+Cleanup runs here follow the root `CLAUDE.md` **Compatibility Contract** first. The ponytail
+plugin decides *what* looks over-engineered; this skill decides what may actually change
+and how to prove nothing broke. When the two disagree, the contract wins.
+
+## Scope decisions (do not propose these again without new information)
+
+Excluded from cleanups by Marcel on 2026-10-01:
+
+- Duplicate ABI files (`apps/api/src/contracts`, `apps/frontend/src/contracts`,
+  `packages/shared/src/contracts`) and swaps to viem's `erc20Abi`.
+- Storybook (`apps/frontend/.storybook`, `*.stories.tsx`), and any component a story
+  imports.
+- The retired BRL↔AssetHub flows, the phases only they use, and their substrate branches.
+- Generic `packages/shared` shrinking: endpoint placeholders, twin helpers, dead DTO types.
+- The rebalancer's BlindPay shadow quotes, and gold demo mode.
+- Hand-rolled sleeps and IP-range checks (stdlib/`node:net` swaps).
+
+Kept by the Compatibility Contract: mounted endpoints that nothing in this repo calls
+(`/v1/siwe`, `/v1/storage`, `GET /v1/prices`), because external partners may call them.
+
+Deferred because the swap changes behaviour; each needs an explicit decision and a
+migration plan, not a cleanup commit:
+
+- `body-parser` → `express.json()`: body-parser 2 leaves `req.body` undefined when nothing
+  was parsed.
+- `joi` → zod: the email validation regexes differ.
+- `method-override`: live, it honours `X-HTTP-Method-Override`.
+- `dotenv`: the api also loads `../.env`; Bun only auto-loads from the working directory.
+- ethers/siwe → viem: signed-transaction parsing and the SIWE nonce format.
+- The swc build step: the Render start command depends on it.
+- SDK ESLint → Biome: it enforces `.js` import extensions in the published ESM.
+- node-forge → `node:crypto` for BRLA signing: node:crypto rejects PEM spellings forge
+  accepts, and the production key format is unverified.
+- react-toastify → sonner, removing `input-otp`: UX changes.
+
+## Procedure
+
+1. **Base and isolation.** Work from `origin/staging` in a worktree. Re-check every finding
+   against the latest `staging` before integrating: staging can start using something you
+   deleted as dead.
+2. **Audit.** Partition by workspace. Every delegated agent gets the Compatibility Contract
+   and this skill's scope table in its prompt: built-in Explore/Plan subagents do not load
+   `CLAUDE.md`. Finder-style passes can use the cheap tier (Claude Code: `sonnet`; Codex:
+   GPT-5.6-Luna); agents that edit code use the strong tier (Claude Code: session model;
+   Codex: GPT-5.6-Sol).
+3. **Prove "dead" before deleting.** Zero references across `apps/`, `packages/`,
+   `contracts/`, `scripts/`, CI workflows, and package.json scripts. Include barrels,
+   string-keyed and dynamic use, lazy imports, TanStack file routes, dynamic i18n keys,
+   tsconfig `types`, side-effect imports, and stories. Usage only by tests means the
+   test usage goes too, never that the code is live.
+4. **Dependencies.** Check imports, config files, CLI use in scripts, and peer requirements.
+   The frontend bundles `packages/shared` from source through its browser export, so
+   anything shared imports must stay resolvable from the frontend. The `bun.lock` diff may
+   only remove packages or move hoisting, never shift a consumer's resolved version.
+5. **Refactors.** Characterization tests against the old code come first and stay. Keep
+   message strings, state keys, attempt classes, and log semantics that recovery or
+   operators rely on. If the result isn't smaller, or equivalence is uncertain, skip it
+   and say why. Skipping is fine; a silent behaviour change is not.
+6. **Gates.** Before handing off:
+   - `bun run typecheck`, `bun run verify`, `bun run wire-contract:check`.
+   - The affected test suites. API tests need their own database: create
+     `vortex_test_<name>` on `localhost:54329` and run with `TEST_DB_NAME`. The dashboard
+     uses `bun run test`, since plain `bun test` picks up its Playwright specs.
+   - `bun run build` for every affected app.
+   - Any change to the wire-contract snapshot needs a compatibility note in the PR.
+7. **Commits and PR.** One conventional commit per concern, with tests in the same
+   commit, grouped by workspace. The PR targets `staging` and lists what was kept or
+   skipped and why.
+
+## Running parallel workstreams
+
+- Install with Bun's global cache (`bun install --frozen-lockfile`). Per-worktree caches
+  from `bun bootstrap:worktree` filled the disk when seven agents ran at once.
+- Give each workstream exclusive ownership of the `package.json` files it edits. When
+  integrating by cherry-pick, resolve `bun.lock` conflicts by keeping the integration
+  side and re-running `bun install`.

.claude/skills/vortex-cleanup

@@ -0,0 +1 @@
+../../.agents/skills/vortex-cleanup

CLAUDE.md

@@ -157,6 +157,33 @@ Before finalizing, make a simplification pass. Remove speculative flexibility, d
 state, unnecessary branches, single-use helpers, and indirection that do not protect a
 demonstrated requirement. Keep the regression test that proves the leaner fix is safe.
 
+## Compatibility Contract
+
+Every change, and especially every refactor or cleanup (including ponytail audits), must
+keep existing integrators working. Simplification never justifies breaking them.
+
+- **HTTP API**: every route mounted from `apps/api/src/config/express.ts` keeps its path,
+  method, request validation, status codes, error codes/messages, and response bodies.
+  Never remove a mounted endpoint because nothing in this repo calls it; partners might.
+- **SDK**: the exports of `packages/sdk/src/index.ts`, its emitted types, its runtime
+  behavior, and the HTTP requests it sends stay unchanged. Relaxing a requirement (for
+  example dropping an unused peer dependency) is fine.
+- **`@vortexfi/shared`** is published to npm: never remove or change anything the SDK
+  source or its emitted types reference. Other removed exports need a version bump on the
+  next publish.
+- **Persisted formats** stay readable: ramp state and its metadata, rebalancer state files,
+  browser storage keys, and webhook payloads.
+- **Refactors** need tests that prove equivalence. Where existing tests don't, write
+  characterization tests against the old code first; if equivalence can't be shown, skip
+  the refactor. No exceptions in fund-moving code (`apps/api/src/api/services/phases/`,
+  `apps/rebalancer`).
+- A **cleanup** must remove net code. Moving lines into a new abstraction is not cleanup.
+
+`bun run wire-contract:check` (CI) snapshots the shared endpoint types, the SDK surface,
+and every mounted `METHOD /path`; a snapshot diff is a compatibility review, not a
+formality. Cleanup and ponytail runs also follow
+[`.agents/skills/vortex-cleanup/SKILL.md`](.agents/skills/vortex-cleanup/SKILL.md).
+
 ## Testing
 
 These apply to every agent working in this repo:

MAP.md

@@ -45,6 +45,6 @@ The full placement and lifecycle policy is in [`docs/README.md`](docs/README.md)
 |---|---|
 | `scripts` | Repository coverage and maintenance tooling. |
 | `supabase` | Supabase configuration, migrations, snippets, and email templates. |
-| `.agents/skills` | Purpose-built, repository-specific agent workflows (currently Vortex integration and Sentry guidance). |
+| `.agents/skills` | Purpose-built, repository-specific agent workflows (review, shipping, PR feedback, cleanup rules, Vortex integration, and Sentry guidance). |
 | `.claude` | Shared Claude Code settings and worktree configuration. |
 | `.clinerules` | Pointer from Cline to the canonical `CLAUDE.md` and documentation policy. |

docs/api/README.md

@@ -5,7 +5,7 @@ This directory is the repository source of truth for the partner-facing Vortex A
 ## Structure
 
 - `openapi/vortex.openapi.json` is the OpenAPI reference used for the Apidog endpoint catalog.
-- `wire-contract.snapshot.md` is the generated snapshot of the typed partner-facing surface (shared endpoint types + public SDK API). CI fails when it is stale; regenerate with `bun run wire-contract:update` and review the diff for backward compatibility.
+- `wire-contract.snapshot.md` is the generated snapshot of the partner-facing surface (shared endpoint types, public SDK API, and every mounted `METHOD /path` of the API). CI fails when it is stale; regenerate with `bun run wire-contract:update` and review the diff for backward compatibility.
 - `pages/*.md` contains the pure Markdown guide pages that sit around the endpoint reference.
 - `apidog/page-manifest.json` records the intended page order, source files, current Apidog project ID, and endpoint grouping decisions.
 - `scripts/*.ts` contains the local export, validation, and type-generation helpers for this docs source.