main 99cc4f59(#38 병합) push run의 :app-bootstrap:documentContractTest가 MetricsRegistryCodeAlignmentTest.everyRowNamesTheMainFileThatRegistersIt에서 실패한다(79개 중 1개).
원인: #38의 2d274a684가 NotificationSchedulerWorker를 adapter:outbound:notification(platform/dispatch)에서 composition:notification-platform(composition/notification)으로 옮겼다. docs/registries/metrics.yaml의 notification.queue.depth 행 registered_by는 옛 경로로 남았다. #37은 이 파일을 건드리지 않았다.
#38 PR run이 초록이었던 이유: 이 대조 시험은 document-contract 태그라 main 단계(mainCheck)에서만 돈다. PR에서 도는 scripts/check-docs.py의 경로 검사는 마크다운만 읽었다.
이 PR은 두 커밋이다.
fix(registries): 행의 registered_by를 새 경로로 고친다. 코드가 맞다(의도한 이동이고, gauge는 새 파일 96줄에서 NotificationMetricName.QUEUE_DEPTH로 등록된다).
ci(docs)!: check-docs.py의 reference 검사가 docs/registries/*.yaml의 값과 주석에 적은 repo 경로도 본다. 같은 어긋남이 다음에는 옮기는 PR에서 걸린다. docs/work/reference/gates.md 2절에 「지표·헤더를 등록하는 코드를 옮기거나 바꿈 → :app-bootstrap:documentContractTest」 행을 따로 둔다.
같은 모양 찾기: #37·#38이 지우거나 옮긴 파일 27개의 옛 경로와 클래스 이름을 살아 있는 문서·registry에서 찾았다. 남은 것은 이 행 하나다. 새 검사를 지금 트리에 돌려도 걸리는 것이 없다.
고른 방법과 버린 대안
고친 쪽: registry. 코드 이동은 #38의 구조 변경이고 되돌릴 이유가 없다.
막는 장치: 이미 PR에서 도는 검사가 볼 파일만 넓혔다.
버림 (1) 대조 시험을 PR 단계로 옮기기: 문서 대조는 main 단계라는 결정(2026-09-16)을 바꾸고 Gradle lane 하나를 PR에 더한다.
버림 (2) gates.md에 돌릴 lane만 적기: 사람이 표를 놓치면 다시 샌다.
gates.md 7절 답(검사 장치를 넓힘):
단계: PR. 새 job·태스크 없이 :prCheck 안의 기존 documentCheck(check-docs.py)가 본다.
다른 단계와 겹침: 없음. 같은 경로를 보는 다른 태스크가 없다(main의 대조 시험은 행과 등록 코드를 대조하고, 이 검사는 경로가 있는지만 본다).
run: 줄: 바꾸지 않았다.
경로 필터: 없음.
PR에 두는 이유: Gradle 없이 1초 안에 끝나는(reference 검사 전체 0.4초) 기존 검사를 넓힌 것이다. 옮기는 PR에서 잡지 못하면 main이 빨강이 되어 모든 병합이 멈춘다. 이번이 그 경우다.
job 수: 그대로. 시간: 1초 미만 증가.
Gitea에서 못 쓰는 action·권한: 쓰지 않는다.
스크립트·시험 위치: 기존 scripts/check-docs.py, 시험은 scripts/tests/test_check_docs.py.
위험과 영향
파생 서비스: registry 주석에 적은 경로가 지금 트리에 없으면 PR 단계 documentCheck가 새로 실패한다. 주석은 지금까지 어떤 검사도 보지 않았다. source·registered_by는 main 단계 대조 시험에서 이미 실패하던 경로다. 안내는 docs/upgrade/2026-11-round9-observability.md 14번 행이고 커밋에 BREAKING CHANGE:가 있다.
한계: 경로가 있는지만 본다. 파일은 남고 등록 줄만 다른 파일로 옮긴 경우는 여전히 main 단계 document-contract lane이 잡는다(gates.md 새 행).
운영 코드와 HTTP 응답은 바뀌지 않는다.
검증
명령
실행 위치
결과
수정 전: main run의 :app-bootstrap:documentContractTest
## 무엇을, 왜
main 99cc4f59(#38 병합) push run의 `:app-bootstrap:documentContractTest`가 `MetricsRegistryCodeAlignmentTest.everyRowNamesTheMainFileThatRegistersIt`에서 실패한다(79개 중 1개).
- 원인: #38의 2d274a684가 `NotificationSchedulerWorker`를 `adapter:outbound:notification`(`platform/dispatch`)에서 `composition:notification-platform`(`composition/notification`)으로 옮겼다. `docs/registries/metrics.yaml`의 `notification.queue.depth` 행 `registered_by`는 옛 경로로 남았다. #37은 이 파일을 건드리지 않았다.
- #38 PR run이 초록이었던 이유: 이 대조 시험은 document-contract 태그라 main 단계(`mainCheck`)에서만 돈다. PR에서 도는 `scripts/check-docs.py`의 경로 검사는 마크다운만 읽었다.
이 PR은 두 커밋이다.
1. `fix(registries)`: 행의 `registered_by`를 새 경로로 고친다. 코드가 맞다(의도한 이동이고, gauge는 새 파일 96줄에서 `NotificationMetricName.QUEUE_DEPTH`로 등록된다).
2. `ci(docs)!`: `check-docs.py`의 `reference` 검사가 `docs/registries/*.yaml`의 값과 주석에 적은 repo 경로도 본다. 같은 어긋남이 다음에는 옮기는 PR에서 걸린다. `docs/work/reference/gates.md` 2절에 「지표·헤더를 등록하는 코드를 옮기거나 바꿈 → `:app-bootstrap:documentContractTest`」 행을 따로 둔다.
같은 모양 찾기: #37·#38이 지우거나 옮긴 파일 27개의 옛 경로와 클래스 이름을 살아 있는 문서·registry에서 찾았다. 남은 것은 이 행 하나다. 새 검사를 지금 트리에 돌려도 걸리는 것이 없다.
## 고른 방법과 버린 대안
- 고친 쪽: registry. 코드 이동은 #38의 구조 변경이고 되돌릴 이유가 없다.
- 막는 장치: 이미 PR에서 도는 검사가 볼 파일만 넓혔다.
- 버림 (1) 대조 시험을 PR 단계로 옮기기: 문서 대조는 main 단계라는 결정(2026-09-16)을 바꾸고 Gradle lane 하나를 PR에 더한다.
- 버림 (2) gates.md에 돌릴 lane만 적기: 사람이 표를 놓치면 다시 샌다.
gates.md 7절 답(검사 장치를 넓힘):
1. 단계: PR. 새 job·태스크 없이 `:prCheck` 안의 기존 `documentCheck`(`check-docs.py`)가 본다.
2. 다른 단계와 겹침: 없음. 같은 경로를 보는 다른 태스크가 없다(main의 대조 시험은 행과 등록 코드를 대조하고, 이 검사는 경로가 있는지만 본다).
3. `run:` 줄: 바꾸지 않았다.
4. 경로 필터: 없음.
5. PR에 두는 이유: Gradle 없이 1초 안에 끝나는(reference 검사 전체 0.4초) 기존 검사를 넓힌 것이다. 옮기는 PR에서 잡지 못하면 main이 빨강이 되어 모든 병합이 멈춘다. 이번이 그 경우다.
6. job 수: 그대로. 시간: 1초 미만 증가.
7. Gitea에서 못 쓰는 action·권한: 쓰지 않는다.
8. 스크립트·시험 위치: 기존 `scripts/check-docs.py`, 시험은 `scripts/tests/test_check_docs.py`.
## 위험과 영향
- 파생 서비스: registry 주석에 적은 경로가 지금 트리에 없으면 PR 단계 `documentCheck`가 새로 실패한다. 주석은 지금까지 어떤 검사도 보지 않았다. `source`·`registered_by`는 main 단계 대조 시험에서 이미 실패하던 경로다. 안내는 `docs/upgrade/2026-11-round9-observability.md` 14번 행이고 커밋에 `BREAKING CHANGE:`가 있다.
- 한계: 경로가 있는지만 본다. 파일은 남고 등록 줄만 다른 파일로 옮긴 경우는 여전히 main 단계 document-contract lane이 잡는다(gates.md 새 행).
- 운영 코드와 HTTP 응답은 바뀌지 않는다.
## 검증
| 명령 | 실행 위치 | 결과 |
| --- | --- | --- |
| 수정 전: main run의 `:app-bootstrap:documentContractTest` | runner(main 99cc4f59) | 79개 중 1개 실패(RED) |
| `./gradlew :app-bootstrap:documentContractTest --rerun --no-build-cache` | desktop, 트리 fcc67388(= 첫 커밋의 트리), 시작 부하 9.84 | rc=0, 79개 통과, 55초, `~/be-main-red2-logs/c-doccontract.log` |
| `bash scripts/verify.sh docs` | 노트북, 이 PR head | rc=0, 스크립트 시험 170개 통과 |
| 옛 `metrics.yaml`로 `python3 scripts/check-docs.py --only reference` | 노트북 | rc=1, `metrics.yaml:878: 없는 경로다` |
| 새 시험 셋을 옛 `check-docs.py`로 | 노트북 | 셋 모두 실패(RED) |
| 정규식 변이 셋(따옴표 안 값만, 한글에서 안 끊기, 주석 건너뛰기) | 노트북 | 각각 시험 하나 이상 실패 |
- 새 눈 리뷰 1회(렌즈 be-observability·be-build-ci·be-docs): Minor 5건 → 모두 고침. 확인 리뷰 1회: 5건 닫힘, 새 문구 2건(Minor) → 고침.
- `:prCheck`은 desktop에서 따로 돌리지 않았다. 이 PR의 runner `pr / done`이 돌린다.
## 리뷰어가 볼 곳
- `scripts/check-docs.py` 142줄 정규식과 `check_reference`의 registry 반복문.
- `docs/work/reference/gates.md` 2절 두 행.
## 관련
- 실패 로그: main 99cc4f59 push run(`documentContractTest` 1397~1409줄).
- 일으킨 커밋: 2d274a684(#38).
문제: main 99cc4f59(#38 병합) push run의 :app-bootstrap:documentContractTest가
MetricsRegistryCodeAlignmentTest.everyRowNamesTheMainFileThatRegistersIt에서
실패한다. #38의 2d274a684가 NotificationSchedulerWorker를
adapter:outbound:notification(platform/dispatch)에서
composition:notification-platform(composition/notification)으로 옮겼는데,
metrics.yaml의 notification.queue.depth 행 registered_by는 옛 경로를
가리킨다. 이 대조 시험은 main 단계(mainCheck)에서만 돌아 #38의 PR run은
초록이었다. #37은 이 파일을 건드리지 않았다.
방법: 코드가 맞다. 옮긴 것은 #38의 의도한 구조 변경이고 gauge는 새 파일
96줄에서 NotificationMetricName.QUEUE_DEPTH로 등록된다. 그래서 registry의
registered_by만 새 경로로 바꾼다.
같은 모양: #37·#38이 지우거나 옮긴 파일 27개의 옛 경로와 클래스 이름을
살아 있는 문서·registry에서 찾았다. 남은 것은 이 행 하나다.
검증: desktop, 트리 fcc67388, `./gradlew :app-bootstrap:documentContractTest
--rerun --no-build-cache` rc=0, 79개 통과(실패 0). 로그
~/be-main-red2-logs/c-doccontract.log. 수정 전 실패는 main run의 같은 태스크
(79개 중 1개 실패).
Fixes: 2d274a684e3a ("refactor(application)!: 시스템 쓰기와 운영자 연산을 유스케이스 계약 안으로 옮긴다")
문제: 코드 파일을 옮기는 PR은 docs/registries/*.yaml 행의 source·
registered_by가 옛 경로로 남아도 초록이다. scripts/check-docs.py의 reference
검사는 마크다운만 읽고, 행과 코드를 대조하는 MetricsRegistryCodeAlignmentTest·
HeaderRegistryRuntimeAlignmentTest는 main 단계에서만 돈다. #38이 이렇게
병합돼 main이 빨강이 됐고, main이 빨강인 동안 다른 PR 병합이 모두 멈췄다.
방법: reference 검사가 docs/registries/*.yaml의 줄에서 repo 경로 모양의 낱말
(PATH_ROOTS로 시작, 공백·따옴표·한글에서 끊는다)을 찾아 git이 아는 파일인지
본다. headers.yaml의 "service: src/..." 같은 접두어 붙은 값과 주석의 경로도
같은 규칙으로 잡는다. gates.md 2절에 「지표·헤더를 등록하는 코드를 옮기거나
바꿈 → :app-bootstrap:documentContractTest」 행을 따로 두고, 「지우거나 옮김」
행에 registry YAML을 적는다. docs/README.md 「문서 검사」 표와 관측 업그레이드
안내(14번 행)를 고친다.
버린 대안: (1) 대조 시험을 PR 단계로 옮기기 — 문서 대조는 main 단계라는
결정(2026-09-16)을 바꾸고 Gradle lane 하나를 PR에 더한다. (2) gates.md에
사람이 돌릴 lane만 적기 — #38도 그 표를 따랐어야 했지만 기계가 막지 않으면
다시 샌다.
PR 단계에 두는 이유(gates.md 7절 5번): 이미 PR에서 도는 check-docs.py의
기존 검사가 볼 파일만 넓힌다. 새 태스크·job이 없고 Gradle 없이 1초 안에
끝난다. 옮기는 PR에서 잡지 못하면 main이 빨강이 되어 모든 병합이 멈춘다.
위험·한계: 경로가 있는지만 본다. 파일은 남고 등록 줄만 다른 파일로 옮긴
경우는 여전히 main 단계 document-contract lane이 잡는다(gates.md 새 행).
파생 서비스는 registry 주석에 적은 경로가 없으면 PR에서 새로 실패한다. 주석은
지금까지 어떤 검사도 보지 않았다. source·registered_by는 main 단계 대조
시험에서 이미 실패하던 경로다.
검증: 노트북 `bash scripts/verify.sh docs` rc=0(스크립트 시험 170개 통과).
옛 metrics.yaml에서 `check-docs.py --only reference`가 rc=1로
metrics.yaml:878을 가리킨다. 새 시험 셋은 옛 check-docs.py에서 실패하고, 정규식
변이 셋(따옴표 안 값만 보기, 한글에서 안 끊기, 주석 건너뛰기)이 각각 시험
하나 이상을 실패시킨다.
BREAKING CHANGE: docs/registries/*.yaml의 값과 주석에 적은 repo 경로가 지금
트리에 없으면 PR 단계 documentCheck가 실패한다. 파생 서비스는
`python3 scripts/check-docs.py --only reference`로 자기 행·주석을 확인한다
(docs/upgrade/2026-11-round9-observability.md 14번).
donghyeon.kang
changed title from fix(registries): 옮긴 worker 파일을 가리키게 하고 문서 검사가 registry 경로를 본다 to fix(registries)!: 옮긴 worker 파일을 가리키게 하고 문서 검사가 registry 경로를 본다2026-11-18 12:18:40 +00:00
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.
무엇을, 왜
main 99cc4f59(#38 병합) push run의
:app-bootstrap:documentContractTest가MetricsRegistryCodeAlignmentTest.everyRowNamesTheMainFileThatRegistersIt에서 실패한다(79개 중 1개).NotificationSchedulerWorker를adapter:outbound:notification(platform/dispatch)에서composition:notification-platform(composition/notification)으로 옮겼다.docs/registries/metrics.yaml의notification.queue.depth행registered_by는 옛 경로로 남았다. #37은 이 파일을 건드리지 않았다.mainCheck)에서만 돈다. PR에서 도는scripts/check-docs.py의 경로 검사는 마크다운만 읽었다.이 PR은 두 커밋이다.
fix(registries): 행의registered_by를 새 경로로 고친다. 코드가 맞다(의도한 이동이고, gauge는 새 파일 96줄에서NotificationMetricName.QUEUE_DEPTH로 등록된다).ci(docs)!:check-docs.py의reference검사가docs/registries/*.yaml의 값과 주석에 적은 repo 경로도 본다. 같은 어긋남이 다음에는 옮기는 PR에서 걸린다.docs/work/reference/gates.md2절에 「지표·헤더를 등록하는 코드를 옮기거나 바꿈 →:app-bootstrap:documentContractTest」 행을 따로 둔다.같은 모양 찾기: #37·#38이 지우거나 옮긴 파일 27개의 옛 경로와 클래스 이름을 살아 있는 문서·registry에서 찾았다. 남은 것은 이 행 하나다. 새 검사를 지금 트리에 돌려도 걸리는 것이 없다.
고른 방법과 버린 대안
gates.md 7절 답(검사 장치를 넓힘):
:prCheck안의 기존documentCheck(check-docs.py)가 본다.run:줄: 바꾸지 않았다.scripts/check-docs.py, 시험은scripts/tests/test_check_docs.py.위험과 영향
documentCheck가 새로 실패한다. 주석은 지금까지 어떤 검사도 보지 않았다.source·registered_by는 main 단계 대조 시험에서 이미 실패하던 경로다. 안내는docs/upgrade/2026-11-round9-observability.md14번 행이고 커밋에BREAKING CHANGE:가 있다.검증
:app-bootstrap:documentContractTest99cc4f59)./gradlew :app-bootstrap:documentContractTest --rerun --no-build-cache~/be-main-red2-logs/c-doccontract.logbash scripts/verify.sh docsmetrics.yaml로python3 scripts/check-docs.py --only referencemetrics.yaml:878: 없는 경로다check-docs.py로:prCheck은 desktop에서 따로 돌리지 않았다. 이 PR의 runnerpr / done이 돌린다.리뷰어가 볼 곳
scripts/check-docs.py142줄 정규식과check_reference의 registry 반복문.docs/work/reference/gates.md2절 두 행.관련
99cc4f59push run(documentContractTest1397~1409줄).fix(registries): 옮긴 worker 파일을 가리키게 하고 문서 검사가 registry 경로를 본다to fix(registries)!: 옮긴 worker 파일을 가리키게 하고 문서 검사가 registry 경로를 본다