release(v4.9.2): README rewritten against the code, README.ko.md in step - archive the review reports and bump the lockstep version

Review loop (--review-only, --all-reviewer, fact-checked against the code): rounds 1-3 NOT PASS with factual corrections, round 4 (@62da805) 4/4 PASS. Documentation only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCgu9Fa9iT7TbJUSzdq4Ff
2026-10-13 11:57:33 +09:00
1 parent 62da805668
commit e3bcdee834
@@ -0,0 +1,14 @@
+{
+  "loop_id": "loop-20261013T025132Z-60f239",
+  "base_sha": "ae2813773c973daedd2275cb55ad340a682c3fae",
+  "head_sha": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "tree_sha": "f549246ffbe2d5e58cb7e33c212a383cd429dce5",
+  "review_commit": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "reviewer": "planner-reviewer-claude-01",
+  "job_id": "8b2392ce",
+  "verdict": "PASS",
+  "transport": "herdr",
+  "evidence": "review-tree",
+  "isolation": "worktree",
+  "verified_at": "2026-10-13T02:56:58Z"
+}
@@ -0,0 +1,22 @@
+# README.md / README.ko.md 4차 리뷰 — 커밋 62da805 (job 8b2392ce)
+
+- 리뷰어: planner-reviewer-claude-01 (Reviewer)
+- 리뷰 identity: loop-20261013T025132Z-60f239 / base ae281377 .. head 62da8056 (커밋 1개, 두 README 각 2줄) / tree f549246f
+- 검증 경로: `/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1` — HEAD·tree 일치, `git status --porcelain` 0 줄(시작·종료). 본 체크아웃 HEAD 2ccf439(main) 변동 없음.
+- 방법: 바뀐 두 문장만 코드와 대조. `generate-env.sh`·설치기는 실행하지 않았고, 테스트도 돌리지 않았다(픽스처 집계는 `pytest --co` 에 수집 전용 플러그인을 얹어 `fixturenames` 만 셌다; `env -i`, basetemp 는 scratchpad). 실제 서버·세션·`.mam`·`.mam.env`·에이전트 홈 미접촉.
+
+## 1. 두 문장의 코드 대조
+
+| 문장 (README.md / README.ko.md 같은 줄) | 근거 | 판정 |
+|---|---|---|
+| **:41** `generate-env.sh` 는 `.mam.env` 가 없을 때 `.mam.env.example` 로 만들고, `--force` 는 `.mam.env.bak` 을 남기고 덮어씀 | `deploy/generate-env.sh:54-64`: `[ -f "$DST" ] && [ "$FORCE" != "1" ]` → "no-op … (use --force to overwrite)" `exit 0`; `[ -f "$DST" ] && [ "$FORCE" = "1" ]` → `cp -p "$DST" "$DST.bak"`; 그 뒤 `cp "$SRC" "$DST"`. 머리 주석(`:5-7`)과도 일치 | ✓ |
+| **:175** 모든 테스트는 임시 잡 레지스트리·감사 로그; 약 3분의 1 이 임시 HOME 샌드박스 픽스처, 그보다 적은 수가 mock herdr | 이 head 에서 수집 1901 개 중 `fixturenames` 에 `mam_sandbox` 포함 **575 (30 %)**, `mock_herdr` 포함 **186 (9 %)**(`mock_agents` 125). grok 집계(1708 중 573/196)와 모수만 다르고 비율은 같다. "약 3분의 1" 과 "그보다 적은 수" 모두 맞음. 전체 테스트의 임시 레지스트리·로그는 `conftest.py:170-181` 의 autouse 픽스처(3차에서 확인) | ✓ |
+
+## 2. 두 언어의 일치
+- 두 문장 모두 영문·한국어가 같은 조건·같은 수치를 말한다(없을 때 생성 / `--force` 는 `.bak` 남기고 덮어씀; 약 3분의 1 / 그보다 적은 수).
+- 구조(head): 제목 18/18, 표 행 17/17, 코드 블록 7/7(번역 주석 블록 외 동일), 숫자 집합 동일, 백틱 토큰 차이는 `MULTI_AGENT_RULES.md` ↔ `.ko.md` 뿐.
+
+## 결론
+grok 21063f28 의 두 지적이 코드와 맞게 고쳐졌고 두 언어가 같다. 앞 라운드에서 내가 남겼던 `generate-env.sh` 메모도 이 커밋으로 해소됐다. 남은 지적 없음.
+
+[VERDICT: PASS]
@@ -0,0 +1,14 @@
+{
+  "loop_id": "loop-20261013T025132Z-60f239",
+  "base_sha": "ae2813773c973daedd2275cb55ad340a682c3fae",
+  "head_sha": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "tree_sha": "f549246ffbe2d5e58cb7e33c212a383cd429dce5",
+  "review_commit": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "reviewer": "planner-reviewer-codex-01",
+  "job_id": "a2716e3b",
+  "verdict": "PASS",
+  "transport": "herdr",
+  "evidence": "review-tree",
+  "isolation": "worktree",
+  "verified_at": "2026-10-13T02:56:58Z"
+}
@@ -0,0 +1,45 @@
+# README 4차 리뷰 — a2716e3b
+
+판정: PASS. 지정된 두 문장의 수정에서 차단할 사실 오류나 영문·한국어 의미 불일치를 발견하지 못했습니다.
+
+## 리뷰 identity 및 범위
+
+- loop: `loop-20261013T025132Z-60f239`
+- base: `ae2813773c973daedd2275cb55ad340a682c3fae`
+- head: `62da8056680fca939a2aff924037ed48b5f74afa`
+- tree: `f549246ffbe2d5e58cb7e33c212a383cd429dce5`
+- 검증 경로: `/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1`
+- HEAD/tree가 브리프와 일치하고 작업 트리가 clean임을 확인했습니다. 이번 커밋만 검토했으며, 두 README에서 각각 41행과 175행만 변경된 것을 확인했습니다.
+
+## 검토 결과
+
+### 1. generate-env.sh 설명 — PASS
+
+`README.md:41`, `README.ko.md:41`은 대상 파일이 없을 때 생성하고, `--force`로 기존 파일을 덮어쓸 때 `.mam.env.bak`을 남긴다고 동일하게 설명합니다.
+
+- `deploy/generate-env.sh:17–18`: 템플릿과 대상 경로를 `.mam.env.example`, `.mam.env`로 지정합니다.
+- 54–56행: 대상이 있고 `--force`가 없으면 성공 코드로 종료하며 변경하지 않습니다.
+- 59–61행: 대상이 있고 `--force`가 있으면 `cp -p "$DST" "$DST.bak"`으로 백업합니다.
+- 64행: 템플릿을 대상으로 복사합니다.
+
+머리 주석 5–7행뿐 아니라 실제 분기를 확인했습니다. 별도 옵션인 `--migrate-legacy`는 이번 문구의 기본 생성/force 설명과 충돌하지 않습니다. 스크립트는 실행하지 않았습니다.
+
+### 2. 테스트 격리 범위 — PASS
+
+`README.md:175`, `README.ko.md:175`은 모든 테스트의 임시 잡 경로와 일부 테스트가 쓰는 임시 HOME/mock herdr를 구별합니다.
+
+- `tests/conftest.py:170–181`: autouse `_isolate_mam_state_dirs`가 테스트별 임시 잡 레지스트리와 감사 로그 경로를 설정합니다.
+- 195–207행: autouse 에이전트 환경 정리 자체는 HOME을 바꾸지 않는다고 명시합니다.
+- 228–269행: 선택적 `mam_sandbox`가 HOME과 레지스트리를 임시 경로로 설정합니다.
+- 312–315행: 별도 `mock_herdr` 픽스처가 `mam_sandbox`에 의존하여 mock 실행 파일을 제공합니다. 샌드박스 사용 자체가 mock 사용을 의미하지 않습니다.
+
+브리프에 제시된 수집 항목 집계는 1708개 중 샌드박스 573개(33.55%), mock 196개(11.48%)이므로 새 표현과 맞습니다. 이 정확한 pytest 수집 수는 재수집하지 않았습니다. 독립적인 AST 정적 확인에서는 테스트 함수 정의 1272개 중 명시적 인자/데코레이터 및 픽스처 의존 경로로 `mam_sandbox` 485개, `mock_herdr` 168개를 확인했습니다. 이 수치는 매개변수화된 pytest 항목 수가 아니며, 클래스/모듈 수준의 간접 지정까지 완전 재현한 집계도 아닙니다. “대부분”이라는 이전 과장을 제거하고 mock 사용 범위를 더 좁힌 수정 방향을 뒷받침하는 보조 확인으로만 사용했습니다.
+
+## 검증 및 제한
+
+- `git diff --check ae28137..HEAD`: 성공.
+- 양 문서의 변경 행이 정확히 `[41, 175]`이며 줄 수가 유지됨을 정적 검사로 확인했습니다. 나머지 문장·명령·다이어그램은 이번 커밋에서 바뀌지 않았습니다.
+- 두 변경 문장의 조건과 수량 표현이 EN/KO에서 일치합니다.
+- 테스트, 설치기, 환경 생성 스크립트, 실제 herdr/에이전트/monitor는 실행하지 않았습니다. 지정 리뷰 트리의 파일만 읽었고 소스·문서·실제 설정 파일을 수정하지 않았습니다. pytest 전체 통과 또는 정확한 수집 수 재현을 주장하지 않습니다.
+
+[VERDICT: PASS]
@@ -0,0 +1,14 @@
+{
+  "loop_id": "loop-20261013T025132Z-60f239",
+  "base_sha": "ae2813773c973daedd2275cb55ad340a682c3fae",
+  "head_sha": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "tree_sha": "f549246ffbe2d5e58cb7e33c212a383cd429dce5",
+  "review_commit": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "reviewer": "reviewer-agy-01",
+  "job_id": "f3b2d22c",
+  "verdict": "PASS",
+  "transport": "herdr",
+  "evidence": "review-tree",
+  "isolation": "worktree",
+  "verified_at": "2026-10-13T02:56:58Z"
+}
@@ -0,0 +1,67 @@
+# Code Review Report (4th Round): `docs/readme-refresh` (README.md & README.ko.md Targeted Refinement)
+
+- **Job ID**: `f3b2d22c`
+- **Reviewer**: `agy` (Session: `herdr:reviewer-agy-01`, Role: `Reviewer`)
+- **Date**: 2026-10-13
+- **Target Branch**: `docs/readme-refresh`
+- **Base Commit**: `ae2813773c973daedd2275cb55ad340a682c3fae`
+- **Head Commit**: `62da8056680fca939a2aff924037ed48b5f74afa`
+- **Verification Path**: `/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1`
+- **Verification Environment**: macOS (Darwin 24.3.0, arm64), Python 3.9.6
+
+---
+
+## 1. Executive Summary
+
+This 4th-round review evaluated commit [`62da8056680fca939a2aff924037ed48b5f74afa`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1), which addresses 3rd-round reviewer feedback (grok `21063f28`) regarding two targeted descriptions across [`README.md`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/README.md) and [`README.ko.md`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/README.ko.md):
+1. Clarification that [`deploy/generate-env.sh`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/deploy/generate-env.sh) creates `.mam.env` only when missing, and `--force` backs up `.mam.env` to `.mam.env.bak` before overwriting.
+2. Accurate quantification of test isolation fixtures: all tests get temporary job registry and audit-log directories, while roughly one-third use sandbox temporary HOME fixtures, and an even smaller subset use mock herdr.
+
+Both changes have been verified against the codebase and found factually accurate. Bilingual parity between English and Korean is fully preserved.
+
+**Verdict: PASS**.
+
+---
+
+## 2. Technical Item Verification
+
+### 2.1 `deploy/generate-env.sh` Behavior
+- **Code Inspection** ([`deploy/generate-env.sh:54-64`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/deploy/generate-env.sh#L54-L64)):
+  - If `.mam.env` exists and `--force` is not passed, the script exits immediately with no-op:
+    ```bash
+    if [ -f "$DST" ] && [ "$FORCE" != "1" ]; then
+      echo "no-op: $DST already exists (use --force to overwrite)"
+      exit 0
+    fi
+    ```
+  - If `.mam.env` exists and `--force` is passed, it creates a backup copy at `.mam.env.bak` before overwriting:
+    ```bash
+    if [ -f "$DST" ] && [ "$FORCE" = "1" ]; then
+      cp -p "$DST" "$DST.bak"
+      echo "backed up existing .mam.env -> $DST.bak"
+    fi
+    cp "$SRC" "$DST"
+    ```
+- **Documentation Verification**:
+  - *EN*: `deploy/generate-env.sh creates .mam.env from .mam.env.example when it is missing (--force overwrites it, keeping a .mam.env.bak).`
+  - *KO*: `deploy/generate-env.sh 는 .mam.env 가 없을 때 .mam.env.example 로 만듭니다(--force 는 .mam.env.bak 을 남기고 덮어씁니다).`
+- **Evaluation**: Accurately reflects the conditional creation and backup semantics of `generate-env.sh`.
+
+### 2.2 Test Isolation Scoping & Proportions
+- **Code Inspection** ([`tests/conftest.py`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/tests/conftest.py)):
+  - `_isolate_mam_state_dirs` is `autouse=True`, executing for 100% of tests.
+  - Of 1,272 test functions defined across `tests/`, 418 (~32.8%, roughly one-third) declare sandbox fixtures (`mam_sandbox`, `temp_home`), and only 158 declare `mock_herdr`.
+- **Documentation Verification**:
+  - *EN*: `Every test gets a temporary job registry and audit-log directory. About a third also use the sandbox fixtures, which set a temporary HOME (and, for fewer, a mock herdr):`
+  - *KO*: `모든 테스트는 임시 잡 레지스트리와 감사 로그 디렉터리를 씁니다. 약 3분의 1 은 임시 HOME 을 설정하는 샌드박스 픽스처도 쓰고, 그보다 적은 수는 mock herdr 도 씁니다.`
+- **Evaluation**: The replacement of "most" with "about a third" (and fewer for mock herdr) accurately aligns the documentation with actual test fixture distribution.
+
+---
+
+## 3. Bilingual Alignment & Integrity
+- Both updated lines in [`README.md`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/README.md) and [`README.ko.md`](file:///var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261013T025132Z-60f239/1/README.ko.md) maintain exact semantic, technical, and structural parity.
+- Markdown formatting, links, and code backticks remain intact and consistent.
+
+---
+
+[VERDICT: PASS]
@@ -0,0 +1,14 @@
+{
+  "loop_id": "loop-20261013T025132Z-60f239",
+  "base_sha": "ae2813773c973daedd2275cb55ad340a682c3fae",
+  "head_sha": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "tree_sha": "f549246ffbe2d5e58cb7e33c212a383cd429dce5",
+  "review_commit": "62da8056680fca939a2aff924037ed48b5f74afa",
+  "reviewer": "reviewer-grok-01",
+  "job_id": "2311b972",
+  "verdict": "PASS",
+  "transport": "herdr",
+  "evidence": "review-tree",
+  "isolation": "worktree",
+  "verified_at": "2026-10-13T02:56:58Z"
+}
@@ -0,0 +1,15 @@
+# Review 2311b972 — test share and generate-env.sh
+
+Head `62da8056680fca939a2aff924037ed48b5f74afa` (tree `f549246ffbe2d5e58cb7e33c212a383cd429dce5`) is the one commit `62da805 docs(readme): round-3 review fixes (21063f28)` on base `ae2813773c973daedd2275cb55ad340a682c3fae`. Two files, `README.md` and `README.ko.md`, two lines each, +4/−4. `git diff --check` is clean. Snapshot porcelain empty. Control-plane main is still `2ccf43911cda78fd0655c3770eec90cd22ec2d1b`, porcelain empty.
+
+## The two sentences match
+
+`README.md:175` says every test gets a temporary job registry and audit-log directory, about a third also use the sandbox fixtures that set a temporary HOME, and fewer of those use a mock herdr. That is the count from the previous review of this same test tree: weighting the parametrize lists written out in the source, 573 of 1708 (34%) reach a temporary HOME and 196 of 1708 (11%) reach `mock_herdr`. The autouse fixture still points every test's registry and audit log at a temporary directory (`tests/conftest.py:170-186`). `README.ko.md:175` says the same fraction and the same split.
+
+`README.md:41` says `deploy/generate-env.sh` creates `.mam.env` from `.mam.env.example` when `.mam.env` is missing, and that `--force` overwrites it while keeping a `.mam.env.bak`. The script copies the example when the destination is absent (`deploy/generate-env.sh:54-64`). When the destination exists and `--force` is absent, it exits 0 without writing (`:54-57`). With `--force` and an existing file, it copies that file to `$DST.bak`, which is `.mam.env.bak`, and then copies the example over it (`:59-64`). `README.ko.md:41` says the same.
+
+The script was not executed. No herdr server was started. The suite was not run.
+
+User `~/.config/herdr/config.toml` mtime stayed `1784456394`.
+
+[VERDICT: PASS]