# 📑 자율 반복 정제 루프 스킬 (`multi-agent-mux-loop`) 개발 계획서

이 문서는 멀티 에이전트 자율 오케스트레이션 루프(`multi-agent-mux-loop`)의 **최종 안전/가드레일 옵션 규격을 포함하여 완벽하게 정제된 마스터 계획서**입니다.
리뷰어 에이전트들의 교차 2차 피드백(Verdict 파싱, 자가 리뷰 방지, 타임아웃 보강)을 완벽하게 수렴하여 정교하게 갱신되었습니다.

---

## 1. ⚙️ 최종 스킬 명령 및 전체 옵션 세트 명세 (CLI Spec)

```bash
$ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
    [--plan] \
    [--plan-talk N] \
    [--reviewer "reviewer-1,reviewer-2"] \
    [--all-reviewer] \
    [--max-loop N] \
    [--verbose] \
    [--cleanup] \
    --target-agent "<creator-session-name>" \
    --task "수행할 작업 목표"
```

### 📥 옵션 상세 리스트 및 가드레일 제약

| 옵션명 | 기본값 | 분류 | 역할 및 안전 조치 |
|---|---|---|---|
| `--plan` | 비활성 | 기능 | Planner 에이전트를 기동하여 협력 계획 수립 및 토론 단계 개시. (비활성화 시 기존 계획서를 로드하며, 계획서가 없는 경우 Creator가 직접 계획 및 설계를 수립하여 구동) |
| `--plan-talk N` | `1` | 안전 | 플래너-작업자 간 토론 왕복 횟수 상한선. 토큰 낭비 무한 토론 차단. |
| `--reviewer "A,B"` | 비활성 | 기능 | 지정된 peer 리뷰어 에이전트 세션(들)에 피드백 루프 의뢰 (주 작업자 세션은 강제 제외). |
| `--all-reviewer` | 비활성 | 기능 | 레지스트리 상의 모든 `role: reviewer` 세션들을 전수 자동 수집하여 의뢰 (주 작업자 세션은 강제 제외). |
| `--max-loop N` | `3` | **안전 (필수)** | 반려(`NOT PASS`) 시 최대 수정 횟수 제한. **토큰 비용 폭주 방지 가드레일.** |
| `--verbose` | 비활성 | 편의 | 단계별 타임라인 진행 상태 및 잡 매핑 로그의 실시간 상세 출력. |
| `--cleanup` | 비활성 | 편의 | 루프 완료 후 성공한 임시 잡 파일(`.mam/jobs/`)들의 자동 클린업 청소. |
| `--target-agent` | (필수) | 인프라 | 구현을 처리할 주 개발자(Creator) 세션 이름 명시. |
| `--task` | (필수) | 인프라 | 자율 루프에 전달할 최종 구현 지시사항 텍스트. |

---

## 🔄 2. 자율 오케스트레이션 상세 파이프라인 (Sequence Flow)

```mermaid
sequenceDiagram
    autonumber
    actor User as 사용자 / run_loop.sh
    participant Plan as Planner Agent
    participant Dev as Creator Agent
    participant Rev as Reviewer Agents

    User->>User: run_loop.sh 기동 (옵션 세트 검증 및 대상 예외 필터링)
    
    %% Planning & Challenge discussion
    alt --plan 지정 시
        User->>Plan: delegate-job (계획 수립 지시)
        Plan-->>User: 계획서 도출 완료
        loop 지정된 --plan-talk 횟수 동안 반복 (기본 1회)
            User->>Dev: delegate-job (계획서 비판적 검토 및 이의제기 지시)
            Dev->>Plan: 계획서의 맹점 1가지 이상 Challenge 메일 교환
            Plan-->>Dev: 수정 반영 및 최종 계획 합의
        end
    else --plan 미지정
        alt 기존 계획 존재 시
            User->>Dev: 기존 계획서 로드 및 구현 지시
        else 계획 미존재 시
            User->>Dev: Self-planning 지시 (스스로 계획/설계 수립하여 구현)
        end
    end
    
    %% Execution
    User->>Dev: delegate-job (작업 지시)
    Dev-->>User: 구현 완료 (git diff 발생)
    
    %% Peer-Review Loop with Max-Loop constraint
    loop 최대 --max-loop 횟수 동안 반복 (기본 3회)
        alt 리뷰어 옵션 지정 시 (--reviewer or --all-reviewer)
            User->>Rev: delegate-job (정식 peer 코드 리뷰 위임)
            Rev-->>User: [VERDICT: PASS] 또는 [VERDICT: NOT PASS] 태그 리포트 제출
            alt 100% PASS 충족 시
                Note over User,Rev: 루프 즉시 탈출 (성공)
            else NOT PASS 검출 시
                User->>Dev: 피드백 전달 및 수정 지시 (피드백 난이도에 따라 Planner 우회 계획 갱신 적용)
            end
        else 리뷰어 미지정
            User->>Dev: Self-Review 지시 (자가 검증 및 자율 종결)
        end
    end

    %% Cleanup & Final Report
    alt --cleanup 지정 시
        User->>User: 임시 잡 폴더 청소
    end
    User-->>User: 최종 결과 요약 출력 및 마감
```

---

## 🛠️ 3. 개발 로직 및 안전 파싱 체크포인트

### 1) Verdict 판정 파서 안전 가이드라인 (Fail-Closed & Precedence)
*   **NOT PASS 우선권**: 리뷰 리포트 본문 내에 `[VERDICT: NOT PASS]` 가 단 한 번이라도 등장하면, `[VERDICT: PASS]` 문구 존재 여부와 상관없이 무조건 **NOT PASS**로 처리하여 오독 필터링을 방지합니다.
*   **Fail-Closed 기본 실패주의**: 태그 누락이나 malformed 리포트로 인해 두 토큰이 모두 스캔되지 않을 경우, 통과시키지 않고 **NOT PASS(실패)** 로 취급하여 루프 무한 기동 및 맹점 통과를 원천 차단합니다.
*   **템플릿 명시**: 리뷰어 위임 잡 발행 시, 최종 결과 요약 행에 정형화된 태그 `[VERDICT: PASS]` 혹은 `[VERDICT: NOT PASS]`를 리포트 본문 하단에 반드시 기재하도록 프롬프트 템플릿에 명시적으로 추가합니다.

### 2) 자가 리뷰 방지 가드 (Exclusion Rule)
*   `--all-reviewer` 혹은 `--reviewer` 목록을 소집할 때, 해당 작업을 수행한 대상 개발자 세션인 `$TARGET_AGENT` 는 **리뷰어 매핑 목록에서 강제로 배제(Exclude)** 하도록 파싱 쉘 스크립트에서 필터링을 적용합니다.

### 3) 쉘 예외 처리 및 대기 타임아웃 (Error Guard & Timeout)
*   `grep -oP` 나 `find | head` 시 매칭이 없을 때 `set -eo pipefail`에 의해 쉘 스크립트 전체가 비명횡사하지 않도록 `|| true` 가드 및 공백 체크문을 엄밀히 적용합니다.
*   `wait_for_job` 함수 실행 시 타임아웃 가드레일(`WAIT_TIMEOUT`, 기본값 3600초)을 명시적으로 설계하여 무한 루프 행(Hang) 현상을 차단합니다.