multi-agent-mux/.agents/reports/planner-reviewer-claude-01/plan-baea3f7e.md

📑 Implementation Plan Rev.2 — Workspace Root Markdown 정리 및 최신화 (Job baea3f7e, 원본 45bd8635)

• 역할: Planner (planner-reviewer-claude-01)
• 기준 커밋: 07cae71 (main, v4.4.0, 전체 스위트 750 passed / 문서 바인딩 4모듈 49 passed)
• 개정 사유: Creator(creator-agy-01, Job 87aa5b5a) 이의제기 3건. 3건 모두 실측으로 사실 확인되어 전부 수용하고, 검증 과정에서 Planner 자신의 Rev.1 오류 1건(D-1/Phase B-1 "잔재에 고유 내용 없음")을 추가로 발견하여 함께 정정한다.
• Rev.1 대비 변경 범위: §1 D-1, Phase A-2, Phase B 전면, Phase D-1, 게이트 4. 나머지 Phase C/E/F/G와 게이트 1·2·3·5·6은 Rev.1 그대로 유효(본문 하단에 원문 유지).

---

0. 이의제기 판정 (Adjudication of Challenge)

#	Creator 주장	Planner 실측	판정
C-1	완료 과제는 §5 단일 섹션이 아니라 §2(5건)·§3(2건)·§5(24블록)에 분산되어 있고, 헤더 "30건"은 전역 합계이며 Rev.1 Phase B-2 지시("§5의 ### 수로 재계산해 헤더와 일치")는 실행 불가	awk로 전 ### 블록을 섹션별로 열거: §2 완료 5(B-21,B-20,B-19,B-14,B-15), §3 완료 2(O-6,A-4), §5 24블록(O-2 중복 2회), 헤더 ID 정확히 30개. 주장 사실. 단 Creator의 산식 "5+2+23=30"은 우연한 일치다. ID↔블록이 1:1이 아니기 때문이다(아래 §1-A)	수용 — 방안 A 채택, 단 계수 규칙을 블록 기준으로 명문화
C-2	이관되는 implementation_plan.md §7 표의 [.mam.env](.mam.env) 링크는 gitignored 파일(test_d29가 추적 금지)이라 클린 체크아웃에서 게이트 4 test -e가 실패	.gitignore:24 .mam.env, git ls-files에 .mam.env.example만 추적, tests/test_deploy_freshness.py:687 test_d29_env_secrets_never_tracked 존재, 원문 151행 링크 확인. 주장 사실.	수용 — 링크 대상을 .mam.env.example로, 게이트 4에 ignore 예외 규칙 추가
C-3	Phase D-1 트리 추가 목록에 IMPROVEMENTS.md 누락, 영문 README 트리에 README.ko.md/BOOTSTRAP.ko.md 부재, 한국어 README에는 BOOTSTRAP.ko.md만 존재 → "줄수 일치" 게이트 기준 불명확	README.md:188-190 3개 루트 md, README.ko.md:170-173 4개 루트 md. 주장 사실.	수용 — 루트 md 8개 전부를 양 README 트리에 동일 순서로 명시

부수 정정: Creator 보고서의 "450줄"은 wc -l 기준 449줄(마지막 줄 개행 있음)이나 판단에 영향 없음.

---

1. 정정된 결함 진단

1-A. IMPROVEMENTS.md 완료 과제 원장 (Planner 실측, 정본)

헤더 ID 30개와 완료 ### 블록 31개(잔재 제외)의 대응은 다음과 같다. 이 표가 Phase B의 유일한 기준이다.

