Commit Graph
59 Commits
Author SHA1 Message Date
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
DongHyeonka 12d3f39893 docs(manual): 생성 명령 왕복 검사의 leaf 개수 대신 이름을 쓴다
문제: `docs/manual/01-generator.md`가 「./gradlew 5 leaf check」로 leaf 개수를 복사해
숫자 검사 예외에 있다.

고른 방법: `scripts/verify-feature-scaffold.sh`가 실제로 돌리는 leaf 이름(domain-core,
application-core, identifier, web, app-bootstrap)을 쓴다.

검증: `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:18:18 +09:00
DongHyeonka b3121a8626 docs(work): --rerun 예시를 실제 Gradle 경로로 쓴다
문제: `docs/work/operate.md`의 `--rerun` 예시가 `:a:test`·`:b:test`라 registry에 없는
Gradle 경로로 참조 검사 예외에 있다.

고른 방법: 실제 leaf `:domain-core:test`·`:application-core:test`로 바꾼다. 뜻은 같다.

검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0.
2026-11-07 17:18:18 +09:00
DongHyeonka 5a8414a371 docs(agents): 지운 build-tools 경로 대신 제거 표를 가리킨다
문제: `AGENTS.md`가 지운 `src/build-tools/`를 인라인 코드 경로로 적어 참조 검사 예외에
남아 있다.

고른 방법: 경로 대신 이름 `build-tools`와 그 삭제를 적은 `docs/capability-status.md`
「제거된 코드」를 가리킨다. 그 표에 이미 build-tools included build 삭제 행이 있다.

검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py` rc=0.
2026-11-07 17:18:18 +09:00
DongHyeonka af177de0aa docs(compose): Keycloak realm과 Redis ACL 안내를 한국어로 옮긴다
문제: `compose/keycloak/README.md`와 `compose/redis/acl/README.md`가 영어라 언어 검사
예외에 있다. ACL README의 파일 표에는 폴더에 있는 `sentinel-accounts.acl`이 없다.

고른 방법: 뜻을 그대로 옮긴다. 긴 문단은 목록으로 나눈다. 파일 표에
`sentinel-accounts.acl` 행을 더하고, 지금 이 파일을 `aclfile`로 읽는 compose 파일이
없다고 적는다(`git grep sentinel-accounts`가 이 README 밖에서 0건).

위험·한계: `sentinel-accounts.acl`을 지울지는 정하지 않았다.

검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움).
2026-11-07 17:18:18 +09:00
DongHyeonka 81f17b49e0 docs(github): PR 양식과 의존성 취약점 정책을 한국어로 옮긴다
문제: `.github/pull_request_template.md`와 `.github/dependency-vulnerability-policy.md`가
영어라 언어 검사 예외에 있다. 옮기면서 보니 코드와 다른 주장이 넷이다.
- PR 양식이 격리 테스트를 `flaky-quarantine.yaml`에 등록하라고 한다. 그 레지스트리는
  지웠다(`src/README.md` 「Trivy suppression과 플래키 격리」).
- 정책이 이미지 빌드·SBOM·서명·provenance를 「없는 job」이라 한다. 지금은
  `release.yml`에 있다.
- 정책이 patch·pin·digest 보안 갱신은 필수 검사 뒤 자동 병합할 수 있다고 한다.
  `renovate.json`은 모든 갱신이 `automerge: false`이고, lockfile은 사람이 다시 만든다.
- 정책이 `gradle.lockfile`을 「19개」라 한다. 지금 68개다.

고른 방법: 뜻을 그대로 옮기고 위 넷은 코드에 맞춘다. lockfile 개수는 숫자를 쓰지
않는다. 명령·경로·변수 이름은 원문으로 둔다.

검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움).
2026-11-07 17:18:18 +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 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 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 fc3cad7dcc ci(docs): 참조 검사가 루트 compose 폴더 경로도 본다
문제: 구조 정리로 저장소 루트에 `compose/`(개발 compose의 보조 파일)가
생겼다. 참조 검사는 `src/`, `docs/`, `scripts/`, `infra/`, `.github/`로
시작하는 인라인 코드만 본다. 그래서 살아 있는 문서가 가리키는
`compose/redis/acl/README.md` 같은 경로는 파일이 옮겨지거나 지워져도
걸리지 않는다. 지금 살아 있는 문서 여덟 개가 `compose/` 경로를 쓴다.

