⚠️ 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 — applied
uniformly across all five routes below.
Context
src/api/routes.ts groups five idea/task-graph POST routes under /v1/loop/*, each backed by an
MCP tool with its own Zod output shape already defined in src/mcp/server.ts:
| Route |
MCP tool |
Output shape |
POST /v1/loop/evaluate-escalation |
loopover_evaluate_escalation |
evaluateEscalationOutputSchema |
POST /v1/loop/results-payload |
loopover_build_results_payload |
buildResultsPayloadOutputSchema |
POST /v1/loop/progress-snapshot |
loopover_build_progress_snapshot |
buildProgressSnapshotOutputSchema |
POST /v1/loop/intake-idea |
loopover_intake_idea |
intakeIdeaOutputSchema |
POST /v1/loop/plan-idea-claims |
loopover_plan_idea_claims |
planIdeaClaimsOutputSchema |
None of the five appears in src/openapi/spec.ts — grep for /v1/loop/ in that file returns
nothing. Each route's own code comment in src/api/routes.ts explicitly documents it as "the REST
mirror of the loopover_* MCP tool," confirming these are meant to be a fully parallel surface, not
an internal-only shortcut.
Note: POST /v1/loop/request-apr-transfer (in the same file, same /v1/loop/* prefix) is
intentionally excluded from this issue — it's a customer-facing funds/transfer-initiation route
with its own dedicated anti-abuse hardening (see the #7742/#8000 comments above that route in
src/api/routes.ts) and should not be bundled with this batch of pure, source-free composer routes.
Requirements
- In
src/openapi/schemas.ts, define one z.object({...}) response schema per route (5 total,
e.g. EvaluateEscalationResponseSchema, BuildResultsPayloadResponseSchema,
BuildProgressSnapshotResponseSchema, IntakeIdeaResponseSchema, PlanIdeaClaimsResponseSchema),
using each route's existing MCP outputSchema constant (table above) as the field-level source of
truth. Also add request-body schemas mirroring each tool's corresponding inputSchema/shape
constant in src/mcp/server.ts.
- In
src/openapi/spec.ts, registry.register all five response schemas as components, then add a
registerPath entry for each of the five routes.
- Schema is the contract — regenerate and commit. Run
npm run ui:openapi after the 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 five routes are required in this one PR — there is no follow-up issue. request-apr-transfer is
explicitly out of scope for this issue (see Context) — do not add it.
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 response schemas whose keys match each route's MCP tool output shape from the table above.
Expected Outcome
The /v1/loop/* idea/task-graph route family (excluding request-apr-transfer) is documented in
GET /openapi.json / apps/loopover-ui/public/openapi.json, matching what each route's MCP tool
already validates.
Links & Resources
Context
src/api/routes.tsgroups five idea/task-graph POST routes under/v1/loop/*, each backed by anMCP tool with its own Zod output shape already defined in
src/mcp/server.ts:POST /v1/loop/evaluate-escalationloopover_evaluate_escalationevaluateEscalationOutputSchemaPOST /v1/loop/results-payloadloopover_build_results_payloadbuildResultsPayloadOutputSchemaPOST /v1/loop/progress-snapshotloopover_build_progress_snapshotbuildProgressSnapshotOutputSchemaPOST /v1/loop/intake-idealoopover_intake_ideaintakeIdeaOutputSchemaPOST /v1/loop/plan-idea-claimsloopover_plan_idea_claimsplanIdeaClaimsOutputSchemaNone of the five appears in
src/openapi/spec.ts— grep for/v1/loop/in that file returnsnothing. Each route's own code comment in
src/api/routes.tsexplicitly documents it as "the RESTmirror of the
loopover_*MCP tool," confirming these are meant to be a fully parallel surface, notan internal-only shortcut.
Note:
POST /v1/loop/request-apr-transfer(in the same file, same/v1/loop/*prefix) isintentionally excluded from this issue — it's a customer-facing funds/transfer-initiation route
with its own dedicated anti-abuse hardening (see the
#7742/#8000comments above that route insrc/api/routes.ts) and should not be bundled with this batch of pure, source-free composer routes.Requirements
src/openapi/schemas.ts, define onez.object({...})response schema per route (5 total,e.g.
EvaluateEscalationResponseSchema,BuildResultsPayloadResponseSchema,BuildProgressSnapshotResponseSchema,IntakeIdeaResponseSchema,PlanIdeaClaimsResponseSchema),using each route's existing MCP
outputSchemaconstant (table above) as the field-level source oftruth. Also add request-body schemas mirroring each tool's corresponding
inputSchema/shapeconstant in
src/mcp/server.ts.src/openapi/spec.ts,registry.registerall five response schemas as components, then add aregisterPathentry for each of the five routes.npm run ui:openapiafter the edits andcommit the regenerated
apps/loopover-ui/public/openapi.jsonin this same PR. CI enforces this vianpm run ui:openapi:check(part ofnpm run test:ci).Deliverables
src/openapi/schemas.ts, one per route in the table above.src/openapi/spec.ts.apps/loopover-ui/public/openapi.jsonregenerated vianpm run ui:openapiand committed.npm run ui:openapi:checkpasses in CI.All five routes are required in this one PR — there is no follow-up issue.
request-apr-transferisexplicitly out of scope for this issue (see Context) — do not add it.
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 response schemas whose keys match each route's MCP tool output shape from the table above.
Expected Outcome
The
/v1/loop/*idea/task-graph route family (excludingrequest-apr-transfer) is documented inGET /openapi.json/apps/loopover-ui/public/openapi.json, matching what each route's MCP toolalready validates.
Links & Resources
src/api/routes.ts: the five routes in the table above (contiguous block starting atapp.post("/v1/loop/evaluate-escalation", ...))src/mcp/server.ts: the five output-shape constants in the table abovesrc/openapi/spec.ts:/v1/repos/{owner}/{repo}/gate-config/effectiveregistration (pattern tomirror)