tmpl/multi-agent-mux

Fork 0

Files

T

Godopu 4b2f703a73 docs(reports): archive v4.1.3 version update assessment and unanimous peer review reports

2026-08-31 11:25:09 +09:00

12 KiB

Raw Blame History

📋 Multi-Agent Mux 버전 업데이트 필요성 및 적정 버전 검토 보고서

문서 ID: version-update-assessment-issue-3
관련 작업 ID (Job ID): 6c24ddd0
작성 에이전트: creator-agy-01 (agy)
검토 대상 커밋 범위: 0644e77..HEAD (c49ee3b, 7e15081, 94f2e21)
수신 리뷰어: planner-reviewer-claude-01 (claude), reviewer-creator-grok-01 (grok), reviewer-opencode-01 (opencode)
작성 일시: 2026-08-31 (KST)

1. 개요 및 검토 배경 (Executive Summary)

본 보고서는 Issue #3('[Bug] herdr 데몬 프로세스 분리(setsid) 누락으로 인한 세션 리셋 및 UUID 미할당 세션 resume 데드락 문제') 해결을 위해 수행된 코드 변경 사항(c49ee3b, 7e15081)에 대해, SemVer 2.0.0(유의적 버전 2.0.0) 명세 및 본 프로젝트의 릴리스 관리 원칙에 입각하여 버전 업데이트의 필요성 여부, 적정 목표 버전 번호, 그리고 3-Way Version Lockstep 적용 터치포인트를 종합 검토한 결과를 제시합니다.

📌 핵심 결론 요약

버전 업데이트 필요성: 필수 (REQUIRED)
- 프레임워크 런타임 진실 공급원인 .agents/skills/lib.sh 및 복원 스킬의 핵심 라이프사이클 스크립트(.agents/skills/multi-agent-mux-resume/scripts/)에 실제 런타임 버그 수정이 반영되었으며, 신규 회귀 테스트(test_h26, test_t14, test_t15, test_t16)가 추가되었으므로 릴리스 패키징 및 버전 추적이 반드시 수행되어야 합니다.
적정 목표 버전 번호: v4.1.3 (PATCH Release)
- 공개 API의 호환되지 않는 변경(Breaking Changes) 없음 \rightarrow MAJOR(v5.0.0) 배제
- 새로운 기능 서브시스템이나 신규 에이전트 어댑터 추가 없음 \rightarrow MINOR(v4.2.0) 배제
- 기존 결함에 대한 100% 하위 호환 내부 버그 수정 \rightarrow SemVer 2.0.0 §6에 의거하여 PATCH(v4.1.3)가 유일하게 타당함
현재 상태 유지 원칙:
- 본 단계에서는 요구사항에 따라 실제 코드/스킬/버전 파일을 수정하지 않고, 리뷰어 만장일치 합의 수렴 후 후속 릴리스 패키징 작업에서 3자 동기화(3-Way Lockstep)를 원자적으로 일괄 수행할 것을 제안합니다.

2. 변경 내역 분석 (Detailed Code Diff Analysis)

v4.1.2 릴리스 커밋(0644e77) 이후 프레임워크에 반영된 핵심 변경 사항은 다음과 같습니다:

1) Item 1: Herdr 데몬 프로세스 그룹 완전 분리 (`c49ee3b`)

수정 파일: .agents/skills/lib.sh
변경 내용: .mam/shim/herdr 템플릿 내의 불안정한 nohup "$REAL_HERDR" ... server >/dev/null 2>&1 & disown 구문을 파이썬 subprocess.Popen(sys.argv[1:], start_new_session=True) 기반의 스포너로 전면 교체.
영향도 분석:
- start_new_session=True는 자식 프로세스에서 os.setsid()를 호출하여 완전히 새로운 프로세스 그룹(PGID) 및 세션 ID(SID)를 부여합니다.
- 부모 셸이나 테스트 하네스 러너의 시그널 브로드캐스트(SIGINT/SIGTERM)가 백그라운드 Herdr 데몬으로 전파되지 않도록 완벽히 격리합니다.
- 외부 인터페이스나 CLI 인자의 변경 없이 내부 데몬 구동 신뢰성만을 개선한 전형적인 하위 호환 내부 버그 수정입니다.

2) Item 2: Class A 에이전트 0-turn resume fallback 및 Discovery Epoch 갱신 (`7e15081`)