고친 방법: PATH_ROOTS에 `compose/`를 더한다. 정본 design-docs
`conventions/docs-system.md` K3는 「repo 경로」 전체를 말하고 접두사 목록을
정하지 않으므로 규칙 변경이 아니라 새 루트 폴더를 적용한 것이다. 지운
`infra/`는 남겨 둔다(다시 쓰이면 낡은 참조로 걸린다). 루트 파일
(`compose.yaml` 등)은 지금처럼 보지 않는다.

위험·한계: 새로 걸린 참조는 없다(지금 트리의 `compose/` 참조는 모두 있다).

검증: 새 시험 `test_a_missing_path_under_the_root_compose_folder_fails`가
고치기 전 실패(RED: 오류 목록이 비어 있음), 고친 뒤 43개 모두 통과.
check-docs.py rc=0(참조 걸림 7·예외 7).
2026-11-07 15:04:17 +09:00
DongHyeonka 8251616767 fix(docs): 지우고 옮긴 경로에 문서 검사 예외와 참조를 맞춘다
문제: 구조 정리와 문서 체계를 합친 트리에서 `python3 scripts/check-docs.py`가
23건으로 실패한다. 문서 검사는 구조 정리 전 트리를 기준선으로 만들어졌다.
- 예외 목록이 지운 파일(infra 아래 README 6개, 샘플 CLAUDE.md의 언어·숫자
  두 줄)을 가리킨다.
- 옮긴 문서 넷(infra/keycloak, infra/redis-sdk, infra/redis-sdk/acl,
  src/optional-platforms의 README)은 옛 예외 줄이 낡고 새 경로가 영어 문서로
  걸린다.
- `docs/jpa/security.md`는 구조 정리가 한국어 절(운영 DB 조건)을 더해 더는
  영어 문서로 판정되지 않는다.
- 살아 있는 문서 넷이 지운 `infra/`, `src/sample-portfolio`,
  `src/Dockerfile.sample`을 인라인 코드로 가리킨다.

고친 방법: 문서 체계 인계 노트의 「구조 정리와 합칠 때」를 따른다.
- 지운 파일과 더는 걸리지 않는 줄 아홉은 예외 목록에서 지운다.
- 옮긴 문서 넷은 예외 줄의 경로를 새 경로로 바꾸고, FROZEN에서 옛 줄의
  지문을 새 줄의 지문으로 바꾼다. FROZEN에 새로 더한 지문은 없다.
- 결정 색인의 두 행은 지운 경로 대신 지운 목록이 있는 업그레이드 안내
  B-49·B-50을 가리킨다(docs/README.md 「지운 경로는 upgrade/에 쓴다」).
- JPA 적응 표의 「저장소 현실」 칸과 리뷰 기준 18행에서 지운 경로를 뺀다.
- docs/README.md의 검사 설명은 지운 infra 폴더를 인라인 코드 밖에서 적는다.
  검사는 지운 infra/ 아래 경로를 계속 본다(다시 나타나면 낡은 참조다).

버린 대안: 결정 색인을 참조 검사 제외 목록(HISTORY_HOLDERS)에 넣기. 색인은
지금 결정을 찾는 곳이라 낡은 경로를 걸러야 한다.

위험·한계: `docs/jpa/security.md`는 영어 본문이 그대로 남아 있지만 판정에서
빠졌다. 번역 단계의 대상 목록에서 빠지지 않게 인계 노트에 적는다.

