Commit Graph
87 Commits
Author SHA1 Message Date
DongHyeonka a638698fc8 docs(work): experts.md 경로 표를 스킬 paths와 맞추고 대조 시험을 둔다
문제: experts.md 3절 「경로 → 전문가」는 리드가 바뀐 경로로 렌즈를
고르는 표이고 "지식 스킬의 paths와 맞춘다"고 적는다. 그런데 손으로 옮긴
표가 열 스킬 중 아홉에서 이미 갈라졌다. 예: be-build-ci의 settings.gradle·
gradle.properties·Dockerfile·renovate.json, be-api-contract의 .env.example·
docs/upgrade/**, be-observability의 docs/runbooks/**, be-docs의
**/CLAUDE.md가 표에 없다. 표로 렌즈를 고르면 그 파일을 바꾼 변경에서
렌즈가 빠진다. 이름만 보는 시험(test_the_experts_manual_names_every_expert)은
이 차이를 못 잡는다.

고른 방법: 표 1열을 1차 렌즈 스킬의 paths와 똑같이 고치고, 시험이
표를 읽어(중괄호 펼침) 스킬마다 "1차 렌즈로 이름 댄 행의 glob 합집합 ==
그 스킬의 paths"를 본다. 표 위 문장에 대조 시험이 있다고 적는다.
버린 대안: 표를 지우고 각 스킬 paths를 읽으라고만 쓰기 — 리드가 렌즈
하나를 고르려고 스킬 열 개의 머리를 읽어야 하고, 「이럴 때 더한다」 칸이
갈 곳이 없다.

위험·한계: 「이럴 때 더한다」 칸은 기계로 대조하지 않는다.

검증: 새 시험 test_the_experts_path_table_lists_exactly_each_skill_paths —
기준 표에서 9개 스킬 실패(be-domain만 통과), 고친 표에서 통과.
test_claude_setup 16건 통과, check-work-docs.py·check-docs.py rc=0.
2026-11-12 21:40:07 +09:00
DongHyeonka 48789b7c5f feat(scripts): check-work-docs가 작업 흐름 이름과 red team ID를 잡는다
문제: 진입 문서의 이력 ID 검사(HISTORY_PATTERNS)는 리뷰 라운드·묶음
이름의 아는 꼴만 잡는다. 2026-11 프로그램의 작업 흐름 이름(W1~W6)과 red
team 발견 ID(BE-OBS-A, BE-CONFIG-001)는 꼴이 없어, operate.md에 들어간
"(W4 BE-OBS-A)"를 --history도 기본 검사도 잡지 못했다.

고른 방법: 두 꼴을 패턴에 더한다. W 뒤 숫자 하나가 단어로 서 있을 때
(W3C, HTTP-W1-x는 아님), BE·FE 뒤 대문자 분야와 세 자리 번호나 글자
하나. 지금 검사 대상 문서에는 걸리는 줄이 없다.

위험·한계: 새 이름 꼴(다른 프로그램의 흐름 이름 등)은 또 패턴을 더해야
잡힌다. 검사는 아는 꼴만 본다는 한계는 그대로다(be-docs 함정 2).

검증: 새 시험 둘(걸리는 세 줄, 걸리면 안 되는 W3C) — 기준
check-work-docs.py에 얹으면 세 줄 모두 통과해 3건 실패, 이 커밋에서
test_check_work_docs 17건 통과. check-work-docs.py rc=0.
2026-11-12 21:39:43 +09:00
DongHyeonka 7db40c9b7a merge: main(27a18b4f, W3 전문가 스킬 병합)을 받는다
pr / done (pull_request) Successful in 12m1s
2026-11-12 15:01:50 +09:00
DongHyeonka 083c6910fa fix(compose): smoke lane이 기반 서비스를 먼저 띄우고 앱을 띄운다
pr / done (pull_request) Canceled after 0s
문제: compose smoke는 lane의 오래 도는 서비스를 `up --wait` 한 번에 함께 띄운다.
앱과 Kafka가 동시에 뜨면 앱의 producer가 아직 연결을 받지 않는 broker에 붙어
재시도 WARN을 남기고, 「기동 로그가 조용하다」 검사가 실패한다. main 수동 run 59
(2026-11-11)의 local-messaging lane이 이것으로 실패했다. 같은 lane이 바로 앞
run과 desktop에서는 통과했다(시간 경쟁).

