# 📜 Multi-Agent Mux 버전 이력 (`VERSIONS.md`)

이 문서는 `multi-agent-mux` 프레임워크의 버전별 주요 기능 추가, 아키텍처 개선, 버그 수정 및 품질 검증 이력을 기록합니다.

---

## 📌 현재 버전 개요 (Current Release)

- **프레임워크 버전**: `v3.0.1`
- **최신 릴리스 일시**: 2026-08-27 (KST)
- **기준 브랜치**: `main`
- **핵심 아키텍처**:
  - **Herdr Shim Routing & Multi-Workspace Isolation Engine**: `HERDR_WORKSPACE_ID` 환경 변수 스코핑 및 `$WORKSPACE_ROOT/.mam/herdr_workspace_id` 영속화 메커니즘을 통해 다중 워크스페이스 동시 실행 시 페인 교차 오염 원천 차단
  - **Atomic Safe Paste Insertion (`pane send-text`)**: 미지원 서브커맨드(`agent send`) 제거 및 `pane send-text` 단일 삽입 계약 도입, `send_keys_safe` 실패 전파(`rc 3`) 및 중복 제출(Double Submit) 방지
  - **Strict Exact-Match Single Pane Resolver**: 부분 문자열 매칭(`in tn`) 완전 제거, 단일 중앙 `_resolve_herdr_pane_id` 헬퍼 기반 5대 서브커맨드(`has-session`, `kill-session`, `capture-pane`, `send-keys`, `paste-buffer`) 무결성 정립
  - **TUI Readiness & Dialog Token Precision**: `_MAM_DIALOG_TOKENS` 일반 팁(`Yes, try it`) 오탐 제거 및 풀스크린 모달 Escape 거절 브랜치 분리
  - **Comprehensive Test Suite Milestone**: 412개 전체 테스트 100% PASS (412 passed / 0 failed).

---

## 🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)

