From 623eef814b1bb281661f6bcc945ace31ad2d85bf Mon Sep 17 00:00:00 2001 From: Godopu Date: Sun, 21 Jun 2026 07:15:53 +0000 Subject: [PATCH] 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) --- DONE.md | 90 ++++++++++++ FUTURE_WORKS.md | 358 ++++++++---------------------------------------- 2 files changed, 148 insertions(+), 300 deletions(-) create mode 100644 DONE.md diff --git a/DONE.md b/DONE.md new file mode 100644 index 0000000..f79f2bc --- /dev/null +++ b/DONE.md @@ -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 \ No newline at end of file diff --git a/FUTURE_WORKS.md b/FUTURE_WORKS.md index cf4f280..4e98a69 100644 --- a/FUTURE_WORKS.md +++ b/FUTURE_WORKS.md @@ -1,322 +1,80 @@ # FUTURE_WORKS.md > **목적**: `advanced_multi_agent` 프로젝트의 향후 작업 후보를 추적한다. -> **출처**: 2026-06-21 3개 코딩 에이전트 병렬 분석 (`agy-existing`, `agy-new`, `claude-existing`) -> **brief**: `/tmp/deep-analysis-brief.md` (12개 항목) +> 완료된 항목은 `DONE.md`를 참조. +> **최종 갱신**: 2026-06-21 (3개 에이전트 최종 검증 완료 후) --- -## 0. 메타데이터 +## 1. 장기 과제 (근본적 구조 변경) -| 항목 | 값 | -|---|---| -| 분석 일시 | 2026-06-21 (Sun) 03:52 ~ 05:48 KST | -| brief 커밋 | `50b2b20 refactor(skills): rename tmux-agent-orchestrate-delete -> stop (step 1)` 직후 | -| 워크스페이스 | `/home/godopu16/PuKi/laa/canary_projects/advanced_multi_agent` | -| 분석 도구 | tmux `-L multi-agent-canary` 격리 서버 위 3개 세션 | -| 모델 | 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-L1. SQLite WAL 마이그레이션 (FW-02 장기 후속) +- **상태**: FW-02 단기 대응(NFS 경고) 완료. 장기 해결 미진행. +- **문제**: `atomic_dump_yaml`의 fcntl.flock이 NFS/NAS 환경에서 무시됨. 현재는 WARNING 로그만 출력. +- **해결 방안**: YAML 레지스트리를 SQLite WAL(Write-Ahead Logging) 백엔드로 마이그레이션. +- **작업량**: 대 (Large) — 데이터 레이어 전면 교체 +- **우선순위**: NFS 환경 배포 시 필수, 로컬 단일 환경에서는 낮음 -### 추출 상태 보고 - -| agy-existing | 마지막 응답 캡처 성공 (10·11·12번, 102줄) | -| ✅ **agy-new** | **풀 보고서 보존** — `/tmp/agy-new-final-report.txt` (215줄, A~D 1~12번 + 종료선 전부) | -| ⚠️ **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` 재정의 또는 폐기 +### FW-L2. stop 옵션 시맨틱 Step 2 (FW-03/FW-13 후속) +- **상태**: Step 1(디렉터리/식별자 rename) + frontmatter/산문 재작성 완료. Step 2 미진행. +- **남은 작업**: + - `--purge-conversation`(진짜 삭제)와 `--mode soft|hard`의 시맨틱 재정의 또는 폐기 검토 - 하위 호환 코드 제거 - - 산문/주석의 옛 명칭 잔재 정리 - -### C. 코드/구조 품질 진단 (agy-new 평가) - -#### 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` 참조)* + - `--mode soft|hard` 폐기 후 `stop` = 기본 동작, `--purge-conversation` = 파괴적 옵션으로 명확화 +- **작업량**: 중 (Medium) +- **우선순위**: 보통 — 현재 동작에 문제 없으나 API 직관성 향상 --- -## 5. 분석 인프라 개선 권고 (다음 라운드 시) +## 2. 신규 발견 항목 (최종 검증에서 식별) -**근본 원인**: pane TUI의 자체적인 위쪽 truncate + subagent의 pane 추출 시점 차이로 1~5번이 사라짐. -**이번 차이점**: agy-new는 첫 subagent가 brief 직후 빠르게 캡처해 215줄 풀 보고서를 보존함. -agy-existing/claude-existing은 캡처 시점이 늦어 12번 단편만 남음. +### FW-N1. reconcile.sh 모니터 유휴 타임아웃 vs 잡 타임아웃 불일치 +- **발견자**: agy-existing (최종 검증) +- **문제**: `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 | §4 갱신 — `/tmp/agy-new-final-report.txt`(215줄)로 1~9번 영역 보강. SSOT를 agy-new로 확정. §5(분석 인프라 개선) 추가. | -| 2026-06-21 | §1·§3 갱신 — claude 재출력 보고서(`/tmp/claude-existing-report-reprint.md`) 기반 FW-13~16 신규 항목 추가. 우선순위 매트릭스에 FW-13(매우 시급) 포함. 권장 첫 스프린트 갱신. | \ No newline at end of file +| 2026-06-21 | 초기 작성 — 3개 에이전트 분석 결과 (FW-01~FW-16) | +| 2026-06-21 | FW-01~FW-16 전부 완료 -> DONE.md로 이동. 본 파일은 신규 발견 항목(FW-N1~N4) + 장기 과제(FW-L1~L2)만 남김. | \ No newline at end of file