Learning Public Gateway Cutover Task

Agent workflow: follow README.md for Audit -> Investigate -> Code -> Test -> Fix; keep this pack's writable scope and verification commands authoritative.

Dispatch type: orchestrator

Owner: api-gateway plus service-specific owners.

Goal:

Promote question/course/exam/attempt public workflows only after owner service APIs and browser-visible parity are proven.

Legacy source evidence:

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/questions/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/courses/**
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exams/**
• frontend learning flows under /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web.

Writable files:

• services/api-gateway/**
• question route fixtures: deploy/gateway/routes.questions-read-native-example.json, deploy/gateway/routes.questions-read-native-localhost-example.json, deploy/gateway/routes.questions-read-shadow-example.json, deploy/gateway/routes.questions-read-shadow-localhost-example.json, deploy/gateway/routes.question-types-native-example.json, deploy/gateway/routes.question-types-native-localhost-example.json, deploy/gateway/routes.question-types-shadow-example.json, deploy/gateway/routes.question-types-shadow-localhost-example.json, deploy/gateway/routes.question-classification-apply-native-example.json, and deploy/gateway/routes.question-classification-apply-native-localhost-example.json.
• course route fixtures: deploy/gateway/routes.student-courses-read-native-example.json, deploy/gateway/routes.student-courses-read-native-localhost-example.json, deploy/gateway/routes.student-course-progress-native-example.json, and deploy/gateway/routes.student-course-progress-native-localhost-example.json.
• exam/attempt route fixtures: deploy/gateway/routes.exam-authoring-native-example.json, deploy/gateway/routes.exam-authoring-native-localhost-example.json, deploy/gateway/routes.attempt-native-example.json, and deploy/gateway/routes.attempt-native-localhost-example.json.
• route coverage and smoke scripts for the exact learning route groups: scripts/test/question-read-route-table-coverage.sh, scripts/test/question-types-route-coverage.sh, scripts/test/question-classification-apply-route-coverage.sh, scripts/test/student-course-route-coverage.sh, scripts/test/student-course-progress-route-coverage.sh, scripts/test/student-course-browser-smoke.sh, scripts/test/student-course-browser-smoke.mjs, scripts/test/exam-authoring-route-coverage.sh, scripts/test/attempt-route-coverage.sh, scripts/test/attempt-live-smoke.sh, scripts/test/attempt-browser-smoke.sh, and scripts/test/attempt-browser-smoke.mjs.
• learning QA docs under docs/qa/ only for the named question, course, exam, and attempt route rehearsals.
• root Makefile only for the named question, course, exam, and attempt route proof targets listed below.
• docs/agents/service-tasks/learning-public-gateway-cutover.md

Delegated gateway verification scope:

• Route examples: only the question, course, exam-authoring, and attempt route fixture files listed in this pack.
• Test scripts: only the question, student-course, exam-authoring, and attempt route/smoke scripts listed in this pack.
• QA docs: only the named learning route rehearsal docs under docs/qa/.
• Make targets: test-question-read-routes, test-question-types-routes, test-question-classification-apply-routes, test-question-write-routes, test-question-write-live, test-question-write-browser, test-attempt-routes, test-attempt-live, test-attempt-browser, test-student-course-routes, test-student-course-progress-routes, test-student-course-browser, and test-exam-authoring-routes.

Orchestrator-owned files:

• Default gateway route table, frontend/browser smoke artifacts, shared deployment manifests, and final public route promotion notes.

Tasks:

• Add non-default route adapters for one workflow at a time.
• Add route-table static coverage for exact method/path capture.
• Add live gateway smoke with real auth/org headers.
• Add browser smoke for the real frontend route when the route is user-facing.
• Keep default route table legacy until rollback rehearsal and parity evidence exist.

Acceptance:

• Static route coverage is not enough for public cutover.
• Attempt start requires exam runtime/access hydration.
• Course purchase/paid access waits for billing/wallet/usage/payment services.
• Question write cutover waits for docs/qa/question-write-route-rehearsals.md live/browser save/reload parity and rollback proof.

Verification:

• GOTOOLCHAIN=go1.25.11 go test ./services/api-gateway/internal/gateway
• make test-question-read-routes test-attempt-routes test-student-course-routes test-student-course-progress-routes
• make test-question-write-routes
• QUESTION_WRITE_SELF_TEST=1 make test-question-write-live
• QUESTION_WRITE_BROWSER_SELF_TEST=1 make test-question-write-browser
• Workflow-specific live/browser smoke before default route promotion.