패키지 dev.caskeleton.grpc와 proto 조직 이름 caskeleton은 백엔드 템플릿의
자리표시 이름이다. 템플릿 재사용 체크리스트는 파생 서비스에게
dev.caskeleton을 자기 패키지로 바꾸라고 한다. 라이브러리 패키지가 같은
이름이면 그 일괄 바꾸기가 라이브러리 import까지 바꿔 클래스를 못 찾게
된다. Maven group(com.hyeonworks.grpc)과 패키지가 다른 말을 하는 것도
같은 문제다.
첫 배포(1.0.0) 전에 한 번 바꾼다(설계 Q4 NS3). 지금 이 패키지를 쓰는
소비자는 템플릿에도 파생 서비스에도 없다.
- Java: dev.caskeleton.grpc → com.hyeonworks.grpc(폴더도 옮김)
- proto: package caskeleton.grpc.common.v1 → hyeonworks.grpc.common.v1,
생성 Java 패키지 → hyeonworks.grpc.common.v1.generated. 손으로 쓴
com.hyeonworks와 겹치지 않는다는 기존 규칙(생성 코드 시험)을 그대로
지킨다. proto 폴더도 Buf PACKAGE_DIRECTORY_MATCH에 맞게 옮겼다.
- 테스트의 가짜 서비스 이름 caskeleton.document.v1 등도 hyeonworks로.
두 이름의 글자 수가 같아 길이·한도 시험에 영향이 없다.
- SpotBugs 제외 목록의 클래스 이름, AutoConfiguration.imports.
만든 법: git mv로 폴더를 옮기고, grpc·grpc-advanced·config의 추적
파일에서 dev.caskeleton → com.hyeonworks, caskeleton → hyeonworks를
바꾼 뒤 spotlessApply로 import 순서만 다시 맞췄다. build-logic(배포하지
않는 빌드 도구)과 결정 기록 본문은 바꾸지 않았다.
위험: proto 패키지는 wire 이름이다. 지금 쓰는 곳이 없어 깨질 상대가
없지만, 이 커밋 앞의 schema와 buf breaking으로 비교하면 깨짐으로 나온다.
1.0.0 전 한 번의 변경으로 받아들인다.
검증(desktop): spotlessApply rc=0. ci·mainCheck·releaseRehearsal은 이
커밋 위 트리에서 돌렸다(다음 커밋들 본문).
BREAKING CHANGE: Java 패키지 dev.caskeleton.grpc.* → com.hyeonworks.grpc.*,
proto 패키지 caskeleton.grpc.common.v1 → hyeonworks.grpc.common.v1. import와
proto import를 새 이름으로 바꾼다.
Refs: design-docs repo-structure/05-library-repos.md 6.3절 NS3
옮겨 온 gRPC 모듈은 템플릿의 두 번째 빌드(optional build)였다. 그 빌드는
템플릿 build-logic·카탈로그·registry·config를 상대 경로로 읽었고,
grpc-operation-ledger-jpa는 템플릿 persistence-jpa의 testFixtures 파일
셋을 빌드 때 복사해 왔다. 별도 repo에는 그 경로가 없다.
repo 루트를 Gradle 루트로 둔다.
- build-logic: 템플릿 22df3525의 src/build-logic을 복사하고 쓰지 않는
플러그인(bootrun-dotenv, redis topology, config contract,
spring-library, optional registry, purity 태스크)을 뺐다. 출처와 고친
곳은 build-logic/UPSTREAM.md에 적었다(설계 10.3절 L1).
- registry config/architecture/modules.json: 템플릿의 optional-grpc 9행,
source_path는 Gradle 루트 기준.
- 카탈로그·config: 이 repo가 쓰는 항목만. SpotBugs 제외는 이 repo
클래스와 일반 규칙만 남겼다.
- group은 gradle.properties의 libraryGroup(com.hyeonworks.grpc)에서
읽는다. 버전은 -PreleaseVersion 말고 RELEASE_TAG(vX.Y.Z)에서도 읽고,
다른 모양의 태그는 빌드 전에 거부한다.
- 배포: 새 ca.library-publishing이 모듈마다 Maven publication(sources·
javadoc jar, versionMapping으로 해석된 버전)과 저장소 gitea·staging,
SIGNING_KEY가 있으면 PGP 서명을 단다. 루트는 SBOM artifact
grpc-library와 단계 태스크 ci·mainCheck·releaseCheck·release·
releaseRehearsal을 가진다. Trivy·Buf는 scripts/tool.sh가 SHA-256으로
고정해 받는다.
- testFixtures 결합(설계 4.6절 2번)은 integrationTest 안 사본으로 끊었다.
- Buf lint·breaking은 Gradle 태스크(scripts/buf.sh)로 ci에 넣었다.
버린 대안: build-logic을 템플릿이 배포(L2, 순환), 공통 repo(L3, repo가
하나 더), 표준 플러그인만으로 새로 쓰기(L4, strict lane과 방향 검사를
잃음). SBOM은 CycloneDX Gradle 플러그인 대신 이미 고정해 쓰는 Trivy로
만든다(도구를 늘리지 않는다).
위험: strictlane 단계 검사는 included build 태스크를 따라가다 실패해서
그 태스크를 건너뛰게 고쳤다(UPSTREAM.md). Gitea에 실제로 올리는 경로는
비밀 값이 없어 이 커밋에서는 시험하지 못했다.
검증(desktop, 이 트리): ./gradlew ci rc=0, 테스트 739개(build-logic
포함) 중 첫 실행 실패 1개(템플릿 경로를 찾던 GrpcPackageOwnershipTest)를
고친 뒤 통과. ./gradlew verifyStrictLaneStages --dry-run rc=0.
Refs: design-docs repo-structure/05-library-repos.md 4.6·7·10절
문제: 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개 실행.
문제: 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초.
문제: 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초.
문제: Boot 4.0.8 BOM이 고르는 버전에 trivy HIGH·CRITICAL이 있다.
- tomcat-embed-core 11.0.24: CRITICAL 4건. CVE-2026-65182(보안 제약 우회),
CVE-2026-65637(HTTP/2 SNI 검사 우회), CVE-2026-65905(DIGEST 인증 재전송),
CVE-2026-68525(FORM 인증 우회). 11.0.25에서 고쳤다.
- jackson 2.21.5(core·databind): HIGH CVE-2026-89407·89425·68497·91776·91777.
2.21.7에서 고쳤다.
- jackson 3.1.5(core·databind): 같은 CVE 다섯. 3.1.7에서 고쳤다.
이 셋이 trivy 37건 중 15건이다.
고친 방법: Boot 패치 4.0.9 하나로 올린다. 4.0.9 BOM은 tomcat 11.0.27,
jackson-bom 2.21.7·3.1.7을 고른다. Spring이 함께 시험한 묶음을 그대로 받는다.
- 버린 대안: `tomcat.version`·`jackson-2-bom.version`·`jackson-bom.version`
BOM 속성 override. Boot가 고른 짝과 어긋나고, 지울 조건을 세 곳에 둬야 한다.
- 버린 대안: Boot 4.1.x. 마이너 업그레이드다(Kafka 4.2, httpclient5 5.6 등이
같이 바뀐다).
카탈로그 주석의 「Spring Boot 4.0.8's own plugin」도 4.0.9로 고쳤다. 4.0.9의
플러그인도 dependency-management 1.1.7을 가져온다.
같이 바뀐 것(모두 4.0.9 BOM 안의 패치): Spring Framework 7.0.9→7.0.10,
Security 7.0.7→7.0.8, Data 4.0.7→4.0.8(Mongo 5.0.7→5.0.8), Integration
7.0.6→7.0.7, GraphQL 2.0.5→2.0.6, graphql-java 25.0→25.1, Hibernate
7.2.24→7.2.25, Hibernate Validator 9.0.1→9.0.2, Netty 4.2.17→4.2.19, Jetty
12.1.12→12.1.14, Micrometer 1.16.7→1.16.8, Reactor 3.8.7→3.8.8, slf4j
2.0.18→2.0.20, PostgreSQL JDBC 42.7.13→42.7.14. lockfile 65개.
위험·한계: 위 라이브러리의 패치 범위 동작 변화는 받는다. commons-lang3
override(3.20.0)는 4.0.9도 3.19.0을 관리하므로 그대로 둔다. 문서에 적힌
「Spring Boot 4.0.8」은 이 커밋에서 고치지 않는다(check-docs 예외 목록에 얼어
있다). build-logic 테스트 fixture의 4.0.8은 그 테스트가 스스로 만드는
카탈로그 값이다.
검증(desktop, 이 트리 2d387179):
- 세 빌드(주, optional, build-logic)를 `--write-locks`로 다시 쓴 뒤 lockfile을
(좌표, 구성) 쌍으로 비교: 위 버전만 바뀌었고 새로 생기거나 사라진 구성 0.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 2초,
태스크 752(executed 589, from cache 106, up-to-date 57).
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0, 1분 7초.
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
→ 경로를 고침. 두 번째 rc=1: messaging-policy
MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
(2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
--dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
:adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.