Commit Graph
151 Commits
Author SHA1 Message Date
DongHyeonka a2dbf33b75 docs: grpc-library의 Maven group·패키지 이름을 dev.cakit.grpc로 맞춘다
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.
2026-11-08 14:09:47 +09:00
DongHyeonka 57988c2e48 fix(build-logic): registry 행의 build 칸을 거절하고 남은 두 빌드 문장을 고친다
구조 리뷰(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
2026-11-08 13:49:48 +09:00
DongHyeonka 91804ec182 fix(docs): 옮긴 gRPC 기록은 템플릿에 남기고 머리 블록만 고친다
앞 커밋이 ADR-GRPC 7개와 gRPC 설계서를 살아 있는 문서와 함께 지웠다.
그러자 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md의
상대 링크가 깨졌다(desktop: check-work-docs --links broken 1, lychee
Error 1). 기록 본문은 고치지 않는다는 규칙이라 링크를 고칠 수 없다.
기록은 그때 템플릿 안 코드를 두고 한 결정·설계이므로 템플릿에도 남는
것이 맞다(설계 Q15 「리뷰 기록은 템플릿에 남김」과 같은 이유).

- ADR-GRPC 7개와 설계서를 22df3525에서 되살리고, 머리 블록 「현재 정본」을
  「없음 — grpc-library로 옮겼다」로 바꿨다. 사본은 grpc-library에도 있다.
- 업그레이드 안내 B-55의 지운 목록에서 그 기록들을 뺐다.
- persistence-jpa testkit 주석 둘을 Spotless 줄바꿈대로 다시 쌌다
  (desktop ci의 spotlessJavaCheck 실패).

검증(로컬, 문서만): check-docs.py rc=0, check-work-docs.py --links
broken 0. Gradle 게이트는 desktop에서 다시 돈다.
2026-11-08 13:05:03 +09:00
DongHyeonka 5e204e6a43 refactor(platforms)!: gRPC 플랫폼을 별도 repo grpc-library로 옮기고 지운다
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼
(src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드
(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데,
registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘,
카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다.

소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절,
05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다.
gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13).
코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리
해시가 이 기준 커밋 22df3525와 같다).

지운 것:
- src/platforms/grpc, grpc-advanced, optional-build(343파일)
- registry의 "build": "optional-grpc" 9행
- ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs,
  integration-main.yml optional 성능 단계와 job
  grpc-optional-platform-integration, release.yml job
  grpc-stable-release-gate와 이미지 job의 needs 한 줄
- build-logic ca.grpc-platform-module·ca.optional-architecture-registry,
  MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의
  optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다
- 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14:
  채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄
- 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘,
  gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리
  블록 「현재 정본」만 새 자리를 말하게 했다
- DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험,
  adopter API 표면 검사의 optional-build 제외 경로

남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),
src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원
(ModuleRegistry, 일반 기능).

살아 있는 문서: README, docs 지도, capability-status, work/delegate·
gates·decisions(새 행 「라이브러리 repo」)·defect-patterns·
review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로),
manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석.
새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이
고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56.

위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다
(tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전
커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지
않았다.

검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck,
compose smoke, 빠른 시작). 문서 검사 셋 rc=0.

BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:*
프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin
protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로
받는다(docs/upgrade/2026-11-maturity-review.md 3.8절).
Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
2026-11-08 11:29:47 +09:00
DongHyeonka 248df5180f Merge remote-tracking branch 'origin/main' into claude/h3-backend-harness-34fc23 2026-11-07 22:42:49 +09:00
DongHyeonka 7140f27948 docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).

- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
  규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
  지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
  지킬 규칙 몇 줄을 남겼다.
  - application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
    멱등성(KEYED) → 337줄에서 190줄.
  - persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
    TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
    194줄.
  - graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
  TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
  찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
  AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
  가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
  자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
  코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
  맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
  `lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
  PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.

위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.

검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.

BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
2026-11-07 22:33:08 +09:00
DongHyeonka 38891071d6 feat(hooks)!: 편집 직후 포맷·레이어·문서 알림과 migration 차단 훅을 건다
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).

scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
  종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
  버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
  쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
  --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
  파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
  build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
  (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
  같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
  턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).

버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).

위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.

검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.

BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
2026-11-07 22:06:50 +09:00
DongHyeonka 3c73fc333c docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).

- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
  일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
  테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
  계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
  src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
  src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
  docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
  .claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
  .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
  「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
  작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
  행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
  진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
  .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
  읽는다. 단언은 그대로다.

버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.

위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.

검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.

BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
2026-11-07 21:59:42 +09:00
DongHyeonka 08f932123a docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
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` 한 줄이다.
2026-11-07 21:58:12 +09:00
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
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 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 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 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 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 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 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 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 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 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 145ae00f90 docs(src): src/README의 영어 제목과 코드와 다른 주장을 고친다
문제: `src/README.md`에 영어 제목(「Local bootstrap」「App identity」 등)과 영어
문장이 남아 있다. 지운 게이트 표 `.github/ci-gate-matrix.yml`과 검사기
`.github/scripts/verify-gate-matrix.sh`를 지금 있는 것처럼 인라인 코드로 적어 참조
검사의 예외 줄 둘이 남아 있다. 코드와 다른 주장도 둘이다.
- `SPRING_PROFILES_ACTIVE`를 「보통 local | dev | stage | prod」라 한다. registry
  `allowed_values`와 `RuntimeEnvironment`는 local·dev·prod뿐이다.
- 추적 샘플 비율 기본값에 「staging = 0.10」이 있다. `TracingSampleRateResolver`는
  PROD 0.01, LOCAL·DEV 1.0만 안다.

고른 방법: 영어 제목과 문장을 한국어로 옮기고, 지운 두 파일 이야기는 「> 이력」 인용
블록으로 옮긴다. 두 주장은 코드에 맞춘다. 다른 문서가 이름으로 가리키는 「기능 추가 =
한 줄 + env」 제목은 그대로 둔다.

위험·한계: 문서 전체가 「~합니다」체다. 문체를 「~한다」로 바꾸는 일은 하지 않았다.

검증: `python3 scripts/check-docs.py` rc=0(예외 줄 둘을 지움).
2026-11-07 17:18:18 +09:00
DongHyeonka a4382b477f docs(readme): 루트 README를 구조·문서 지도가 보이는 절 순서로 다시 쓴다
문제: 처음 온 사람이 루트 README만 보고는 저장소 구조와 문서 위치를 알 수 없다.
절이 「아키텍처 한눈에, 퀵스타트, 새 프로젝트로 시작하기, 아키텍처 규칙과 검증,
수동 전용 Gradle 태스크, 더 알아보기」라 `src/platforms/`, 루트 `compose.yaml`,
`compose/`, 문서 폴더가 어디에도 없다. 코드와 다른 주장도 있다.
- 「수동 전용 Gradle 태스크」는 `grpcPerformanceTest`를 어떤 workflow도 돌리지 않고
  `cd src && ./gradlew :grpc:grpc-testkit:grpcPerformanceTest`로 부른다고 한다.
  실제로는 `integration-main.yml`이 `-p platforms/optional-build performanceCheck`로
  돌리고, gRPC 플랫폼은 다른 빌드라 그 명령은 주 빌드에서 돌지 않는다.
- 패키지 이름 바꾸기 명령이 `.java`·`.gradle`·`.yml`만 고친다. `dev.caskeleton`은
  `AutoConfiguration.imports` 29개, `spring.factories` 9개, 생성 명령 템플릿,
  xml·json 파일에도 있다.

고른 방법: design-docs `conventions/docs-system.md` 6.1절 순서로 절을 다시 짠다
(프로젝트 구조 → 시작하기 → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로
시작하기 → 규칙과 기여). 구조 절은 최상위 폴더 표, `src/` 폴더 표(기본 조립에
들어가나), 의존 방향 도식을 두고 모듈 개수와 버전 숫자는 쓰지 않는다. 틀린 두
주장은 지우거나 `git grep -l 'dev\.caskeleton'`로 찾게 바꾼다. 프로파일 표와
`bootRunH2` 설명은 이미 `src/README.md`가 가지므로 거기를 가리킨다. 문체는
「~한다」로 바꾼다.

버린 대안: 옛 절을 그대로 두고 두 절만 더하기. 6.1절 순서와 다르고, 같은 내용이
`src/README.md`와 두 곳에 남는다.

위험·한계: README 문구를 단언하던 `DeveloperExperienceContractTest
.readmeDocumentsOneFirstRunEntrypoint`의 기대 문자열을 「## 시작하기」·「첫 실행
진입점은 하나다.」로 맞췄다. 진입점 하나와 성공 확인을 지키는 계약은 그대로다.