검증(노트북, 이 트리): check-docs.py rc=0(언어 걸림 173·예외 173, 참조 걸림 7·
예외 7, 숫자 걸림 28·예외 28), `python3 -m unittest discover -s scripts/tests`
42개 통과, check-work-docs.py rc=0.
2026-11-07 15:03:56 +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 2dd4acc6eb fix(compose): smoke matrix가 실패한 단계를 무시하지 않게 한다
문제: scripts/run-compose-runtime-smoke.sh --matrix는 lane마다
`if ( trap cleanup_lane EXIT; run_lane ... )`로 돈다. bash는 if 조건으로
도는 명령 안에서(함수·subshell 포함) set -e를 끈다. 그래서 명시적으로
`return 1` 하지 않는 단계 — 계약 검사, config, 이미지 build, create,
up --wait — 의 실패가 무시된다. 2026-11-07 최종 게이트에서 이미지 build가
실패했는데(7305ab38이 고친 결함), lane은 두 시간 전에 만든 이미지로
떠서 18개 모두 "passed"였다. --lane 모드는 run_lane을 직접 불러
영향이 없었다.

고른 방법: lane을 `set -e`를 켠 subshell에서 돌리고, 끝난 뒤 그 상태를
읽는다(if 조건으로 부르지 않는다). --lane 모드와 같은 동작이 된다.
버린 대안: 단계마다 `|| return 1`을 붙이기. 새 단계를 더할 때마다 다시
빠뜨리기 쉽다.

위험·한계: 지금까지 무시되던 단계의 실패가 이제 lane 실패가 된다.
그것이 목적이다.

검증(desktop ~/workspace/t1-final, ~/t1-layout-logs/):
- RED: 이미지 build가 깨진 트리(e13a2902)에서 이 수정만 얹고 off-local
  한 lane matrix: rc=1, "1 lane(s) failed: off-local"
  (red-smoke-buildfail.log). 수정 전 같은 트리의 18 lane matrix는 build
  실패를 무시하고 rc=0(final/final-smoke.log)
- 고친 뒤(트리 31466b8e = 이 커밋): run-compose-runtime-smoke.sh --matrix
  18 lane rc=0(693초). 이미지를 새로 빌드했고(build.log ERROR 0),
  모든 lane 컨테이너 재시작 0. 같은 트리에서 :ci, :mainCheck,
  scripts/bootstrap-local.sh, releaseCheck(두 빌드) rc=0
  (~/t1-layout-logs/final/final2-summary.txt)

Fixes: 50cd7154d0 ("refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다")
2026-11-07 14:50:47 +09:00
DongHyeonka e13a29024f ci(repo)!: 최상위 폴더 허용 목록 검사를 더한다
문제: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이
여덟으로 늘었고, 루트에는 compose 파일과 infra/가 쌓였다. 어느 커밋도
최상위 모양을 묻지 않았고 리뷰 기준에도 그 칸이 없었다.

고른 방법(소유자 결정 2026-11-07, 설계 10.3절): scripts/check-repo-layout.py
- 저장소 루트와 src/ 바로 아래의 추적 항목이 허용 목록 안에 있는가
- registry source_path가 허용된 src/ 폴더 아래인가
- (경고) compose·스크립트·compose 보조 파일을 아무 추적 파일도 가리키지
  않는가
를 본다. ci-quality-gates.yml quality-gates job에 한 단계로 붙인다.
Gradle 밖 스크립트다(문서·배치를 파싱하는 Gradle 검사를 두지 않는 정책).
버린 대안: registry에서 허용 폴더를 파생하기. 새 vendored 폴더를 registry
에 등록하는 것만으로 통과해, 막으려는 drift를 막지 못한다.

위험·한계: 참조 0 경고는 경로를 변수로 조립하는 workflow를 따라가지
못해 경고로만 둔다. 리뷰 기준·playbook 문장은 매뉴얼 보강 작업이 넣는다.

검증:
- 노트북·desktop: python3 scripts/check-repo-layout.py rc=0, 경고 0
- 일부러 infra/, src/messaging/, 고아 compose/orphan.sh를 둔 임시 저장소:
  rc=1, 실패 3건과 경고 1건
