Service Agent Task Packs

Canonical service packs in this directory are handoff packs for one service owner agent. Orchestrator, alias, cutover, deprecated, and feature packs coordinate service owners and are not independent service-agent rows unless the agent matrix explicitly promotes them. The packs are intentionally scoped so parallel agents can audit, investigate, code, test, and fix without editing the same files.

Coverage gate:

sh scripts/test/service-task-pack-coverage.sh

Runtime/deploy/docs checkpoint for an integrated service-agent wave:

make test-agent-dispatch
make test-frontend-boundary
make test-compose-migrations
make test-service-readiness
make test-runtime-foundation
pnpm docs:build
git diff --check

make test-compose-migrations renders deploy/docker-compose.yml and checks that every active service in scripts/dev/services.sh has a Compose runtime entry with the correct service Dockerfile, SERVICE_NAME, HTTP_ADDR, and service-owned migration/DSN wiring when that service owns SQL migrations.

Every service pack must include owner scope, legacy evidence paths, writable files, orchestrator-owned shared files, acceptance criteria, verification commands, and an explicit pointer to the shared agent workflow below. The gate also checks canonical alias mappings so agents do not create duplicate implementation directories such as services/question-service or services/organization-service. It also treats scripts/dev/services.sh as the active runtime manifest: every listed service must appear as an implementation owner in the responsibility matrix, workflow matrix, wave board, dispatch roster, API docs, and VitePress navigation.

Shared agent workflow:

1. Audit the assigned service against its task pack and the responsibility matrix before writing code.
2. Investigate the cited legacy source and current Go implementation for the exact workflow being changed.
3. Code one small vertical workflow inside the task pack's writable scope.
4. Test the focused workflow and then run the service verification command.
5. Fix defects found by tests, route rehearsals, docs build, or diff hygiene checks before handing off.

Global rules:

• Work only under go-platform/ unless a task explicitly says otherwise.
• Legacy code under /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api is evidence, not an edit target.
• Frontend apps call only api-gateway or an approved BFF; frontend paths in task packs are read-only evidence unless explicitly delegated. Keep make test-frontend-boundary green when frontend code is touched.
• Do not revert unrelated worktree changes.
• Keep one owner per file. Shared files such as root Makefile, Compose, Helm, gateway route examples, and docs indexes are orchestrator-owned unless a task assigns them.
• Active service directories must keep a service-local Makefile that includes scripts/dev/service.mk for run, test, lint, docker-build, and schema workflow commands. The deprecated user-service scaffold is retirement-only and is not an active service workflow target.
• iam-service is the canonical service name for auth/login/session/access work. /api/auth and /v1/auth are compatibility route namespaces only; do not create an auth-service task pack, OpenAPI contract, deployment, or runtime directory.
• If a service pack asks the service agent to add route, live, or browser proof while route files are orchestrator-owned, it must include a Delegated gateway verification scope section naming the exact route examples, test scripts, docs/QA files, and Make targets that may be edited only for that delegated subtask.
• Every code task needs focused tests plus the service verification command.
• The manifest firstVerification is the mandatory first command in each service pack's Verification: section and in its matching SVC-* workflow matrix row. The service-task-pack guard rejects missing or stale commands.
• DB-backed runtime services and schema migration jobs must use their service-owned Postgres role and database. Do not add deploy/runtime DATABASE_URL values that use the shared bootstrap hoctapaz role.
• Route cutover tasks must include rollback evidence and default-route safety.
• IAM/Profile default route promotion uses docs/agents/service-tasks/iam-profile-default-cutover-proof.md; fixture or non-default rehearsal evidence alone is not enough to promote /api/auth* or profile compatibility routes.

Core docs to read first:

• docs/architecture/service-responsibility-matrix.md
• docs/agents/service-agent-wave-board.md
• docs/agents/service-workflow-test-matrix.md
• docs/architecture/service-boundaries.md
• docs/architecture/target-go-microservices.md
• docs/agents/agent-handoff-format.md

Suggested handoff closeout:

1. List task ID and docs read.
2. List legacy files read.
3. List files changed.
4. List tests run.
5. List open risks, rollback notes, and the next recommended task.