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:
@@ -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
|
||||
|
||||
@@ -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` 통과).
|
||||
|
||||
@@ -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절 |
|
||||
|
||||
@@ -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)}")
|
||||
|
||||
Reference in New Issue
Block a user