- desktop(트리 c7cacf54): :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest rc=0, :verifyStrictLaneStages --dry-run rc=0
- check-work-docs.py rc=0
- 업그레이드 안내 B-50~B-52의 근거 칸을 커밋 해시로 채운다

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 10.3
BREAKING CHANGE: 저장소 루트나 src/에 허용 목록 밖의 최상위 폴더를 둔 파생 서비스는 PR 게이트가 실패한다. docs/upgrade/2026-11-maturity-review.md B-53.
2026-11-07 13:09:05 +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 1c00f89765 ci(docs): 문서 언어·머리 블록·참조·숫자를 PR에서 검사한다
문제: 살아 있는 문서의 언어, 기록의 상태 표시, 인라인 코드 경로, 복사한
버전·개수를 아무 검사도 보지 않는다. lychee는 마크다운 링크만 보는데
경로 대부분은 인라인 코드로 쓰여 있고, leaf CLAUDE.md는 Spring Boot
버전을 4.0.0으로 적어 둔 채 낡았다.

고른 방법: Gradle 밖 scripts/check-docs.py 하나에 검사 넷을 둔다.
- language: 살아 있는 문서와 ADR 본문이 한국어인가. 판정은 보고 언어 훅
  H11과 같다(코드·명령·경로·인용을 빼고 영어 낱말 3개 이상, 한글 비율
  0.3 미만이면 영어).
- head: 기록·ADR 맨 위 머리 블록의 칸, 종류별 상태 어휘, 날짜, 한국어
  요약, 현재 정본·대체됨 경로.
- reference: 인라인 코드 안 src/·docs/·scripts/·infra/·.github/ 경로와
  Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, 「> 이력」 인용,
  제거 표, upgrade/는 건너뛴다. leaf 기준 경로는 어느 파일의 끝부분과
  맞으면 있다고 본다.
- number: Spring Boot x.y.z와 leaf 개수 문장.
예외 목록(scripts/check-docs-exceptions.txt)은 2026-11-07 기준선 217줄이고
줄기만 한다. 줄마다 sha256 지문이 스크립트의 FROZEN에 있어야 해서 목록에
새 줄을 더하면 실패하고, 더는 걸리지 않는 줄을 남겨 두면 실패한다.
workflow docs-check.yml이 PR마다 경로 필터 없이 자기 시험과 검사를 돌린다.
코드에서 파일을 지우는 변경이 문서를 낡게 만들기 때문이다. 같은 커밋에서
지도 CLAUDE.md의 Spring Boot 버전 복사를 정본 가리키기로 고쳤다.

버린 대안: 예외 목록 하나에 「늘리지 않는다」는 약속만 두는 방식(테스트의
KNOWN_DEVIATIONS와 같은 꼴)은 brief가 요구한 「더하면 실패」를 기계로 막지
못한다. 기준선을 git 이력(merge-base)과 비교하는 방식은 얕은 checkout에서
깨진다. 검사를 link-check.yml에 더하는 방식은 그 workflow가 docs 경로에만
걸리고 repository-contract 테스트가 trigger를 고정한다. CI 재편 때 단계
workflow로 접는다.

위험·한계: 타입 이름 검사(지운 클래스 이름)는 넣지 않았다. 외부 타입과
구분하려면 git 전체 이력이 필요하다. 경로 검사는 루트 폴더로 시작하는
경로만 보므로 src/ 기준 상대 경로(adapter/outbound/...)는 보지 않는다.
leaf 개수 규칙은 설계 문서의 개수 같은 정당한 숫자도 잡을 수 있다(지금
generator 출력 예 하나가 예외 목록에 있다). 구조 정리가 src/messaging 등을
옮기면 예외 줄의 경로가 바뀌므로 그 병합에서 FROZEN을 함께 고쳐야 한다.
레지스트리 yaml 설명 칸의 언어는 보지 않는다.

검증: python3 -m unittest discover -s scripts/tests 42개 통과. 변이 시험:
기준선 확인·낡은 예외 확인·언어 판정·이력 인용 건너뛰기·소스 세트 이름·
끝부분 대조·상태 어휘를 하나씩 끄면 해당 시험이 실패했다.
python3 scripts/check-docs.py rc=0(language 181·reference 7·number 29가
모두 예외, head 0), check-work-docs.py rc=0.
2026-11-07 12:26:37 +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 51230caf62 fix(scripts): 색인 절을 총괄이 쓰는 라운드의 색인 검사를 --extra-index로 한다
문제: 독립 리뷰어 둘이나 여러 리뷰 세션이 한 라운드를 나눠 보면, 정본 리뷰어는
영역 문서를 리뷰 폴더에 커밋하지만 README 색인 절은 총괄이 쓴다. 그래서 정본
리뷰어가 커밋한 트리의 색인 검사는 반드시 rc=1인데, improve.md는 리뷰어에게
rc=0을 요구했다(round8 발견 RR8-06-01). 두 규칙을 함께 지킬 수 없었다.

