# Multi-Agent Mux Loop: CLI Option Redesign Final Architecture Consensus (Rev.4)

> **문서 상태**: Creator 재평가 반영 — `--target-agent` 완전 제거안 (Reviewer 판정 대기)  
> **합의 참여 에이전트**: `Grok` (Creator), `Claude` (Planner/Reviewer), `Cline` (Reviewer), `AGY` (Creator Lead)  
> **대상 컴포넌트**: `multi-agent-mux-loop` (`run_loop.sh`, `SKILL.md`, `deploy/INSTALL.md`, `tests/`)  
> **핵심 설계 모델**: Fail-Safe Orthogonality — 단계 스위치와 세션 식별자를 분리하고, 레거시 alias는 두지 않는다.

---

## 1. Rev.4 결정: `--target-agent` 제거

Rev.3는 `--target-agent`를 `--creator`의 영구 alias로 남겼다. Creator (`creator-grok-01`)는 그 선택을 철회한다.

**정본 플래그는 `--creator` 하나다. `--target-agent`는 파싱하지 않고, 전달되면 즉시 거부한다.**

### 1.1 제거하는 이유

Alias를 남기면 얻는 것은 저장소 안 문자열 5개의 무중단뿐이고, 비용은 파서 이중 변수·충돌 행렬·에러 문구 이중화·테스트 분기이다. Rev.2에서 지적한 “한 `case` 팔에 덮어쓰기” 버그는 그 이중 파서가 만든 구멍이다.

| 기준 | 영구 alias (Rev.3) | 완전 제거 (Rev.4) |
| :--- | :--- | :--- |
| 파서 | `CREATOR_OPT` + `TARGET_AGENT_OPT` + 같음/다름 분기 | `--creator) TARGET_AGENT="$2"` 한 줄 |
| 실패 모드 | 구현이 변수를 합치면 충돌을 침묵 덮어씀 | 충돌 상태 자체가 존재하지 않음 |
| in-repo 호출 | 3개 테스트 + `INSTALL.md` 예시 1개 + SKILL 예시 | 같은 파일을 `--creator`로 고치면 끝 |
| 외부 API | `run_loop.sh`는 배포된 공용 CLI가 아님 | 호환 공약이 필요 없음 |
| AGENTS.md | “요청되지 않은 유연성” | Simplicity First에 부합 |

in-repo 실측 호출부 (`--target-agent`):

- `tests/test_o3_scoped_guard.py` (2)
- `tests/test_o2_race_free_lock.py` (1)
- `tests/test_tier4_e2e.py` (1)
- `deploy/INSTALL.md` (1)

이 변경과 같은 커밋에서 `--creator`로 치환한다. alias 유지 비용이 치환 비용보다 크다.

### 1.2 `--target-agent`가 들어왔을 때

일반 `Unknown option`에 맡기지 않는다. 방금 없앤 이름에는 한 줄 힌트를 주고 종료한다. 값은 읽지 않는다. alias가 아니다.

```text
ERROR: --target-agent was removed. Use --creator <session> instead.
```

---

## 2. 설계 원칙

수사적 “3역할 완전 대칭”은 쓰지 않는다. 루프 라이프사이클이 비대칭이고, CLI는 그 비대칭을 그대로 드러낸다.

| 역할 | 라이프사이클 | CLI |
| :--- | :--- | :--- |
| **Planner** | Phase 1은 생략 가능 | `--plan` (단계) ⊥ `--planner <name>` (세션) |
| **Creator** | Phase 2는 항상 필요 | `--creator <name>` 필수. 단계 스위치 없음 |
| **Reviewer** | 없으면 Self-Review | `--reviewer A,B` 또는 `--all-reviewer` |

`--planner`가 `--plan`을 암시하지 않는다. 식별자가 제어 흐름을 바꾸지 않는다.

`--reviewer` + `--all-reviewer`는 기존대로 warn-and-precedence (`--all-reviewer` 우선). Creator 쪽 fail-fast와 다른 이유는 alias 충돌이 아니라 **기존 거버넌스 유지**이다.

역할 문자열 검사(`role`에 `creator`/`planner` 포함)는 이번 범위 밖이다. 현재 `--target-agent`도 등록·running만 본다. `--planner`만 역할 검사하면 비대칭이 된다. 복합 role `planner,reviewer`는 자동 탐색 시 지금처럼 substring 매칭으로 허용한다.

---

## 3. CLI 규격