고른 방법: smoke 스크립트가 app이 아닌 서비스를 먼저 `up --wait`로 healthy까지
띄우고, 그다음 app까지 `up --wait`한다. 모든 lane이 app을 가진다. 개발용
compose.yaml은 바꾸지 않는다.

버린 대안: compose.yaml의 app에 kafka `depends_on`(service_healthy)을 거는 것.
app은 profile이 다른 여러 lane과 개발 환경이 함께 쓰고, 꺼진 profile의 서비스를
기다리게 되면 그 구성이 시작하지 못한다(`required: false`는 Compose 2.20부터).

위험·한계: lane마다 기반 서비스가 healthy가 될 때까지 기다리는 만큼 lane이 조금
길어진다. 그전에도 `up --wait`가 그만큼 기다렸으므로 차이는 작다.

검증: desktop에서 local-messaging lane, runner nightly 수동 실행(이 PR 본문에 적는다).
2026-11-12 07:53:10 +09:00
DongHyeonka aeb6033990 fix(ci): 라이선스 판정을 배포하는 의존성에 두고 빌드한 뒤에 돈다
pr / done (pull_request) Successful in 13m37s
문제: PR 단계를 job 하나로 접자 Trivy filesystem 검사가 Gradle 빌드 뒤에 돌게
됐고, 처음으로 lockfile의 라이선스를 읽었다(run 95). Trivy는 같은 기계의 Gradle
캐시에서만 lockfile의 라이선스를 읽는데, 예전의 따로 된 검사 job에는 캐시가 없어
「High/Critical 라이선스는 막는다」는 검사가 라이선스를 한 번도 본 적이 없었다.
보이게 되자 lockfile마다 SpotBugs·Checkstyle(LGPL), Error Prone dataflow(GPL+CPE),
Jakarta API(EPL/GPL 이중), org.reflections(WTFPL, Trivy 분류 forbidden) 등이 걸렸다.
대부분 배포하지 않는 빌드 도구·시험 구성이다. 한편 릴리스 이미지 검사는 jar의
라이선스를 읽지 못한다(run 62의 Licenses 칸이 모든 jar에서 비어 있다). 그래서 앞
커밋의 「앱 의존성 금지 라이선스는 이미지에서 막는다」도 빈 검사였다.

고른 방법(2026-11-11 소유자 결정 「배포하는 의존성의 금지 라이선스만 실패」):
- filesystem 검사가 `src/bootstrap/app/gradle.lockfile`의 runtimeClasspath 항목
  (기본 조립 jar에 실리는 것)만 골라 forbidden(CRITICAL)이면 실패한다.
- Gradle 캐시가 없으면 건너뛴다고 적는다. 캐시가 있는데 라이선스를 하나도 읽지
  못하면 빈 검사이므로 실패한다.
- 나머지 라이선스 결과(OS, 도구, 시험, restricted)는 보고만 한다. 이미지 검사의
  빈 라이선스 gate는 지우고 보고만 남긴다. 정책 문서를 실제 동작에 맞춘다.

버린 대안: lockfile 전체에 High/Critical을 그대로 막고 예외를 다는 것. Trivy의
라이선스 예외는 라이선스 이름 단위라 도구용 LGPL을 빼면 배포 의존성의 LGPL도 빠진다.

위험·한계: main.yml의 vulnerabilities job은 빌드하지 않아 라이선스 판정을 건너뛴다.
판정은 병합을 막는 PR 단계에 있다. runtimeClasspath 밖에서 jar에 실리는 것(다른
조립)이 생기면 grep 조건을 넓혀야 한다.

