From 793a22158732357c0dbe4443989ccdc7e9a384c8 Mon Sep 17 00:00:00 2001
From: Godopu <godopu16@gmail.com>
Date: Wed, 5 Aug 2026 09:26:16 +0900
Subject: [PATCH] docs: add herdr-server to herdr-session transition task (A-5)
 to IMPROVEMENTS.md

---
 IMPROVEMENTS.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md
index b49ec6b..beecd38 100644
--- a/IMPROVEMENTS.md
+++ b/IMPROVEMENTS.md
@@ -1,8 +1,8 @@
-# 🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (`OPTIMIZATION.md`)
+# 🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (`IMPROVEMENTS.md`)
 
 - **최종 갱신일**: 2026-08-05
-- **통합 관리 대상**: 기존 `CODEBASE_REVIEW_REPORT.md` (코드베이스 잔여 결함 16건) + `OPTIMIZATION.md` (오케스트레이션 최적화 과제 3건)
-- **총 추적 미해결 과제**: **19건**
+- **통합 관리 대상**: 기존 `CODEBASE_REVIEW_REPORT.md` (코드베이스 잔여 결함 16건) + `OPTIMIZATION.md` (오케스트레이션 최적화 과제 3건) + Herdr 네이티브 명칭 전환 과제
+- **총 추적 미해결 과제**: **20건**
 
 ---
 
@@ -12,12 +12,20 @@
 
 ---
 
-## 1. 🔴 아키텍처 결함 (Architecture Flaws — 3건)
+## 1. 🔴 아키텍처 결함 및 네이티브 표준화 (Architecture Flaws — 4건)
 
 ### **A-1: herdr 서버명 전역 고정 및 타 워크스페이스 세션 오등록**
 - **현상**: `HERDR_SERVER_NAME`이 워크스페이스별 파생값이 아닌 `multi-agent-mux`라는 머신 전역 상수로 하드코딩되어 있습니다.
 - **파급 효과**: 한 머신에서 다수의 MAM 워크스페이스 사용 시, 백그라운드 모니터(`reconcile.sh` drift-B)가 다른 워크스페이스의 세션을 내 `.mam/agent-sessions.yaml` 레지스트리에 무단 등록하여 세션 오염을 발생시킵니다.
 
+### **A-5 (신규): `herdr-server` ➔ `herdr-session` Herdr 네이티브 명칭 정문화 전환**
+- **현상**: 과거 Tmux의 `-L <server_name>` 개념이 잔존하여 환경변수(`HERDR_SERVER_NAME`), CLI 옵션(`--herdr-server`), YAML 필드(`herdr_server`)라는 명칭을 사용 중임.
+- **문제점**: 실제 Herdr CLI의 네이티브 소켓 플래그는 `herdr --session <name>` (또는 `HERDR_SESSION_NAME`)으로, 기술적 용어 불일치로 인한 혼선 발생.
+- **해결 방안**:
+  1. 환경변수명 전환: `HERDR_SERVER_NAME` ➔ **`HERDR_SESSION_NAME`**
+  2. CLI 옵션 전환: `create_session.sh --herdr-server` ➔ **`--herdr-session`** (기존 옵션은 하위 호환 alias 보존)
+  3. YAML 필드 전환: `herdr_server:` ➔ **`herdr_session:`**
+
 ### **A-2: 공개 브로커 + HMAC 인증 Off + 와일드카드 전파**
 - **현상**: `mqtt_common.py`의 기본 브로커가 공개 서버(`broker.hivemq.com`), HMAC 무조건 True 반환으로 설정되어 있습니다.
 - **파급 효과**: 외부에서 유입되는 malicious `error` 이벤트 수신 시 `reconcile.sh`가 라이브 에이전트 pane을 `kill-session`으로 강제 파괴하는 치명적 보안/안정성 위험이 존재합니다.
@@ -100,4 +108,4 @@
 
 ## 5. 결론 및 향후 보완 로드맵
 
-두 문서가 `OPTIMIZATION.md` 하나로 통합됨에 따라, 향후 코드베이스 개편 시 본 문서의 19가지 백로그 항목(아키텍처 3건, 엣지케이스 8건, 오케스트레이션 3건, 레거시 잔재 5건)을 일원화된 보완 로드맵으로 관리합니다.
+두 문서가 `IMPROVEMENTS.md` 하나로 통합됨에 따라, 향후 코드베이스 개편 시 본 문서의 20가지 백로그 항목(아키텍처 4건, 엣지케이스 8건, 오케스트레이션 3건, 레거시 잔재 5건)을 일원화된 보완 로드맵으로 관리합니다.