수정 파일:
- .agents/skills/multi-agent-mux-resume/scripts/resume_session.sh
- .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh
변경 내용:
- resume_session.sh: resolve_session_id.sh 결과 UUID가 비어있는 경우, Class A 에이전트(agy, hermes, opencode)는 create_session.sh --role 호출 실패 대신 FRESH_SPAWN=1로 전환하여 spawn-spec 명령어로 자율 fallback 스폰.
- update_yaml_resumed.sh: --uuid 검증 가드를 완화하고, if not uuid: 조건 하에서 herdr_session_epoch = epoch, herdr_session_created_at = now, session_id_source = 'pending-discovery', session_id_verified = False를 원자적으로 재설정.
- Class B 불변성 보존: claude, grok은 기존 verify_session.py:99-101 escape hatch 및 test_t8 계약을 그대로 유지하며, 미식별 세션에 대한 RC=1 hard-exit 동작을 바이트 단위로 보존.
영향도 분석:
- 0-turn 중지된 Class A 세션 복원 시 발생하던 데드락/강제 종료 결함을 해소하고, reconcile.sh의 stale transcript 오인 매칭을 방지.
- 기존 정상 resume 동작이나 Class B 에이전트의 계약을 전혀 침해하지 않는 완전한 하위 호환 버그 수정입니다.

3. SemVer 2.0.0 기반 적정 버전 검토 (SemVer 2.0.0 Evaluation)

유의적 버전 2.0.0 (Semantic Versioning 2.0.0) 명세에 따른 각 버전 계열의 적합성 검토 결과는 다음과 같습니다:

버전 분류	SemVer 2.0.0 규칙	본 변경 사항 해당 여부	채택 여부	상세 논거
MAJOR (`v5.0.0`)	§8: 공개 API에 기존과 호환되지 않는 변경(Breaking Changes)이 도입될 때 증가	❌ 해당 없음	기각	- 기존 CLI 플래그, YAML 스키마, 어댑터 인터페이스 일체 보존 - Class B(`claude`, `grok`)의 기존 동작 및 검증 계약 100% 불변 - 사용자 워크플로우에 파괴적 변경 없음
MINOR (`v4.2.0`)	§7: 공개 API에 하위 호환성을 유지하는 신규 기능이 추가되거나 대규모 서브시스템이 신설될 때 증가	❌ 해당 없음	기각	- 신규 에이전트 어댑터 추가 없음 (v4.1.0 OpenCode 추가와 구별) - 신규 CLI 명령어나 스킬 신설 없음 - 기존 resume 스크립트의 비정상 종료 버그를 정상 동작하도록 내부 분기 처리한 것임
PATCH (`v4.1.3`)	§6: 하위 호환성을 유지하는 버그 수정(Bug Fixes)만 포함될 때 증가	✅ 완전 일치	적합 (선택)	- Issue #3의 2대 결함(데몬 시그널 전파 사망, 0-turn resume 데드락)에 대한 순수 결함 수정 - 기존 공개 인터페이스 완벽 호환 - 455개 전체 테스트 스위트 100% 무결점 통과

따라서 유의적 버전 규칙 및 업계 표준에 따른 가장 정확하고 타당한 목표 버전은 v4.1.3 (PATCH) 입니다.

4. 3-Way Version Lockstep 동기화 터치포인트 명세

본 프로젝트는 버전 일관성 유지를 위해 test_version_consistency.py를 통해 **3자 락스텝(3-Way Version Lockstep)**을 강제합니다. 후속 릴리스 패키징 작업 시 아래 지점들이 원자적으로 갱신되어야 합니다:

1) 런타임 진실 공급원 (Single Source of Truth)

.agents/skills/lib.sh
```
MAM_VERSION="4.1.3"
```

2) 버전 이력 및 매트릭스 (`VERSIONS.md`)

VERSIONS.md
- Line 9: - **프레임워크 버전**: v4.1.3``
- Line 10: - **최신 릴리스 일시**: 2026-08-31 (KST)
- Line 15: lib.sh 내 MAM_VERSION="4.1.3" 런타임 진실 공급원 정의...
- Line 21: ... 표준화를 통해 v4.1.3으로 동기화되어 배포됩니다.
- Line 23~33: 8개 스킬 버전 매트릭스 표 전체 4.1.2 \rightarrow 4.1.3 갱신
- Line 38 상단: 신규 v4.1.3 릴리스 체인지로그 섹션 삽입

