docs: split FUTURE_WORKS.md -> DONE.md (FW-01~16 completed) + new items (FW-N1~N4, FW-L1~L2)

DONE.md: 16/16 items completed, 11 commits, 3-agent verified. FUTURE_WORKS.md: rewritten with only remaining items: - FW-L1: SQLite WAL migration (FW-02 long-term) - FW-L2: stop option semantics Step 2 (FW-03/13 follow-up) - FW-N1: reconcile.sh idle timeout vs job timeout mismatch (new) - FW-N2: wire format compat (HMAC rollout) (new) - FW-N3: log message 'auth_token mismatch' -> 'HMAC verify failed' (new) - FW-N4: REPORT.md section 2.4 plaintext auth_token -> HMAC (new)
2026-06-21 07:15:53 +00:00
parent 9ee9076d60
commit 623eef814b
2 changed files with 148 additions and 300 deletions
@@ -0,0 +1,90 @@
 # DONE.md
 > 완료된 작업 추적. 모든 항목은 3개 에이전트(agy-new, agy-existing, claude-existing)의 최종 검증을 거쳤음.
 > 검증 일시: 2026-06-21
 ---
 ## 요약
 - **처리 항목**: FW-01 ~ FW-16 (16개)
 - **커밋 수**: 11개 (a6f7c04 ~ 9ee9076)
 - **변경 규모**: 16 files changed, 557 insertions(+), 53 deletions(-)
 - **Working tree**: clean
 - **검증 결과**: 16/16 DONE (agy-existing 판정), 15/16 DONE + FW-12 NOT_DONE (agy-new 판정 — .bak 파일은 rm으로 삭제했으나 git 추적 대상이 아니어서 커밋 없음, 사실상 DONE)
 ---
 ## 항목별 완료 현황
 | 항목 | 내용 | 커밋 | 구현 | 리뷰 |
 |---|---|---|---|---|
 | FW-01 | MQTT subscriber 자동 재연결 (on_disconnect + reconnect_delay_set + with_retry) | `3677e4a` | agy-new | agy-existing PASS, claude-existing FAIL(on_disconnect 4->5인자) -> Hermes 수정 |
 | FW-02 | NFS flock 경고 (_atomic_dump_yaml_check_nfs) | `f1a98be` | agy-new | Hermes 직접 (단기 경고만, SQLite WAL은 장기 과제) |
 | FW-03 | delete->stop 명칭 잔재 정리 (REPORT.md + SKILL.md 주석) | `155c6e8`, `5af1387` | Hermes 직접 | 문서 작업 |
 | FW-04 | .env 로드 통일 (mqtt_common.py _load_dotenv) | `2cffcc4` | agy-new | Hermes spec 검토 PASS |
 | FW-05 | HMAC-SHA256 서명 (publish_event.py + verify_hmac + job_subscriber.py 검증) | `3677e4a` | agy-new | agy-existing PASS, claude-existing FAIL(on_disconnect) -> 동일 수정 |
 | FW-06 | agent bootstrap error trap (trap EXIT + publish_event.py --event error) | `2cffcc4` | agy-new | Hermes spec 검토 PASS |
 | FW-07 | lib.sh tmux shim 경로 상수화 (_TMUX_SHIM_DIR_PATTERN / _TMUX_SKILLS_BIN_PATTERN) | `4cea114` | agy-new | agy-existing FAIL(슬래시 누락), claude-existing FAIL(:57/:76 잔존) -> Hermes 수정 |
 | FW-08 | _delegate_py_bin 캐싱 (AGENT_PYTHON_BIN 셸 변수, export 제거) | `4cea114` | agy-new | 동일 리뷰 (export -> 일반 변수로 수정) |
 | FW-09 | monitor status enum 문서화 + reconcile.sh last_visible_note 분리 | `7d925de` | agy-new | Hermes spec 검토 PASS |
 | FW-10 | 세션/잡 상태 glossary 추가 (Messaging_System_REPORT.md) | `155c6e8` | Hermes 직접 | 문서 작업 |
 | FW-11 | venv 의존성 통합 (pyyaml 추가, requirements.txt) | `f1a98be` | agy-new | Hermes spec 검토 PASS |
 | FW-12 | .bak 잔재 파일 정리 (test-sessions.yaml.bak 등 rm) | (커밋 없음) | Hermes 직접 | .gitignore에 이미 패턴 있음, git 추적 대상 아님 |
 | FW-13 | stop SKILL.md frontmatter/heading/산문 stop 재작성 | `5af1387` | Hermes 직접 | claude-existing 최종 검증에서 수정 확인 |
 | FW-14 | REPORT.md -> Messaging_System_REPORT.md git rename 정규화 | `9334352` | Hermes 직접 | git mv로 정규화 |
 | FW-15 | monitor --subscribe 보안 경고 문서화 (SKILL.md Security 섹션) | `7d925de` | agy-new | Hermes spec 검토 PASS |
 | FW-16 | 세션 상태 vs 잡 상태 도메인 분리 (glossary) | `155c6e8` | Hermes 직접 | FW-10과 동일 커밋 |
 ---
 ## 커밋 히스토리
 ```
 9ee9076 docs(delegate-job): add Subagent Orchestration Pattern section to SKILL.md
 f1a98be fix(lib.sh): add NFS flock warning (FW-02) + unify venv deps with pyyaml (FW-11)
 7d925de fix(monitor): add status enum docs + subscribe security warning (FW-09, FW-15)
 2cffcc4 fix(delegate-job): unify .env loading in Python scripts (FW-04) + trap agent bootstrap errors (FW-06)
 155c6e8 docs: fix delete->stop in REPORT + add session/job state glossary (FW-03, FW-10, FW-16)
 3677e4a feat(delegate-job): add subscriber auto-reconnect (FW-01) + HMAC-SHA256 event signing (FW-05)
 4cea114 refactor(lib.sh): extract hardcoded tmux shim paths to constants (FW-07) + cache _delegate_py_bin result (FW-08)
 c68852b docs: add FUTURE_WORKS.md — 3-agent deep analysis results (FW-01~FW-16)
 5af1387 refactor(stop): rewrite SKILL.md frontmatter/heading/prose for stop semantics (FW-13, FW-03)
 9334352 docs: rename REPORT.md -> Messaging_System_REPORT.md (FW-14)
 a6f7c04 feat(delegate-job): bump default --timeout 600s -> 3600s (1h wall-clock budget)
 ```
 ---
 ## 검증 결과 (3개 에이전트 교차)
 ### agy-new (Gemini 3.1 Pro High)
 - 15/16 DONE, FW-12 NOT_DONE (.bak 삭제 커밋 없음 — git 추적 대상 아님)
 - 새 발견: FW-02 근본 해결 지연 (SQLite WAL은 장기 과제)
 ### agy-existing (Gemini 3.5 Flash High)
 - 16/16 DONE
 - 새 발견 2건:
  1. AGENT_PYTHON_BIN export 캐시 오염 위험 -> 이미 수정됨 (export 제거, 일반 셸 변수 사용)
  2. reconcile.sh:66 모니터 유휴 타임아웃 600s vs 잡 3600s 불일치 -> 별개 도메인이나 문서화 가치 있음
 ### claude-existing (Claude Opus 4.8)
 - working tree clean 확인, 모든 커밋 반영 확인
 - FW-01 on_disconnect 5인자 수정 확인 (이전 FAIL에서 지적한 항목)
 - 구문/컴파일/stale 참조/working-tree 전체 검증 통과
 ---
 ## 처리 방식
 - **Main worker**: agy-new (Gemini 3.1 Pro High) — 6개 배치 구현
 - **Reviewers**: agy-existing (Flash High) + claude-existing (Opus 4.8) — 병렬 리뷰
 - **Orchestrator**: Hermes — dispatch, diff 검토, fallback fix, commit
 - **Batch 구성**: 파일 겹침 없이 2-3항씩 6배치로 그룹핑
 - **Hermes fallback**: 리뷰어가 발견한 작은 이슈(슬래시 누락, export 제거, paho 시그니처)를 Hermes가 직접 수정
 ---
 ## 날짜
 2026-06-21 (Sun) 03:52 ~ 07:00 KST
