Motir

The story's foundation, in the shape 11.2.2 established for the work-item resource: the schema module and the operation declarations first, proven on ONE endpoint, so the four endpoint cards behind it are adapters rather than designers.

What to build

1. lib/api/v1/workLoop/schema.ts (or wherever 11.7.1 pinned the module) — the zod/v4 response schemas for this story's resources: the dispatch prompt, the integration result, the session close-out result, the expansion/submit job handle, a plan, a plan's status, a plan session with its turns, and an activity entry. Written per ADR Amendment 2's ownership split as totalized by Amendment 5: a v1 response is a schema's output, never a service DTO passed through.
2. lib/api/v1/workLoop/operations.ts — the operation declarations for all ten, registered in lib/api/v1/openapi/registry.ts as a new resource module. tests/api/v1/openapi-operations-coverage.test.ts walks app/api/v1 and fails on any exported method with no declaration, so declarations and routes land together or CI says so.
3. GET /api/v1/work-items/{key}/dispatch-prompt — the proving endpoint. A pure READ: it assembles text and never claims the item or moves its status, so re-fetching an in-progress item's prompt is safe. Adapts dispatchPromptService.getDispatchPrompt through withV1Route({ scope: 'read' }).
   • sessionBranch is a FALLBACK the server may ignore — an item already on a lineage keeps its own. The endpoint passes it through and never redirects an existing chain.
   • The response carries targetRepo, workflowMode, sessionBranch and the optional advisories block (MOTIR-2079), whose union has two shipped severities and must stay OPEN — a consumer meeting an unknown severity ignores it rather than failing.

Why the schemas land ahead of the endpoints

Ten endpoints returning eight resources cannot each shape their own response and stay coherent — that is the exact drift 11.6 exists to prevent, and it would be perverse to introduce it in the story that supplies 11.6's schemas. One module, declared once, consumed by four cards.

Scope BOUNDARY

Ends at the schema module, the operation declarations and ONE endpoint. It does NOT ship the session, expansion, plan-session or activity endpoints (11.7.4 / 11.7.5 / 11.7.6 / 11.7.7) — their declarations may land here, their routes do not. It does NOT change dispatchPromptService or what a prompt CONTAINS. It does NOT touch the MCP tool, which keeps working unchanged. It does NOT add the field projections (11.7.2).

Acceptance criteria

• The schema module declares a response shape for each of this story's resources, in zod/v4, with no service DTO passed through unmapped.
• All ten operations are declared and registered; the operation-coverage test passes with the routes that exist and would fail if a route landed undeclared.
• GET …/dispatch-prompt returns the assembled prompt with targetRepo, workflowMode, sessionBranch and the optional advisories block, gated on read.
• Fetching a prompt does NOT change the item's status, claim it, or alter its session_branch — asserted by reading the row before and after, including for an item already in_progress.
• A sessionBranch argument does not redirect an item that already carries a lineage — asserted directly, because this is the one way the endpoint could corrupt state.
• The advisories union accepts an unknown severity without failing validation, so a future advisory type does not break a shipped client.
• The endpoint's payload matches the MCP tool's for the same item, asserted field by field.
• A token without read is refused 403; a cross-tenant key returns the product's 404.
• No Prisma call, no transaction, no import from lib/mcp/tools/.
• The per-file coverage floor (≥90%) holds on every new file.

Context refs

• 11.7.1 — Q1 (paths), Q2 (the mirrored scope table), Q3 (the job-handle shape the schemas encode).
• 11.2.2 — the schema-module-then-endpoint pattern this copies.
• lib/services/dispatchPromptService.ts — getDispatchPrompt, the sole service call.
• lib/mcp/tools/dispatchPrompt.ts — the semantics to mirror: pure read, sessionBranch as fallback, the advisories block. Read, not imported.
• lib/dto/dispatch.ts — DispatchPromptDto and DispatchWorkflowMode, the shapes mapped FROM.
• lib/api/v1/route.ts · lib/api/v1/errors.ts · lib/api/v1/pagination.ts — the wrapper, envelope and cursor this composes.
• lib/api/v1/openapi/registry.ts + operation.ts — where the module registers.
• lib/api/v1/workItems/operations.ts — the shipped worked example of a resource module.
• Story: 11.7.