feat(mux-loop): redesign role CLI flags with --creator and --planner, drop --target-agent

- Replace '--target-agent' with mandatory '--creator <session>' flag
- Add explicit rejection error for legacy '--target-agent'
- Add '--planner <session>' flag with fail-fast check when '--plan' is missing
- Implement 2-branch session validation ('is not registered' vs 'is not running')
- Update in-repo references in hooks, SKILL.md, INSTALL.md, and tests
- Add tests/test_loop_cli.py with 9 unit/contract tests

.agents/skills/multi-agent-mux-loop/SKILL.md

@@ -26,7 +26,7 @@ metadata:
 ## What this skill does
 
 Run an autonomous planning-execution-review loop using multiple agents (Planner, Creator, Reviewers) in the workspace. It supports:
-- **Collaborative Planning** (`--plan` and `--plan-talk N`): Planner designs the solution, Creator challenges the plan for N turns to resolve edge cases, then implementation starts.
+- **Collaborative Planning** (`--plan`, optional `--planner <session>`, and `--plan-talk N`): Planner designs the solution, Creator challenges the plan for N turns to resolve edge cases, then implementation starts. `--planner` selects the planner session; omit it to auto-resolve the first running planner.
 - **Creator Self-Planning & Development** (default without `--plan`): Planner 에이전트에게 계획 작성을 위임하지 않고, 기존에 승격된 계획서가 있다면 이를 로드하여 코드를 구현하며, 계획서가 존재하지 않는 경우 작업자(Creator: developer/writer)가 스스로 구현 계획 및 설계 수립을 포함한 개발 전 과정을 직접 진행합니다.
 - **Targeted Peer-Review** (`--reviewer`): Runs custom-selected reviewer agents to verify code changes.
 - **Total Peer-Review** (`--all-reviewer`): Enforces a unanimous PASS verdict from all registered reviewer sessions.
@@ -163,11 +163,14 @@ sequenceDiagram
 | 워크플로우 단계 | 해당 CLI 옵션 | 설명 |
 | :--- | :--- | :--- |
 | **Phase 1: Planning** | `--plan` | Planner 에이전트를 기동하여 최초 계획 작성을 강제합니다. (옵션을 지정하지 않을 경우 새 계획서 작성을 생략하며, 기존 계획서가 있는 경우 이를 로드하고, 없는 경우 Creator가 직접 계획 및 설계를 수립하여 즉시 구현에 착수합니다.) |
+| **Phase 1: Planner session** | `--planner <name>` | 계획 단계를 수행할 세션을 명시합니다. **`--plan`과 함께만** 사용합니다. 생략 시 running planner를 자동 탐색합니다. |
 | **Phase 1: Debate** | `--plan-talk N` | Planner와 Creator가 상호 대화식 챌린지 루프를 `N`회 돌며 계획을 교차 정제합니다. |
-| **Phase 2: Execution** | (기본값) | `--target-agent`로 명시한 주 작업 세션에 코딩 태스크를 주입합니다. |
+| **Phase 2: Execution** | `--creator <name>` | 코드를 구현할 Creator 세션에 코딩 태스크를 주입합니다. (필수) |
 | **Phase 3: Review** | `--reviewer "A,B"` | 지정된 리뷰어 세션 리스트(`A`, `B` 등)에 교차 Peer Review를 위임합니다. |
 | **Phase 3: Consensus** | `--all-reviewer` | 레지스트리에 등록된 모든 active 리뷰어 세션을 자동으로 수집하여 리뷰를 돌립니다. (`--reviewer` 옵션과는 상호 배타적이며, 지정/수집된 모든 리뷰어의 PASS 만장일치가 항상 필요합니다.) |
 | **Iterative Loop** | `--max-loop M` | NOT PASS 판정 시 최대 `M`회까지 Creator가 자체 수정합니다. `--plan` 모드에서 리뷰어가 리포트에 `[ESCALATE: PLANNER]` 태그를 남기면 설계 변경 수준으로 판단하여 Planner에게 계획 갱신을 위임합니다 (린트는 리뷰어가 검토 관점 중 하나로 확인할 뿐, 별도의 자동 게이트는 아닙니다). |
+| **Rebuttal** | `--max-rebut N` | 이터레이션당 Creator 반론 횟수 (기본 1, `0`이면 끔). |
+| **Control** | `--verbose` / `--cleanup` | 상세 로그 / 성공 시 임시 job 디렉터리 삭제. |
 
 ---
 
