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