# 📑 Issue #5 Phase 3 — `run_loop.sh` Thin Wrapper 전환 및 `lib_py.loop` 승격 명세

- **문서 버전**: Rev.1
- **상태**: Phase 3 설계 및 이식 착수 기준선 (Implementation & Regression Specification)
- **대상 파일**:
  - `lib_py/loop/runner.py`, `lib_py/loop/__main__.py`, `lib_py/loop/parser.py`
  - `.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh`
  - `tests/test_issue5_phase3_loop.py`

---

## 1. 개요 및 한 문장 요약

**936줄의 복잡한 Bash 오케스트레이션(`run_loop.sh`)을 단일 제어 구조의 Python 모듈(`lib_py.loop`)로 승격하고, `run_loop.sh`는 CLI 계약과 B-13 Freeze를 보존하는 얇은 래퍼(Thin Wrapper)로 전환한다.**

Phase 2(CAS 전이 엔진, 이중 감지 자동완료 게이트)에서 구축된 상태 및 판정 기반을 실제 루프 제어 흐름에 유기적으로 결합하며, 기존 732개 테스트의 0-Fail 통과와 셸 레거시 롤백(`MAM_LOOP_PY=0`)을 보장합니다.

---

## 2. 모듈 아키텍처 (`lib_py/loop/`)

Phase 1/2a의 형제 패키지 격리 원칙(D1(b), G9: `lib_py.loop`는 `lib_py.delegation` 외의 다른 형제 패키지를 임포트하지 않음)을 엄격히 준수합니다.

```
lib_py/loop/
├── __init__.py           # 패키지 선언 및 export
├── __main__.py           # python3 -m lib_py.loop 진입점
├── parser.py             # 코드 펜스 제외 Strict 판정/태그 파서
├── runner.py             # 오케스트레이터 본체 (LoopRunner 클래스)
├── checkpoint.py         # 체크포인트 기록 및 복구 (.mam/loop-checkpoint.json)
├── attribution.py        # [Phase 2a] 관측 증거 수집
├── watcher.py            # [Phase 2a] herdr agent wait 래퍼
├── policy.py             # [Phase 2a] 상태 결정 정책
├── shadow.py             # [Phase 2a] Would-Complete shadow 실행기
├── store.py              # [Phase 2a] 증거 저장소
└── autocomplete.py       # [Phase 2b] 자동완료 평가기
```

---

## 3. 핵심 설계 요소

### 3-1. 엄격한 판정 파서 (Strict Parser, `parser.py`)
- **코드 펜스(` ``` `) 무시**:
  - 기존 셸 정규식은 리포트 본문 내 코드 블록(예: 마크다운 예시 등)에 적힌 `[VERDICT: PASS]`도 파일 끝에 위치하면 유효한 판정으로 오인하는 결함(`baseline.md` Gap)이 존재했습니다.
  - Python 파서는 텍스트를 파싱할 때 마크다운 코드 펜스(` ``` ` 또는 `~~~`) 내부 라인을 제거한 뒤, **가장 마지막 비공백 라인(last non-blank line)**만을 검사합니다.
- **Fail-Closed 불변식**:
  - 판정 라인이 없거나, `[VERDICT: NOT PASS]`와 `[VERDICT: PASS]`가 모호하게 충돌하거나, 알 수 없는 태그인 경우 예외 없이 `NOT PASS`로 처리합니다.
- **태그 추출**:
  - `[ESCALATE: PLANNER]`: 코드 펜스 외부 어디서든 단독 행으로 존재하면 감지
  - `[REBUT: <reviewer>]`: Creator 반론 대상 리뷰어 세션명 추출 (중복 제거 및 실제 거부한 리뷰어로 필터링)
  - `[ADJUDICATION: SUSTAINED|OVERRULED]`: 재심 판정 추출 (fail-closed: 명시적 SUSTAINED 외에는 모두 OVERRULED)
  - `[ARBITRATION: CREATOR|REVIEWER]`: Planner 중재 판정 추출

### 3-2. `run_loop.sh` Thin Wrapper 및 하위 호환성
- **하위 호환 롤백 플래그**:
  - `MAM_LOOP_PY=1` (기본값): Python `lib_py.loop` 실행
  - `MAM_LOOP_PY=0`: 기존 인라인 셸 루프 실행 (안전 롤백 경로)
