docs: clean up root markdown files and synchronize with v4.4.0 standards
- Relocate legacy implementation_plan.md to docs/contracts/nats-backplane/implementation_plan.md - Synchronize root documentation (README, README.ko, BOOTSTRAP, BOOTSTRAP.ko, AGENTS, MESSAGING, IMPROVEMENTS) to latest v4.4.0 standards - Consolidate IMPROVEMENTS.md to single source of truth (5 open / 31 completed tasks 1:1 matching section headers) - Archive unanimous PASS review reports from Claude, Grok, Codex, and OpenCode along with Plan Rev.2
This commit is contained in:
Godopu committed
1 parent
07cae71667
commit
f98b9582c7
13 files changed
+450
-112
No files matched your search
@@ -0,0 +1,138 @@
|
||||
# 📑 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 실행 필수)**:
|
||||
```bash
|
||||
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 추적 대상이다".
|
||||
```bash
|
||||
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.
|
||||
@@ -0,0 +1,52 @@
|
||||
# 🔍 Cross-Review Report (재검토) — Workspace Root Markdown 정리 및 최신화 (Job f28629a3)
|
||||
|
||||
- **리뷰어**: `planner-reviewer-claude-01` (Reviewer)
|
||||
- **기준**: `main` `07cae71` 워킹트리(미커밋). 직전 리뷰 `50886e6f`([VERDICT: NOT PASS], 차단 결함 D-1/D-2)에 대한 재검토.
|
||||
- **범위 고정**: 브리프 내장 diff = `git diff HEAD -- . ':(exclude).agents/reports'`(55,043 B) + 아카이브된 Rev.2 계획 사본(`.agents/reports/planner-reviewer-claude-01/plan-baea3f7e.md`). 두 diff의 차이는 계획 사본 블록(145줄)뿐. 변경 파일 8 + 이관 1, 코드·테스트·인스톨러 변경 0건.
|
||||
|
||||
---
|
||||
|
||||
## 1. 직전 리뷰 대비 델타 (실측: `diff head_5088.diff head_f286.diff`)
|
||||
정확히 3곳만 달라졌다. 그 외 diff 본문은 바이트 동일.
|
||||
|
||||
| # | 위치 | 변경 | 직전 지적 대응 |
|
||||
|---|---|---|---|
|
||||
| Δ1 | `MESSAGING.md:350` §5.1 CAS 문단 | "monotonic `dispatch_token`" → "opaque per-attempt `dispatch_token` (fresh `uuid4` hex issued whenever an attempt starts via `claim`/`redispatch`) … compared inside the registry lock as an `expected_dispatch_token` precondition; ordering … tracked separately by the monotonic `transition_seq` counter" | **D-1 해소** |
|
||||
| Δ2 | `MESSAGING.md:353` §5.1 항목 1 | 로그 경로 `<job_id>.<phase>.subscriber.out` → `<job_id>.subscriber.out (loop iterations use <job_id>.iter_<n>_<role>.subscriber.out)` | **D-2 해소** |
|
||||
| Δ3 | `IMPROVEMENTS.md:307-311` B-8 블록 | 앞 공백 2줄→1줄, 뒤 `---` 앞 공백 1줄 추가 | 비차단 O-2 해소 |
|
||||
|
||||
## 2. 델타의 코드 대조
|
||||
| 문장 요소 | 코드 근거 | 판정 |
|
||||
|---|---|---|
|
||||
| `dispatch_token` = 시도 시작 시 `uuid4` hex 재발급 | `engine.py:300` `record[DISPATCH_TOKEN_FIELD] = uuid.uuid4().hex`, 발급 조건 `request in ATTEMPT_STARTING_REQUESTS` (`engine.py:87` = `("claim", "redispatch")`) | ✅ |
|
||||
| 락 안에서 `expected_dispatch_token` 전제조건 대조 | `engine.py:181-183`; 계약 `docs/contracts/issue-5/state-transitions.md:57` | ✅ |
|
||||
| 순서는 `transition_seq` 단조 카운터 | `engine.py:296` `+ 1` 증가, 주석 "A monotonic counter" | ✅ |
|
||||
| `MAM_ENGINE_CAS=1` 기본 | `engine.py:109` | ✅ (변경 없음) |
|
||||
| direct 경로 `<job_id>.subscriber.out` | `multi-agent-mux-delegate-job:165` | ✅ |
|
||||
| 루프 경로 `<job_id>.iter_<n>_<role>.subscriber.out` | `:286` `${JOB_ID}.iter_${iteration}_${display_role}.subscriber.out` | ✅ |
|
||||
| `grep -n monotonic MESSAGING.md` | 3건: 227행(`last_seq`, HEAD 기존), 294행(monotonic time, HEAD 기존), 350행(`transition_seq`, 신규·정확). HEAD 기준 2건 → 3건 | ✅ 직전 리뷰 재검증 조건 충족 |
|
||||
|
||||
## 3. Rev.2 게이트 전건 재실행
|
||||
| 게이트 | 결과 |
|
||||
|---|---|
|
||||
| G1 루트 md 8개, 이관 파일 존재 | ✅ 8 |
|
||||
| G2 문서 바인딩 4모듈 | ✅ **49 passed** (57.96s) |
|
||||
| G3 전체 스위트 | §5 |
|
||||
| G4 상대 링크 (서브모듈 인식 보강판: `nats-docker/*`는 `git -C nats-docker ls-files`로 추적 확인) | ✅ BROKEN/UNTRACKED 0건 (직전 오탐 6건 해소) |
|
||||
| G5 `.agents/skills`, `tests`, `deploy` 무변경 | ✅ stat 0줄 |
|
||||
| G6 인스톨러 | ✅ minimal rc=0 `AGENTS.md`; full rc=0 `AGENTS.md BOOTSTRAP.ko.md BOOTSTRAP.md MESSAGING.md` |
|
||||
| G7 원장 | ✅ `## 2.`/`## 3.` 1/1, §5 블록 31 = 헤더 ID 31, 10개 핵심 ID 제목 각 1회, §2~§3 `✅` 누출 0, 잔재 토큰 **20/20** 보존 |
|
||||
| README 트리 | ✅ 40/40줄, 루트 md 8/8 |
|
||||
|
||||
## 4. 잔여 관측 (비차단, 조치 불요)
|
||||
- O-1(직전) B-14 "원 진단" 불릿과 `현상` 불릿 부분 중복 — 유지됨. 토큰 보존 목적이므로 허용.
|
||||
- README `tests/ (32 modules)` — `test_*.py` 31 + `conftest.py` 1. 계수 기준 미명시이므로 허용.
|
||||
- 게이트 4 스크립트의 서브모듈 오탐은 Planner(본인) 측 스크립트 결함이었으며 본 리뷰에서 보강판으로 대체. 향후 계획서 게이트에 반영 필요(Planner 후속).
|
||||
|
||||
## 5. 전체 회귀 스위트 (G3)
|
||||
- `.venv/bin/python -m pytest -q tests/` (워킹트리, 본 변경 적용): **750 passed in 930.36s (0:15:30)**, FAILED/ERROR 0건. 기준선 `07cae71`(750)과 동일.
|
||||
|
||||
## 6. 결론
|
||||
직전 차단 결함 D-1(`dispatch_token` 단조성 오기)·D-2(submit 로그 경로 오기)는 제시한 검증 문장으로 정확히 교체되었고, 코드(`engine.py:87/296/300`, `multi-agent-mux-delegate-job:165/286`)와 일치한다. 그 외 diff는 직전 리뷰 시점과 바이트 동일하며 모든 게이트(문서 테스트 49, 전체 750, 링크 0건 깨짐, 인스톨러 두 모드, 원장 31=31, 잔재 토큰 20/20, README 트리 40/40)를 통과한다. 린트·동작성·유실 관점 모두 결함 없음.
|
||||
|
||||
[VERDICT: PASS]
|
||||
@@ -0,0 +1,28 @@
|
||||
# Cross-review — root Markdown cleanup, follow-up
|
||||
|
||||
Job: `fd874949`
|
||||
Reviewer: `planner-reviewer-codex-01` (`planner,reviewer`)
|
||||
Baseline: `07cae71`, current working tree including the staged roadmap move.
|
||||
|
||||
No blocking findings remain. Both findings from review `2601270d` are resolved by documentation changes that match the implementation.
|
||||
|
||||
## Previous findings verified as resolved
|
||||
|
||||
1. **Optional dispatch-token comparison — resolved (`MESSAGING.md:350`).** The paragraph now distinguishes the token stored for an attempt from the optional `expected_dispatch_token` supplied by callers. It explicitly states that ordinary publisher status updates do not supply the precondition. This matches `lib_py/delegation/engine.py:181` and `:270`, the publisher update path in `lib_py/delegation/mqtt_common.py:435`, and inferred completion in `lib_py/loop/autocomplete.py:224`. Token generation and transition ordering also match `engine.py:296-300`.
|
||||
|
||||
2. **Subscriber readiness fallback — resolved (`MESSAGING.md:354`).** The handshake bullet now describes a bounded readiness attempt, warning and continuation after the polling budget expires, and continuation on early exit status 0 or 3. These statements match `multi-agent-mux-delegate-job/multi-agent-mux-delegate-job:172-194`; the previous unconditional readiness guarantee has been removed.
|
||||
|
||||
## Verification and review scope
|
||||
|
||||
- Compared the complete embedded diff payloads of jobs `2601270d` and `fd874949`: only the two passages above and the corresponding `MESSAGING.md` blob hash changed. The previously reviewed roadmap move, backlog consolidation, bilingual trees, bootstrap updates, and archived reports are unchanged.
|
||||
- Verified every file included in the new brief against its recorded new Git blob hash; all match the current files.
|
||||
- `git diff HEAD --check`: clean.
|
||||
- No changes under `.agents/skills/`, `tests/`, or `deploy/`.
|
||||
- Root Markdown inventory remains the required eight files. Backlog section counts remain **1 / 3 / 1 / 0 / 31**, with no completed blocks in sections 2 or 3.
|
||||
- Rechecked **34 local link targets**, including six references tracked inside the `nats-docker` submodule: all exist and are tracked. The plan's parent-repository-only tracking check produces submodule false positives; validating those targets within their owning repository resolves them.
|
||||
- Prior independent preservation checks remain applicable because the relevant files are byte-identical to the preceding review: O-1 content, moved completed blocks, legacy diagnosis details, README tree parity, and roadmap links showed no content-loss defect.
|
||||
- Prior independent focused regression result from job `2601270d`: **49 passed in 54.88s**, using `tests/test_deploy_layout.py`, `tests/test_o1_rebuttal.py`, `tests/test_deploy_freshness.py`, and `tests/test_version_consistency.py`. This run was not repeated for the two prose corrections. The attached peer report's full-suite result of 750 passing tests and minimal/full installation checks remain attributed peer evidence, not an independent rerun in this job.
|
||||
|
||||
The two requested wording corrections close the review. No runtime changes or planner escalation are needed.
|
||||
|
||||
[VERDICT: PASS]
|
||||
@@ -0,0 +1,35 @@
|
||||
# Root markdown cleanup review (uncommitted tree on `07cae71`)
|
||||
|
||||
- **Reviewer**: `reviewer-creator-grok-01`
|
||||
- **Job**: `30122522`
|
||||
- **HEAD**: `07cae71` (working tree)
|
||||
- **Diff**: `AGENTS.md`, `BOOTSTRAP.md` / `.ko.md`, `IMPROVEMENTS.md`, `MESSAGING.md`, `README.md` / `.ko.md`, `implementation_plan.md` → `docs/contracts/nats-backplane/implementation_plan.md`
|
||||
- **Checks**: `git diff --check` clean. Root `*.md`: `AGENTS.md`, `BOOTSTRAP.md`, `BOOTSTRAP.ko.md`, `IMPROVEMENTS.md`, `MESSAGING.md`, `README.md`, `README.ko.md`, `VERSIONS.md`.
|
||||
|
||||
Documentation only. No production tests required. Tree re-read independently (same diff as job `01859590`; residuals below still present).
|
||||
|
||||
---
|
||||
|
||||
## What holds
|
||||
|
||||
The NATS backplane plan is off the workspace root and lives next to Issue #5 contracts. The new file records the move date and uses working relative links to `nats-docker/NATS_REPORT.md` and `PRIVATE_SERVER.md`.
|
||||
|
||||
`BOOTSTRAP.md` / `.ko.md` list `lib_py/{agents,delegation,loop}` and call `scripts/*.py` shims. `README.md` / `.ko.md` do the same in the skills list and directory tree. `MESSAGING.md` stamps v4.4.0, names `lib_py.delegation` as the body, notes CAS/`dispatch_token`, and marks HMAC as implemented. `AGENTS.md` O-3 still delegates via `run_loop.sh` and names the Python loop runtime.
|
||||
|
||||
`IMPROVEMENTS.md` is one ledger: **5 open** (A-2, B-16, B-17, B-18, O-5) and **31 completed**. Header IDs match completed `###` headings. Merge-duplicate B-14/B-15/B-16 blocks are gone. O-2 (P0-2) is still in §5. B-13 notes freeze removal in v4.4.0.
|
||||
|
||||
---
|
||||
|
||||
## Residuals (non-blocking)
|
||||
|
||||
1. **README architecture narrative was not updated.** Skills list and tree mention `lib_py.loop`; Layer A is still “lib.sh + status/resume/stop/create” and Layer B does not mention the CAS engine (`README.md:62-63`, same in `README.ko.md:44-45`).
|
||||
2. **Inbound link not updated with the move.** `nats-docker/PRIVATE_SERVER.md:5` still points `implementation_plan.md` at `lac/curriculum/How_To_Use_GENAI/implementation_plan.md`. After this relocate it should be `../docs/contracts/nats-backplane/implementation_plan.md`. `IMPROVEMENTS.md` still names `NATS_REPORT.md` without a path; the file is `nats-docker/NATS_REPORT.md`.
|
||||
3. **Stale line number.** B-16 still says `mqtt_common.py:258`; `client_id` is built at `lib_py/delegation/mqtt_common.py:276`.
|
||||
4. **BOOTSTRAP parent line** still calls `skills/` “a collection of shell scripts” while listing `lib_py/` under it.
|
||||
5. **`AGENTS.md` / `README.md` have no trailing newline.** Pre-existing. `git diff --check` is clean.
|
||||
|
||||
No `[ESCALATE: PLANNER]`.
|
||||
|
||||
---
|
||||
|
||||
[VERDICT: PASS]
|
||||
@@ -0,0 +1,50 @@
|
||||
# 🔍 Cross-Review: Workspace Root Markdown Cleanup & Modernization (Job b049e495)
|
||||
|
||||
- **Reviewer**: `reviewer-opencode-01` (role: reviewer)
|
||||
- **Target**: Uncommitted working tree on `main` @ `07cae71` (v4.4.0): 7 modified root docs + 1 rename (`implementation_plan.md` → `docs/contracts/nats-backplane/implementation_plan.md`) — the Rev.2 plan (`plan-baea3f7e.md`) executed, refined through multiple review rounds (Claude `50886e6f` NOT PASS → `f28629a3` PASS re-review; Grok `30122522` PASS; codex `2601270d` findings remediated by `09f2c915`).
|
||||
- **Method**: All plan gates re-run by me against the live tree — ledger algebra, link integrity (submodule-aware), tree parity, installer modes, doc-binding tests, the full regression suite, and every new MESSAGING.md technical claim traced to code.
|
||||
|
||||
---
|
||||
|
||||
## 0. My Verification Runs
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| Full suite `pytest tests/ -q` (my own run, started in the interrupted `ee242671` round; tree unchanged since — only MESSAGING.md §350/§354 prose refined, no code/tests touched) | **750 passed / 0 failed** (983s) — identical to the `07cae71` baseline |
|
||||
| Doc-binding 4-module suite (G2) | **49 passed** |
|
||||
| Installer both modes (G6) | minimal rc=0, full rc=0 |
|
||||
| Code/test/deploy drift | **0 files** — pure documentation change |
|
||||
|
||||
## 1. All Rev.2 gates re-verified by me
|
||||
|
||||
- **G1**: Root markdowns exactly 8 (AGENTS, BOOTSTRAP, BOOTSTRAP.ko, IMPROVEMENTS, MESSAGING, README, README.ko, VERSIONS); NATS plan relocated to `docs/contracts/nats-backplane/` via proper git rename, with move-date annotation and `../../../`-prefixed links; the §7 `.mam.env` link correctly retargeted to the tracked `.mam.env.example` (challenge C-2's gitignored-file trap avoided).
|
||||
- **G4 (links)**: All relative links resolve and are git-tracked — 0 broken. (My first run flagged 6 `nats-docker/*` paths; I traced this to my own script lacking submodule handling — the files exist and are tracked in the submodule's repo, exactly the false-positive Claude's `f28629a3` documented and fixed. Submodule-aware re-run: clean.)
|
||||
- **G7 (IMPROVEMENTS.md single ledger)**: single `## 2.`/`## 3.` headers; §5 = **31 blocks** = header **31 IDs**; per-ID `###` uniqueness holds for all spot-checked IDs; zero ✅ leakage into §2/§3; all 20 remnant-only tokens (B-14/B-15 original diagnoses, O-5 nats-py rationale, etc.) preserved ≥1 occurrence each — merged-then-deleted as the plan required, not silently dropped.
|
||||
- **README trees**: 45/45 line parity, all 8 root mds in both trees' tree blocks (each exactly once within the block; the extra `BOOTSTRAP.md`/`VERSIONS.md` occurrences are the prose link and version badge — outside the tree block, expected).
|
||||
- **O-1 preserved string**: covered by the passing `test_o1_rebuttal.py` in the 49.
|
||||
|
||||
## 2. The codex-review remediations (`2601270d` → `09f2c915`) — independently verified against code
|
||||
|
||||
This diff's MESSAGING.md §5.1 evolved after my interrupted prior round; the two changes are the codex reviewer's precision findings, and I verified both remediations against live source myself:
|
||||
|
||||
1. **`dispatch_token` precondition correctly scoped as optional** (MESSAGING.md:350) — verified: `engine.py:181` compares only `if expected_dispatch_token is not None` (default `None` at :147/:270); `mqtt_common.py:435` (ordinary publisher updates) calls `engine.transition` without the precondition; `lib_py/loop/autocomplete.py:224` (inferred completion) explicitly supplies `expected_dispatch_token=token`; token issuance gated on `ATTEMPT_STARTING_REQUESTS = ("claim", "redispatch")` (`engine.py:87`, `uuid4().hex` at :300); ordering by monotonic `transition_seq` (+1 at :296); `MAM_ENGINE_CAS` default-on (:109). Every sentence in the paragraph matches code.
|
||||
2. **Subscriber handshake described as bounded wait with fallback** (MESSAGING.md:354) — verified: `multi-agent-mux-delegate-job:172-195` polls `^SUBSCRIBED ` every 0.2s for 25 iterations; on budget expiry it warns ("falling back to proceed") and proceeds; early subscriber exits 0 or 3 permit continuation. The old "ensure the subscriber is connected" overstated the guarantee — now accurate.
|
||||
3. The D-1/D-2 fixes from the earlier Claude NOT PASS round (monotonic-token mischaracterization; `<job_id>.<phase>.subscriber.out` path error) remain correctly in place — the direct path `<job_id>.subscriber.out` (:165) and loop path `iter_<n>_<role>.subscriber.out` (:286) both match the doc, and `monotonic` appears exactly 3 times, all now accurate.
|
||||
|
||||
## 3. Peer-review trail (all registry-verified)
|
||||
|
||||
The chain is honest and complete: plan Rev.1 (`45bd8635`) → challenge (`87aa5b5a`, 3 findings all accepted) → plan Rev.2 (`baea3f7e`) → execution → Grok PASS (`30122522`, residuals non-blocking) → Claude NOT PASS (`50886e6f`, D-1/D-2 factual errors) → remediation → Claude PASS re-review (`f28629a3`, all gates green + 750 suite) → codex review (`2601270d`, 2 precision findings) → remediation (`09f2c915`, verified) → this review. Grok's residuals (README architecture narrative, `PRIVATE_SERVER.md` inbound link, B-16 stale line number, BOOTSTRAP "shell scripts" parent line, trailing newlines) remain — all non-blocking, all explicitly out-of-scope per the plan (§4).
|
||||
|
||||
## 4. Residual observations (non-blocking)
|
||||
|
||||
- Grok's five residuals stand as documented — each is a candidate for a follow-up docs pass, none affects correctness.
|
||||
- `README tests/ (32 modules)` counts `test_*.py` + `conftest.py`; counting basis unstated but tolerable.
|
||||
- The prior interrupted round's own report artifact (`ee242671`) was never published — this report supersedes it; the job registry shows only its `started` event, consistent with an interrupted run.
|
||||
|
||||
---
|
||||
|
||||
## 5. Verdict
|
||||
|
||||
Every Rev.2 acceptance gate passes under my own re-execution (root 8 + relocation, 49 doc-binding tests, 750 full-suite green, 0 broken links submodule-aware, installer both modes, ledger 31=31 with zero ✅ leakage and all remnant tokens preserved, README trees in parity, zero code/test/deploy drift). The two most recent precision findings (codex) are correctly remediated with every technical claim independently traced to code by me, and the multi-round review chain — including a genuine NOT PASS → fix → re-verify cycle — is recorded honestly. Documentation-only change with no functional risk.
|
||||
|
||||
[VERDICT: PASS]
|
||||
Reference in new issue
Block a user