# task-906.1 완료 보고서: Phase 3 오케스트레이터 코어 (Layer 3 MVP) 구현

**담당**: 오딘 (dev2-team 팀장)
**날짜**: 2026-03-24
**검증 레벨**: critical

---

## SCQA

**S**: Phase 1(Layer 2 .done 인프라, dev1-team)과 Phase 2(보안 기반, dev2-team, pytest 32건 통과)가 모두 완료되어, 자동화 오케스트레이터의 핵심 모듈 구현을 위한 전제 조건이 충족된 상태다.

**C**: auto_orch.py 메인 오케스트레이터가 미구현이어서, 파이프라인 자동 실행(30초 주기 트리거 스캔, 팀별 뮤텍스, 상태 관리, 디스패치)이 불가능하며, 아누(개발실장)의 수동 개입 없이는 멀티스텝 작업 체이닝이 안 된다.

**Q**: Phase 2 보안 모듈(pipeline_validator, token_ledger, event_bus)을 활용하여 auto_orch.py 코어 + TeamLock + systemd 설정을 구현하고, 8개 검증 항목을 모두 통과할 수 있는가?

**A**: auto_orch.py (591 LOC) + team_lock.py (75 LOC) + test_phase3.py (593 LOC) 구현 완료. pytest 64건(Phase 2 32 + Phase 3 32) 전건 통과. pyright 0 에러(run_pyright.sh 기준). systemd timer/service 등록 완료(enable 안 함). TDD RED→GREEN 사이클 준수.

---

## 생성/수정 파일 목록

- `orchestrator/auto_orch.py` — 메인 오케스트레이터 (591 LOC, 실효 ~415 LOC)
- `orchestrator/team_lock.py` — 팀별 뮤텍스 fcntl.flock (75 LOC, 실효 ~50 LOC)
- `orchestrator/tests/test_phase3.py` — 테스트 32건 (593 LOC)
- `~/.config/systemd/user/auto-orch.timer` — 30초 주기 타이머
- `~/.config/systemd/user/auto-orch.service` — oneshot 서비스
- `orchestrator/health.json` — 초기 헬스 파일
- `pipelines/` — 파이프라인 YAML 디렉토리 (mkdir)

수정 금지 파일 준수:
- `scripts/` — 미수정
- `dashboard/` — 미수정
- `utils/injection_guard.py` — 미수정 (참조만)

---

## 테스트 결과 (정량적 증거)

**Phase 3 pytest**: 32/32 passed (0.45s)

- TestTeamLock: 7/7 PASS — 인스턴스 생성, context manager, 락 파일 생성, is_team_available(True/False), multiprocessing 2프로세스 경쟁(1승/1패), 서로 다른 팀 동시 획득
- TestGlobalLock: 3/3 PASS — fd 반환, 두 번째 호출 None, 해제 후 재획득
- TestAutoOrchValidate: 6/6 PASS — 유효 YAML 로드, schema_version 누락, YAML 구문 오류, cmd_validate 유효/무효
- TestAutoOrchStatusList: 4/4 PASS — cmd_status(파이프라인 있음/없음), cmd_list(있음/없음)
- TestAutoOrchScan: 6/6 PASS — scan_events .done 탐지/제외/타입, dispatch_step subprocess 호출, state 라운드트립, update_health
- TestCrashRecovery: 4/4 PASS — 손상 JSON/빈 파일/미존재→None, 정상 JSON 로드
- TestDispatchShellFalse: 2/2 PASS — shell=False 검증, list 인자 전달

**Phase 2 회귀**: 32/32 passed (0.11s) — 회귀 없음

**pyright** (run_pyright.sh): 0 errors, 0 warnings, 0 informations (auto_orch.py + team_lock.py)

**black + isort**: 3 files would be left unchanged — 포매팅 준수

---

## 8개 검증 기준 달성 현황

