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

# 🏛️ Definitive Architecture Consensus & Implementation Specification: `multi-agent-mux-loop` CLI Redesign

- **Author / Synthesist**: `creator-agy-01` (Worker / Creator Team Leader)
- **Contributors**: `planner-reviewer-claude-01`, `reviewer-cline-01`, `grok`
- **Job ID**: `9f2ae7bd`
- **Version**: Rev.3 (Final Consensus — Incorporating Grok's Critique & All Reviewer Findings)
- **Supersedes**: Supersedes Section 4 & Edge Case 3.2 of `cli_redesign_opinion.md` and extends `cli_redesign_debate_consensus.md`.

---

## 1. Executive Summary & Core Paradigm

The Multi-Agent Mux team has converged on the **Orthogonal with Fail-Safe Validation** architecture for `multi-agent-mux-loop` (`run_loop.sh`).

### Core Principles:
1. **Separation of Phase Switch vs. Target Identity**:
   - **Phase Switches** (`--plan`, `--all-reviewer`) control *which phases execute*.
   - **Target Identities** (`--planner`, `--creator`, `--reviewer`) control *which sessions execute those phases*.
2. **Fail-Fast Safety (No Magic, No Silent Drops)**:
   - Passing an identity without its corresponding phase switch (e.g., `--planner <name>` without `--plan`) immediately **fails fast with exit code 1**, providing an actionable error message and exact remediation syntax.
3. **Role Lifecycle Alignment**:
   - **Planner Tier**: Optional phase (`--plan` to activate, `--planner` to bind, default: Creator self-planning).
   - **Creator Tier**: Mandatory execution (`--creator` to bind, with `--target-agent` as 100% backward-compatible alias).
   - **Reviewer Tier**: Optional peer verification (`--reviewer` for targeted list, `--all-reviewer` for all active reviewers, default: Creator self-review).

---

## 2. Exhaustive Resolution of Grok's Critique & Spec Gaps

### 2.1 Parser Variable Separation (Conflict Detection Fix)
- **Issue**: Parsing `--creator|--target-agent)` into a single variable in the `case` loop overwrites the first flag, making conflicting input (`--creator sess-A --target-agent sess-B`) undetectable.
- **Fix**: Parse into two distinct variables: `CREATOR_OPT=""` and `TARGET_AGENT_OPT=""`.
- **Pre-Freeze Resolution**: Check for conflicts immediately after the `while` loop using raw `echo` (before B-13 freeze snapshot re-exec):
  ```bash
  if [ -n "$CREATOR_OPT" ] && [ -n "$TARGET_AGENT_OPT" ]; then
    if [ "$CREATOR_OPT" != "$TARGET_AGENT_OPT" ]; then
      echo "ERROR: Conflicting creator sessions specified via --creator ('$CREATOR_OPT') and --target-agent ('$TARGET_AGENT_OPT')."
      exit 1
    fi
  fi
  TARGET_AGENT="${CREATOR_OPT:-$TARGET_AGENT_OPT}"
  ```

### 2.2 Spec Gap (a): Explicit Bypass of Planner Auto-Discovery
- **Specification**: When `--planner <name>` is provided, `PLANNER_SESSION` is assigned directly from the CLI argument, completely bypassing `resolve_planner_session`.
- **Logic**:
  ```bash
  if [ -n "$PLANNER_SESSION_OVERRIDE" ]; then
    PLANNER_SESSION="$PLANNER_SESSION_OVERRIDE"
  else
    PLANNER_SESSION=$(resolve_planner_session)
  fi
  ```

### 2.3 Spec Gap (b): 2-Branch Session Liveness & Registration Validation
- **Specification**: Post-freeze validation for `PLANNER_SESSION` mirrors `TARGET_AGENT` validation with distinct error messages:
  ```bash
  if [ "$PLAN_MODE" = true ]; then
    if [ -z "$PLANNER_SESSION" ]; then
      log_error "Planner mode enabled (--plan) but no running session with a 'planner' role was found."
      exit 1
    fi

    PLANNER_STATUS=$(MAM_STATE_JSON="$(load_state_json)" PLANNER="$PLANNER_SESSION" python3 -c "
  import os, json
  d = json.loads(os.environ.get('MAM_STATE_JSON', '{}'))
  target = os.environ.get('PLANNER')
  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 "Planner agent session '$PLANNER_SESSION' is not registered in the session registry."
      exit 1
    elif [ "$PLANNER_STATUS" != "running" ]; then
      log_error "Planner agent session '$PLANNER_SESSION' is not running (current status: '$PLANNER_STATUS'). Please start it first."
      exit 1
    fi
  ```

### 2.4 Spec Gap (c): Substring Matching for Composite Roles
- **Specification**: Role verification must support composite roles (e.g. `planner,reviewer` or `creator,planner`) using lowercase substring checks:
  ```python
  if 'planner' in (s.get('role') or '').lower():
      # Valid planner role match
  ```
  If a session with a non-planner role (e.g. strictly `role: creator`) is explicitly targeted via `--planner`, emit an advisory warning (`log_warn "Session '$PLANNER_SESSION' has role '$PLANNER_ROLE' but was assigned as Planner"`) and proceed.

### 2.5 Spec Gap (d): Test Suite Division (Pre-Freeze vs. Sandbox)
- **Tier 1 Unit Tests (`tests/test_tier1_unit.py`)**:
  - Direct shell CLI parser tests (verifying exit codes 0 vs 1 for `--creator` + `--target-agent` conflict, `--planner` without `--plan`, invalid integer inputs).
- **Tier 2 Component Tests (`tests/test_tier2_component.py`)**:
  - Isolated multi-agent state tests using `mam_sandbox` (mocking `load_state_json`, planner/creator/reviewer job registration, 3-tier feedback loops).

### 2.6 Spec Gap (e): Documentation & Formatting Scope
- Include `deploy/INSTALL.md` in the rollout update list alongside all `SKILL.md` documents, `MULTI_AGENT_RULES.md`, and slash command help.
- Clean all quotation escaping in documentation examples.

---

## 3. Production-Ready `run_loop.sh` Reference Implementation

```bash
# ===========================================================================
# 1. Configuration Defaults
# ===========================================================================
PLAN_MODE=false
PLAN_TALK_TURNS=1
ALL_REVIEWERS=false
MAX_LOOP=3
MAX_REBUT=1
VERBOSE=false
CLEANUP=false
CREATOR_OPT=""
TARGET_AGENT_OPT=""
PLANNER_SESSION_OVERRIDE=""
TASK=""
REVIEWER_LIST=""

# ===========================================================================
# 2. CLI Option Parser (Pre-Freeze Safe)
# ===========================================================================
while [[ "$#" -gt 0 ]]; do
  case "$1" in
    --plan)
      PLAN_MODE=true
      shift ;;
    --planner)
      PLANNER_SESSION_OVERRIDE="$2"
      shift 2 ;;
    --creator)
      CREATOR_OPT="$2"
      shift 2 ;;
    --target-agent) # Backward-compatible alias
      TARGET_AGENT_OPT="$2"
      shift 2 ;;
    --reviewer)
      if [ -n "$REVIEWER_LIST" ]; then
        REVIEWER_LIST="${REVIEWER_LIST},$2"
      else
        REVIEWER_LIST="$2"
      fi
      shift 2 ;;
    --all-reviewer)
      ALL_REVIEWERS=true
      shift ;;
    --plan-talk)
      if [[ ! "$2" =~ ^[0-9]+$ ]]; then
        echo "ERROR: --plan-talk requires a positive integer."
        exit 1
      fi
      PLAN_TALK_TURNS="$2"
      shift 2 ;;
    --max-loop)
      if [[ ! "$2" =~ ^[0-9]+$ ]] || [ "$2" -le 0 ]; then
        echo "ERROR: --max-loop requires a positive non-zero integer."
        exit 1
      fi
      MAX_LOOP="$2"
      shift 2 ;;
    --max-rebut)
      if [[ ! "$2" =~ ^[0-9]+$ ]]; then
        echo "ERROR: --max-rebut requires a non-negative integer."
        exit 1
      fi
      MAX_REBUT="$2"
      shift 2 ;;
    --verbose)
      VERBOSE=true
      shift ;;
    --cleanup)
      CLEANUP=true
      shift ;;
    --task)
      TASK="$2"
      shift 2 ;;
    -h|--help)
      usage ;;
    *)
      echo "Unknown option: $1"
      usage ;;
  esac
done

# ===========================================================================
# 3. Pre-Freeze Validation & Resolution (Uses raw echo)
# ===========================================================================
# Fail-fast on --planner without --plan
if [ -n "$PLANNER_SESSION_OVERRIDE" ] && [ "$PLAN_MODE" = false ]; then
  echo "ERROR: --planner was specified without --plan."
  echo "To enable the planning phase with this planner, please include the --plan flag:"
  echo "  run_loop.sh --creator <creator> --plan --planner $PLANNER_SESSION_OVERRIDE --task \"$TASK\""
  exit 1
fi

# Resolve Creator & detect conflicts
if [ -n "$CREATOR_OPT" ] && [ -n "$TARGET_AGENT_OPT" ]; then
  if [ "$CREATOR_OPT" != "$TARGET_AGENT_OPT" ]; then
    echo "ERROR: Conflicting creator sessions specified via --creator ('$CREATOR_OPT') and --target-agent ('$TARGET_AGENT_OPT')."
    exit 1
  fi
fi

TARGET_AGENT="${CREATOR_OPT:-$TARGET_AGENT_OPT}"

if [ -z "$TARGET_AGENT" ] || [ -z "$TASK" ]; then
  echo "ERROR: --creator (or --target-agent) and --task are mandatory fields."
  usage
fi
```

---

## 4. Summary Matrix of Supported Invocations

| Scenario | Command Line | Execution Behavior |
| :--- | :--- | :--- |
| **Creator Self-Planning (Default)** | `run_loop.sh --creator c1 --task "..."` | No Phase 1. Creator plans & implements. Self-review. |
| **Auto-Discovered Planner** | `run_loop.sh --creator c1 --plan --task "..."` | Phase 1 runs with auto-discovered planner. |
| **Targeted Planner** | `run_loop.sh --creator c1 --plan --planner p1 --task "..."` | Phase 1 runs with `p1` explicitly. |
| **Fail-Fast Misconfiguration** | `run_loop.sh --creator c1 --planner p1 --task "..."` | **Exits 1 immediately**: prompts user to add `--plan`. |
| **Targeted Reviewers** | `run_loop.sh --creator c1 --reviewer "r1,r2" --task "..."` | Phase 2 -> Phase 3 with reviewers `r1`, `r2`. |
| **Repeated Reviewer Flags** | `run_loop.sh --creator c1 --reviewer r1 --reviewer r2 --task "..."` | Appends `r1,r2` -> runs review with both. |
| **Full 3-Tier Suite** | `run_loop.sh --creator c1 --plan --planner p1 --all-reviewer --task "..."` | Full 3-tier orchestration with unanimous review. |
| **Legacy Invocations** | `run_loop.sh --target-agent c1 --plan --task "..."` | 100% backward-compatible execution. |

---

## 5. Verdict & Status

The team is in **complete consensus (100% Unanimous PASS)** on this architecture. All 5 spec gaps and the parser conflict detection bug identified by Grok are fully resolved.