검증: runner PR `pr / done`(이 PR 본문에 적는다).
2026-11-12 02:26:58 +09:00
DongHyeonka 2c180b9059 ci(main): main과 integration 단계를 job 하나, Gradle 실행 한 번으로 돈다
문제: main push는 `main`(17.1분)과 `integration`(17.4분) 두 job을 차례로 돈다
(run 79, runner capacity 1). 두 job이 같은 모듈을 각자 설정·컴파일하고,
integration의 컨테이너 lane은 실서버 슬롯(ExclusiveRealServerLaneService)
하나를 차례로 쓰는 동안 나머지 worker가 놀고, main의 분석(testQualityCheck,
생성 명령 왕복의 안쪽 빌드)은 다른 job이라 그 시간에 겹치지 못한다.

고른 방법: `./gradlew :mainCheck :integrationCheck --continue` 한 줄을 `main` job이
돈다. strict lane 단계 선언에 `line`을 더해, 같은 job을 쓰는 단계가 선언한 한
줄을 나눠 쓸 수 있게 한다. 「단계마다 정해진 한 줄」 규칙은 그대로다: 두 단계
모두 그 정확한 줄을 요구하고, line에는 태스크 경로만 쓸 수 있고 자기 단계를
빼면 설정 단계에서 거절한다(TestKit 시험 셋). scripts/verify.sh의 main 단계도
같은 줄을 쓴다.

버린 대안: 한 job에 두 줄을 차례로 두기. mainCheck가 실패하면 integration이
돌지 않는다. 실서버 슬롯을 둘로 늘리기. 시간에 민감한 lane이 서로 겹쳐 불안정해진다
(그 서비스가 생긴 이유).

위험·한계: 컨테이너 lane이 main 단계의 CPU 작업과 겹친다. 시간에 민감한 system
lane은 지금도 main 단계 안에서 같은 겹침을 견디고, integration lane은 대부분
컨테이너 계약이다. 한 job이 길어져(예상 22~25분) timeout을 240분으로 둔다.

검증: build-logic 시험(desktop), verifyStrictLaneStages --dry-run, runner main 수동
실행의 main job 시간(이 PR 본문에 적는다).
2026-11-12 01:37:37 +09:00
DongHyeonka 000a59ed5f fix(redis): Redis 8 구성 lane이 search 모듈을 싣고 admin이 FT.INFO를 받는다
문제: 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 본문에 적는다).
2026-11-12 01:25:53 +09:00
DongHyeonka cfc80ae8d4 build(release): 기본 이미지를 noble로 올리고 이미지 검사를 취약점과 라이선스로 나눈다
pr / done (pull_request) Failing after 12m44s
문제: release 수동 실행(run 62)의 app-image-release가 Trivy에서 실패한다. 기본
이미지 eclipse-temurin:21-jre-jammy(ubuntu 22.04)에 고친 버전이 있는 OS 취약점
HIGH 7건(apt, libssl3/openssl, libbrotli1 등)과 OS 패키지 라이선스 HIGH 370건이
걸렸다. 앱 jar는 0건이다.

고른 방법(2026-11-11 소유자 결정 「권하는 안」):
- builder·runtime을 eclipse-temurin:21-{jdk,jre}-noble(ubuntu 24.04.5)의
  2026-10-29 digest로 올린다. noble 이미지에는 uid·gid 1000인 `ubuntu` 계정이
  있어, 앱 계정(uid 1000)을 만들기 전에 지운다. wget(healthcheck)과 C.UTF-8은
  noble에도 있다(desktop에서 확인).
- 취약점: OS·앱 모두 High/Critical이면 실패를 유지한다. 고친 버전이 있으면
  새 digest로 고치고, 아직 없는 것만 .trivyignore.yaml에 만료일 예외로 둔다.
- 라이선스: 앱 의존성(`--pkg-types library`)의 금지 라이선스(Trivy CRITICAL)만
  실패. OS 패키지 것을 포함한 나머지는 보고만 한다.
- 정책 문서(.github/dependency-vulnerability-policy.md)에 같은 내용을 적는다.

위험·한계: noble로 바꾸며 아직 고친 버전이 없는 High가 새로 보일 수 있다.
그때는 이유와 만료일을 달아 예외로 둔다. PR의 filesystem 검사는 그대로라
앱 의존성의 restricted(HIGH) 라이선스는 PR에서 여전히 막힌다.

