상대 링크 검사가 둘이고 규칙이 갈라졌다. 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번을 본다.
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
문서 검사 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번이다.
문서 검사 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번이다.