모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v3.0.1`으로 동기화되어 배포됩니다.

| 스킬명 | 버전 | 역할 및 주요 책임 | 상태 |
| :--- | :---: | :--- | :---: |
| **`multi-agent-mux-create`** | `3.0.1` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
| **`multi-agent-mux-stop`** | `3.0.1` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
| **`multi-agent-mux-resume`** | `3.0.1` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
| **`multi-agent-mux-status`** | `3.0.1` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
| **`multi-agent-mux-monitor`** | `3.0.1` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
| **`multi-agent-mux-delegate-job`** | `3.0.1` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
| **`multi-agent-mux-loop`** | `3.0.1` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
| **`multi-agent-mux-orc-onboard`** | `3.0.1` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |

---

## 📋 버전별 상세 변경 내역 (Changelog)

### 🚀 `v3.0.1` — Herdr Shim Routing Contract Refactor, Multi-Workspace Isolation & 412-Test Milestone (2026-08-27)

> **주요 마일스톤**: Herdr 심 라우팅 5대 결함(ISSUE-1~5) 및 F-1~F-4 보완 완결, `HERDR_WORKSPACE_ID` 환경 변수 스코핑 및 파일 기반 격리 영속화 엔진 탑재, `pane send-text` 기반 단일 안전 삽입 계약 정립, 부분 문자열 매칭(`in tn`) 완전 제거, 412개 전체 테스트 100% PASS 달성.

#### 1. Herdr 심 라우팅 및 다중 워크스페이스 격리 강화 (`.agents/skills/lib.sh`)
* **`HERDR_WORKSPACE_ID` 명시적 스코프 & 영속화 (`ISSUE-3`, `F-2b`)**:
  - `_herdr_ws_id_file()`, `_herdr_persist_ws_id()`, `_herdr_ws_scope()` 헬퍼 도입.
  - `new-session` 시 생성된 워크스페이스 ID를 `$WORKSPACE_ROOT/.mam/herdr_workspace_id`에 영속화.
  - `_herdr_agent_get_scoped`는 호출자의 환경변수(`HERDR_WORKSPACE_ID`)만을 우선 평가하여 단축 경로에서의 교차 워크스페이스 라우팅 오염 차단.
* **엄격 일치(Exact-Match) 단일 페인 리졸버 정립 (`ISSUE-2`, `ISSUE-5`, `F-3`)**:
  - 기존의 에이전트 CLI 명칭 부분 문자열 매칭(`in tn`, `agent in tn`) 완전 제거.
  - 단일 중앙 헬퍼 `_resolve_herdr_pane_id`로 `has-session`, `kill-session`, `capture-pane`, `send-keys`, `paste-buffer`의 페인 해석 통합.
  - 영숫자 워크스페이스 식별자 패턴(`^w[A-Za-z0-9]+:p[A-Za-z0-9]+$`) 지원 (`H-20`).

#### 2. 원자적 텍스트 삽입 및 안전 전송 계약 교정 (`ISSUE-1`, `F-4`)
* **`paste-buffer`의 `pane send-text` 전용화**:
  - Herdr CLI에 미존재하던 `agent send` 제거 및 `pane send-text`로 교체.
  - 삽입과 제출(Enter) 책임을 분리하여 의도치 않은 자동 제출 및 이중 제출(Double Submit) 방지.
  - 페인 미해석 또는 삽입 실패 시 `send_keys_safe`로 에러 코드(`rc 3`) 명시적 전파.
* **`capture-pane` 폴백 체인 복원 (`F-4`)**:
  - `pane read` 실패 시 `agent read`로의 폴백 체인을 안정적으로 복원하여 TUI 캡처 신뢰성 보장.

#### 3. TUI 준비 상태 감지 및 다이얼로그 토큰 정밀화 (`N-1`, `F-1`)
* **`_MAM_DIALOG_TOKENS` 일반 팁 토큰 분리**:
  - 일반 대화형/TUI 팁에 등장하는 `Yes, try it`을 블로킹 다이얼로그 토큰 목록에서 제외하여 세션 시작 시의 오탐 방지.
  - 풀스크린 업셀 모달에 대해서는 전용 Escape 거절 브랜치로 격리 처리.

#### 4. 테스트 스위트 및 Mock Herdr 계약 정기 동기화 (`tests/`)
* **Mock Herdr (`tests/conftest.py`)**: 실제 Herdr 0.8.2 CLI 계약과 완벽 동기화 (`pane send-text`, `pane read`, `pane rename` 반영, 미지원 `agent send` 실패 처리).
* **신규 계약 & 회귀 테스트 19건 추가**:
  - `test_herdr_shim_contract.py`: H-15 ~ H-23 (단일 리졸버 불변식, 워크스페이스 격리, 단축경로 스코핑).
  - `test_b19_headless_reconcile_fixes.py`: D-4 ~ D-7 (set -e 안전성, send_keys_safe 실패 전파, 다이얼로그 토큰 제외 회귀 방지).
* **전체 테스트 결과**: 412 passed in 681.20s (100% PASS).

---

### 🚀 `v3.0.0` — 5th Agent (Grok) Ecosystem Expansion, Mux Loop CLI Redesign & Deterministic 2xK Layout Engine 2.0 (2026-08-26)

> **주요 마일스톤**: 5번째 공식 에이전트 `grok`(Grok Build) 전면 통합, `/multi-agent-mux-loop`의 `--target-agent` 폐지 및 `--creator`/`--planner` 역할 분리(Breaking Change), 2×2 대칭 그리드를 보장하는 결정론적 레이아웃 엔진 2.0 탑재, 393개 전체 테스트 100% PASS 달성.

#### ⚠️ Breaking Changes & Migration Guide
* **`multi-agent-mux-loop` CLI 플래그 개편**:
  - 기존의 단일 대상 지정 플래그 `--target-agent <session>`가 **공식 제거(Drop)** 되었습니다.
  - 기존 명령은 이제 `ERROR: --target-agent was removed. Use --creator <session> instead.`와 함께 종료(`exit 1`)됩니다.
  - **마이그레이션 방법**:
    - 기존: `bash run_loop.sh --target-agent <dev-session> --task "..."`
    - 변경: `bash run_loop.sh --creator <dev-session> --task "..."`
    - 플래너 지정 시: `bash run_loop.sh --plan --planner <plan-session> --creator <dev-session> --task "..."`

#### 1. 5번째 공식 AI 에이전트 Grok Build (`grok`) 전면 통합
* **어댑터 및 수명 주기 관리 (`lib_py/agents/`, `lib.sh`)**:
  - `GrokAgentAdapter` 구현 및 레지스트리 공식 등록 (`claude, agy, hermes, cline, grok`).
  - `create_session.sh`, `resume_session.sh`, `stop_session.sh`, `resolve_session_id.sh`의 에이전트 화이트리스트 및 디스패치 지원 완비.
  - 온디스크 세션 UUID 해석 및 TUI 렌더링 준비 감지 토큰 반영.

#### 2. 결정론적 2×K 그리드 레이아웃 엔진 2.0 (`lib_py/layout.py`, `lib.sh`)
* **$N=1\to 2$ `right` 분할 우선 정책 (R-1 결함 해소)**:
  - 1개 페인에서 2번째 에이전트 추가 시 `down` 대신 `right`로 분할(`single_pane_split_right`)하여 좌/우 2개의 전고(Full-height) 열 확보.
  - 이후 $N=3$(좌측 down), $N=4$(우측 down)로 이어져 완벽한 2×2 균등 대칭 격자 기하학(`widths=[138,139], heights=[39]`) 완성.
* **GUI ↔ 헤드리스 단일 결정표 통합 (`_decide_from_cols`)**:
  - 기존의 불완전한 `n % 2` 홀짝 패리티 로직을 폐기하고, 열 점유 상태(`cols=(a, b)`) 기반의 통합 3단계 결정 매트릭스로 일원화.
* **안전 가드 및 4중 용량 배선**:
  - `_full_height_pane` 가드로 반쪽 열 분할 원천 차단.
  - `layout.py` 기본값(`default=2`), `lib.sh:435` CLI 인자(`--max-cols`, `--max-rows`), `.mam.env.example` 동기화 완료.

#### 3. 사전 검증 및 인프라 동기화
* `create_session.sh`의 `--workspace` 필수 인자 사전 검증(preflight) 강화.
* 사설 NATS 브로커(`nats-docker`) 2.14-alpine 최신 태그 동기화.

---

### 🚀 `v2.2.1` — Single-Workspace 2xK Multi-Pane Tiling Optimization & Premature Overflow Fix (2026-08-24)

> **주요 마일스톤**: `MAM_MIN_PANE_COLS` 기본값 60→40 완화, 표준 80~100컬럼 터미널 뷰포트에서 조기 워크스페이스 오버플로(가상 데스크톱 분리) 방지 및 단일 워크스페이스 2x2 통합 타일링 완성, 신규 80/79 경계 및 90/100 col 타일링 테스트 6종 추가, 다중 에이전트 피어 리뷰 100% PASS 달성.

#### 1. 2xK 레이아웃 엔진 최소 폭 완화 (`lib_py/layout.py`, `lib.sh`)
- `compute_2xk_layout` 기본 `min_cols` 및 CLI `--min-cols`, `lib.sh:432`의 `${MAM_MIN_PANE_COLS:-40}`, `.mam.env.example` 문서를 `40`으로 4중 일치화.
- 90~100컬럼 너비 터미널에서 3번째, 4번째 에이전트 생성 시 불필요하게 가상 데스크톱(Workspace)이 분리되던 현상 완전 해소.

#### 2. 경계값 및 타일링 자동화 테스트 확충 (`tests/test_layout.py`, `tests/test_tier1_unit.py`)
- `80` 컬럼(분할 성공) vs `79` 컬럼(오버플로) 하한 경계값 검증.
- `90` 및 `100` 컬럼 단일 워크스페이스 1→2→3→4 단계 2x2 타일링 및 5번째 에이전트 오버플로 전 과정 수명 주기 검증.

---

### 🚀 `v2.2.0` — Herdr Workspace Label Standardization, Runtime Sync & Legacy Fallback Decoupling (2026-08-24)

> **주요 마일스톤**: `--herdr-workspace` 옵션 전 스킬 도입 및 YAML 독립 직렬화, Herdr 런타임 워크스페이스 레이블 실시간 동기화, 레거시 소켓 폴백 체인 분리(Breaking Change 방어), 최신 Claude Code TUI 감지 토큰 반영, 27개 신규 테스트 추가 및 만장일치 PASS 달성.

#### 1. `--herdr-workspace` 옵션 도입 및 Herdr 런타임 레이블 동기화
- **CLI 옵션 및 YAML 직렬화 표준화**:
  - `create_session.sh`, `resume_session.sh`, `update_yaml_resumed.sh`, `stop_session.sh`에 `--herdr-workspace <name>` 파서 및 환경변수(`HERDR_WORKSPACE`) 지원 추가.
  - `agent-sessions.yaml`에 `herdr_session`(소켓명)과 `herdr_workspace`(워크스페이스 라벨)를 각각 독립 필드로 영구 직렬화.
- **Herdr 런타임 워크스페이스 레이블 실시간 연동 (`lib.sh`, `resume_session.sh`)**:
  - `herdr workspace create` 호출 시 `--label "$MAM_WS_LABEL"` 전달 및 기존 워크스페이스 사용 시 `herdr workspace rename` 자동 호출.
  - `resume_session.sh` 실행 시 저장된 `herdr_workspace`를 읽어 Herdr 런타임 레이블 복원 보장.

#### 2. 레거시 소켓 폴백 체인 분리 및 Breaking Change 원천 차단
- **소켓 vs 워크스페이스 함수 완전 분리 (`lib.sh`)**:
  - `resolve_herdr_session()`: 데몬/소켓 세션명만 반환 (row `herdr_session` -> row `herdr_server` -> env -> slug).
  - `resolve_herdr_workspace()`: 워크스페이스 라벨만 반환 (row `herdr_workspace` -> `pane.cwd` slug -> caller `ws` arg).
  - 기존 코드베이스 6개 지점(`lib.sh:1027`, `reconcile.sh:135, 399, 495`, `status.sh:145, 270`)에서 소켓 검색 시 `herdr_workspace`를 오인 참조하던 구문을 완전히 제거.
- **외부 세션 입양(Drift-B) 보강 (`reconcile.sh`)**:
  - 외부 세션 입양 시 `herdr_workspace`와 `herdr_server`를 자동 채번 및 직렬화.

#### 3. 최신 에이전트 TUI 준비 감지 보강 (`claude.py`, `lib.sh`)
- 최신 Claude Code(`v2.1.241`)의 시작 배너(`Claude Code`, `Opus 5 with high effort` 등)를 `ready_tokens`에 추가하여 세션 생성 타임아웃 방지.

---

### 🚀 `v2.1.0` — 2xK Grid Layout Engine, Explicit Agent Standardization & Herdr Session Hardening (2026-08-24)

> **주요 마일스톤**: 2xK 우측 성장 그리드 레이아웃 엔진(`lib_py.layout`) 구축(B-20), 전 스크립트 `--agent` / `--herdr-session` 표준화 및 전파 가드, 전체 346개 테스트 스위트 100% PASS 달성.

#### 1. 2xK 우측 성장 그리드 레이아웃 엔진 구축 (B-20 / I-2, I-3, C-1, J-1)
- **순수 파이썬 레이아웃 엔진 신설 (`lib_py/layout.py`)**:
  - `tput` 기반 터미널 크기 동적 감지 및 2xK(2행 고정, 우측 열 추가) 그리드 기하학 계산 엔진 구현.
  - 패널 번호 순서(0:좌상, 1:좌하, 2:중상, 3:중하...)에 따른 우측 확장 타일링 분할 명령(`split-pane -h/-v`, `select-pane`) 계산.
  - 헤드리스/CI 최소 차원(최소 너비 60, 최소 높이 20) 가드 및 `default=60` falsy-zero trap 해결 (`_env_int`).
- **33개 신규 레이아웃 단위/회귀 테스트 구축 (`tests/test_layout.py`)**:
  - 1~8개 패널 수식 검증, 비정상 인자/환경변수 방어, 무한 루프 방지 가드 검증.

#### 2. 에이전트 인자 표준화 및 레지스트리 자동 추론
- `stop_session.sh`, `create_session.sh`, `resume_session.sh`, `update_yaml_resumed.sh`, `resolve_session_id.sh` 전반에 걸쳐 `--agent <claude|agy|hermes|cline>` 명시적 표준화.
- 미지정 시 YAML 레지스트리(`agent-sessions.yaml`) 기반 에이전트 타입 자동 추론(`resolve_agent_type_from_registry`) 연동.

#### 3. `--herdr-session` 격리 세션 옵션 표준화 및 전파 가드
- `create_session.sh`, `resume_session.sh`, `stop_session.sh`, `update_yaml_resumed.sh` 전반에 `--herdr-session <NAME>` 표준 옵션화 (레거시 `--herdr-server` 완전 호환).
- `create_session.sh`에서 명시적 세션명이 워크스페이스 슬러그에 의해 덮어씌워지지 않도록 가드 보강.
- `resume_session.sh`의 post-spawn 재개 시 신규 Herdr 세션명이 YAML 레지스트리에 정확히 전파되도록 갱신 로직 및 신규 Tier 2 테스트 5건 추가.

#### 4. 테스트 스위트 확장 및 피어 리뷰 전원 만장일치 PASS
- 전체 테스트 스위트 수 **276건 → 346건 (100% PASS)** 확장.
- Multi-Agent Loop를 통한 Reviewer(`claude`, `cline`) 전원 `[VERDICT: PASS]` 검증 완료.

---

### 🚀 `v2.0.0` — Unified Agent Adapter Architecture & Herdr Standardization (2026-08-17)

> **주요 마일스톤**: 에이전트 지식 계층 단일 소스화(A-4), 레거시 격리 완전 폐기(Option B), 셸 브리지 하드닝 및 스킬 메타데이터 규격화 완료.

#### 1. 에이전트 지식 계층 마이그레이션 (A-4 Phase 2 / P3-1)
- **`BaseAgentAdapter` 추상 클래스 및 4대 어댑터 구축**:
  - [`.agents/skills/lib_py/agents/base.py`](.agents/skills/lib_py/agents/base.py): `DiscoveryContext` 및 추상 인터페이스 정의 (`ready_tokens`, `exit_key`, `delegate_agent_key`, `identity_cache_fields`, `artifact_path`, `verify_artifact`, `purge_artifacts`, `spawn_spec`, `resume_spec`, `auth_ok`, `discover`).
  - [`.agents/skills/lib_py/agents/adapters/`](.agents/skills/lib_py/agents/adapters/): `ClaudeAgentAdapter`, `AgyAgentAdapter`, `HermesAgentAdapter`, `ClineAgentAdapter` 4개 구체 클래스 구현.
- **`facts` 브리지 셸 인터페이스 하드닝**:
  - `lib_py.agents` CLI 모듈을 통해 8개 `MAM_*` 변수를 `shlex.quote` 안전 인용 처리하여 방출.
  - `wait_for_tui_ready` 빈 토큰 시 전량 매칭 오탐 방지 및 미지 에이전트 fail-closed 가드 내장.
- **셸 스크립트 전반 어댑터 이관**:
  - `create_session.sh`, `resume_session.sh`, `stop_session.sh`, `reconcile.sh`에 산재되어 있던 40여 개 하드코딩 분기를 어댑터 호출로 일원화.

#### 2. 레거시 `isolation.root` 및 C-3b 소비자 완전 폐기 (Option B)
- Universal Global Config 전환 이후 남아있던 4개 레거시 격리 소비자 코드(`lib.sh::mam_session_iso_root`, `workspace_uuid.py::iso_root_of`, `verify_session.py`, `stop_session.sh`) 및 `atomic_yaml.py`의 레거시 유효성 검사 절 100% 삭제.
- 저장소 내 격리 잔재 참조 0건 달성.

#### 3. 셸 브리지 보안 및 예외 처리 강화 (R1, R2, N1 교정)
- **R1 (위임 에이전트 키 폴백 보강)**: 브리지 미작동 시 `delegate_agent`가 `antigravity-cli`로 일괄 퇴화하지 않고 `claude-code`, `hermes-agent`, `cline-agent`로 명시적 `case` 폴백하도록 개선.
- **R2 (`argv` 서브커맨드 전환)**: `python -c` 셸 변수 문자열 보간을 `spawn-spec`, `resume-spec`, `exit-key` 서브커맨드로 전면 전환하여 공백/작은따옴표 경로 에러 및 코드 주입 위협 원천 차단.
- **N1 (클린 환경 격리 가드)**: `test_a4_adapter_contract.py` 내 CLI 테스트가 앰비언트 `PYTHONPATH` 없이도 독립 통과하도록 환경 격리 보강.

#### 4. 스킬 메타데이터 규격화 및 피어 리뷰 100% PASS
- 8개 `SKILL.md` frontmatter `version: 2.0.0` 통일 및 배포 무결성 검증.
- Reviewer `cline` (Job `e7b9812b`) 및 Planner/Senior Reviewer `claude` (Job `31730364`) 전원 `[VERDICT: PASS]` 획득.

#### 5. 레거시 주석 및 사용법 정합성 최신화 (C-6)
- `stop_session.sh` 상단 주석 및 `usage()` 내 폐기된 플래그(`--mode soft|hard`, `--capture-id`, `--graceful`) 안내 문구를 완전 제거하고 현행 4대 에이전트(`claude`, `agy`, `hermes`, `cline`) 및 플래그 체계로 동기화.
- 회귀 방지 컴포넌트 테스트(`test_comp_stop_usage_matches_parser`) 신설.
- 회귀 및 계약 테스트: **263/263 PASS (100%)** 달성.

#### 6. macOS NFS 감지 `df -P` 폴백 검증 및 종결 (B-5)
- `_check_is_nfs`(`lib.sh`)의 macOS/BSD 환경 내 GNU 전용 `df --output` 구문 오류 시 POSIX `df -P` 폴백 동작을 실측 및 단위 테스트(`test_stop_check_is_nfs_local`)로 검증 완료하여 B-5 이슈를 정식 종결.

#### 7. `agent_identities` tier-3 신원 캐시 완전 제거 및 UUID 해결 경로 PyYAML 탈의존 (B-10 / Option A)
- 쓰기 경로가 존재하지 않아 구조적으로 히트 불가였던 tier-3 폴백과 부속 소비자(`workspace_uuid.py`, `reconcile.sh` drift D, `stop_session.sh` 캐시 소거)를 전면 삭제.
- UUID 해결 경로를 **tier-1(per-row own id) → tier-2(어댑터 `discover()`)** 2단계로 단순화.
- `verify_session.py::mam_orchestrator_uuids` 의 즉시 `yaml` import 를 YAML 폴백 분기로 이동, UUID 해결 경로가 PyYAML 없이 완주함을 실행 가드로 고정(`atomic_yaml.py` 의 시스템 PyYAML 요구는 설계상 유지).
- 회귀 가드 3종 신설 — 읽기 경로 부활 차단, `import yaml` AST 검사(지연 import 포함), 실행 경로 검증.
- 회귀 및 계약 테스트: **266/266 PASS (100%)** 달성.

#### 8. 셀프 호스팅 루프 런타임 프리즈 스냅샷 (B-13 / Stage 2)
- 루프 기동 시 `.agents/skills/` 를 `$TMPDIR` 에 1회 동결하고 스냅샷에서 재실행하여, 턴 도중 프레임워크 스킬 편집이 진행 중인 루프를 깨뜨리지 못하도록 차단.
- 코드 루트(스냅샷)와 상태 루트(`MAM_REAL_ROOT`)를 분리해 레지스트리·루프 락·diff 수집은 실제 저장소를 계속 사용.
- 재실행 시 원본 argv 를 배열로 보존해 인자 유실을 방지(파서가 `$@` 를 소비하므로 필수).
- 스냅샷 생성 실패 시 `log_*` 정의 이전 구간임을 고려해 `echo` 로 경고하고 미동결 진행.
- `MAM_LOOP_NO_FREEZE=1` 로 비활성화 가능. 스냅샷 생성 실패는 경고 후 기존 동작으로 폴백.
- 회귀 가드 5종 신설 — argv 보존, 파손 래퍼 면역, 스킬 트리 무오염(B-6 경계), 락 해제 및 스냅샷 정리(B-12 경계), 비활성화 스위치.
- 회귀 및 계약 테스트: **271/271 PASS (100%)** 달성.

#### 9. 감사 로그 루트 지연 평가 (B-9 / P4-1)
- `mqtt_common.LOGS_DIR` 의 import 시점 cwd 고정을 제거하고 호출 시점에 해석하는 `get_logs_dir()` 를 도입. `chdir` 이후에도 감사 로그가 현재 워크스페이스에 정확히 기록됨.
- PEP 562 모듈 `__getattr__` 로 `LOGS_DIR` 속성 접근 하위 호환 유지(동적 평가).
- PEP 562 `__dir__` 병행 정의로 `dir()`·탭 완성 가시성 유지.
- `DELEGATE_JOB_LOGS_DIR` 환경변수가 실행 중 변경까지 반영.
- 회귀 가드 5종 신설 — cwd 추종, 실제 파일 생성, 환경변수 동적 반영, 전역 재도입 차단, dir() 탐색성.
- 회귀 및 계약 테스트: **276/276 PASS (100%)** 달성.

---

### 🛠️ `v1.4.0` — Stability, Cleanup & Safe Job Delegation (2026-08-16)

> **주요 마일스톤**: 격리 잔재 정리, 서브셸 루프 락 조기 해제 버그 픽스, 신규 파일 캡처 및 경량화.

- **P2-2 (C-3a / C-4 레거시 격리 스텁 및 미사용 심볼 제거)**:
  - `lib.sh` 내 빈 스텁 4종(`provision_isolation`, `isolation_lever`, `isolation_env_prefix`, `isolation_cmd_args`) 및 `_REAL_HERDR_PATH` 완전 삭제.
  - `registry.py::TERMINAL_STATUSES` 및 `create_session.sh::ISOLATE` 제거.
- **P2-1 (B-6 / B-12 `delegate_job_safe` 안정화)**:
  - `.agents/skills/...` 내 불필요한 `.tmp` 복사본 생성 제거 및 인플레이스 직접 실행(`bash "$orig_script"`) 전환.
  - 서브셸 내 `trap`으로 인한 루프 락 마커(`.mam/loop-guard-active`) 조기 삭제 결함(D1) 원천 차단.
- **P0-2 (O-2 중복 루프 기동 방지 원자적 락)**:
  - `loop_lock.sh` 신설: `set -C` 기반 원자적 락 획득 및 PID + lstart 소유권 검증으로 동시 실행 방지.
- **P0-1 (B-7 외곽 diff 수집 및 미추적 파일 캡처)**:
  - `diff_collect.sh` 도입: CWD 독립 `$REPO_ROOT` 기준 diff 수집 및 `git ls-files -o` 미추적 파일 병합.
- **B-4 (시프트 `ls` 동적 포시스 타임스탬프 복원)**:
  - `lib.sh` 554행의 `created=999999` 하드코딩을 실시간 타임스탬프(`int(time.time())`)로 복원.
- **테스트 슈트 경량화**:
  - 노후화된 중복 레거시 테스트 7개 파일(1,559줄) 삭제 (`cf51b2c`).

---

### 🛡️ `v1.3.0` — Orchestrator Onboarding & Scoped Guarding (2026-08-15)

> **주요 마일스톤**: 오케스트레이터 신원 격리 및 다중 에이전트 협업 가드레일 확립.

- **`multi-agent-mux-orc-onboard` 스킬 신설**:
  - 오케스트레이터(`agy`)의 대화 UUID를 `.mam/agent-sessions.yaml` 내 `orchestrator_uuids` 리스트로 등록.
  - `find_workspace_uuid` 및 `verify_session_uuid`에서 오케스트레이터 UUID를 스킵하여 서브에이전트 세션 오염 방지.
- **O-3 (조건부 오케스트레이션 위임 가드 — Scoped Guard)**:
  - 오케스트레이터가 `/multi-agent-mux-loop` 활성화 상태에서 직접 코드를 수정하지 않고 스크립트로 위임하도록 통제.
  - `AGENTS.md` §5 및 `MULTI_AGENT_RULES.md` 내 가드레일 명시.
- **배포 및 패키징 파이프라인 현대화**:
  - `deploy/lib_ownership.sh` 신설 및 `hooks.json` 3-way 병합(`MERGE_REGISTRY`) 지원.
  - Gitea CI/CD 파이프라인 (`deploy/gitea-ci.yml`) 연동.

---

### 🔌 `v1.2.0` — Universal Herdr Server Isolation & Cline Integration (2026-08-14)

> **주요 마일스톤**: Herdr 단일 서버 격리 및 다중 AI 에이전트 확장.

- **Universal Herdr Session Isolation**:
  - `HERDR_SESSION_NAME` 기반으로 격리 서버를 통일하여 프로세스 충돌 방지.
- **Cline 에이전트 통합**:
  - `cline` CLI 기반 대화 세션 생성, 정지, 복원 및 TUI 레디 토큰 핸들링 지원.
- **SQLite WAL 트랜잭션 동시성**:
  - 세션 레지스트리 동시 쓰기 시 발생하는 락 충돌을 방지하기 위해 SQLite WAL 모드 전면 적용.

---

### 🧱 `v1.0.0` ~ `v1.1.0` — Initial Multi-Agent Mux Framework (2026-08-10 ~ 2026-08-13)

> **주요 마일스톤**: 터미널 다중 에이전트 오케스트레이션 기초 설계 및 비동기 루프 완성.

- **핵심 수명주기 스킬군 구축**: `create`, `stop`, `resume`, `status`, `monitor` 스킬 기본 구현.
- **MQTT 기반 비동기 잡 위임**: `multi-agent-mux-delegate-job`을 통한 에이전트 간 이벤트 통신 및 결과 구독.
- **자율 협업 루프**: `multi-agent-mux-loop` 컨트롤러를 통한 Planner-Creator-Reviewer 역할 분담 체계 정립.

---

## 🧪 품질 보증 및 검증 기준 (Verification Standards)

모든 릴리스는 다음 4단계 엄격한 검증을 통과해야 배포됩니다:
1. **정적 문법 검사**: `bash -n` (모든 셸 스크립트) 및 AST 미사용 코드 분석.
2. **단위 및 컴포넌트 테스트 (Tier 1~2)**: 인플레이스 및 컴포넌트 간 상호작용 검증.
3. **통합 및 계약 테스트 (Tier 3~4 / Contract)**: clean environment (`env -u PYTHONPATH`) 하에서의 어댑터 계약 및 CLI 브리지 검증.
4. **멀티에이전트 교차 피어 리뷰**: Planner(`claude`) 및 Reviewer(`cline`) 간 교차 검증 및 `[VERDICT: PASS]` 100% 합의.