# task-2104 완료 보고서

## Situation
`codex_gate_check.py`의 `workspace_root` 기본값이 `/home/jay/workspace`로 하드코딩되어, InsuRo(`/home/jay/projects/InsuRo/`) 등 외부 프로젝트 파일 분석 불가.

## Complication
worktree에서 Codex 게이트 실행 시 affected_files 경로가 맞지 않아 파일 읽기 실패. 외부 프로젝트 작업마다 수동 경로 지정 필요.

## Question
CLI에 `--workspace-root` 옵션을 추가하고, task 파일에서 프로젝트를 자동 감지하여 하위호환을 유지하면서 외부 프로젝트를 지원할 수 있는가?

## Answer

### 수정 파일 목록

- `scripts/codex_gate_check.py` — `--workspace-root` CLI 옵션, `_detect_workspace_root()` 자동 감지, 시그니처 변경
- `prompts/gate_instructions.py` — `get_codex_gate_command()`에서 `--workspace` → `--workspace-root` 전환
- `prompts/DIRECT-WORKFLOW.md` — workspace-root 가이드 섹션 추가
- `tests/integration/test_gate_instructions.py` — `--workspace` ��� `--workspace-root` 어서션 업데이트

### 변경 상세

**1. CLI `--workspace-root` 옵션 추가**
- `--workspace-root` (primary) + `--workspace` (별칭, 하위호환) → `dest="workspace_root"`
- 기본값: `None` (미지정 시 자동 감지)

**2. 프로젝트 경로 자동 감지**
- `_detect_workspace_root(task_file)` 신규 함수
- task 파일 `## 프로젝트` 섹션에서 프로젝트명 파싱
- 매핑: `insuro` → `/home/jay/projects/InsuRo`, `insuwiki` → `/home/jay/projects/insuwiki`
- 매핑에 없는 프로젝트명 → `/home/jay/workspace` 기본값 (dev-system 등)
- 경로 미존재 시 경고 후 기본값 폴백

**3. `codex_gate_check()` 시그니처 변경**
- `workspace_root: str = "/home/jay/workspace"` → `workspace_root: str | None = None`
- 함수 진입 시 `None`이면 `_detect_workspace_root()` 호출
- assert로 Pyright 타입 내로잉 보장

**4. `gate_instructions.py` 업데이트**
- `get_codex_gate_command()`에서 `--workspace` → `--workspace-root` 전환

**5. DIRECT-WORKFLOW.md 가이드 추가**
- Codex 게이트 `--workspace-root` 옵션 사용 안내 섹션 추가

### 검증 결과

**기존 테스트:**
- `scripts/tests/test_codex_gate_check.py`: 45 passed
- `tests/integration/test_gate_instructions.py`: 16 passed
- 총 61 테스트 전부 PASS (0.22s)

**검증 시나리오:**
1. `--workspace-root /home/jay/workspace` 명시 지정 → 정상 작동 (pass: true)
2. `--workspace-root` 미지정 (task-2104 = dev-system 프로젝트) → `/home/jay/workspace` 기본값 자동 감지 (pass: true)
3. `--workspace` 하위호환 → 정상 작동 (pass: true)

### L1 스모크테스트 결과
- 서버 재시작: 해당없음 (CLI 도구, 서버 아님)
- API 응답 확인: 해당없음
- CLI 실행 확인: `python3 scripts/codex_gate_check.py --task-id task-2104` → JSON 출력 성공, source=codex_companion
- 스크린샷: 해당없음

### 이슈 및 해결

1. **Pyright 타입 에러** — `workspace_root: str | None`을 `str` 파라미터에 전달 시 타입 불일치. `assert isinstance(workspace_root, str)` 추가로 해결.
2. **gate_instructions.py 미갱신** — `get_codex_gate_command()`가 여전히 `--workspace` 사용 중이었음. `--workspace-root`로 업데이트 및 테스트 수정.
3. **dispatch.py 수정 불필요** — dispatch.py는 codex_gate_check를 직접 호출하지 않고 프롬프트 삽입 방식. gate_instructions.py가 실제 호출 명령을 생성하므로 여기만 수정하면 충분.

### QC 자동 검증
```
qc_verify.py --task-id task-2104 --skip api_health --check-files scripts/codex_gate_check.py,prompts/gate_instructions.py
- test_runner: PASS (61 tests)
- pyright_check: PASS
- scope_check: PASS
- schema_contract: PASS
```

### 모델 사용 기록
- 엔키(백엔드, sonnet): codex_gate_check.py 수정
- 이쉬타르(프론트엔드, haiku): DIRECT-WORKFLOW.md 가이드 추가 (단순 문서 작업이므로 haiku 적합)
- 마르둑(팀장, opus): gate_instructions.py 수정, Pyright 에러 수정, 테스트 어서션 업데이트, QC/보고서 작성

## 세션 통계
- 총 도구 호출: 0회