고른 방법: check-review-index.py에 --extra-index <파일>을 더했다. 리뷰어가
보고에 둔 색인 표 파일을 색인의 일부로 센다. improve.md 4.1절 7·8단계와 5절,
delegate.md 4.1절, 결정 색인 「리뷰 README 분담」에 쓰는 법을 적었다. 버린 안:
리뷰가 권한 "보고 표를 붙인 README 임시 사본" 절차 — 복사·붙이기 단계가 늘고
같은 대조를 손으로 한다. 정본 리뷰어가 README 색인 절을 먼저 쓰는 안 — 결정
「리뷰 README 분담」을 뒤집는다.

위험·한계: --extra-index는 넘긴 파일 전체를 색인으로 읽는다. 표만 담은 파일을
넘겨야 한다(노트 전체를 넘기면 본문에 나온 ID도 색인으로 센다). 매뉴얼에
"색인 표만 담은 파일"로 적었다.

검증(트리 3c305d7a, desktop 로그 ~/manual-gap-fix-2-logs/B-*):
- RED: 정본 리뷰어 커밋 27260ad0의 리뷰 폴더에 옵션 없이 rc=1(180 중 172)
- GREEN: 리뷰어 A의 색인 표를 --extra-index로 넘기면 rc=0(180/180)
- 지금 트리 docs/reviews/2026-11-03-rereview rc=0(182/182), 없는 파일을
  넘기면 rc=1
- check-work-docs.py 기본·--history docs/manual·--links rc=0

Refs: docs/reviews/2026-11-03-rereview/round8/06-manual-scripts.md RR8-06-01
2026-11-07 07:02:09 +09:00
DongHyeonka 6b253c6c75 docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.

고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.

위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).

검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
  lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
  'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
  rc=0(3건)
2026-11-07 07:02:09 +09:00
DongHyeonka 8b979ac171 Merge remote-tracking branch 'origin/claude/t4-2-manual-history-ids-9ac57c' into claude/integration-r8-a4196a
# Conflicts:
#	docs/work/evidence.md
#	scripts/check-work-docs.py
2026-11-07 01:41:24 +09:00
DongHyeonka 6dd9ef7613 fix(scripts): 이력 검사가 "2~3라운드 동안" 같은 횟수를 잡지 않게 한다
문제: 앞 커밋에서 더한 한국어 라운드 번호 패턴이 "1라운드"(지난 라운드
하나의 이름)와 "2~3라운드 동안"(라운드 수)을 가르지 못한다. 확인 리뷰를
독립 리뷰어 둘로 하는 소유자 결정을 delegate.md에 옮기다가 "2~3라운드
기록이 쌓이면"이 이력 ID로 잡혀 기본 검사가 rc=1이 됐다.

고른 방법: 범위 기호(~, -) 바로 뒤의 숫자와, 뒤에 동안·마다·씩·간이
붙는 경우를 뺀다. 버린 대안: 문서에서 "라운드 두세 번"으로 돌려 쓰기.
다음에 쓰는 사람이 같은 오탐을 다시 만난다.

위험·한계: "3라운드 뒤"처럼 다른 낱말이 붙는 횟수는 아직 이력으로
잡는다. 그때는 문장을 고치거나 패턴에 낱말을 더한다.

