# task-2355: codex_gate_check.py 워크트리 인식 fix

## SCQA 요약

**S**: `scripts/codex_gate_check.py`는 `_detect_workspace_root()`로 프로젝트 디렉토리(예: `/home/jay/projects/InsuRo`)를 감지하여 affected_files 코드를 Codex에 전달한다.

**C**: 봇이 워크트리(예: `/home/jay/projects/InsuRo/.worktrees/task-2354-fix`, branch `feat/task-2354-phase1`)에서 작업하면 worktree 변경분이 아닌 main 브랜치 코드가 Codex에 전달되어 false negative FAIL이 반복된다. task-2354에서 페룬이 fix 16건을 worktree에 commit했으나 Codex는 매 회 "현재 코드베이스에는 그 상태가 반영되어 있지 않아"로 응답해 무한 follow-up 루프 발생 (13:47 멈춤).

**Q**: task_id로부터 활성 worktree를 자동 탐지하여 Codex가 실제 변경분을 평가하도록 만들 수 있는가?

**A**: `utils/worktree_resolver.py` 신규 모듈로 task-timers.json + glob 2단계 탐지를 구현하고, `codex_gate_check`에 `target_dir` 개념(env `CODEX_TARGET_DIR` / CLI `--target-dir` / auto-resolve / fallback)을 도입했다. 파일 읽기와 codex companion cwd가 모두 worktree 기준으로 동작한다. pytest 71/71 PASS, 기존 호출 사이트(`gate_instructions.py`, `team_prompts.py`)는 옵션 파라미터라 무수정 호환.

## 변경 요약

### 신규 (2)
- `/home/jay/workspace/utils/worktree_resolver.py` (70 lines)
  - `resolve_worktree_target_dir(task_id) -> tuple[str | None, str]`
  - 우선순위: task-timers.json `worktree_path`(`/.worktrees/` 포함 시) → projects glob (most-recent mtime) → None
- `/home/jay/workspace/scripts/tests/test_worktree_resolver.py` (220 lines, 11 tests)

### 수정 (2)
- `/home/jay/workspace/scripts/codex_gate_check.py` (483 → 522 lines)
  - `codex_gate_check()` / `_maat_fallback_check()`에 `target_dir` 파라미터 추가
  - target_dir 결정 우선순위: param → env `CODEX_TARGET_DIR` → `resolve_worktree_target_dir(task_id)` → workspace_root fallback
  - 파일 읽기와 `_run_codex_companion(prompt, cwd=...)`에 target_dir 사용 (AST callers 분석은 workspace_root 유지 — 도구 자체가 workspace 자산)
  - 결과 dict에 `target_dir`, `target_dir_source` 메타 추가 → `.codex-gate` 이벤트 파일에 저장 → 사후 디버깅 가능
  - `--target-dir` CLI 인자 추가
- `/home/jay/workspace/scripts/tests/test_codex_gate_check.py` (1141 → 1317 lines)
  - `TestTargetDirResolution` 클래스 추가 (6 tests): explicit param, env var, task-timers, glob, fallback, 결과 메타 검증

## 테스트 결과

```
============================== 71 passed in 0.28s ==============================
scripts/tests/test_worktree_resolver.py ...........              [11/11]
scripts/tests/test_codex_gate_check.py .................................  [60/60]
```

기존 60개 + 신규 11개 = 71개 모두 PASS. 기존 호출 사이트 무회귀.

## L1 스모크테스트 결과

- **서버 재시작**: 해당없음 (CLI 스크립트, 서버 없음)
- **API 응답 확인**: 해당없음
- **스크린샷**: 해당없음
- **실동작 검증** (codex_gate_check CLI):
  ```
  $ python3 utils/worktree_resolver test
    task-2354: path=None, source=none  # task-2354 worktree가 cleanup된 상태
    None: path=None, source=none
    task-99999: path=None, source=none
  ```
  → 실제 환경에는 활성 worktree가 없어 source=none이 정상.
  → 단위테스트 `test_glob_fallback`, `test_glob_returns_most_recent`로 worktree 존재 시 정상 탐지 검증 완료.
- **결과 dict 메타데이터**: `target_dir`, `target_dir_source` 키가 `.codex-gate` 이벤트 파일에 기록되어 운영 시 false negative 사후 추적 가능.

## 발견 이슈 및 해결

### 자체 해결 (2건)
1. **Pyright import-untyped 진단** — `from utils.worktree_resolver import ...`에 `# type: ignore[import-untyped]` 추가 (기존 `from utils.sanitize_gate import ...` 패턴 동일).
   - 상세: `scripts/codex_gate_check.py:388`, `scripts/tests/test_codex_gate_check.py:798`
2. **테스트 미사용 변수 경고** — `test_worktree_resolver.py`의 미사용 `import pytest` 제거, `capture_run(*_args, ...)` → `capture_run(*_, ...)`로 변경 (pyright는 `_` 단일 이름만 미사용 허용).
   - 상세: `scripts/tests/test_worktree_resolver.py:12`, `scripts/tests/test_codex_gate_check.py:787`

### 범위 외 미해결 (1건)
1. **task-timers.json `worktree_path` 미저장 사례** — task-2354에서 worktree_path가 None으로 저장되었음을 발견. dispatch.py가 worktree 경로를 task-timers에 저장하지 않는 케이스가 존재. 본 fix에서는 glob fallback으로 우회 가능하므로 별도 task로 분리 권장 — 범위 외 사유: dispatch.py 수정은 본 task 범위(`codex_gate_check.py` 인식 fix)를 벗어남.

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: 본 작업은 워크스페이스 시스템 코드 (project worktree 미사용) — 직접 main에 작성됨
- **워크트리 경로**: 해당없음 (시스템 인프라 작업)
- **머지 의견**: pytest 71/71 PASS, 기존 호출 사이트와 100% 호환 (target_dir 기본값 None). 추가 위험 없음.

## 영향 분석 (다른 task의 false negative 가능성)

- task-2354: 본 fix 후 재실행 시 worktree 변경분 기반 정확 평가 가능 (단, worktree가 다시 생성되어야 함)
- task-2353 등 비슷한 패턴: `.codex-gate` 이벤트 파일에 `target_dir_source = "workspace_root_fallback"`이 기록되면 동일 false negative 가능성. 사후 grep으로 식별 가능.
- 향후 dispatch.py가 위임 시 `--target-dir`를 명시적으로 전달하도록 보강하면 더욱 robust (별도 task 권장).

## 산출물 파일

- `/home/jay/workspace/utils/worktree_resolver.py`
- `/home/jay/workspace/scripts/codex_gate_check.py`
- `/home/jay/workspace/scripts/tests/test_worktree_resolver.py`
- `/home/jay/workspace/scripts/tests/test_codex_gate_check.py`
- `/home/jay/workspace/memory/reports/task-2355.md` (본 보고서)

## 모델 사용 기록

- 팀원: 쿠쿨칸 (백엔드) / 작업 내용: worktree_resolver 모듈 + codex_gate_check.py 수정 + 테스트 71개 / 사용 모델: sonnet / 정당성: -
- 팀원: 이참나 (팀장) / 작업 내용: 진단 4건 직접 수정 (pyright fix) / 사용 모델: opus / 정당성: 단순 import 주석 추가로 dispatch 비용 절감

(총 약 470 단어)

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


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


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


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