Handoff: RET-USER-retirement-readiness-proof user-service retirement readiness proof

Scope

• Service/area: deprecated user-service compatibility scaffold
• Task ID: RET-USER-retirement-readiness-proof
• Goal: audit whether user-service can be removed or narrowed after IAM/Profile parity, default-route proof, rollback proof, and retirement criteria are attached.
• Non-goals: deleting services/user-service, removing runtime manifests, promoting default auth/profile routes, adding product work to user-service, or changing legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• docs/agents/service-tasks/user-service-retirement.md
• docs/agents/handoffs/RET-USER-user-service-quarantine.md
• docs/agents/service-agent-next-slice-queue.json
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/agent-handoff-format.md
• docs/api/user-service.md
• docs/api/iam-service.md
• docs/api/profile-service.md
• docs/qa/iam-profile-default-cutover-proof.md
• docs/qa/user-service-retirement-readiness.md
• docs/qa/service-agent-goal-completion-audit.md
• docs/qa/service-agent-readiness-smoke.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/auth/auth.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/auth/auth.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma
• Legacy auth/profile source was read-only evidence; no legacy file, route, or table was changed.

Files Changed

• docs/qa/user-service-retirement-readiness.md
• docs/api/user-service.md
• docs/index.md
• docs/.vitepress/config.ts
• docs/agents/handoffs/RET-USER-retirement-readiness-proof.md
• docs/agents/service-agent-next-slice-closeout-ledger.json
• docs/agents/service-agent-next-slice-closeout-ledger.md
• docs/agents/service-agent-accepted-handoffs.md
• docs/qa/service-agent-goal-completion-audit.md
• docs/qa/service-agent-readiness-smoke.md
• No services/user-service product code or runtime manifest was changed.

Behavior Implemented

• None in the deprecated service. This is an orchestrator-owned retirement readiness audit.
• Recorded a route inventory for all six user-service profile compatibility routes and mapped them to profile-service compatibility/native ownership; IAM owns auth/session/credential routes.
• Recorded that user-service is absent from default gateway routes, Compose/K8s/Helm runtime lists, BFF upstream targets, and migration jobs.
• Kept the existing quarantine behavior: deprecated response headers identify iam-service and profile-service as canonical owners.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/user-service/...
• Result: passed with -count=1.
• Evidence: compatibility marker and deprecated headers remained covered.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/profile-service/... ./services/iam-service/...
• Result: passed with -count=1.
• Evidence: replacement IAM/Profile packages passed in the same verification run.
• Command: make test-profile-routes test-auth-routes
• Result: passed.
• Evidence: default auth/profile families remained legacy; native examples and self-test live/browser/rollback hooks passed.
• Command: make test-iam-profile-default-cutover-review-artifact
• Result: requires IAM_PROFILE_DEFAULT_CUTOVER_PROOF_BUNDLE_ARTIFACT_DIR; the actual latest-artifact invocation was run and rejected the fixture/self-test bundle as expected.
• Actual command: IAM_PROFILE_DEFAULT_CUTOVER_PROOF_BUNDLE_ARTIFACT_DIR=output/qa/iam-profile-default-cutover-proof-bundle-20260709-121632 make test-iam-profile-default-cutover-review-artifact.
• Evidence: review rejected mode=self-test, selfTestOnly=true, targetProvenance=fixture_only, missing live minimums, missing route hashes, and missing production-like per-step summaries.
• Command: make test-service-agent-goal-completion-audit
• Result: passed while keeping retirement and the broad goal not-complete.
• Command: pnpm docs:build
• Result: passed after adding the retirement QA page and VitePress links.
• Command: git diff --check
• Result: passed.

Required Evidence

• IAM/Profile parity evidence: user-service, IAM, and Profile tests pass; native route guards/self-test hooks pass; the required production-like default proof is still missing and the offline review rejects the latest fixture bundle.
• default-route and rollback proof: deploy/gateway/routes.json remains unchanged with auth/profile/admin/fallback on legacy; the QA page records candidate route, runtime manifest, migration, compatibility-header, and rollback plans.
• retirement criteria: the QA page lists the required production-like reconciliation, route/browser/hash, route inventory, runtime removal, migration, and rollback conditions; they are not yet all satisfied.

Route Inventory

• Deprecated compatibility routes: /v1, /v1/users/{userId}/profile-snapshot, /v1/users/{userId}/profile, and the teacher/student/parent profile PATCH routes.
• Replacement owner: profile-service exposes the compatibility profile paths and native profile APIs; IAM owns /v1/auth/*, sessions, credentials, roles, permissions, and membership.
• Current gateway state: no user-service route is present in deploy/gateway/routes.json; auth/profile native examples are non-default only.

Route State

• Legacy route: default auth/profile compatibility remains legacy_proxy; user-service is not promoted as a native owner.
• Native route: replacement work is owned by iam-service and profile-service through non-default rehearsals and candidate artifacts.
• Gateway state: retirement blocked until IAM/Profile default proof and rollback evidence are accepted.
• Delegated gateway scope: none; this is retirement readiness audit only.
• Rollback notes: keep deploy/gateway/routes.json active, preserve the compatibility deployment/image/migrations during the rollback window, disable native callers on regression, and retain deprecation/canonical-owner headers.

Data Notes

• Tables touched: none; no user-service, IAM, Profile, or legacy database was modified.
• Migration run: none.
• Validation report: latest IAM/Profile bundle was read-only fixture/self-test evidence and was rejected by the offline review; no retirement deletion was attempted.

Risks / Blockers

• IAM/Profile production-like populated target validation with required migrator run-report reconciliation is not attached.
• Candidate/gateway route hashes and production-like per-step summaries are missing from the current bundle.
• Default-route rollback-after-candidate proof is not accepted for retirement.
• User-service compatibility tables/migrations must remain available until the parity and rollback gates close.

Next Step

• Capture the production-like IAM/Profile default proof bundle and pass the offline review artifact; then re-run this route inventory and prepare an explicit orchestrator-owned runtime/migration removal change with rollback approval.