검증: runner release 수동 실행의 app-image-release(이 PR 본문에 적는다),
desktop compose smoke(같은 Dockerfile로 qualification 이미지를 만든다).
2026-11-12 01:18:24 +09:00
DongHyeonka 6325b5183f fix(compose): root로 도는 CI에서도 Keycloak이 smoke lane secret을 읽는다
문제: compose smoke는 실행마다 Keycloak client secret을 0600 파일로 만든다.
Compose는 파일을 소유자·권한 그대로 붙이고 Keycloak은 이미지 사용자 uid
1000으로 읽는다. runner job은 root라 파일이 root 소유가 되고, Keycloak
entrypoint가 읽지 못해 exit 78로 끝난다. auth profile을 쓰는 8 lane이
run 52·63에서 모두 이것으로 실패했다. desktop은 만든 사람이 uid 1000이라
통과했다.

고른 방법: root면 파일을 uid 1000에게 넘기고 0600을 지킨다. uid 1000도
root도 아니면 같은 스크립트의 Mailpit 키처럼 0644로 둔다(값은 실행마다
새로 만들고, Git이 무시하는 폴더에 있고, 끝나면 지운다).

위험·한계: Keycloak 이미지의 사용자가 1000이 아니게 바뀌면 상수를 고쳐야
한다. 이미지 태그(26.0)를 올릴 때 확인할 것으로 주석에 적었다.

검증: runner main 수동 실행의 compose-smoke(이 PR 본문에 적는다).
2026-11-12 01:16:57 +09:00
DongHyeonka c611b06f03 feat(claude): 분야 전문가를 지식 스킬 열 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
pr / vulnerabilities (pull_request) Canceled after 0s
pr / done (pull_request) Canceled after 0s
pr / gradle (pull_request) Canceled after 8m18s
문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·
빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한,
동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그
문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게
합치는지도 정한 곳이 없다.

고른 방법(소유자 결정 2026-11-11 「W3 설계대로」):
- 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을
  만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 →
  검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이
  repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
  be-domain을 미리 싣고 lead 공통 양식으로 돌려준다.
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
  「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다).
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트
  AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와
  delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths·
  설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림,
  명단이 모든 전문가를 담음.
버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07
글이 반대하고, 설명이 모든 세션에 든다.

위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다.

검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는
조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
2026-11-11 23:19:44 +09:00
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 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
2026-11-11 22:15:42 +09:00
DongHyeonka 1388c06a9f refactor(layout)!: Gradle 루트와 계층 폴더를 옮긴다(옮기기만)
문제: 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절
2026-11-11 21:04:21 +09:00
DongHyeonka 74b0599f12 fix(ci): Redis topology 스크립트가 데몬 호스트 주소를 바르게 읽는다
redis-topology.sh는 job 컨테이너의 기본 게이트웨이(=Docker 데몬 호스트)를
/proc/net/route에서 awk로 읽었다. awk는 "0x.." 문자열을 0으로 읽어 주소가
0.0.0.0이 됐고, 포워더가 자기 자신에게 이어 붙어 "Too many open files"로
main.yml 수동 실행(run 52)의 redis-topology 11행이 모두 실패했다.

python3로 little-endian 16진수를 바르게 바꾸고, 주소가 없거나 0.0.0.0이면
그 자리에서 실패한다.

