docs(mux-loop): add multi-agent architecture consensus & review reports for CLI redesign
This commit is contained in:
@@ -0,0 +1,235 @@
|
||||
# 🏛️ 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.
|
||||
Reference in New Issue
Block a user