fix(scripts): 색인 절을 총괄이 쓰는 라운드의 색인 검사를 --extra-index로 한다

문제: 독립 리뷰어 둘이나 여러 리뷰 세션이 한 라운드를 나눠 보면, 정본 리뷰어는
영역 문서를 리뷰 폴더에 커밋하지만 README 색인 절은 총괄이 쓴다. 그래서 정본
리뷰어가 커밋한 트리의 색인 검사는 반드시 rc=1인데, improve.md는 리뷰어에게
rc=0을 요구했다(round8 발견 RR8-06-01). 두 규칙을 함께 지킬 수 없었다.

고른 방법: check-review-index.py에 --extra-index <파일>을 더했다. 리뷰어가
보고에 둔 색인 표 파일을 색인의 일부로 센다. improve.md 4.1절 7·8단계와 5절,
delegate.md 4.1절, 결정 색인 「리뷰 README 분담」에 쓰는 법을 적었다. 버린 안:
리뷰가 권한 "보고 표를 붙인 README 임시 사본" 절차 — 복사·붙이기 단계가 늘고
같은 대조를 손으로 한다. 정본 리뷰어가 README 색인 절을 먼저 쓰는 안 — 결정
「리뷰 README 분담」을 뒤집는다.

위험·한계: --extra-index는 넘긴 파일 전체를 색인으로 읽는다. 표만 담은 파일을
넘겨야 한다(노트 전체를 넘기면 본문에 나온 ID도 색인으로 센다). 매뉴얼에
"색인 표만 담은 파일"로 적었다.

검증(트리 3c305d7a, desktop 로그 ~/manual-gap-fix-2-logs/B-*):
- RED: 정본 리뷰어 커밋 27260ad0의 리뷰 폴더에 옵션 없이 rc=1(180 중 172)
- GREEN: 리뷰어 A의 색인 표를 --extra-index로 넘기면 rc=0(180/180)
- 지금 트리 docs/reviews/2026-11-03-rereview rc=0(182/182), 없는 파일을
  넘기면 rc=1
- check-work-docs.py 기본·--history docs/manual·--links rc=0