@@ -176,26 +179,27 @@ sequenceDiagram
 ```bash
 # 1. Creator Self-Planning & Development + Self-review (direct task execution using existing promoted plan or Creator's own self-plan)
 bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
-  --target-agent "<creator-session-name>" \
+  --creator "<creator-session-name>" \
   --task "Fix typo in deploy/README.md"
 
 # 2. Collaborative planning + Targeted Reviewers + Safety limits
 #    (실전 자율 루프 기동의 표준 패턴 — 리뷰어 2인 지정 + 최대 3회 반복)
 bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
+  --creator "<creator-session-name>" \
   --plan \
+  --planner "<planner-session-name>" \
   --plan-talk 1 \
   --reviewer "<reviewer-session-name-1>,<reviewer-session-name-2>" \
   --max-loop 3 \
   --verbose \
-  --target-agent "<creator-session-name>" \
   --task "Refactor the session backup mechanism to handle NFS flock"
 
 # 3. Total validation (all reviewers must PASS)
 bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
+  --creator "<creator-session-name>" \
   --all-reviewer \
   --max-loop 5 \
   --cleanup \
-  --target-agent "<creator-session-name>" \
   --task "Close CI shellcheck coverage gaps"
 ```
 

.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh

@@ -31,12 +31,15 @@ CLEANUP=false
 TARGET_AGENT=""
 TASK=""
 REVIEWER_LIST=""
+PLANNER_SESSION_OVERRIDE=""
 
 # Print usage instructions
 usage() {
-  echo "Usage: $0 [options] --target-agent <agent-session-name> --task <goal-text>"
+  echo "Usage: $0 [options] --creator <agent-session-name> --task <goal-text>"
   echo "Options:"
+  echo "  --creator <name>       Creator session that implements the task (required)"
   echo "  --plan                 Enable Planner agent intervention & design phase"
+  echo "  --planner <name>       Planner session (requires --plan; default: auto-resolve)"
   echo "  --plan-talk N          Planner-Creator discussion limit turns (default: 1)"
   echo "  --reviewer \"A,B\"       Targeted reviewer session name list (comma-separated)"
   echo "  --all-reviewer         Enforce PASS verdict from all active reviewer sessions"
@@ -73,7 +76,12 @@ while [[ "$#" -gt 0 ]]; do
       MAX_REBUT="$2"; shift 2 ;;
     --verbose) VERBOSE=true; shift ;;
     --cleanup) CLEANUP=true; shift ;;
-    --target-agent) TARGET_AGENT="$2"; shift 2 ;;
+    --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 ;;
     --task) TASK="$2"; shift 2 ;;
     -h|--help) usage ;;
     *) echo "Unknown option: $1"; usage ;;
@@ -85,10 +93,17 @@ done
 REBUT_TOTAL_BUDGET=$((MAX_REBUT * MAX_LOOP))
 
 if [ -z "$TARGET_AGENT" ] || [ -z "$TASK" ]; then
-  echo "ERROR: --target-agent and --task are mandatory fields."
+  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
+
 # --- B-13 Stage 2: freeze the runtime before the loop can be edited under us ---
 # bash keeps reading a running script from disk by byte offset, so a worker that
 # edits .agents/skills/ mid-loop can break this very file (measured: even a valid
@@ -351,15 +366,35 @@ elif [ "$TARGET_STATUS" != "running" ]; then
   exit 1
 fi
 
-PLANNER_SESSION=$(resolve_planner_session)
-log_info "Resolved Planner session: $PLANNER_SESSION"
-
-if [ "$PLAN_MODE" = true ]; then
-  if [ -z "$PLANNER_SESSION" ]; then
+if [ -n "${PLANNER_SESSION_OVERRIDE:-}" ]; then
+  # Explicit --planner skips auto-resolve. Pre-freeze already required --plan.
+  PLANNER_SESSION="$PLANNER_SESSION_OVERRIDE"
+  PLANNER_STATUS=$(MAM_STATE_JSON="$(load_state_json)" TARGET="$PLANNER_SESSION" python3 -c "
+import os, json
+d = json.loads(os.environ.get('MAM_STATE_JSON', '{}'))
+target = os.environ.get('TARGET')
+status = ''
+for s in d.get('herdr_sessions', []):
+    if s.get('name') == target:
+        status = s.get('status')
+        break
+print(status)
+")
+  if [ -z "$PLANNER_STATUS" ]; then
+    log_error "Specified planner session '$PLANNER_SESSION' is not registered in the session registry."
+    exit 1
+  elif [ "$PLANNER_STATUS" != "running" ]; then
+    log_error "Specified planner session '$PLANNER_SESSION' is not running (current status: '$PLANNER_STATUS')."
+    exit 1
+  fi
+else
+  PLANNER_SESSION=$(resolve_planner_session)
+  if [ "$PLAN_MODE" = true ] && [ -z "$PLANNER_SESSION" ]; then
     log_error "Planner mode enabled (--plan) but no running session with a 'planner' role was found."
     exit 1
   fi
 fi
+log_info "Resolved Planner session: $PLANNER_SESSION"
 
 CURRENT_PLAN=""
 CREATED_JOBS=()