헤더 ID	현재 블록 위치	비고
B-21, B-20, B-19, B-14, B-15	§2 (30/44/54/64/68행)	미해결 섹션에 완료 항목 혼재
O-6, A-4	§3 (99/106행)	A-4 블록은 Rev.2 어댑터 계층 45행 분량
B-9, B-13, B-10, B-5, C-6, P2-2, P2-1, B-4, O-3, A-1, A-3, C-2, A-5, B-1, B-3, C-1, O-1, Herdr-0.8.0-Compat-SanitizeHash	§5	1:1 대응
B-7	§5 P0-1 (B-7) (253행)	키 표기 상이
O-4-OrcOnboard	§5 multi-agent-mux-orc-onboard (242행)	키 표기 상이
O-2	§5 2블록: P0-2 (O-2) 247행(Rev.1: pid+lstart 마커, 46/46) + O-2 273행(Rev.2: 하드링크 원자 쓰기, steal_lock, 204/204)	동일 과제의 연속 개정 → 병합 대상
C-3b	독립 블록 없음. §5 P3-1 (A-4 Phase 2 / Option B / C-3b / M2~M7) 224행 제목에 포함	P3-1 블록이 A-4(2차)와 C-3b를 동시에 담음
B-8	독립 블록 없음. §6.2 표 367행 P1-2(과거) B-8 … (✅ 완료 — tests/test_b8_send_keys_verification.py 1/1 PASS)에만 존재	tests/test_b8_send_keys_verification.py 실재 확인
(헤더에 없음)	§5 Rev.2 (b4a1d094) 260행 세션 ID 자동 할당	헤더 ID 목록에서 누락된 블록

결론: "헤더 30 = §2 5 + §3 2 + §5 23"은 (O-2 중복 −1, C-3b 블록 없음 −1, B-8 블록 없음 −1, Rev.2 블록 ID 없음 +1, P3-1 별도 블록 +1)이 상쇄된 우연이다. Rev.2는 **"§5의 ### 블록 1개 = 헤더 ID 1개"**를 강제하여 이 우연을 제거한다.

1-B. Rev.1 오류 정정 — 154~186행 잔재는 단순 삭제 불가

Rev.1 Phase B-1은 "앞쪽 사본이 최신 서술을 모두 포함(확인됨)"이라 했으나 틀렸다. 잔재 전용 토큰 20종을 실측했다: B-14 원 진단(publish_event.py:195-199, wait_for_job(), max_wait=3900s, status=running), B-15 원 진단(job_subscriber.py:172-251, queue.Empty, idle_timeout, multi-agent-mux-delegate-job:331-341, wait "$sub_pid", sub_rc, job_status="error", job_status="broker_unavailable", load_job/read_logged_status, source: disk-fallback), O-5 배경(nats-py Option B 기각 사유). 앞쪽 B-14/B-15 블록(64~70행)은 각 2줄 요약뿐이다. B-16 블록은 양쪽 동일(잔재 고유 내용 없음). 따라서 잔재는 병합 후 삭제한다(Phase B-1).

---

2. 개정된 작업 계획 (변경된 Phase만 기술; 미기재 Phase는 Rev.1 원문 적용)

Phase A-2 (개정) — 이관 파일 링크 규칙

• git mv implementation_plan.md docs/contracts/nats-backplane/implementation_plan.md 후 상대 링크를 ../../../ 접두로 승격하되, §7 표의 [.mam.env](.mam.env)는 [.mam.env (템플릿: .mam.env.example)](../../../.mam.env.example)로 변경한다. 이유: .mam.env는 gitignored(.gitignore:24)이며 test_d29가 추적을 금지하므로 클린 체크아웃에 존재하지 않는다.
• 같은 이유로 문서 내 .mam.env를 파일 링크 없이 코드 스팬으로만 언급하는 것은 허용한다(23행·122행은 링크가 아니므로 변경 불필요).

Phase B (전면 개정) — IMPROVEMENTS.md 단일 원장화 (방안 A 채택)

작업 순서를 엄수한다. 행 번호는 착수 시점 기준이며 이후 단계는 헤더 문자열로 앵커링한다.