검증:
- 패턴 시험 19건(보통 문장 11, 이력 8)이 모두 기대대로 나왔다
- python3 scripts/check-work-docs.py rc=0, 본문 이력 0줄
- --history docs/manual 결과는 16줄 그대로(rc=1)
2026-11-07 00:27:59 +09:00
DongHyeonka b7d1310459 fix(scripts): 이력 검사가 앞말 없는 번호 목록·리뷰 영역·묶음 번호를 잡는다
문제: check-work-docs.py --history는 리뷰·라운드 낱말 바로 뒤의 NN-NN만
발견 번호로 본다. 그래서 앞말 없이 나열한 "(05-01, 04-01, 06-01)",
"리뷰 01 영역 5.2절", "sample P30 결정"을 놓친다. 2026-11-07 docs/manual
이력 걷어내기에서 검사가 찾은 16줄을 고친 뒤 docs-writing.md 9절대로
grep으로 다시 읽으니 이 꼴 3줄이 더 있었다.

고른 방법: 패턴 셋을 더한다.
- 쉼표+공백이나 가운뎃점으로 이은 NN-NN 둘 이상. 콜론 뒤 줄 범위
  ("Foo.java:10-12,20-24")와 공백 없는 쉼표 범위는 잡지 않는다
- "리뷰 NN 영역", "NN 영역 N.N절"
- 2026-09-25 리뷰 후속 묶음 번호 P10~P49와 "W3-P30" 꼴
버린 대안:
- 홀로 선 NN-NN 하나까지 잡기. 장 번호·범위 같은 보통 숫자가 걸린다
- P 뒤 두 자리를 모두 잡기. P95·P99 같은 백분위수가 걸린다

위험·한계: 검사는 여전히 아는 꼴만 잡는다. P1~P9 묶음 번호는 우선순위
P0~P3과 겹쳐 잡지 않는다. 문서가 자기 목록에 P10~P49 번호를 붙이면
이력이 아니어도 잡는다(docs/study/graphql-walkthrough.ko.md의 할 일
번호 P10·P11). 지금 검사 대상인 docs/work 본문과 docs/manual에는 그런
줄이 없다. 이 커밋만 있으면 --history docs/manual이 19줄, rc=1이다.
다음 커밋이 그 19줄을 걷어낸다. 기본 모드(docs/work 본문, 루트
CLAUDE.md)는 0줄 그대로다.

검증(desktop worktree, 다음 커밋까지 얹은 트리 8ff82a67과 같은 스크립트):
- 기준 커밋 73d39212의 docs/manual: 옛 스크립트 16줄, 새 스크립트 19줄.
  더 잡은 3줄은 03-placement.md:40·:54, 05-idempotency.md:93이다
- 오탐 시험 14줄: 보통 문장 8줄(p95·P99, 콜론 뒤 줄 범위, 날짜 쌍,
  홀로 선 번호, 장 번호)은 안 잡고 이력 6줄은 잡았다
- 노트북에서 docs/reviews 밖 *.md에 새 패턴을 돌려 걸린 65줄을 읽었다.
  위 할 일 번호 4줄 말고는 모두 실제 이력 번호였다
- 기본 모드 rc=0, 본문 이력 0줄
2026-11-07 00:24:58 +09:00
DongHyeonka b872b0ea93 fix(scripts): 이력 검사가 "리뷰 02-01"·"1라운드 06-01" 꼴을 잡는다
문제: check-work-docs.py --history는 날짜 접두어(MMDD/), RR 접두어,
묶음 이름, round 폴더, 번호만 쓴 결정, 커밋 sha만 이력 ID로 본다.
그래서 "리뷰 02-01 결정", "1라운드 06-01·06-03", "리뷰 README 13절"처럼
날짜 접두어 없이 쓴 리뷰 번호를 놓친다. 2026-11-06 docs/manual 이력
걷어내기 시험에서 --history가 0을 냈는데, 손으로 찾으니 16줄이 남아
있었다.

고른 방법: 패턴 셋을 더한다.
- 리뷰·라운드·review 낱말 뒤 20자 안에 홀로 선 NN-NN. 2026-11-01 같은
  날짜의 일부는 홀로 선 번호가 아니라 잡지 않는다
- 한국어 라운드 번호(1라운드, 라운드6)
- 리뷰 README 절 번호(리뷰 README 13절)
버린 대안: 앞말 없이 모든 NN-NN을 잡기. 장 번호·시각 범위 같은 보통
숫자까지 잡아 오탐이 많다.

