Commit Graph
340 Commits
Author SHA1 Message Date
DongHyeonka 1b0c14de9f Merge remote-tracking branch 'origin/main' into claude/v1-vuln-fix-e089b9
main(b3f63be6, 문서 2단계 통합 PR #3)을 V1 브랜치에 합친다. 충돌은 없었다.

- docs/web/repository-adaptation.md: V1이 숫자를 고쳤다가 되돌려(23f04afb) 기준과
  같았으므로 main의 번역(숫자 없이 카탈로그를 가리킴)이 그대로 들어왔다.
- src/adapter/outbound/persistence-jpa/README.md: V1의 Querydsl 문장(71~75줄)과
  main의 번역이 자동으로 함께 남았다.
- docs/work/reference/decisions.md, docs/upgrade/2026-11-maturity-review.md: V1이
  더한 행과 main의 행이 모두 남았다.
- main 쪽에서 들어온 workflow 변경은 없다.

검증(노트북, 합친 트리): check-docs.py rc=0(넓어진 숫자 검사 포함 걸림 0),
자기 시험 OK, check-work-docs.py rc=0, check-repo-layout.py rc=0. 게이트는
desktop에서 이 커밋으로 돌린다.
2026-11-07 20:47:18 +09:00
donghyeon.kang b3f63be655 Merge pull request 'docs!: 번역 네 묶음을 합치고 문서 검사 장치를 마무리한다' (#3) from claude/i2-docs-merge-02df15 into main 2026-11-07 11:45:21 +00:00
DongHyeonka 23f04afbed docs(web): baseline 숫자를 고친 것을 되돌린다
문제: cb67b879가 `docs/web/repository-adaptation.md:65`의 baseline 숫자를
4.0.8에서 4.0.9로 고쳤다. 이 파일은 문서 번역 작업(D2d)이 지금 옮기고 있고,
총괄은 숫자를 하나도 고치지 않기로 정했다(2026-11-07). 번역 작업이 숫자를
복사하는 대신 정본(`src/gradle/libs.versions.toml`)을 가리키게 바꾸므로 4.0.9도
그때 맞춰진다.

고친 방법: 그 한 줄을 4.0.8로 되돌린다. 이 파일은 기준 커밋 5ab1b418과 같아진다.
- cb67b879는 이미 push해서 고쳐 쓰지 않고 되돌림 커밋을 붙인다.

위험·한계: 번역이 끝날 때까지 이 줄과 check-docs 예외로 얼린 8곳이 실제 Boot
4.0.9와 다른 숫자를 말한다.

검증: 앞 커밋과 같다(트리 fbb325c1에서 문서 검사 전부 rc=0).
`git diff 5ab1b418 -- docs/web/repository-adaptation.md`가 비어 있다.
2026-11-07 19:24:43 +09:00
DongHyeonka 6ad8f4b635 docs(persistence-jpa): README가 고친 버전 없는 Querydsl 좌표를 권하지 않게 한다
문제: persistence-jpa README 「라이브러리 API」가 Querydsl을 쓰는 서비스에
`com.querydsl:querydsl-jpa:5.1.0:jakarta`를 직접 추가하라고 한다. 그 좌표에는
HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있고 고친 버전이 없다.
8e3bef0f가 이 leaf를 querydsl-core로 옮겼는데, 살아 있는 문서는 아직 그
좌표를 권한다.

고친 방법: 총괄이 권한 안 A를 확인하고 이 문장도 고치라고 했다(2026-11-07).
문장을 넷으로 나눴다: 템플릿은 querydsl-core의 `Predicate`만 쓴다, JPA 질의가
필요한 서비스는 querydsl-jpa를 직접 더한다, 그 좌표 5.1.0에는 CVE-2024-49203이
있고 고친 버전이 없다, 쓰려면 OpenFeign 포크(`io.github.openfeign.querydsl`)를
검토한다. Envers 안내는 그대로다. 결정 색인 「Querydsl 취약 좌표」 행의 「누가」를
「총괄 확인 전」에서 위임(총괄 확인)으로 바꾸고 README를 출처에 더했다.
- 원래는 8e3bef0f와 같은 커밋이어야 했다. 그 커밋은 이미 push해서 고쳐 쓰지
  않고 바로 뒤에 붙인다.

위험·한계: README 줄은 문서 번역 작업(D2b) 범위 안이다. 총괄이 D2b에 이 줄을
건드리지 말라고 알린다.

검증(desktop, 이 커밋과 다음 커밋을 얹은 트리 fbb325c1):
`python3 -m unittest discover -s scripts/tests` OK, `check-docs.py` rc=0,
`check-work-docs.py` rc=0, 같은 범위 상대 링크 555개 깨짐 0, `check-repo-layout.py`
rc=0. lychee(0.22.0 이미지)는 rc=2이고 실패 4건이 앞 트리와 같다(기록 문서의
404, 이 변경 전부터). 이 README를 읽는 테스트는 없다(`grep -rn --include='*.java'`).
2026-11-07 19:24:43 +09:00
DongHyeonka 2d43356136 ci(docs): 참조 검사가 디스크에만 남은 폴더를 있는 경로로 세지 않는다
참조 검사(reference)와 머리 블록의 「현재 정본」·「대체됨」 검사는 경로가
있는지를 파일 시스템(Path.exists)으로 본다. git mv는 옮긴 뒤 빈 옛 폴더를
디스크에 남긴다. 그래서 지운 폴더를 가리키는 살아 있는 문서가 노트북에서는
통과하고, 빈 폴더가 없는 새 checkout(PR workflow)에서만 실패한다. 알림 ADR을
옮길 때(39d4f248) 실제로 그랬다: docs/README.md에 쓴 옛 폴더 경로가 빈
docs/notification/adr/ 때문에 통과했고, 폴더를 지운 뒤에야 걸렸다.

「있다」를 git이 아는 파일(추적 + 무시되지 않은 새 파일, 문서 목록과 같은
git ls-files)과 그 위 폴더로 바꿨다(known_paths). leaf 기준 상대 경로를
위 폴더로 올라가며 찾는 규칙은 그대로다. 무시되는 경로(src/.env 등)는
전처럼 git check-ignore가 건너뛴다.

버린 대안: 빈 폴더만 따로 빼기. 아무도 추가하지 않은 파일(디스크에만 있는
build 밖 산출물)도 같은 거짓 통과를 만든다. git이 보는 것과 같게 하면
노트북과 PR workflow가 같은 답을 낸다.

자기 시험 셋을 더했다(79 OK): 빈 폴더를 가리키는 참조가 실패, 파일이 든
폴더는 통과, 빈 폴더를 가리키는 「현재 정본」이 실패. 변이 시험: 디스크의
모든 경로를 다시 세게 하면 rc=1, 빈 폴더 시험 둘이 실패한다.

검증(노트북): check-docs.py OK(여섯 검사 걸림 0, 0.8초), 자기 시험 79 OK.
빈 docs/notification/adr/를 다시 만들어도 known_paths는 그 폴더를 모른다.
2026-11-07 18:31:33 +09:00
DongHyeonka 83e9bd3dc3 docs(runbooks): JVM OOM runbook의 종료 코드를 실제 JVM 동작에 맞춘다
runtime-jvm-oom runbook이 「컨테이너가 코드 137로 끝난다
(-XX:+ExitOnOutOfMemoryError가 동작함)」고 적는다. 그 옵션으로 JVM이 스스로
끝나면 종료 코드는 3이고 stderr에 「Terminating due to
java.lang.OutOfMemoryError: …」가 남는다. 137은 SIGKILL이다. 힙이 아니라
프로세스 전체 메모리가 컨테이너 한계를 넘어 커널이 죽인 경우이고, 원인과
볼 것이 다르다(번역 묶음 D2c가 확인 필요로 넘긴 것).

증상 절을 둘로 나눴다: 코드 3 + 그 stderr 줄은 이 runbook, 코드 137 +
OOMKilled는 다른 일(힙과 네이티브 메모리의 합, MaxRAMPercentage가 남긴 몫,
힙 덤프 없음).

검증: desktop에서 이 저장소 이미지(caskeleton:0.0.1_local_0000000-default,
9ae52229)를 공유 잠금 아래 java -Xmx4m·-Xmx6m
-XX:+ExitOnOutOfMemoryError -jar application.jar로 띄웠다. 둘 다 rc=3,
stderr 「Terminating due to java.lang.OutOfMemoryError: Java heap space」.
노트북 check-docs.py OK.

한계: ContainerRuntimeOomContractTest Javadoc의 「exit 137」은 테스트 코드라
이 변경에서 고치지 않았다.
2026-11-07 18:30:03 +09:00
DongHyeonka 4fc586478c docs(claude): 진입 문서에 단독 번호로 남은 이력 ID를 내용과 날짜로 바꾼다
AGENTS.md와 src/**/CLAUDE.md는 본문에 지난 리뷰 ID를 두지 않는다
(docs/work/README.md 8절). 번역한 CLAUDE.md 넷에 짝 하나짜리 번호가
남았다: persistence-jpa·app-bootstrap의 「07-08」, grpc의 「11-M9」,
messaging의 「06-01 수정」. check-work-docs.py는 단독 NN-NN을 일부러 잡지
않으므로(범위·절 번호와 구별할 수 없다) 통과했다(번역 묶음 D2b가 넘긴 것).

ID 대신 그 발견의 내용과 날짜를 적었다. 원래 ID와 근거 리뷰 파일은
docs/work/evidence.md 10절 끝에 행 넷으로 남겼다(앞 행들과 같은 칸).

검증(노트북): check-work-docs.py OK, --history(바꾼 파일) 이력 ID 0,
check-docs.py OK. 이 넷을 읽는 테스트는 없다(git grep 'CLAUDE.md' -- '*Test.java').
2026-11-07 18:27:30 +09:00
DongHyeonka 65749238b2 docs(mongodb): MongoDB runbook 머리말 상태를 초안·운영 어휘로 바꾼다
runbook 상태 어휘가 초안·운영으로 바뀌었는데(docs/runbooks/template.md,
RunbookCoverageContractTest) docs/mongodb/runbooks/의 두 runbook은 옛 값
status: active를 쓴다. 그 시험은 docs/runbooks만 보므로 걸리지 않았다
(번역 묶음 D2c가 범위 밖으로 넘긴 것).

failover.md, unknown-commit.md의 status: active → 운영(옛 active의 뜻).
본문은 바꾸지 않았다.

검증(노트북): check-docs.py OK. 살아 있는 문서의 머리말 status 중 초안·운영
밖의 값 0(git grep '^status:').
2026-11-07 18:27:30 +09:00
DongHyeonka 44779a0625 docs(web): web README의 없는 오류 코드와 지운 IP 모드 주장을 코드에 맞춘다
번역 묶음(D2b)이 확인하지 못하고 넘긴 대문자 식별자 넷을 코드와 대조했다.
MAX_CONCURRENT_STREAMS(RFC 9113 HTTP/2 설정 이름)와 DEFAULT_MAX_PAGE_SIZE
(Spring Data 상수)는 바깥 이름이라 맞다. 둘은 틀렸다.

- 예외 대응 표의 MaxUploadSizeExceededException 행이 「multipart 전용
  413(UPLOAD_SIZE_EXCEEDED)은 이 영역의 책임 — 병합 후 정제」라고 적는다.
  그런 오류 코드는 레지스트리에도 코드에도 없다.
  GlobalExceptionHandler.handleMaxUploadSizeExceededException은 multipart와
  JSON 본문 모두 PAYLOAD_TOO_LARGE(413)로 답한다. 그대로 적었다.
- 「클라이언트 IP」 절이 지운 모드의 이름(FORWARDED_HEADERS_TRUSTED)을 지금
  있는 것처럼 인라인 코드로 적는다. 이름을 빼고, 지운 사실은 제거 표
  (docs/capability-status.md 「제거된 코드」)를 가리킨다.

검증(노트북): check-docs.py OK. 이 README를 읽는 테스트는 없다
(git grep 'inbound/web/README').
2026-11-07 18:27:30 +09:00
DongHyeonka 2af465e71c docs(src): src/README를 「~한다」체로 맞추고 Compose 최소 버전은 정본을 가리킨다
src/README.md가 「~합니다」체다(끝맺음 215곳, 「~한다」는 번역 묶음이 고친
두 문장뿐). docs/README.md 「문서 수명과 언어」는 살아 있는 문서의 문체를
「~한다」로 정하고 한 문서 안에서 섞지 않게 한다. 번역 묶음(D2a)이 이
문서의 영어 제목·문장만 맡아 문체는 범위 밖으로 넘겼다.

- 끝맺음만 바꿨다. 낱말 111개를 하나씩 대응표로 바꾸고(합니다 → 한다,
  입니다 → 이다·다, 형용사는 하다·다: 견고하다, 필요하다, 다르다, 크다,
  쉽다, 같다, 「있지 않습니다」 → 「있지 않다」, 「~세요」 → 「~한다」),
  바뀐 195줄을 한 줄씩 읽었다. 줄 수(577)와 다른 글자는 그대로다.
- 「Docker Compose 최소 버전 `2.24.4`」가 정본
  (compose-profile-contracts.json의 minimumComposeVersion)을 옆에 적고도
  값을 복사했다. 값을 지우고 정본 키를 가리킨다.

버린 대안: 문체를 그대로 두고 규칙 쪽에 예외를 두기. 한 파일만 다른
문체를 허용할 근거가 없다.

이 문서를 글자 그대로 읽는 테스트는 없다(git grep 'src/README' — 링크
검사 범위 목록 테스트 하나만 경로를 적는다).

검증(노트북): check-docs.py OK, 「~니다」 끝맺음 남은 수 0(「아니다」 제외).
2026-11-07 18:27:30 +09:00
DongHyeonka 9c4ca9f391 ci(docs): 숫자 검사가 굵은 글씨·표 칸의 Spring Boot 버전 복사도 잡는다
숫자 검사(number)는 「Spring Boot 4.0.8」처럼 이름 바로 뒤에 붙은 버전만
본다. 이름과 떨어진 복사는 지나간다. 기준 커밋 03a313ed의 살아 있는
문서에 그런 복사가 넷 있었다.
- docs/web/repository-adaptation.md:65 「baseline is **4.0.8**」
  (의존성 세션이 손으로 찾아 고친 줄. 그 브랜치는 **4.0.9**로 바꾼다)
- docs/compatibility/grpc-support-matrix.md:29 「| Spring Boot | 4.0.8 …」
- docs/mongodb/support-matrix.md:12 「| Spring Boot | 4.0.0 |」
- docs/jpa/repository-adaptation.md:100 「Boot 4.0.0 resolves …」
번역 묶음이 넷 모두 정본을 가리키게 고쳤지만, 검사가 막지 않으면
다시 생긴다.

규칙 셋을 더했다(Spring Boot 버전에만).
1. 이름 규칙이 「Spring」 없는 「Boot x.y.z」도 잡는다.
2. 표 행에 칸 전체가 「Spring Boot」(굵은 글씨·코드·링크를 벗긴 뒤,
   뒤에 BOM·버전이 붙어도 됨)인 칸이 있으면 그 행의 세 자리 버전.
3. 정본(src/gradle/libs.versions.toml의 springBoot)과 같은 버전 문자열은
   어디에 쓰든(굵은 글씨, 표 칸, 인라인 코드). 앞이 낱말·점·§이거나
   뒤가 낱말·「.숫자」이면 다른 수의 일부로 보고 넘긴다(RFC §4.0.8,
   14.0.8, 4.0.80, 4.0.8.1).
이름 옆 복사는 한 번만 센다(2·3이 그 안의 버전을 다시 세지 않는다).
결정 기록·제거 표·upgrade/를 빼는 범위는 그대로다(checked_for_drift).

버린 대안: 굵은 글씨 안의 모든 세 자리 버전을 잡기. 살아 있는 문서를
훑으면 Spring Boot 아닌 것이 둘 걸린다. docs/jpa/support-matrix.md의
Hibernate **7.1.8.Final**은 JpaDocumentationContractTest가 release
registry의 값과 같은지 단언하는 렌더링이라 지울 수 없다. 그것을 잡으면
굵은 글씨만 빼서 검사를 피하게 된다. 규칙 3은 정본 값을 직접 보므로,
지금 버전의 복사는 모양과 상관없이 생길 수 없고, 버전을 올리는 변경
때 옛 값의 복사가 남아 있을 수 없다.

한계: 정본 값과 다르고 이름과도 떨어진 버전(「4.0.0 / 5.0.0」 같은
문장)은 잡지 않는다. Spring Boot 밖의 버전 복사는 이 검사의 범위가
아니다(docs/README.md 「문서 검사」 number 행).

시험: 03a313ed 트리와 의존성 브랜치(cb67b879) 트리에 옛·새 검사를
돌렸다. 새 검사가 위 네 줄(의존성 브랜치는 **4.0.9**)을 더 잡고,
옛 검사가 잡던 28건은 모두 그대로 잡는다. 합친 트리는 걸림 0이라
예외를 더하거나 고칠 문서가 없다.

자기 시험 8개를 더했다(76 OK). 조건을 하나씩 끈 변이 시험 7개가 모두
rc=1이다: 옛 이름 정규식, 표 칸 규칙 끔, 정본 값 규칙 끔, 중복 세기
제거 끔, 정본 값 앞 § 허용, 정본 값 뒤 경계 끔, 칸 이름 앞부분만 맞춤.

검증(노트북): check-docs.py OK, 자기 시험 76 OK, check-work-docs.py OK.
2026-11-07 18:19:42 +09:00
DongHyeonka ff6f5cc0a7 docs(upgrade): 문서 번역 단계가 파생 서비스에 주는 변경을 안내한다
번역 네 묶음(D2a~D2d)을 합친 트리는 문서만이 아니라 문서를 읽는
테스트의 기대 문구도 바꿨다. runbook 머리말 status 어휘(stub·active →
초안·운영), 루트 README의 「## 시작하기」, 알림 지원 매트릭스의 등급 칸
이름, 파일서버·JPA 문서의 한국어 제목과 문구, 패키지 소유 표의 머리
칸이다. 자기 runbook을 두었거나 그 문서를 고친 파생 서비스는 merge 뒤
mainCheck의 document-contract lane이 실패한다. 그런데 이것을 적은
안내가 없다. docs/README.md도 「아직 옮기지 않은 문서는 예외 목록에
있다」고 적어 지금(목록이 빔)과 맞지 않고, ADR 본문을 옮긴 사실이 「본문은
원문 그대로」라는 기록 규칙 설명과 부딪친다.

- docs/upgrade/2026-11-docs-records.md에 4절(2단계)을 더했다. 할 일
  다섯과, 기대 문구가 바뀐 문서·테스트 표다. 범위·「누가 읽나」·3절의
  「본문은 원문 그대로」를 2단계에 맞게 고쳤다.
- docs/README.md 「문서 수명과 언어」: 모두 옮겼고 예외 목록이 비었다,
  ADR 번역은 뜻을 바꾸지 않은 옮김이고 원문은 03a313ed에 있다.
  「기록 문서의 머리 블록」: ADR만 본문을 옮겼다.

버린 대안: 새 업그레이드 문서를 따로 쓰기. 같은 날 같은 문서 체계 일의
두 단계이고, 옮긴 경로 표(2절)를 2단계의 ADR 이동과 함께 한 곳에서
찾게 하는 편이 낫다.

한계: ADR 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 고치지
않았다. 그 문구는 design-docs conventions/docs-system.md가 정하고
check-docs.py가 글자 그대로 본다. 바꾸려면 정본부터 바꿔야 한다.
docs-check를 파생 서비스가 유지할지(docs/ci-cd/template-vs-consumer.md
분류)는 이 변경이 정하지 않는다.

검증(노트북): check-docs.py OK, 자기 시험 68 OK, check-work-docs.py OK.
안내의 테스트 이름·기대 문구는 각 테스트 소스에서 확인했다
(RunbookCoverageContractTest RUNBOOK_STATUSES, DeveloperExperience
ContractTest, NotificationEvidenceVerifier GRADE_COLUMN_HEADER,
NotificationReleaseGateTest, FileserverDocumentationCoverageTest,
JpaDocumentationContractTest, TemplatePackageOwnershipDocumentTest).
2026-11-07 18:16:54 +09:00
DongHyeonka 80e7ef12a2 ci(docs): FROZEN에 목록에 없는 지문이 남으면 문서 검사가 실패한다
예외 목록은 줄기만 해야 하는데 빈틈이 있다. check-docs.py는 목록의
줄이 FROZEN에 있는지만 보고, FROZEN의 지문이 목록에 있는지는 보지
않는다. 그래서 번역해서 지운 줄의 지문이 FROZEN에 남고, 같은 줄을 다시
더해도 검사가 통과한다. 기준 커밋 03a313ed에서 이미 FROZEN 217개 중
9개가 목록에 줄이 없었다(앞 단계의 이름 바꾸기에서 남은 것).

- run()이 FROZEN - (목록 줄의 지문)을 실패로 낸다. --only와 상관없이
  돈다(목록의 줄이 FROZEN에 있는지 보는 검사와 같다).
- 합친 트리의 목록이 비었으므로 FROZEN에서 217개를 모두 뺐다. 이제
  목록에 어떤 줄을 더해도 실패한다.
- 설명(스크립트 머리, 예외 목록 머리 주석, docs/README.md 「문서
  검사」)에 「줄을 지우면 FROZEN에서 그 지문도 뺀다」를 더했다.
  스크립트 머리의 「넷 모두」를 지금의 여섯 검사로 고쳤다.

버린 대안: FROZEN을 그대로 두고 자기 시험만 더하기. 실제 검사(PR
workflow)는 자기 시험과 따로 돌므로, 목록과 FROZEN이 어긋난 트리가
check-docs.py만으로는 통과한다. 검사 자신이 막아야 한다.

자기 시험(scripts/tests/test_check_docs.py)에 셋을 더했다.
- test_a_frozen_fingerprint_whose_line_was_removed_fails: 고장 낸 입력
  (빈 목록 + 지문 하나)이 language·head 어느 검사로 돌려도 실패한다.
- test_a_removed_line_added_back_fails_once_its_fingerprint_is_gone:
  지문을 뺀 뒤 줄을 다시 더하면 「기준선에 없는 예외다」로 실패하고,
  남은 줄에는 고아 지문 오류가 나지 않는다.
- test_every_frozen_fingerprint_has_its_line_in_the_real_exception_list:
  실제 FROZEN과 실제 목록이 맞는다.

조건을 끈 변이 시험(사본에 문자열 치환, 자기 시험 실행):
- 고아 지문 검사를 지움 → rc=1, 첫째 시험 실패
- FROZEN을 03a313ed의 217개로 되돌림 → rc=1, 셋째 시험 실패.
  실제 트리의 check-docs.py도 고아 지문 217건으로 실패한다.
- 둘 다(바꾸기 전 코드) → rc=1, 첫째·셋째 시험 실패

검증(노트북): check-docs.py OK(여섯 검사 걸림 0), 자기 시험 68 OK,
check-work-docs.py OK.
2026-11-07 18:15:29 +09:00
DongHyeonka 39d4f24803 docs(adr)!: 알림 결정 기록을 docs/adr로 옮긴다
결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다.
문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이
모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지
보기」도 두 곳을 가리킨다.

NOTIF-ADR-001~005를 이름 그대로 docs/adr/로 옮긴다(git mv, 본문·머리
블록 그대로). 가리키던 곳을 함께 고친다.
- 루트 README 문서 지도 행, docs/README.md 지도·수명 표·머리 블록 절
- scripts/check-docs.py의 RECORD_KINDS·DECISION_PREFIXES와 설명
- NotificationReleaseGateTest: ADR 넷의 존재를 docs/adr/에서 본다
- docs/upgrade/2026-11-docs-records.md: 옮긴 경로 표와 찾는 명령

파일 이름 앞머리(NOTIF-ADR-)는 바꾸지 않았다. 설계서·리뷰·모듈 문서가
NOTIF-ADR-005처럼 번호로 부르고 있어, 이름을 ADR-NOTIF-로 바꾸면
기록 본문의 부름이 맞지 않게 된다.

위험: 이 ADR을 가리키던 문서·주석을 가진 파생 서비스는 경로를 바꿔야
한다(upgrade 안내 3절). notification-platform.yml의 pull_request 경로
필터 docs/notification/**는 이제 이 ADR을 보지 않는다. ADR 존재 시험
(NotificationReleaseGateTest)은 PR의 ci(:adapter:outbound:notification:
check)에서 계속 돈다. workflow는 이 변경에서 고치지 않았다.

이 ADR을 예외로 둔 줄은 없었다(합친 트리의 예외 목록이 이미 비어 있다).

검증(노트북): check-docs.py OK(language·head·reference·number·map·
readme 걸림 0), 자기 시험 65 OK, check-work-docs.py OK,
check-repo-layout.py OK, 살아 있는 문서에서 notification/adr 참조 0.

BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로
옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로
바꾼다.
2026-11-07 18:10:33 +09:00
DongHyeonka a1d75a924c Merge branch 'claude/d2d-ops-docs-2-e40938' — MongoDB·파일서버·HTTP·web·Redis·WebSocket 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 159줄, D2d 49줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(61 → 12줄).
2026-11-07 18:07:21 +09:00
DongHyeonka ef029f2643 Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄).
2026-11-07 18:07:16 +09:00
DongHyeonka bec5079193 Merge branch 'claude/d2b-src-adr-d46d23' — 모듈 문서와 ADR 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(D2a 11줄, D2b 81줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(220 → 128줄).
2026-11-07 18:07:04 +09:00
DongHyeonka b20143e456 Merge branch 'claude/d2a-entry-docs-12a342' — 루트 README·문서 지도·검사 K5·K6·레지스트리 설명 칸 2026-11-07 18:06:49 +09:00
DongHyeonka cb67b8792d docs: 의존성 취약점 수정의 업그레이드 안내와 결정 색인 행을 더한다
문제: 앞 커밋 아홉 개가 파생 서비스가 받는 버전을 바꿨다(Spring Boot 4.0.9,
gRPC 1.75.0, httpclient5·httpcore5, 새 `pinned-*` 고정, Querydsl 컴파일 의존,
lockfile 옛 줄). 업그레이드 안내에 행이 없으면 파생 서비스는 merge 때 lockfile
충돌과 httpcore5의 새 응답 헤더 상한을 미리 알 수 없다. 버전을 고르는 규칙과
Querydsl 처리도 결정 색인에 없어 다음 세션이 다시 묻는다.

고친 방법:
- `docs/upgrade/2026-11-maturity-review.md`: 새 3.7절과 B-54 행(무엇이 바뀌었나,
  증상, 할 일, 근거 커밋). 이 안내는 아직 main에 합쳐지지 않았으므로 결정 색인
  「아직 합치지 않은 업그레이드 안내」대로 머리 「커밋:」 목록에 한 항목을 더했다.
- `docs/work/reference/decisions.md` 2.7절: 「취약점이 있는 의존성 버전」(고르는
  순서와 놓는 곳)과 「Querydsl 취약 좌표」 두 행. 둘 다 기본값이고, Querydsl은
  총괄 확인 전이라고 적었다.
- `docs/web/repository-adaptation.md:65`: baseline 숫자 4.0.8→4.0.9만 고쳤다.
  같은 숫자가 있는 다른 살아 있는 문서 8곳은 `scripts/check-docs-exceptions.txt`의
  number 예외로 얼어 있어 고치지 않았다(고치면 문서 검사가 실패하고, 예외 파일은
  이 작업의 범위 밖이다).

위험·한계: 위 8곳은 Boot 4.0.8로 남는다. 번역 작업이 그 문서를 옮길 때 숫자를
정본(카탈로그)을 가리키는 말로 바꾸고 예외 줄을 지워야 한다.

검증: `python3 scripts/check-docs.py` rc=0(number 걸림 28, 예외 28, 실패 0),
`python3 scripts/check-work-docs.py` rc=0. 고친 세 문서를 읽는 테스트는 없다
(`grep -rn --include='*.java'`로 파일 이름을 찾았다).
2026-11-07 17:59:29 +09:00
DongHyeonka 8e3bef0f3e build(deps): persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다
문제: persistence-jpa의 compileOnly·testImplementation
`com.querydsl:querydsl-jpa:5.1.0:jakarta`에 HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있다. 그 좌표에는 고친 버전이
없다(GHSA-6q3q-6v5j-h6vg: com.querydsl:querydsl-jpa·querydsl-apt <=5.1.0, 고친
버전 없음). trivy 37건 중 마지막 남은 한 건이다.

고친 방법: 이 leaf가 쓰는 Querydsl 타입은 `querydsl.PredicatePolicy`의
`com.querydsl.core.types.Predicate` 하나이고, 이것은 querydsl-core에 있다(공지 대상이
아니다). 그래서 두 줄을 `com.querydsl:querydsl-core`(Boot BOM이 관리하는 5.1.0)로
바꾼다. 둘 다 compileOnly·test 범위라 배포물은 원래부터 Querydsl을 싣지 않는다.
JPAQuery를 만드는 querydsl-jpa는 이 capability를 켜는 서비스가 직접 더하는 것으로
그대로 둔다(README의 안내와 같다). build.gradle 주석에 이유를 적었다.
- 버린 대안: OpenFeign 포크 `io.github.openfeign.querydsl:querydsl-jpa`(5.6.1, 6.10.1+)로
  옮기기. 좌표가 바뀌어 파생 서비스가 같이 바꿔야 하고, 이 leaf에는 필요 없는 jar다.
- 버린 대안: `.trivyignore.yaml`에 90일 무시. 쓰지 않는 jar의 위험을 기한부로 안는다.
이 선택은 총괄에게 물었고 답을 받기 전에 권하는 안으로 진행했다.

위험·한계: querydsl-jpa를 직접 더하는 서비스는 여전히 고친 버전이 없는 좌표를 쓴다.
업그레이드 안내 B-54에 OpenFeign 포크를 검토하라고 적는다. 동작 변화는 없다
(compileOnly 클래스패스에서 쓰지 않는 jar 하나가 빠진다).

검증(desktop, 이 트리 6831ad47):
- 세 빌드를 `--write-locks`로 다시 썼다. persistence-jpa lockfile에서 querydsl-jpa가
  7개 구성에서 빠졌고 querydsl-core 5.1.0은 그대로다.
- `:adapter:outbound:persistence-jpa:check :adapter:outbound:persistence-jpa:testQualityCheck
  verifyDependencyLocks` rc=0, test 666 실패 0(`PredicatePolicyTest`,
  `JpaModuleBoundaryTest` 포함).
- `:adapter:outbound:persistence-jpa:compileJava --rerun` rc=0: 운영 코드가
  querydsl-core만으로 컴파일된다.
- 앞 커밋 트리(c5ed4659)를 깨끗한 worktree로 꺼내 돌린 trivy에서 남은
  HIGH·CRITICAL은 이 한 건이었다.
2026-11-07 17:58:32 +09:00
DongHyeonka 54383d3f45 docs(storage): 파일 서버와 Object Storage 경계 문서를 한국어로 옮긴다
문제: `docs/storage-capability-boundary.md`가 영어였다.

고친 것: 번역했다. 주장은 바꾸지 않았다. 예외 목록에서 이 파일의 language 줄을 지웠다.
이 커밋으로 이 작업 범위(runbook·알림·JPA·관측·호환·storage)의 language·number 예외
줄이 0이 된다.

검증: 최종 트리 기준(첫 커밋 본문 참고).
2026-11-07 17:56:35 +09:00
DongHyeonka 119c8d6e5a docs(compatibility): gRPC 지원 매트릭스를 한국어로 옮기고 정본을 가리킨다
문제: `docs/compatibility`의 두 문서가 영어였고, `grpc-support-matrix.md`는 Spring Boot
버전을 복사했다(number 예외). 지운 `GrpcAdvancedSupportMatrix`·
`GrpcAdvancedPromotionEvidence`와 없는 `runtime_memberships`, `src/build.gradle`의
`ext.grpcVersion`을 가리켰다.

고친 것: 둘을 번역했다. 버전은 `src/gradle/libs.versions.toml`을 가리키고, 등급의 정본은
`GrpcAdvancedCapability.defaultGrade`, 빌드 상태는 registry의 `"build": "optional-grpc"`로
적었다. 예외 목록에서 language 줄 2개와 number 줄 1개를 지웠다.

검증: 최종 트리 기준(첫 커밋 본문 참고).
2026-11-07 17:56:35 +09:00
DongHyeonka e243eb582b docs(observability): 구조화 로그 칸 사전을 한국어로 옮긴다
문제: `docs/observability/log-fields.md`가 영어였고, `startup.phase` 예시에 없는 값
`adapter-check`가 있었다.

고친 것: 번역했다. `startup.phase` 값을 `StartupPhase`의 넷(`env-validation`, `migration`,
`profile-check`, `adapter-enablement`)으로 맞췄다. 칸 이름은 코드에서 찾아 그대로다.
예외 목록에서 이 파일의 language 줄을 지웠다.

검증: 최종 트리 기준(첫 커밋 본문 참고).
2026-11-07 17:56:34 +09:00
DongHyeonka b1cda0307b docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.

고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
  gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
  `` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
  lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
  한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
  - support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
    `JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
  - repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
    `src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
    `composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
    plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
    `JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
    여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
  - experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
  증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
  고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.

버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.

위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
  `JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
  `PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
2026-11-07 17:56:34 +09:00
DongHyeonka 5a860e1e6b docs(notification): 알림 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.

고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
  그대로다.
- 코드에 맞춘 주장:
  - configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
    (`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
    (`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
    적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
  - at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
    지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
    `NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
    결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
    문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
    대로 짧은 교체 순서를 더했다.
  - module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
    「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
    provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
  옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
  있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
  거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
  표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.

버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.

위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:notification:check` rc=0(375개 건너뜀 1 실패 0. `NotificationReleaseGateTest` 3,
  `NotificationEvidenceVerifierTest` 7, `NotificationModeSsotTest` 3, `NotificationPayloadAtRestContractTest` 5),
  `:mainCheck` rc=0(`notificationDocumentContractTest`의 저장소 문서 대조 통과), `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `NotificationReleaseGateTest` 2개와 저장소 문서 대조가 실패한다
  ("support-matrix.md has no table that assigns a grade (a '등급' column …)").
2026-11-07 17:56:34 +09:00
DongHyeonka a81e92faca docs(runbooks): runbook을 한국어로 옮기고 상태를 초안·운영으로 바꾼다
문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.

고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
  lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`.
  머리말이 없는 gRPC runbook 둘은 그대로다.
- 코드에 맞춘 주장:
  - adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의
    `failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는
    곳은 `RoutingNotifier`뿐이다.
  - startup-required-adapter-disabled: `startup.phase=adapter-check` →
    `adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`).
  - cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure:
    그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다.
  - db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout`
    → `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다.
  - dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call`
    (`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다).
  - management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록
    (`config/observability.yml`).
  - runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프
    경로(`src/Dockerfile`)를 적었다.
  - auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`.
  - grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` →
    `GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로.
  - grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index
  migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는
  쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다.
- `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영`
  밖이면 실패하는 테스트를 더했다.
- `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다.

버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영
runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다.

위험·한계:
- 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다.
- runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의
  `-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다.
- `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다.

검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다.

검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
  `:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
  `postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
  `postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
  rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
  `:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
  `everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
2026-11-07 17:56:34 +09:00
DongHyeonka 9fcab227d8 build(deps): Kafka 클라이언트의 lz4-java·snappy-java를 고정한다
문제: Boot 4.0.9가 고르는 kafka-clients 4.1.2가 압축 라이브러리 두 개의 낡은
버전을 가져온다.
- at.yawk.lz4:lz4-java 1.10.1: HIGH CVE-2026-106451(공유 임시 폴더로 native
  라이브러리를 풀어 코드 실행). 1.11.4에서 고쳤다.
- org.xerial.snappy:snappy-java 1.1.10.7: HIGH CVE-2026-93451(손상된 압축
  입력으로 버퍼 넘침), CVE-2026-108106(압축 해제 중 메모리 할당 제한 없음).
  1.1.10.9에서 고쳤다.
messaging 플랫폼의 kafka leaf 셋, adapter:inbound:messaging,
adapter:outbound:messaging-kafka, app-bootstrap이 가진다.

고친 방법: `pinned-*` 묶음에 `pinned-lz4-java`(1.11.4)와
`pinned-snappy-java`(1.1.10.9)를 더한다. 둘 다 고친 가장 작은 버전이다.
lz4 1.11.4는 1.11.1~1.11.4에서 고친 lz4 MEDIUM·LOW 공지 다섯도 함께 푼다.
- 버린 대안: kafka-clients를 올리기(`kafka.version` override). 4.1 줄에는
  고친 패치가 없고, 4.3.2가 lz4 1.11.4·snappy 1.1.10.11을 가져오지만 Boot 4.0의
  spring-kafka가 시험한 Kafka 줄을 벗어난다.

위험·한계: kafka-clients 4.1.2는 lz4 1.10.1에 맞춰 빌드됐다. Kafka 4.2.2가
1.11.2를, 4.3.2가 1.11.4를 쓰므로 Kafka가 쓰는 lz4 API는 1.11에서도 같다.
이 저장소는 Kafka 압축을 켜지 않아(설정·테스트에 `compression.type` 없음) 기존
테스트는 두 라이브러리를 부르지 않는다. 그래서 아래 탐침으로 kafka-clients의 압축
경로를 따로 봤다. 압축을 켠 실제 브로커 왕복은 보지 않았다.

검증(desktop, 이 트리 c5ed4659):
- 세 빌드를 `--write-locks`로 다시 썼다. Kafka를 쓰는 lockfile 6개에서
  lz4-java 1.10.1→1.11.4, snappy-java 1.1.10.7→1.1.10.9만 바뀌었다.
- `:messaging:messaging-kafka:check :messaging:messaging-spring-boot-starter-kafka:check
  :messaging:messaging-spring-boot-starter:check :adapter:inbound:messaging:check
  :adapter:outbound:messaging-kafka:check :app-bootstrap:check verifyDependencyLocks`
  rc=0. 클래스패스가 바뀐 leaf의 test가 다시 돌았다: messaging-kafka 87,
  starter 77, starter-kafka 2, adapter:outbound:messaging-kafka 4, 실패 0.
- `verifyMessagingCertificationEvidence`(messaging-certification workflow의 PR job,
  실제 Kafka 컨테이너) rc=0, 인증 lane 37 실패 0.
- 탐침(커밋하지 않음): kafka-clients 4.1.2의 `MemoryRecords.withRecords`로 lz4·snappy
  batch를 만들고 다시 읽는 프로그램. 새 jar 쌍과 옛 jar 쌍 모두 rc=0, 두 레코드와
  값 10006바이트를 그대로 읽었고 batch 크기도 같다(lz4 145, snappy 581바이트).
2026-11-07 17:55:02 +09:00
DongHyeonka ad859ca3a6 docs(registries): 출처 줄의 꼬리표와 기록 절 이름을 원문으로 되돌린다
문제: 앞 커밋이 레지스트리 주석의 `# source:`를 `# 출처:`로 바꾸고, 출처 줄 안의 기록 절
이름(「In scope」「Decisionized Work Items」「decisions」「Exposure Policy」「AuthN/AuthZ
Decision Matrix」)까지 한국어로 옮겼다. 출처 줄은 기록 이름·날짜·절 이름으로 원문을
찾아가는 줄이라, 옮기면 그 기록에서 같은 이름을 찾을 수 없다. 또 metrics.yaml 주석 세 줄에
변환 실수로 `\"`(백슬래시가 붙은 따옴표)가 들어갔다.

고른 방법: 총괄 기준(2026-11-07)대로 나눈다.
- 원문으로 둔다: 출처 줄의 꼬리표 `source:`, 기록 이름·날짜·절 이름, 따옴표 인용.
- 한국어로 둔다: 같은 줄의 나머지 설명, 행마다의 이유·조건·주의 산문, 값 칸, 파일 머리 블록.
- `\"`는 `"`로 고친다.

위험·한계: 출처가 가리키는 `feature-*` 계약 기록 24개는 저장소 어디에도(이력 포함) 그 이름의
파일이 없다. `docs/design/`에 있는 것은 `five-adapter-runtime-remediation`과
`redis-production-capability` 둘이고, 파일 이름에 날짜와 `-design`이 붙어 있다. 이름은 고치지
않았다.

검증: 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 앞 커밋과 같다(주석만 바뀜).
`python3 scripts/check-docs.py` rc=0.
2026-11-07 17:49:10 +09:00
DongHyeonka 81573f7098 build(deps): Checkstyle 도구의 plexus-utils를 3.6.1로 고정한다
문제: Checkstyle 13.5.0의 doxia 1.12.0이 plexus-utils 3.3.0을 가져온다. HIGH
CVE-2025-67030(extractFile 경로 조작)이 있고 3.x 줄에서는 3.6.1, 4.x에서는
4.0.3에서 고쳤다. 모든 leaf의 checkstyle 구성에 걸린다.

고친 방법: 앞 커밋의 `pinned-*` 묶음에 `pinned-plexus-utils`(3.6.1)를 더한다.
3.x 안에서 고친 가장 작은 버전이다.
- 버린 대안: 4.0.3. 메이저다. 4.0은 XML 클래스를 plexus-xml로 떼어 냈다.
- 버린 대안: doxia를 뺀 Checkstyle 13.11.0으로 올리기. plexus-utils는
  사라지지만 Checkstyle 규칙이 여섯 마이너만큼 바뀐다.

위험·한계: doxia는 Checkstyle의 사이트 문서 생성에만 쓰여 Gradle checkstyle
태스크에서는 plexus-utils를 거의 부르지 않는다. 그래도 모든 leaf의
checkstyle이 이 구성으로 돈다.

검증(desktop, 이 트리 00b8e235):
- 세 빌드를 `--write-locks`로 다시 썼다. lockfile 64개의 checkstyle 구성에서
  plexus-utils 3.3.0→3.6.1만 바뀌었다.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 32초,
  태스크 752(executed 641, up-to-date 111). checkstyle 태스크 109개가 실제로 돌았다.
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0,
  checkstyle 태스크 17개 실행.
2026-11-07 17:47:41 +09:00
DongHyeonka 2cf6aafd8a build(deps): guava를 33.7.2로 고정한다
문제: guava의 HIGH CVE-2026-102554(역직렬화 중 메모리 할당 제한 없음)는
33.7.2에서 고쳤다. 그런데 guava는 어떤 leaf도 직접 선언하지 않고, 낡은 버전이
셋에서 들어온다.
- gRPC 1.75.0: 33.3.1-android(lockfile에는 jre 변형 이름으로도 남는다)
- Error Prone 2.49.0(annotationProcessor 구성): 33.5.0-jre
- Checkstyle 13.5.0(checkstyle 구성): 33.6.0-jre
leaf 거의 전부의 lockfile에 걸린다.

고친 방법: 카탈로그에 `pinned-*` 라이브러리 묶음을 두고, JavaConventionsPlugin이
그 묶음을 Spring dependency management로 모든 leaf에 건다. 첫 항목이
`pinned-guava`(33.7.2-jre)다. 버전 키 주석에 CVE와 낡은 버전을 가져오는 곳을
적고, 그곳들이 고친 버전을 가져오면 지운다.
- dependency management를 쓰는 이유: Boot BOM처럼 모든 구성에 걸린다.
  checkstyle·annotationProcessor 구성도 받는다(lockfile에서 checkstyle 구성의
  commons-lang3가 BOM override 3.20.0인 것이 이미 그 증거다). Gradle constraint는
  구성마다 따로 걸어야 한다.
- 버전을 카탈로그에 두는 이유: 이 빌드가 고르는 버전이다(카탈로그 머리말).
  BOM이 관리하는 것을 덮는 override와 다르다.
- build-logic `PlatformModuleConventionTest`에 시험을 하나 더했다. fixture
  카탈로그의 `pinned-fixture`는 checkstyle 구성의 관리 버전이 되고,
  `unpinned-fixture`는 관리되지 않는다.
- 버린 대안: Error Prone 2.51.0, Checkstyle 14.4.0으로 올리기. 둘 다 guava
  33.7.2를 가져오지만 gRPC 쪽은 남고, 새 검사 규칙이 들어와 범위가 커진다.
  Checkstyle 14는 메이저다.

위험·한계: dependency management는 하한이 아니라 정확한 고정이다. 나중에
33.7.2보다 새 guava를 요구하는 라이브러리가 들어와도 33.7.2로 내린다. 그때는
그 leaf가 guava를 버전과 함께 직접 선언하면 그 선언이 이긴다. gRPC가 쓰던
android 변형 대신 jre 변형이 들어간다. jre 변형은 android 변형의 API를 모두
가진다. guava 33.7.2가 요구하는 대로 error_prone_annotations 2.50.0,
failureaccess 1.0.3, j2objc-annotations 3.1, jspecify 1.0.1이 같이 들어오고
checker-qual은 빠진다.

같은 커밋의 작은 정리: 앞 커밋이 넣은 httpcore5 주석의 줄바꿈을 고쳤다.

검증(desktop, 트리 49191720 위에 시험·주석 정리를 얹은 9a97dbbb):
- 세 빌드를 `--write-locks`로 다시 썼다. lockfile 64개에서 guava가 33.7.2-jre
  하나가 됐다(checkstyle·annotationProcessor 구성 포함). 위 동반 라이브러리 외에
  바뀐 것은 없고, 새로 생기거나 사라진 구성 0.
- RED: 장치 없는 트리(앞 커밋)에 새 시험만 얹으면 실패한다
  ("pinned=null unpinned=null").
- GREEN: `./gradlew -p build-logic check javadoc` rc=0, 테스트 174 실패 0.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 33초,
  태스크 752(executed 641, up-to-date 111, from cache 0). 모든 leaf가 새 guava로
  Error Prone·Checkstyle을 돌렸다.
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0, 1분 11초.
2026-11-07 17:36:22 +09:00
DongHyeonka 94ac85adf6 docs(notification-adr): 알림 결정 기록 본문을 한국어로 옮긴다
문제: `docs/notification/adr/`의 NOTIF-ADR-001~004는 머리 블록만
한국어이고 본문이 영어다. NOTIF-ADR-005는 한국어지만 상태 값과 절
제목 하나, 인용문이 영어로 남아 있다.

방법: 결정의 뜻을 바꾸지 않고 제자리에서 옮긴다(폴더 옮기기는 통합
단계의 몫이다). 머리 블록은 바꾸지 않는다. 식별자·타입 이름·상태 값
같은 코드 표기는 원문으로 두고, NOTIF-ADR-005가 인용한 영어 원문에는
뜻을 괄호로 붙인다. 파일 이름이 그대로라 NotificationReleaseGateTest가
보는 존재 단언은 영향이 없다.

위험: 없음. 본문 뜻은 바꾸지 않았다.

검증: python3 scripts/check-docs.py rc=0(language 줄 4개 지움, head
실패 0), 머리 블록이 HEAD와 같은지 5개 모두 diff로 대조.
2026-11-07 17:34:51 +09:00
DongHyeonka 74be416f93 docs(adr): 아키텍처 결정 기록 본문을 한국어로 옮긴다
문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이
영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로
정했다(design-docs `repo-structure/README.md` 3.2절).

방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약·
현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위
줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드·
명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한
영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을
괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본
지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은
`scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에
남긴다.

위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤
문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다.

검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움,
head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조,
check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:33:54 +09:00
DongHyeonka 7c2cfa0601 docs(websocket): WebSocket runbook을 한국어로 옮긴다
문제: docs/websocket/runbook.md가 영어였다(language 예외).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·close code·nginx 지시어·표 구조는 원문으로
둔다. 적힌 클래스·lane(`TomcatWebSocketShutdownIT`, `websocketNginxTest`,
`websocketJettyTest`, `nginx-no-upgrade.conf` 등)은 모두 지금 있다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/websocket을 읽는 테스트는
없다(`grep -rn 'docs/websocket' src --include=*.java` 결과 0).
2026-11-07 17:29:57 +09:00
DongHyeonka 4e2f08a687 docs(redis): Redis SDK 운영 문서를 한국어로 옮긴다
문제: docs/redis 아래 살아 있는 문서 4개가 영어였다(language 예외).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다.
support-matrix.md의 표 첫 칸(package·capability·토폴로지 이름)과 증거 칸의 테스트 클래스
이름은 RedisSupportMatrixTest가 그대로 읽으므로 바꾸지 않았다. 번역하며 고친 것:
- 「pinned to Lettuce 6.8.2」: build.gradle은 버전 없이 Boot BOM을 따른다. 숫자 대신
  BOM과 leaf gradle.lockfile을 가리킨다.
- 「five defects」 뒤 목록이 일곱 항목이라 「결함 일곱」으로 고쳤다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. RedisSupportMatrixTest의 세
단언(package·capability가 첫 칸에 있음, 토폴로지 행이 있는 테스트 클래스를 댐)을 같은
규칙으로 문서에 돌려 보았다(빠진 것 0).
2026-11-07 17:29:57 +09:00
DongHyeonka 9d6c67c14e docs(web): web 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는
짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외).
repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다.
- 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에,
  `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다.
  `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다.
- Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()`
  (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf
  `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다.
- 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다.
- 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다.
- 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로
둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과
문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다.

버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한
대응이 사라진다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는
주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
2026-11-07 17:29:57 +09:00
DongHyeonka e38c949c2f docs(httpclient): HTTP client 문서를 한국어로 옮기고 숫자 복사를 없앤다
문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외).
repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring
Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit`
source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는
원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다.
leaf 수는 registry(src/config/architecture/modules.json)를, 버전은
src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default,
Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만
옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만).
configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다.

버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라
날짜와 함께 그대로 둔다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0).
python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
2026-11-07 17:29:57 +09:00
DongHyeonka 6583cc2e02 docs(fileserver): 파일서버 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며
본 주장 중 지금 코드와 다른 것이 있었다.
- design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`·
  content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로
  없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`·
  `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만
  지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다.
  지운 reactive transport가 아직 스트리밍한다고 했다.
- security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다
  (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는
  지금 `HttpContentDispositionFactory`다.
- upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로
  읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이
  Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는
  `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다.
- operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 지원 등급
이름(Stable, Beta, Limited, Compatibility, Experimental)은 표와 테스트가 읽는 꼬리표라
원문으로 둔다(messaging 지원 매트릭스와 같다). configuration.md의 절 제목은 테스트가 읽는
「… — `key`」 꼴을 지킨다. 위 불일치는 코드에 맞춰 고쳤다.

테스트: FileserverDocumentationCoverageTest가 runbook 제목 일곱과 「Explicitly not
claimed」를 영어 문자열로 단언했다. 같은 계약(runbook마다 제목이 있고, 주장하지 않는 것을
따로 밝힌다)을 한국어 제목 `## 저장소 가득 참` 등과 `## 주장하지 않는 것`으로 단언한다.
제목 앞에 `## `를 붙여 본문 어딘가에 낱말만 있어도 통과하던 것을 제목으로 좁혔다.
metric 이름·CI job·endpoint·설정 key 단언은 그대로다.

버린 대안: runbook 제목을 영어로 남기기. 살아 있는 문서를 한국어로 쓴다는 소유자 결정과
맞지 않는다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로
문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
2026-11-07 17:29:57 +09:00
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language
예외), 몇 가지 주장이 지금 코드와 달랐다.
- repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨
  적었다(number 예외 두 줄).
- 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh·
  verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도
  있고 lane을 돌린다.
- testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와
  `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다.
- ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은
  없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`·
  `noProductionPackageDependsOnTheTestkit`이다.
- support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이
  lockfile과 달랐다(예: driver 5.6.1 → 5.6.5).
- consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다
  (reference 예외).
- document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과
leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile,
container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른
단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다.

버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시
틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는
그대로 두었다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0).
docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java`
— package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는
advanced 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00
DongHyeonka b169ad88bf docs(src): 모듈 문서의 ArchUnit 규칙 이름을 코드 상수 이름에 맞춘다
문제: 모듈 문서가 ArchUnit 규칙을 `domain_is_pure`,
`query_ports_do_not_leak_domain_jpa_or_web_types` 같은 소문자 이름으로
가리킨다. 지금 코드의 규칙은 `DOMAIN_IS_PURE` 같은 대문자 `static final
ArchRule` 상수이고 소문자 이름은 운영 코드 어디에도 없다. 문서의
이름으로 규칙을 찾으면 아무것도 나오지 않는다.

방법: `src/**`의 CLAUDE.md와 README에서 backtick으로 쓴 소문자 규칙
이름 중, 같은 이름의 대문자 ArchRule 상수가 코드에 있는 것만 그
상수 이름으로 바꾼다(31곳, 파일 8개). 지운 규칙을 적은 곳
(`inbound_port_implementations_do_not_declare_keyed_idempotency`)은
지웠다는 기록이라 그대로 둔다.

위험: shared-contract 운영 코드 Javadoc 두 곳
(`DomainContextPropagator`, `ThreadLocalDomainContextPropagator`)이 아직
소문자 `no_inheritable_thread_local`을 쓴다. 이 작업 범위(문서) 밖이라
고치지 않았다.

검증: 바꾼 이름마다 `static final ArchRule <NAME>` 또는 `<NAME> =`가
코드에 있는지 스크립트로 대조했다. python3 scripts/check-docs.py rc=0,
check-work-docs.py rc=0.
2026-11-07 17:25:37 +09:00
DongHyeonka 05e2145d22 docs(registries): 레지스트리 yaml의 설명 칸과 주석을 한국어로 옮긴다
문제: 소유자 결정(2026-11-07, design-docs `repo-structure/README.md` 3.2절)은 레지스트리
yaml의 설명 칸을 번역하라고 한다. 지금 값 칸 중 영어 산문은 env-keys `required_when`
7개, metrics `alert_severity_thresholds` 51개, object-storage-readiness `limitations`
15개이고, 주석은 약 940줄이 영어다. 주석 하나는 없는 파일
`docs/notification/configuration.md`를 가리킨다(있는 것은
`configuration-reference.md`).

고른 방법:
- 값 칸: 뜻을 그대로 옮기고 속성 이름·지표 이름·연산자·기간(5m, 1h)·식별자는 원문으로
  둔다. `required_when`의 `<속성>=<값>` 꼴(공백 없음)은 `RequiredWhenIsEnforcedTest`가
  기계로 읽으므로 그대로 두고, 공백이 든 설명 꼴만 옮긴다. 옮긴 값도 공백을 가져 그
  테스트가 계속 건너뛴다.
- 주석: 파일 머리의 설명 블록과 행마다의 설명·출처 주석을 옮긴다. `# source:`는
  `# 출처:`로 바꾸고, 설계 문서에서 따온 인용("...")은 원문으로 둔다.
- 그대로 둔 것: `RegistryGovernanceCatalog`가 글자 그대로 비교하는 머리 줄
  (`# Schema owner: ...`, object-storage-readiness 머리 넷)과 `# Registry:` 등 메타
  줄.
- 없는 문서 경로는 `docs/notification/configuration-reference.md`로 고친다.

이 칸을 읽는 테스트(먼저 찾음):
- `RegistryGovernanceCatalog`(ContractRegistrySchemaGovernanceTest): 머리 주석 줄을 글자
  그대로 본다 — 해당 줄은 바꾸지 않았다.
- `RequiredWhenIsEnforcedTest`(redis-runtime): 공백 없는 `required_when`만 조건으로 쓴다.
- `SecretsClassificationRegistryTest`: `required_when`이 null인지만 본다.
- `MetricsAlertingContractTest`: 경보 키가 `AlertSeverity`로 풀리는지와 값이 비어 있지
  않은지만 본다.
- `ObjectStorageReadinessRegistryTest`: `limitations`가 비어 있지 않은지만 본다.
- `NotificationModeSsotTest`: `name: APP_NOTIFICATION_PLATFORM_MODE` 뒤 첫 `default: `를
  찾는다 — 옮긴 주석에 `default: ` 글자를 넣지 않았다.

위험·한계: 행마다의 주석은 설계 문서 ID와 날짜를 그대로 둔다. 남은 영어는 인용과
식별자뿐이다.

검증: 바꾸기 전후 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 값 칸 말고는 같다(주석만
바꾼 파일은 완전히 같다). `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:24:54 +09:00
DongHyeonka 8813b02e54 docs(adapter-outbound): outbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가
영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전
(4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열·
표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을
가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다:
identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는
hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap
`IdempotencySettings`」를 실제 위치 `composition:idempotency`로,
redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로
mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는
지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다
(MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한
곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가
아직 영어라 원문 제목으로 둔다.

위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면
낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음
커밋에서 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄
10개 지움, src/** number 줄 0), check-work-docs.py rc=0,
--links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:24:33 +09:00
DongHyeonka d5b324ddb7 build(deps): httpclient5·httpcore5를 5.6.3·5.4.3으로 올린다
문제: Boot 4.0.9 BOM은 아직 httpcore5 5.3.6을 고른다. HIGH 두 건이 있고,
5.3 줄에는 고친 버전이 없다.
- CVE-2026-54399(httpcore5): HTTP/1 헤더 수·줄 길이 제한 없음, 메모리 고갈
- CVE-2026-54428(httpcore5-h2): HPACK 헤더 목록 크기 제한 없음
adapter:outbound:httpclient와 app-bootstrap이 이것을 가진다.

고친 방법: JavaConventionsPlugin에서 commons-lang3와 같은 BOM 속성 override로
`httpcore5.version`=5.4.3, `httpclient5.version`=5.6.3을 준다.
- core 5.4.3: 두 건을 고친 첫 버전.
- client를 함께 올리는 이유: client 릴리스마다 core 한 줄에 맞춰 빌드된다
  (5.5는 core 5.3, 5.6은 core 5.4). core 5.4는 client가 쓰는 classic-over-async
  bridge를 다시 설계했다. 5.6.2가 core 5.4.3을 선언하는 첫 client이고, 5.6.3은
  같은 core에 5.5.2에도 있는 MEDIUM GHSA-hjcp-jmpx-g3qm(Content-Encoding 디코딩
  중 연결 누수)을 고친다. 그래서 5.6.3이다.
- 버린 대안: core만 5.4.3. Apache가 시험하지 않은 짝이다.
- 버린 대안: Boot 4.1.2가 고르는 5.6.5·5.4.4. 5.4.4는 HTTP/1.1 기본 버퍼를
  32KiB로 바꾸는 등 이 CVE와 상관없는 기본값 변경이 더 있다.
카탈로그 머리말의 「일부러 여기 없는 것」 문단에 두 override를 더했다.

위험·한계: core 5.4.3은 들어오는 HTTP/1 메시지(HTTP client에게는 응답)에 줄
길이 8192, 헤더 100개 상한을 기본으로 건다. 넘는 응답은 거절된다. 5.6에서
client 기본값이 더 바뀐 것이 있으면 httpclient leaf의 테스트와 성능 lane이
본다. Boot가 httpcore5 5.4.3 이상을 관리하면 두 override를 지운다.

검증(desktop, 트리 a2bc6e76. 커밋 트리 d5bf2fd9는 여기에 주석 한 줄 줄바꿈만
더했고 build-logic `compileJava` rc=0):
- 세 빌드를 `--write-locks`로 다시 썼다. 바뀐 lockfile은 httpclient와
  app-bootstrap 둘이고 httpclient5·httpcore5·httpcore5-h2만 바뀌었다.
- `:adapter:outbound:httpclient:check :app-bootstrap:check verifyDependencyLocks`
  rc=0. httpclient test 360, httpClientSecurityTest 9, 실패 0.
- `httpClientStableContractTest -Phttpclient.contract.transports=apache`·`=jdk`
  (pr-adapters의 matrix) 둘 다 rc=0, 각 17 실패 0.
- `spring70CompatibilityTest` 23, `httpClientFailureInjectionTest` 4,
  `httpClientPerformanceTest`(상한 단언) 5, 모두 실패 0.
2026-11-07 17:22:34 +09:00
DongHyeonka 3b9b738cea build(deps): gRPC를 1.75.0으로 올린다
문제: gRPC BOM 1.68.1의 grpc-netty-shaded에 HIGH CVE-2025-55163(Netty HTTP/2
"MadeYouReset" 서비스 거부)이 있다. 1.75.0에서 고쳤다. adapter:inbound:grpc,
app-bootstrap, optional 빌드의 grpc-testkit lockfile이 이 버전을 가진다.

고친 방법: `grpc`를 고친 가장 작은 버전 1.75.0으로 올린다. 같이
`protobufGrpc`를 3.25.5→3.25.8로 올린다. grpc-protobuf 1.75.0이 선언하는
protobuf-java가 3.25.8이고, adapter:inbound:grpc의 protobuf-bom import가 실제로
해석되는 버전을 정하므로, 그대로 두면 gRPC가 자기가 빌드된 것보다 오래된
runtime에서 돈다. 같은 키를 쓰는 grpc-contract의 protoc도 3.25.8이 된다.
protobuf 다른 두 줄(4.33.2, 4.29.3)은 건드리지 않는다.
- 버린 대안: Boot 4.1이 관리하는 1.84.x. 열 버전 가까이 넘고, gRPC 플랫폼
  leaf 전체를 다시 검증해야 한다. 이 커밋의 목적은 CVE 하나다.
- 버린 대안: protobufGrpc를 3.25.5로 두기. 위 이유.

위험·한계: build-logic `PlatformModuleConventionTest`의 1.68.1은 그 테스트가
스스로 만드는 카탈로그 값이라 저장소 카탈로그와 상관없다. 고치지 않는다.
guava는 1.75.0도 낡은 버전(33.3.1-android)을 가져온다. 다음 커밋이 고정한다.

검증(desktop, 이 트리 92b9061f):
- 세 빌드를 `--write-locks`로 다시 썼다. 바뀐 lockfile 9개(adapter:inbound:grpc,
  app-bootstrap, gRPC 플랫폼 leaf 6개, grpc-contract). io.grpc 1.68.1→1.75.0,
  protobuf-java·util 3.25.5→3.25.8, guava 33.2.1→33.3.1, proto-google-common-protos
  2.41.0→2.59.2 등 gRPC가 가져오는 것만 바뀌었다.
- `:adapter:inbound:grpc:check :adapter:inbound:grpc:grpcTransportQualificationTest
  :app-bootstrap:check :app-bootstrap:conditionalTransportBuildContractTest
  verifyDependencyLocks` rc=0. 테스트: grpc leaf test 74, grpc 전송 lane 29,
  app-bootstrap test 225(skip 4), 조건부 전송 lane 3, 실패 0.
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0, 1분 15초.
2026-11-07 17:19:25 +09:00
DongHyeonka f56a100528 ci(docs): 문서 지도와 루트 README 절을 문서 검사가 본다
문제: 「모든 문서 폴더가 `docs/README.md` 지도에 있다」와 「루트 README가 정해진 절을
가진다」(design-docs `conventions/docs-system.md` 7절 K5·K6)를 아무것도 지키지 않는다.
테스트 자원 `broken-readme.md`(일부러 깨뜨린 입력)를 살아 있는 문서로 보고 언어 검사
예외에 둔다.

고른 방법: `scripts/check-docs.py`에 검사 둘을 더한다. docs-check workflow가 인자 없이
돌리므로 PR에서 바로 실패로 돈다.
- `map`: `docs/` 바로 아래 폴더가 모두 지도 표의 첫 칸에 있어야 한다. 파일 없이 폴더만
  가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. `.md`가 없는 폴더(스냅숏,
  yaml)도 본다. 지도에 있지만 없는 폴더도 실패다.
- `readme`: 첫 줄 `# 제목`, 그 아래 한 문단, `README_SECTIONS`의 `##` 절이 그 순서로
  있어야 한다. 사이에 다른 절은 있어도 된다.
- 소스 세트 resources 폴더 아래 `.md`(`/src/<세트>/resources/`)는 문서로 보지 않는다.
  그래서 `broken-readme.md` 예외 줄을 지운다.

버린 대안: 지도 폴더를 모든 깊이까지 요구하기. 리뷰 라운드 폴더, 납품 패키지 폴더마다
행이 생겨 지도가 목록이 된다. 절을 정확히 일곱 개만 허용하기. 서비스가 절을 더할 수
없게 된다.

위험·한계: `FROZEN` 지문은 건드리지 않았다. leaf·family README 절 검사(K6 뒷부분)와 파일
이름 규칙·실행 산출물 검사(K5 뒷부분)는 넣지 않았다.

검증:
- `python3 -m unittest discover -s scripts/tests` 65건 rc=0(새 시험 22건).
- 판정 조건 18개를 하나씩 끈 사본마다 자기 시험이 실패했다(rc=1).
- `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:18:19 +09:00
DongHyeonka d8afffce9e docs(docs): docs/README를 모든 문서 폴더를 덮는 지도로 다시 쓴다
문제: `docs/README.md`의 폴더 표에 `ci-cd/`, `compatibility/`, `mongo/`,
`objectstorage/`, `observability/`, `roadmap/`, `testing/`, `upgrade/`, `web/`,
`websocket/`가 없다. 폴더 밖 문서 둘(`capability-status.md`,
`storage-capability-boundary.md`)도 없다. 처음 온 사람이 문서를 찾을 수 없다.

고른 방법: 「문서 지도」 절 하나에 목적별 표(매뉴얼, 계약과 스냅숏, 영역 운영 문서,
운영과 전달, 결정 기록, 설계와 기록, 폴더 밖 문서)를 두고, 표의 첫 칸에 `폴더/`를
적는다. 다음 커밋의 `map` 검사가 이 첫 칸을 읽는다. 「문서 검사」 절에 `map`·`readme`
검사, resources 폴더 제외, `.lycheeignore` 규칙을 적는다.

위험·한계: 알림 ADR은 지금 위치 `notification/adr/`로 적었다. 옮기는 변경이 지도도
고친다.

검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py --links
docs/README.md` 깨진 링크 0.
2026-11-07 17:18:19 +09:00
DongHyeonka 6fa4f825f2 ci(links): 기록 안의 죽은 외부 링크 넷을 lychee 제외 목록에 둔다
문제: lychee가 기록 문서 안의 외부 링크 404 넷으로 실패한다(mongodb write-concern,
aws credentials-chain `.html/`, aws SES SendEmail `.html/`, spring-graphql 1.3
request-execution). 넷 모두 `docs/design`·`docs/reviews` 안에 있고, 기록 본문은
고치지 않는다.

고른 방법: 저장소 루트에 `.lycheeignore`를 두고 그 네 URL만 `^…$`로 묶은 정규식으로
뺀다. lychee는 실행 위치의 `.lycheeignore`를 읽으므로 workflow를 고치지 않아도 된다.
`scripts/check-repo-layout.py` 허용 목록에 이 파일을 더한다.

버린 대안:
- `lychee.toml`의 `exclude_path`로 기록 폴더를 통째로 빼기. 기록 안 상대 링크까지 검사에서
  빠진다.
- workflow에 `--exclude` 인자 더하기. workflow는 CI 재편 작업이 고친다.

위험·한계: 같은 URL을 살아 있는 문서가 쓰면 거기서도 검사하지 않는다. 끝의 `/`가 없는
aws 두 URL은 살아 있어 빼지 않았다.

검증: `python3 scripts/check-repo-layout.py` rc=0. 정규식이 네 URL에만 맞고 `/` 없는
aws 두 URL에는 맞지 않는 것을 Python `re`로 확인했다.
2026-11-07 17:18:18 +09:00
DongHyeonka 12d3f39893 docs(manual): 생성 명령 왕복 검사의 leaf 개수 대신 이름을 쓴다
문제: `docs/manual/01-generator.md`가 「./gradlew 5 leaf check」로 leaf 개수를 복사해
숫자 검사 예외에 있다.

고른 방법: `scripts/verify-feature-scaffold.sh`가 실제로 돌리는 leaf 이름(domain-core,
application-core, identifier, web, app-bootstrap)을 쓴다.

검증: `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:18:18 +09:00
DongHyeonka b3121a8626 docs(work): --rerun 예시를 실제 Gradle 경로로 쓴다
문제: `docs/work/operate.md`의 `--rerun` 예시가 `:a:test`·`:b:test`라 registry에 없는
Gradle 경로로 참조 검사 예외에 있다.

고른 방법: 실제 leaf `:domain-core:test`·`:application-core:test`로 바꾼다. 뜻은 같다.

검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0.
2026-11-07 17:18:18 +09:00
DongHyeonka 5a8414a371 docs(agents): 지운 build-tools 경로 대신 제거 표를 가리킨다
문제: `AGENTS.md`가 지운 `src/build-tools/`를 인라인 코드 경로로 적어 참조 검사 예외에
남아 있다.

고른 방법: 경로 대신 이름 `build-tools`와 그 삭제를 적은 `docs/capability-status.md`
「제거된 코드」를 가리킨다. 그 표에 이미 build-tools included build 삭제 행이 있다.

검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0.
2026-11-07 17:18:18 +09:00
DongHyeonka af177de0aa docs(compose): Keycloak realm과 Redis ACL 안내를 한국어로 옮긴다
문제: `compose/keycloak/README.md`와 `compose/redis/acl/README.md`가 영어라 언어 검사
예외에 있다. ACL README의 파일 표에는 폴더에 있는 `sentinel-accounts.acl`이 없다.

고른 방법: 뜻을 그대로 옮긴다. 긴 문단은 목록으로 나눈다. 파일 표에
`sentinel-accounts.acl` 행을 더하고, 지금 이 파일을 `aclfile`로 읽는 compose 파일이
없다고 적는다(`git grep sentinel-accounts`가 이 README 밖에서 0건).

위험·한계: `sentinel-accounts.acl`을 지울지는 정하지 않았다.

검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움).
2026-11-07 17:18:18 +09:00