feat(pr-gate): support Docker compose lifecycle for integration-test-dependent repos

[screenleon]

Problem

pr-gate.sh dispatches reviewer agents (Codex) in a sandbox (workspace-write) that cannot access /var/run/docker.sock. For repos whose integration tests require Docker-backed services (Postgres, Redis, etc.), the gate runner cannot execute make test-integration or equivalent commands — tests either skip silently or fail with a socket permission error.

Example failure from gate run:

FAIL  — Docker Compose could not connect to the Docker API at /var/run/docker.sock

The reviewer then cannot produce a valid test-run result, causing a block verdict on every gate run regardless of code quality.

Context

• The main Claude Code session (which calls pr-gate.sh) does have Docker access — it runs as the user who is in the docker group.
• The Codex sandbox launched by pr-gate.sh does not inherit Docker socket access.
• Repos with pre-started Docker services on localhost ports ARE reachable from the Codex sandbox via TCP (e.g. 127.0.0.1:5433). The socket restriction is only for starting new containers.

Proposed Solution

Add an optional --compose-file <path> (and optionally --compose-project <name>) flag to pr-gate.sh that:

1. Before dispatching Codex reviewers: starts the specified compose stack from the main-thread process (which has Docker access), waits for declared services to be ready.
2. Passes COMPOSE_ALREADY_STARTED=true (or equivalent) so the reviewer brief knows services are live on localhost.
3. After all reviewer sessions complete: tears down the compose stack (only if pr-gate.sh started it — idempotent if services were already running).

This keeps Docker lifecycle management on the main thread where permissions exist, while Codex reviewers see pre-started services via localhost and can run real integration tests.

Alternatives Considered

• Project-level wrapper script (scripts/qa-gate.sh in JapanJob): bypasses the tool boundary, creates an informal fork of gate logic outside pm-dispatch. Rejected because it obscures the root cause and diverges from the intended tool contract.
• Manual pre-start by developer: viable short-term workaround, but not automated or reliable.
• Changing Codex sandbox mode: risky and likely overridden by Codex CLI sandbox policy.

Acceptance Criteria

• bash scripts/pr-gate.sh --compose-file infrastructure/docker-compose.test.yml --compose-project japanjob_test starts services, runs gate, and stops services automatically.
• If services are already running on the target ports, the flag is a no-op for startup (does not restart or stop existing services after gate).
• Gate result reflects actual integration test outcomes, not socket-permission failures.
• Existing gate runs without --compose-file are unaffected.

Current Workaround

Manually start test services before running /pr-gate, then stop after:

docker compose -f infrastructure/docker-compose.test.yml -p test up -d
# run /pr-gate
docker compose -f infrastructure/docker-compose.test.yml -p test down

[screenleon]

設計評估與方向調整

感謝提出這個問題，Codex sandbox 無法存取 Docker socket 是真實的限制，整合測試無法在 gate 中執行是需要解決的問題。

但評估後，--compose-file flag 的方向有一個架構問題：這會把 Docker 這個基礎設施技術耦合進 pm-dispatch（一個 PM 工具層），而不同 repo 的 compose 設定、啟動順序、健康檢查方式各不相同，未來維護成本會持續累積。

建議方向：gate lifecycle hook

更好的分層是：pm-dispatch 提供 hook 點，repo 實作 內容。與 git hooks 的設計哲學相同。

做法：

• pr-gate.sh 在 dispatch reviewers 前，若 .pm-dispatch/pre-gate.sh 存在則在主線程執行
• pr-gate.sh 在所有 reviewer sessions 完成後，若 .pm-dispatch/post-gate.sh 存在則在主線程執行
• hook 不存在時 gate 行為完全不變

使用端（例如需要 Docker 的 repo）自行實作：

# .pm-dispatch/pre-gate.sh
docker compose -f infrastructure/docker-compose.test.yml -p myproject_test up -d
# 等待服務就緒...

# .pm-dispatch/post-gate.sh
docker compose -f infrastructure/docker-compose.test.yml -p myproject_test down

這樣 pm-dispatch 本身不知道 Docker 的存在，但使用者的問題完全解決。同樣的機制也可以用於其他「主線程有權限但 Codex sandbox 沒有」的場景。

後續

已將此需求記錄進 backlog（CC-206，Priority P2），將以上述 hook 方案實作。

在此之前的 workaround：gate 執行前手動啟動服務，gate 完成後手動停止（如 issue 描述）。