- **B-13 Freeze 및 인자 보존**:
  - Phase 4에서 Freeze가 제거되기 전까지, `run_loop.sh`는 기존처럼 기동 시 `/tmp/mam-loop-freeze.XXXXXX`로 트리를 복제하여 실행 격리를 유지합니다.
  - `MAM_REAL_ROOT`, `WORKSPACE_ROOT`, `MAM_ENV_FILE` 환경변수 export를 그대로 유지하여 기존 테스트의 문자열 검증을 만족합니다.
- **기존 테스트 텍스트 앵커 보존**:
  - `test_o1_rebuttal.py` (`has_tag_line() {`, `extract_tag_values() {`, `find_report() {`)
  - `test_b7_diff_untracked.py` (`CHANGES_DIFF=$(mam_collect_changes_diff ...`)
  - `test_deploy_freshness.py` (`export MAM_ENV_FILE=`)
  - `test_o3_scoped_guard.py` (`mam_release_loop_lock`)
  - 위 앵커들은 `run_loop.sh` 내에 셸 헬퍼 또는 주석/shim 블록으로 보존되어 기존 정적 검사 테스트들을 100% 통과시킵니다.

### 3-3. 체크포인트 및 정지 프로토콜 (`checkpoint.py`)
- **원자적 체크포인트 (`.mam/loop-checkpoint.json`)**:
  - 루프 회차(`iteration`), 활성 Job ID 목록(`created_jobs`), 현재 계획(`current_plan`), 리뷰 상태(`review_status`), 기준 커밋(`base_commit`), 타임스탬프 기록.
  - 임시 파일 쓰기 후 원자적 rename(`replace`)으로 커밋.
- **우아한 정지 (Quiesce on Signal)**:
  - SIGINT/SIGTERM 수신 시 즉시 강제 종료하지 않고, 현재 진행 중인 서브프로세스를 정리하고 체크포인트를 기록한 뒤 가드를 해제하고 안전하게 종료(exit 130/143)합니다.

---

## 4. 단계별 세부 구현 및 검증 게이트 (P3-01 ~ P3-03)

### 📌 P3-01: `lib_py/loop/parser.py` 및 오케스트레이션 로직 이식
1. `parser.py` 구현: 코드 펜스 분리 및 엄격한 판정/태그 추출 로직 작성.
2. `runner.py` 구현:
   - CLI 인자 파싱 및 검증 (`--creator`, `--task`, `--plan`, `--plan-talk`, `--reviewer`, `--all-reviewer`, `--max-loop`, `--max-rebut`, `--cleanup`, `--verbose`)
   - 세션 조회 및 상태 검증 (Planner, Target Agent, Reviewers)
   - Phase 1 플래닝 및 토론 (Plan ➔ Critique ➔ Refine)
   - Phase 2 구현 디스패치 (Worker)
   - Phase 3 리뷰 루프 (병렬 디스패치, Strict 판정 수렴, Escalation 분기, Rebuttal/Adjudication/Arbitration)
   - Phase 4 산출물 승격 (Plan 및 Report 원자적 복사/이동) 및 임시 디렉터리 정리
3. `tests/test_issue5_phase3_loop.py` 작성:
   - 코드 펜스 내부 허위 판정 무시 검증 (Strict Parser)
   - Rebuttal 예산(iteration budget vs run-wide budget) 및 중재 흐름 검증
   - 만장일치 PASS 수렴 검증

### 📌 P3-02: `run_loop.sh` Thin Wrapper 전환 및 런타임 호환성
1. `run_loop.sh`에 `MAM_LOOP_PY` 분기 도입:
   - `MAM_LOOP_PY=1`일 때 Python `lib_py.loop`로 위임
   - 기존 CLI 파싱, `--help` exit 1 유지, B-13 freeze 격리 유지
   - 기존 테스트 텍스트 앵커 보존
2. CWD, 공백 경로, 시그널 트랩, 인터프리터 앵커링 검증:
   - Freeze 사본 내에서 실행 시 `_delegate_py_bin`이 `WORKSPACE_ROOT` 기준 인터프리터를 정확히 해석하는지 검증 (O-4 인계 해결)

### 📌 P3-03: 전면 회귀 검증 및 체크포인트 핸드오프
1. 전체 732개 테스트 회귀 검증:
   - `test_loop_cli.py`, `test_o1_rebuttal.py`, `test_tier4_e2e.py` (Scenario 5 E2E 루프 포함) 전체 0-Fail 통과
2. 체크포인트 기록 및 시그널 인터럽트 시뮬레이션 검증.
3. 롤백 드릴: `MAM_LOOP_PY=0`으로 기존 셸 루프 전환 시 정상 작동 확인.