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
+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)}")