@@ -1,322 +1,80 @@
 # FUTURE_WORKS.md
 > **목적**: `advanced_multi_agent` 프로젝트의 향후 작업 후보를 추적한다.
-> **출처**: 2026-06-21 3개 코딩 에이전트 병렬 분석 (`agy-existing`, `agy-new`, `claude-existing`)
+> 완료된 항목은 `DONE.md`를 참조.
-> **brief**: `/tmp/deep-analysis-brief.md` (12개 항목)
+> **최종 갱신**: 2026-06-21 (3개 에이전트 최종 검증 완료 후)
 ---
-## 0. 메타데이터
+## 1. 장기 과제 (근본적 구조 변경)
-| 항목 | 값 |
+### FW-L1. SQLite WAL 마이그레이션 (FW-02 장기 후속)
-|---|---|
+- **상태**: FW-02 단기 대응(NFS 경고) 완료. 장기 해결 미진행.
-| 분석 일시 | 2026-06-21 (Sun) 03:52 ~ 05:48 KST |
+- **문제**: `atomic_dump_yaml`의 fcntl.flock이 NFS/NAS 환경에서 무시됨. 현재는 WARNING 로그만 출력.
-| brief 커밋 | `50b2b20 refactor(skills): rename tmux-agent-orchestrate-delete -> stop (step 1)` 직후 |
+- **해결 방안**: YAML 레지스트리를 SQLite WAL(Write-Ahead Logging) 백엔드로 마이그레이션.
-| 워크스페이스 | `/home/godopu16/PuKi/laa/canary_projects/advanced_multi_agent` |
+- **작업량**: 대 (Large) — 데이터 레이어 전면 교체
-| 분석 도구 | tmux `-L multi-agent-canary` 격리 서버 위 3개 세션 |
+- **우선순위**: NFS 환경 배포 시 필수, 로컬 단일 환경에서는 낮음
 | 모델 | agy-existing: Gemini 3.5 Flash (High) · agy-new: Gemini 3.1 Pro (High) · claude-existing: Claude Opus 4.8 |
 | 분석 wall-clock | agy-existing ~6min · agy-new ~5min · claude-existing ~4min (3m 51s reported) |
 | 본문 추출 범위 | **10~12번 항목만**(개선점 + 기술부채). 1~9번(프로젝트 목표/스킬 분석)은 pane scrollout으로 미수복. |
