문서 검사(scripts/check-docs.py, scripts/check-work-docs.py)의 대조 빈틈 셋과, 그 빈틈을 피해 남은 문서 한 줄을 고친다. 커밋 넷이 리뷰 항목 넷과 하나씩 맞는다. 검사가 엄해져 파생 서비스 문서가 새로 실패할 수 있어 검사기 커밋 셋은 !와 BREAKING CHANGE:를 달고, 할 일을 docs/upgrade/2026-11-docs-check-references.md에 적는다.
REV-BE-0009 (fix(scripts)! 첫 커밋): reference가 task 없이 쓴 leaf 경로를 놓친다. registry_projects가 leaf의 모든 앞부분(:adapter, :adapter:inbound)을 project로 세고 부모가 그 집합에 있으면 통과시켜서 :adapter:inbound:web-old가 통과한다. GRADLE_PATH가 두 마디 이상만 봐서 :gone-leaf는 검사 밖이다.
REV-BE-0010 (둘째): PATH_ROOTS에 .claude/가 없어 규칙·스킬 파일 이름을 바꿔도 실패하지 않는다. 없는 경로가 git이 아는 아무 파일의 꼬리와 같으면 통과시켜서, scripts/feature-scaffold/templates/src/ 때문에 지운 leaf 폴더 경로도 통과한다. docstring은 뿌리를 여섯으로 적고 코드는 아홉이다.
REV-BE-0015 (docs(jpa)): docs/jpa/repository-adaptation.md:99가 없는 경로 build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt를 백틱 없이 적어 참조 검사를 피했다.
REV-BE-0017 (넷째): 상대 링크 검사가 둘이고 규칙이 갈라졌다. check-work-docs.py(기본 실행과 --links)는 exists()로 디스크를 봐서 git이 모르는 파일, git mv가 남긴 빈 폴더, 저장소 밖 ../도 통과시킨다.
고른 방법과 버린 대안
0009: Gradle 경로는 registry leaf, 루트 task, <leaf>:<task> 중 하나여야 한다. 루트 task는 루트 build.gradle의 tasks.register·tasks.named 이름, 루트 plugin(ca.architecture, ca.strict-lane-stages)이 만드는 task(PLUGIN_ROOT_TASKS, 시험이 두 plugin 소스와 대조), Gradle 도움 task(GRADLE_ROOT_TASKS: help, tasks 등)다. 한 마디 경로는 SQL 이름 붙은 인자(lease_owner = :workerId)나 문장 속 표기(각 leaf의 :test)와 모양이 같아서, gradlew·gradle·verify.sh 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf 이름(마디가 -로 이어짐)·루트 task 이름(camelCase) 모양일 때만 본다. 버린 안: task 이름까지 대조 — Gradle 없이 알 수 없고, 빌드는 문서를 읽지 않는다는 규칙과 부딪힌다. 맨 앞 한 마디를 늘 보기 — 문장 속 :test·:authority가 거짓 실패한다.
0010: .claude/를 뿌리에 더한다. 꼬리 대조는 src/ 다음 첫 마디가 registry leaf의 src/ 아래 소스 세트 이름(main, test, testFixtures 등)인 leaf 상대 경로에만 쓰고, 꼬리는 registry leaf 폴더 아래 파일을 그 leaf에서 쓴 경로로만 만든다(템플릿의 src/ 나무, leaf 폴더 안 docs/는 세지 않는다). config/ 뿌리는 자원 폴더 상대 경로가 많아 이번에 더하지 않는다(카드의 「바꾸지 말 것」).
0015: 칸을 「계획(docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md 218줄)의 Kotlin 경계 시험」으로. 버린 안: 행을 「이력」 인용 블록으로 — 표 안이라 못 옮긴다.
0017: check-docs.py의 check_link 몸통을 broken_relative_links(known, path, text)로 뽑고(규칙 그대로), check-work-docs.py가 그 모듈을 불러 기본 실행과 --links가 같은 함수를 쓴다. --links에 저장소 밖 파일이나 이 저장소 git이 모르는 파일(무시된 다른 checkout .claude/worktrees/…)을 주면 대조할 git이 없으므로 rc=2로 거절한다. 버린 안: check-work-docs.py에 git 대조를 따로 구현 — 규칙이 다시 둘이 된다.
docs/README.md 「문서 검사」의 reference 행을 같은 규칙으로 고친다(뿌리 목록은 PATH_ROOTS를 가리킨다).
위험과 영향
파생 서비스: 새로 잡는 꼴 다섯(task 없는 leaf·묶음 폴더 task, 한 마디 경로, .claude/ 경로, 꼬리로만 통과하던 경로, --links의 밖·모르는 파일)이 그 서비스 문서에 있으면 PR 단계 documentCheck가 실패한다. 할 일은 업그레이드 안내 1~5번. 이 템플릿 트리와 main을 합친 트리에는 걸리는 것이 없다(아래 검증).
<leaf>:<task>의 task 이름은 여전히 보지 않는다. 소문자 한 낱말 경로(:app)는 명령 밖에서 보지 않는다. 루트 plugin이 새 루트 task를 만들면 PLUGIN_ROOT_TASKS에 더해야 한다(시험이 두 plugin 소스와 대조해 알린다).
check-work-docs.py 기본 실행도 이제 코드 블록·인라인 코드·「이력」 인용 블록 안의 링크를 보지 않는다(check-docs.pylink와 같은 규칙). 옛 --links docs README.md는 base에서 rc=1(인라인 코드 속 [job-timeout.md](job-timeout.md) 표기 1건)이었고 이제 rc=0이다. 시험 fixture가 git 저장소가 됐다(known_paths가 git ls-files를 쓴다).
RED(노트북): HEAD 트리에 검사기 두 파일만 base b884bb11의 것으로 바꾼 트리(c43463ef)에서 같은 시험 rc=1, Ran 129, failures=16·errors=1. 실패: task 없는 leaf 경로 2·묶음 폴더 task·한 마디 경로 3·gradle 명령 속 한 마디·루트 task는 루트 빌드 스크립트가 있어야 함·.claude/ 경로·꼬리 2·--links 5. 오류 1은 plugin task 대조 시험(base에 PLUGIN_ROOT_TASKS가 없다). 리뷰 반영 전 검사기(40b76ef8)로 바꾼 트리(b0f4c1c2)에서는 failures=6(리뷰 발견 1~4마다 하나 이상).
변이(노트북): 검사기를 하나씩 되돌린 10개(묶음 폴더 앞부분을 project로, 꼬리 조건 빼기, .claude/ 빼기, 한 마디 늘 검사, 모양 무시, gradle 명령 빼기, 아무 파일 꼬리, plugin task 하나 빼기, --links가 모르는 파일 받기, exists()로 되돌리기) 모두 시험이 잡는다(rc=1).
병합 확인: git merge-tree --write-tree origin/main HEAD rc=0, 겹치는 파일 없음. 합친 트리(d3c90eb7)에서 시험 129 OK, check-docs.py rc=0, check-work-docs.py rc=0.
새 눈 리뷰 1회(렌즈 be-build-ci·be-docs): High 0·Medium 0·Low 4·Minor 2. 모두 이 PR에서 고쳤고 다시 리뷰하지 않았다.
[Low] 루트 plugin이 만드는 verifyCleanArchitectureDependencies·verifyApplicationCoreDependencyPurity·verifyNoIgnoredSourcePackages와 Gradle 도움 task(:help 등)가 루트 task 목록에 없어 거짓 실패 → PLUGIN_ROOT_TASKS·GRADLE_ROOT_TASKS, plugin 소스 대조 시험.
[Low] 인라인 코드 맨 앞 한 마디를 늘 Gradle 경로로 봐 문장 속 :test·:authority가 거짓 실패, gradle :gone-leaf는 거짓 통과 → 명령(gradle 포함) 안이거나 맨 앞에서 leaf·루트 task 이름 모양일 때만.
[Minor] 꼬리 후보를 git이 아는 모든 파일에서 만들어 템플릿에만 있는 src/main/java/…가 통과 → registry leaf 폴더 아래 파일에서 <leaf>/ 다음부터만.
[Minor] --links가 저장소 안의 무시된 다른 checkout 파일을 받아 맞는 링크를 깨짐으로 보고 → 이 저장소 git이 모르는 파일도 rc=2.
[Low] docs/README.mdreference 행이 옛 뿌리 목록·Gradle 규칙 → 행을 맞추고 뿌리는 PATH_ROOTS를 가리킨다.
[Low] 검사가 엄해져 파생 서비스 문서가 새로 실패하는데 안내가 없다 → docs/upgrade/2026-11-docs-check-references.md, 커밋 셋에 !·BREAKING CHANGE:.
리뷰어가 볼 곳
scripts/check-docs.pycheck_reference의 한 마디 경로 판정(GRADLE_COMMAND·SINGLE_PART_NAME)과 leaf_paths.
scripts/check-work-docs.pylinks_only의 rc=2 거절과 load_check_docs(모듈을 sys.modules에 넣는 이유: dataclass가 만들어질 때 모듈을 찾는다).
## 무엇을, 왜
문서 검사(`scripts/check-docs.py`, `scripts/check-work-docs.py`)의 대조 빈틈 셋과, 그 빈틈을 피해 남은 문서 한 줄을 고친다. 커밋 넷이 리뷰 항목 넷과 하나씩 맞는다. 검사가 엄해져 파생 서비스 문서가 새로 실패할 수 있어 검사기 커밋 셋은 `!`와 `BREAKING CHANGE:`를 달고, 할 일을 `docs/upgrade/2026-11-docs-check-references.md`에 적는다.
- REV-BE-0009 (`fix(scripts)!` 첫 커밋): `reference`가 task 없이 쓴 leaf 경로를 놓친다. `registry_projects`가 leaf의 모든 앞부분(`:adapter`, `:adapter:inbound`)을 project로 세고 부모가 그 집합에 있으면 통과시켜서 `:adapter:inbound:web-old`가 통과한다. `GRADLE_PATH`가 두 마디 이상만 봐서 `:gone-leaf`는 검사 밖이다.
- REV-BE-0010 (둘째): `PATH_ROOTS`에 `.claude/`가 없어 규칙·스킬 파일 이름을 바꿔도 실패하지 않는다. 없는 경로가 git이 아는 아무 파일의 꼬리와 같으면 통과시켜서, `scripts/feature-scaffold/templates/src/` 때문에 지운 leaf 폴더 경로도 통과한다. docstring은 뿌리를 여섯으로 적고 코드는 아홉이다.
- REV-BE-0015 (`docs(jpa)`): `docs/jpa/repository-adaptation.md:99`가 없는 경로 `build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt`를 백틱 없이 적어 참조 검사를 피했다.
- REV-BE-0017 (넷째): 상대 링크 검사가 둘이고 규칙이 갈라졌다. `check-work-docs.py`(기본 실행과 `--links`)는 `exists()`로 디스크를 봐서 git이 모르는 파일, `git mv`가 남긴 빈 폴더, 저장소 밖 `../`도 통과시킨다.
## 고른 방법과 버린 대안
- 0009: Gradle 경로는 registry leaf, 루트 task, `<leaf>:<task>` 중 하나여야 한다. 루트 task는 루트 `build.gradle`의 `tasks.register`·`tasks.named` 이름, 루트 plugin(`ca.architecture`, `ca.strict-lane-stages`)이 만드는 task(`PLUGIN_ROOT_TASKS`, 시험이 두 plugin 소스와 대조), Gradle 도움 task(`GRADLE_ROOT_TASKS`: `help`, `tasks` 등)다. 한 마디 경로는 SQL 이름 붙은 인자(`lease_owner = :workerId`)나 문장 속 표기(각 leaf의 `:test`)와 모양이 같아서, `gradlew`·`gradle`·`verify.sh` 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf 이름(마디가 `-`로 이어짐)·루트 task 이름(camelCase) 모양일 때만 본다. 버린 안: task 이름까지 대조 — Gradle 없이 알 수 없고, 빌드는 문서를 읽지 않는다는 규칙과 부딪힌다. 맨 앞 한 마디를 늘 보기 — 문장 속 `:test`·`:authority`가 거짓 실패한다.
- 0010: `.claude/`를 뿌리에 더한다. 꼬리 대조는 `src/` 다음 첫 마디가 registry leaf의 `src/` 아래 소스 세트 이름(main, test, testFixtures 등)인 leaf 상대 경로에만 쓰고, 꼬리는 registry leaf 폴더 아래 파일을 그 leaf에서 쓴 경로로만 만든다(템플릿의 `src/` 나무, leaf 폴더 안 `docs/`는 세지 않는다). `config/` 뿌리는 자원 폴더 상대 경로가 많아 이번에 더하지 않는다(카드의 「바꾸지 말 것」).
- 0015: 칸을 「계획(`docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md` 218줄)의 Kotlin 경계 시험」으로. 버린 안: 행을 「이력」 인용 블록으로 — 표 안이라 못 옮긴다.
- 0017: `check-docs.py`의 `check_link` 몸통을 `broken_relative_links(known, path, text)`로 뽑고(규칙 그대로), `check-work-docs.py`가 그 모듈을 불러 기본 실행과 `--links`가 같은 함수를 쓴다. `--links`에 저장소 밖 파일이나 이 저장소 git이 모르는 파일(무시된 다른 checkout `.claude/worktrees/…`)을 주면 대조할 git이 없으므로 rc=2로 거절한다. 버린 안: `check-work-docs.py`에 git 대조를 따로 구현 — 규칙이 다시 둘이 된다.
- `docs/README.md` 「문서 검사」의 `reference` 행을 같은 규칙으로 고친다(뿌리 목록은 `PATH_ROOTS`를 가리킨다).
## 위험과 영향
- 파생 서비스: 새로 잡는 꼴 다섯(task 없는 leaf·묶음 폴더 task, 한 마디 경로, `.claude/` 경로, 꼬리로만 통과하던 경로, `--links`의 밖·모르는 파일)이 그 서비스 문서에 있으면 PR 단계 `documentCheck`가 실패한다. 할 일은 업그레이드 안내 1~5번. 이 템플릿 트리와 main을 합친 트리에는 걸리는 것이 없다(아래 검증).
- `<leaf>:<task>`의 task 이름은 여전히 보지 않는다. 소문자 한 낱말 경로(`:app`)는 명령 밖에서 보지 않는다. 루트 plugin이 새 루트 task를 만들면 `PLUGIN_ROOT_TASKS`에 더해야 한다(시험이 두 plugin 소스와 대조해 알린다).
- `check-work-docs.py` 기본 실행도 이제 코드 블록·인라인 코드·「이력」 인용 블록 안의 링크를 보지 않는다(`check-docs.py` `link`와 같은 규칙). 옛 `--links docs README.md`는 base에서 rc=1(인라인 코드 속 `[job-timeout.md](job-timeout.md)` 표기 1건)이었고 이제 rc=0이다. 시험 fixture가 git 저장소가 됐다(`known_paths`가 `git ls-files`를 쓴다).
## 검증
- 커밋마다(노트북): `python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py'` OK — 121·124·124·129개, `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0.
- RED(노트북): HEAD 트리에 검사기 두 파일만 base `b884bb11`의 것으로 바꾼 트리(`c43463ef`)에서 같은 시험 rc=1, Ran 129, failures=16·errors=1. 실패: task 없는 leaf 경로 2·묶음 폴더 task·한 마디 경로 3·`gradle` 명령 속 한 마디·루트 task는 루트 빌드 스크립트가 있어야 함·`.claude/` 경로·꼬리 2·`--links` 5. 오류 1은 plugin task 대조 시험(base에 `PLUGIN_ROOT_TASKS`가 없다). 리뷰 반영 전 검사기(`40b76ef8`)로 바꾼 트리(`b0f4c1c2`)에서는 failures=6(리뷰 발견 1~4마다 하나 이상).
- 변이(노트북): 검사기를 하나씩 되돌린 10개(묶음 폴더 앞부분을 project로, 꼬리 조건 빼기, `.claude/` 빼기, 한 마디 늘 검사, 모양 무시, `gradle` 명령 빼기, 아무 파일 꼬리, plugin task 하나 빼기, `--links`가 모르는 파일 받기, `exists()`로 되돌리기) 모두 시험이 잡는다(rc=1).
- 병합 확인: `git merge-tree --write-tree origin/main HEAD` rc=0, 겹치는 파일 없음. 합친 트리(`d3c90eb7`)에서 시험 129 OK, `check-docs.py` rc=0, `check-work-docs.py` rc=0.
- 깨끗한 detached worktree(HEAD 트리와 같음):
- 노트북 `scripts/verify.sh docs` rc=0
- desktop `scripts/verify.sh leaf :adapter:outbound:persistence-jpa --no-cache --log g3a-leaf2` rc=0, 트리 `d17dde52`(HEAD 트리와 같음), 29 tasks executed, tests=683 failures=0 skipped=0 (0015가 바꾼 `docs/jpa/repository-adaptation.md`는 이 leaf `test`의 입력)
- desktop `scripts/verify.sh pr --no-cache --log g3a-pr2` rc=0, 같은 트리, 662 tasks executed, tests=7350 failures=0 errors=0 skipped=35
## 리뷰 반영
새 눈 리뷰 1회(렌즈 be-build-ci·be-docs): High 0·Medium 0·Low 4·Minor 2. 모두 이 PR에서 고쳤고 다시 리뷰하지 않았다.
1. [Low] 루트 plugin이 만드는 `verifyCleanArchitectureDependencies`·`verifyApplicationCoreDependencyPurity`·`verifyNoIgnoredSourcePackages`와 Gradle 도움 task(`:help` 등)가 루트 task 목록에 없어 거짓 실패 → `PLUGIN_ROOT_TASKS`·`GRADLE_ROOT_TASKS`, plugin 소스 대조 시험.
2. [Low] 인라인 코드 맨 앞 한 마디를 늘 Gradle 경로로 봐 문장 속 `:test`·`:authority`가 거짓 실패, `gradle :gone-leaf`는 거짓 통과 → 명령(`gradle` 포함) 안이거나 맨 앞에서 leaf·루트 task 이름 모양일 때만.
3. [Minor] 꼬리 후보를 git이 아는 모든 파일에서 만들어 템플릿에만 있는 `src/main/java/…`가 통과 → registry leaf 폴더 아래 파일에서 `<leaf>/` 다음부터만.
4. [Minor] `--links`가 저장소 안의 무시된 다른 checkout 파일을 받아 맞는 링크를 깨짐으로 보고 → 이 저장소 git이 모르는 파일도 rc=2.
5. [Low] `docs/README.md` `reference` 행이 옛 뿌리 목록·Gradle 규칙 → 행을 맞추고 뿌리는 `PATH_ROOTS`를 가리킨다.
6. [Low] 검사가 엄해져 파생 서비스 문서가 새로 실패하는데 안내가 없다 → `docs/upgrade/2026-11-docs-check-references.md`, 커밋 셋에 `!`·`BREAKING CHANGE:`.
## 리뷰어가 볼 곳
- `scripts/check-docs.py` `check_reference`의 한 마디 경로 판정(`GRADLE_COMMAND`·`SINGLE_PART_NAME`)과 `leaf_paths`.
- `scripts/check-work-docs.py` `links_only`의 rc=2 거절과 `load_check_docs`(모듈을 `sys.modules`에 넣는 이유: dataclass가 만들어질 때 모듈을 찾는다).
- `docs/upgrade/2026-11-docs-check-references.md` 2절 표.
## 관련
- 리뷰 항목 REV-BE-0009·0010·0015·0017(r1-2026-11-21 BE-5-F01·F02·F07·F09).
문서 검사 reference는 문서의 Gradle 경로를 registry와 대조한다고 하지만
두 꼴을 놓친다. registry_projects가 leaf뿐 아니라 모든 앞부분(:adapter,
:adapter:inbound)을 넣고 부모가 그 집합에 있으면 통과시켜서, 이름을 바꾼
leaf를 task 없이 쓴 `:adapter:inbound:web-old`가 통과한다. GRADLE_PATH가
두 마디 이상만 봐서 `:gone-leaf` 같은 한 마디 경로는 아예 검사 밖이다.
비교 대상을 registry leaf, 루트 task, `<leaf>:<task>` 셋으로 좁힌다.
루트 task는 루트 build.gradle의 tasks.register·tasks.named 이름, 루트에
적용한 plugin(ca.architecture, ca.strict-lane-stages)이 만드는 task,
Gradle 도움 task(help, tasks 등)다. plugin task 목록은 시험이 두 plugin
소스와 대조한다. 한 마디 경로는 SQL의 이름 붙은 인자(`lease_owner =
:workerId`)나 문장 속 표기(각 leaf의 `:test`)와 모양이 같아서,
gradlew·gradle·verify.sh 명령 안에서, 또는 인라인 코드 맨 앞에서 leaf
이름(마디가 `-`로 이어짐)·루트 task 이름(camelCase) 모양일 때만 본다.
버린 안: task 이름까지 대조 — Gradle 없이 알 수 없고, 빌드는 문서를 읽지
않는다는 규칙과 부딪힌다. 맨 앞 한 마디를 늘 Gradle 경로로 보기 — 문장
속 `:test`·`:authority`가 거짓 실패한다.
docs/README.md 「문서 검사」의 reference 행을 같은 규칙으로 고치고,
파생 서비스 문서가 새로 실패하는 꼴을
docs/upgrade/2026-11-docs-check-references.md에 적는다.
한계: `<leaf>:<task>`의 task 이름은 여전히 보지 않는다. 소문자 한 낱말
경로(`:app`)는 명령 밖에서 보지 않는다. 루트 plugin이 새 루트 task를
만들면 PLUGIN_ROOT_TASKS에 더해야 한다(시험이 알린다).
검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py'
OK(121), python3 scripts/check-docs.py rc=0.
Refs: REV-BE-0009
BREAKING CHANGE: 문서 검사 reference가 task 없이 쓴 leaf 경로, 묶음
폴더의 task(`:adapter:inbound:check`), 한 마디 경로(`:gone-leaf`)를
registry leaf·루트 task와 대조한다. 파생 서비스 문서에 그런 낡은 경로가
있으면 PR 단계 documentCheck가 실패한다. 할 일은
docs/upgrade/2026-11-docs-check-references.md 1·2번이다.
문서 검사 reference의 경로 뿌리(PATH_ROOTS)에 .claude/가 없어서, 진입
문서가 가리키는 .claude/rules/*.md·.claude/skills/*의 이름을 바꿔도
실패하지 않는다. 또 없는 경로가 git이 아는 아무 파일·폴더의 꼬리와 같으면
통과시켜서, scripts/feature-scaffold/templates/src/ 아래 템플릿 때문에
지운 leaf 폴더 `src/adapter/inbound/old/` 같은 경로도 통과한다. docstring은
뿌리를 여섯으로 적고 코드는 아홉이다.
PATH_ROOTS에 .claude/를 더한다. 꼬리 대조는 leaf 상대 경로, 곧 `src/`
다음 첫 마디가 registry leaf의 src/ 아래 소스 세트 이름(main, test,
testFixtures 등)인 경로에만 쓰고, 꼬리는 registry leaf 폴더 아래 파일을
그 leaf에서 쓴 경로로만 만든다. 그래서 템플릿의 src/ 나무나 leaf 폴더 안
docs/는 leaf 경로를 살리지 않는다. 나머지는 저장소 루트나 문서 폴더에서
읽혀야 한다. docstring과 docs/README.md 「문서 검사」의 뿌리 목록·꼬리
규칙을 코드에 맞추고(README는 PATH_ROOTS를 가리킨다), 업그레이드 안내에
새로 실패하는 꼴 둘을 더한다.
한계: config/ 뿌리는 자원 폴더 상대 경로(config/module-defaults/*.yml)가
많아 이번에 더하지 않는다(카드 범위의 「바꾸지 말 것」).
검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py'
OK(124), python3 scripts/check-docs.py rc=0.
Refs: REV-BE-0010
BREAKING CHANGE: 문서 검사 reference가 인라인 코드의 .claude/ 경로를
지금 트리와 대조하고, leaf 상대 경로는 registry leaf 폴더 아래에 있을
때만 통과시킨다. 파생 서비스 문서에 옮긴 .claude/ 파일이나 템플릿·다른
파일의 꼬리로만 통과하던 경로가 있으면 PR 단계 documentCheck가
실패한다. 할 일은 docs/upgrade/2026-11-docs-check-references.md
3·4번이다.
docs/jpa/repository-adaptation.md의 계획 대조 표 한 칸이 지금 없는
build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt를 백틱 없이 적는다.
레이아웃을 옮긴 커밋이 PATH_ROOTS에 build-logic/을 더하면서 이 칸의
백틱을 빼 참조 검사를 피했다.
칸을 계획 문서와 그 줄(218줄)을 가리키는 말로 바꾼다. 계획 문서는 있는
경로라 참조 검사가 계속 본다. 버린 안: 행 전체를 「이력」 인용 블록으로
옮기기 — 표 안이라 블록으로 옮길 수 없다.
검증: git grep -n 'build-logic/src/test/kotlin' -- docs/jpa/repository-adaptation.md
rc=1(없음), python3 scripts/check-docs.py rc=0.
Refs: REV-BE-0015
상대 링크 검사가 둘이고 규칙이 갈라졌다. check-docs.py의 link는 git이
아는 경로만 받고 저장소 밖(..)은 실패로 본다. check-work-docs.py는
디스크를 exists()로 봐서 git이 모르는 파일, git mv가 남긴 빈 폴더, 저장소
밖 형제 clone(../design-docs/…)도 통과시킨다. 기본 실행은 같은 PR 단계에서
check-docs.py link가 다시 보지만, lychee 없는 기계에서 손으로 쓰는
--links는 약한 쪽의 답만 준다.
check-docs.py의 check_link 몸통을 broken_relative_links(known, path, text)로
뽑고(규칙은 그대로) check-work-docs.py가 그 모듈을 불러 기본 실행과 --links
모두 같은 함수를 쓴다. 그래서 링크 규칙을 한 곳에서 고친다. --links에
저장소 밖 파일이나 이 저장소 git이 모르는 파일(무시된 다른 checkout
.claude/worktrees/…, 빌드 출력)을 주면 그 git으로는 대조할 수 없으므로
rc=2로 거절한다. 버린 안: check-work-docs.py에 git 대조를 따로 구현 —
규칙이 다시 둘이 된다.
위험: check-work-docs.py 기본 실행도 이제 코드 블록·인라인 코드·「이력」
인용 블록 안의 링크를 보지 않는다(check-docs.py link와 같다). 지금 트리에서
깨진 링크 0은 그대로다. 옛 --links가 깨짐으로 본 인라인 코드 속 링크 표기
(docs/upgrade/2026-11-round9-followups.md:31)는 이제 링크로 보지 않는다.
시험 fixture가 git 저장소가 됐다(known_paths가 git ls-files를 쓴다).
검증: python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py'
OK(129), python3 scripts/check-work-docs.py rc=0,
python3 scripts/check-work-docs.py --links docs README.md rc=0(536 링크,
깨짐 0), python3 scripts/check-docs.py rc=0.
Refs: REV-BE-0017
BREAKING CHANGE: check-work-docs.py --links가 저장소 루트를 넘는 링크와
git이 모르는 곳을 가리키는 링크를 깨짐(rc=1)으로 보고, 저장소 밖이나
git이 모르는 파일을 받으면 rc=2로 거절한다. 그 명령을 스크립트로 쓰는
파생 서비스는 docs/upgrade/2026-11-docs-check-references.md 5번을 본다.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
문서 검사(
scripts/check-docs.py,scripts/check-work-docs.py)의 대조 빈틈 셋과, 그 빈틈을 피해 남은 문서 한 줄을 고친다. 커밋 넷이 리뷰 항목 넷과 하나씩 맞는다. 검사가 엄해져 파생 서비스 문서가 새로 실패할 수 있어 검사기 커밋 셋은!와BREAKING CHANGE:를 달고, 할 일을docs/upgrade/2026-11-docs-check-references.md에 적는다.fix(scripts)!첫 커밋):reference가 task 없이 쓴 leaf 경로를 놓친다.registry_projects가 leaf의 모든 앞부분(:adapter,:adapter:inbound)을 project로 세고 부모가 그 집합에 있으면 통과시켜서:adapter:inbound:web-old가 통과한다.GRADLE_PATH가 두 마디 이상만 봐서:gone-leaf는 검사 밖이다.PATH_ROOTS에.claude/가 없어 규칙·스킬 파일 이름을 바꿔도 실패하지 않는다. 없는 경로가 git이 아는 아무 파일의 꼬리와 같으면 통과시켜서,scripts/feature-scaffold/templates/src/때문에 지운 leaf 폴더 경로도 통과한다. docstring은 뿌리를 여섯으로 적고 코드는 아홉이다.docs(jpa)):docs/jpa/repository-adaptation.md:99가 없는 경로build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt를 백틱 없이 적어 참조 검사를 피했다.check-work-docs.py(기본 실행과--links)는exists()로 디스크를 봐서 git이 모르는 파일,git mv가 남긴 빈 폴더, 저장소 밖../도 통과시킨다.고른 방법과 버린 대안
<leaf>:<task>중 하나여야 한다. 루트 task는 루트build.gradle의tasks.register·tasks.named이름, 루트 plugin(ca.architecture,ca.strict-lane-stages)이 만드는 task(PLUGIN_ROOT_TASKS, 시험이 두 plugin 소스와 대조), Gradle 도움 task(GRADLE_ROOT_TASKS:help,tasks등)다. 한 마디 경로는 SQL 이름 붙은 인자(lease_owner = :workerId)나 문장 속 표기(각 leaf의:test)와 모양이 같아서,gradlew·gradle·verify.sh명령 안에서, 또는 인라인 코드 맨 앞에서 leaf 이름(마디가-로 이어짐)·루트 task 이름(camelCase) 모양일 때만 본다. 버린 안: task 이름까지 대조 — Gradle 없이 알 수 없고, 빌드는 문서를 읽지 않는다는 규칙과 부딪힌다. 맨 앞 한 마디를 늘 보기 — 문장 속:test·:authority가 거짓 실패한다..claude/를 뿌리에 더한다. 꼬리 대조는src/다음 첫 마디가 registry leaf의src/아래 소스 세트 이름(main, test, testFixtures 등)인 leaf 상대 경로에만 쓰고, 꼬리는 registry leaf 폴더 아래 파일을 그 leaf에서 쓴 경로로만 만든다(템플릿의src/나무, leaf 폴더 안docs/는 세지 않는다).config/뿌리는 자원 폴더 상대 경로가 많아 이번에 더하지 않는다(카드의 「바꾸지 말 것」).docs/history/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md218줄)의 Kotlin 경계 시험」으로. 버린 안: 행을 「이력」 인용 블록으로 — 표 안이라 못 옮긴다.check-docs.py의check_link몸통을broken_relative_links(known, path, text)로 뽑고(규칙 그대로),check-work-docs.py가 그 모듈을 불러 기본 실행과--links가 같은 함수를 쓴다.--links에 저장소 밖 파일이나 이 저장소 git이 모르는 파일(무시된 다른 checkout.claude/worktrees/…)을 주면 대조할 git이 없으므로 rc=2로 거절한다. 버린 안:check-work-docs.py에 git 대조를 따로 구현 — 규칙이 다시 둘이 된다.docs/README.md「문서 검사」의reference행을 같은 규칙으로 고친다(뿌리 목록은PATH_ROOTS를 가리킨다).위험과 영향
.claude/경로, 꼬리로만 통과하던 경로,--links의 밖·모르는 파일)이 그 서비스 문서에 있으면 PR 단계documentCheck가 실패한다. 할 일은 업그레이드 안내 1~5번. 이 템플릿 트리와 main을 합친 트리에는 걸리는 것이 없다(아래 검증).<leaf>:<task>의 task 이름은 여전히 보지 않는다. 소문자 한 낱말 경로(:app)는 명령 밖에서 보지 않는다. 루트 plugin이 새 루트 task를 만들면PLUGIN_ROOT_TASKS에 더해야 한다(시험이 두 plugin 소스와 대조해 알린다).check-work-docs.py기본 실행도 이제 코드 블록·인라인 코드·「이력」 인용 블록 안의 링크를 보지 않는다(check-docs.pylink와 같은 규칙). 옛--links docs README.md는 base에서 rc=1(인라인 코드 속[job-timeout.md](job-timeout.md)표기 1건)이었고 이제 rc=0이다. 시험 fixture가 git 저장소가 됐다(known_paths가git ls-files를 쓴다).검증
python3 -m unittest discover -s scripts/tests -p 'test_check_*docs.py'OK — 121·124·124·129개,python3 scripts/check-docs.pyrc=0,python3 scripts/check-work-docs.pyrc=0.b884bb11의 것으로 바꾼 트리(c43463ef)에서 같은 시험 rc=1, Ran 129, failures=16·errors=1. 실패: task 없는 leaf 경로 2·묶음 폴더 task·한 마디 경로 3·gradle명령 속 한 마디·루트 task는 루트 빌드 스크립트가 있어야 함·.claude/경로·꼬리 2·--links5. 오류 1은 plugin task 대조 시험(base에PLUGIN_ROOT_TASKS가 없다). 리뷰 반영 전 검사기(40b76ef8)로 바꾼 트리(b0f4c1c2)에서는 failures=6(리뷰 발견 1~4마다 하나 이상)..claude/빼기, 한 마디 늘 검사, 모양 무시,gradle명령 빼기, 아무 파일 꼬리, plugin task 하나 빼기,--links가 모르는 파일 받기,exists()로 되돌리기) 모두 시험이 잡는다(rc=1).git merge-tree --write-tree origin/main HEADrc=0, 겹치는 파일 없음. 합친 트리(d3c90eb7)에서 시험 129 OK,check-docs.pyrc=0,check-work-docs.pyrc=0.scripts/verify.sh docsrc=0scripts/verify.sh leaf :adapter:outbound:persistence-jpa --no-cache --log g3a-leaf2rc=0, 트리d17dde52(HEAD 트리와 같음), 29 tasks executed, tests=683 failures=0 skipped=0 (0015가 바꾼docs/jpa/repository-adaptation.md는 이 leaftest의 입력)scripts/verify.sh pr --no-cache --log g3a-pr2rc=0, 같은 트리, 662 tasks executed, tests=7350 failures=0 errors=0 skipped=35리뷰 반영
새 눈 리뷰 1회(렌즈 be-build-ci·be-docs): High 0·Medium 0·Low 4·Minor 2. 모두 이 PR에서 고쳤고 다시 리뷰하지 않았다.
verifyCleanArchitectureDependencies·verifyApplicationCoreDependencyPurity·verifyNoIgnoredSourcePackages와 Gradle 도움 task(:help등)가 루트 task 목록에 없어 거짓 실패 →PLUGIN_ROOT_TASKS·GRADLE_ROOT_TASKS, plugin 소스 대조 시험.:test·:authority가 거짓 실패,gradle :gone-leaf는 거짓 통과 → 명령(gradle포함) 안이거나 맨 앞에서 leaf·루트 task 이름 모양일 때만.src/main/java/…가 통과 → registry leaf 폴더 아래 파일에서<leaf>/다음부터만.--links가 저장소 안의 무시된 다른 checkout 파일을 받아 맞는 링크를 깨짐으로 보고 → 이 저장소 git이 모르는 파일도 rc=2.docs/README.mdreference행이 옛 뿌리 목록·Gradle 규칙 → 행을 맞추고 뿌리는PATH_ROOTS를 가리킨다.docs/upgrade/2026-11-docs-check-references.md, 커밋 셋에!·BREAKING CHANGE:.리뷰어가 볼 곳
scripts/check-docs.pycheck_reference의 한 마디 경로 판정(GRADLE_COMMAND·SINGLE_PART_NAME)과leaf_paths.scripts/check-work-docs.pylinks_only의 rc=2 거절과load_check_docs(모듈을sys.modules에 넣는 이유: dataclass가 만들어질 때 모듈을 찾는다).docs/upgrade/2026-11-docs-check-references.md2절 표.관련