3) 8개 스킬 메타데이터 (`SKILL.md` frontmatter)

.agents/skills/multi-agent-mux-create/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-stop/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-resume/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-status/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-monitor/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-delegate-job/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-loop/SKILL.md: version: 4.1.3
.agents/skills/multi-agent-mux-orc-onboard/SKILL.md: version: 4.1.3

4) 자동화 검증 계약

tests/test_version_consistency.py:
- test_three_way_version_lockstep(): lib.sh(MAM_VERSION) == VERSIONS.md(Current + Matrix 8 items) == 8x SKILL.md frontmatters 100% 일치 검증
- test_mam_version_is_not_env_overridable(): 환경변수 위조 차단 검증

5. `VERSIONS.md` 반영용 `v4.1.3` 체인지로그 초안

후속 릴리스 작업 시 VERSIONS.md에 추가될 표준 변경 이력 초안입니다:

### 🛠️ `v4.1.3` — Herdr Daemon Isolation & Class A 0-Turn Resume Reliability Fixes (2026-08-31)

> **주요 마일스톤 (PATCH Release)**: Issue #3 결함 해소 — Herdr 백그라운드 데몬의 `start_new_session=True` 기반 프로세스 그룹(setsid) 완전 격리, Class A(`agy`, `hermes`, `opencode`) 에이전트 0-turn 중지 세션의 `FRESH_SPAWN` fallback 및 discovery epoch 원자적 재설정, Class B(`claude`, `grok`) 계약 불변 보존, 455개 전체 테스트 스위트 100% PASS 달성.

#### 🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)
* **C-1: Herdr 데몬 프로세스 그룹(PGID/SID) 완전 분리 (`lib.sh`)**:
  - `.mam/shim/herdr` 템플릿의 `nohup ... & disown` 스폰 방식을 파이썬 `subprocess.Popen(..., start_new_session=True)` 기반 전용 스포너로 대체하여 자식 프로세스에서 `os.setsid()` 호출 보장.
  - 부모 셸이나 테스트 러너의 시그널 브로드캐스트(`SIGTERM`/`SIGINT`)로 인해 백그라운드 Herdr 데몬이 예기치 않게 종료되는 결함을 원천 차단 (`test_h26`).
* **C-2: Class A 에이전트 0-turn resume 자율 Fallback 및 Discovery Watermark 갱신 (`resume_session.sh`, `update_yaml_resumed.sh`)**:
  - 대화 턴이 발생하기 전에 중지된 Class A(`agy`, `hermes`, `opencode`) 세션 resume 시, UUID 미존재로 인한 비정상 hard-fail(RC=1) 대신 `FRESH_SPAWN=1`로 자동 전환하여 `spawn-spec` 기반의 정상 재스폰 수행 (`test_t14`).
  - fresh-spawn resume 시 `update_yaml_resumed.sh`에서 `herdr_session_epoch`를 resume 시점의 타임스탬프로 즉시 갱신하고 `session_id_source: pending-discovery`로 재설정하여, 세션 생성과 복원 사이에 생성된 무관한 이전 대화 파일이 `reconcile.sh`의 discovery sweep에 의해 오인 캡처되는 것을 방지 (`test_t16`).
  - Class B(`claude`, `grok`) 에이전트의 `verify_session.py:99-101` assigned escape hatch 및 `test_t8` 계약은 수정 없이 완벽히 보존 (`test_t15`).

6. 결론 및 피어 리뷰 요청 (Conclusion & Consensus Request)

최종 결론:
- Issue #3의 수정 사항은 프레임워크의 핵심 실행 라이프사이클에 직접적인 영향을 미치는 중요한 안정성 개선이므로 버전 업데이트가 필수적입니다.
- 변경의 성격은 100% 하위 호환성을 유지하는 결함 수정이므로, v4.1.3 (PATCH) 로 판정하는 것이 SemVer 2.0.0 규칙에 부합합니다.
리뷰어 피어 리뷰 요청:
- planner-reviewer-claude-01, reviewer-creator-grok-01, reviewer-opencode-01 세 리뷰어께 본 검토 보고서의 버전 판정 논리(v4.1.3 PATCH) 및 3-Way Lockstep 계획에 대한 검토와 합의를 요청드립니다.

12 KiB Raw Blame History