# 📋 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 적용 터치포인트**를 종합 검토한 결과를 제시합니다.

### 📌 핵심 결론 요약
1. **버전 업데이트 필요성**: **필수 (REQUIRED)**  
   - 프레임워크 런타임 진실 공급원인 `.agents/skills/lib.sh` 및 복원 스킬의 핵심 라이프사이클 스크립트(`.agents/skills/multi-agent-mux-resume/scripts/`)에 실제 런타임 버그 수정이 반영되었으며, 신규 회귀 테스트(`test_h26`, `test_t14`, `test_t15`, `test_t16`)가 추가되었으므로 릴리스 패키징 및 버전 추적이 반드시 수행되어야 합니다.
2. **적정 목표 버전 번호**: **`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자 동기화(3-Way Lockstep)를 원자적으로 일괄 수행할 것을 제안합니다.

---

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

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

### 1) Item 1: Herdr 데몬 프로세스 그룹 완전 분리 (`c49ee3b`)
- **수정 파일**: [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh#L207-L224)
- **변경 내용**: `.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`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh#L50-L136)
  - [`.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh#L165-L178)
- **변경 내용**:
  - `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 스키마, 어댑터 인터페이스 일체 보존<br>- Class B(`claude`, `grok`)의 기존 동작 및 검증 계약 100% 불변<br>- 사용자 워크플로우에 파괴적 변경 없음 |
| **MINOR (`v4.2.0`)** | **§7**: 공개 API에 하위 호환성을 유지하는 신규 기능이 추가되거나 대규모 서브시스템이 신설될 때 증가 | ❌ 해당 없음 | **기각** | - 신규 에이전트 어댑터 추가 없음 (v4.1.0 OpenCode 추가와 구별)<br>- 신규 CLI 명령어나 스킬 신설 없음<br>- 기존 resume 스크립트의 비정상 종료 버그를 정상 동작하도록 내부 분기 처리한 것임 |
| **PATCH (`v4.1.3`)** | **§6**: 하위 호환성을 유지하는 버그 수정(Bug Fixes)만 포함될 때 증가 | ✅ **완전 일치** | **적합 (선택)** | - Issue #3의 2대 결함(데몬 시그널 전파 사망, 0-turn resume 데드락)에 대한 순수 결함 수정<br>- 기존 공개 인터페이스 완벽 호환<br>- 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`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh#L16)
  ```bash
  MAM_VERSION="4.1.3"
  ```

### 2) 버전 이력 및 매트릭스 (`VERSIONS.md`)
- [`VERSIONS.md`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/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`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/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`에 추가될 표준 변경 이력 초안입니다:

```markdown
### 🛠️ `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)

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