| 역할 / 계층 | CLI 플래그 | 형태 | 필수 | 동작 |
| :--- | :--- | :---: | :---: | :--- |
| **Creator** | `--creator <name>` | Value | **필수** | 구현 세션. 내부 변수는 기존 `TARGET_AGENT`에 대입해 스크립트 잔여 경로를 건드리지 않는다 |
| **Planner** | `--plan` | Flag | 선택 | Phase 1 활성화 |
| | `--planner <name>` | Value | 선택 | Phase 1 세션. **`--plan`과 함께만**. 지정 시 `resolve_planner_session` 호출 금지 |
| | `--plan-talk N` | Int | 선택 | Planner ↔ Creator 챌린지 횟수 (기본 1). `--plan` 없으면 기존처럼 경고 후 무시 |
| **Reviewer** | `--reviewer "A,B"` | Value | 선택 | 지정 리뷰어 |
| | `--all-reviewer` | Flag | 선택 | running reviewer 전원, 만장일치 PASS |
| **공통** | `--task "<goal>"` | Value | **필수** | 작업 목표 |
| | `--max-loop M` | Int | 선택 | 교정 루프 상한 (기본 3, ≥1) |
| | `--max-rebut N` | Int | 선택 | 이터레이션당 반론 상한 (기본 1, 0이면 끔) |
| | `--verbose` | Flag | 선택 | 상세 로그 |
| | `--cleanup` | Flag | 선택 | 성공 시 `.mam/jobs/<id>` 임시 트리 삭제 |
| | `-h` / `--help` | Flag | 선택 | usage 후 종료 |
| **제거됨** | `--target-agent` | — | 거부 | 전용 에러 후 `exit 1`. 값 파싱 없음 |

`usage()` 첫 줄은 `--creator <session> --task <goal>`을 정본으로 적는다. `--target-agent`는 usage 옵션 목록에 올리지 않는다.

---

## 4. 호출 예시

### ① 풀 팀 (계획 + 지정 플래너 + 지정 리뷰어)

```bash
bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --creator creator-grok-01 \
  --plan --planner planner-reviewer-claude-01 \
  --reviewer reviewer-cline-01 \
  --task "새로운 분산 세션 동기화 엔진 구현"
```

### ② 플래너 자동 탐색 + 전체 리뷰어

```bash
bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --creator creator-agy-01 \
  --plan \
  --all-reviewer \
  --task "코어 라이브러리 리팩토링"
```

### ③ Creator 단독 (셀프 계획 + 셀프 리뷰)

```bash
bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --creator creator-grok-01 \
  --task "README.md 오타 수정 및 CLI 도움말 갱신"
```

레거시 `--target-agent` 예시는 삭제한다. 그 플래그는 더 이상 유효한 호출이 아니다.

---

## 5. 엣지 케이스

| 상황 | 결과 | 메시지 / 처리 |
| :--- | :--- | :--- |
| `--planner`만 있고 `--plan` 없음 | Fail-fast, freeze 전 `echo`, `exit 1` | `ERROR: --planner was specified without --plan.` + `--plan --planner` 사용 예 |
| `--target-agent` 전달 | Fail-fast, freeze 전 `echo`, `exit 1` | `ERROR: --target-agent was removed. Use --creator <session> instead.` |
| `--creator` 또는 `--task` 누락 | Fail-fast, freeze 전 | `ERROR: --creator and --task are mandatory fields.` |
| `--planner <name>` 미등록 | Fail-fast, freeze 후 `log_error` | `specified planner session '<name>' is not registered in the session registry.` |
| `--planner <name>` 등록됐으나 running 아님 | Fail-fast, freeze 후 `log_error` | `specified planner session '<name>' is not running (current status: '<status>').` |
| `--plan`만 있고 `--planner` 없음 | 기존 자동 탐색 | running 이고 role에 `planner`가 있는 첫 세션. 없으면 기존 에러 |
| `--reviewer` + `--all-reviewer` | 기존 유지 | `log_warn` 후 `--all-reviewer` 우선 |
| `--plan-talk` 정수 아님 / `--max-loop` ≤0 / `--max-rebut` 비정수 | 기존 유지 | freeze 전 `echo`, `exit 1` |

`--creator`와 `--planner`의 세션 동일 여부, 역할 문자열 일치 여부는 검사하지 않는다 (현행과 동일).

---

## 6. 구현 블루프린트

Freeze 전 파서 오류는 원시 `echo` (B-13: `log_*`는 freeze 이후에만 정의됨). 세션 레지스트리 조회는 freeze 이후 `log_error` / `log_warn`.

### 6.1 Pre-freeze 파서

기존 정수 검사·그 외 플래그는 보존한다. 추가/변경은 다음뿐이다.