검증: `python3 scripts/check-docs.py` rc=0,
`python3 scripts/check-work-docs.py --links README.md` 깨진 링크 0.
2026-11-07 17:18:18 +09:00
DongHyeonka ff6fdf8d80 build(deps): build-logic의 Jackson 3를 3.1.7로 올린다
문제: build-logic만 카탈로그 `jackson3`(3.0.2)를 그대로 해석한다. 그 lockfile의
jackson-core·databind 3.0.2에 trivy HIGH가 10건 있다.
- jackson-core: CVE-2026-29062(중첩 깊이, 3.1.0), CVE-2026-68494(비동기
  파서, 3.1.4), GHSA-2m67-wjpj-xhg9(문서 길이 제한 우회, 3.1.1),
  CVE-2026-89407·CVE-2026-89425(3.1.7)
- jackson-databind: CVE-2026-54512·CVE-2026-54513(PolymorphicTypeValidator
  우회, 3.1.4), CVE-2026-68497(3.1.6), CVE-2026-91776·CVE-2026-91777(3.1.7)
leaf는 이 키를 쓰지 않고 Boot BOM의 jackson-bom을 따른다.

고친 방법: `jackson3`를 3.1.7로 올린다. 위 10건을 모두 고친 가장 작은 버전이고,
바로 앞 커밋의 Boot 4.0.9 BOM이 leaf에 주는 버전과 같다. 그래서 빌드와
애플리케이션이 같은 Jackson을 쓴다. 키 설명도 그 뜻으로 고쳤다.
- 버린 대안: 3.2.x. 마이너를 하나 더 넘고, leaf와 다른 Jackson이 된다.

위험·한계: build-logic은 Jackson으로 registry JSON과 설정 metadata만 읽는다
(`ModuleRegistry`, `ConfigurationMetadataClasspath`). 3.0→3.1 사이 동작 차이는
이 두 곳의 테스트가 본다.

검증(desktop, 이 트리 c0ddf259):
- 세 빌드를 `--write-locks`로 다시 썼다. 바뀐 lockfile은 build-logic 하나이고,
  jackson-core·databind·bom 3.0.2→3.1.7, jackson-annotations 2.20→2.21이다.
- `./gradlew -p build-logic check javadoc` rc=0, 테스트 173 실패 0 skip 0.
- `./gradlew verifyDependencyLocks architectureCheck` rc=0(registry를 Jackson으로
  읽는 설정 단계 포함). optional 빌드 `verifyDependencyLocks` rc=0.
2026-11-07 17:13:24 +09:00
DongHyeonka 5a3784be58 docs(adapter-inbound): inbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: inbound 어댑터 leaf(messaging, web, web-advanced, websocket,
graphql, grpc)의 CLAUDE.md가 영어이거나 영어 절이 섞여 있다. 다섯
CLAUDE.md는 Spring Boot 버전(4.0.0, 4.0.8)을, graphql README는 leaf
개수(19·24·43)를 복사해 두었고 그 수는 registry가 바뀌면 틀린다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·표 구조는
원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을, leaf 수는
registry를 가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에
맞춘다: web CLAUDE.md의 `adapter-persistence`(없는 이름)를
`adapter:outbound:persistence-jpa`로, Jackson 속성 위치를
`spring.jackson.serialization.*`·`generator.*`에서 실제 키
`spring.jackson.deserialization.*`·`spring.jackson.datatype.*`로,
「`WRITE_BIGDECIMAL_AS_PLAIN=true`로 고정」을 「설정 키가 아니라
`JacksonSerializationPolicyTest`가 지수 표기 없음을 단언」으로 고친다.
매뉴얼 장 번호만 쓴 참조는 경로와 절 제목으로 바꾼다.

