커밋된 인증 manifest의 네 줄이 gitCommit으로 템플릿 커밋
8d69e599(2026-11-07)를 가리킨다. 그 SHA는 이 repo에 없다. 증거가
어느 소스 트리에서 나왔는지 이 repo 안에서 따라갈 수 없다.
desktop에서 이 repo main dd19478을 그대로 두고 인증 lane을 다시
돌려(-PcertificationCommit=dd19478…, --rerun-tasks) 만든 manifest로
덮었다. 시나리오 넷, 결과, broker 이미지 digest는 그대로이고
gitCommit·observedAt만 바뀌었다. 게이트는 그 두 칸을 빼고 비교하므로
판정은 같다.
검증: desktop
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence
-PcertificationCommit=dd19478… --rerun-tasks rc=0
(로그 ~/x3-messaging-library-logs/12-cert-provenance.log).
Refs: design-docs repo-structure/05-library-repos.md 4.2절
템플릿 재사용 체크리스트는 파생 서비스에게 dev.caskeleton 패키지를
자기 이름으로 바꾸라고 한다. 라이브러리 패키지가 dev.caskeleton.messaging
그대로면, 체크리스트를 따르는 서비스가 import까지 바꿔 라이브러리
클래스를 찾지 못한다. Maven group(dev.cakit.messaging)과 패키지가 다른
말을 하는 것도 첫 배포 뒤에는 고칠 수 없다.
첫 배포(1.0.0) 전에 한 번 바꾼다(설계 NS3, 이름은 소유자 2026-11-08
결정 dev.cakit). 기계적으로 만들었다: 소스 폴더 dev/caskeleton/messaging
44곳을 git mv로 dev/cakit/messaging으로, 파일 411개의
dev.caskeleton.messaging·dev/caskeleton/messaging 문자열을
dev.cakit.messaging·dev/cakit/messaging으로 바꿨다. Kafka 클라이언트
설정 키 caskeleton.messaging.credential.{registry,id}(이 라이브러리
안에서만 쓰는 상수)도 cakit.messaging.credential.*로 바꿨다.
SpotBugs 제외 목록에서 템플릿 타입(@RequiresPermission) 줄을 뺐다.
위험: 지금 쓰는 소비자는 템플릿 하나이고, 템플릿은 1.0.0을 받는
변경에서 import를 함께 바꾼다. 배포한 버전이 없으니 깨질 다른 소비자는
없다.
검증: 남은 caskeleton 문자열은 build-logic 패키지(배포하지 않는 빌드
도구)뿐이다(git grep -i caskeleton).
BREAKING CHANGE: dev.caskeleton.messaging.* 타입이 dev.cakit.messaging.*로
옮겨졌다. import 접두사를 바꾸면 된다. Kafka 설정 키
caskeleton.messaging.credential.*은 cakit.messaging.credential.*이다.
Refs: design-docs repo-structure/05-library-repos.md 6.3절, 15절 변경(2026-11-08)
옮겨 온 메시징 19개 모듈은 템플릿의 src/settings.gradle·build-logic·
카탈로그·registry에 기대고 있어 이 repo만으로는 빌드되지 않는다.
repo 루트를 Gradle 루트로 하는 단독 빌드를 만든다.
- build-logic/: grpc-library main 2e880c7의 줄인 사본(템플릿
22df3525에서 복사, 템플릿 2959eff0까지의 변경도 같은 내용)에서
gRPC BOM 규칙(ca.grpc-platform-module)만 뺐다. 배포 플러그인
ca.library-publishing과 서명 키 해석(SigningKeys)은 그대로다.
출처·뺀 것·고친 것은 build-logic/UPSTREAM.md.
- settings.gradle·build.gradle·gradle.properties: group
dev.cakit.messaging, 단계 태스크 ci·mainCheck·releaseCheck와
배포(release·releaseRehearsal·verifySigningKey)는 grpc-library와
같은 모양이다. 메시징만 다른 점: Buf가 없고, 성능 lane이 없고,
mainCheck와 releaseCheck가 브로커 인증 증거 게이트
(verifyMessagingCertificationEvidence)를 부른다. 템플릿은 이 게이트를
따로 messaging-certification.yml로 돌렸다. 그 workflow는 지운다.
- config/: registry 19행(source_path만 messaging/<leaf>로), 메시징
클래스만 남긴 SpotBugs 제외 목록, 이미지 셋(postgres-16, kafka,
toxiproxy, 모두 digest 고정), checkstyle 사본.
- gradle/libs.versions.toml: 메시징이 쓰는 항목만(avro, cloudevents,
protobuf 4.33.2, toxiproxy, jmh)과 kafka-clients가 끌고 오는 취약
버전을 덮는 pinned-lz4-java·pinned-snappy-java.
- 저장소 계약 테스트: MessagingPublicSurfaceContractTest(템플릿
app-bootstrap에서 이력째 옮김)와 새 MessagingSettingsOwnerContractTest
(app.messaging 주인은 starter 하나)를 messaging-testkit의
repositoryContractTest lane에 둔다. check에 들어가 PR 단계에서 돈다.
- messaging-kafka: 인증 manifest 경로를 새 배치로 고친다.
버린 대안: 계약 테스트를 build-logic 테스트로 두는 안. 빌드 플러그인
시험과 모듈 계약이 섞이고, 소스·build.gradle을 입력으로 선언하는
기존 lane 장치를 쓸 수 없다.
위험: 이 커밋 단독으로는 lockfile을 다시 쓰지 않았다(뒤 커밋에서
desktop에서 쓴다). 패키지는 아직 dev.caskeleton.messaging이다.
검증: desktop ./gradlew projects rc=0(19개 모듈 포함).
Refs: design-docs repo-structure/05-library-repos.md 4·10.3·13.1절
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).
- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.
위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.
검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.
BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
문제: :messaging:messaging-kafka:verifyMessagingCertificationEvidence가
rc=1이다. 커밋된 증거 broker-certification-evidence.jsonl(2026-08-24)의
brokerImage는 apache/kafka:4.1.0인데, 2026-11-03 container-images.properties
가 kafka 이미지를 digest로 고정한 뒤 레인은
apache/kafka@sha256:bff074a5…로 돈다. 시나리오 넷의 결과는 같고 이미지
이름만 다르다. 이 workflow는 messaging 경로가 바뀔 때만 PR에서 돌아
그동안 드러나지 않았다.
고른 방법: 게이트가 안내하는 대로 이번 실행이 만든 jsonl로 커밋된
파일을 바꾼다(증거는 실행 기록이다). 손으로 이미지 이름만 고치지
않는다.
위험·한계: gitCommit 칸은 레인을 돌린 트리의 커밋(c9733223, 이 파일만 다르다)을
가리킨다. 레인은 실 Kafka 컨테이너와 Toxiproxy가 있는 곳에서만 돈다.
검증(desktop, ~/t1-layout-logs/):
- 고치기 전(트리 2b3354a4): verifyMessagingCertificationEvidence rc=1.
claimed/produced 차이는 brokerImage(apache/kafka:4.1.0 ↔
apache/kafka@sha256:bff074a5…)뿐이고 시나리오·결과·testId는 같다
- 고친 뒤(트리 4b304c59): :messaging:messaging-kafka:verifyMessagingCertificationEvidence
-PcertificationCommit=c9733223… :messaging:messaging-testkit:check
:messaging:messaging-kafka:check rc=0 (messagingCertificationTest 실행)
문제: 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.
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.
방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.
위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).
검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
한 커밋인 이유: src/build.gradle 안에서 ca.testkit-publisher 플러그인 제거와
게이트 수정이 얽혀 있다. 플러그인 적용부만 빼면 web·websocket·persistence-jpa·
persistence-mongo·app-bootstrap 이 사라진 testkitPublisher() 와 *Testkit
컨피규레이션을 계속 참조해 설정 단계에서 빌드가 죽는다. 파일 단위로 나눌 수 없다.
1) testkit 소스셋 → Gradle 표준 java-test-fixtures 이관
web, websocket, persistence-jpa, persistence-mongo, httpclient, graphql 과
이들의 testkit 컨피규레이션을 소비하던 app-bootstrap.
자체 제작 ca.testkit-publisher.gradle 77줄이 사라진다.
2) 실행되지 않거나 실패할 수 없던 빌드 게이트 정상화 (E등급)
- strict-test-lane 의 실행 카운터가 skip 을 실행으로 세던 것 수정.
전부 skip 인 레인은 이제 실패한다 (회귀 테스트 2건 추가)
- public-path 스냅샷이 gitignore 된 src/.env 를 읽던 것을
config/security.yml 의 바인딩 기본값으로 교체
- verifyEnvKeys 가 build/ 산출물을 소스로 읽어 삭제된 키를 사용 중으로
오판하던 것 수정 (입력 4,637 → 4,630 파일)
- jpa-evidence 가 git 실패를 "워크트리 깨끗함"으로 읽던 것을 fail-closed 로
- notification-evidence 의 Grade 열 탐지를 헤더 기준으로 교체 +
표 부재 시 fail-closed
- spring70CompatibilityTest 가 레인을 복제하며 잃은 fail-closed 복구
(태스크명 유지 — 워크플로 3곳과 gate-matrix 린트 무손상)
- 메시징 R2 스켈레톤 주변의 도달 불가 검증 45줄을 MSG-015 명시적 실패로 교체
3) git 에 없던 빌드 필수 파일 추적
- src/gradle/libs.versions.toml — src/build.gradle 이 9곳에서 참조하는데
추적되지 않아 깨끗한 체크아웃에서 설정이 실패했다
- app-bootstrap config/*.yml 15개 — application.yml 이 전부 import 한다.
하드코딩된 시크릿은 없고 값은 secret://environment/APP_* 참조다
4) 진행 중이던 구현 작업 반영 (redis/idempotency 구성, startup 검증,
아키텍처 테스트 클래스, notification 콜백 레지스트리 등)
검증:
- 깨끗한 체크아웃에서 ./gradlew help 통과
- :app-bootstrap:test --tests 'dev.caskeleton.bootstrap.architecture.*'
→ 20개 클래스 174 tests, 실패 0, 스킵 0 (이전에는 0개 실행)
미해결: verifyOneTypePerFile 은 손대지 않았다(Checkstyle 로 교체 권고).
B/C/D 등급 100여 건과 CI 단계 분리는 별도 작업 —
docs/superpowers/plans/2026-09-16-ci-stage-separation.md 참고.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>