```bash
# --creator replaces --target-agent. Internal name TARGET_AGENT is unchanged.
# --planner) PLANNER_SESSION_OVERRIDE="$2"; shift 2 ;;

case "$1" in
  --creator) TARGET_AGENT="$2"; shift 2 ;;
  --target-agent)
    echo "ERROR: --target-agent was removed. Use --creator <session> instead." >&2
    exit 1
    ;;
  --planner) PLANNER_SESSION_OVERRIDE="$2"; shift 2 ;;
  # ... existing cases unchanged ...
esac

if [ -z "$TARGET_AGENT" ] || [ -z "$TASK" ]; then
  echo "ERROR: --creator and --task are mandatory fields." >&2
  usage
fi

if [ -n "${PLANNER_SESSION_OVERRIDE:-}" ] && [ "$PLAN_MODE" = false ]; then
  echo "ERROR: --planner was specified without --plan." >&2
  echo "To enable planning, include the --plan flag:" >&2
  echo "  run_loop.sh --creator <creator> --plan --planner <planner> --task \"...\"" >&2
  exit 1
fi
```

두 개의 Creator 변수도, 충돌 비교도 없다.

### 6.2 Post-freeze 플래너 결정

`--planner`가 있으면 `resolve_planner_session`을 호출하지 않는다.

```bash
if [ "$PLAN_MODE" = true ]; then
  if [ -n "${PLANNER_SESSION_OVERRIDE:-}" ]; then
    PLANNER_SESSION="$PLANNER_SESSION_OVERRIDE"
    # same two-step check as TARGET_AGENT: missing vs not-running
  else
    PLANNER_SESSION=$(resolve_planner_session)
    if [ -z "$PLANNER_SESSION" ]; then
      log_error "Planner mode enabled (--plan) but no running session with a 'planner' role was found."
      exit 1
    fi
  fi
fi
```

명시 `--planner` 검증은 기존 TARGET_AGENT 조회와 같은 패턴을 재사용한다 (`load_state_json`, 이름 일치, `status`). 역할 필드는 보지 않는다.

### 6.3 문서·테스트 (같은 변경에 포함)

문서:

- `run_loop.sh` `usage()` — `--creator` 정본, `--target-agent` 미기재
- `.agents/skills/multi-agent-mux-loop/SKILL.md` — CLI 표·예시
- `deploy/INSTALL.md` — 대표 예시를 `--creator`로 치환

테스트 위치: `tests/test_tier1_unit.py`에 넣지 않는다. 그 파일은 `run_loop` 스위트가 아니다.

Pre-freeze (프로세스만 기동, 락/레지스트리 불필요). `test_o1_rebuttal.py`와 같은 방식으로 `run_loop.sh`를 직접 호출한다. 신규 파일도 허용한다.

- `--creator` + `--task` 누락 → `exit 1`
- `--planner` without `--plan` → `exit 1`, 메시지에 `--plan` 안내
- `--target-agent` → `exit 1`, `was removed` / `Use --creator`
- `--help`에 `--creator` 있고 `--target-agent`는 옵션 목록에 없음

기존 `--target-agent` 호출 치환 (동작 유지, 플래그만 변경):

- `tests/test_o3_scoped_guard.py`
- `tests/test_o2_race_free_lock.py`
- `tests/test_tier4_e2e.py`

Post-freeze 샌드박스 (레지스트리 있는 기존 픽스처):

- `--plan --planner <running>` 이 자동 탐색을 건너뛰고 그 세션을 쓰는지
- 미등록 `--planner` / 비-running `--planner` 각각 다른 에러

---

## 7. 이번 범위에 넣지 않는 것

- `--creator` / `--planner` 역할 필드 검사 (후속, 넣을 거면 둘 다)
- `--planner`가 `--plan`을 암시
- `--all-planner`
- `--reviewer`+`--all-reviewer`를 fail-fast로 승격
- `TARGET_AGENT` 내부 식별자 전면 rename
- 한글 프롬프트 → `brief.md` 이관, 셀프 리뷰 교정 잡 등 루프 본체 다른 과제

---

## 8. Reviewer에게 묻는 판정 포인트

1. `--target-agent` 완전 제거 (전용 에러, 값 미파싱)를 수용하는가, Rev.3 영구 alias로 되돌릴 것인가.
2. 내부 변수명 `TARGET_AGENT` 유지를 수용하는가.
3. 섹션 6 체크리스트가 구현 단위로 충분한가.

`[VERDICT: PASS]`는 위 세 항에 이견이 없을 때만 발행한다. alias 복원을 원하면 근거와 함께 `[VERDICT: NOT PASS]`로 돌린다.