contract: api-schemas.ts is half-generated — regenerating it deletes live discovery-route schemas, and the check is not wired into CI

[JSONbored]

Problem

npm run contract:api-schemas:check fails on current main, and running the generator to fix it destroys working code.

packages/loopover-contract/src/api-schemas.ts opens with:

// GENERATED by scripts/gen-contract-api-schemas.ts -- do not edit.

but it currently contains hand-maintained content the generator does not produce. Regenerating removes it:

-import { FindOpportunitiesInput, RetrieveIssueContextInput } from "./tools/local-branch.js";
-export const FindOpportunitiesRequestSchema = z.object(FindOpportunitiesInput.shape);
-export const IssueRagRetrieveRequestSchema = z.object(RetrieveIssueContextInput.shape);
+// #9310 — request/response schemas for the two discovery routes below, mirroring the MCP tools'
+// own Zod shapes verbatim ...

FindOpportunitiesRequestSchema is live — api-schemas.ts:2322 maps it to POST /v1/opportunities/find. Regenerating deletes both the symbol and its import while leaving the reference, so the file stops compiling.

Why this is the dangerous shape

test/unit/contract-limits-pinned.test.ts:18 already records this exact failure once before: "left main failing contract:api-schemas:check for every PR: regenerating produced an uncompilable file." It has recurred.

The generator is behind the #10040/#10225 discovery-route work — those schemas were added to the generated file without the generator learning to emit them, so the artifact and its generator now disagree permanently. The check correctly reports drift; the documented remedy ("run npm run contract:api-schemas and commit the result") is actively harmful here.

Two contributing factors, both worth naming

1. contract:api-schemas:check is in the local test:ci aggregate but NOT in ci.yml. Nothing in CI runs it, which is why this drifts silently and is only discovered by whoever next runs the full local gate. Every other generated-artifact drift check (db:migrations:check, cf-typegen:check, selfhost:env-reference:check, command-reference:check) IS wired into ci.yml.
2. A separate, older drift also exists in this file: feat(gate): let maintainers be exempt from the missing-linked-issue penalty #10160 added linkedIssueMaintainerExempt to the repository-settings surface without regenerating. A fix for that was carried in feat(observability): capture every miner AI generation, and stop fabricating zero token counts #10233 and did not survive the merge — the PR listed 16 files, the merge commit ba35c8bab has 15, and api-schemas.ts is the missing one. Worth understanding on its own, since a silently-dropped file in a gate merge is a bigger problem than this file.

Deliverables

• Decide the source of truth: either teach scripts/gen-contract-api-schemas.ts to emit the discovery-route schemas, or stop generating this file and drop the "do not edit" header. It cannot stay half-generated.
• npm run contract:api-schemas produces a file that compiles — regression-guarded, since this is the second occurrence.
• Fold in the linkedIssueMaintainerExempt regeneration from feat(gate): let maintainers be exempt from the missing-linked-issue penalty #10160.
• Wire contract:api-schemas:check into ci.yml alongside the other generated-artifact drift checks, so this cannot drift unobserved a third time.

[linear-code]

JSO-7142