tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: archive planning/review reports and issue report from previous multi-agent-mux-loop runs

Browse Source
This commit is contained in:
Godopu
2026-07-17 21:33:31 +09:00
parent b45649de76
commit 31ca11c57d
6 changed files with 603 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-cline-loop-refactor.md
+95
View File
@@ -0,0 +1,95 @@
# ✅ Peer Review Report: multi-agent-mux-loop SKILL.md & run_loop.sh Refactoring (Commits 52c270e, f85fdfc, 6c90342)
**Job**: `47d1dce6` · **Reviewer**: Reviewer B (Cline, `canary-projects-multi-agent-mux-reviewer-cline`)
**Review Targets**:
- Commit `52c270e` — "docs(skill): update multi-agent-mux-loop SKILL manual to reflect skipped planning mode when --plan is omitted"
- Commit `f85fdfc` — "docs(skill): genericize multi-agent-mux-loop SKILL manual by replacing hardcoded agent session names with placeholders"
- Commit `6c90342` — "fix(skill): resolve hardcoded planner session name and plan file paths dynamically in run_loop.sh"
**Prior Context**: PTY 리뷰 5회차 완료 (cc09bae5 PASS). 본 잡은 multi-agent-mux-loop 오케스트레이션 스킬의 문서/스크립트 리팩토링 리뷰.
**Plan Reference**: `.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final.md` (Rev.3)
**Review Scope**: 브리프가 요청한 "잠재적인 문법 오류나 셸 스크립트 오작동 여부 꼼꼼한 검토"
**Method**: 라인 단위 diff 분석 + `bash -n` 문법 검사 + `shellcheck` 정적 분석 + Python 임베디드 코드 4시나리오 런타임实证 + Self-Planning Mode bash 로직 3시나리오 `set -euo pipefail` 시뮬레이션 + mermaid 다이어그램 문법 검증 + 플레이스홀더 일관성 교차 검증
---
## 1. 커밋 개요
3개 커밋이 multi-agent-mux-loop 오케스트레이션 스킬의 문서와 스크립트를 리팩토링:
| 커밋 | 파일 | 변경량 | 내용 |
|------|------|--------|------|
| 52c270e | SKILL.md | 문서 | 계획 생략 모드 설명 업데이트 + mermaid 시퀀스 다이어그램 "Use Existing Plan (No --plan)" 분기 추가 |
| f85fdfc | SKILL.md | 문서 | 하드코딩 에이전트명 → 범용 플레이스홀더(`<creator-session-name>`, `<reviewer-session-name>`) 정제 |
| 6c90342 | run_loop.sh | +5/-3 | 하드코딩 fallback 플래너 세션명/계획 파일 경로 → 동적 `$PLANNER_SESSION` 변수 기반 리팩토링 |
---
## 2. 핵심 검증: run_loop.sh 셸 스크립트 (6c90342)
### 2.1 정적 분석 — ✅ 통과
| 검증 | 방법 | 결과 |
|------|------|------|
| bash 문법 검사 | `bash -n run_loop.sh` | ✅ SYNTAX OK |
| shellcheck (기본) | `shellcheck run_loop.sh` | ✅ EXIT 0 (경고/에러 전무) |
| shellcheck (-x 외부 소스 제외) | `shellcheck -x -S warning run_loop.sh` | ✅ EXIT 0 |
| shellcheck 버전 | 0.11.0 | 최신 분석 도구 |
**평가**: ✅ 셸 스크립트 정적 분석 완벽 통과. 문법 오류, 미정의 변수, 인용 오류, 조건부 파이프라인 등 shellcheck가 감지할 수 있는 모든 결함이 전무.
### 2.2 변경 1: `resolve_planner_session` 함수 (라인 185 영역)
**diff**:
```diff
-planner = 'canary-projects-multi-agent-mux-planner-reviewer-claude'
+planner = ''
for s in d.get('tmux_sessions', []):
if 'planner' in s.get('role', ''):
planner = s.get('name')
```
**분석**: 하드코딩된 플래너 세션명을 빈 문자열 초기값으로 변경. 이후 루프가 `tmux_sessions` 배열에서 `role`에 'planner'가 포함된 세션을 동적으로 검색하여 할당. 찾지 못하면 빈 문자열 반환.
**Python 임베디드 코드 런타임实证 (4시나리오)**:
| 시나리오 | 입력 MAM_STATE_JSON | 출력 | 기대 | 결과 |
|----------|---------------------|------|------|------|
| 1. 플래너 발견 | `{tmux_sessions:[{name:test-creator,role:creator},{name:test-planner-xyz,role:planner}]}` | `test-planner-xyz` | 동적 세션명 | ✅ |
| 2. 플래너 없음 | `{tmux_sessions:[{name:test-creator,role:creator}]}` | ``(빈) | 빈 문자열 | ✅ |
| 3. 빈 상태 | `{}` | ``(빈) | 빈 문자열 | ✅ |
| 4. env var 없음 | unset | ``(빈) | 빈 문자열 | ✅ |
**평가**: ✅ Python 임베디드 코드가 4가지 시나리오에서 모두 올바르게 동작. 동적 세션명 할당 및 빈 문자열 안전 반환 확인.
### 2.3 변경 2: Self-Planning Mode 계획 파일 로드 (라인 312 영역)
**diff**:
```diff
- EXISTING_PLAN_FILE=".agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final.md"
- if [ -f "$EXISTING_PLAN_FILE" ]; then
+ EXISTING_PLAN_FILE=""
+ if [ -n "$PLANNER_SESSION" ]; then
+ EXISTING_PLAN_FILE=".agents/reports/$PLANNER_SESSION/report-final.md"
+ fi
+ if [ -n "$EXISTING_PLAN_FILE" ] && [ -f "$EXISTING_PLAN_FILE" ]; then
```
**분석**: 하드코딩된 경로를 `$PLANNER_SESSION` 동적 변수 기반 경로로 변경. 2단계 가드 추가:
1. `[ -n "$PLANNER_SESSION" ]` — 빈 세션명이면 경로 구성 스킵
2. `[ -n "$EXISTING_PLAN_FILE" ] && [ -f "$EXISTING_PLAN_FILE" ]` — 빈 경로이거나 파일이 없으면 로드 스킵
**변수 할당 흐름 추적**:
- `PLANNER_SESSION`는 라인 211에서 `resolve_planner_session()` 호출로 할당 — Self-Planning Mode(라인 312) **이전**에 실행 ✅
- `CURRENT_PLAN`는 라인 213에서 `CURRENT_PLAN=""`로 초기화 — `set -u` (nounset) 오류 방지 ✅
- 라인 335: `if [ -n "$CURRENT_PLAN" ]` — 빈 문자열이면 false → `EXECUTION_PROMPT`에 계획서 미포함 ✅
- 라인 543: `if [ "$PLAN_MODE" = true ] && [ -n "${CURRENT_PLAN:-}" ]` — `${CURRENT_PLAN:-}` 기본값 확장으로 `set -u` 추가 방어 ✅
**Self-Planning Mode bash 로직 시뮬레이션 (3시나리오, `set -euo pipefail` 하)**:
| 시나리오 | PLANNER_SESSION | 동작 | CURRENT_PLAN | 결과 |
|----------|-----------------|------|--------------|------|
| 1. 실제 플래너 (파일 존재) | `canary-...-planner-reviewer-claude` | 계획 로드 | 2220자 | ✅ |
| 2. 빈 문자열 | `` | 파일 로드 스킵 | 0자 | ✅ |
| 3. 다른 플래너 (파일 없음) | `some-other-planner` | 파일 없음 스킵 | 0자 | ✅ |
**평가**: ✅ `set -euo pipefail` (특히 `set -u` nounset) 하에서 3가지 시나리오 모두 에러 없이 통과. 변수 안전성 확보. 2단계 가드 로직이 빈 세션명/존재하지 않는 파일을 올바르게 처리.
.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-cline-m2.md
+138
View File
@@ -0,0 +1,138 @@
# ✅ Peer Review Report: M2 PTY _exit Syscall Symbol Correction (Commit f0e2bd2)
**Job**: `cc09bae5` · **Reviewer**: Reviewer B (Cline, `canary-projects-multi-agent-mux-reviewer-cline`)
**Review Target**: Commit `f0e2bd2` — "fix(ui): correct libc symbol lookup for direct _exit syscall to achieve async-signal-safety"
**Prior Reviews**:
- Job `66ec158f` (b7901bc) → 3 BLOCKING 결함 지적
- Job `fcf4c9d0` (f52f6eb) → DEFECT 1/2 해결, DEFECT 3 미해결
- Job `7448cb2f` (7781e79) → async-signal-safety/waitpid 해결, DEFECT 3 미해결 (3회차)
- Job `ef0b32ff` (7f1a7e5) → **DEFECT 3 해결 (4회차) + 모든 결함 PASS** — 본 커밋은 ef0b32ff 리뷰의 NON-BLOCKING 관찰 #1 정밀 수정
**Plan Reference**: `.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final.md` (Rev.3, §6.7 PTY 메커니즘 / §10 DoD)
**Review Scope**: 브리프가 명시한 `cExit` lookup 심볼 오타 수정 (`'exit'` → `'_exit'`) 검증 + 회귀 확인
**Method**: 라인 단위 diff 분석 + `dart analyze`/`flutter analyze`/`dart test` + **`_exit` 심볼 glibc resolve实证** + TMUX env 격리 회귀实证
---
## 1. 커밋 개요
커밋 `f0e2bd2`는 이전 리뷰(ef0b32ff)의 NON-BLOCKING 관찰 #1을 정밀 수정. 1개 파일, +1/-1행 (단일 라인 변경).
**변경 내용** (`pty_session.dart:111`):
```diff
- final cExit = libc.lookupFunction<_exit_c, _exit_dart>('exit');
+ final cExit = libc.lookupFunction<_exit_c, _exit_dart>('_exit');
```
---
## 2. 수정 항목 교차 검증
### 2.1 이전 리뷰 관찰 (ef0b32ff, NON-BLOCKING #1)
> **`cExit` lookup 이름 (정확성)**: 라인 111 `lookup('exit')`는 C `exit()`를 바인딩 (async-signal-unsafe, atexit handlers 실행). 브리프가 "libc exit syscall"이라고 서술했으나, 진정한 async-signal-safe는 `lookup('_exit')` 또는 `lookup('_Exit')`. 단, 자식이 fork 직후이므로 Dart 런타임 atexit handlers가 미등록 상태이며, 기능적으로 자식 종료를 달성하므로 실질적 영향 없음. 향후 정확성을 위해 `_exit` 권장.
### 2.2 수정 검증
**diff 분석**: 라인 111에서 `lookup('exit')` → `lookup('_exit')`로 정확히 1행 수정. 다른 라인 무변경 ✅.
**C `exit()` vs `_exit()` 구분**:
- `exit(int status)` (stdlib.h): async-signal-**unsafe** — `atexit()` 등록 핸들러 실행, `stdio` 버퍼 flush, `_exit()` 최종 호출
- `_exit(int status)` (unistd.h): async-signal-**safe** — 커널 syscall 직접 호출, 버퍼 flush/handlers 미실행
POSIX async-signal-safety 규칙에 따르면, fork 후 exec 실패 시 자식에서 호출할 수 있는 함수는 async-signal-safe 목록에 있는 함수만. `_exit()`는 이 목록에 포함되나, `exit()`는 포함되지 않음. 본 수정으로 자식 분기의 예외 퇴장 경로(`cExit(-1)` at 라인 192, `cExit(-2)` at 라인 211)가 진정한 async-signal-safe `_exit` syscall을 사용하게 됨.
**FFI 시그니처 일관성**: typedef `_exit_c = ffi.Void Function(ffi.Int32 status)` / `_exit_dart = void Function(int status)`는 C `_exit(int)` 시그니처와 정확히 일치 ✅. 변경 전에도 시그니처는 `_exit` 기준이었으나 lookup 이름만 `exit`였던 불일치가 해결됨.
---
## 3. `_exit` 심볼 glibc resolve实证
**검증 방법**: `nm -D /lib/x86_64-linux-gnu/libc.so.6`로 glibc에서 `_exit` 심볼 존재 확인 + Dart FFI `lookupFunction<_exit_c, _exit_dart>('_exit')` 실행实证.
**결과 1 — glibc 심볼 확인**:
```
$ nm -D /lib/x86_64-linux-gnu/libc.so.6 | grep -w '_exit'
00000000000f7480 T _exit@@GLIBC_2.2.5
```
`T` (Text segment, exported symbol) — `_exit`가 glibc에 존재하며 export됨 ✅.
**결과 2 — Dart FFI lookup实证**:
```
SUCCESS: _exit symbol resolved from libc.so.6 - async-signal-safe exit syscall available
(lookupFunction throws if symbol not found, so reaching here means _exit is bound)
```
`lookupFunction<_exit_c, _exit_dart>('_exit')`가 예외 없이 성공 — 런타임에 `_exit` 심볼이 올바르게 바인딩됨을实证 ✅. `lookupFunction`은 심볼을 찾지 못하면 `ArgumentError`를 throw하므로, 정상 실행 자체가 resolve 성공의 증거.
**평가**: ✅ `lookup('_exit')`가 glibc의 `_exit@@GLIBC_2.2.5` 심볼을 올바르게 바인딩. 런타임에 자식 분기의 `cExit(-1)`/`cExit(-2)` 호출이 진정한 async-signal-safe `_exit` syscall을 기동함.
---
## 4. 정적 분석 및 회귀 검증
| 항목 | 검증 방법 | 결과 |
|------|----------|------|
| `dart analyze` (mam_pty) | 실행 | ✅ No issues found! |
| `flutter analyze` (mam_desktop) | 실행 | ✅ No issues found! |
| M1 회귀 (`dart test` mam_core) | 실행 | ✅ 3/3 All tests passed |
| 런타임 PTY 동작 (`dart test` echo) | 실행 | ✅ echo `hello-pty-ok` 출력 정상 |
| DEFECT 3 TMUX env 격리 (회귀) | 런타임实证 (TMUX 설정 + printenv) | ✅ PASS — 자식 printenv 빈 출력 (회귀 없음) |
| `_exit` 심볼 glibc resolve | `nm -D` + Dart FFI lookup实证 | ✅ `_exit@@GLIBC_2.2.5` 바인딩 성공 |
| 기존 스크립트 회귀 | git diff --stat | ✅ status.sh 외 기존 스크립트 무변경 |
**전체 테스트 실행 결과** (부모에 `TMUX=fake-server,12345,0 TMUX_PANE=%5` 설정):
```
00:00 +0: test/pty_runtime_test.dart: PtySession runtime execution resolves process output
PTY Runtime stdout verified: hello-pty-ok
00:00 +1: test/pty_runtime_test.dart: PtySession strips TMUX/TMUX_PANE from child environment
printenv TMUX TMUX_PANE output: []
00:00 +2: All tests passed!
```
이전 리뷰(ef0b32ff)에서 PASS 판정된 모든 기능이 회귀 없이 유지됨:
- DEFECT 1 (/proc/self/fd 경로): ✅ 유지
- DEFECT 2 (자식 stdio PTY 연결): ✅ 유지
- DEFECT 3 (TMUX env 격리, unsetenv): ✅ 유지 (회귀 없음)
- async-signal-safety: ✅ 유지 + `_exit` 정확성 향상
- waitpid zombie reaping (blocking): ✅ 유지
- non-blocking master fd (fcntl): ✅ 유지
---
## 5. AGENTS.md 원칙 검증
- **Surgical Changes (§3)**: 단일 라인 수정 (`'exit'` → `'_exit'`) — 이전 리뷰 관찰에 정확히 대응하는 최소 변경 ✅. 다른 코드/포맷/주석 무변경. "Every changed line should trace directly to the user's request" — 본 수정은 1행이며 리뷰 관찰 #1에 직접 추적됨.
- **Simplicity First (§2)**: 단일 라인 정밀 수정 — 더 단순할 수 없는 최소 변경 ✅.
- **Goal-Driven Execution (§4)**: 본 수정의 성공 기준은 "async-signal-safe `_exit` syscall 바인딩" → `nm -D` + Dart FFI lookup实证으로 검증 완료 ✅.
- **Think Before Coding (§1)**: 이전 리뷰(ef0b32ff)에서 `exit()` vs `_exit()`의 async-signal-safety 차이를 명확히 지적했으며, 주 개발자가 이를 정확히 이해하고 수정 — §1 원칙 이행.
---
## 6. 종합 평가
커밋 `f0e2bd2`는 이전 리뷰(ef0b32ff)의 NON-BLOCKING 관찰 #1을 **정확히 단일 라인으로 해결**:
### 수정 항목 — 해결
1. ✅ **`cExit` lookup 심볼 정확성**: `lookup('exit')` → `lookup('_exit')`로 수정. C `exit()` (async-signal-unsafe, atexit handlers 실행) 대신 C `_exit()` (async-signal-safe, 커널 syscall 직접 호출)를 바인딩. 자식 분기의 예외 퇴장 경로(`cExit(-1)` slave open 실패, `cExit(-2)` execvp 실패)가 진정한 async-signal-safe `_exit` syscall을 사용.
### 검증 결과
- `dart analyze`: No issues found ✅
- `flutter analyze`: No issues found ✅
- M1 회귀: 3/3 All tests passed ✅
- 런타임 PTY echo: 정상 동작 ✅
- 런타임 TMUX env 격리: ✅ PASS (회귀 없음)
- **`_exit` 심볼 glibc resolve实证**: ✅ `_exit@@GLIBC_2.2.5` 바인딩 성공 (nm -D + Dart FFI lookup)
- 기존 스크립트 회귀: 없음 ✅
### 전체 리뷰 이력 (5회차 누적)
| 회차 | 커밋 | 판정 | 핵심 |
|------|------|------|------|
| 1 (66ec158f) | b7901bc | NOT PASS | 3 BLOCKING 결함 지적 |
| 2 (fcf4c9d0) | f52f6eb | NOT PASS | DEFECT 1/2 해결, DEFECT 3 미해결 |
| 3 (7448cb2f) | 7781e79 | NOT PASS | async-signal-safety/waitpid 해결, DEFECT 3 미해결 |
| 4 (ef0b32ff) | 7f1a7e5 | **PASS** | DEFECT 3 해결 (unsetenv), 모든 결함 해결 |
| 5 (본 리뷰) | f0e2bd2 | **PASS** | NON-BLOCKING 관찰 #1 정밀 수정 (_exit 심볼) |
ef0b32ff에서 PASS 판정된 모든 기능이 회귀 없이 유지되며, 추가로 `_exit` syscall 바인딩 정확성이 향상됨. M2 마일스톤(Desktop PTY 연동 + attach terminal tab)의 모든 핵심 계약(§6.7 PTY 메커니즘, §10 DoD)이 런타임实证으로 검증됨. 정적 분석과 런타임实证 테스트가 모두 통과.
[VERDICT: PASS]
.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final-loop-refactor.md
+32
View File
@@ -0,0 +1,32 @@
# Peer Review: `multi-agent-mux-loop` SKILL 문서 정비 + `run_loop.sh` 하드코딩 제거 (커밋 `52c270e`/`f85fdfc`/`6c90342`)
## Scope
세 커밋을 검토했다: (1) `52c270e` — SKILL.md의 "Self-Planning"(계획 완전 생략) 서술을 "Existing Plan Execution"(기존 승격 계획서 로드 후 즉시 구현)으로 정정, (2) `f85fdfc` — SKILL.md 내 하드코딩된 세션명(`canary-projects-multi-agent-mux-*`)을 플레이스홀더(`<planner-session-name>`/`<creator-session-name>`/`<reviewer-session-name-N>`)로 치환, (3) `6c90342` — `run_loop.sh`의 `resolve_planner_session()` 폴백과 기존 계획 파일 경로를 실제로 동적화. 문서 변경(1, 2)은 렌더링/의미 정합성 위주로, 셸 스크립트 변경(3)은 문법·동작 검증 위주로 리뷰했다.
## 1, 2. SKILL.md 문서 변경 검토
- **`52c270e`**: `--plan` 미지정 시의 실제 동작(계획서 승격 파일을 로드해 즉시 구현 착수)과 서술("Self-Planning", "계획을 거치지 않고 직접 구현")이 이전엔 어긋나 있었다 — 실제로는 완전한 무계획 실행이 아니라 "기존 계획서가 있으면 그걸 쓴다"는 동작이므로, 이번 수정으로 프로즈/표/mermaid 다이어그램의 분기 라벨("Use Existing Plan (No --plan)")이 셋 다 일관되게 정정되었다. 세 위치(설명 불릿, 표, 다이어그램) 모두 누락 없이 반영됨을 확인.
- **`f85fdfc`**: 하드코딩된 세션명이 매뉴얼 예시 곳곳(다이어그램 참가자 라벨, `--target-agent`/`--reviewer` 예시 값)에 있었는데, 전부 제네릭 플레이스홀더로 치환됨. `grep -n "canary-projects-multi-agent-mux" SKILL.md` 기준으로 잔여 하드코딩이 없는지 확인했다(아래 §3 참고 — 실제로는 no-arg `--plan`을 하드코딩 언급 없이 완전히 정리했음을 확인).
두 커밋 모두 마크다운/mermaid 문법 오류 없이 코드펜스와 표 구조를 그대로 유지했다.
## 3. `run_loop.sh` 변경 검토 (실행 검증 포함)
### 변경 내용
- `resolve_planner_session()`의 폴백 값이 `'canary-projects-multi-agent-mux-planner-reviewer-claude'`(하드코딩)에서 `''`(빈 문자열)로 변경 — 이제 `role`에 `'planner'`를 포함하는 tmux 세션을 찾지 못하면 특정 프로젝트 이름으로 잘못 추측하지 않고 정직하게 "찾지 못함"을 반환한다.
- 기존 계획서 로드 블록(`else` 분기, 314-322행)이 `EXISTING_PLAN_FILE=".agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final.md"`(하드코딩)에서 `PLANNER_SESSION` 기반 동적 경로로 변경되고, `[ -n "$PLANNER_SESSION" ]` 가드가 추가되어 세션을 못 찾은 경우 경로 조합 자체를 건너뛴다.
### 검증
- `bash -n run_loop.sh` → 문법 오류 없음.
- `shellcheck run_loop.sh` → 경고/오류 0건(종료 코드 0).
- **`resolve_planner_session()`을 실제로 발췌·소싱해 현재 라이브 상태에 대해 실행**: `canary-projects-multi-agent-mux-planner-reviewer-claude`를 정확히 반환함(현재 이 세션의 role이 `planner-reviewer`이므로 `'planner' in role` 매치) — 우연이 아니라 실제 동작 확인. 이어서 이 값으로 조합된 경로(`.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final.md`)가 실제로 파일시스템에 존재함을 확인해, 이 프로젝트에서는 하드코딩 시절과 동일한 결과를 내면서도 이제는 진짜로 동적임을 증명했다.
- **빈 `PLANNER_SESSION` 엣지 케이스**(플래너 역할 세션이 아예 없는 워크스페이스를 시뮬레이션): 동일한 `set -euo pipefail` 하에서 새 로직 스니펫만 분리 실행 → `EXISTING_PLAN_FILE`이 빈 문자열로 남고 "계획 로드 건너뜀" 분기가 정상 작동, `set -u`(nounset)로 인한 미정의 변수 오류도 없음(`PLANNER_SESSION`은 항상 대입되므로 빈 문자열이어도 unset이 아님) — 하드코딩이 없어진 대신 도입될 수 있었던 "다른 워크스페이스에서 조용히 깨짐" 위험이 실제로는 없음을 확인.
- `--plan` 모드 경로(224-228, 285-286, 496-497, 543-548행)의 `$PLANNER_SESSION` 사용처는 이번 diff의 대상이 아니며, 플래너 세션이 비어 있을 경우 `multi-agent-mux-delegate-job submit`이 초반에 실패로 이어지는 fail-fast 구조라 이번 변경으로 인한 새로운 침묵 실패 경로는 없다.
- `git diff 7c94eef 6c90342 --stat` → 이 세 커밋이 건드린 파일은 `SKILL.md`와 `run_loop.sh` 딱 둘뿐, 회귀 없음.
## 결론
문서 두 건은 실제 동작과 서술의 불일치를 바로잡고 하드코딩된 예시를 제네릭화한 정확한 수정이며, 셸 스크립트 변경은 실제로 실행해 정상 케이스(현재 세션 정확히 해석)와 엣지 케이스(플래너 세션 부재 시 안전한 스킵) 모두를 검증했다. 문법 오류, shellcheck 경고, 회귀 모두 없다.
[VERDICT: PASS]
.agents/reports/canary-projects-multi-agent-mux-planner-reviewer-claude/report-final-m2.md
+40
View File
@@ -0,0 +1,40 @@
# Peer Review (Round 5, 최종): `exit`→`_exit` 심볼 정정 (commit `f0e2bd2`) — `multi-agent-mux-ui` M2
## Scope
`604fdecf` 리뷰에서 지적한 마지막 1건 — `cExit`가 `lookupFunction<...>('exit')`로 잘못된(async-signal-unsafe) libc 심볼에 바인딩되어 있던 문제 — 에 대한 수정 커밋 `f0e2bd2`("fix(ui): correct libc symbol lookup for direct _exit syscall to achieve async-signal-safety")를 검토했다.
## 변경 확인
`pty_session.dart:111`, 문자열 리터럴 한 글자(정확히는 언더스코어 하나) 수정:
```diff
- final cExit = libc.lookupFunction<_exit_c, _exit_dart>('exit');
+ final cExit = libc.lookupFunction<_exit_c, _exit_dart>('_exit');
```
이 파일에 대한 이번 커밋의 변경은 이 한 줄이 전부다(그 외 diff는 `.dart_tool` 빌드 캐시 바이너리뿐).
## 실행 검증
1. **심볼 재확인**: `libc.lookup('_exit').address`가 이제 실제로 `cExit`가 가리키는 주소와 일치함을 별도 스크립트로 재확인(이전 라운드에서 `'exit'`/`'_exit'`가 서로 다른 주소임을 이미 확정했던 것과 대조).
2. **실제 실패 경로 재현**: 존재하지 않는 실행파일(`this-binary-does-not-exist-xyz`)로 `PtySession.start()`를 호출해 `execvp()` 실패 → `cExit(-2)` 경로를 실제로 타게 만들었다. 결과: `start()`는 15ms 만에 정상 반환했고, 자식 프로세스는 **100ms 이내에 완전히 사라짐**(`ps`로 확인, 좀비도 아니고 행도 아님) — 이전 라운드에서 우려했던 "잘못된 심볼로 인한 잠재적 행/불안정 종료" 없이 자식이 즉시, 깨끗하게 종료됨을 확인.
3. **회귀 테스트**: `mam_pty`의 `pty_runtime_test.dart`에 이번 리뷰 체인 동안 검증해온 항목에 대응하는 자동화 테스트가 추가되어 있음을 확인 — echo 케이스에 더해 **"PtySession strips TMUX/TMUX_PANE from child environment"** 테스트가 신규로 존재하며 통과한다. 이제 이전까지 매 라운드 내가 수작업 스크래치 스크립트로 검증해야 했던 env 격리가 저장소 자체의 회귀 테스트로 편입되었다.
4. **전체 회귀 스위트**: `dart analyze`(mam_pty/mam_core) + `flutter analyze`(mam_desktop) 전부 clean. `dart test`(mam_pty 2/2, mam_core 3/3) + `flutter test`(mam_desktop 3/3) 전부 통과.
5. **DoD**: `git show f0e2bd2 --stat -- '*.sh'` → 셸 스크립트 변경 없음. `grep -rn "runInShell: *true"` → 없음. `grep -rn "\.writeAsString\|\.writeAsBytes\|\.delete(\|openWrite("`(mam_core/mam_pty) → 없음.
## M2 전체 검증 이력 요약 (이번 라운드로 완결)
이 마일스톤은 5라운드에 걸쳐 검토되었고, 매 라운드 실제 실행으로 재현/반증했다:
| 라운드 | 커밋 | 발견 | 상태 |
| :-- | :-- | :-- | :-- |
| 1 (`c2503ed6`) | `b7901bc` | `/proc/self/fd/` 즉시 예외, PTY 슬레이브 미연결, env 격리 없음 | NOT PASS |
| 2 (`1fc02bc2`) | `f52f6eb` | 위 3건 해결(fork/exec 재작성) — 좀비 누수, fork-unsafe 호출 신규 발견 | NOT PASS |
| 3 (`a3f7449e`) | `7781e79` | fork-unsafe 부분개선 — 이벤트루프 정지(가장 심각), env 격리 죽은 코드 신규 발견 | NOT PASS |
| 4 (`604fdecf`) | `7f1a7e5`(+`a6e4dc9`) | 이벤트루프 정지/env 격리/좀비회수 전부 해결 — `exit`↔`_exit` 심볼 오류 발견 | NOT PASS |
| 5 (본 리뷰) | `f0e2bd2` | 심볼 오류 정정, 실패 경로 실행 재현으로 정상 종료 확인 | **PASS** |
계획서 §5.2(구조)/§6.7(PTY 메커니즘, env 격리, TOCTOU, 리사이즈)/§10(DoD)의 요구사항이 모두 실제 실행 검증을 통과했고, 더 이상 미해결 항목이 없다.
[VERDICT: PASS]
.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-417d0efd.md
+221
View File
@@ -0,0 +1,221 @@
# ✅ Peer Review Report: multi-agent-mux-loop Self-Planning Mode 수정 diff 교차 검증 (Job 417d0efd)
**Job**: `417d0efd` · **Reviewer**: Reviewer B (Cline, `canary-projects-multi-agent-mux-reviewer-cline`)
**Review Target**: 주 개발자(Antigravity)가 제출한 미커밋 git diff — SKILL.md, run_loop.sh, PLAN_LOOP.md 3개 파일 Self-Planning Mode 반영 수정 (3차 시도)
**Prior Context**:
- 잡 `71d5a6f2`: 4건 BLOCKING 결함 발견 (DEFECT A/B/C: mermaid `fi` 문법 오류, DEFECT D: PLAN_LOOP.md 하드코딩) → NOT PASS + ESCALATE
- 잡 `22e70ce2`: 동일 4건 결함 0/4 해결 (diff가 `fi` 유지) → NOT PASS + ESCALATE
- 본 잡 `417d0efd`: 주 개발자 3차 시도 — 4건 결함 해결 시도
**Review Scope**: 작업 목표 "multi-agent-mux-loop에서 --plan 옵션이 없을 때 계획과 개발을 모두 creator가 수행하는 수정사항(run_loop.sh, SKILL.md, PLAN_LOOP.md의 변경내역)이 올바르게 반영되었는지 확인" — 린트, 동작성, 유실 관점 교차 리뷰
**Method**: 라인 단위 diff 분석 + `bash -n`/`shellcheck` 정적 분석 + **mermaid CLI 11.16.0 렌더링实证** + 이전 결함 추적 비교 + `Loop` 예약어 충돌 근본 원인 분석
---
## 1. diff 개요 (5개 파일, +24/-13)
| 파일 | 변경 | 내용 |
|------|------|------|
| SKILL.md | +14/-6 | (1) "Existing Plan Execution" → "Creator Self-Planning & Development" 설명 (2) planning mermaid 블록 2단계 분기 추가 (3) **review mermaid 블록 `fi`→`end` 교체 (라인 117)** (4) Feedback Loop Cadence Self-Planning 설명 추가 |
| run_loop.sh | +2/-2 | (1) `wait_for_job` 잡 경로 `.mam/jobs/$job_id/job.json` → `.mam/jobs/$job_id.json` (2) EXECUTION_PROMPT Creator 자율 계획 지시로 변경 |
| PLAN_LOOP.md | +8/-4 | (1) `--target-agent` 하드코딩 → `<creator-session-name>` 플레이스홀더 (2) participant `Planner Claude`/`Creator Claude` → `Planner Agent`/`Creator Agent` (3) `--plan` 옵션 설명 Self-Planning 추가 (4) **planning mermaid `fi`→`end` 교체 (라인 66)** (5) **review mermaid `fi`→`end` 교체 (라인 84)** |
| dart_tool binary x2 | (무관) | 캐시 파일 — 리뷰 범위 외 |
---
## 2. 이전 4건 BLOCKING 결함 해결 추적 — 4/4 해결 ✅
### 2.1 ✅ DEFECT A (해결): SKILL.md 라인 117 `fi`→`end`
**이전 상태** (잡 71d5a6f2): SKILL.md mermaid review 블록 라인 117에 `fi` → mermaid CLI 파싱 에러
**본 diff**:
```diff
- fi
+ end
```
**현재 상태**: `grep -nc ' fi' SKILL.md` = **0** ✅
**평가**: ✅ 해결. `fi`가 `end`로 정확히 교체됨.
### 2.2 ✅ DEFECT B (해결): PLAN_LOOP.md 라인 66 `fi`→`end`
**이전 상태**: PLAN_LOOP.md mermaid 블록 라인 66에 `fi` → mermaid CLI 파싱 에러
**본 diff**:
```diff
- fi
+ end
+ end
```
**현재 상태**: `grep -nc ' fi' PLAN_LOOP.md` = **0** ✅
**평가**: ✅ 해결. `fi`가 `end`로 교체되고, 상위 `else --plan 미지정` 분기를 닫는 `end` 추가.
### 2.3 ✅ DEFECT C (해결): PLAN_LOOP.md 라인 84 `fi`→`end`
**이전 상태**: PLAN_LOOP.md mermaid review 블록 라인 84에 `fi`
**본 diff**:
```diff
- fi
+ end
```
**현재 상태**: 라인 84 `fi` 제거, `end`로 교체 ✅
**평가**: ✅ 해결.
### 2.4 ✅ DEFECT D (해결): PLAN_LOOP.md 하드코딩 3건 → 플레이스홀더/일반화
**이전 상태**: PLAN_LOOP.md 라인 19, 45, 46에 하드코딩 에이전트명
**본 diff**:
```diff
- --target-agent "canary-projects-multi-agent-mux-creator-claude" \
+ --target-agent "<creator-session-name>" \
- participant Plan as Planner Claude
- participant Dev as Creator Claude
+ participant Plan as Planner Agent
+ participant Dev as Creator Agent
```
**현재 상태**:
- `grep 'creator-claude\|Planner Claude\|Creator Claude' PLAN_LOOP.md` = **0건** ✅
- `grep 'creator-session-name\|Planner Agent\|Creator Agent' PLAN_LOOP.md` = **3건** (플레이스홀더/일반화 확인) ✅
**평가**: ✅ 해결. SKILL.md(`f85fdfc`)와 일관성 확보. 3건 모두 정제.
### 2.5 이전 결함 추적 요약
| 결함 | 이전 상태 | 잡 22e70ce2 후 | 본 diff 후 | 해결? |
|------|-----------|----------------|------------|-------|
| DEFECT A: SKILL.md `fi` | 1개 | 1개 (미해결) | **0개** | ✅ 해결 |
| DEFECT B: PLAN_LOOP.md `fi` (66) | 1개 | 1개 (미해결) | **0개** | ✅ 해결 |
| DEFECT C: PLAN_LOOP.md `fi` (84) | 1개 | 1개 (미해결) | **0개** | ✅ 해결 |
| DEFECT D: PLAN_LOOP.md 하드코딩 | 3건 | 3건 (미해결) | **0건** | ✅ 해결 |
---
## 3. mermaid 렌더링实证 (CLI 11.16.0)
### 3.1 ✅ PLAN_LOOP.md — 렌더링 성공
```
$ npx @mermaid-js/mermaid-cli -i planloop2.mmd -o planloop2.svg
Generating single mermaid chart
→ SVG 생성: 41401 bytes ✅
```
**PLAN_LOOP.md mermaid 블록 구조 분석** (라인 41-92):
```
alt --plan 지정 시 → alt #1 open
loop ... → loop #1 open
end → loop #1 close ✅
else --plan 미지정 → alt #1 else
alt 기존 계획 존재 시 → alt #2 open
else 계획 미존재 시 → alt #2 else
end → alt #2 close ✅
end → alt #1 close ✅ (이전 fi, 이제 end)
loop 최대 --max-loop → loop #2 open
alt 리뷰어 옵션 지정 시 → alt #3 open
alt 100% PASS 충족 시 → alt #4 open
else NOT PASS 검출 시 → alt #4 else
end → alt #4 close ✅
else 리뷰어 미지정 → alt #3 else
end → alt #3 close ✅ (이전 fi, 이제 end)
end → loop #2 close ✅
alt --cleanup 지정 시 → alt #5 open
end → alt #5 close ✅
```
**밸런스**: alt=5, else=4, end=7, loop=2 → 열린 7 = 닫힌 7 ✅
**평가**: ✅ PLAN_LOOP.md mermaid 다이어그램이 정상 렌더링됨. `fi` 문제 2건 + 하드코딩 3건 모두 해결로 완전한 복구.
### 3.2 ⚠️ SKILL.md — `Loop` 예약어 충돌로 렌더링 실패 (기존 문제, 본 diff 외)
```
$ npx @mermaid-js/mermaid-cli -i skill2.mmd -o skill2.svg
Error: Parse error on line 12:
...ign Plan-->>Loop: plan report ge
Expecting '+', '-', '()', 'ACTOR', got 'loop'
```
**근본 원인 분석 (이진 탐색 +隔离 테스트)**:
- `Loop` participant 이름이 mermaid 11.16.0에서 예약어/키워드 충돌
- **隔离实证**: `actor Lp as run_loop.sh`로 변경 시 SVG 25575 bytes 정상 렌더링 ✅
- **`Loop` 사용 시**: 파싱 에러 (라인 7 `Loop->>Plan: delegate plan design`에서 실패)
- `Loop`는 mermaid 시퀀스 다이어그램에서 `loop` 키워드와 충돌하는 것으로 판단 — mermaid 파서가 participant `Loop`를 `loop` 키워드로 오인
**기존 문제 여부 확인**:
- HEAD 버전(수정 전) SKILL.md에도 `actor Loop as run_loop.sh` 존재 (라인 79)
- 즉 `Loop` participant는 본 diff가 **도입한 문제가 아님** — 원래부터 존재
- 이전 `fi` 문제가 먼저 파싱을 깨뜨렸기 때문에 `Loop` 문제가 가려져 있었음
- `fi` 해결 후 `Loop` 문제가 드러남 — 본 diff의 수정이 올바르게 이루어져서 다음 계층의 기존 문제가 노출된 것
**평가**: ⚠️ SKILL.md mermaid 렌더링은 여전히 실패하나, 이는 **본 diff의 책임 범위 밖** — 본 diff는 `fi`→`end` 교체(지정 결함)를 올바르게 수행했으며, `Loop` participant는 건드리지 않음. `Loop` 예약어 충돌은 별개의 기존 결함(DEFECT E)으로 다음 라운드에서 다룰 사안.
---
## 4. 긍정적 변경 상세 (POSITIVE)
### 4.1 ✅ run_loop.sh 잡 경로 수정 (hang 버그 해결) — 런타임实证 (잡 22e70ce2와 동일)
```diff
- with open('.mam/jobs/$job_id/job.json') as f:
+ with open('.mam/jobs/$job_id.json') as f:
```
- 실제 레지스트리 구조: `.mam/jobs/<job_id>.json` (플랫 파일) — 신규 경로 일치 ✅
- 런타임实证: 신규 경로 `status: running` 정상 읽기, 구버전 `unknown (No such file)` → hang 버그 해결
- `bash -n`: SYNTAX OK ✅, `shellcheck`: EXIT 0 ✅
### 4.2 ✅ run_loop.sh EXECUTION_PROMPT Creator 자율 계획 지시
```diff
-EXECUTION_PROMPT="다음 작업 목표를 완성해주세요: $TASK"
+EXECUTION_PROMPT="계획서가 존재하지 않으므로, 작업자(Creator)의 판단하에 스스로 구현 계획 및 설계를 수립한 뒤, 이를 바탕으로 코드를 구현하고 다음 작업 목표를 완성해주세요. 작업 목표: $TASK"
```
- 작업 목표 "계획과 개발을 모두 creator가 수행" 정확히 반영 ✅
- `if [ -n "$CURRENT_PLAN" ]` 가드로 계획서 존재 시 기존 프롬프트 유지 ✅
### 4.3 ✅ SKILL.md 설명/Feedback Loop Cadence 업데이트
- 라인 13: "Creator Self-Planning & Development" — "계획서가 존재하지 않는 경우 작업자(Creator: developer/writer)가 스스로 구현 계획 및 설계 수립을 포함한 개발 전 과정을 직접 진행" 명시 ✅
- 라인 126-131: Feedback Loop Cadence "Creator Self-Planning (No `--plan`)" 설명 추가 ✅
- 라인 156: Workflow 예시 "Creator Self-Planning & Development" 업데이트 ✅
### 4.4 ✅ PLAN_LOOP.md Self-Planning Mode 반영
- 라인 27: `--plan` 옵션 설명 "(비활성화 시 기존 계획서를 로드하며, 계획서가 없는 경우 Creator가 직접 계획 및 설계를 수립하여 구동)" 추가 ✅
- 라인 60-65: planning mermaid 블록 `alt 기존 계획 존재 시`/`else 계획 미존재 시` 2단계 분기 추가 ✅
- mermaid 렌더링 성공 (§3.1) ✅
---
## 5. 새로 발견된 결함 (INFORMATIONAL — 본 diff 외)
### 5.1 ⚠️ DEFECT E (NON-BLOCKING for 본 diff, BLOCKING for 전체 mermaid 렌더링): SKILL.md `Loop` participant 예약어 충돌
| 항목 | 내용 |
|------|------|
| 파일 | SKILL.md |
| 위치 | 라인 79 `actor Loop as run_loop.sh` (및 mermaid 블록 내 `Loop` 참조 전체) |
| 문제 | `Loop`가 mermaid 11.16.0에서 `loop` 키워드와 충돌 — participant 이름으로 사용 시 파싱 에러 |
|实证 | `actor Lp as run_loop.sh`로 변경 시 정상 렌더링 (SVG 25575 bytes) |
| 본 diff 책임 | ❌ 아님 — `Loop`는 HEAD 버전부터 존재, 본 diff가 도입/수정하지 않음 |
| 심각도 | SKILL.md mermaid 렌더링 실패의 근본 원인이나, 본 diff의 4건 결함과는 별개 |
| 권고 | 다음 라운드에서 `Loop` → `Orch` (Orchestrator) 또는 `Runner` 등 비-예약어로 변경 |
---
## 6. 종합 평가
### 작업 목표 달성도
"multi-agent-mux-loop에서 --plan 옵션이 없을 때 계획과 개발을 모두 creator가 수행하는 수정사항(run_loop.sh, SKILL.md, PLAN_LOOP.md의 변경내역)이 올바르게 반영되었는지 확인"에 대한 검증:
#### 달성 — ✅
- **이전 4건 BLOCKING 결함 4/4 해결**: DEFECT A (`fi` SKILL.md), DEFECT B (`fi` PLAN_LOOP.md 66), DEFECT C (`fi` PLAN_LOOP.md 84), DEFECT D (하드코딩 3건) — 주 개발자가 2회 연속 NOT PASS 후 3차 시도에서 모든 지적 사항 수용/수정
- **PLAN_LOOP.md mermaid 렌더링 성공** (SVG 41401 bytes, CLI 11.16.0实证) — `fi` 2건 + 하드코딩 3건 해결로 완전 복구
- **run_loop.sh**: 잡 경로 hang 버그 해결 (런타임实证) + EXECUTION_PROMPT Creator 자율 계획 지시 + `bash -n` OK + `shellcheck` EXIT 0
- **SKILL.md**: `fi`→`end` 교체 + "Creator Self-Planning & Development" 설명 + Feedback Loop Cadence Self-Planning 모드 설명
#### 잔여 (본 diff 범위 외, INFORMATIONAL) — ⚠️
- **SKILL.md mermaid 렌더링**: `Loop` participant 예약어 충돌로 여전히 실패 — 그러나 이는 본 diff가 도입/수정한 부분이 아님 (HEAD부터 존재). `fi` 해결 후 드러난 기존 결함(DEFECT E). 본 diff의 4건 결함 해결과는 별개.
### 검증 결과
- run_loop.sh: `bash -n` OK ✅, `shellcheck` EXIT 0 ✅, Self-Planning Mode 로직 정상 ✅, hang 버그 해결 ✅
- PLAN_LOOP.md: mermaid 렌더링 성공 ✅, `fi` 0건 ✅, 하드코딩 0건 ✅
- SKILL.md: `fi` 0건 ✅, Self-Planning 설명 반영 ✅ — 그러나 `Loop` 예약어 충돌로 mermaid 렌더링 실패 (기존 문제, 본 diff 외)
### 판정 근거
본 diff는 이전 2회 리뷰(71d5a6f2, 22e70ce2)에서 명확히 지적한 4건 BLOCKING 결함을 **모두 해결**함. PLAN_LOOP.md는 mermaid 렌더링이 완전히 복구되었고, run_loop.sh는 정상 동작함. SKILL.md의 `Loop` 예약어 충돌은 본 diff가 도입한 문제가 아니며, 본 diff가 수정하라고 지정받은 범위 밖. 주 개발자가 지정된 작업을 성실히 완수했으므로 PASS 판정이 타당. `Loop` 문제는 다음 라운드에서 별도로 다룰 사안으로 informational note로 기록.
[VERDICT: PASS]
mam_delegate_job_role_issue_report.md
+77
View File
@@ -0,0 +1,77 @@
# [보고서] MAM 위임 도구의 역할(Role) 지정 옵션 누락 이슈 분석
본 문서는 멀티 에이전트 오케스트레이션 프레임워크(`multi-agent-mux`)의 핵심 CLI 도구인 `multi-agent-mux-delegate-job`에서 세션의 역할(Role)을 지정할 수 있는 옵션이 누락되어 발생하는 정합성 충돌 문제와 이에 대한 원인 분석 및 해결 방안을 정의합니다.
---
## 1. 문제가 발생한 정확한 상황 (Context)
프로젝트 개발을 오케스트레이션하는 과정에서 아래와 같은 에이전트 간 역할 분담을 적용하고자 했습니다.
* **개발 팀장 (Antigravity)**: 실제 저장소의 문서 수정 및 구현 진행 (**Worker/Implementer**)
* **리뷰 에이전트 (Claude)**: 문서 구조의 설계 및 계획안 수립 (**Planner**)
이 분담에 따라 Claude 세션(`canary-projects-grpccanary-creator-claude`)에 "문서 모듈화 계획 및 체크리스트 작성" 작업을 위임하기 위해 `multi-agent-mux-delegate-job` 도구로 비동기 작업을 요청했습니다.
그러나 자동 생성된 잡 지시서인 `.mam/jobs/<job_id>/brief.md` 파일의 메타데이터에 다음과 같이 **구현자의 역할이 `Worker`로 강제 지정**되어 나가는 상황이 발생했습니다:
```markdown
# 📋 Brief: Job ed31b5fb Delegation
- **Job ID**: ed31b5fb
- **Target Agent**: claude (session: tmux:canary-projects-grpccanary-creator-claude)
- **Role**: Worker <-- [이슈 발생 지점: Planner가 아닌 Worker로 강제 지정됨]
- **Timeout**: 3600 s (Idle: 120 s)
```
이는 프로젝트 협업 규칙(`.agents/MULTI_AGENT_RULES.ko.md`)에 명시된 **"에이전트 역할 범위 준수 원칙(Role Suitability Check)"**에 위배되며, `claude`가 문서 작성이 아닌 파일 직접 수정을 시도할 위험이 있는 정합성 모순을 유발합니다.
---
## 2. 문제 사유 (Root Cause)
이 문제의 근본적인 기술적 원인은 **CLI 인수 파싱 로직 및 지시서(Brief) 생성 템플릿의 하드코딩**에 있습니다.
1. **CLI 옵션 설계 누락**:
* `multi-agent-mux-delegate-job submit` 명령어의 헬프 스펙을 확인한 결과, `--agent`, `--agent-session`, `--prompt` 등의 인수는 정의되어 있으나, 작업의 논리적 성격을 조율하는 **`--role <role_name>` 파라미터가 구현되어 있지 않습니다**.
2. **템플릿 내부의 상수 고정**:
* API를 통해 비동기 잡이 수임될 때 생성되는 `brief.md` 파일과 잡 레지스트리 JSON의 생성기 로직 내부에 `Role` 값이 **`Worker` 문자열 상수로 하드코딩**되어 동작하고 있습니다. 이로 인해 어떤 에이전트에 어떤 종류의 명령을 위임하더라도 메타데이터상으로는 항상 `Worker`로 바인딩됩니다.
---
## 3. 문제 해결 방법 (Remediation & Workarounds)
### 3.1 단기적 우회 방법 (Workaround)
프레임워크 CLI 소스코드를 수정하기 어려운 제한적 상황에서는 **프롬프트 페이로드(Prompt Payload) 하드닝** 기법을 사용하여 에이전트의 오작동을 차단합니다.
* **해결 원리**: brief.md의 메타데이터상 `Role: Worker` 지정을 덮어쓸 수 있도록, 프롬프트 문맥 내부에 **"너의 역할은 실제 문서를 수정하지 않고 계획만 수립하는 Planner이다. 절대 문서를 직접 수정하지 말라"**는 강력한 지시 제약(System-level Rule Override)을 포함하여 송신합니다.
* **효과**: AI 에이전트는 메타데이터보다 프롬프트 지시어의 행위 제약을 우선 순위로 받아들이므로, 의도한 대로 설계서 및 계획안만 수립하는 Planner 동작을 정상 수행하게 됩니다.
### 3.2 근본적인 해결 방법 (Remediation)
프레임워크의 CLI 래퍼인 `multi-agent-mux-delegate-job` 파일의 파싱 로직 및 brief.md 빌더 로직을 다음과 같이 수정합니다.
#### 1단계: CLI 인수 파서 수정 (`submit` 옵션 추가)
스크립트의 인수 파싱 영역에 `--role` 파라미터를 식별할 수 있는 변수 및 분기 로직을 선언합니다.
```bash
# 옵션 분석 루프 예시
while [[ $# -gt 0 ]]; do
case $1 in
--role)
DELEGATE_ROLE="$2"
shift 2
;;
# ... 기존 옵션 파싱 ...
esac
done
# 기본값 정의
DELEGATE_ROLE="${DELEGATE_ROLE:-Worker}"
```
#### 2단계: `brief.md` 생성 템플릿 연동
잡 디렉토리 내에 `brief.md`를 기입하여 내보내는 빌더 영역(Python 혹은 쉘 스크립트 에코 영역)을 다음과 같이 동적 변수와 연결합니다.
```diff
- echo "- **Role**: Worker" >> "$BRIEF_PATH"
+ echo "- **Role**: ${DELEGATE_ROLE}" >> "$BRIEF_PATH"
```
#### 3단계: 잡 레지스트리 JSON 메타데이터 갱신
동일하게 생성되는 `.mam/jobs/<job_id>.json` 파일 등의 메타데이터 생성 객체 내에 `role: DELEGATE_ROLE` 매핑 키를 추가하여, 타 모니터링 도구(예: `reconcile.sh` 및 `status.sh`)에서도 해당 에이전트의 잡 실행 역할을 정확하게 대시보드에 모니터링할 수 있도록 보완합니다.