위험·한계: 검사는 아는 꼴만 잡는다. 다른 꼴은 걷어낸 뒤 grep으로 한 번
더 읽는다(docs-writing.md 자주 하는 실수). 이 커밋 뒤 --history
docs/manual은 16줄을 내고 rc=1이 된다. 그 16줄은 이번에 고치지 않는다.
다음 cold-read 시험 과제다. 기본 모드(docs/work 본문, 루트 CLAUDE.md)는
0줄 그대로다.

검증:
- 고치기 전 python3 scripts/check-work-docs.py --history docs/manual
  결과 0줄, rc=0
- 고친 뒤 같은 명령 결과 16줄, rc=1. 2026-11-06 시험 세션이 손으로 찾은
  16줄과 같다
- 오탐 시험 12건(보통 문장 7, 이력 5)이 모두 기대대로 나왔다
- 기본 모드 rc=0, 본문 이력 0줄. desktop worktree에서도 같다
2026-11-06 23:18:33 +09:00
DongHyeonka d35bbb614b feat(scripts): 작업 매뉴얼 검사와 리뷰 색인 대조 스크립트를 더한다
문제: 옛 개선 매뉴얼은 진입 경로가 717줄이었고 본문에 지난 리뷰 ID가 든
줄이 많아, 이력을 모르는 세션은 근거를 따라가지 못했다. 이것을 사람 눈으로만
지키면 다시 늘어난다. 리뷰 색인도 손으로 옮기다 발견 5건이 빠져 어떤 수정
묶음에도 배정되지 않은 적이 있다(원래 리뷰 124건이 색인에는 119건).

고른 방법: Gradle 밖 Python 스크립트 두 개를 둔다(2026-11-06 소유자 결정 D6:
이 repo는 문서를 파싱하는 Gradle 검사를 두지 않는다).
- check-work-docs.py: 지도(CLAUDE.md)와 docs/work/의 분량 상한(지도 120,
  README 80, playbook 150, 진입 경로 350), playbook 9칸 뼈대, 「자주 하는
  실수」 10줄, 본문 이력 ID 0(evidence.md와 reference/의 두 색인 문서는 제외),
  상대 링크를 본다. --links, --history 모드로 다른 문서에도 쓴다.
- check-review-index.py: 리뷰 폴더의 영역 문서 제목에 있는 발견 ID가 README
  색인에 모두 있는지 본다. 범위(A~B)와 이어 쓰기(A·07)를 읽고, NN- 자리표시자를
  잡는다.
정규식은 re.ASCII로 쓴다. Python의 \w·\b가 한글을 단어 문자로 봐서
"RR6-01-07과" 같은 표기를 놓쳤다.
버린 대안: document-contract Gradle lane(이 repo 원칙과 충돌), 검사 없이
cold-read 시험에서만 확인(매번 사람이 세야 한다).

위험·한계: check-work-docs.py가 보는 docs/work/는 다음 커밋에 들어온다. 이
커밋만으로는 "missing"으로 실패한다. 이력 ID 패턴은 이 repo가 쓴 형식만 안다
(MMDD/, RR<n>-, 묶음 이름, round<n>, 번호만 쓴 결정, 커밋 sha). 색인 검사는
"이름이 있나"만 보고 고쳤는지는 보지 않는다.

검증
- check-review-index.py docs/reviews/2026-11-01-maturity-review
  --index-heading "12. 발견 색인": 124/124, rc=0
- 같은 폴더를 사고 시점 34565130에서 꺼내 돌림: NN-10~NN-14 5건, rc=1
- check-review-index.py docs/reviews/2026-11-03-rereview: 157 중 135, rc=1
  (README가 ID 대신 내용·건수로 적은 22건)
- check-work-docs.py를 일부러 망가뜨린 사본 18가지에 돌림: 이력 ID 7형식,
  분량 3종, 뼈대, 실수 줄 수, 깨진 링크, 빠진 파일은 rc=1, ID가 허용된 파일과
  "결정 3개" 같은 개수 표현은 rc=0
2026-11-06 19:58:15 +09:00
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00
DongHyeonka 5786126cfa fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
  바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
  httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태

Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 17:01:54 +09:00