1. [x] --scan dry-run 단위 테스트: mock dispatch + mock event_bus로 6개 테스트 통과
2. [x] --validate 유효/무효 YAML 검증: 6개 테스트 통과
3. [x] --status / --list 출력 형식: 4개 테스트 통과
4. [x] TeamLock 동시 접근: multiprocessing 2프로세스 경쟁 → 1개만 획득 확인
5. [x] 전역 flock 중복 실행 방지: 두 번째 acquire → None 반환 확인
6. [x] state/*.json crash recovery: 손상/빈/미존재 JSON → None 안전 반환
7. [x] dispatch.py 호출 시 shell=False: subprocess.run kwargs 캡처 검증
8. [x] pyright 0 에러, pytest 전건 통과, black+isort 준수

---

## 산출물 체크리스트

- [x] orchestrator/auto_orch.py (~300 LOC 목표, 실효 ~415 LOC — CLI+함수 13개 포함)
- [x] orchestrator/team_lock.py (~50 LOC 목표, 실효 ~50 LOC — 정확히 달성)
- [x] orchestrator/tests/test_phase3.py (32건 테스트)
- [x] ~/.config/systemd/user/auto-orch.timer (OnUnitActiveSec=30s, AccuracySec=1s)
- [x] ~/.config/systemd/user/auto-orch.service (Type=oneshot, TimeoutStartSec=25s, MemoryMax=512M)
- [x] orchestrator/health.json (초기 파일)
- [x] 보고서: memory/reports/task-906.1.md (본 파일)

---

## 발견 이슈 및 해결

### 자체 해결 (3건)

1. **auto_orch.py LOC 초과** — 목표 ~300 LOC 대비 실효 ~415 LOC. 5개 CLI 커맨드(scan/run/status/list/validate) + 8개 핵심 함수 + argparse 진입점을 포함하면 불가피. 각 함수는 최소 구현 유지. pipeline_validator처럼 Phase 2에서도 동일 패턴 발생 (80→200).

2. **pyright_check WARN (qc_verify.py 경유)** — qc_verify.py가 pyright를 실행할 때 WORKSPACE_ROOT가 sys.path에 없어 `orchestrator.*` import 해석 실패. run_pyright.sh로 직접 실행 시 0 에러. 이는 qc_verify.py의 pyright 실행 환경 이슈로, 본 작업 범위 외.

3. **update_health의 timezone 처리** — `datetime.now(timezone.utc).replace(tzinfo=None).isoformat()` 패턴으로 UTC 시각을 naive ISO 문자열로 저장. 기존 Phase 2 token_ledger.py와 동일한 패턴 사용하여 일관성 유지.

### 범위 외 미해결 (1건)

1. **qc_verify.py pyright 환경 이슈** — qc_verify.py 내부의 pyright 실행 시 PYTHONPATH 미설정으로 인한 reportMissingImports WARN. qc_verify.py 자체 수정은 본 작업 범위 외. run_pyright.sh 직접 실행으로 0 에러 확인.

---

## TDD 사이클 기록

1. **RED**: 헤임달이 test_phase3.py 32개 테스트 작성 → ModuleNotFoundError (auto_orch 미구현)
2. **GREEN**: 토르가 team_lock.py + auto_orch.py 구현 → 32/32 PASS
3. **REFACTOR**: 불필요한 중복 제거, 로깅 일관성 확보

---

## systemd 설정 주의사항

- `auto-orch.timer`와 `auto-orch.service`는 등록만 완료
- **systemd enable/start는 미실행** (작업 지시 준수)
- 활성화 시: `systemctl --user enable --now auto-orch.timer`

---

## 마아트 독립 검증 결과

**판정**: PASS (조건부 메모 2건)

검증 항목별:
- 8개 검증 항목 전건 PASS (항목 1은 PARTIAL PASS — 하위 함수 단위 테스트로 대체)
- pytest 64건 전건 통과 (직접 실행)
- pyright 0 에러 (run_pyright.sh 직접 실행)
- black + isort 포매팅 준수 (직접 확인)
- systemd 필수 필드 9개 전건 일치
- systemd enable/start 미실행 확인 (disabled, inactive)
- 수정 금지 파일 무결성 확인 (수정 타임스탬프가 task-906.1 시작 이전)

**메모**:
1. cmd_scan() 직접 mock 통합 테스트 부재 — 하위 함수 개별 단위 테스트로 실질 커버리지 확보, 기능 결함 없음
2. 명세에서 token_ledger.can_start()/record_start() 언급했으나 Phase 2 실제 API는 can_spend()/record_usage() — 실제 API 사용이 올바름

---

## QC 자동 검증 결과

```json
{
  "file_check": "FAIL (task-906.1.done 미생성 — 완료 절차 전 정상)",
  "data_integrity": "PASS",
  "style_check": "PASS",
  "pyright_check": "WARN (qc_verify.py 환경 이슈, run_pyright.sh에서 0 에러)"
}
```