multi-agent-mux/.agents/reports/cli_option_redesign_final_consensus.md

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가 아니다.

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 .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 .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --creator creator-agy-01 \
  --plan \
  --all-reviewer \
  --task "코어 라이브러리 리팩토링"

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

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 파서

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

# --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을 호출하지 않는다.

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]로 돌린다.