1. 잔재 병합 후 삭제 (1-B 반영)
   • 잔재 ### **B-14 (F-1 / P1)…(156행)의 현상·파급 효과 불릿을 앞쪽 ### **B-14 (✅ 완료 — F-1 / P1)… 블록의 현상 불릿 아래에 "원 진단" 불릿으로 추가(내용 원문 유지, 시제만 과거형 허용).
   • 잔재 B-15(161행)의 현상 1·2항과 파급 효과를 앞쪽 B-15 블록에 동일 방식으로 추가.
   • 잔재 O-5(179행)의 현상 문장 중 "nats-py 클라이언트 재작성(Option B)을 배제하고" 구절을 앞쪽 O-5 현상에 삽입.
   • 잔재 B-16(170행)은 앞쪽과 동일하므로 추가 없음.
   • 그 다음 두 번째 ## 2. 🟠 …(Edge-case Bugs — 3건)부터 두 번째 ## 3. 블록 끝(## 4. ⚪ 레거시 잔재 직전 구분선)까지 삭제.
   • 검증: 위 20종 토큰 전부가 삭제 후 파일에 여전히 존재(grep -cF로 각 1 이상), grep -c '^## 2\.'=1, grep -c '^## 3\.'=1.
2. 완료 블록 §5 이관 (방안 A)
   • §2의 B-21, B-20, B-19, B-14, B-15 블록과 §3의 O-6, A-4 블록을 현재 등장 순서 그대로 ## 5. 🎉 완료된 과제 제목 바로 아래(기존 B-9 앞)에 삽입. 블록 본문은 한 글자도 바꾸지 않는다(제목의 (✅ 완료 — …) 표기 포함).
   • 이관 후 §2에는 B-16, B-17, B-18만, §3에는 O-5만 남는다.
3. O-2 중복 병합
   • ### **O-2: 동일 워크스페이스 … (Race-Free Mutex & Ownership)**(Rev.2, 최종본)을 유지하고, ### **P0-2 (O-2): …** 블록은 제목을 제거한 뒤 그 불릿 4개를 O-2 블록 끝에 - **Rev.1 (P0-2) 선행 조치**: 하위 불릿으로 편입한다. 제목은 ### **O-2 (P0-2): …**로 갱신하여 키 대응을 유지.
4. B-8 블록 신설 (원장 완결성)
   • ## 5 말미(Herdr-0.8.0 블록 뒤)에 ### **B-8 (P1-2): agy 주입 시 \return 0` 우회 제거 및 제출 검증 루프 이관** — ✅ 완료블록을 추가하고, 불릿 1개만 둔다: §6.2 표 367행의 서술을 그대로 옮기고 근거로tests/test_b8_send_keys_verification.py` (1/1 PASS)를 명기한다. 새 사실을 지어내지 않는다 — 표 367행 밖의 내용은 쓰지 않는다.