검증: 노트북에서 같은 계산이 기본 게이트웨이를 낸다. runner 재실행은
다음 main.yml 수동 실행에서.
2026-11-09 06:56:38 +09:00
DongHyeonka 4d778c2293 Merge remote-tracking branch 'origin/main' into claude/t2a-backend-ci-451e3b
pr / gradle (pull_request) Successful in 12m38s
pr / vulnerabilities (pull_request) Successful in 36s
pr / done (pull_request) Successful in 0s
메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은
이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길
측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로
두고 CI 절을 3.10(B-60~B-66)으로 미룬다.
2026-11-08 22:20:58 +09:00
DongHyeonka d46bab9659 ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
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을 따른다.
2026-11-08 21:55:43 +09:00
DongHyeonka 5af9415587 refactor(platforms)!: 메시징 플랫폼을 messaging-library 1.0.0으로 받고 지운다
템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(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절
2026-11-08 17:11:20 +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 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 d905980676 test(scripts): 하위 CLAUDE.md가 AGENTS.md만 가져오는지 보고 검사기 시험을 둔다
폴더 지역 규칙은 이제 src/**/AGENTS.md이고 옆의 CLAUDE.md는 `@AGENTS.md`
한 줄이다. 누가 CLAUDE.md에 규칙을 다시 쓰거나, AGENTS.md만 만들고
CLAUDE.md를 빠뜨리면 Claude Code가 그 폴더 규칙을 못 읽거나 규칙이 두 벌이
된다. 그리고 check-work-docs.py에는 자기 시험이 하나도 없었다.

- check-work-docs.py: src/**/AGENTS.md마다 옆 CLAUDE.md가 있고, 모든
  src/**/CLAUDE.md가 정확히 `@AGENTS.md`이며 옆에 AGENTS.md가 있는지 본다
  (build 출력 제외).
- scripts/tests/test_check_work_docs.py(13건): 최소 매뉴얼 통과, 지도 41줄·
  CLAUDE.md 11줄 실패, CLAUDE.md 첫 줄이 가져오기가 아니면 실패, 진입 경로가
  네 파일(AGENTS.md + CLAUDE.md + README + playbook) 합인지, 짝 셋, 하위
  규칙과 .claude/rules·skills·agents의 이력 ID, 로컬 .claude 상태는 안 봄,
  하위 규칙의 깨진 링크.
- gates.md 「링크 검사」: lychee 범위 밖 지침 문서는 check-docs.py `link`가
  보고, 손으로 돌리는 범위를 src/**/AGENTS.md로 바꿨다. docs/README.md의
  검사 설명에서 링크 문법 예를 뺐다(링크 검사기가 링크로 읽었다).

위험: 진입 경로 상한 350은 파일별 상한의 합(40+10+80+150=280)보다 커서
지금 구조에서는 닿지 않는다. 옛 상한(120+80+150=350)도 같았다. 상한은 그대로
두고 시험은 상한을 낮춰 계산식을 본다.

검증: unittest(전체), check-work-docs, check-docs, 같은 범위 --links 모두
rc=0(깨진 링크 0). 조건 다섯(짝 검사, 지도 상한, 진입 경로의 CLAUDE.md,
첫 줄 가져오기, .claude 문서 이력)을 하나씩 끈 사본마다 시험이 1~3건 실패했다.
2026-11-07 22:23:01 +09:00
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00
DongHyeonka 37c88fedd4 docs(ledger): 작업마다 예측과 실측을 쌓는 repo 장부를 둔다
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).

- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
  뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
  실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
  merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
  더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
  근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.

버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.

위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.

검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
2026-11-07 22:11:27 +09:00
DongHyeonka 67ecae2cc2 feat(skills)!: 새 기능과 desktop 게이트 절차를 모델이 부르는 스킬로 둔다
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).

- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
  실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
  → 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
  순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
  테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
  327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
  가리키기, skills-lock.json 없음)을 더했다.

버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).

위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.

검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.

BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
2026-11-07 22:10:08 +09:00
DongHyeonka c67c713177 feat(agents)!: Agent 금지를 풀고 결과만 돌려주는 서브에이전트 셋을 둔다
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).

- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
  판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
  띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
  않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
  4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
  직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
  조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
  따르는지 본다.

버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).

위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.

검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.

BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
2026-11-07 22:08:42 +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 2d43356136 ci(docs): 참조 검사가 디스크에만 남은 폴더를 있는 경로로 세지 않는다
참조 검사(reference)와 머리 블록의 「현재 정본」·「대체됨」 검사는 경로가
있는지를 파일 시스템(Path.exists)으로 본다. git mv는 옮긴 뒤 빈 옛 폴더를
디스크에 남긴다. 그래서 지운 폴더를 가리키는 살아 있는 문서가 노트북에서는
통과하고, 빈 폴더가 없는 새 checkout(PR workflow)에서만 실패한다. 알림 ADR을
옮길 때(39d4f248) 실제로 그랬다: docs/README.md에 쓴 옛 폴더 경로가 빈
docs/notification/adr/ 때문에 통과했고, 폴더를 지운 뒤에야 걸렸다.

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

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

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

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

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

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

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

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

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