Refs: docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md RR8-06-01
This commit is contained in:
DongHyeonka
2026-11-07 07:02:09 +09:00
parent 6b253c6c75
commit 51230caf62
4 changed files with 29 additions and 6 deletions
+1 -1
View File
@@ -38,7 +38,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
- 두 리뷰가 끝나면 총괄이 합친다. 같은 결함(같은 원인·같은 위치)끼리 짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어에게 보내 탐침으로 다시 확인한 뒤 다음 번호로 넣게 한다. 그 라운드 색인 절은 총괄이 쓰고 대응표(`B-NN-MM` → 정본 ID)를 둔다.
- 겹침 비율(두 리뷰가 모두 찾은 결함 수 / 합친 결함 수)을 그 라운드 색인 절과 design-docs `delegation-loop/metrics.md`의 M11 칸에 적는다. 2~3라운드 기록이 쌓이면 소유자가 이 방식을 다시 본다.
- 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다.
- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 수정 묶음은 색인에서 배정한다.
- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 색인 절을 총괄이 쓰기 전에는 리뷰어 보고의 표를 `--extra-index <파일>`로 넘겨 본다. 수정 묶음은 색인에서 배정한다.
- 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md).
### 4.2 나누는 법 — 이 repo
+3 -3
View File
@@ -42,8 +42,8 @@
4. 전체 리뷰는 게이트를 먼저 한 번 돌려 결과를 적고([reference/gates.md](reference/gates.md)), 영역을 나눈다([delegate.md](delegate.md) 「나누는 법」).
5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs `conventions/delegation-loop.md` 11절), worktree는 지운다.
6. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 발견마다 증거 수준과 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다.
7. 리뷰 폴더 README에 이번 라운드의 색인 절 하나를 더한다: 발견 ID, 심각도, 한 줄 내용, 결정이 필요한 질문. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. README의 다른 절(처리 표, 결정의 답, 라운드 끝 게이트)은 맡긴 쪽이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 맡긴 쪽이 쓰고, 리뷰어는 보고에 같은 표를 둔다.
8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. rc=0이어야 한다. 지난 라운드 색인에서 빠진 ID 때문에 처음부터 rc=1이면, 빠진 ID를 이번 색인 절에 「색인 보완」 한 줄로 이름만 적는다. 지난 영역 문서는 고치지 않는다.
7. 리뷰 폴더 README에 이번 라운드의 색인 절 하나를 더한다: 발견 ID, 심각도, 한 줄 내용, 결정이 필요한 질문. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. README의 다른 절(처리 표, 결정의 답, 라운드 끝 게이트)은 맡긴 쪽이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 맡긴 쪽이 쓰고, 리뷰어는 README를 고치지 않고 보고에 같은 표를 둔다.
8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌려 rc=0을 본다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. 색인 절을 맡긴 쪽이 쓰면 보고의 색인 표만 담은 파일을 `--extra-index <파일>`로 넘겨 rc=0을 본다. 그때 옵션 없이 돌린 rc=1은 맡긴 쪽이 색인 절을 쓰면 닫히니, 보고에 두 결과를 함께 적는다. 지난 라운드 색인에서 빠진 ID 때문에 처음부터 rc=1이면, 빠진 ID를 이번 색인 절에 「색인 보완」 한 줄로 이름만 적는다. 지난 영역 문서는 고치지 않는다.
9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. 지난 라운드에서 열린 채 넘어온 Declined는 brief가 맡겼을 때만 다시 판정한다. 맡기지 않았으면 건수와 위치만 적는다.
**독립 리뷰어 둘.** 아래 셋 중 하나면 같은 범위를 서로 결과를 보지 않는 리뷰어 둘이 따로 리뷰하고 맡긴 쪽이 합친다([delegate.md](delegate.md) 4.1절).
@@ -94,7 +94,7 @@
## 5. 완료 기준
- 리뷰: 모든 발견이 양식대로이고 증거 수준이 있다. 색인 검사가 rc=0이다. 결정이 필요한 항목마다 선택지와 권하는 안이 있다.
- 리뷰: 모든 발견이 양식대로이고 증거 수준이 있다. 색인 검사가 rc=0이다(색인 절을 맡긴 쪽이 쓰면 `--extra-index`로 본 rc). 결정이 필요한 항목마다 선택지와 권하는 안이 있다.
- 결함 수정: 수정 전 실패(RED)와 수정 뒤 통과(GREEN) 로그가 있다. 같은 원인의 다른 자리를 확인했다. 해당 게이트가 rc=0이다(desktop 로그 경로). 보고에 「새로 가정하는 것」이 있다.
- 리팩터링: 보존 조건 테스트가 전후 모두 통과하고 `architectureCheck`가 통과한다. 지운 코드를 가리키는 문서·주석이 grep으로 0이다.
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
+1 -1
View File
@@ -32,7 +32,7 @@
| --- | --- | --- | --- | --- |
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 |
| 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 |
| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 총괄이 쓴다 | 기본값 | 2026-11-06 | `docs/work/evidence.md` 9절 |
| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 총괄이 쓰고, 리뷰어는 보고의 색인 표를 `check-review-index.py --extra-index`로 대조해 rc=0을 보인다 | 기본값 | 2026-11-06, 2026-11-07 | `docs/work/evidence.md` 9·11절 |
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`. 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 `~/.claude/CLAUDE.md` 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 | 기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「보고」 |
| 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 |
+24 -1
View File
@@ -12,8 +12,15 @@ This compares the two mechanically. Every finding ID in an area heading must app
`06-10~06-14` counts for every ID inside it. A heading ID that still has a placeholder area
(`NN-10`) is reported too, because it cannot be assigned at all.
When the orchestrating session writes the round's index section after two reviews are merged, the
reviewer who committed the area documents must not edit the README, so the committed tree fails
this check until that section exists. --extra-index takes the index table the reviewer puts in the
report (a file holding that table only) and counts it as part of the index, so the reviewer can show
that the table names every finding before handing it over.
python3 scripts/check-review-index.py docs/reviews/2026-11-01-maturity-review --index-heading "12. 발견 색인"
python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview
python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview --extra-index <index-table.md>
"""
from __future__ import annotations
@@ -92,6 +99,13 @@ def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("review", type=Path, help="review folder, e.g. docs/reviews/2026-11-01-maturity-review")
parser.add_argument("--index-heading", help="compare against this README section only (heading text)")
parser.add_argument(
"--extra-index",
type=Path,
action="append",
default=[],
help="a file holding a round's index table that is not in the README yet; may repeat",
)
args = parser.parse_args()
readme = args.review / "README.md"
@@ -99,8 +113,15 @@ def main() -> int:
print(f"{readme}: missing", file=sys.stderr)
return 1
missing_extra = [str(path) for path in args.extra_index if not path.is_file()]
if missing_extra:
print(f"--extra-index: missing {', '.join(missing_extra)}", file=sys.stderr)
return 1
findings = area_findings(args.review)
indexed = indexed_ids(index_text(readme, args.index_heading))
texts = [index_text(readme, args.index_heading)]
texts += [path.read_text(encoding="utf-8") for path in args.extra_index]
indexed = indexed_ids("\n".join(texts))
placeholder = sorted(finding for finding in findings if "NN-" in finding)
missing = sorted(f for f in findings if f not in indexed and f not in placeholder)
duplicated = sorted(f for f, places in findings.items() if len(places) > 1)
@@ -108,6 +129,8 @@ def main() -> int:
scope = f"section '{args.index_heading}'" if args.index_heading else "whole README"
print(f"review: {args.review}")
print(f"index: README.md, {scope}")
for path in args.extra_index:
print(f"index: + {path} (--extra-index)")
print(f"finding headings in area documents: {len(findings)}")
print(f"found in index: {len(findings) - len(missing) - len(placeholder)}")
print(f"missing from index: {len(missing)}")