5. 섹션 헤더 카운트 확정 (계수 규칙: 해당 섹션 하위 ### 블록 수)
   • ## 1. 🔴 아키텍처 결함 (Architecture Flaws — 1건) (A-2)
   • ## 2. 🟠 엣지 케이스 및 런타임 버그 (Edge-case Bugs — 3건) (B-16, B-17, B-18)
   • ## 3. 🟡 오케스트레이션 최적화 과제 (Orchestration Optimizations — 1건) (O-5)
   • ## 4. ⚪ 레거시 잔재 및 죽은 코드 (Legacy Remnants — 0건 — 전원 완료) (변경 없음)
   • ## 5. 🎉 완료된 과제 (Completed Tasks — 31건) = 기존 24 − 1(O-2 병합) + 7(이관) + 1(B-8) = 31
6. 헤더 요약(3~6행) 동기화
   • 최종 갱신일: 2026-09-07 (IMPROVEMENTS.md 단일 원장화: §2/§3 완료 항목 §5 이관, 머지 잔재 병합 제거, v4.1.x~v4.4.0 완료 사항 반영).
   • 총 추적 미해결 과제: 5건 문구 유지(A-2 / B-16, B-17, B-18 / O-5).
   • 완료된 과제: 31건으로 갱신하고 괄호 목록을 §5 블록 키를 등장 순서대로 나열한 31개로 교체: B-21, B-20, B-19, B-14, B-15, O-6, A-4, B-9, B-13, B-10, B-5, C-6, P3-1-A4Phase2-C3b, P2-2-C3a-C4-LegacyCleanup, P2-1-DelegateJobSafe-TrapFix, O-4-OrcOnboard, O-2-P0-2, P0-1-B-7, Rev.2-b4a1d094-SessionIdPinning, B-4, O-3, A-1, A-3, C-2, A-5, B-1, B-3, C-1, O-1, Herdr-0.8.0-Compat-SanitizeHash, B-8. (기존 B-7, C-3b, O-2, A-4는 위 키 안에 포함되어 유실되지 않는다.)
7. v4.1.x~v4.4.0 반영 (Rev.1 B-3 유지, 위치만 명확화)
   • 기존 ### **B-13 (Stage 2)… 블록 끝에 1불릿: "v4.4.0(Issue #5 Phase 4)에서 freeze 스냅샷을 기본 경로에서 철거, MAM_LOOP_FREEZE=1 롤백 스위치만 잔존 (docs/contracts/issue-5/phase4-freeze-removal.md)".
   • 신규 블록은 추가하지 않는다(codex/grok/opencode 통합, Python 코어 마이그레이션은 VERSIONS.md가 정본이며, 백로그 ID가 부여된 과제가 아니므로 §5에 등재하지 않는다). 대신 📌 개요 절 끝에 1문장: "v4.1.0 이후 릴리스 단위 변경 이력은 VERSIONS.md를 정본으로 하며 본 백로그는 ID가 부여된 과제만 추적한다."
8. 보존 필수 문자열: ### **O-1: 타당하지 않은 리뷰 피드백 거부/반론 프로토콜 미지원 (Rebuttal Protocol)** 제목과 본문은 변경 금지 (test_o1_rebuttal.py::test_v10).

• Phase B 검증 스크립트 (Creator 실행 필수):

  f=IMPROVEMENTS.md
  test "$(grep -c '^## 2\.' $f)" = 1 && test "$(grep -c '^## 3\.' $f)" = 1
  # §5 블록 수 = 31, 헤더 괄호 ID 수 = 31
  awk '/^## 5\./{s=1;next} /^## 6\./{s=0} s&&/^### /{n++} END{print n}' $f          # → 31
  sed -n '6p' $f | grep -o -E '\(B-21.*\)' | tr ',' '\n' | grep -c .               # → 31
  # 각 완료 ID의 ### 제목이 정확히 1회
  for id in B-21 B-20 B-19 B-14 B-15 O-6 O-2 B-8 A-4; do test "$(grep -c "^### \*\*$id[ :(]" $f)" = 1 || echo "DUP/MISSING $id"; done
  # §2·§3에 ✅ 완료 블록 잔존 금지
  awk '/^## 2\./{s=1} /^## 4\./{s=0} s&&/^### .*✅/{print "LEAK: "$0}' $f
  .venv/bin/python -m pytest -q tests/test_o1_rebuttal.py
  

Phase D-1 (개정) — README 트리의 루트 마크다운 표기 기준

• 양 README의 text 트리 루트 레벨 마크다운 항목은 다음 8개를 알파벳 순으로 전부 기재한다(언어별 미러 포함, 기존 3~4개 → 8개): AGENTS.md, BOOTSTRAP.ko.md, BOOTSTRAP.md, IMPROVEMENTS.md, MESSAGING.md, README.ko.md, README.md, VERSIONS.md. 설명 문구만 언어별로 다르다.
• 디렉터리 항목 추가 목록은 Rev.1 D-1 그대로(lib_py/ 3패키지, scripts/ shim 재표기, docs/ 4항목, nats-docker/, tests/).
• 검증: 두 파일의 트리 블록에서 ├──|└──로 시작하는 줄 수가 동일하고, 루트 md 8개 문자열이 양쪽에 각 1회 존재.

게이트 4 (개정) — 깨진 상대 링크 0건

• 검사 대상: 루트 8개 + 이관 문서. 링크 경로 추출 후 test -e; 단 git check-ignore -q <path>가 참인 경로는 검사에서 제외하지 않고 오류로 처리한다(추적되지 않는 파일로의 링크는 문서 결함이므로 Phase A-2 규칙에 따라 링크 자체를 제거/대체해야 한다). 즉 게이트 4 = "모든 링크 대상이 존재하고 git 추적 대상이다".

  for f in README.md README.ko.md BOOTSTRAP.md BOOTSTRAP.ko.md MESSAGING.md IMPROVEMENTS.md AGENTS.md VERSIONS.md docs/contracts/nats-backplane/implementation_plan.md; do
    d=$(dirname "$f")
    grep -o -E '\]\(([^)#]+)(#[^)]*)?\)' "$f" | sed -E 's/^\]\(//; s/#.*//; s/\)$//' | grep -v -E '^(https?:|mailto:|file:)' | while read -r p; do
      t="$d/$p"; { test -e "$t" && git ls-files --error-unmatch "$t" >/dev/null 2>&1; } || echo "BROKEN/UNTRACKED: $f -> $p"
    done
  done
  

• 주의: IMPROVEMENTS.md 248행 등에 file:///Users/... 절대 링크가 존재한다. 본 게이트에서는 제외(file: 필터)하되, Phase B-3 O-2 병합 시 해당 불릿의 file:// 링크는 상대 경로 .agents/skills/multi-agent-mux-loop/scripts/loop_lock.sh로 교체한다(같은 불릿을 만지는 김에 최소 수정).

---

3. 최종 검증 게이트 (Rev.2 확정본)

1. 루트 마크다운 8개, implementation_plan.md는 docs/contracts/nats-backplane/.
2. pytest -q tests/test_deploy_layout.py tests/test_o1_rebuttal.py tests/test_deploy_freshness.py tests/test_version_consistency.py → 49 passed.
3. pytest -q tests/ → 750 passed.
4. 위 개정 게이트 4 스크립트 출력 0줄.
5. git diff --stat에 .agents/skills/**, tests/**, deploy/** 변경 없음.
6. MAM_INSTALL_DOCS=minimal|full 설치 시 루트 문서 1개/4개.
7. (신설) Phase B 검증 스크립트 전 항목 통과: §5 블록 31 = 헤더 ID 31, §2/§3 완료 블록 누출 0, 잔재 토큰 20종 보존.

4. 범위 외 (Rev.1 §4 유지) + 추가

• nats-docker/PRIVATE_SERVER.md:5 깨진 링크 — 서브모듈 별도 커밋.
• 미해결 5건(A-2, B-16, B-17, B-18, O-5)의 코드 대조 재판정 — 별도 리뷰 잡. 특히 B-17은 MESSAGING.md:310이 "구현됨"으로 서술하고 있어 상태 불일치 의심이 있으나 본 작업에서는 손대지 않는다(코드 확인 없이 완료로 옮기면 원장 오염).
• README 배지 5번째 lockstep 레그 — 별도 잡.

5. 리스크

• Phase B는 이동·병합이 많아 유실 위험이 가장 크다. 반드시 B-1 → B-2 → B-3 → B-4 순서로 각 단계 후 검증 스크립트를 실행하고, 최종적으로 git diff --stat IMPROVEMENTS.md의 삭제 줄 수가 (잔재 33줄 + P0-2 제목 1줄 + 이관에 따른 이동분) 범위 안인지 확인한다. 이관은 git diff에서 삭제+추가로 보이므로 git diff --color-moved=plain으로 이동임을 확인한다.

---

부록. Rev.1 원문 중 유효 유지 항목 (변경 없음)

• §0 실측 인벤토리 표 및 KEEP/이관 판정 9건.
• §1 D-2(MESSAGING lib_py 미반영), D-3(README 트리), D-4(BOOTSTRAP §1), D-5(implementation_plan 이관), D-6(AGENTS §5).
• Phase A-1/A-3/A-4, Phase C 전체, Phase D-2~D-4, Phase E, Phase F, Phase G.