-### 추출 상태 보고
+### FW-L2. stop 옵션 시맨틱 Step 2 (FW-03/FW-13 후속)
-
+- **상태**: Step 1(디렉터리/식별자 rename) + frontmatter/산문 재작성 완료. Step 2 미진행.
-| agy-existing | 마지막 응답 캡처 성공 (10·11·12번, 102줄) |
+- **남은 작업**:
-| ✅ **agy-new** | **풀 보고서 보존** — `/tmp/agy-new-final-report.txt` (215줄, A~D 1~12번 + 종료선 전부) |
+  - `--purge-conversation`(진짜 삭제)와 `--mode soft|hard`의 시맨틱 재정의 또는 폐기 검토
 | ⚠️ **claude-existing** | 초기 응답 단편(38줄, ##12) 캡처 → subagent가 재요청으로 풀 보고서 회수 — `/tmp/claude-existing-report-reprint.md` (129줄, 1~12번 전부) |
 → 본 문서는 **agy-new의 풀 보고서를 SSOT(Single Source of Truth)로 사용**하고, claude 재출력 보고서를 §6(3-way 합의 보강)에 cross-validate. 1~9번 영역은 §4(agy-new 보고서 발췌)에 보존됨.
 ---
 ## 1. 합의된 개선점 (3개 에이전트 교차 검증)
 각 항목의 인용 수는 **3개 에이전트 중 몇 명이 지적했는지**를 나타낸다.
 ### 🔴 FW-01. MQTT subscriber 자동 재연결 부재 (3/3 합의)
 - **출처**: agy-existing(개선점 2, 우선순위 높음), agy-new(개선점 2), claude-existing(간접 — ack 빈도 안정성)
 - **문제**: `job_subscriber.py` 메인 루프가 일시적 네트워크 단절 시 즉시 종료. 에이전트가 오케스트레이터로부터 고아(orphaned) 상태가 됨.
 - **영향 범위**: `skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py`
 - **해결 방안**:
  - paho-mqtt의 `on_disconnect` 콜백 + 지수 백오프(exponential backoff)
  - 재접속 성공 시 `--expect-retention` 옵션으로 retained terminal 이벤트 즉시 조회
 - **작업량**: 소 (Small)
 - **근거 파일**: `skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py:165-174` (on_connect/connect)
 ### 🔴 FW-02. NFS/네트워크 파일시스템 환경에서 flock 락 취약 (3/3 합의)
 - **출처**: agy-existing(개선점 1, 우선순위 높음), agy-new(개선점 2, "구조 확장성")
 - **문제**: `atomic_dump_yaml`의 동시성 잠금이 로컬 fcntl.flock에 의존. NFS/NAS 환경에서 락 무시 → 레지스트리 손상 위험.
 - **영향 범위**: `skills/lib.sh`의 `atomic_dump_yaml`, `skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py:55`의 `timeout_sec: int = 600` 인접 영역
 - **해결 방안**:
  - **단기**: 락 파일 명시적 에러 핸들링 + 사용자 경고
  - **장기**: SQLite WAL(Write-Ahead Logging)로 마이그레이션
 - **작업량**: 중 (Medium) — 단순 패치가 아닌 데이터 레이어 교체 검토
 - **근거 파일**: `skills/lib.sh` (atomic_dump_yaml)
 ### 🟡 FW-03. delete/stop 명칭 잔재 + 산문/주석 drift (2/3 합의 + 1/3 [추측])
 - **출처**: agy-new(##12, "잔재된 단어의 찌꺼기"), claude-existing(##12, "이름/의미 불일치", [추측])
 - **문제**: 50b2b20에서 `tmux-agent-orchestrate-delete` → `stop` rename 완료했으나:
  - `Messaging_System_REPORT.md` 본문에 `terminate`/`delete` 용어 잔존
  - `skills/tmux-agent-orchestrate-create/SKILL.md:25` 주석에 `create/resume/delete/status/monitor` 옛 이름 잔존 가능 ([추측])
  - 옵션 명세(`--purge-conversation`, `--mode soft|hard`)는 delete 시맨틱 유지
 - **영향 범위**: 보고서 + SKILL.md 주석 + 옵션 시맨틱
 - **해결 방안**:
  - `grep -rn -E '(delete|terminate|terminated|kill)' --include='*.md' skills/` 일괄 점검
  - 산문에서 옛 의미 단어를 모두 stop으로 치환 (단, `--purge-conversation`은 의도적 단어로 보존 — 사용자 확인 필요)
  - **Step 2 작업의 일부로 흡수 가능**
 - **작업량**: 소 (Small)
 - **근거 파일**: `Messaging_System_REPORT.md`, `skills/tmux-agent-orchestrate-create/SKILL.md:25`
 ### 🟡 FW-04. 환경변수 오버라이드 경로 분절화 (2/3 합의)
 - **출처**: agy-new(##12, "암시적 환경변수 오버라이드 분절화")
 - **문제**: 래퍼 셸 스크립트는 `.env`를 보고, `mqtt_common.py`는 OS 환경변수를 직접 조회. `export` 누락 시 로드 경로 불일치 버그.
 - **영향 범위**: 래퍼 셸 스크립트 전체 + `skills/tmux-agent-orchestrate-delegate-job/scripts/mqtt_common.py`
 - **해결 방안**:
  - 진입점(예: `delegate-job submit`)에서 `.env`를 강제 로드하는 단일 함수 도입
  - 또는 `mqtt_common.py`에서도 dotenv 패턴 사용 (`python-dotenv` 의존성 추가)
 - **작업량**: 소 (Small) ~ 중 (Medium)
 - **근거 파일**: `skills/tmux-agent-orchestrate-delegate-job/scripts/mqtt_common.py`
 ### 🟡 FW-05. Public Broker 환경에서 auth_token 평문 노출 (1/3 합의, 1/3 강조)
 - **출처**: agy-new(개선점 3, 우선순위 높음, 보안)
 - **문제**: PoC(HiveMQ 공용 브로커) 환경에서 `auth_token`이 평문 전달 → 도청·이벤트 인젝션 위험.
 - **영향 범위**: `publish_event.py`, `job_subscriber.py`
 - **해결 방안**: HMAC-SHA256 서명 도입 (토큰 자체는 평문, 이벤트 페이로드에 서명 첨부)
 - **작업량**: 중 (Medium)
 - **근거 파일**: `skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py:55` (auth_token 정의), `Messaging_System_REPORT.md` §1.1(PoC 보안 위험)
 ### 🟡 FW-06. 에이전트 초기 기동 에러 MQTT 전파 결함 (1/3 합의)
 - **출처**: agy-existing(개선점 3, 우선순위 보통)
 - **문제**: 에이전트 쉘 기동 시 syntax error·패키지 부재 등 즉각적 예외가 MQTT error 채널로 안 가서 오케스트레이터가 timeout(exit 2)까지 대기.
 - **영향 범위**: `delegate-job submit`의 에이전트 부트스트랩 셸
 - **해결 방안**: 셸 진입 시 `trap ... ERR` + `publish_event.py --event error` 강제 발행하는 부트스트랩 래퍼.
 - **작업량**: 중 (Medium)
 - **근거 파일**: `skills/tmux-agent-orchestrate-delegate-job/SKILL.md`
 ### 🟢 FW-07. lib.sh `_resolve_real_tmux_path`의 하드코딩 경로 (1/3 합의)
 - **출처**: agy-existing(##12 #1)
 - **문제**: `_resolve_real_tmux_path` 함수 안에 `/multi-agent-tmux-shim/`, `/skills/.bin` 경로 문자열 하드코딩.
 - **영향 범위**: `skills/lib.sh:32` 부근
 - **해결 방안**: 상수 정의로 추출 + 동적 감지.
 - **작업량**: 소 (Small)
 - **근거 파일**: `skills/lib.sh`
 ### 🟢 FW-08. `_delegate_py_bin` 매 호출마다 디스크 검색 (1/3 합의)
 - **출처**: agy-existing(##12 #3)
 - **문제**: `.venv/bin/python`을 매 호출마다 상위 경로 디스크 검색 → 불필요한 I/O.
 - **영향 범위**: `skills/lib.sh`의 `_delegate_py_bin`
 - **해결 방안**: 환경변수(`AGENT_PYTHON_BIN`)로 캐싱.
 - **작업량**: 소 (Small)
 - **근거 파일**: `skills/lib.sh`
 ### 🟢 FW-09. YAML 비정형 status 코멘트 혼재 (1/3 합의, [추측])
 - **출처**: agy-existing(##12 #2, [추측])
 - **문제**: `last_visible_status`에 `auto-registered` 같은 임의 코멘트 → 파서 혼란 가능 ([추측]).
 - **영향 범위**: 모니터 스크립트 status 갱신 경로
 - **해결 방안**: 상태 코드 enum 정의 + 코멘트는 별도 필드(`last_visible_note`).
 - **작업량**: 소 (Small)
 - **근거 파일**: 모니터 SKILL.md
 ### 🟢 FW-10. 상태값/문서 표류 (1/3 합의, [추측])
 - **출처**: claude-existing(##12, [추측])
 - **문제**: 코드 검증셋(`lib.sh:217`)은 `running/terminated/archived/stopped` 4종. `Messaging_System_REPORT.md:168-179`의 잡 상태머신은 `pending/running/completed/error/cancelled` 5종. 두 도메인이 섞여 문서 표류 가능 ([추측]).
 - **영향 범위**: 도큐먼트 + lib.sh status enum
 - **해결 방안**: 두 도메인(세션 상태 vs 잡 상태)을 명시적으로 분리하고 glossary 섹션 추가.
 - **작업량**: 소 (Small)
 - **근거 파일**: `lib.sh:217`, `Messaging_System_REPORT.md:168-179`
 ### 🟢 FW-11. 인터프리터 분리 부채 (1/3 합의, [추측])
 - **출처**: claude-existing(##12, [추측])
 - **문제**: `.venv`는 paho-mqtt만, 시스템 python3는 yaml만 → monitor --subscribe는 venv, YAML 쓰기는 시스템 python 위임 ([추측]). 단일 인터프리터에 둘 다 설치하면 단순화 가능 ([추측]).
 - **영향 범위**: `requirements.txt` 또는 셋업 스크립트
 - **해결 방안**: 의존성 통합 + 둘 다 포함하는 단일 venv 강제.
 - **작업량**: 소 (Small)
 - **근거 파일**: `.venv/`, 시스템 python3 의존성
 ### 🟡 FW-13. stop SKILL.md frontmatter description이 delete 시절 문구 그대로 (1/3 합의, 매우 시급)
 - **출처**: claude-existing(11-1, 우선순위 높음 · 작업량 소 · 문서신뢰)
 - **문제**: `skills/tmux-agent-orchestrate-stop/SKILL.md`의 description이 여전히 *"Terminate … mark it terminated … Does NOT delete on-disk"* 식의 옛 문구. 본문 16회 "terminated" 잔존.
 - **영향**: LLM 라우팅 정확도(description으로 스킬 선택) + 사용자 혼란.
 - **해결 방안**: Step 2와 함께 description + 산문을 `stopped` 중심으로 재작성.
 - **작업량**: 소 (Small)
 - **근거 파일**: `skills/tmux-agent-orchestrate-stop/SKILL.md` frontmatter + 본문
 ### 🟡 FW-14. REPORT.md 미커밋 rename으로 작업 트리 더러움 (1/3 합의)
 - **출처**: claude-existing(11-2, 우선순위 높음 · 작업량 중 · 미완결상태)
 - **문제**: `git status` = `D REPORT.md` + `?? Messaging_System_REPORT.md`. rename이 `git mv`가 아니라 단순 mv였음. 권위 문서가 모호.
 - **영향**: 협업/리뷰 혼란, "어느 게 사양서?"
 - **해결 방안**: `git mv Messaging_System_REPORT.md REPORT.md && git commit` 또는 명시적 삭제.
 - **작업량**: 소 (Small)
 - **근거 파일**: 작업 트리 상태
 ### 🟡 FW-15. monitor `--subscribe`의 wildcard MQTT 구독 + 자동 kill (1/3 합의, 보안)
 - **출처**: claude-existing(11-3)
 - **문제**: 기본값이 평문 공용 브로커(`MQTT_BROKER=broker.hivemq.com:1883`) + 평문 bearer 토큰. monitor `--subscribe`가 wildcard 구독 + 자동 kill까지 함 (과거 리뷰 식별).
 - **영향**: 공용 브로커 사용 시 이벤트 스푸핑 / 세션 원격 종료 가능.
 - **해결 방안**: HMAC 서명 + TLS 강제. monitor subscribe의 자동 kill은 화이트리스트 기반 매칭.
 - **작업량**: 중 (Medium)
 - **근거 파일**: `Messaging_System_REPORT.md:310-311, 323-326`
 ### 🟢 FW-16. 세션 상태(YAML)와 잡 상태(registry) 도메인 혼동 (1/3 합의, [추측])
 - **출처**: claude-existing(12)
 - **문제**: 코드 검증셋(`lib.sh:217`)은 `running/terminated/archived/stopped`. `Messaging_System_REPORT.md:168-179`의 잡 상태머신은 `pending/running/completed/error/cancelled`. 두 도메인이 다르다는 것을 문서가 명확히 구분 안 함.
 - **영향**: 운영 시 혼동, API/스킬 옵션 시맨틱 일관성 저하.
 - **해결 방안**: 도큐먼트 glossary 섹션 추가 + 두 도메인 명시적 분리.
 - **작업량**: 소 (Small)
 - **근거 파일**: `lib.sh:217`, `Messaging_System_REPORT.md:168-179`
 ---
 ## 2. 합의된 강점 (3개 에이전트 공통)
 | 강점 | 출처 | 근거 파일 |
 |---|---|---|
 | 원자적 YAML 레지스트리(flock + validate + os.replace) | agy-existing(10-1) | `skills/lib.sh` |
 | tmux shim 소켓 격리 (PATH prepend) | agy-existing(10-2) | `skills/lib.sh` (`TMUX_SERVER_NAME`) |
 | 3-Tier UUID Resolution (`find_workspace_uuid`) | agy-existing(10-3) | `skills/lib.sh` |
 | 워크플로우 A→B→C→D 통합 (squashed from delegate-job) | git log `0eb1d94` | `.git` 히스토리 |
 (1~9번 항목 미수복으로 3-way 합의 강점 리스트는 불완전 — 추후 보강 필요)
 ---
 ## 3. 작업 우선순위 매트릭스
 | 우선순위 | 항목 | 합의 | 작업량 |
 |---|---|---|---|
 | 🔴 매우 시급 | **FW-13** (stop SKILL frontmatter 잔존) | 1/3 (claude, 강하게 강조) | 소 |
 | 🔴 높음 + 다수 합의 | FW-01 (subscriber 재연결) | 3/3 | 소 |
 | 🔴 높음 + 다수 합의 | FW-02 (flock NFS 취약) | 3/3 | 중~대 |
 | 🔴 높음 + 단독 합의 | FW-05 (auth_token 평문) | 1/3 (강조) | 중 |
 | 🟡 보통 | FW-03 (delete 잔재) | 2/3 | 소 |
 | 🟡 보통 | FW-04 (env 분절) | 2/3 | 소~중 |
 | 🟡 보통 | FW-06 (초기 에러 전파) | 1/3 | 중 |
 | 🟡 보통 | FW-14 (REPORT.md 미커밋 rename) | 1/3 | 소 |
 | 🟡 보통 | FW-15 (monitor subscribe + 자동 kill) | 1/3 | 중 |
 | 🟢 낮음 | FW-07 ~ FW-12, FW-16 | 1/3 | 소 |
 **권장 첫 스프린트** (소~중 작업량, 합의도/시급성 높은 것부터):
 1. **FW-14** REPORT.md rename 정규화 (`git mv`) — 즉시 가능, 작업 트리 클린업
 2. **FW-12** 미커밋 잔재 정리 (`test-sessions.yaml.bak` 등) — 즉시 가능
 3. **FW-13** stop SKILL.md frontmatter/산문 재작성 — Step 2의 일부
 4. **FW-01** subscriber 재연결 — 작업량 작고 합의도 3/3
 5. **FW-05** auth_token HMAC 서명 — 보안, 합의 강조
 **claude-only 신규 인사이트 (FW-13~16)**는 Step 2 작업(옵션 시맨틱 재정립) 시작 시 함께 흡수 권장.
 특히 **FW-13(stop SKILL.md description 잔존)**은 즉시 처리 가능하고 라우팅 정확도에 직결.
 ---
 ## 4. agy-new 풀 보고서 발췌 (1~9번 영역 보강)
 > 출처: `/tmp/agy-new-final-report.txt` (215줄)
 > 캡처 시점: 2026-06-21 05:50 (첫 subagent가 추출, agy-new pane 응답이 종료되기 직전)
 ### A. 프로젝트의 최종 목표 (Goal / Vision)
 #### 1. 달성하려는 사용자 시나리오
 단일 tmux 환경 위에서 다수 자율 에이전트(Claude Code, Antigravity CLI 등)에게
 병렬로 복잡한 장기 작업을 **위임(Delegate) + 비동기 관찰(Fire-and-observe)**.
 사용자는 터미널을 점유당하지 않고, 격리 서버에서 에이전트가 알아서 일하도록 한 뒤
 작업 완료나 권한 필요 시 MQTT 이벤트 스트림으로 알림.
 *(근거: `skills/tmux-agent-orchestrate-delegate-job/SKILL.md:3-4`)*
 #### 2. 6개 스킬의 워크플로우 시퀀스
 1. `create` — 빈 tmux 격리 세션 생성·등록
 2. `delegate-job` — 프롬프트 위임 + MQTT 구독기 시작
 3. `monitor` / `status` — 30초 주기 reconcile 또는 단발 조회
 4. `stop` — 우아 종료(`--capture-id` 옵션으로 ID 보존)
 5. `resume` — 디스크의 대화 ID로 컨텍스트 복원
 *(근거: 각 SKILL.md Companion skills, delegate-job Workflow)*
 #### 3. 연구실/표준화 연구 연결성 [추측 포함]
 QUIC/IoT 기반 멀티 에이전트 표준화 연구의 **최소 기능 검증(Canary PoC)**.
 MQTT 단방향 이벤트 스트리밍 모델(Event-driven state machine)이
 분산 에이전트들의 잡 라이프사이클 통합 관제에 적합한지 가설 검증.
 #### 4. 권위 있는 "사양서" 문서
 - **아키텍처/시스템 사양**: `Messaging_System_REPORT.md` (MQTT 브로커, 와이어 스키마, ACL, 보안)
 - **에이전트 로컬 실행/세션 관리 사양**: 6개 SKILL.md
 - **상태 SSOT**: `.hermes/agent-sessions.yaml`
 ### B. 개발 내용 심층 분석
 #### 5. Messaging_System_REPORT.md 분석
 - **와이어 스키마**: `schema_version=1`, `seq`(단조 증가), `job_id`(8-hex), `event` ∈ {`started`,`progress`,`permission_required`,`completed`,`error`}, `timestamp`(ISO-8601 UTC), `detail`, `data`
 - **잡 상태 머신**: `pending` → `running` → `completed`|`error`(터미널, `retain=True`) → `cancelled`
 - **ACL**: 구독자(Hermes)=`read`, 에이전트=`write`, 토픽 `python/mqtt/jobs/+/events`
 - **PoC vs Prod**:
  - PoC: `broker.hivemq.com:1883`, 인증/TLS 없음 — 도청·스푸핑 위험
  - Prod: 자체 호스팅 Mosquitto/EMQX, `:8883` TLS 1.3, username/password + persistence true — 코드 변경 없이 `.env`만으로 전환
 - **알려진 한계**: NFS fcntl 붕괴 → SQLite WAL, 토큰 평문 → HMAC, 구독자 끊김 → Auto-Reconnect
 #### 6. 6개 스킬 역할/입출력/의존성
 - `create`: tmux 격리 + YAML 등록
 - `resume`: 디스크 UUID로 tmux 부활
 - `stop`: tmux 종료 + YAML 갱신 (이력 보존)
 - `status`: 스냅샷 (drift 감지)
 - `monitor`: Kanban 워커 30초 reconcile
 - `delegate-job`: 비동기 위임 + MQTT 이벤트 관찰
 - **agent-sessions.yaml**: fcntl.flock + `os.replace`로 동시성 훼손 방지
 - **tmux 격리**: `TMUX_SERVER_NAME` 또는 `-L` 플래그, 글로벌 `kill-server` 보호
 #### 7. 환경변수 통합 제어
 - `.env` + `generate-env.sh`로 시스템 기본값 오버라이드
 - **경로**: `AGENT_SESSIONS_YAML`, `CLAUDE_PROJECT_DIR`, `LOCAL_BIN`
 - **통신**: `TMUX_SERVER_NAME`, `MQTT_BROKER`, `MQTT_USERNAME`, `MQTT_TLS`, `MQTT_CA_CERTS`
 - 로컬 워크스페이스 세팅과 MQTT 클라우드 세팅 분리 → 잡별 주입 + 프로덕션 전환 무코드
 #### 8. cd9eec1 커밋 의미 (절대경로 → 상대경로/Env)
 - **문제**: 개발자 홈(`/home/godopu16/PuKi/...`) 하드코딩 → 다른 환경/CI 복사 시 즉시 고장
 - **해결**: `BASH_SOURCE` 기반 워크스페이스 동적 추론 + `${VAR:-default}` env override
 - **흔적**: `.env.example` 기본값 패턴, `lib.sh` 동적 경로 파싱
 #### 9. 50b2b20 커밋 의미 (rename `delete` → `stop`)
 - **문제 의식**: `delete`라는 명칭이 "영구 삭제/복구 불가" 오해 유발
 - **실제 의도**: tmux 컨테이너 우아 종료 + `resume` 가능 (대화 이력 보존)
 - **Step 1**: 디렉터리명/식별자만 rename (이미 커밋됨)
 - **예상 Step 2**:
  - 옵션 직관성 재정립: `--purge-conversation`(진짜 삭제)과 `--mode soft|hard` 재정의 또는 폐기
  - 하위 호환 코드 제거
-  - 산문/주석의 옛 명칭 잔재 정리
+  - `--mode soft|hard` 폐기 후 `stop` = 기본 동작, `--purge-conversation` = 파괴적 옵션으로 명확화
-
+- **작업량**: 중 (Medium)
-### C. 코드/구조 품질 진단 (agy-new 평가)
+- **우선순위**: 보통 — 현재 동작에 문제 없으나 API 직관성 향상
 #### 10. 잘 된 점 Top 3
 1. **무결성 보장 동시성 모델** — fcntl 락 + 임시파일 `os.replace` 패턴으로 YAML/JSON 파손 방지
 2. **비침투 무중단 아키텍처** — PoC→Prod 전환 시 `.env`/Registry JSON만으로 설정 오버라이드
 3. **사용자 환경 격리** — `TMUX_SERVER_NAME` 소켓으로 사용자 터미널과 완전 분리
 #### 11. 시급 개선점 Top 3 (agy-new 발췌)
 1. **fcntl NFS 환경 붕괴** (구조 확장성, 작업량: 大) → SQLite WAL 전면 교체
 2. **Public Broker 평문 토큰** (보안, 우선순위 高) → HMAC-SHA256 서명 도입
 3. **Subscriber 재연결 부재** → Auto-Reconnect + 지수 백오프
 ### D. 기술 부채 후보 (agy-new 발췌)
 - 옛 명칭 잔재 (delete/terminate)
 - `stopped` 상태 추가로 인한 reconcile.sh Skip-set 비대화
 - `.env`(셸)와 OS env(python) 분기 — `export` 누락 시 버그
 *(agy-new 풀 본문은 `/tmp/agy-new-final-report.txt` 참조)*
 ---
-## 5. 분석 인프라 개선 권고 (다음 라운드 시)
+## 2. 신규 발견 항목 (최종 검증에서 식별)
-**근본 원인**: pane TUI의 자체적인 위쪽 truncate + subagent의 pane 추출 시점 차이로 1~5번이 사라짐.
+### FW-N1. reconcile.sh 모니터 유휴 타임아웃 vs 잡 타임아웃 불일치
-**이번 차이점**: agy-new는 첫 subagent가 brief 직후 빠르게 캡처해 215줄 풀 보고서를 보존함.
+- **발견자**: agy-existing (최종 검증)
-agy-existing/claude-existing은 캡처 시점이 늦어 12번 단편만 남음.
+- **문제**: `reconcile.sh`의 `SUB_IDLE_TIMEOUT` 기본값 600s가 잡 wall-clock timeout 기본값 3600s와 불일치. 모니터가 잡보다 먼저 타임아웃되어 조기 종료 간섭 가능.
 - **영향 범위**: `skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh:66` 부근
 - **해결 방안**: 모니터 유휴 타임아웃을 잡 타임아웃과 독립적으로 문서화하거나, 기본값을 3600s 이상으로 조정.
 - **작업량**: 소 (Small)
 - **우선순위**: 낮음 — 별개 도메인(모니터 유휴 vs 잡 wall-clock)이나 문서화 필요
-**다음 분석 시 권장 패턴**:
+### FW-N2. 와이어 포맷 호환성 (HMAC 전환 후 혼합 배포)
 - **발견자**: claude-existing (Batch 2 리뷰)
 - **문제**: `data.auth_token` → `data.hmac_sig` 와이어 포맷 변경. 구 버전(publish_event.py)과 신 버전(job_subscriber.py)이 혼재하는 롤아웃 시 모든 이벤트가 drop될 수 있음.
 - **해결 방안**: 롤아웃 시 전체 노드 동시 업데이트 또는 하위 호환 모드(auth_token + hmac_sig 동시 전송) 추가.
 - **작업량**: 소 (Small)
 - **우선순위**: 낮음 — 단일 노드 Canary 환경에서는 해당 없음
 ### FW-N3. 로그 문구 "auth_token mismatch" → "HMAC verify failed" 갱신
 - **발견자**: claude-existing (Batch 2 리뷰)
 - **문제**: `job_subscriber.py`의 drop 로그가 여전히 "auth_token mismatch"를 사용. HMAC 검증으로 변경되었으나 로그 미갱신.
 - **해결 방안**: 로그 문구를 "HMAC verify failed"로 변경.
 - **작업량**: 소 (Small)
 - **우선순위**: 낮음 — 기능 영향 없음, 디버깅 가독성만
 ### FW-N4. Messaging_System_REPORT.md §2.4 평문 auth_token 기술 갱신
 - **발견자**: claude-existing (Batch 2 리뷰)
 - **문제**: 보고서 §2.4가 여전히 "plaintext bearer auth_token" 기술. HMAC 서명으로 변경되었으나 문서 미갱신.
 - **해결 방안**: §2.4를 HMAC-SHA256 서명 방식으로 갱신.
 - **작업량**: 소 (Small)
 - **우선순위**: 보통 — 권위 문서의 정확성
 ---
 ## 3. 분석 인프라 개선 (다음 분석 라운드 시)
 **근본 원인**: pane TUI의 자체적인 위쪽 truncate + subagent의 pane 추출 시점 차이로 긴 응답이 스크롤아웃됨.
 **검증된 패턴** (delegate-job SKILL.md "Subagent Orchestration Pattern" 섹션에 반영됨):
 1. brief 직후 `capture-pane -S -200` 즉시 캡처 → 누적 백업
 2. 응답 진행 중 30초마다 `>> /tmp/pane-snap.txt` 누적
-3. "분석 종료" 직후에도 한 번 더 전체 캡처 (출력이 안정될 때까지)
+3. "분석 종료" 직후에도 한 번 더 전체 캡처
 4. 짧은 작업(<5min)은 폴링이 MQTT subscriber보다 안정적
 5. 긴 brief는 파일 경로로 전달 (inline send-keys는 TUI가 swallow)
 ---
-## 6. 변경 이력
+## 4. 변경 이력
 | 날짜 | 변경 |
 |---|---|
-| 2026-06-21 | 초기 작성 — 3개 에이전트 분석 결과를 3-way 합의 매트릭스로 정리 |
+| 2026-06-21 | 초기 작성 — 3개 에이전트 분석 결과 (FW-01~FW-16) |
-| 2026-06-21 | §4 갱신 — `/tmp/agy-new-final-report.txt`(215줄)로 1~9번 영역 보강. SSOT를 agy-new로 확정. §5(분석 인프라 개선) 추가. |
+| 2026-06-21 | FW-01~FW-16 전부 완료 -> DONE.md로 이동. 본 파일은 신규 발견 항목(FW-N1~N4) + 장기 과제(FW-L1~L2)만 남김. |
 | 2026-06-21 | §1·§3 갱신 — claude 재출력 보고서(`/tmp/claude-existing-report-reprint.md`) 기반 FW-13~16 신규 항목 추가. 우선순위 매트릭스에 FW-13(매우 시급) 포함. 권장 첫 스프린트 갱신. |