위험: ArchUnit 규칙 이름의 대소문자(문서는 소문자, 코드는 대문자
상수)는 이 커밋에서 그대로 두고 다음 커밋에서 한꺼번에 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 4개, number 줄
7개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:12:03 +09:00
DongHyeonka afe30e733d build(deps): Spring Boot를 4.0.9로 올린다
문제: 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초.
2026-11-07 17:10:19 +09:00
DongHyeonka c91cc3fb10 docs(core): core·조립·빌드·플랫폼 모듈 문서를 한국어로 옮긴다
문제: core 계층(application·domain·shared-contract), app-bootstrap,
composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다.
세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를
모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을
4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로
둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다.
다른 문서·코드가 제목으로 가리키는 절(application-core의
Naming convention·Package ownership·Canonical use case shape·Allowed
transactional shapes, shared-contract의 Responsibility·Forbidden,
messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가
계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다.
코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을
`adapter-persistence`에서 `adapter:outbound:persistence-jpa`의
`SpringTransaction`으로, registry README의 빈 의존 목록 예를
persistence-mongo(실제 목록은 application-core·shared-contract)에서
domain-core·shared-contract·messaging-core-api로 고친다.
TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로
머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을
대조하는 계약은 그대로다.

위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로
바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01,
11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다.

검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개,
number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위)
깨진 링크 0, unittest discover scripts/tests 43개 통과.
2026-11-07 17:07:16 +09:00
DongHyeonka 3744736c4c build(deps): lockfile에서 지금 빌드에 없는 구성의 옛 줄을 지운다
문제: lockfile 5개가 이제 빌드에 없는 구성의 잠금 상태를 들고 있다.
- application-core: redisPolicyContractTest(source set은 5f10b791d에서 지움)
- shared-contract: edgeRateLimitContractTest
- objectstorage: objectStorageMinioContractTest·objectStorageMinioFaultTest
  (두 lane은 지금 `integrationTest` source set에서 돈다)
- persistence-jpa·persistence-mongo: testkit(testFixtures로 바뀜)
`--write-locks`는 그 빌드에서 해석한 구성만 다시 쓰고 나머지 줄은 그대로
둔다. 그래서 source set을 지워도 줄이 남았다. STRICT 잠금은 해석하는
구성만 대조하므로 빌드는 이 줄을 쓰지 않지만, trivy는 lockfile을 읽어
그 버전을 취약점으로 센다. trivy HIGH 한 건(assertj-core 3.27.6,
CVE-2026-24400)은 application-core의 이 옛 줄에서만 나온다. 해석되는
구성은 모두 3.27.7이다.

고친 방법: 다섯 파일을 지우고 `resolveAndLockAll --write-locks`로 새로
만들었다. 다른 lockfile은 같은 방법으로 새로 만들어도 바이트가 같았다
(주 빌드, optional 빌드, build-logic 모두).
- 버린 대안: 옛 줄만 손으로 지우기. lockfile 머리말이 손 편집을 막고,
  Gradle이 쓴 결과와 같다는 보장이 없다.
- 버린 대안: assertj 무시 항목. 쓰지 않는 버전을 무시 목록에 올리는 것이다.

위험·한계: 같은 방법으로 남는 옛 줄을 막는 장치는 없다. source set을
지우는 사람이 lockfile도 새로 만들어야 한다.

검증(desktop, 기준 5ab1b418):
- lockfile 전부를 지우고 새로 만든 결과와 커밋된 결과를 (좌표, 구성) 쌍으로
  비교했다. 다른 것은 위 다섯 파일의 사라진 구성뿐이고, 남은 구성의 쌍은
  하나도 다르지 않다.
- `./gradlew verifyDependencyLocks` rc=0(leaf 태스크 55개와 루트 집계).
2026-11-07 17:01:08 +09:00
DongHyeonka 5ab1b4182c test(messaging): 대기 허가 테스트가 실행 순서에 따라 갈리지 않게 한다
문제: `MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned`가
desktop 부하가 높을 때 가끔 실패한다(구조 정리 게이트에서 부하 7에 한 번,
이번에 부하 24~27에서 20번 중 한 번).

원인: 이 테스트는 대상 하나(`order.created`)로 허가 하나를 쥔 뒤, 같은 대상으로
대기자를 띄우고 곧바로 허가를 돌려준다. 그런데 대상별 상한(2인자 생성자에서는
프로세스 상한과 같은 1)이 나중에 더해지면서 같은 대상의 두 번째 호출은
프로세스 허가를 기다리지 않고 바로 `DESTINATION_IN_FLIGHT_LIMIT_EXCEEDED`로
거절된다. 그래서 테스트는 main 스레드의 `complete`가 대기자의 `admit`보다
먼저 돌 때만 통과한다(그때는 대기자가 기다릴 일이 없다). 부하가 높아 대기자가
먼저 돌면 거절되고 in-flight가 0이 되어 실패한다. 테스트 이름이 말하는
"기다리던 호출이 허가를 받는다"는 어느 쪽에서도 시험되지 않았다.

