# 📑 Issue #5 Implementation Plan (Phase 1–4 Execution & Rollback Specification)

- **Document Version**: Rev.4 (Post Revision Review Corrections)
- **Issue**: [Gitea Issue #5](https://git.godopu.com/tmpl/multi-agent-mux/issues/5)
- **Status**: Target Architecture Roadmap & Execution Gate Criteria

---

## 1. 개요 및 마이그레이션 원칙

본 문서는 Issue #5(Python 모듈화 및 `lib_py` 승격)의 단계적 구현(Phase 1–4) 순서, 필수 완료 기준(Gate), 롤백 절차, 그리고 명시적 비범위(Out of Scope)를 규정합니다.

### 📌 핵심 원칙:
1. **점진적 격리 및 무중단 전환**: 프로덕션 셸 오케스트레이션(`run_loop.sh`)은 Phase 3 이전까지 계속해서 활성 상태를 유지하며, 파이썬 모듈은 독립된 패키지(`lib_py`)로 단계적으로 승격됩니다.
2. **동일 작업공간 다중 Writer 절대 금지**: 과도기적 단계에서도 특정 워크스페이스에는 오직 단 하나의 상태 제어자(신규 엔진 또는 구형 셸 루프)만 실행되어야 합니다.
3. **Fail-Closed 및 Rollback 보장**: 각 단계는 이전 버전으로 즉시 되돌릴 수 있는 명확한 롤백 소유권과 체크포인트 인계 절차를 갖추어야 합니다.

---

## 2. 단계별 구현 단위 및 필수 완료 기준 (Roadmap & Gates)

| 단계 | 작업 목표 | 세부 구현 내용 | 필수 완료 게이트 (Gate Criteria) | 롤백 절차 (Rollback Path) |
|---|---|---|---|---|
| **Phase 0**<br>*(현재)* | **사전 계약 고정 및 Fixture 수집** | • CLI, 이벤트, 리포트, 락 계약 기준선 문서화<br>• Herdr 0.8.2 네이티브 캡처 및 복합 Watcher 시나리오 2계층 분리<br>• 6개 백엔드 실측 증거 행렬 수집 | • 499개 전체 테스트 수집 및 회귀 0-Fail (100% 통과)<br>• Fixture 스키마 및 증거 경계 검증 통과<br>• 프로덕션 코드 무변경 diff 검증 | 미추적 산출물 즉시 삭제 (`rm -rf docs/contracts/issue-5 tests/fixtures/issue_5 tests/test_issue5_phase0_contracts.py`) |
| **Phase 1** | **`lib_py/delegation/` 추출** | • `lib.sh` L1833 이하 위임 헬퍼를 파이썬 서비스 클래스로 추출<br>• `start_watchdog`을 내부 명칭 `ensure_subscriber_daemon`으로 명명(기존 함수 별칭 보존)<br>• 장수 프로세스 단일 MQTT 연결 재사용 프로토타입 | • CLI/non-fatal/HMAC/seq/디스크 폴백 회귀 100% 통과<br>• 데몬 수명 및 PID 계약 일치 확인<br>• **자동완료 정책 변경 없음** | `lib.sh` 위임 헬퍼 호출을 이전 인라인/셸 방식으로 즉시 복원 |
| **Phase 2a** | **`lib_py/loop/` 코어 & Shadow Watcher** | • `engine.py` (단일 전이 주체), `watcher.py` (`herdr agent wait` 래핑) 구현<br>• 모든 Writer에 대한 단일 CAS 트랜잭션 경계 구현<br>• 자동완료를 수행하지 않고 "Would-Complete" 로깅만 수행하는 Shadow 모드 가동 | • 락 내 비동기/I/O 배제 검증<br>• 소켓 단절/스냅샷 재연결 백오프 검증<br>• Shadow 모드가 레지스트리 상태를 쓰지 않음을 검증 | 1) Shadow 모니터 프로세스 종료 및 인메모리 큐 폐기<br>2) CAS 서비스는 하위 호환 모드로 유지하거나 `MAM_ENGINE_CAS=0` 플래그로 비활성화하여 레거시 무조건 필드 병합(`update_job_status`)으로 복귀<br>3) 기존 셸 루프 상태 및 레코드 불변 유지 |
| **Phase 2b** | **이중 감지 자동완료 활성화 (Flag-Gated)** | • 4중 실행 귀속 + 리포트 확정 계약 + 단일 CAS 전이 게이트 연동<br>• Pending Notification 지연 알림 및 크래시 복구 구현<br>• 검증된 백엔드/작업에 한해 opt-in 플래그로 활성화 (기본값 OFF) | • 부수효과 작업 예외 및 무판정 fail-closed 테스트 완료<br>• 경쟁/재시작 시나리오 통과<br>• 플래그 OFF 시 기존 explicit event 경로 100% 보존 | 환경변수/플래그 `MAM_AUTO_COMPLETE=0` 설정; 이미 확정된 terminal 레코드는 보존하고 신규 자동완료만 중단 |
| **Phase 3** | **`run_loop.sh` Thin Wrapper 전환 및 전면 회귀** | • `run_loop.sh`를 인자 전달 래퍼(`exec python3 -m lib_py.loop "$@"`)로 전환<br>• 플래너/리뷰어/반론/승격 오케스트레이션 로직 완전 이식<br>• 엄격한 판정 파서(Strict Parser) 적용 | • 5개 subprocess 전용 테스트(~1,621줄) 포함 전체 481개+ 테스트 0-Fail<br>• 시그널, 루프 가드, 임의 CWD 및 공백 경로 검증 통과 | **우아한 핸드오프 시퀀스**:<br>1) Quiesce: 실행 중인 Python 루프 프로세스에 종료 신호를 전달하여 신규 디스패치 중단<br>2) Checkpoint: 현재 루프 회차, 활성 Job ID 및 리뷰 상태를 `.mam/loop-checkpoint.json`에 원자적 기록<br>3) Exit: Python 루프 정상 종료 및 가드 해제<br>4) Resume: 백업된 셸 원본 스크립트로 `run_loop.sh` 복원 후 체크포인트 기반 재개 검증 |
| **Phase 4** | **불변 런타임 검증 및 Freeze 제거** | • 기동 시 전체 모듈 상주(Eager Import) 및 자식 템플릿 불변성 검증<br>• 작업 도중 스킬 파일 교체 및 늦은 경로 스트레스 테스트 통과<br>• `/tmp/mam-loop-freeze.XXXXXX` 우회책 완전 제거 | • 런타임 자기수정 크래시(B-13) 재발 방지 검증<br>• Live Helper 버전 호환 게이트 검증 통과<br>• 운영 문서 및 배포 스크립트 갱신 | Freeze 복사 로직(`run_loop.sh:112-127`) 재활성화 및 라이브 헬퍼 버전 검사 복구 |

