From 9b2b3921c815040cda4786bfddab13e73dcba4fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EB=A8=B8=EB=8B=88=ED=8E=98=EB=8B=88?=
 <moneypenny@meonipeniui-Macmini.local>
Date: Fri, 20 Mar 2026 22:21:22 +0900
Subject: [PATCH] docs: apply review feedback to Phase 5 deploy spec

---
 ...3-20-galaxis-agent-phase5-deploy-design.md | 28 +++++++++++++------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md b/docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md
index 3a6ad2c..edcd148 100644
--- a/docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md
+++ b/docs/superpowers/specs/2026-03-20-galaxis-agent-phase5-deploy-design.md
@@ -16,7 +16,6 @@ galaxis-agent를 Oracle VM (A1, 4코어 ARM64, 24GB)에 배포하기 위한 자
 - 모니터링 대시보드 (Grafana)
 - 멀티 리포 지원
 - autonomous 모드 전환
-- `docker-compose.prod.yml` 수정 (CLAUDE.md 금지)
 
 ---
 
@@ -29,15 +28,17 @@ SSH로 Oracle VM에 접속한 후 실행하는 배포 스크립트.
 ```
 1. Docker 설치 확인 (docker --version)
 2. Docker Compose 설치 확인 (docker compose version)
-3. galaxis-net 네트워크 존재 확인 → 없으면 생성
-4. .env 파일 존재 확인 → 없으면 에러 + .env.example 복사 안내
-5. 필수 환경변수 검증:
+3. docker-compose.yml 유효성 검증 (docker compose config --quiet)
+4. galaxis-net 네트워크 존재 확인 → 없으면 생성
+5. .env 파일 존재 확인 → 없으면 에러 + .env.example 복사 안내
+6. 필수 환경변수 검증:
    - ANTHROPIC_API_KEY
    - GITEA_TOKEN
    - GITEA_WEBHOOK_SECRET
    - DISCORD_TOKEN
    - DISCORD_CHANNEL_ID
    - FERNET_KEY
+   - AGENT_API_KEY
 ```
 
 ### 배포 단계
@@ -45,18 +46,18 @@ SSH로 Oracle VM에 접속한 후 실행하는 배포 스크립트.
 ```
 1. galaxis-agent 이미지 빌드 (docker compose build)
 2. 서비스 시작 (docker compose up -d)
-3. 30초 대기
-4. Health check 검증:
+3. Health check 검증 (5초 간격, 최대 60초 retry):
    - GET /health → status == "ok"
    - GET /health/gitea → 연결 확인
    - GET /health/discord → 연결 확인
+   - GET /health/queue → 큐 상태 확인
    - GET /health/costs → 응답 확인
-5. 결과 출력 (성공/실패 + 로그 안내)
+4. 결과 출력 (성공/실패 + 로그 안내)
 ```
 
 ### --dry-run 옵션
 
-실제 Docker 명령을 실행하지 않고, 어떤 명령이 실행될지만 출력한다. 로컬에서 스크립트 검증용.
+pre-flight 체크는 실제로 실행하되, Docker 명령(build, up, health check)은 echo만 출력한다. 로컬에서 `.env` 유효성 등을 검증할 수 있다.
 
 ### 에러 처리
 
@@ -64,6 +65,14 @@ SSH로 Oracle VM에 접속한 후 실행하는 배포 스크립트.
 - 빌드 실패 시: 에러 로그 출력 후 종료
 - health check 실패 시: `docker compose logs` 안내 후 종료 (자동 롤백 없음)
 
+### 수동 롤백
+
+```bash
+docker compose down
+git checkout <이전_커밋>
+./deploy.sh
+```
+
 ---
 
 ## 2. build-sandbox.sh
@@ -73,9 +82,12 @@ SSH로 Oracle VM에 접속한 후 실행하는 배포 스크립트.
 ```
 1. Dockerfile.sandbox 존재 확인
 2. docker build -f Dockerfile.sandbox -t galaxis-sandbox:latest .
+   (VM에서 직접 실행하므로 네이티브 ARM64 빌드, --platform 불필요)
 3. 빌드 성공 확인 + 이미지 크기 출력
 ```
 
+`--dry-run` 옵션: 명령 출력만 (실행 안 함).
+
 ---
 
 ## 3. .env.example 업데이트