고친 방법:
- 대기자를 다른 대상으로 보내 프로세스 허가만 다투게 한다.
- 대기자가 실제로 limiter의 bounded wait에 들어가(TIMED_WAITING) 줄을 선 뒤에
  허가를 돌려준다. 순서를 테스트가 정하므로 스레드 일정에 기대지 않는다.
- 대기자의 거절을 잡아 단언한다(전에는 스레드 밖으로 사라졌다).
- 대기 상한을 2초에서 30초로 늘린다. 부하가 높을 때 상한이 먼저 끝나 생기는
  다른 갈림을 막는다. 대기자는 허가를 받는 즉시 끝나므로 평소 시간은 같다.

버린 대안: 같은 대상을 두고 3인자 생성자로 대상별 상한을 2로 주기. 그러면
대상별 상한 1·프로세스 상한 1 조합(2인자 생성자 기본)의 동작을 시험에서
숨긴다. 그 동작 자체를 바꾸는 것은 이 변경의 범위가 아니다.

위험·한계: 2인자 생성자 Javadoc은 "only ceiling is the process-wide one"이라
하지만 한 대상이 프로세스 허가를 모두 쥐면 같은 대상의 호출은 기다리지 않고
바로 거절된다. 운영 조립(`MessagingPublishConfiguration`)은 3인자 생성자로
대상별 상한(기본 64)을 따로 주므로 영향이 없다. 문서와 동작 중 무엇을 맞출지는
별도로 남긴다.

검증(desktop, `--no-build-cache`):
- RED: 새 테스트 모양에 대기자를 같은 대상으로 두면 매번 실패한다. 메시지
  "the waiter must be queued on the permit before it is returned (refused:
  MessageBackpressureException: order.created already holds its 1 in-flight
  publishes ...) expected: TIMED_WAITING but was: TERMINATED".
- GREEN: `:messaging:messaging-policy:check :messaging:messaging-policy:testQualityCheck`
  rc=0, 테스트 43 실패 0.
- 부하: busy loop 24개(12코어)를 건 채 이 클래스를 `--rerun`으로 20번 연속
  돌렸다. 고친 트리 20/20 통과(1분 부하 8→24). 같은 부하에서 고치기 전 트리는
  20번 중 1번 실패(8번째, "expected: 1 but was: 0", 대기자가 위 거절을 받음).
  로그 desktop `~/i1-layout-docs-logs/flaky/`.