검증(노트북): check-docs.py OK, 자기 시험 76 OK, check-work-docs.py OK.
2026-11-07 18:19:42 +09:00
DongHyeonka 80e7ef12a2 ci(docs): FROZEN에 목록에 없는 지문이 남으면 문서 검사가 실패한다
예외 목록은 줄기만 해야 하는데 빈틈이 있다. check-docs.py는 목록의
줄이 FROZEN에 있는지만 보고, FROZEN의 지문이 목록에 있는지는 보지
않는다. 그래서 번역해서 지운 줄의 지문이 FROZEN에 남고, 같은 줄을 다시
더해도 검사가 통과한다. 기준 커밋 03a313ed에서 이미 FROZEN 217개 중
9개가 목록에 줄이 없었다(앞 단계의 이름 바꾸기에서 남은 것).

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

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

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

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

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

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

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

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

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

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

BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로
옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로
바꾼다.
2026-11-07 18:10:33 +09:00
DongHyeonka a1d75a924c Merge branch 'claude/d2d-ops-docs-2-e40938' — MongoDB·파일서버·HTTP·web·Redis·WebSocket 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 159줄, D2d 49줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(61 → 12줄).
2026-11-07 18:07:21 +09:00
DongHyeonka ef029f2643 Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄).
2026-11-07 18:07:16 +09:00
DongHyeonka bec5079193 Merge branch 'claude/d2b-src-adr-d46d23' — 모듈 문서와 ADR 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(D2a 11줄, D2b 81줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(220 → 128줄).
2026-11-07 18:07:04 +09:00
DongHyeonka 54383d3f45 docs(storage): 파일 서버와 Object Storage 경계 문서를 한국어로 옮긴다
문제: `docs/storage-capability-boundary.md`가 영어였다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
  `:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
  `postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
  `postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
  rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
  `:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
  `everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
2026-11-07 17:56:34 +09:00
DongHyeonka 94ac85adf6 docs(notification-adr): 알림 결정 기록 본문을 한국어로 옮긴다
문제: `docs/notification/adr/`의 NOTIF-ADR-001~004는 머리 블록만
한국어이고 본문이 영어다. NOTIF-ADR-005는 한국어지만 상태 값과 절
제목 하나, 인용문이 영어로 남아 있다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0).
docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java`
— package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는
advanced 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00
DongHyeonka 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 f56a100528 ci(docs): 문서 지도와 루트 README 절을 문서 검사가 본다
문제: 「모든 문서 폴더가 `docs/README.md` 지도에 있다」와 「루트 README가 정해진 절을
가진다」(design-docs `conventions/docs-system.md` 7절 K5·K6)를 아무것도 지키지 않는다.
테스트 자원 `broken-readme.md`(일부러 깨뜨린 입력)를 살아 있는 문서로 보고 언어 검사
예외에 둔다.

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

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

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

검증:
- `python3 -m unittest discover -s scripts/tests` 65건 rc=0(새 시험 22건).
- 판정 조건 18개를 하나씩 끈 사본마다 자기 시험이 실패했다(rc=1).
- `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:18:19 +09:00
DongHyeonka 6fa4f825f2 ci(links): 기록 안의 죽은 외부 링크 넷을 lychee 제외 목록에 둔다
문제: lychee가 기록 문서 안의 외부 링크 404 넷으로 실패한다(mongodb write-concern,
aws credentials-chain `.html/`, aws SES SendEmail `.html/`, spring-graphql 1.3
request-execution). 넷 모두 `docs/design`·`docs/reviews` 안에 있고, 기록 본문은
고치지 않는다.

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

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

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

검증: `python3 scripts/check-repo-layout.py` rc=0. 정규식이 네 URL에만 맞고 `/` 없는
aws 두 URL에는 맞지 않는 것을 Python `re`로 확인했다.
2026-11-07 17:18:18 +09:00