문제: 기본 compose.yaml은 -XX:HeapDumpPath=/var/tmp/heap을 512m tmpfs로
붙였다. 컨테이너는 mem_limit 512m·swap 없음이고 힙은 그 75%(384m)다.
tmpfs에 쓴 페이지는 같은 컨테이너 메모리 한계에 잡힌다. 그래서
OutOfMemoryError 때 덤프를 쓰는 동안 컨테이너가 OOM kill(137)될 수 있었고,
runbook이 기대하는 깨끗한 끝(코드 3, ExitOnOutOfMemoryError)이 사라졌다.
덤프가 끝까지 써져도 tmpfs는 컨테이너가 끝나면 함께 사라져 읽을 수 없었다.
Dockerfile 주석은 오케스트레이터에 그 경로를 tmpfs로 붙이라고 했고,
internal-error-spike runbook은 없는 파일 이름(heapdump-<pid>.hprof)을 적었다.
고른 방법:
- 기본 compose.yaml은 그 경로에 아무것도 붙이지 않는다. 루트가 읽기
전용이라 JVM은 파일을 만들지 못하고 바로 코드 3으로 끝난다. 덤프를 남기는
dev lane(named volume heap-dumps)은 그대로다.
- scripts/verify-compose-profile-contracts.sh(prCheck의
verifyComposeProfiles)가 모든 lane에서 그 경로의 tmpfs를 거절한다. 경로는
Dockerfile의 -XX:HeapDumpPath에서 읽는다.
- Dockerfile 주석과 runbook 둘(runtime-jvm-oom 「진단」, internal-error-spike)에
덤프를 남기는 법(Kubernetes emptyDir without medium: Memory·PV, dev lane
volume)과 실제 파일 이름(java_pid<pid>.hprof)을 적었다.
- 버린 대안: 기본 compose에 named volume을 붙이기 — 기본 조립은 디스크에
아무것도 남기지 않는다는 결정(compose.yaml 「No volume」 주석)과 다르다.
- 고치며 찾은 것(RR9-03-30): ComposeMergeCharacterizationTest는 어느 lane에서도
돌지 않았다. integrationTest lane은 requires로 적은 클래스 넷만 고른다
(StrictTestLanePlugin). 그 시험이 보던 기본·dev 조합 렌더링과 계약 스크립트는
verifyComposeProfiles가 18개 lane으로 이미 본다. 시험과, 그 lane에 compose
파일을 입력으로 선언하던 블록을 지웠다.
검증(desktop):
- RED: 기준 ca1fbfde + 검사 스크립트만으로 :verifyComposeProfiles 실패
(기본 compose를 쓰는 lane마다 「heap dump path ... as a tmpfs」).
- 탐침(eclipse-temurin:21-jdk, 읽기 전용 루트, 메모리 192m·swap 없음,
-Xmx96m으로 OutOfMemoryError):
경로에 아무것도 없음 → "Unable to create /var/tmp/heap: Read-only file
system", 코드 3. tmpfs → 덤프를 쓰다 코드 137(OOM kill). 디스크 마운트 →
덤프 101MB가 남고 코드 3.
- GREEN: :verifyComposeProfiles(18 lane), :app-bootstrap:integrationTest,
repositoryContractTest, spotlessCheck — 71건 실패 0, skip 1, rc=0.
문제: 공개 경로 스냅숏(publicPathSnapshotTest)은 config/security.yml의
기본값 한 줄만 읽었다. 문서(docs/build.md, gates.md 「공개 경로·보안 체인」)는
보안 체인 전체를 지킨다고 했다. 그래서 둘이 검사를 지나갔다.
- application-local.yml이 public-paths를 /api/healthcheck로 덮는다.
- web-notification의 callback chain이 /internal/notification/callbacks/**를
anyRequest().permitAll()로 연다. actuator chain의 health·info·prometheus도
같다.
docs/build.md는 지운 PublicPathSnapshotPlugin.java와 없는
updatePublicPathSnapshot 태스크를 승인 방법으로 적었다.
관리 포트도 문서와 compose가 갈렸다. 관리 포트가 컨테이너 loopback에 묶인
뒤(MANAGEMENT_SERVER_ADDRESS 기본 127.0.0.1) compose.yaml·dev lane의
127.0.0.1:9001 publish는 아무것도 답하지 않는 줄이 됐고, service-runtime
README·Dockerfile은 Kubernetes 프로브가 닿는다고 적었다. dev lane은 원격
JMX(9999)를 인증·TLS 없이, jmxremote.host 없이 열었다(주석은 「localhost
only」).
고른 방법:
- 스냅숏에 두 절을 더한다. profile 파일이 public-paths를 리터럴로 덮으면
그 값, 모든 leaf 운영 코드에서 Spring Security를 import한 파일의
permitAll·securityMatcher 문장(파일 경로와 함께, 정렬). 그 소스와 baseline을
lane 입력으로 선언해 캐시가 변경을 놓치지 않게 했다.
- 기동한 SecurityFilterChain의 matcher를 reflection으로 읽는 안은 버렸다.
matcher가 Spring의 private 필드에 있어 버전마다 깨진다. 문장 글자만 보므로
상수로 만든 matcher의 값은 못 본다. 그 한계를 docs/build.md에 적었다.
- 관리 포트 publish 줄과 dev lane JMX를 지웠다. 컨테이너 안에서 읽는 명령
(docker compose exec app wget …, jcmd)을 주석에 적었다. Kubernetes는
MANAGEMENT_SERVER_ADDRESS를 바꾸거나 sidecar로 읽어야 한다고
service-runtime README·Dockerfile·docs/build.md에 적었다.
위험·한계: 파생 서비스가 자기 chain이나 profile 덮어쓰기를 두었다면 merge 뒤
스냅숏이 실패한다. 읽고 승인하면 된다(upgrade 안내 1). dev lane에서 원격
JMX로 보던 사람은 jcmd로 바꾼다(안내 4).
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10에 permitAll chain을 더한 탐침 트리에서 기존
publicPathSnapshotTest가 통과했다(rc=0) — 틈이 있다.
- GREEN: spotlessApply 뒤 :app-bootstrap:test --tests '*PublicPathSnapshotTest'
(새 렌더링 시험 둘), :app-bootstrap:publicPathSnapshotTest,
repositoryContractTest, spotlessCheck, :verifyComposeProfiles(18 lane) —
67건 실패 0, skip 1, rc=0.
- 변이: 새 스냅숏을 커밋한 트리에서 callback chain의 securityMatcher를
"/internal/**"로 넓히면 publicPathSnapshotTest가 실패한다.
BREAKING CHANGE: 공개 경로 스냅숏이 profile 덮어쓰기와 모든 모듈의
permitAll·securityMatcher 문장을 본다. compose가 관리 포트 9001과 dev lane
JMX 9999를 publish하지 않는다. 할 일은
docs/upgrade/2026-11-round9-public-surface.md.
문제: 모듈 README·AGENTS·매뉴얼·Javadoc이 옮기거나 이름을 바꾼 타입,
지운 샘플, 다른 repo로 옮긴 플랫폼을 그대로 가리켰다.
- 옮기거나 바꾼 타입: OutboxConfig(지금 :composition:outbox-relay의
OutboxRelayAutoConfiguration), IdempotencyProviderSelectionConfig(지금
:composition:idempotency의 IdempotencyAutoConfiguration),
TracingProperties·GraphQlPlatformProperties(지금 *Settings), SecretSource
(지금 application-core SecretSourcePort), JsonNullableModule(지금
JsonNullableJackson3Module), PeriodTest·OutboxEventIdFactory(샘플과 함께
지움).
- 지운 샘플: SampleDemoProfilesStartupSystemTest, 「sample 테스트」,
IdempotencyAutoConfiguration·ManagementSecurityConfig Javadoc의 샘플.
- 옮긴 플랫폼: graphql AGENTS·README가 messaging 플랫폼과 「두 패턴 공존」을
적었지만 그 플랫폼은 2026-11-08 messaging-library로 옮겼다. gRPC 문서는
grpc-library로 옮긴 플랫폼을 「vendored」·「벤더 starter」로 불렀다.
- leaf CLAUDE.md를 가리키던 곳(지금 AGENTS.md), 복사한 숫자(httpclient
java 파일 수, graphql systemTest 수), manual 06의 registry 머리말 옛 영어 인용.
고른 방법: 문장이 가리키는 대상만 지금 이름으로 바꾼다. 동작 설명은 그대로
둔다. 숫자는 지운다(레지스트리·빌드가 정한다).
검증:
- 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄
때문에만 rc=1.
- desktop(--no-build-cache, 트리 310eb524): 이 문서들을 읽는 시험
(:app-bootstrap:documentContractTest, repositoryContractTest —
DeveloperExperienceContractTest 포함, MongoNamespaceContractTest,
AwsQualificationClaimHonestyTest)과 Javadoc을 고친 두 leaf의
compileJava·spotlessCheck. 134건 실패 0, skip 1.
문제: inbound messaging의 IdempotentConsumer.TransactionRunner는
new TransactionTemplate(transactionManager)를 상한 없이 썼다. handler의
유스케이스가 부르는 TransactionPort.inWrite는 이 트랜잭션에 합류하고, 합류한
쓰기는 자기 상한(app.persistence-jpa.transaction.write-timeout 30s)을 걸지
않는다. 그래서 막힌 문장이나 잠금 대기가 연결과 partition을 그 시간 내내
쥐었다. docs/work/reference/decisions.md 2.5 JPA 기본값
「트랜잭션 제한 30초」와 다르다.
고른 방법: TransactionTemplate에 쓰기와 같은 30초를 건다. 값은 상수 하나
(TRANSACTION_TIMEOUT_SECONDS)이고, 설정 키는 더하지 않았다 — 쓰기 상한과
따로 움직일 이유가 아직 없고, 키를 더하면 env 계약도 늘어난다.
버린 대안: 쓰기 상한 설정(write-timeout)을 읽어 쓰기 — 이 leaf가
persistence-jpa 설정에 기대게 되어 registry edge가 생긴다.
위험·한계: 30초를 넘기던 handler는 이제 롤백되고 재전달된다. 그런
handler는 원래 쓰기 상한도 넘긴 것이다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 시험만으로
MessagingInboxAutoConfigurationTest 8건 중 새 시험 1건 실패(상한이 걸리지 않음).
- GREEN: :adapter:inbound:messaging:check rc=0.
grpc README는 "전용 APP_* 키는 registry에 없다"고 했지만 끄는 값
APP_GRPC_SERVER_ENABLED가 있고, 기동에 꼭 두라는
APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL은 registry에 없었다(앞 커밋이 등록).
cache-redis README는 운영 비밀로 읽는 곳 없는 폐기 키 셋
(APP_CACHE_REDIS_PASSWORD, APP_IDEMPOTENCY_/LEASE_REDIS_KEY_HMAC_SECRET)을
넣으라고 했다. 자격 증명은 APP_REDIS_AUTHENTICATION_*의 secret 참조다.
검증: python3 scripts/check-docs.py rc=0.
문제: 저장소 전체 ArchUnit suite가 약속한 것을 막지 못하는 길이 다섯이다.
1. controller가 domain repository 포트(생성 명령이 aggregate 옆
dev.caskeleton.domain.<feature>에 두는 <Aggregate>Repository)를 주입해도
걸리지 않는다. 규칙은 ..repository.. 패키지와 Spring Data·JPA 타입만 본다.
gRPC 서비스는 controller 판정에 들지 않는다(HARD-STOP 2).
2. ..adapter.inbound.. 밖의 사용자 전송(조립 모듈의 controller 등)이
@SystemInvoked 유스케이스를 new로 만들어 부르거나, 표시 없는 중간 클래스를
거쳐 부르면 통과한다. 매뉴얼 07은 이것을 "빌드 실패"라고 약속한다. app
AGENTS의 "bootstrap에 controller 금지"도 검사가 없다.
3. web 패키지 밖에 둔 Spring Security 요청 경로 확장점(JWT converter,
AuthorizationManager, AuthenticationProvider, 필터 chain DSL)은 servlet 타입을
쓰지 않아 사용자 전송으로 보이지 않는다.
4. 설정이 interceptor를 자기 클래스 타입 필드로 쥐고
registration.interceptors(x)로 넘기면, ArchUnit 1.3은 ChannelRegistration
(설정용 타입)만 기록해 설정이 사용자 전송이 되지 않는다.
5. capabilityProjects에 :adapter:inbound:messaging이 없어 저장소 전체 suite가
MessagingInboxAutoConfiguration을 읽지 않는다("suite가 모든 모듈을 본다"는
주석과 다름).
고른 방법:
1. ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS: controller와 gRPC 서비스는
..domain..·..application..의 *Repository·*StorePort·*QueryPort에 의존하지
않는다.
2. CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS, 그리고
USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS의 전이 대상에 @SystemInvoked
유스케이스 자신을 더한다.
3. org.springframework.security.web·config.annotation.web·
oauth2.server.resource·oauth2.jwt 패키지와 AuthenticationProvider·
AuthorizationManager를 사용자 전송·요청 처리기 목록에 더한다.
4. 설정이 의존하는 프로젝트 클래스가 요청 처리기 타입을 상속·구현하면 그
설정도 사용자 전송으로 본다.
5. capabilityProjects와 주석 처리된 runtimeOnly 줄에 inbound messaging을 더한다.
매뉴얼 07 표와 app AGENTS를 같이 고쳤다. 지금 운영 코드에 걸리는 곳은
없다(inbound가 그런 포트를 import한 곳 0, 조립 모듈 controller 0).
버린 대안: inbound가 application *Port 전부를 못 쓰게 하기 — web이
AuthorizationPort·CorrelationIdPort를 구현하고 쓰므로 맞는 코드가 걸린다.
IdFactory는 지금 DurableOperationController가 쓰고 있어 이번 규칙에서 뺐다
(그 controller의 id 생성은 리뷰 RR9-05-13로 따로 고친다).
위험·한계: 규칙 3·4는 목록·클래스 의존 방식이라, 목록에 없는 보안 타입이나
타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히
못 본다(매뉴얼 07 「규칙이 못 보는 길」). gRPC 서비스 fixture는 io.grpc가
architectureTest 컴파일 classpath에 없어 두지 않았다 — 판정은
BindableService 이름으로 한다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 새 fixture와 시험(새 규칙 대신 기존 규칙을 부르는
변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반
모두 기존 규칙에 안 걸림. 허용 시험은 통과.
- GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음),
spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0,
:app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck,
:verifyDependencyLocks, :architectureCheck rc=0. 로그 desktop
~/r9-be-logs/b14-{red,green2}.log.
Refs: docs/reviews/2026-11-12-round9-review RR9-05-01~05
round9 확인 리뷰가 CI 파일의 설명이 실제와 다른 곳을 짚었다.
- verify.sh 머리 표: PR 단계 job 이름이 `gradle`이다. 실제는 `done`.
- build.gradle: JMH가 「세 leaf」에 있다고 하지만 지금은 플러그인을
쓰는 leaf가 정한다. verifyFeatureScaffold는 「leaf 다섯 중첩
빌드」라고 하지만 그 안의 architectureCheck가 모든 leaf의
architecture lane을 부른다.
- release.yml: `release` job 주석은 「ci를 다시 돌리지 않는다」인데
뒤의 job들은 ci가 이미 돈 시험 일부를 다시 돈다. 그 이유(문서가
job id로 부르는 릴리스 증거이고, 이미지 job이 모두를 needs로 받아
같은 run·같은 커밋에서 통과한 뒤 publish한다)를 적었다. job은 그대로다.
- gates.md 2절: redis-topology 줄을 desktop에서 그대로 돌리라고 하지만
스크립트 안 ./gradlew는 daemon을 남긴다. desktop에서는
GRADLE_OPTS=-Dorg.gradle.daemon=false를 붙이라고 적었다. 스크립트에
--no-daemon을 넣지 않은 이유: CI는 한 job의 step 11개가 daemon을
다시 쓴다.
- redis-sdk compose README: cache-redis 칸에 필수 클래스가 둘뿐이다.
build.gradle의 standalone·cluster 목록 다섯으로 맞췄다.
- template-vs-consumer.md: object-storage-aws를 nightly job으로 적었다.
실제는 손으로 실행하고 입력 run_protected_aws를 켤 때만 돈다. 최상위
항목을 더하면 「AGENTS.md 지도를 함께 고친다」고 했지만 지도는 루트
목록을 두지 않고 check-repo-layout.py를 가리킨다. src/ 최상위 폴더일
때만 지도의 src/ 줄을 고친다고 적었다.
동작 변경 없음: workflow는 주석만, 스크립트는 머리 주석만 바꿨다.
검증: scripts/verify.sh docs(노트북) rc=0.
Refs: round9 확인 리뷰(r9-be wave1-r4 「넘길 것」)
main.yml `links`의 lychee 범위에 `src/**/CLAUDE.md`가 있다. 폴더
지역 규칙이 같은 폴더 AGENTS.md로 옮겨 간 뒤 CLAUDE.md는
`@AGENTS.md` 한 줄이라 링크가 하나도 없다. 외부 URL이 있는
`src/**/AGENTS.md`는 범위 밖이라 그 링크가 죽어도 아무 단계도
모른다(상대 링크는 PR의 check-docs.py가 본다).
범위의 그 한 칸을 `src/**/AGENTS.md`로 바꾼다. 범위를 고정하는
DeveloperExperienceContractTest와 gates.md 2절 링크 검사 문장도 함께
바꾼다. 버린 안: 두 패턴을 다 두기 — 링크 없는 파일을 매번 읽을 뿐이다.
위험: 새로 보는 외부 링크는 messaging-kafka AGENTS.md의 Gitea 링크
하나다(코드 span 밖 URL 기준). 익명 GET이 200이라 runner에서도
통과할 것으로 본다. main push의 links job에서 확인한다.
검증: scripts/verify.sh docs(노트북) rc=0. Gradle 쪽
(DeveloperExperienceContractTest)은 PR 실행과 desktop verify.sh pr로 본다.
문제: `JpaPlatformContractSupport`의 Javadoc은 「서버를 JVM에서 공유한다」고
하지만, `start`는 부를 때마다 컨테이너를 새로 띄웠다. 클래스 42개가 저마다 띄워
desktop main 단계에서 platform 계약 lane이 컨테이너 75개(기동 181초), migration
lane이 36개(71초)를 썼다. 이 lane들은 build의 실서버 슬롯 하나 위에서 돌기 때문에,
이 기동 시간이 main job 시간에 그대로 더해졌다. release gate 셋과 nightly
행렬 셋에서도 같은 lane이 major마다 돈다.
고친 방법: Stable major마다 서버 하나를 JVM에서 처음 쓸 때 띄우고, JVM이 끝날 때
멈춘다(shutdown hook, reaper에 기대지 않는다). support마다 그 서버에 database를
하나 만들고(`create database contract_<n>`), close에서 pool을 다 닫은 뒤
지운다(`drop database ... with (force)`). 표·스키마·Flyway 이력은 database에
있어 클래스끼리 섞이지 않는다. 서버 전체에 걸리는 role은 섞이므로 Javadoc에
적었다. role을 만드는 계약은 `PostgreSqlSecurityContractTest` 하나이고, lane마다
JVM이 따로라 이름이 겹치지 않는다.
시험: 소유권 시험에 둘을 더한다. 두 번째 support가 같은 서버, 다른 database를
받는지, close가 database를 지우는지 본다. 공유를 되돌리면 앞의 것이, drop을
빼면 뒤의 것이 실패한다. close 시험의 이름은 「database를 지우기 전에 pool을
닫는다」로 고친다.
버린 대안: 컨테이너 tmpfs·fsync 끄기로 기동만 빠르게. 재시작·장애 복구 계약의
조건이 바뀐다. Testcontainers reuse: CI에서 일부러 끈 설정이다.
위험·한계: 한 클래스가 서버 설정(`ALTER SYSTEM`)을 바꾸면 같은 lane의 다음
클래스가 본다. 지금 그런 계약은 없다(검색으로 확인).
문제: nightly의 redis-topology가 행렬 job 11개였다. 행마다 job을 새로 시작해
컨테이너·checkout·JDK·Gradle 시작과 구성을 다시 치렀다. 수동 실행 run 100에서
이 11개가 runner 135분 가운데 26분이었고, 그중 약 3분의 1이 시작 비용이었다.
고른 방법: job 하나에 행마다 step 하나를 둔다. 각 step은 지금과 같은
`bash scripts/ci/redis-topology.sh <topology> <version>` 한 줄이다.
- `if: always()`로 한 행이 실패해도 나머지가 돈다. job이 빨갛게 되고, 실패한
step 이름이 행을 말한다.
- 스크립트가 끝날 때 자기 topology를 내리므로 행끼리 서버를 나누지 않는다.
- 같은 job 안에서 Gradle daemon과 구성 결과를 다시 쓴다.
- timeout은 행 11개를 합친 시간에 맞춰 90분으로 둔다.
문서: 행렬이라고 적던 곳(gates.md, template-vs-consumer.md, redis-sdk compose
README, 스크립트 머리 주석)을 step으로 고친다.
버린 대안: 버전마다 job 하나(3개). 시작 비용을 셋 더 치른다. 한 step에서
셸 반복문으로 돌기: 어느 행이 실패했는지 로그를 뒤져야 하고, 단계 job 규칙과
같은 이유로 셸 문법을 늘리지 않는다.
위험·한계: UI에서 행마다 따로 보이던 초록·빨강이 step 단위가 된다. job 하나가
시간 제한에 걸리면 남은 행이 함께 멈춘다.
검증: YAML을 읽어 step 13개(checkout, setup, 행 11)를 확인했다. runner nightly
측정은 PR 본문에 적는다.
ContractRegistrySchemaGovernanceTest(모든 레지스트리 행에 legal
compatibility_impact + non-blank required_test 강제)는 @Tag(document-contract)
라 main 스테이지에서만 돈다. PR 레인은 repository-contract이고 그 입력에
docs/**가 빠져 있어, 잘못된 env-keys가 prCheck를 통과하고 병합 뒤 mainCheck
에서야 깨졌다(BE-CONFIG-001이 그렇게 새어 나갔다). 또 필드가 아예 빠지면
Set.of(...).contains(null)이 NPE를 던져 어느 행이 문제인지 알 수 없었다.
- RegistrySchemaPullRequestGateTest(@Tag repository-contract): 같은
RegistryGovernanceCatalog.validate를 PR 레인에서 돌려 위반이 병합 전에
막히게 한다.
- app build.gradle repositoryContractInputs에 docs/registries/**를 더해
레지스트리가 바뀌면 PR 레인이 재실행된다.
- RegistryGovernanceCatalog: compatibility_impact가 null이면 "... must be one
of [...], but was null"로 또렷이 실패한다(NPE 대신). 누락-필드 음성 사례를
ContractRegistrySchemaGovernanceTest에 더했다.
- ManagementActuatorSecurityContractTest javadoc에
actuator-contract:management-address-loopback 항목을 더해 열거를 맞춘다.
버린 대안: required_test가 실제 시험을 가리키는지 범용 강제는 안 넣었다 —
env-keys의 distinct required_test 193개 중 테스트 소스에 literal로 있는 건
7개뿐이라(나머지는 문서적 식별자), 범용 강제는 기존 186행을 깨뜨린다.
위험·한계: PR 레인이 docs/registries 변경에도 재실행된다(의도).
검증(desktop, 고친 env-keys): spotlessCheck·verifyEnvKeys·build-logic test·
documentContractTest·repositoryContractTest(새 게이트)·
ManagementActuatorSecurityContractTest·web-fileserver·web-advanced 모두 rc=0.
RED 재현: 고치기 전 새 게이트가 "env-keys.yaml row MANAGEMENT_SERVER_PORT
compatibility_impact must be one of [...], but was null"로 실패.
PR #12의 액추에이터·fileserver·web-advanced 수정 커밋이 긴 주석과
assertion 메시지에 포맷 드리프트를 남겨, runner pr / gradle의
:app-bootstrap:spotlessJavaCheck가 깨졌다. 모듈 시험만 돌리고 포맷
게이트(spotlessCheck)를 건너뛴 탓이다.
./gradlew spotlessApply로 바뀐 3개 파일만 재포맷했다. 이미 push된
커밋이라 force push 금지 → squash 대신 새 커밋으로 올린다.
위험·한계: 포맷만 바뀐다(긴 줄의 줄바꿈). 동작·의미 변화 없음.
검증: spotlessCheck rc=0. 바뀐 3개 모듈 시험 재실행 —
ManagementActuatorSecurityContractTest·FileserverAdminControllerRequestBodyValidationTest·WebCodecMapperTest
BUILD SUCCESSFUL (1m8s).
문제: NegotiatedProtocolContractTest의 JDK transport 시험 둘은 공용 시험 프로필
(연결 500ms, TLS 핸드셰이크 1s)을 그대로 쓴다. 부하가 높을 때 TLS 핸드셰이크와
ALPN이 그 안에 끝나지 않아 HttpConnectTimeoutException으로 실패한다.
main push run 93(2026-11-11, spring70CompatibilityTest lane)과 desktop(부하
18~24, 2026-11-08)에서 봤다. 이 시험이 보는 것은 협상된 프로토콜이지 시간
예산이 아니다.
고른 방법: 두 시험만 넉넉한 TimeoutSettings(연결·핸드셰이크·헤더·유휴 10s,
전체 30s)를 쓴다. DNS 값은 플랫폼이 받는 유일한 값인 기본값으로 둔다. 시간
제한을 보는 다른 시험은 공용 프로필 그대로다.
위험·한계: 공용 프로필을 쓰는 다른 실서버 시험도 같은 부하에서 걸릴 수 있다.
관측된 것은 이 시험뿐이라 이것만 고쳤다.
검증: desktop mainCheck, runner main 수동 실행.
문제: nightly의 redis-topology 8.2 standalone·sentinel·cluster가 run 63에서
RedisTopologyContractTest 「admin 계정이 ADMIN_ONLY 진단을 모두 쓸 수 있다」로
실패한다. 7.2·7.4는 통과한다. 원인은 둘이다.
- 명령 정책 catalog는 search 모듈의 FT.INFO를 8.0부터 ADMIN_ONLY로 둔다.
fixture ACL의 admin 줄에는 그 권한이 없다(standalone: 거부).
- sentinel·cluster lane은 entrypoint를 덮어써 `redis-server`를 바로 실행한다.
Redis 8 이미지의 docker-entrypoint.sh가 모듈을 싣는데 그것을 건너뛰어
FT.INFO 자체가 없다(「있어야 할 서버에 없다」).
desktop에서 확인: Redis 7.2·7.4는 ACL 규칙 `+ft.info`가 있으면 시작을 거부하고,
8.2는 모듈을 실었을 때만 받는다. cluster 모드에서도 search 모듈은 실리고
FT.INFO가 생긴다.
고른 방법:
- sentinel·cluster 데이터 노드가 `exec docker-entrypoint.sh redis-server`로
standalone처럼 이미지 entrypoint를 거친다. 서버도 root가 아니라 이미지의
redis 사용자로 돈다.
- 네 구성의 ACL 마운트 원본을 `REDIS_ACL_DIR`로 바꿀 수 있게 한다(기본값은
지금 폴더). redis-topology.sh가 8 이상에서만 커밋한 ACL 파일에서 admin 줄
끝에 `+ft.info`를 더한 사본을 build/ 아래 만들어 쓴다. 실행마다 원본에서
만들어 어긋날 수 없다. ACL README에 이 예외를 적는다.
버린 대안: 버전별 ACL 파일을 하나 더 커밋하기. README가 금하는 두 번째
사본이다. catalog에서 FT.INFO를 빼기. SDK가 문서로 지원한다고 한 진단이다.
위험·한계: entrypoint를 거치며 7.x에서도 서버 사용자가 redis로 바뀐다.
/tmp의 nodes.conf와 읽기 전용 ACL 마운트는 그 사용자도 읽고 쓸 수 있다.
검증: runner redis-topology 11칸(nightly 수동 실행, 이 PR 본문에 적는다).
문제: main.yml의 `performance`는 한 번도 돌지 않았다. 수동 실행(run 63)에서는
2.5일 동안, main push(run 79)에서는 지금까지 Blocked다. Gitea API의 job
상태 `waiting`은 runner를 기다리는 것(`queued`)이 아니라 서버의 Blocked다.
Gitea 1.27은 앞 job이 끝나면 `needs`가 있는 job의 `if`를 서버에서 계산하고,
계산이 실패하면 Blocked로 둔다. 일회용 workflow 세 가지(입력 있음·없음,
concurrency 있음·없음)를 수동 실행해 보니, `needs`와 `if`를 함께 가진 job
여섯 개가 `if` 내용(`!cancelled()`, `always()`, 이벤트 이름만)과 앞 job 결과에
상관없이 모두 Blocked였다. `if`가 없는 `needs` job과 `needs`가 없는 `if` job은
제대로 풀렸다. release.yml의 `app-image-signing`도 같은 모양이라 수동 실행이
끝나지 않는다.
고른 방법:
- performance: `needs`를 지우고 파일 맨 끝에 둔다. `needs` 없는 job은 run이
시작할 때 대기열에 들어가고, capacity 1인 runner 하나는 run의 job을 만든
순서(파일 순서)대로 돈다. 조건은 `github.event_name != 'push'` 하나다.
build.gradle의 strict lane 단계 선언도 같은 조건으로 바꾼다.
- app-image-signing: job 조건을 두 step의 조건으로 옮긴다. 수동 실행에서는
job이 뜨고 step이 모두 건너뛴다. 키를 가진 job이 하나뿐이라는 시험은
그대로 두고, 조건을 보는 단언만 step으로 옮긴다.
버린 대안: performance를 별도 workflow로 빼기. workflow는 셋(pr·main·release)만
둔다는 규칙(docs/work/reference/gates.md)을 바꾸게 된다.
위험·한계: runner가 둘이 되거나 capacity가 1보다 커지면 performance가 다른
job과 겹칠 수 있다. 그래도 돌기는 한다. 원인이 Gitea 서버 쪽이라 Gitea를
올리면 다시 확인할 일이다. 수동 실행으로만 재현했고 push 실행의 원인은
같은 증상으로 판단했다.
검증: verifyStrictLaneStages --dry-run(desktop·runner PR), runner main 수동
실행에서 performance가 마지막에 도는지(이 PR 본문에 적는다).
문제: main의 links job이 run 52·63·79 모두 `lychee: unexpected argument
'--root-dir'`로 실패한다. 고정한 lychee-action v2.0.2는 lychee v0.16.1을
받는데, 그 버전에는 --root-dir이 없다. 상대 경로 --root-dir은 lychee
v0.22.0부터 읽는다.
고른 방법: action을 v2.9.0(lychee v0.24.2, 2026-07-09)의 커밋 SHA로 올린다.
Gitea의 job token은 lychee가 보낼 GitHub 쪽에서 의미가 없어 token을 비우고,
Gitea에 없는 job summary를 끈다. DeveloperExperienceContractTest가 고정한
SHA를 함께 바꾼다.
버린 대안: v2.0.2에 lycheeVersion만 새로 주기. v2.0.2의 내려받기 경로는
lychee 0.16 이전의 자산 이름을 쓴다.
위험·한계: 새 lychee가 전보다 많은 외부 링크를 깨졌다고 볼 수 있다. 그러면
링크를 고치거나 .lycheeignore에 이유와 함께 넣는다.
검증: runner main 수동 실행의 links job(이 PR 본문에 적는다).
문제: HttpResponseLossFixture.reset()은 시나리오 전에 부수 효과 카운터를
지우는 DELETE다. 이 요청이 응답을 일부러 버리는 호출용 읽기 제한(750ms)을
그대로 썼다. 부하가 높은 runner에서 평범한 reset 응답이 그보다 늦어
JettyCommitThenConnectionResetIT가 시나리오를 시작하기도 전에
SocketTimeoutException으로 실패했다(main run 24, 2026-11-08, 세 번 중 한 번).
고른 방법: 재시도와 부수 효과 조회처럼 넉넉한 HttpFixtureTimeouts.READ_MILLIS를
쓴다. 짧은 제한은 장애를 건 호출에만 남는다.
위험·한계: 시험이 보는 동작은 바뀌지 않는다. 준비 단계가 기다릴 수 있는
시간만 늘었다.
검증: desktop mainCheck(webJettyCompatTest 포함), runner main 수동 실행.
문제: MinioS3ManagedObjectProviderContractTest는 endpoint를
`https://localhost:<포트>`로 고정했다. Gitea runner의 job 컨테이너 안에서
localhost는 job 컨테이너 자신이고, Testcontainers가 띄운 MinIO는 dind
daemon 쪽에 있다. 그래서 main의 integration job이 run 52·63·79 세 번 모두
이 시험의 연결 거부로 빨갛다. desktop에서는 둘이 같아 통과한다. 시험
인증서도 localhost와 127.0.0.1만 이름으로 가졌다.
고른 방법: 같은 lane의 평문 시험(MinioManagedObjectContractTest)처럼
Testcontainers가 알려 주는 Docker 호스트 주소로 붙고, 그 주소를 인증서
SAN에 더한다(IP면 ip:, 이름이면 dns:). 인증서는 컨테이너보다 먼저
만들어야 하므로 주소는 DockerClientFactory에서 받는다.
버린 대안: 인증서 검증을 끄는 것. 이 시험은 운영 클라이언트 그대로
HTTPS로 붙는 것이 목적이라 검증을 끄면 시험이 다른 경로를 본다.
위험·한계: IPv6 호스트는 URI에 대괄호를 씌우는 것만 넣었고 그 환경에서
돌려 보지 않았다.
검증: desktop integrationCheck, runner main 수동 실행(이 PR 본문에 적는다).
red team 리뷰가 WebXmlMapperFactory를 WebCborMapperFactory의 scalar-coercion
잠금(withCoercionConfig String->Fail, Textual Integer->Fail)을 빠뜨린 것으로 보고
표현별 엄격성 불일치를 의심했다. 실제로는 by-design이다: XML은 textual 포맷이라
숫자·불리언 DTO 필드도 전부 String 토큰(<count>5</count>)으로 들어온다. 거기서
String 입력을 막으면 모든 숫자/불리언 바인딩이 깨지고, WebCodecMapperTest의
xmlRoundTripPreservesWireTypes(int count를 바인딩)가 바로 그걸 고정한다. CBOR과의
엄격성 차이는 검증 우회가 아니다 — FAIL_ON_UNKNOWN_PROPERTIES와 SecureXmlInputFactory
하드닝은 여기에도 적용되고, @Valid 제약은 바인딩 뒤 모든 표현에 돈다.
순진한 "parity fix"가 멀쩡한 XML 바인딩을 깨뜨리지 않도록, 왜 CoercionConfig를
두지 않는지 주석으로 못 박는다(동작 변경 없음).
검증: :adapter:inbound:web-advanced:test --tests '*WebCodecMapperTest*' rc=0(무회귀).
web-fileserver admin 평면에서 orphans:reconcile만 @RequestBody에 @Valid가 없었다.
다른 다섯 핸들러(relocate·force-delete·submit-notification 등)는 모두 @Valid다.
지금은 OrphanReconcileHttpRequest에 Bean Validation 제약이 없어 드러나지 않지만,
나중에 limit에 @Min, reason에 @NotBlank를 더하면 @Valid가 없어 조용히 무시된다 —
이 템플릿이 평소 막는 검증 우회 부류다.
reconcileOrphans 파라미터에 @Valid를 더하고, 이 컨트롤러의 모든 @RequestBody가
@Valid를 갖는지 반사로 확인하는 막는 시험을 더해 admin 평면 전체에 규약을 고정한다.
검증: RED→GREEN — @Valid를 빼면 FileserverAdminControllerRequestBodyValidationTest
가 실패(rc=1, 그 파일 41행 AssertionError: offenders 비지 않음), 넣으면
:adapter:inbound:web-fileserver:test rc=0.
`management.server.address`가 비어 있어 Spring이 관리 커넥터를 모든 인터페이스
(0.0.0.0)에 바인딩했다. 별도 포트는 별도 네트워크가 아니다. 그 포트의
health·prometheus·info는 permitAll이고 actuator 체인에 인증 메커니즘이 없어,
파드/호스트 네트워크의 누구에게나 무인증으로 응답한다.
동적으로 확인했다(bootRunH2): `ss`가 `*:9001`, `curl :9001/actuator/health·info·
prometheus`=200. info는 build group/artifact/version·capabilities를, prometheus는
disk 경로·free/total·JVM·timing을 유출한다(API 표면·인프라 토폴로지). compose의
`127.0.0.1:9001` publish는 Docker 호스트만 막고 같은 compose 네트워크의 형제
컨테이너나 NetworkPolicy 없는 k8s/bare 배포는 막지 못한다. 선행 리뷰(07-13)는
compose publish만 확인했고 앱의 bind 주소는 보지 않았다.
observability.yml에 `management.server.address: ${MANAGEMENT_SERVER_ADDRESS:
127.0.0.1}`를 둬서 posture가 compose·NetworkPolicy에 의존하지 않고 앱 자체에서
loopback으로 닫히게 한다. 원격 스크레이프 배포는 그 env를 명시하거나 loopback
사이드카로 긁는다. 노출 allowlist는 그대로다.
버린 대안:
- 하드코딩 `127.0.0.1` → operator override 불가, env-driven 관례 위반.
- compose/NetworkPolicy에만 의존 → 앱 밖 설정에 보안 posture를 맡김(이 발견의 원인).
검증: 막는 계약 시험 `actuator-contract:management-address-loopback`를 더했다.
desktop에서 RED→GREEN 확인 — address 줄을 빼면 그 시험이 실패(rc=1,
ManagementActuatorSecurityContractTest.java:239 AssertionError), 넣으면
`:app-bootstrap:test` rc=0. build-logic `EnvContractVerifierTest` rc=0(env-keys와
설정 정합).
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
문제: Gradle 루트가 src/라서 빌드 도구(build-logic, gradle, config, 빌드
파일)가 계층 코드 폴더 옆에 섞여 있다. composition과 app-bootstrap은 같은
조립 계층인데 폴더가 따로이고, application 모듈 넷은 최상위에 흩어져 있다.
「Gradle은 src/에서 실행」이라는 예외 규칙이 모든 문서와 스크립트에 퍼졌다.
고른 방법: 저장소 루트를 Gradle 루트로 하고 src/에는 계층 코드만 둔다
(design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3, 소유자
승인 2026-11-07). 이 커밋은 git mv만 한다. 이름 바꾸기 감지가 1541개
파일 모두를 R100으로 잡도록 내용을 바꾸지 않았다. 바뀐 곳은 둘뿐이다:
src/.gitignore의 줄을 루트 .gitignore로 옮겼다.
- 빌드 파일, gradle/, build-logic/ → 저장소 루트
- config/checkstyle·spotbugs → config/ (코드 검사 도구 설정만)
- registry config/architecture/modules.json → gradle/modules.json,
시험 이미지 config/testing/container-images.properties
→ gradle/container-images.properties, registry 설명 → gradle/README.md
- Dockerfile, .dockerignore, .env*.example → 저장소 루트
- src/README.md(빌드·env 참조) → docs/build.md
- src/domain-core → src/domain/core,
src/application-* → src/application/*,
src/app-bootstrap → src/bootstrap/app,
src/composition/* → src/bootstrap/*
- 기능 생성 템플릿 scripts/feature-scaffold/{templates,probes}/src/ 아래도
같은 모양으로(domain/core, application/core, bootstrap/app)
위험: 이 커밋만으로는 빌드되지 않는다. 경로를 부르는 곳은 다음 커밋이
고친다. 두 커밋을 나눈 것은 파생 서비스가 merge할 때 이름 바꾸기와 내용
변경을 따로 보게 하려는 것이다.
검증: git diff --cached -M --name-status 에서 R100 1541개, 그 밖은
.gitignore 수정과 src/.gitignore 삭제뿐.
BREAKING CHANGE: 모든 빌드 파일과 계층 폴더의 경로가 바뀐다. 옛 경로 →
새 경로 표와 받는 순서는 docs/upgrade/2026-11-relayout.md에 있다.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절
b0bca2a6이 단 주석 한 줄이 100칸을 넘어 spotlessJavaCheck가 PR #7의
pr.yml(run 61)을 막았다. 같은 뜻으로 줄을 다시 나눈다.
검증: desktop :adapter:inbound:websocket:spotlessJavaCheck와 check 통과.
websocketNginxTest의 Nginx 컨테이너는 host.docker.internal을
host-gateway(Docker 호스트)로 풀어 시험 JVM의 앱에 붙었다. desktop에서는
Docker 호스트가 곧 JVM의 호스트라 됐지만, Gitea runner처럼 job이 자기
컨테이너 안에서 돌면 앱은 거기 없다. release 수동 실행(run 51)의
websocket-stable-release-gate가 upgrade마다 DeploymentException으로
실패했다.
Testcontainers의 호스트 포트 노출(exposeHostPorts, withAccessToHost)로
host.testcontainers.internal을 이 JVM으로 잇는다. 두 환경에서 같은
이름이다. 버린 것: runner 설정을 host 네트워크로 바꾸기(platform-core 몫,
job 격리를 푼다).
위험: Testcontainers가 sshd 보조 컨테이너를 하나 더 띄운다(이미지는
Testcontainers가 고정한 것, container-images.properties 밖).
검증: desktop에서 :adapter:inbound:websocket:websocketNginxTest.
메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은
이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길
측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로
두고 CI 절을 3.10(B-60~B-66)으로 미룬다.
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).
소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.
- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
`./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
(trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
`needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
(build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
.gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
docs/upgrade B-57~B-61.
버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.
위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.
BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
NotificationReleaseGateTest(알림 leaf의 `test`)는 docs/notification의
문서와 docs/adr의 NOTIF-ADR 넷이 있는지 본다. 그 파일들이 test 태스크의
입력이 아니어서, ADR을 옮기거나 지워도 Gradle이 태스크를 up-to-date나
캐시로 끝내고 시험이 다시 돌지 않았다. 지운 notification-platform.yml의
경로 필터가 docs/adr/로 옮긴 ADR을 못 보던 것과 같은 빈틈이다.
두 경로를 test의 입력으로 선언한다. 이 시험은 `ci` → `prCheck` 안에서
경로 필터 없이 매 PR 돈다(--dry-run 계획으로 확인).
검증: desktop PR 단계.
dev lane overlay(src/app-bootstrap/compose-lanes/dev.yaml)가 heap dump
폴더를 bind mount `./tmp/heap-dumps`로 두었다. Docker가 그 폴더를 root
소유로 만들어, compose lane을 돌린 git worktree를 일반 사용자가 지우지
못했다(`git worktree remove`가 Permission denied). 그래서 operate.md
4.1절에 컨테이너로 폴더를 지우는 우회 문장이 있었다.
named volume `heap-dumps`로 바꾼다. dump는 컨테이너가 사라져도 남고,
`docker compose cp`로 꺼낸다. 우회 문장을 지운다.
버린 것: bind mount에 사용자 uid를 맞추기(이미지·환경마다 다르다).
검증: desktop PR 단계(`verifyComposeProfiles`가 렌더링된 모델의 mount
대상 중복을 본다)와 nightly compose smoke.
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms
경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도
지운 docs/messaging/support-matrix.md를 가리킨다.
- docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째
messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09,
messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다.
- 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만
고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱
쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md.
- docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움),
라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때
composite build(Gradle 루트가 src/라 ../../messaging-library), registry
라이브러리 칸. 설계 14절이 근거다.
- src/config/architecture/README.md: library_groups·allowed_libraries 설명.
- docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는
법·패키지·auto-config 이름), B-59(registry 칸).
- 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions,
review-criteria, defect-patterns, gates, capability-status, manual 07,
build-logic·persistence-jpa·inbound messaging·shared-contract 지침,
env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo
라이브러리 문장으로 바꿨다.
위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개
repo라 익명으로 읽힌다).
검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크
깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s
scripts/tests OK.
BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는
messaging-library repo의 docs/messaging/에 있다.
Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).
- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
composition:outbox-relay와 app-bootstrap architectureTest. import와
auto-configuration 이름 문자열 dev.caskeleton.messaging →
dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
(../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
의존성 집합은 그대로, 설계 16절 H6).
버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).
위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).
검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.
BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).
Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
방향 검사(verifyModuleDependencyDirection)는 프로젝트 edge만 센다.
라이브러리가 별도 repo로 나가 외부 좌표가 되면, 지금 registry가
지키는 약속(메시징 bridge는 core-api만 본다, Kafka capability는
starter-kafka를 runtimeOnly로만 싣는다, 계층 leaf는 메시징을 모른다)을
아무것도 검사하지 않게 된다.
registry에 칸 둘을 더한다(설계 10.2절 T2, 소유자 승인 Q11).
- 맨 위 선택 칸 library_groups: 다스릴 Maven group 접두사.
- 행마다 선택 칸 allowed_libraries: group:artifact 목록. 꼴이 틀리거나,
library_groups 밖 group이거나, 겹치면 registry를 읽을 때 거절한다.
계층 leaf(domain-core, shared-contract, application-*) 행이 칸을
채우면 registry 위반이다. purity 검사가 비프로젝트 선언을 막는 것과
따로 registry 자체가 막는다.
- 방향 검사는 프로젝트 edge와 같은 방식으로 본다: 운영 선언
(api·implementation·compileOnly·runtimeOnly)의 소유 group 좌표와,
compileClasspath에서 보이는 소유 group 모듈(라이브러리 모듈이 api로
내보낸 것 포함)이 모두 칸에 있어야 한다. --include-build로 끼운
라이브러리 프로젝트는 프로젝트 edge가 아니라 그 좌표로 본다. 그래야
같이 고치는 흐름(composite build)에서도 같은 판정이 나온다. 「자기
빌드」는 ":"로 짐작하지 않고 해석 root의 build path로 읽는다(이 빌드가
다른 빌드에 끼워 돌아도 검사가 꺼지지 않게).
버린 대안: app-bootstrap ArchUnit 패키지 규칙(T1). import만 보고
runtimeOnly로 싣는 starter를 못 본다. 「어떤 모듈을 싣는가」는 빌드
사실이라 빌드 검사가 맞다.
위험: 시험 구성(testImplementation 등)은 프로젝트 edge처럼 보지 않는다.
이 빌드 자체를 다른 빌드에 끼우는 경우는 시험이 없다.
검증: desktop ./gradlew -p build-logic test rc=0. 새 시험: ModuleRegistryTest
4, CleanArchitectureResolvedClasspathFunctionalTest 7. functional 시험은
구현 전 RED였다(runtimeOnly·compile-visible 두 건은 게이트가 통과해
버렸고, --include-build 건은 「forbidden project dependencies
[demo-included]」로 실패).
Refs: design-docs repo-structure/05-library-repos.md 10.2절
workflow 15개 가운데 모듈 모양 파일들이 PR·main·nightly 단계가 이미
계획하는 Gradle 태스크를 한 번 더 돌린다(설계 design-docs
repo-structure/03-ci.md 3.1절 「중복」).
- fileserver-pr.yml 다섯 job: 모두 leaf `test`나 그 부분집합이다.
`ci`가 매 PR 돌린다.
- fileserver-nightly.yml의 --rerun-tasks job 셋: 같은 `test`의
부분집합이다. NFS job만 남긴다.
- jpa-nightly.yml의 failure·query plan·security·pool job: 모두
integration()·performance() lane이라 :integrationCheck·
:performanceCheck가 돈다. PostgreSQL major 행렬만 남긴다.
- notification-platform.yml의 pr job: `ci`와 :integrationCheck의
태스크다. 경로 필터가 docs/adr/로 옮긴 알림 ADR을 보지 못했다.
chaos job만 남긴다.
- object-storage-qualification.yml의 MinIO job 둘: integration lane이다.
보호된 AWS job만 남긴다.
- link-check.yml: 문서 검사라 main 단계로(소유자 결정 2026-09-16).
integration-main.yml의 links job으로 옮긴다.
fileserver 지원 매트릭스는 지운 job id 대신 그 증거를 실제로 만드는
테스트 클래스·모듈 test·남은 job을 적고, FileserverDocumentation
CoverageTest가 행마다 그 이름이 있는지 본다. job이 사라진 시험 문장
(PoolLaneClaimTest의 nightly job 검사, lychee 경로 필터 검사)은
지우거나 새 위치로 맞춘다.
위험: PR에서 경로로 켜지던 컨테이너 lane(notification의 실 PostgreSQL
두 lane, MinIO)은 이제 main push와 nightly에서만 돈다. 어댑터 컨테이너
lane을 main 단계로 옮긴 소유자 결정(2026-11-07 ②)과 같은 쪽이다.
검증: 기준 2959eff0의 desktop worktree에서 workflow의 Gradle 명령 50개를
--dry-run해 태스크 집합을 만들었다. 지운·옮긴 job 27개의 태스크는 모두
:ci·:mainCheck·:integrationCheck·:performanceCheck·:releaseCheck 계획
안에 있다(단계 집계 밖 0). 로그 desktop ~/t2a-backend-ci-logs/wave1-base/.
python3 scripts/check-docs.py, check-work-docs.py 통과.
Refs: design-docs repo-structure/03-ci.md 7.3절 Wave 1
grpc-library가 이름을 com.hyeonworks.grpc에서 dev.cakit.grpc로 바꾼다
(grpc-library PR #2, 소유자 2026-11-08: 개인 도메인 이름을 공용
라이브러리에 쓰지 않는다). 이 브랜치 문서는 옛 이름을 적고 있었다.
- README 재사용 체크리스트 6번: 라이브러리 패키지 dev.cakit.*은 바꾸지
않는다. 2번이 바꾸는 dev.caskeleton과 겹치지 않게 정한 이름이라고 적었다
- related-repos.md(group 두 칸과 받는 법), capability-status, 업그레이드
안내 B-55, 카탈로그 주석
남긴 것: Gitea 서버 주소, 기록(ADR-GRPC-002, 리뷰·history 본문)의 옛
proto 조직 이름 hyeonworks.
검증: check-docs.py OK, check-work-docs.py OK, --links broken 0.
구조 리뷰(arch-reviewer, 이 브랜치)가 찾은 권고 다섯을 고친다.
1. ModuleRegistry가 행의 `build` 칸을 아직 읽었다. 두 번째 빌드가 없어진
뒤로 main이 아닌 값(오타 포함)을 적은 leaf는 settings가 include하지
않고, 방향 검사도, 등록 안 된 build 스크립트 검사도 보지 않는데 ci는
초록으로 남는다(08-05가 막으려던 모양). 칸이 있으면(빈 값 포함) read에서
그 id와 'build'를 이름 대고 실패한다.
2. gates.md·defect-patterns.md의 「두 빌드의 verifyStrictLaneStages」.
3. shared-contract AGENTS.md의 「optional gRPC 빌드는 자기 사본을 둔다」를
별도 repo 라이브러리로.
4. QualityConventionsPlugin 주석의 현재형 「optional-platforms 빌드가 같은
제외 파일을 읽는다」를 이력으로.
5. StrictLaneStagesExtension 주석의 optional-build 경로에 그 빌드가 옮겨
갔다는 말을 붙였다.
버린 대안: `build` 칸과 modulesForBuild를 통째로 지우기. settings 설치기와
ArchitecturePlugin의 시그니처까지 바뀌고, 막는 효과는 같다.
검증(desktop ~/x2-template-wt, --no-build-cache):
- RED: 새 시험 aBuildFieldIsRejected… 고치기 전 실패(9 tests, 1 failed)
- GREEN: ModuleRegistryTest 통과. 옛 blankBuildOwnershipIsRefused는 새
문구로 바꿨다(빈 값도 같은 이유로 거절)
- -p build-logic check javadoc rc=0(172 tests), :ci :verifyDependencyLocks
rc=0(7389 tests, 실패 0), verifyStrictLaneStages --dry-run, check-docs,
check-work-docs(--links 포함), check-repo-layout 모두 rc=0