2026-11-07 15:14:21 +09:00
DongHyeonka 268bfdd1d8 Merge remote-tracking branch 'origin/claude/d1-docs-system-fd4a0f' into claude/i1-layout-docs-merge-217f1e
# Conflicts:
#	docs/ci-cd/template-vs-consumer.md
#	src/platforms/grpc/CLAUDE.md
2026-11-07 14:59:56 +09:00
DongHyeonka 7305ab38a3 fix(docker): 의존성 단계에 leaf의 release 데이터를 복사한다
문제: 8d69e599가 config/jpa를 persistence-jpa의 release/로 옮긴 뒤 이미지
빌드가 깨진다. Dockerfile 의존성 단계는 config/와 빌드 파일만 복사하고
./gradlew verifyDependencyLocks를 도는데, persistence-jpa build.gradle은
설정 평가 중에 release/readiness-cards.yaml을 읽는다("Unable to process
file: …/release/readiness-cards.yaml"). 빠른 시작(bootstrap-local.sh)이
최종 게이트에서 rc=1로 드러냈다. compose smoke는 같은 빌드 실패를 무시해
이 결함을 숨겼다(다음 커밋).

고른 방법: 의존성 단계에 COPY --parents **/release/*.yaml **/release/*.json
한 줄을 더한다. 빌드 파일만 복사하는 단계의 성질(의존성 계층 캐시)은
그대로 두고, 설정 평가가 읽는 데이터만 더한다.
버린 대안: build.gradle이 그 파일을 늦게 읽게 바꾸기. readiness lane이
요구하는 테스트 목록이 설정 시점에 정해져야 해서 늦출 수 없다.
DeveloperExperienceContractTest의 의존성 단계 계약에 이 줄을 더한다.

위험·한계: release/ 데이터가 바뀌면 의존성 계층도 다시 만든다(예전
config/와 같다).

검증(desktop ~/workspace/t1-final, ~/t1-layout-logs/):
- RED: 8d69e599 이후 트리에서 이미지 빌드가 위 오류로 실패
  (final/final-bootstrap.log, rc=1)
- scripts/bootstrap-local.sh rc=0(이미지 빌드, /api/healthcheck 200 UP,
  트리 3b755111 — 이 커밋과 Dockerfile 주석 한 줄만 다르다)
- :app-bootstrap:repositoryContractTest :app-bootstrap:spotlessCheck rc=0
  (트리 b91277be)

Fixes: 8d69e599a3 ("refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다")
2026-11-07 14:34:22 +09:00
DongHyeonka 1ed683ffdb fix(messaging): 인증 증거를 digest로 고정한 Kafka 이미지로 다시 만든다
문제: :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 칸은 레인을 돌린 트리의 커밋(8d69e599, 이 파일만 다르다)을
가리킨다. 레인은 실 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=8d69e599… :messaging:messaging-testkit:check
  :messaging:messaging-kafka:check rc=0 (messagingCertificationTest 실행)
2026-11-07 13:07:47 +09:00
DongHyeonka 8d69e599a3 refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다
문제: 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.
2026-11-07 13:04:54 +09:00
DongHyeonka 50cd7154d0 refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
  보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
  .local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
  죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
  겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.

고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
  capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
  고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
  mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
  overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
  계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
  redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
  backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
  전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
  OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
  남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
  런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).

위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
  lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
  src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
  (YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
  둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
  lane-services.yaml(smoke client 변수)은 뺀다.

검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
  :app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
  redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
  :adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
  모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
  all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
  기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
  up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
  README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest, verify-compose rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
2026-11-07 12:52:36 +09:00
DongHyeonka a025f244c7 refactor(repo)!: 쓰지 않는 파일과 운영 인프라 파일을 지운다
문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.

고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
  docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
  internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
  ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
  docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
  jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
  httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
  경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
  근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.

위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.

검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
  :app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
  FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
2026-11-07 12:22:47 +09:00
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00
DongHyeonka 630f9b860a docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.

고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
  → docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
  원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.

옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.

위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.

검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
2026-11-07 12:15:45 +09:00
DongHyeonka c79d4259a9 Merge remote-tracking branch 'origin/claude/r9-g4-idempotency-c669be' into claude/integration-r9-f1bc5c
충돌 하나를 정리했다.

- docs/upgrade/2026-11-maturity-review.md 머리 「커밋:」 줄: 앞서 합친 G3·G1·G2
  항목을 두고, G4의 「멱등 저장소의 markFailed 재전송 인자와 renew 뒤 start」를
  끝에 더했다(G4가 둔 자리도 끝이다).

decisions.md와 application-core README는 G1·G4가 서로 다른 행·문단을 고쳐
자동 병합됐다. 두 브랜치가 더한 줄이 모두 남은 것을 diff로 봤다.
2026-11-07 10:01:27 +09:00
DongHyeonka dc47fbda2e Merge remote-tracking branch 'origin/claude/r9-g2-stomp-interceptor-f5675d' into claude/integration-r9-f1bc5c
충돌 하나를 정리했다.

- docs/upgrade/2026-11-maturity-review.md 머리 「커밋:」 줄: 앞서 합친 G3·G1
  항목을 두고, G2의 「STOMP channel interceptor를 사용자 전송으로 셈」을 끝에
  더했다(G2가 둔 자리도 끝이다).
2026-11-07 10:01:06 +09:00
DongHyeonka f33903cc1e Merge remote-tracking branch 'origin/claude/r9-g1-inbound-456713' into claude/integration-r9-f1bc5c
충돌 하나와 텍스트 충돌 없는 컴파일 깨짐 하나를 정리했다.

- docs/upgrade/2026-11-maturity-review.md 머리 「커밋:」 줄: G3의 「실패한 동시
  인덱스 drop의 복구 절차」와 G1의 「r9-g1 GraphQL 판정 순서와 인자 변환 단계」를
  모두 남겼다. G1 항목은 G1이 둔 자리(r8-f1 뒤), G3 항목은 G3가 둔 자리(끝)다.
- PostgreSqlDistributedLockIntegrationTest: G3가 OutboxRunbookSql을 RunbookSql로
  바꿨는데 G1의 새 테스트 두 곳이 옛 이름을 부른다. 새 이름으로 바꿨다.
2026-11-07 10:00:44 +09:00
DongHyeonka 11c7608914 docs(web): 필터가 던진 예외를 컨테이너가 원인째 남기는 것을 적는다
문제(리뷰 README 19.4절 끝 개선 제안):
- web README는 필터가 던진 예외가 GlobalExceptionHandler를 지나지
  않는다고만 적는다. 그 예외의 서버 로그가 어디서 어떤 모양으로
  남는지(ServerFailureLog의 정리를 받지 못한다는 것)는 적혀 있지 않고,
  리뷰도 실행으로 확인하지 않았다.

고른 방법:
- 먼저 실제 Tomcat 테스트 FilterFailureContainerLogIT(systemTest)로
  확인했다. 필터가 PersistenceFailureException(SQL 원인)을 감싼 예외를
  던지면 WARN 이상 줄은 하나뿐이다: Tomcat ContainerBase…
  [dispatcherServlet] logger의 ERROR "Servlet.service() for servlet
  [dispatcherServlet] … threw exception"과 원인 사슬 전체(SQL 접속
  문자열 포함). GlobalExceptionHandler 줄은 없다.
- 그 결과를 README 「EnvelopeErrorController」 절에 적고, 필터에서
  저장소·외부 의존을 부르면 실패를 필터에서 잡아 EnvelopeResponseWriter로
  답하고 로그는 ServerFailureLog.of로 정하라고 안내한다. 테스트는 그
  문장을 지키려고 남긴다.

위험·한계:
- Tomcat에서만 확인했다. Jetty는 확인하지 않았다고 README에 적었다.
- 로그 줄 모양은 Tomcat 버전에 기댄다. 바뀌면 이 테스트가 실패한다.

검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- 확인(README를 쓰기 전, 기준 3eb3b067 + 이 테스트, 트리 a675c244):
  :adapter:inbound:web:systemTest --tests FilterFailureContainerLogIT rc=0.
  로그: "ERROR … o.a.c.c.C.[.[.[/].[dispatcherServlet] : Servlet.service()
  for servlet [dispatcherServlet] in context with path [] threw exception"과
  "Caused by: java.sql.SQLException: jdbc:postgresql://db.internal/…".
  red/R4-web-filter-log.log
- 이 커밋 트리(64089130, 브랜치 마지막 트리)의 pull request 단계 게이트
  (모두 rc=0, FROM-CACHE 0, green2/; 같은 worktree 앞 실행의 UP-TO-DATE는
  green/의 같은 이름 로그가 트리 d6f6b28a에서 실행한 것):
  - :ci :verifyDependencyLocks --warning-mode=fail — 태스크 1142, test
    XML 2,216건 실패 0(skip 19 이전부터). 전체 실행은 green/D01-ci.log
    (752초), 그 뒤 바뀐 web·websocket test는 green2/B1에서 실행.
  - :verifyStrictLaneStages --dry-run, :sample-portfolio:check
    :sample-portfolio:qualityCheck, -p optional-platforms ci,
    -p optional-platforms :verifyStrictLaneStages --dry-run,
    bash scripts/verify-compose-profile-contracts.sh(18 lane 일치)
  - 바뀐 경로로 켜지는 pr-adapters lane: web systemTest 19건·
    webJettyCompatTest 16건, websocketJettyTest 8건, websocketNginxTest
    4건, jpaPlatformContractTest PostgreSQL 16·18 각 429건,
    jpaPlatformMigrationTest 45건, 모두 실패 0
  - 링크 검사(lychee 없음)는 check-work-docs.py --links로 대체: 555개 깨짐
    0. check-work-docs.py rc=0
  - 해당 없음·못 돌림: grpc-proto-buf(.proto 변경 없음),
    dependency-review(lockfile 변경 없음), trivy-fs(desktop에 trivy 없음)
- 더 돌린 것: graphql·websocket systemTest 55건, documentContractTest 67건,
  바뀐 leaf 여섯의 testQualityCheck rc=0

Refs: docs/reviews/2026-11-03-rereview/README.md 19.4절 끝(개선 제안), 19.5절
2026-11-07 08:22:59 +09:00