---

## 3. 라이브 헬퍼 버전 호환성 및 작업 상태 전이 계약 (Live Helper Compatibility Gate)

통합 보고서(Rev.2) 및 B-13 합의에 따라, `multi-agent-mux-create`, `resume`, `stop` 등 1회성 스크립트는 Freeze 복사본이 아닌 Live Tree에서 실행됩니다. Phase 4에서 Freeze가 제거되기 전까지, 라이브 헬퍼와 고정 실행 엔진 간의 충돌을 방지하고 기존 작업 상태 전이 효과를 보존하기 위해 다음 규칙을 적용합니다:

1. **ABI 버전 및 프로토콜 해시 검증**:
   - Live Tree의 스크립트가 실행될 때, 현재 실행 중인 루프의 `MAM_VERSION` 또는 공통 라이브러리 인터페이스 해시를 비교합니다.
   - 메이저 버전 불일치 또는 레지스트리 스키마 변경이 감지되면, 라이브 헬퍼는 즉시 오류를 반환하고 안전하게 중단(fail-closed)합니다.
2. **작업 취소(`cancelled`) 전이의 정규 서비스 경유 보존**:
   - `multi-agent-mux-stop/scripts/stop_session.sh`는 세션 강제 종료 시 잔여 활성 작업에 대해 `cancelled` 이벤트를 발행합니다 (`stop_session.sh:242, 322`).
   - 라이브 헬퍼는 레지스트리 JSON 파일을 임의로 변조하지 않고, `delegate_publish_event` 및 공통 상태 전이 서비스(Transition Service)를 호출하여 CAS 불변식을 준수하면서 작업을 정규 `cancelled` 상태로 전이시킵니다.
   - 이를 통해 세션 중단 시 작업이 영구 고착(hang)되지 않고 오케스트레이터 루프가 즉각 취소를 인지할 수 있도록 보장합니다.

---

## 4. 명시적 비범위(Out of Scope) 및 호환성 계약

1. **저장소 통합 금지**:
   - 세션 관리용 SQLite/YAML 저장소(`.mam/agent-sessions.yaml`, `.db`)와 비동기 작업 관리용 JSON 레지스트리(`.mam/jobs/`)를 하나로 통합하려 시도하지 않습니다.
2. **원샷 스킬의 Live Tree 실행 유지**:
   - `multi-agent-mux-create`, `resume`, `stop` 등 1회성 셸 스크립트는 Freeze 복사본이 아닌 실제 작업 트리의 코드를 실행하도록 유지합니다.
3. **타임아웃 3원 분리 보존**:
   - (a) 전체 벽시계 타임아웃, (b) MQTT 가입자 idle-timeout, (c) TUI idle 자동완료를 독립적으로 유지하며, 자동완료가 기존 타임아웃 메커니즘을 덮어쓰지 않습니다.

---

## 5. 성능 수용 기준 (Performance Acceptance Criteria)

고정밀 10ms 폴링 대신 실제 시스템 자원 측정을 기준으로 성능을 평가합니다:
- **프로세스 포크 수 (Fork Count)**: 루프 반복당 서브프로세스 생성 횟수 대폭 감소 (셸 루프 대비 ≥70% 감축).
- **유휴 CPU 점유율 (Idle CPU)**: 대기 중 CPU 사용률 1% 미만 유지 (이벤트 구동 및 유계 폴링).
- **MQTT 연결 재사용**: 단일 장수 프로세스 내에서 다수의 작업 발행 시 연결 재수립 오버헤드 제거 (p50 레이턴시 단축).