⚠️ Definition of Done: this issue must be completed in full, in a single PR. Do not split this
work across multiple PRs, and do not defer any Deliverable below to a follow-up issue. A PR that
satisfies only some of the Deliverables, stubs a required test, or leaves a checkbox
partially-done does NOT resolve this issue and will be closed.
⚠️ Required pattern: mirror how GET /v1/repos/{owner}/{repo}/gate-config/effective is documented
in src/openapi/spec.ts — issue #6611 fixed the exact same class of gap for that route.
Context
Five GET /v1/repos/:owner/:repo/* maintainer-report routes in src/api/routes.ts are all live,
maintainer-authenticated, and each already has an MCP tool with its own Zod output shape in
src/mcp/server.ts — but none of the five appears in src/openapi/spec.ts:
.../maintainer-noise → loopover_get_maintainer_noise. Its response schema,
MaintainerNoiseReportSchema, is even already imported into spec.ts and
registry.register("MaintainerNoiseReport", MaintainerNoiseReportSchema)'d as a component — it is
simply never attached to a registerPath, so it's orphaned in the components section and
unreachable from paths.
.../ams-miner-cohort → loopover_get_ams_miner_cohort. Same situation: AmsMinerCohortComparisonSchema
is registered as a component but never attached to a path.
.../gate-precision → loopover_get_gate_precision (outputSchema: gatePrecisionOutputSchema,
no OpenAPI schema exists yet).
.../outcome-calibration → loopover_get_outcome_calibration (outputSchema: maintainerMeasurementReportOutputSchema, no OpenAPI schema exists yet).
.../activation-preview → loopover_get_activation_preview (outputSchema: activationPreviewOutputSchema, no OpenAPI schema exists yet).
All five share the same owner/repo path params and maintainer-only auth boundary as their
already-documented sibling .../gate-config/effective and .../live-gate-thresholds (#6611 fixed
this same class of gap for .../gate-config/effective).
Requirements
- For
maintainer-noise and ams-miner-cohort: the response schemas already exist
(MaintainerNoiseReportSchema, AmsMinerCohortComparisonSchema, already registry.register'd in
src/openapi/spec.ts) — just add the missing registry.registerPath({...}) entries for
GET /v1/repos/{owner}/{repo}/maintainer-noise and GET /v1/repos/{owner}/{repo}/ams-miner-cohort.
- For
gate-precision, outcome-calibration, and activation-preview: define new
z.object({...}) schemas in src/openapi/schemas.ts (GatePrecisionResponseSchema,
OutcomeCalibrationResponseSchema, ActivationPreviewResponseSchema), using
gatePrecisionOutputSchema, maintainerMeasurementReportOutputSchema, and
activationPreviewOutputSchema (the raw Zod shapes already validated in src/mcp/server.ts) as
the source of truth, registry.register them, then add registerPath entries for their three
routes.
- All five paths take
owner/repo path params and (where applicable) the same optional
windowDays query param their MCP tool siblings accept — mirror the request shape
.../gate-config/effective and .../live-gate-thresholds already use.
- Schema is the contract — regenerate and commit. Run
npm run ui:openapi after the schema/spec
edits and commit the regenerated apps/loopover-ui/public/openapi.json in this same PR. CI
enforces this via npm run ui:openapi:check (part of npm run test:ci).
Deliverables
All deliverables are required in this one PR — there is no follow-up issue.
Test Coverage Requirements
99%+ Codecov patch target (codecov/patch, unsharded via npm run test:coverage) on any new schema
helper code. Add a regression test asserting all five paths appear in buildOpenApiSpec()'s output
with the correct method and a response schema whose keys match each route's MCP tool output shape.
Expected Outcome
All five maintainer-report routes are documented in GET /openapi.json /
apps/loopover-ui/public/openapi.json, matching what their MCP tool counterparts already validate —
closing the drift for the entire "repo maintainer advisory report" route family in one pass.
Links & Resources
Context
Five
GET /v1/repos/:owner/:repo/*maintainer-report routes insrc/api/routes.tsare all live,maintainer-authenticated, and each already has an MCP tool with its own Zod output shape in
src/mcp/server.ts— but none of the five appears insrc/openapi/spec.ts:.../maintainer-noise→loopover_get_maintainer_noise. Its response schema,MaintainerNoiseReportSchema, is even already imported intospec.tsandregistry.register("MaintainerNoiseReport", MaintainerNoiseReportSchema)'d as a component — it issimply never attached to a
registerPath, so it's orphaned in the components section andunreachable from
paths..../ams-miner-cohort→loopover_get_ams_miner_cohort. Same situation:AmsMinerCohortComparisonSchemais registered as a component but never attached to a path.
.../gate-precision→loopover_get_gate_precision(outputSchema: gatePrecisionOutputSchema,no OpenAPI schema exists yet).
.../outcome-calibration→loopover_get_outcome_calibration(outputSchema: maintainerMeasurementReportOutputSchema, no OpenAPI schema exists yet)..../activation-preview→loopover_get_activation_preview(outputSchema: activationPreviewOutputSchema, no OpenAPI schema exists yet).All five share the same
owner/repopath params and maintainer-only auth boundary as theiralready-documented sibling
.../gate-config/effectiveand.../live-gate-thresholds(#6611 fixedthis same class of gap for
.../gate-config/effective).Requirements
maintainer-noiseandams-miner-cohort: the response schemas already exist(
MaintainerNoiseReportSchema,AmsMinerCohortComparisonSchema, alreadyregistry.register'd insrc/openapi/spec.ts) — just add the missingregistry.registerPath({...})entries forGET /v1/repos/{owner}/{repo}/maintainer-noiseandGET /v1/repos/{owner}/{repo}/ams-miner-cohort.gate-precision,outcome-calibration, andactivation-preview: define newz.object({...})schemas insrc/openapi/schemas.ts(GatePrecisionResponseSchema,OutcomeCalibrationResponseSchema,ActivationPreviewResponseSchema), usinggatePrecisionOutputSchema,maintainerMeasurementReportOutputSchema, andactivationPreviewOutputSchema(the raw Zod shapes already validated insrc/mcp/server.ts) asthe source of truth,
registry.registerthem, then addregisterPathentries for their threeroutes.
owner/repopath params and (where applicable) the same optionalwindowDaysquery param their MCP tool siblings accept — mirror the request shape.../gate-config/effectiveand.../live-gate-thresholdsalready use.npm run ui:openapiafter the schema/specedits and commit the regenerated
apps/loopover-ui/public/openapi.jsonin this same PR. CIenforces this via
npm run ui:openapi:check(part ofnpm run test:ci).Deliverables
registerPathentries added for all five routes insrc/openapi/spec.ts.src/openapi/schemas.tsforgate-precision,outcome-calibration, andactivation-preview, matching their MCP tools' output shapesfield-for-field.
apps/loopover-ui/public/openapi.jsonregenerated vianpm run ui:openapiand committed.npm run ui:openapi:checkpasses in CI.All deliverables are required in this one PR — there is no follow-up issue.
Test Coverage Requirements
99%+ Codecov patch target (
codecov/patch, unsharded vianpm run test:coverage) on any new schemahelper code. Add a regression test asserting all five paths appear in
buildOpenApiSpec()'s outputwith the correct method and a response schema whose keys match each route's MCP tool output shape.
Expected Outcome
All five maintainer-report routes are documented in
GET /openapi.json/apps/loopover-ui/public/openapi.json, matching what their MCP tool counterparts already validate —closing the drift for the entire "repo maintainer advisory report" route family in one pass.
Links & Resources
src/api/routes.ts: the fiveGET /v1/repos/:owner/:repo/*routes abovesrc/mcp/server.ts:MaintainerNoiseReportSchema,AmsMinerCohortComparisonSchema,gatePrecisionOutputSchema,maintainerMeasurementReportOutputSchema,activationPreviewOutputSchemasrc/openapi/spec.ts:/v1/repos/{owner}/{repo}/gate-config/effectiveregistration (pattern tomirror); the two already-registered-but-orphaned component schemas noted above