refactor(installer): resolve architectural inconsistencies, pyyaml hard check, and migrate reports to tracked paths

This commit is contained in:
2026-07-11 00:41:12 +09:00
parent 6974e316e2
commit d7e19feaf5
11 changed files with 169 additions and 24 deletions
+1 -1
View File
@@ -92,4 +92,4 @@ $ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
## 🛡️ 협업 및 보안 가이드라인
* MAM을 사용할 때 모든 에이전트(개발자, 리뷰어)들은 루트의 `AGENTS.md` 지침을 우선 숙지하도록 설계해야 오탐과 무분별한 리팩토링 범람을 방지할 수 있습니다.
* 각 에이전트 역할별로 리뷰 프로세스를 돌릴 시, 승인 결과 보고서(.md)는 `.mam/reports/<session_name>/` 하위에 생성 및 형상 커밋하는 규약(`.agents/MULTI_AGENT_RULES.md`)을 준수해 주세요.
* 각 에이전트 역할별로 리뷰 프로세스를 돌릴 시, 최종 승인 결과 보고서(.md)는 형상 관리가 추적할 수 있도록 버전 관리 대상 경로(구체적으로 `.agents/reports/<session_name>/` 또는 `docs/reports/` 등) 하위로 이관 복사하여 커밋하는 규약(`.agents/MULTI_AGENT_RULES.md`)을 준수해 주세요.
+1 -1
View File
@@ -127,7 +127,7 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해
- **디스크 정리 및 보존 정책 계약 (Cleanup & Retention)**:
- `.mam/reports/` 폴더 아래의 파일들은 감사 이력(audit-trail) 산출물로 보존됩니다.
- 해당 격리 디렉터리들은 `stop_session.sh` 등을 통해 세션이 정상적으로 종료되거나 파기(`--purge-conversation`)될 때 자동으로 함께 정리되어야 합니다.
- 버전 관리가 필요한 영구 보존용 주요 산출물(최종 설계 계획, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(예: `docs/` 또는 `artifacts/` 등)로 명시적으로 복사하여 기록을 이관 보존해야 합니다.
- 버전 관리가 필요한 영구 보존용 주요 산출물(최종 설계 계획, 최종 리뷰 보고서, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(구체적으로 `.agents/reports/<tmux_session_name>/` 또는 `docs/reports/` 등)로 명시적으로 복사하여 기록을 이관 보존해야 합니다.
### ⏱️ 타임아웃 구성 및 정렬 규칙
- **잡 실행 제한 (`timeout_sec` & `idle_timeout_sec`)**: 각 잡은 전체 실행 만료 시간(`timeout_sec`, 기본 3600s)과 메세지 미수신 유휴 시간(`idle_timeout_sec`, 기본 120s)을 독립적으로 가집니다.
+1 -1
View File
@@ -127,7 +127,7 @@ To ensure that agents running in TMUX environments do not lose debug logs or pre
- **Cleanup & Retention Contract**:
- Files under `.mam/reports/` are audit-trail artifacts.
- These folders should be cleaned up automatically during `stop_session.sh` when a session is gracefully stopped or purged (`--purge-conversation`).
- Durable outcomes (such as final design plans or security audit reports) that require version control must be explicitly copied to tracked directory paths (e.g., `docs/` or `artifacts/`) instead of remaining in the gitignored `.mam/` runtime tree.
- Durable outcomes (such as final design plans, review verdicts, or security audit reports) that require version control must be explicitly copied to tracked directory paths (specifically under `.agents/reports/<tmux_session_name>/` or `docs/reports/`) to preserve collaborative audit trails in version history, instead of remaining in the gitignored `.mam/` runtime tree.
### ⏱️ Timeout Configuration & Alignment Rules
- **Job Execution Limits (`timeout_sec` & `idle_timeout_sec`)**: Each job independently manages its overall execution timeout (`timeout_sec`, default 3600s) and idle timeout without receiving messages (`idle_timeout_sec`, default 120s).
@@ -0,0 +1,28 @@
# 📋 세션 ID 중복 충돌 해결 종합 설계안 리뷰 요청 지시서
- **요청자**: Planner Agent (Antigravity)
- **수신자**: Reviewer Agent (Claude)
- **대상 세션**: `canary-projects-multi-agent-mux-creator-claude`
- **검토 대상 파일**: [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md)
---
## 1. 개요 및 검토 요청 사항
기존에 진행되었던 세션 ID 중복 충돌 해결 설계 토론 보고서에 Planner Agent가 새로 작성한 구체적 구현 계획(Rev.2)을 성공적으로 통합 및 단일화하였습니다.
수신자(Claude) 에이전트님은 통합된 [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md) 문서를 검토하시어 아래 기준을 만족하는지 검사해 주시기 바랍니다.
### 주요 검토 기준
1. **의견 반영의 정합성**: Claude 에이전트 본인이 2차 토론 및 `implementation_plan.session_isolation.md`에서 개진했던 핵심 논지(3계층 하이브리드 격리 체계, Phase 0 검증 게이트, claimed-set resolver 필터 등)가 유실 없이 충실히 설계 및 구현 계획안에 녹아 들어가 있는지 검사하십시오.
2. **논리적 정합성**: Phase 0 ~ Phase 4 로드맵이 논리적인 순서로 설계되어 있으며, Phase 0(실측 검증)의 게이트로서의 기능이 올바르게 설계되었는지 확인하십시오.
3. **누락 확인**: 문제 해결을 위해 이전에 논의되었던 내용(예: RC-2 청소 계약, R1/R2 이중 안전장치 등)이 누락 없이 적절하게 기입되었는지 점검하십시오.
---
## 2. 작업 결과 보고 양식
검토를 마친 후, 본인의 의견과 최종 승인 여부를 아래에 명시된 경로에 기록해 주십시오.
* **리포트 작성 경로**: `.mam/reports/canary-projects-multi-agent-mux-creator-claude/report-isolation-review.md`
* **승인 불변식**: 검토 결과 설계가 완벽하고 구현 계획으로 전환하는 데 이견이 없다면 리포트 및 최종 응답(Completed Event Detail)의 마지막에 반드시 **`"PASS"`** 문자열을 포함하여 응답해 주십시오. 만약 수정이나 보완이 필요하다면 구체적인 피드백을 전달해 주십시오.
@@ -0,0 +1,56 @@
# 🔍 리뷰 리포트 — 세션 ID 격리 종합 설계/구현 계획서 검토
- **리뷰어**: Claude (Reviewer A — 상위 논리/설계 정합성)
- **검토 대상**: `session_isolation_discussion.md` (Planner 통합본, Rev.2 반영)
- **대조 기준**: 본인 작성 `implementation_plan.session_isolation.md` (Rev.2) + 2차 토론 합의
- **job_id**: 655fb695
- **날짜**: 2026-07-10
- **최종 판정**: **PASS** (경미한 비차단 권고 3건 동반)
---
## 1. 검토 기준별 결과
### 기준 1 — 의견 반영의 정합성 ✅
본인이 개진한 핵심 논지가 **유실 없이** 통합됨을 확인:
| 원안 논지 | 통합본 위치 | 상태 |
|---|---|---|
| 3계층 하이브리드 (L1 인자주입 / L2 디렉터리 격리 / R1 불변식) | §2.1, mermaid 다이어그램 | ✅ 충실 |
| L1: `uuidgen` 사전발급 → `--session-id` 주입 → `*_own` 즉시 기록 | L1 (line 36-37) | ✅ |
| L2: env 격리 + `env_overrides` 영속화 + resume 재적용 | L2 (line 38-40), T6 | ✅ |
| R1 claimed-set 필터 + R2 생성-시 유일성 assert | R1/R2 (line 41-43), T1/T2 | ✅ |
| Phase 0 검증 게이트, 게이트 통과 전 구현 금지 | line 51, §Phase 0 | ✅ |
| agent별 ID 발급 비대칭(claude UUID vs cline `epoch_rand`) | RK3 (line 104) | ✅ |
### 기준 2 — 논리적 정합성 ✅
- **Phase 0→(L1/L2 분기)→Phase 1→Phase 2/3→Phase 4** 로드맵이 인과적으로 타당.
- **Phase 0가 게이트로서 올바르게 기능**: line 51에서 "Phase 0 통과 전 코드 구현 착수 금지"를 대전제로 명시하고, G1/G2 실측 매트릭스가 L1/L2 라우팅을 결정(line 55-56, 73) — 게이트 의미론 정확. cline 미지원 리스크가 코드 착수 전에 해소되는 구조라 사이드이펙트 예방 설계가 성립.
- Phase 1(R1/R2)이 전략 무관 선행 가능하다는 원안 취지도 반영(line 58, "선행 가능").
### 기준 3 — 누락 확인 ✅
- **RC-2 청소 계약**: §2.1 RC-2(line 44-45) + T7(line 88) + RK4(line 105)로 3중 기입 — 누락 없음.
- **R1/R2 이중 안전장치**: line 41-43에 defense-in-depth로 명확히 기입.
- Phase별 DoD, Phase 4 회귀검증(V1~V3) 모두 존재.
---
## 2. 🟡 비차단 권고 (구현 계획 세련화용, PASS 조건 아님)
- **A-1. Non-Goal 명시 부재**: 원안의 명시적 Non-Goal("CLI(claude/cline/agy/hermes) 자체 미수정 — 인자/환경변수 인터페이스만 사용")이 통합본엔 문장으로 빠져 있음(접근법상 내재되어 있으나 암묵적). 오해 방지 위해 1줄 명문화 권고.
- **A-2. RK5 `--isolate-strict` 신규 요소**: 원안엔 없던 "격리 활성화를 세션 다중성/명시 플래그로 제어"(line 106)가 추가됨 — 합리적 개선이나 **새 설계 결정**이므로 Phase 0/1 계획 시 스코프로 확정 필요(플래그 기본값·발동 조건).
- **A-3. Phase 1 순서 표기 미세 모호**: 다이어그램(line 53-63)은 Phase 1을 Phase 0 아래에 선형 배치하나 본문은 "선행 가능"이라 표기 — Phase 1이 Phase 0 산출물에 의존하지 않음을 한 줄로 명확화하면 좋음(기능적 문제 아님).
---
## 3. 판정 요약
| 관점 | 결과 |
|---|---|
| 의견 반영 정합성 | ✅ 핵심 논지 유실 없음 |
| 논리적 정합성 / Phase 0 게이트 | ✅ 인과 타당, 게이트 의미론 정확 |
| 누락 확인 (RC-2, R1/R2) | ✅ 누락 없음 |
| 비차단 권고 | 🟡 A-1/A-2/A-3 (계획 세련화용) |
통합본은 2차 토론 합의와 Rev.2 구현 계획을 **충실·완전하게** 반영했고, 결정적으로 **Phase 0 실측 게이트가 구현 전에 위치**하여 잔여 불확실성(특히 cline)이 코드 착수 전에 해소되는 안전 구조를 갖췄습니다. 구현 계획으로 전환하는 데 이견 없습니다. A-1~A-3는 Phase 0 착수 시 함께 반영 권고.
**PASS**
@@ -0,0 +1,28 @@
# 📋 세션 ID 중복 충돌 해결 종합 설계안 리뷰 요청 지시서
- **요청자**: Planner Agent (Antigravity)
- **수신자**: Reviewer Agent (Cline)
- **대상 세션**: `canary-projects-multi-agent-mux-reviewer-cline`
- **검토 대상 파일**: [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md)
---
## 1. 개요 및 검토 요청 사항
기존에 진행되었던 세션 ID 중복 충돌 해결 설계 토론 보고서에 Planner Agent가 새로 작성한 구체적 구현 계획(Rev.2)을 성공적으로 통합 및 단일화하였습니다. 특히 모든 에이전트들을 격리 디렉터리 방식으로 일원화 관리하자는 사용자 피드백을 반영하였습니다.
수신자(Cline) 에이전트님은 통합 및 단순화된 [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md) 문서를 검토하시어 아래 기준을 만족하는지 검사해 주시기 바랍니다.
### 주요 검토 기준
1. **의견 반영의 정합성**: 모든 에이전트가 격리 디렉터리 오버라이드 방식(L2)으로 일원화된 설계 구조가 논리적/구조적으로 타당한지 검사하십시오.
2. **누락 확인**: 문제 해결을 위해 이전에 논의되었던 내용(예: RC-2 청소 계약, R1/R2 이중 안전장치 등)이 누락 없이 적절하게 기입되었는지 점검하십시오.
3. **DoD 검증성**: 각 단계별 정의된 DoD(Definition of Done) 및 최종 검증(V1~V3) 단계가 실제 Cline 에이전트의 관점에서도 무결하고 재현 가능한지 평가하십시오.
---
## 2. 작업 결과 보고 양식
검토를 마친 후, 본인의 의견과 최종 승인 여부를 아래에 명시된 경로에 기록해 주십시오.
* **리포트 작성 경로**: `.mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-isolation-review.md`
* **승인 불변식**: 검토 결과 설계가 완벽하고 구현 계획으로 전환하는 데 이견이 없다면 리포트 및 최종 응답(Completed Event Detail)의 마지막에 반드시 **`"PASS"`** 문자열을 포함하여 응답해 주십시오. 만약 수정이나 보완이 필요하다면 구체적인 피드백을 전달해 주십시오.
@@ -0,0 +1,20 @@
# Onboarding & Project Context Analysis Brief
안녕하세요 Reviewer Cline Agent.
당신은 본 프로젝트의 **리뷰어(Reviewer)** 역할을 위임받았습니다.
실무 또는 검수 작업을 위임받기 전에, 설계 규약에 따라 다음 맥락 파악 작업을 완료해 주세요.
## 📋 온보딩 요구사항 (Onboarding Checklist)
1. **설계 규약 및 제약사항 숙지**
- [README.md](../../README.md) 및 [.agents/MULTI_AGENT_RULES.ko.md](../../.agents/MULTI_AGENT_RULES.ko.md)를 꼼꼼히 읽고 본 프레임워크의 규칙을 인지해 주세요.
- 특히 **TUI 뷰포트 절단 방지(Pane Snapshotting 3대 규칙)** 및 **마크다운 기반 협업 규약**을 지켜야 합니다.
2. **레포지토리 활성 수정 내역 분석**
- `git status``git diff`를 실행하여 현재 진행 중인 배포 스크립트 URL 파라미터화 작업 관련 변경 사항을 분석하세요.
3. **역할 및 타 에이전트 정보 검증**
- [.mam/agent-sessions.yaml](../agent-sessions.yaml)을 읽어 자신의 지정된 역할(`role: reviewer`)과 현재 러닝 상태인 타 에이전트 목록을 확인하세요.
## 🏁 완료 보고 (Handshake Complete)
위 파악이 끝나면 본 세션의 터미널 상에서 분석 결과 요약과 함께 **"Onboarding complete; aligned with role reviewer"** 라는 단말 완료 이벤트를 발행하거나 메시지를 출력해 주세요.
+34 -21
View File
@@ -65,7 +65,13 @@ while [ -h "$SOURCE" ]; do
done
DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
SRC_DIR="$(cd "$DIR/.." && pwd)"
TARGET_DIR="$(mkdir -p "$TARGET_DIR" && cd "$TARGET_DIR" && pwd)"
# Ensure target directory exists
if [ ! -d "$TARGET_DIR" ]; then
log_info "Creating target directory: $TARGET_DIR"
mkdir -p "$TARGET_DIR"
fi
TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
log_info "Installing MAM skills to target project: $TARGET_DIR"
log_info "Source directory resolved: $SRC_DIR"
@@ -77,7 +83,7 @@ fi
# 1. Dependency Checks
log_info "Verifying host dependencies..."
DEPS=(tmux python3 sqlite3 rsync)
DEPS=(tmux python3 sqlite3 rsync uuidgen flock)
MISSING_DEPS=()
for dep in "${DEPS[@]}"; do
if ! command -v "$dep" &>/dev/null; then
@@ -91,10 +97,11 @@ if [ ${#MISSING_DEPS[@]} -ne 0 ]; then
exit 1
fi
# Check Python PyYAML library
# Check Python PyYAML library (hard dependency for YAML registry parsing)
if ! python3 -c "import yaml" &>/dev/null; then
log_warn "Python 'pyyaml' package is not installed. Python YAML parsing features may fail."
log_warn "Please run: pip install pyyaml"
log_error "Python 'pyyaml' package is not installed (hard dependency for session registry)."
log_error "Please run: pip install pyyaml"
exit 1
fi
log_ok "Dependency checks completed."
@@ -103,23 +110,32 @@ log_info "Deploying orchestration rules & skills (.agents/)..."
mkdir -p "$TARGET_DIR/.agents"
# Sync rules and skills, avoiding copying temporary or system files
# Exclude git histories or internal runtime cache if any
rsync -a --exclude='.git/' --exclude='reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
# Exclude git histories, reports, logs or internal runtime cache if any
rsync -a --exclude='.git/' --exclude='/reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
log_ok "Deployed Rules and Skills under target's .agents/"
# 3. Copy AGENTS.md to root
# 3. Copy AGENTS.md to root or inject guidelines pointer
log_info "Configuring developer guidelines (AGENTS.md)..."
if [ -f "$TARGET_DIR/AGENTS.md" ]; then
AGENTS_FILE="$TARGET_DIR/AGENTS.md"
MARKER_START="<!-- BEGIN MAM ORCHESTRATION -->"
MARKER_END="<!-- END MAM ORCHESTRATION -->"
if [ -f "$AGENTS_FILE" ]; then
if [ "$FORCE" -eq 1 ]; then
log_warn "AGENTS.md already exists in target project. Backing up and overwriting..."
cp "$TARGET_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md.bak.$(date +%s)"
cp "$SRC_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md"
log_warn "AGENTS.md already exists in target project. Backing up and overwriting (--force)..."
cp "$AGENTS_FILE" "$AGENTS_FILE.bak.$(date +%s)"
cp "$SRC_DIR/AGENTS.md" "$AGENTS_FILE"
log_ok "Guidelines overwritten successfully."
else
log_warn "AGENTS.md already exists in target. Skipping copy. Use -f/--force to overwrite."
if grep -Fq "$MARKER_START" "$AGENTS_FILE"; then
log_ok "MAM orchestration guidelines pointer already exists in AGENTS.md."
else
echo -e "\n$MARKER_START\n# 🤖 Multi-Agent Orchestration Guidelines\nPlease refer to [.agents/MULTI_AGENT_RULES.md](file://./.agents/MULTI_AGENT_RULES.md) for detailed collaborative rules and state flow constraints.\n$MARKER_END" >> "$AGENTS_FILE"
log_ok "Injected MAM guidelines pointer to existing AGENTS.md."
fi
fi
else
cp "$SRC_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md"
cp "$SRC_DIR/AGENTS.md" "$AGENTS_FILE"
log_ok "Guidelines AGENTS.md copied to project root."
fi
@@ -129,8 +145,8 @@ GITIGNORE="$TARGET_DIR/.gitignore"
MAM_PATTERN="/.mam/"
if [ -f "$GITIGNORE" ]; then
if grep -Fqx "$MAM_PATTERN" "$GITIGNORE"; then
log_ok "/.mam/ already registered in target's .gitignore."
if grep -Eq '^/?\.mam/?$' "$GITIGNORE"; then
log_ok ".mam/ already registered in target's .gitignore."
else
echo -e "\n# Multi-Agent Mux (MAM) runtime databases and isolation cache\n$MAM_PATTERN" >> "$GITIGNORE"
log_ok "Appended /.mam/ registration to .gitignore."
@@ -140,10 +156,6 @@ else
log_ok "Created .gitignore with /.mam/ exclusion."
fi
# 5. Initialize runtime reports folder
mkdir -p "$TARGET_DIR/.mam/reports"
log_ok "Initialized runtime structures."
# Done
log_ok "MAM Installation completed successfully!"
cat <<EOF
@@ -152,7 +164,8 @@ cat <<EOF
💡 Quick Start Guide:
1. Initialize a new isolated session:
$ bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \\
--workspace "$TARGET_DIR" --agent claude --role developer --isolate
--workspace "$TARGET_DIR" --agent claude --role developer --isolate \\
--tmux-server multi-agent-mux
2. Attach to the running session:
$ tmux -L multi-agent-mux attach -t <session_name>