Commit Graph
131 Commits
Author SHA1 Message Date
DongHyeonka 4fc586478c docs(claude): 진입 문서에 단독 번호로 남은 이력 ID를 내용과 날짜로 바꾼다
AGENTS.md와 src/**/CLAUDE.md는 본문에 지난 리뷰 ID를 두지 않는다
(docs/work/README.md 8절). 번역한 CLAUDE.md 넷에 짝 하나짜리 번호가
남았다: persistence-jpa·app-bootstrap의 「07-08」, grpc의 「11-M9」,
messaging의 「06-01 수정」. check-work-docs.py는 단독 NN-NN을 일부러 잡지
않으므로(범위·절 번호와 구별할 수 없다) 통과했다(번역 묶음 D2b가 넘긴 것).

ID 대신 그 발견의 내용과 날짜를 적었다. 원래 ID와 근거 리뷰 파일은
docs/work/evidence.md 10절 끝에 행 넷으로 남겼다(앞 행들과 같은 칸).

검증(노트북): check-work-docs.py OK, --history(바꾼 파일) 이력 ID 0,
check-docs.py OK. 이 넷을 읽는 테스트는 없다(git grep 'CLAUDE.md' -- '*Test.java').
2026-11-07 18:27:30 +09:00
DongHyeonka 44779a0625 docs(web): web README의 없는 오류 코드와 지운 IP 모드 주장을 코드에 맞춘다
번역 묶음(D2b)이 확인하지 못하고 넘긴 대문자 식별자 넷을 코드와 대조했다.
MAX_CONCURRENT_STREAMS(RFC 9113 HTTP/2 설정 이름)와 DEFAULT_MAX_PAGE_SIZE
(Spring Data 상수)는 바깥 이름이라 맞다. 둘은 틀렸다.

- 예외 대응 표의 MaxUploadSizeExceededException 행이 「multipart 전용
  413(UPLOAD_SIZE_EXCEEDED)은 이 영역의 책임 — 병합 후 정제」라고 적는다.
  그런 오류 코드는 레지스트리에도 코드에도 없다.
  GlobalExceptionHandler.handleMaxUploadSizeExceededException은 multipart와
  JSON 본문 모두 PAYLOAD_TOO_LARGE(413)로 답한다. 그대로 적었다.
- 「클라이언트 IP」 절이 지운 모드의 이름(FORWARDED_HEADERS_TRUSTED)을 지금
  있는 것처럼 인라인 코드로 적는다. 이름을 빼고, 지운 사실은 제거 표
  (docs/capability-status.md 「제거된 코드」)를 가리킨다.

검증(노트북): check-docs.py OK. 이 README를 읽는 테스트는 없다
(git grep 'inbound/web/README').
2026-11-07 18:27:30 +09:00
DongHyeonka 2af465e71c docs(src): src/README를 「~한다」체로 맞추고 Compose 최소 버전은 정본을 가리킨다
src/README.md가 「~합니다」체다(끝맺음 215곳, 「~한다」는 번역 묶음이 고친
두 문장뿐). docs/README.md 「문서 수명과 언어」는 살아 있는 문서의 문체를
「~한다」로 정하고 한 문서 안에서 섞지 않게 한다. 번역 묶음(D2a)이 이
문서의 영어 제목·문장만 맡아 문체는 범위 밖으로 넘겼다.

- 끝맺음만 바꿨다. 낱말 111개를 하나씩 대응표로 바꾸고(합니다 → 한다,
  입니다 → 이다·다, 형용사는 하다·다: 견고하다, 필요하다, 다르다, 크다,
  쉽다, 같다, 「있지 않습니다」 → 「있지 않다」, 「~세요」 → 「~한다」),
  바뀐 195줄을 한 줄씩 읽었다. 줄 수(577)와 다른 글자는 그대로다.
- 「Docker Compose 최소 버전 `2.24.4`」가 정본
  (compose-profile-contracts.json의 minimumComposeVersion)을 옆에 적고도
  값을 복사했다. 값을 지우고 정본 키를 가리킨다.

버린 대안: 문체를 그대로 두고 규칙 쪽에 예외를 두기. 한 파일만 다른
문체를 허용할 근거가 없다.

이 문서를 글자 그대로 읽는 테스트는 없다(git grep 'src/README' — 링크
검사 범위 목록 테스트 하나만 경로를 적는다).

검증(노트북): check-docs.py OK, 「~니다」 끝맺음 남은 수 0(「아니다」 제외).
2026-11-07 18:27:30 +09:00
DongHyeonka 39d4f24803 docs(adr)!: 알림 결정 기록을 docs/adr로 옮긴다
결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다.
문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이
모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지
보기」도 두 곳을 가리킨다.

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

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

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

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

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

BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로
옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로
바꾼다.
2026-11-07 18:10:33 +09:00
DongHyeonka a1d75a924c Merge branch 'claude/d2d-ops-docs-2-e40938' — MongoDB·파일서버·HTTP·web·Redis·WebSocket 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 159줄, D2d 49줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(61 → 12줄).
2026-11-07 18:07:21 +09:00
DongHyeonka ef029f2643 Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄).
2026-11-07 18:07:16 +09:00
DongHyeonka bec5079193 Merge branch 'claude/d2b-src-adr-d46d23' — 모듈 문서와 ADR 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(D2a 11줄, D2b 81줄, 겹침 0).
기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(220 → 128줄).
2026-11-07 18:07:04 +09:00
DongHyeonka 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 6583cc2e02 docs(fileserver): 파일서버 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며
본 주장 중 지금 코드와 다른 것이 있었다.
- design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`·
  content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로
  없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`·
  `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만
  지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다.
  지운 reactive transport가 아직 스트리밍한다고 했다.
- security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다
  (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는
  지금 `HttpContentDispositionFactory`다.
- upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로
  읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이
  Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는
  `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다.
- operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope).

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

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

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

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

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로
문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
2026-11-07 17:29:57 +09:00
DongHyeonka b169ad88bf docs(src): 모듈 문서의 ArchUnit 규칙 이름을 코드 상수 이름에 맞춘다
문제: 모듈 문서가 ArchUnit 규칙을 `domain_is_pure`,
`query_ports_do_not_leak_domain_jpa_or_web_types` 같은 소문자 이름으로
가리킨다. 지금 코드의 규칙은 `DOMAIN_IS_PURE` 같은 대문자 `static final
ArchRule` 상수이고 소문자 이름은 운영 코드 어디에도 없다. 문서의
이름으로 규칙을 찾으면 아무것도 나오지 않는다.

방법: `src/**`의 CLAUDE.md와 README에서 backtick으로 쓴 소문자 규칙
이름 중, 같은 이름의 대문자 ArchRule 상수가 코드에 있는 것만 그
상수 이름으로 바꾼다(31곳, 파일 8개). 지운 규칙을 적은 곳
(`inbound_port_implementations_do_not_declare_keyed_idempotency`)은
지웠다는 기록이라 그대로 둔다.

위험: shared-contract 운영 코드 Javadoc 두 곳
(`DomainContextPropagator`, `ThreadLocalDomainContextPropagator`)이 아직
소문자 `no_inheritable_thread_local`을 쓴다. 이 작업 범위(문서) 밖이라
고치지 않았다.

검증: 바꾼 이름마다 `static final ArchRule <NAME>` 또는 `<NAME> =`가
코드에 있는지 스크립트로 대조했다. python3 scripts/check-docs.py rc=0,
check-work-docs.py rc=0.
2026-11-07 17:25:37 +09:00
DongHyeonka 8813b02e54 docs(adapter-outbound): outbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가
영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전
(4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열·
표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을
가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다:
identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는
hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap
`IdempotencySettings`」를 실제 위치 `composition:idempotency`로,
redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로
mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는
지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다
(MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한
곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가
아직 영어라 원문 제목으로 둔다.

위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면
낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음
커밋에서 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄
10개 지움, src/** number 줄 0), check-work-docs.py rc=0,
--links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:24:33 +09:00
DongHyeonka 145ae00f90 docs(src): src/README의 영어 제목과 코드와 다른 주장을 고친다
문제: `src/README.md`에 영어 제목(「Local bootstrap」「App identity」 등)과 영어
문장이 남아 있다. 지운 게이트 표 `.github/ci-gate-matrix.yml`과 검사기
`.github/scripts/verify-gate-matrix.sh`를 지금 있는 것처럼 인라인 코드로 적어 참조
검사의 예외 줄 둘이 남아 있다. 코드와 다른 주장도 둘이다.
- `SPRING_PROFILES_ACTIVE`를 「보통 local | dev | stage | prod」라 한다. registry
  `allowed_values`와 `RuntimeEnvironment`는 local·dev·prod뿐이다.
- 추적 샘플 비율 기본값에 「staging = 0.10」이 있다. `TracingSampleRateResolver`는
  PROD 0.01, LOCAL·DEV 1.0만 안다.

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

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

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

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

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

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

검증: `python3 scripts/check-docs.py` rc=0,
`python3 scripts/check-work-docs.py --links README.md` 깨진 링크 0.
2026-11-07 17:18:18 +09:00
DongHyeonka 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 5ab1b4182c test(messaging): 대기 허가 테스트가 실행 순서에 따라 갈리지 않게 한다
문제: `MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned`가
desktop 부하가 높을 때 가끔 실패한다(구조 정리 게이트에서 부하 7에 한 번,
이번에 부하 24~27에서 20번 중 한 번).

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

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

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

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

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

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

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

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

Fixes: 8d69e599a3 ("refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다")
2026-11-07 14:34:22 +09:00
DongHyeonka 1ed683ffdb fix(messaging): 인증 증거를 digest로 고정한 Kafka 이미지로 다시 만든다
문제: :messaging:messaging-kafka:verifyMessagingCertificationEvidence가
rc=1이다. 커밋된 증거 broker-certification-evidence.jsonl(2026-08-24)의
brokerImage는 apache/kafka:4.1.0인데, 2026-11-03 container-images.properties
가 kafka 이미지를 digest로 고정한 뒤 레인은
apache/kafka@sha256:bff074a5…로 돈다. 시나리오 넷의 결과는 같고 이미지
이름만 다르다. 이 workflow는 messaging 경로가 바뀔 때만 PR에서 돌아
그동안 드러나지 않았다.

고른 방법: 게이트가 안내하는 대로 이번 실행이 만든 jsonl로 커밋된
파일을 바꾼다(증거는 실행 기록이다). 손으로 이미지 이름만 고치지
않는다.

위험·한계: gitCommit 칸은 레인을 돌린 트리의 커밋(8d69e599, 이 파일만 다르다)을
가리킨다. 레인은 실 Kafka 컨테이너와 Toxiproxy가 있는 곳에서만 돈다.

검증(desktop, ~/t1-layout-logs/):
- 고치기 전(트리 2b3354a4): verifyMessagingCertificationEvidence rc=1.
  claimed/produced 차이는 brokerImage(apache/kafka:4.1.0 ↔
  apache/kafka@sha256:bff074a5…)뿐이고 시나리오·결과·testId는 같다
- 고친 뒤(트리 4b304c59): :messaging:messaging-kafka:verifyMessagingCertificationEvidence
  -PcertificationCommit=8d69e599… :messaging:messaging-testkit:check
  :messaging:messaging-kafka:check rc=0 (messagingCertificationTest 실행)
2026-11-07 13:07:47 +09:00
DongHyeonka 8d69e599a3 refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.

고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
  registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
  그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
  주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
  이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
  registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
  buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
  경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
  release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).

위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.

검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
  첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
  → 경로를 고침. 두 번째 rc=1: messaging-policy
  MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
  (2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
  3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
  --dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
  :adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
  이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.
2026-11-07 13:04:54 +09:00
DongHyeonka 50cd7154d0 refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
  보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
  .local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
  죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
  겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Refs: docs/reviews/2026-11-03-rereview/README.md 19.4절 끝(개선 제안), 19.5절
2026-11-07 08:22:59 +09:00
DongHyeonka ba189869e8 fix(lock): 락 timeout runbook이 있는 정보로 경합과 보유자를 찾게 한다
문제(round8 확인 리뷰 RR8-01-02):
- 락 timeout이 4xx carrier가 된 뒤로 어느 락이 막혔는지 서버 어디에도
  남지 않는다. 그런데 runbook은 lock.acquisition metric에서 락 이름과
  시간을 보라고 하고(metric은 outcome tag 하나뿐인 counter), 없는
  integration_lock 테이블에서 보유자를 찾으라고 한다(테이블은 INT_LOCK,
  LOCK_KEY는 key가 아니라 key의 UUID). 예외 Javadoc과 application-core
  README는 메시지가 "서버 로그 전용"이라 적지만 그 메시지를 남기는
  로그가 없다.

고른 방법(리뷰 권장안):
- runbook Symptoms·Diagnosis를 있는 정보로 다시 쓴다: 로그가 없다는 것,
  경합 비율은 lock.acquisition{outcome} 비교(JDBC 락에만, 이름·시간
  없음), INT_LOCK의 보유자 목록, 코드에서 아는 key의 보유자(key를
  Spring Integration과 같은 name-based UUID로 계산하는 SQL).
- 두 SQL에 runbook-sql 표시를 달고 postgresqlDistributedLockIntegrationTest
  가 runbook 파일에서 읽어 실 PostgreSQL에서 락을 잡은 채 돌린다(lane
  입력에 runbook을 넣어 문서를 고치면 lane이 다시 돈다).
- 예외 Javadoc·README의 "서버 로그 전용"을 "클라이언트에 보내지 않고,
  어느 로그에도 남지 않는다. 필요하면 호출자가 key()를 남긴다"로 고친다.
- 버린 안: 락 timeout에 WARN 한 줄(key digest, 대기 시간)을 남기기 —
  로그 정책을 바꾸는 소유자 결정이고, 템플릿은 tryAcquire를 부르지 않는다.

위험·한계:
- runbook은 status: stub 그대로다. Action·Escalation 본문은 도메인을
  고른 서비스가 쓴다.
- key가 UUID 문자열이면 Spring Integration은 그대로 쓰므로 계산 SQL이
  맞지 않는다. runbook은 "코드에서 아는 key"만 말한다.
- OutboxRunbookSql을 그대로 쓴다. 그 이름을 바꾸는 수정(RR8-03-03)과
  합칠 때 이 테스트의 참조도 함께 바뀌어야 한다.

검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- RED(문서의 주장을 단언한 임시 탐침, 기준 3eb3b067 + 탐침, 커밋 안 함,
  트리 a675c244):
  - "integration_lock 테이블에서 보유자를 찾는다": 락을 잡은 채
    SELECT count(*) FROM integration_lock → postgresqlDistributedLock
    IntegrationTest 7건 중 1건 실패, BadSqlGrammarException(relation
    "integration_lock" does not exist). red/R6-jpa-table-claim.log
  - "lock.acquisition metric에서 락 이름과 시간을 본다": timeout 뒤
    outcome 밖의 tag가 있어야 한다 → MeteredDistributedLockTest 11건 중
    1건 실패(tag 없음). red/R5-jpa-metric-claim.log
- GREEN(이 커밋 트리 fc5eae5a):
  - :application-core:check :adapter:outbound:persistence-jpa:check rc=0,
    test 1,089건 실패 0(skip 19는 application-core의 이전부터 것). 같은
    worktree의 앞 실행(green/C1-check.log, 이 두 leaf의 입력이 같은 트리
    acf42e98)으로 UP-TO-DATE. green2/C1-check.log
  - :adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest
    rc=0, 8건(runbook의 두 SQL 블록을 파일에서 읽어 실행하는 새 테스트 2건
    포함) 실패 0. green2/C2-lock-lane.log
  - :app-bootstrap:documentContractTest rc=0, 67건(RunbookCoverageContract
    Test 포함). green2/C3-doc-contract.log

Refs: docs/reviews/2026-11-03-rereview/README.md 19절 RR8-01-02, round8/01-transport-errors.md
2026-11-07 08:22:59 +09:00
DongHyeonka ee5b4e1b7e fix(inbound): 인자 변환 실패는 원인의 carrier와 상관없이 거부로 본다
문제(round8 리뷰 01 「Declined to judge」, 리뷰 README 19.4절 ④):
- 결정 「감싼 carrier를 전송이 읽는 법」이 인자 변환 단계까지 덮는지
  정해지지 않았다. STOMP advice는 @DestinationVariable·@Header의
  ConversionFailedException과 받은 메시지가 실린
  MessageConversionException의 원인에 carrier가 있으면 거부 WARN 한 줄
  대신 그 carrier의 줄(5xx면 ERROR와 예외)을 남긴다. web은 같은 실패에
  원인을 보지 않고 BAD_PARAMETER·VALIDATION_FAILED로 답한다.

고른 방법(소유자 결정 2026-11-07, ④ (a)):
- 인자 변환 단계는 carrier를 보지 않는다. StompHandlerFailureLog가 거부
  판정(clientRefusalOf)을 원인 사슬의 carrier 검색보다 먼저 한다.
  응답 프레임은 그대로다(handler 경로는 프레임을 보내지 않는다).
- web은 지금 동작이 결정과 같아 코드를 바꾸지 않았다. 경로 변수 변환기와
  Jackson creator가 carrier를 던지는 지킴 테스트 둘을 더하고,
  handleTypeMismatch·handleHttpMessageNotReadable Javadoc에 이유를 적었다.
- GraphQL @Argument binder는 변환기가 던진 실패를 binding result에 담고
  BindException의 원인으로 싣지 않아, carrier를 던져도 BAD_PARAMETER다.
  실제 binder 경로 지킴 테스트 하나와 매퍼 Javadoc·README 한 줄.
- 버린 안: (b) 세 전송의 변환 단계가 원인의 carrier를 먼저 본다 — 요청
  형식 오류의 코드가 변환기 구현에 따라 바뀐다.

위험·한계:
- 바뀌는 것은 STOMP 로그 줄뿐이다. 템플릿에는 carrier를 던지는 변환기가
  없다. 안내 B-46에 적었다.
- GraphQL 지킴 테스트는 Spring for GraphQL 2.0.5 binder의 동작에 기댄다.
  binder가 원인을 싣게 바뀌면 그 테스트가 실패한다.

검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- RED(기준 3eb3b067 + 테스트만, 트리 4feb83c6): :adapter:inbound:websocket:test
  --tests StompHandlerFailureLogTest rc=1, 13건 중 2건 실패. 두 경우 모두
  기대 WARN "request refused as VALIDATION_FAILED|BAD_PARAMETER by
  <변환 예외>", 실제 ERROR "persistence failure classified as
  DB_UNAVAILABLE ...". red/R2c-websocket.log
- 지킴(RED 없음 — 지금 동작이 결정과 같다): web TransportErrorHandlingTest
  12건(red/R3c-web-guard.log)과 GraphQlArgumentBindingFailureTest
  (트리 7c45e303, red/R1b-graphql.log)가 기준 커밋에서 통과. 변이:
  handleTypeMismatch가 원인의 carrier를 먼저 보게 바꾸면 12건 중 1건
  (경로 변수) 실패, 400 대신 503. red/R7c-web-guard-mutant.log
- GREEN(이 커밋 트리 1a5b4a8f): :adapter:inbound:websocket:check
  :adapter:inbound:web:check :adapter:inbound:graphql:check
  :shared-contract:check rc=0, websocket 107·web 343·graphql 408·
  shared-contract 269건 실패 0·skip 0, FROM-CACHE 0. green2/B1-check.log
- testQualityCheck 첫 실행(green/D16)에서 이 커밋의 테스트 record 둘
  (Signup, `if (email != null)`)이 SpotBugs NP_LOAD_OF_KNOWN_NULL_VALUE로
  걸려 `!email.isEmpty()`로 고쳤다. 고친 테스트로 RED·지킴·변이를 다시
  돌렸고(위 R2c·R3c·R7c), 마지막 트리에서 web·websocket spotbugsTest가
  실행되어 통과했다(green2/D16).

Refs: docs/reviews/2026-11-03-rereview/README.md 19.4절 ④, round8/01-transport-errors.md 「Declined to judge」
2026-11-07 08:22:59 +09:00
DongHyeonka e1fb049b64 fix(graphql): 등록한 실패는 원인의 carrier보다 등록한 코드로 답한다
문제(round8 확인 리뷰 RR8-01-01, 회귀):
- GraphQL 매퍼가 원인 사슬의 첫 carrier를 앱이 등록한 매핑보다 먼저
  본다. 앱이 GraphQlExceptionResolver에 등록한 실패가 하위 실패(예:
  PersistenceFailureException)를 원인으로 들면 등록한 코드 대신 carrier
  코드로 답한다(ORDER_UNAVAILABLE 대신 DB_UNAVAILABLE). r8-f1 전에는
  등록한 코드였다. 소유자 결정 「감싼 carrier를 전송이 읽는 법」은
  "바뀌는 응답은 500 INTERNAL_ERROR이던 경우뿐"을 전제로 했다.

고른 방법(소유자 결정 2026-11-07, 리뷰 README 19.4절 ① (a)):
- 판정 순서를 플랫폼 거부 → 실패 자신이 carrier → 등록된 application
  매핑 → 원인 사슬의 첫 carrier → 거부된 인자 → 가림으로 바꾼다.
  sharedCodeOf는 실패 자신이 carrier가 아니고 등록 매핑이 있으면 원인
  사슬을 보지 않는다. web에서 앱의 도메인 advice가 먼저 받는 것과 같다.
- 로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier로 정한다(기본값).
  등록 매핑이 답해도 그 안의 서버 쪽 carrier는 그 줄(persistence는 분류
  한 줄)을 남긴다. 버린 안: 등록 매핑이 답하면 아무 줄도 남기지 않기
  (r8-f1 전 동작) — DB 장애의 흔적이 사라진다.
- 버린 안: (b) 지금 순서를 두고 문서에 적기 — 앱에 원인 버리기를
  강요하고 web과 계속 다르다. (c) 등록 매핑을 실패 자신이 carrier인
  경우보다도 먼저 — r8-f1 전에도 없던 변화라 범위가 넓다.
- 같은 내용을 GraphQL README·CLAUDE.md, GraphQlExceptionResolver·
  ApiErrorCarrier.firstIn Javadoc, shared-contract README, 결정 색인,
  업그레이드 안내 B-45·B-46에 적었다.

위험·한계:
- 실패 자신이 carrier인 타입(예: LockAcquisitionTimeoutException)을
  등록한 GraphQL 매핑은 계속 쓰이지 않는다. B-45와 resolver Javadoc에
  적었다.
- main 대비 GraphQL 응답은 바뀌지 않는다(r8-f1이 아직 main에 없다).
  합치지 않은 안내 행 B-45·B-46만 최종 동작으로 고쳤다.

검증(desktop, flock /tmp/claude-gates/heavy.lock, --no-build-cache,
로그 ~/r9-g1-inbound-logs/):
- RED(기준 3eb3b067 + 테스트만, 트리 7c45e303): :adapter:inbound:graphql:test
  --tests GraphQlWireErrorMapperTest --tests GraphQlArgumentBindingFailureTest
  rc=1, 22건 중 1건 실패
  aRegisteredFailureThatKeepsACarrierAsItsCauseIsAnsweredWithItsRegisteredCode
  (기대 [ORDER_UNAVAILABLE, BUSINESS], 실제 [DB_UNAVAILABLE, DEPENDENCY]).
  지킴 테스트 둘(실패 자신이 carrier인 등록 타입, 등록 매핑이 답해도 남는
  carrier 줄)은 기준에서도 통과. red/R1b-graphql.log
- GREEN(이 커밋 트리 d00d1f4d): :adapter:inbound:graphql:check
  :shared-contract:check rc=0, graphql 407·shared-contract 269건
  실패 0·skip 0, FROM-CACHE 0. green/A1-check.log
- python3 scripts/check-work-docs.py rc=0(이 커밋 트리, 이력 ID 0).

Refs: docs/reviews/2026-11-03-rereview/README.md 19절 RR8-01-01, 19.4절 ①
2026-11-07 08:22:59 +09:00
DongHyeonka 4cd38cf492 test(migration): 예외 목록 검사를 fixture로 지켜 빈 목록에서도 돌게 한다
문제 (재리뷰 round8 RR8-03-04)
- GrpcOperationLedgerMigrationLockWaitIT의 예외 목록 검사
  (everyMigrationListedAsRunningOutsideATransactionIsOneConcurrentIndex
  BuildThatSaysSo)는 RUN_OUTSIDE_A_TRANSACTION 위에서 돈다. 목록이 비어
  루프가 한 번도 돌지 않고, 단언은 늘 참이다. 거부 조건 셋을 모두 무력하게
  바꿔도 통과한다(리뷰 변이 A11). 가이드는 이 테스트가 목록을 지킨다고
  적는다.

고른 방법
- 리뷰 권장안: 판정을 static refusalsOf(목록, 트리)로 뺀다. 트리는 파일
  이름 → (SQL, executeInTransaction)이다. 실제 목록 검사도 이 메서드를
  부른다. 같은 IT에 문자열 fixture로 위반 넷(트리에 없음, 동시 인덱스 문장
  없음, executeInTransaction=false 없음, 다른 문장과 섞임)과 허용 하나를
  둔다.
- 버린 대안: 판정을 testkit의 ConcurrentIndexMigrationInspector로 옮겨
  persistence-jpa 단위 테스트가 fixture를 갖게 한다. optional 빌드로
  복사하는 JDK 전용 파일이 늘고, ledger 전용 규칙(트리에 있어야 함)이
  testkit에 들어간다.

위험·한계
- fixture 케이스도 클래스의 Testcontainers PostgreSQL이 뜬 뒤 돈다(같은
  클래스라 컨테이너 하나를 같이 쓴다).
- RED 없음 — 테스트 구조 개선이다. 대신 변이: 기준 커밋에서 A11 변이가
  살아남고, 고친 코드에 같은 변이를 얹으면 위반 fixture가 실패한다.

변이 (desktop, 로그 ~/r9-g3-logs/)
- 기준 3eb3b067 + A11 변이: 목록 검사 1건 rc=0 통과(변이 생존)
- 이 커밋 + 같은 변이: GrpcOperationLedgerMigrationLockWaitIT rc=1,
  8건 중 위반 fixture 4건 실패(트리에 없음은 NPE, 나머지 셋은 "Expected
  size: 1 but was: 0")

검증 (desktop, 이 커밋의 트리 65218dff, --no-build-cache, 로그 ~/r9-g3-logs/)
- -p optional-platforms :grpc:grpc-operation-ledger-jpa:check rc=0,
  test 13건
- 같은 leaf integrationTest rc=0, 52건(새 5건 포함) 실패·skip 0
- 같은 leaf testQualityCheck rc=0
- FROM-CACHE 0

Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-04
Fixes: 6ec0c4f7fa ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
2026-11-07 08:07:42 +09:00
DongHyeonka 8ebe98e69a fix(migration): 실패한 DROP INDEX CONCURRENTLY를 runbook 절차로 복구되게 한다
문제 (재리뷰 round8 RR8-03-01)
- migration-failed.md "Recover a failed concurrent index migration"은
  CREATE·DROP·REINDEX 동시 문장 셋을 대상으로 두고, 2단계에서 "빌드가 남긴
  무효 인덱스를 지운다"고 한다. 실패한 DROP INDEX CONCURRENTLY가 남긴 무효
  인덱스는 그 마이그레이션이 지우려던 인덱스다. 절차대로 지우고 실패 행을
  지운 뒤 다시 배포하면 같은 문장이 42704(index does not exist)로 실패하고
  실패 행이 다시 생긴다. 운영자는 처음과 같은 막힌 상태로 돌아간다.
- 고치다 같은 절에서 하나 더 찾았다. 2단계(DROP INDEX CONCURRENTLY)가
  3단계(원인 정리) 앞이다. 취소·timeout이 원인이면 그 열린 트랜잭션이
  운영자의 DROP INDEX CONCURRENTLY도 붙잡아, 2단계가 3단계를 기다린다.
- runbook을 실행하는 IT는 중복으로 실패한 unique CREATE 한 경우만 돌렸다.

고른 방법
- 리뷰 권장안: 무효 인덱스를 지우는 단계를 문장 종류로 나눈다. CREATE는
  그 인덱스를, REINDEX는 _ccnew(또는 _ccold) 사본을 지운다. DROP INDEX
  CONCURRENTLY면 이 단계를 건너뛴다. 다시 배포한 같은 문장이 그 인덱스를
  지운다(PostgreSQL은 중간에 실패한 DROP INDEX CONCURRENTLY의 재시도를
  받는다). 5단계 문장도 "builds the index"에서 세 경우로 고친다.
- 단계 순서를 "빌드 확인 → 원인 정리 → 무효 인덱스 삭제 → 실패 행 삭제 →
  재배포"로 바꾼다. 실패 행만 지운다는 소유자 결정(2026-11-06)은 그대로다.
- IT에 두 경우를 더한다. 열린 쓰기를 기다리다 취소된 REINDEX와 열린
  읽기를 기다리다 취소된 DROP에 runbook SQL을 runbook에서 읽어 돌리고,
  재배포 뒤 이력 [1 true, 2 true], 무효 인덱스 없음, V1 checksum 그대로를
  단언한다. 대기를 30초 기다리지 않고, 문장이 잠금을 기다리는 것을 본
  즉시 취소하는 도우미(cancelledOnceItWaits)를 둔다.
- 같은 절차를 요약한 곳을 같이 고친다: docs/jpa/runbooks.md "An invalid
  index exists", migration-guide "Concurrent index builds"(DROP이 무엇을
  기다리는지 포함), 학습 문서 8.2절, ConcurrentIndexMigrationInspector의
  Javadoc과 실패 메시지, 업그레이드 안내 5절 행(그 범위가 아직 main에
  없어 행을 최종 동작으로 고치고 머리 목록에 더함).
- 버린 대안: 가이드와 검사기가 DROP INDEX CONCURRENTLY에 IF EXISTS를
  요구한다. 이미 배포된 파일은 고칠 수 없어 새 파일에만 통하고, 서비스의
  기존 마이그레이션 검사를 새로 실패시킨다.

위험·한계
- 운영자가 실패한 문장의 종류를 마이그레이션 파일에서 읽어야 한다.
  runbook이 이력 행만으로는 알 수 없는 것을 요구한다.
- REINDEX가 swap 뒤에 실패해 _ccold가 남는 경우는 문서로만 다뤘다(실행
  재현 없음). PostgreSQL 문서의 권장 복구와 같다.
- 단계 번호가 바뀌었다. 리뷰 기록이 옛 번호(2단계 = drop)로 적은 곳은 그때의
  기록이라 두었다.

RED (desktop, 기준 3eb3b067 + 임시 테스트, 로그 ~/r9-g3-logs/red-concurrent.log)
- postgresqlConcurrentIndexMigrationIntegrationTest rc=1, 9건 중 2건 실패
  - redAFailedConcurrentDropIsRecoveredByTheBaseRunbook: 기준 runbook
    1·2·4단계 뒤 재배포가 "42704 ERROR: index "ix_probe_id" does not
    exist"로 실패, 이력 [1 true, 2 false] 그대로
  - redTheBaseRunbookDropsBeforeItEndsTheTransaction: 기준 순서의 2단계
    (_ccnew drop)가 열린 쓰기 트랜잭션을 기다려 취소됨
  - 나머지 7건(기존) 통과

검증 (desktop, 이 커밋의 트리 7cfaa83c, --no-build-cache, 로그 ~/r9-g3-logs/)
- :adapter:outbound:persistence-jpa:check rc=0, test 666건 실패·skip 0
- postgresqlConcurrentIndexMigrationIntegrationTest rc=0, 9건(새 2건 포함)
- :adapter:outbound:persistence-jpa:testQualityCheck rc=0
- :app-bootstrap:documentContractTest rc=0, 67건(RunbookCoverageContractTest
  포함)
- -p optional-platforms :grpc:grpc-operation-ledger-jpa:integrationTest
  rc=0, 47건(검사기 사본이 바뀌어서)
- FROM-CACHE 0
- 상대 링크(노트북): python3 scripts/check-work-docs.py --links로 바꾼
  문서 5개(migration-failed.md, jpa/runbooks.md, migration-guide.md,
  학습 문서, 업그레이드 안내) rc=0, 깨진 링크 0

Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-01
Fixes: 6ec0c4f7fa ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
2026-11-07 08:07:42 +09:00
DongHyeonka dae6dcaf51 docs(migration): 동시 인덱스 IT Javadoc의 runbook 절 이름을 바로잡는다
문제 (재리뷰 round8 RR8-03-02)
- PostgreSqlConcurrentIndexMigrationIntegrationTest의 클래스 Javadoc이
  migration-failed.md의 "A concurrent index migration failed" 절을 읽는다고
  적는다. 그런 제목은 없다. 실제 절은 "Recover a failed concurrent index
  migration"이다.

고른 방법
- 절 이름만 고친다. 같은 원인으로 다른 문서·코드가 없는 절을 가리키는지
  보려고, 문서 경로 뒤에 따옴표로 절 제목을 적은 곳을 저장소 전체(리뷰
  기록 제외)에서 찾아 그 문서의 제목과 대조했다. 마이그레이션·runbook
  문서를 가리키는 곳에 다른 틀린 이름은 없었다.

위험·한계
- RED 없음 — Javadoc 문구다. 틀린 문장의 출처는 위 줄, 실제 제목은
  docs/runbooks/migration-failed.md의 "## Recover a failed concurrent index
  migration"이다.

검증 (desktop, 이 커밋의 트리 1b95ec3f, --no-build-cache, 로그 ~/r9-g3-logs/)
- :adapter:outbound:persistence-jpa:spotlessCheck
  compilePostgresqlIntegrationTestJava rc=0, FROM-CACHE 0

Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-02
Fixes: 6ec0c4f7fa ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
2026-11-07 08:07:42 +09:00
DongHyeonka e3ebc25ef4 refactor(persistence-jpa): runbook SQL 리더 이름을 RunbookSql로 바꾼다
문제 (재리뷰 round8 RR8-03-03)
- runbook에서 runbook-sql 블록을 읽는 IT 도우미의 이름이
  OutboxRunbookSql이다. round7 수정 뒤로 마이그레이션 runbook
  (migration-failed.md)도 이 클래스로 읽는다. 다음 runbook의 SQL을 lane으로
  돌리려는 사람이 이름을 보고 공용 리더를 찾지 못해 사본을 만들 수 있다.

고른 방법
- 리뷰 권장안대로 RunbookSql로 이름을 바꾸고 사용처 세 클래스(같은
  postgresqlIntegrationTest source set)를 따라 고친다. 클래스 Javadoc에
  모든 runbook lane이 이 리더 하나를 쓴다고 적는다. 동작은 바꾸지 않는다.

위험·한계
- 같은 source set 안의 package-private 클래스라 밖에서 쓰는 곳이 없다.
  리뷰 기록(docs/reviews/**)의 옛 이름은 그때의 기록이라 두었다.
- RED 없음 — 이름 문제다. 사용처 lane 셋이 그대로 통과하는 것으로 본다.

검증 (desktop, 이 커밋의 트리 328f6012, --no-build-cache, 로그 ~/r9-g3-logs/)
- :adapter:outbound:persistence-jpa:check rc=0, test 666건 실패·skip 0
- postgresqlConcurrentIndexMigrationIntegrationTest rc=0, 7건
- postgresqlOutboxOrderKeyRunbookIntegrationTest rc=0, 10건
- postgresqlOutboxDispositionRunbookIntegrationTest rc=0, 8건
- 네 명령 모두 FROM-CACHE 0, 테스트 태스크 실행됨(UP-TO-DATE 아님)

Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-03
Fixes: 6ec0c4f7fa ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다")
2026-11-07 08:07:42 +09:00
DongHyeonka 06b9433855 fix(app-bootstrap)!: STOMP channel interceptor를 사용자 전송으로 센다
문제
- 사용자 전송 타입 목록(USER_TRANSPORT_TYPE_NAMES)은 STOMP 쪽에서 simp
  패키지와 @MessageMapping만 담는다. 클라이언트 프레임마다 도는 inbound
  channel interceptor(ChannelInterceptor·ExecutorChannelInterceptor)는
  STOMP 헤더 타입을 읽지 않으면 사용자 전송으로 보이지 않는다.
- 그래서 설정이 configureClientInboundChannel에서 익명 interceptor를
  등록해 @SystemCaller를 부르거나, 사용자 전송 패키지 밖의 interceptor가
  부르거나, interceptor를 구현한 설정이 부르면
  USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가 통과한다. 인증만 된
  WebSocket 클라이언트가 권한 검사 없는 쓰기를 부른다.
- 매뉴얼 07 「규칙이 못 보는 길」은 설정에 중첩한 클래스가 이 사각지대에
  들지 않는다고 적어 동작과 다르다(RR8-02-01).

고른 방법
- 두 interceptor 타입을 사용자 전송 타입 목록과 요청 처리기 타입 목록
  (REQUEST_HANDLER_TYPE_NAMES)에 이름으로 더한다. 앞쪽은 중첩·최상위
  interceptor를, 뒤쪽은 interceptor를 구현하거나 @Bean으로 내놓는 설정
  자신을 잡는다. HandlerInterceptor·ServerInterceptor도 두 목록에 있다.
- inbound channel의 thread만 정하는 설정(ChannelRegistration)은 설정용
  타입이라 그대로 통과한다. interceptor bean을 handler bean과 다른 설정에
  두면 통과한다. 둘 다 허용 fixture로 고정했다.
- 위반 fixture 다섯(설정 안 익명 ChannelInterceptor, 설정 안
  ExecutorChannelInterceptor, 최상위 interceptor, interceptor를 구현한
  설정, @Bean ChannelInterceptor를 내놓으며 handler bean도 만드는 설정)이
  목록 항목을 하나씩 증명한다. fixture가 spring-messaging 타입을 써서
  architectureTestCompileOnly 한 줄과 lockfile 한 줄을 더했다. runtime에는
  WebSocket adapter가 이미 싣는다.
- 매뉴얼 07, 업그레이드 안내 B-16, app-bootstrap README, 규칙 Javadoc과
  실패 메시지를 동작에 맞췄다.
- 버린 대안:
  - 요청 처리기 목록에는 넣지 않기(리뷰 A 권장안). interceptor는 람다로
    설정에 쓸 수 없지만, 설정이 interceptor를 구현하거나 @Bean으로 내놓는
    길이 남는다. 매뉴얼은 이미 "interceptor 등록은 handler bean을 만드는
    설정과 다른 설정에 둔다"고 적는다. 리뷰 B 권장안을 따랐다.
  - org.springframework.messaging.support 패키지째 넣기. 같은 패키지의
    MessageBuilder를 시스템 쪽 Spring Integration 흐름도 써서 판정이
    넓어진다.
  - 규칙은 두고 매뉴얼에 사각지대로 적기(리뷰 대안). 템플릿 자신이 쓰는
    진입 타입이라 규칙으로 막을 수 있다.
  - ChannelInterceptor로 대입 가능한 타입 전부(assignableTo). 프로젝트
    interceptor 클래스까지 사용자 전송 타입이 되어, 그것에 의존하는 모든
    클래스가 사용자 전송이 된다. 다른 목록과 모양도 달라진다.

위험·한계
- 판정이 넓어진 곳: STOMP outbound·broker channel interceptor도 같은
  타입이라 사용자 전송으로 센다. 시스템 쪽 Spring Integration 흐름의
  channel interceptor를 @SystemCaller 안에 두면 실패한다. 템플릿에는 둘 다
  없다(Spring Integration은 JDBC lock registry만 쓴다).
- 이름 목록이라 ImmutableMessageChannelInterceptor 같은 구현 클래스를
  상속한 interceptor는 보지 못한다.
- 설정이 registration.interceptors(x)로 넘기기만 할 때 설정 자신이
  잡히는지는 확인하지 않았다. interceptor 자신은 사용자 전송으로 검사된다.
- STOMP 런타임 기동은 보지 않았다. 규칙 판정만 봤다.

검증 (desktop, flock /tmp/claude-gates/heavy.lock,
로그 ~/r9-g2-stomp-interceptor-logs/)
- RED: 3eb3b067에 테스트·fixture·의존성 줄만 얹은 트리 39b02529에서
  ArchitectureViolationFixtureTest 실행. 99건 중 5건 실패, 다섯 모두 위반
  0건(Expecting any element of: []). 허용 2건은 통과. rc=1.
- GREEN: :app-bootstrap:architectureTest --rerun 249건, 실패·skip 0, rc=0.
- 변이: ExecutorChannelInterceptor를 두 목록에서 빼면 [2]만, 요청 처리기
  목록의 ChannelInterceptor를 빼면 [4][5]만, 사용자 전송 목록의
  ChannelInterceptor를 빼면 [1][3]과 UserTransportTypeListsTest가 실패.
- 트리 742428a9에서 모두 rc=0, FROM-CACHE 0:
  :app-bootstrap:check(305건, skip 5, 실패 0), architectureCheck,
  :app-bootstrap:testQualityCheck,
  :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache
  (842 태스크 실행, 6906건 실패 0), :verifyStrictLaneStages --dry-run,
  scripts/verify-compose-profile-contracts.sh,
  :sample-portfolio:check :sample-portfolio:qualityCheck(340건 실패 0),
  -p optional-platforms ci(593건 실패 0),
  -p optional-platforms :verifyStrictLaneStages --dry-run.

Refs: docs/reviews/2026-11-03-rereview/README.md 19절 RR8-02-01

BREAKING CHANGE: STOMP inbound channel interceptor(ChannelInterceptor,
ExecutorChannelInterceptor)가 사용자 전송 타입이자 요청 처리기 타입이
됐다. 사용자 전송 패키지 밖이나 설정 안에 둔 interceptor, interceptor를
구현한 설정이 @SystemCaller에 닿거나, interceptor를 @Bean으로 내놓는 설정이
@SystemCaller bean도 만들면 :app-bootstrap:architectureTest가 실패한다.
interceptor에서 시스템 작업을 부르지 않는다. 사용자도 시켜야 하면
@RequiresPermission 유스케이스를 따로 만들고, interceptor 등록은 handler
bean을 만드는 설정과 다른 설정에 둔다(업그레이드 안내 B-16).
2026-11-07 07:55:55 +09:00
DongHyeonka 7535a4ca7a fix(idempotency)!: 적용한 핸들의 재전송을 전이 종류와 인자로 가린다
문제: 전이를 적용한 핸들이 그 전이를 다시 보낼 때 세 저장소가 서로, 그리고
포트 Javadoc과 다르게 답한다(재리뷰 round8 RR8-04-01·02, 같은 원인).
- markFailed를 다른 disposition으로 다시 보내면 fake·Redis·PostgreSQL 모두
  NOT_OWNER다. 기록을 남이 가져갔다는 틀린 신호이고 Javadoc은
  OPERATION_CONFLICT라고 적는다.
- retention만 다르면 fake·Redis는 ALREADY_MARKED_SAME_OPERATION, PostgreSQL은
  fail digest에 retention이 들어 있어 OPERATION_CONFLICT다.
- Redis는 start가 돌려준 핸들로 renew한 뒤 그 핸들로 start를 보내면
  ALREADY_STARTED_SAME_OPERATION으로 답한다. renew도 기록을 EXECUTING·
  revision+1로 두어 TRANSITION이 상태와 revision만으로는 start와 구별하지
  못한다. executor는 그 답에 action을 실행해 이미 도는 작업을 한 번 더
  돌린다. fake·PostgreSQL은 NOT_OWNER다.
원인은 하나다. "적용한 핸들"을 revision 하나로만 가리고 전이 종류와 인자를
같이 보지 않는다.

방법: 소유자 결정(2026-11-07, 1103 README 19.4절 ② (a))대로 다른
disposition은 OPERATION_CONFLICT, 다른 retention은 "이미 처리됨"으로 맞춘다.
retention은 complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐이라
비교하지 않는다.
- Redis: 기록 hash에 lastKind(CLAIM·START·RENEW·COMPLETE·FAIL)를 남긴다.
  TRANSITION의 재전송 판정은 "rev == 핸들 rev + 1 그리고 lastKind == 이
  전이"다. 그 안에서 상태가 목표면 ALREADY, 아니면(다른 disposition의
  실패) OPERATION_CONFLICT. claim·takeover는 CLAIM을 써 넘겨받기 전 종류가
  남지 않게 한다. 어댑터가 전이 종류를 9번째 인자로 보낸다. 명령 fake를
  같이 고친다.
- PostgreSQL: fail 재생 판정이 두 실패 종류(FAIL_RETRYABLE·FAIL_ABANDONED)를
  모두 실패의 재생으로 읽는다. fail digest에서 retention을 뺀다.
- fake: 적용한 핸들의 markFailed 재전송에 disposition이 다르면
  OPERATION_CONFLICT.
- 공유 계약 IdempotencyStoreContract에 케이스 셋(다른 retention, 다른
  disposition과 기록 유지, renew 뒤 같은 핸들의 start)을 더했다.
- PostgreSqlIdempotencyIntegrationTest의 "다른 retention은 conflict" 케이스가
  옛 동작을 고정하고 있어 결정대로 "이미 처리됨, 처음 retention 유지"로
  바꿨다(...IsConfirmedAndKeepsItsRetention).
  IdempotencyFailOutcome·IdempotencyStartOutcome·IdempotencyStorePort Javadoc,
  결정 색인 2.4절(새 행과 「넘겨받기 전 핸들의 재전송」 적용 조건),
  application-core CLAUDE.md·README, cache-redis·persistence-jpa README,
  TESTING_STRATEGY, 업그레이드 안내 5절 행을 같이 고쳤다.
버린 대안: 다른 disposition을 NOT_OWNER로 두고 Javadoc만 고치기(19.4절 ②
(b), 소유자가 고르지 않음, 적용한 핸들에 "넘겨받혔다"는 틀린 신호),
다른 retention도 OPERATION_CONFLICT(② (c), Redis 기록에 retention을 더하고
Lua를 바꿔야 하며 보관 기간을 인자로 본다), Redis start 분기만
"renewedFromRev가 있으면 ALREADY 아님"으로 막기(같은 상태에 머무는 전이가
늘면 다시 갈라진다).

위험·한계: 템플릿 호출자(IdempotencyExecutor)는 같은 인자로만 다시 보내고
renew를 부르지 않아 HTTP 동작은 같다. 포트를 직접 부르는 코드만 답이
바뀐다. 이 배포 전에 쓰인 Redis 기록에는 lastKind가 없어, 새 프로그램이
그 기록의 전이를 재전송으로 보지 않는다. 핸들은 프로세스 메모리에만 있고
같은 프로세스는 같은 프로그램을 돌리므로, 새 프로그램이 옛 프로그램이
적용한 전이의 핸들을 받는 경로는 템플릿에 없다고 본다(실행으로 확인하지
않음). PostgreSQL도 같은 이유로 옛 fail digest(retention 포함)와 새
digest를 같은 핸들로 비교하는 경로가 없다고 보고 digest VERSION을 올리지
않았다.

검증: desktop, 공유 잠금, --no-build-cache, 기준 3eb3b067.
- RED(기준 커밋 + 계약 케이스만, 로그 ~/r9-g4-red-logs/red-summary.txt):
  fake 62 중 1 실패(다른 disposition "expected: OPERATION_CONFLICT but was:
  NOT_OWNER"), Redis 명령 fake 62 중 2·실 Redis(redisContainerContractTest)
  103 중 2 실패(다른 disposition, renew 뒤 start "expected: NOT_OWNER but
  was: ALREADY_STARTED_SAME_OPERATION"), 실 PostgreSQL 62 중 2 실패(다른
  disposition, 다른 retention "expected: ALREADY_MARKED_SAME_OPERATION but
  was: OPERATION_CONFLICT").
- GREEN(이 커밋과 같은 트리 5a74698d, 로그 ~/r9-g4-green-logs/와 pass2/,
  수는 결과 XML에서 셈 test-counts.txt): 네 leaf check(application-core 426·
  skip 19 fake 시간 케이스, cache-redis 228, redis-runtime 65,
  persistence-jpa 666)와 testQualityCheck, redisContainerContractTest 103,
  jpaPlatformContractTest 432, fake를 쓰는 leaf(composition:idempotency 32,
  redis-sdk 310, web 341, sample-portfolio 339), documentContractTest 67 —
  모두 rc=0, 실패 0. postgresqlIdempotencyIntegrationTest는 1차에서 위 옛
  케이스 1건이 실패했고, 고친 뒤 pass2에서 persistence-jpa spotlessCheck·
  check·testQualityCheck와 함께 10 중 실패 0, rc=0.
- scripts/check-work-docs.py rc=0, git diff --check 통과.

BREAKING CHANGE: IdempotencyStorePort 구현은 적용한 핸들이 markFailed를 다른
disposition으로 다시 보내면 OPERATION_CONFLICT, retention만 다르면
ALREADY_MARKED_SAME_OPERATION으로 답해야 하고, renew를 적용한 핸들의 start를
"이미 시작됨"으로 확인하면 안 된다(NOT_OWNER). 직접 구현한 store는
IdempotencyStoreContract의 새 케이스로 확인한다.
2026-11-07 07:50:40 +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 c95869da9d Merge remote-tracking branch 'origin/claude/r8-f5-small-fixes-f40412' into claude/integration-r8-a4196a
# Conflicts:
#	docs/upgrade/2026-11-maturity-review.md
2026-11-07 01:41:00 +09:00
DongHyeonka 91a708340f Merge remote-tracking branch 'origin/claude/r8-f4-idempotency-3a6a0f' into claude/integration-r8-a4196a 2026-11-07 01:40:44 +09:00
DongHyeonka 8c5ba6a979 Merge remote-tracking branch 'origin/claude/r8-f3-persistence-9e8157' into claude/integration-r8-a4196a 2026-11-07 01:40:39 +09:00
DongHyeonka d618d41ba2 Merge remote-tracking branch 'origin/claude/r8-f2-arch-rules-60140e' into claude/integration-r8-a4196a 2026-11-07 01:40:39 +09:00
DongHyeonka ef8ef170e8 fix(inbound)!: Retry-After를 레지스트리대로 붙이고 GraphQL 인자 거부를 맞춘다
문제(r8-f1 보고의 범위 밖 1·2, 소유자 답 2026-11-07 "권하는 안대로"):
- web RetryAfterAdvisor 표가 레지스트리 retry_after_seconds 칸의 미러인데
  7개가 빠졌다(DB_UNAVAILABLE 5, DB_SERIALIZATION_FAILURE 1, DB_DEADLOCK
  1, DB_IDLE_IN_TX_TIMEOUT 2, OUTBOX_PUBLISH_FAILED 30,
  JOB_EXECUTOR_REJECTED 5, JOB_TIMEOUT 10). 그래서 DB 일시 실패 응답에
  Retry-After가 없다. 대조하는 테스트가 없었다: advisor 단위 테스트는
  값을 코드마다 손으로 옮겼고, enum·레지스트리 대조 테스트는 category·
  status·retryable만 봤다.
- GraphQL @Argument 값이 파라미터 타입으로 바뀌지 않으면 Spring 인자
  binder가 BindException을 던지는데, 매퍼가 모르는 타입이라
  INTERNAL_ERROR로 가리고 예외째 ERROR로 남긴다. 그 메시지에
  rejected value [...]가 실린다.

고친 것:
- RetryAfterAdvisor 표를 Map.ofEntries로 바꾸고 7개를 채웠다(Map.of는
  10쌍이 상한). OperationalErrorRegistryContractTest(document-contract)에
  OperationalError마다 RetryAfterAdvisor.retryAfterSeconds와 레지스트리
  값이 같은지 보는 테스트를 더했다. 버린 안: advisor가 레지스트리를
  런타임에 읽는 것 — web leaf가 저장소 파일을 읽게 되고 jar에 실리지
  않는다.
- GraphQlWireErrorMapper가 BindException을 IllegalArgumentException과
  같은 "거부된 인자"로 본다: 등록된 매핑이 없으면 BAD_PARAMETER(REQUEST),
  로그는 ServerFailureLog.refused의 WARN 한 줄(타입만). web이 바뀌지 않는
  경로 변수에 답하는 것과 같다.
- 결정 색인 2.3절에 두 결정과 STOMP 필수 header 누락을 ERROR로 두는
  기본값(이유 포함)을 적었다. 업그레이드 안내 B-47·B-48.

위험·한계:
- 응답이 바뀐다: DB 일시 실패 넷에 Retry-After가 생기고, GraphQL 인자
  변환 실패가 INTERNAL_ERROR → BAD_PARAMETER.
- 대조 테스트는 OperationalError 코드만 본다. 다른 leaf의 코드는
  RetryAfterHint로 자기 값을 말한다(대조 대상 아님).
- BindException은 binder가 인자 변환을 모아 던질 때만 온다. @Valid
  검증(ConstraintViolationException)은 이 leaf에 Bean Validation이 없어
  다루지 않았다.

검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/round2/):
- RED(5f6a86d7 + 테스트만): 11건 실패. advisor 7개 코드 empty, 레지스트리
  대조 1건, GraphQL 3건(INTERNAL_ERROR, ERROR "graphql failure masked" +
  BindException "rejected value [alice@example.com]"). round2/red.log
- 이 트리(ca44d3fc): :ci :verifyDependencyLocks --warning-mode=fail rc=0
  (web test 341, graphql test 404, app-bootstrap test 225 skip 4 이전부터,
  architectureTest, verifyGraphQlApiSurface 포함)
- :sample-portfolio:check :sample-portfolio:qualityCheck rc=0
- :verifyStrictLaneStages --dry-run 두 빌드 rc=0, -p optional-platforms ci rc=0
- web·graphql systemTest, :conditionalTransportQualification rc=0
- :app-bootstrap:documentContractTest rc=0(67)
- web·graphql·app-bootstrap testQualityCheck rc=0
- scripts/verify-compose-profile-contracts.sh rc=0, scripts/check-work-docs.py rc=0

BREAKING CHANGE: DB_UNAVAILABLE(5초)·DB_SERIALIZATION_FAILURE(1초)·
DB_DEADLOCK(1초)·DB_IDLE_IN_TX_TIMEOUT(2초) 응답에 Retry-After가 붙고,
GraphQL @Argument 변환 실패는 INTERNAL_ERROR 대신 BAD_PARAMETER로 답한다.
업그레이드 안내 B-47·B-48.
Refs: docs/work/reference/decisions.md 2.3절, docs/upgrade/2026-11-maturity-review.md B-47, B-48
2026-11-07 01:38:36 +09:00
DongHyeonka a490c20f3e fix(strict-lane)!: 태그 push·release로만 도는 workflow는 releaseCheck에만 센다
문제: verifyStrictLaneStages의 workflow 판독기는 `push: tags:`만 있거나
`release` trigger만 있는 workflow의 명령을 모든 단계의 실행으로 센다.
태그 push는 매 변경에 돌지 않는데, 그런 workflow에만 `:integrationCheck`
같은 단계를 두어도 검사가 통과한다(round7 05 「Declined to judge」 ①).

고른 방법: 소유자 결정(2026-11-07, "권하는 안대로", 리뷰 README 18.4절
(a))대로, 요청이나 경로 필터 없이 시작하는 trigger가 release 흐름뿐인
workflow — `release`, 또는 `branches`·`branches-ignore` 없이
`tags`·`tags-ignore`가 있는 `push` — 의 명령은 `:releaseCheck`에만
센다. 경로 필터 결정(2026-11-06)과 같은 원칙이다. 판독기는 trigger를
변경·release·경로 필터·요청 넷으로 나누고, workflow의 시작을 "매 변경 /
release 흐름만 / 돌지 않을 수 있음" 셋으로 낸다. release 흐름만인
workflow를 부르는 재사용 workflow도 같다. Invocation에 releaseFlowReason을
두고, whyNotExecuting(taskPath, buildDirectory)가 `:releaseCheck` 밖의
단계에 그 이유를 준다. 실패 메시지, AGENTS.md, src/README.md,
build-logic/README.md, 업그레이드 안내 B-36, 결정 색인 2.7절을 고쳤다.
버린 대안: 지금처럼 모든 단계에 세고 문서에 적는다 — 소유자가 위 안을
골랐다. release 단계 이름을 빌드 설정(`strictLaneStages`)으로 받는다 —
결정이 `releaseCheck`를 이름으로 정했고, 파생 서비스 설정 표면이 늘어
판독기 상수로 두었다.

위험·한계: 파생 서비스가 `releaseCheck`가 아닌 단계를 태그·release
workflow에서만 돌리면 이제 verifyStrictLaneStages --dry-run이 실패한다.
이 repo의 release.yml은 `-p optional-platforms integrationCheck`도
돌리지만 integration-main.yml(main push·nightly)이 같은 단계를 돌려
판정이 그대로다(두 빌드 확인). release의 `types`는 보지 않는다.
`branches`와 `tags`를 함께 둔 push는 지금처럼 모든 단계에 센다.

검증(desktop, 로그 ~/r8-f5b-logs/):
- RED: 기준 ac3c6a81에 테스트만 얹음. 68건 중 2건 실패 —
  WorkflowGradleInvocationsTest(세 workflow의 :integrationCheck가
  실행으로 셈), StrictLaneStagesFunctionalTest(UnexpectedBuildSuccess,
  "every strict lane is in an executed stage")
  (red-release-flow.log, TEST-*.xml)
- GREEN: 같은 두 클래스 46건·22건 실패 0 (green-release-flow.log)
- -p build-logic check javadoc rc=0(build-logic 테스트 173건 실패 0),
  :verifyStrictLaneStages --dry-run, -p optional-platforms
  :verifyStrictLaneStages --dry-run rc=0(둘 다 "every strict lane is in
  an executed stage"), check-work-docs.py와 상대 링크 검사 rc=0
  (summary.txt)

Refs: docs/reviews/2026-11-03-rereview/README.md 18.4절(cb340001)
BREAKING CHANGE: `releaseCheck`가 아닌 단계(:ci, :mainCheck, :integrationCheck, :performanceCheck 등)를 태그 push(`branches` 없는 `tags`)나 `release` trigger로만 시작하는 workflow에서만 돌리면 verifyStrictLaneStages --dry-run이 실패한다. 그 단계를 매 push·pull_request·schedule에 도는 workflow에서도 돌린다(docs/upgrade/2026-11-maturity-review.md B-36).
2026-11-07 01:37:14 +09:00
DongHyeonka 6764246ac9 fix(architecture): Flyway 규칙이 설정 객체를 직접 만드는 길도 막는다
문제 (재리뷰 round7 RR7-03-06)
- 규칙 문장은 "코드로 만드는 Flyway는 모두 FlywaySchemaPolicy.configure()
  에서 시작한다"(persistence-jpa CLAUDE.md, FlywaySchemaPolicy Javadoc,
  migration-guide)인데 JpaProductionArchitectureTest는 Flyway.configure()
  호출만 막는다. new FluentConfiguration(), new ClassicConfiguration(),
  FluentConfiguration::new로 만든 Flyway는 검사를 지나 Flyway의
  PostgreSQL 잠금 기본값(트랜잭션 안의 잠금)을 되찾는다. 그 잠금 아래
  동시 인덱스 마이그레이션은 끝나지 않는다(RR6-03-01).

고른 방법
- 규칙을 상수 EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY로 빼고, Flyway
  Configuration에 대입 가능한 타입의 생성자 접근(호출과 생성자 참조)을
  더 막는다. 하위 클래스와 직접 구현도 같은 접근이라 함께 걸린다.
  new Flyway(...)는 허용한다 — 정책의 설정 위에서는 정책의 Flyway다.
- 위반 fixture 4개(configure 호출, FluentConfiguration·ClassicConfiguration
  생성, 생성자 참조)와 허용 fixture 1개(정책 빌더, 정책 설정 위의
  new Flyway)를 ArchitectureViolationFixtureTest로 평가한다.
- 버린 안: callConstructor를 생성자 시그니처마다 나열 — Flyway 버전마다
  생성자 목록이 바뀌고 생성자 참조를 못 본다. new Flyway(...)까지 금지 —
  정책 설정 위의 정당한 사용까지 막는다.

위험·한계
- 하위 클래스 fixture는 두지 않았다. SpotBugs가 Flyway 설정을 상속한
  클래스를 분석하다 lombok.Generated를 못 찾아 testQualityCheck가 실패한다
  (빌드는 불완전 분석을 실패로 본다). 이 경우는 GREEN 1차 실행에서 규칙이
  잡는 것을 확인했고(g0306-archtest.log), 규칙 Javadoc에 이유를 적었다.
- 리플렉션이나 Configuration 맵으로 잠금 값을 덮어쓰는 것은 막지 않는다.
- 이 규칙을 이미 지키는 파생 서비스(업그레이드 안내 2절 15번)는 바꿀 것이
  없다. 설정 객체를 직접 만들던 서비스는 architectureTest가 새로 실패한다
  (안내 15번과 5절 「Flyway 잠금」 행에 적었다).

검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/)
RED — 6ec0c4f7 + 규칙 상수 추출(규칙 그대로)과 fixture·테스트:
- :app-bootstrap:architectureTest 1차 233건 중 3건 실패
  (FluentConfiguration·ClassicConfiguration·하위 클래스 fixture 통과),
  2차(생성자 참조 fixture 추가) 234건 중 4건 실패. Flyway.configure()
  fixture는 잡히고 허용 fixture는 통과 (red0306-arch*.log)
GREEN — 이 커밋의 트리 e7e19298:
- :app-bootstrap:architectureTest rc=0 (233건 실패 0; 위반 fixture 4개
  모두 걸리고 허용 fixture와 운영 코드는 통과)
- architectureCheck rc=0
- :adapter:outbound:persistence-jpa:check rc=0, :app-bootstrap:check rc=0
- :app-bootstrap:documentContractTest rc=0 (66건 실패 0)
- :app-bootstrap:testQualityCheck rc=0. 하위 클래스 fixture를 둔 1차
  트리(f8fecd1e)에서는 spotbugsArchitectureTest가 "missing analysis class
  lombok.Generated"로 실패했고, 그 fixture만 빼자 통과했다
  (g0306-testquality.log, g0306b-testquality.log)
- 같은 우회가 다른 곳에 있는지: 운영 코드 전체(src 아래 main·testFixtures)
  에서 Flyway를 만드는 곳은 FlywaySchemaPolicy와 규칙이 예외로 둔
  MessagingInboxSchemaStream의 Flyway.configure()뿐이다. optional 빌드와
  src/messaging에는 운영 Flyway 생성이 없다

Refs: docs/reviews/2026-11-03-rereview/README.md 18.5절 round7 1차 Declined 판정 (cb340001)
2026-11-07 01:28:33 +09:00
DongHyeonka 5f6a86d7b7 fix(inbound)!: 네 전송이 같은 실패에 같은 코드와 로그로 답한다
문제(round7 리뷰 RR7-01-03~06):
- 분산 락 timeout(LockAcquisitionTimeoutException)이 ApiErrorCarrier가
  아니어서 web·GraphQL·gRPC 모두 500 INTERNAL_ERROR(재시도 불가)와
  "unhandled" ERROR로 답한다. 레지스트리·runbook·Javadoc은 409 재시도
  가능을 약속한다. web은 carrier가 되어도 Retry-After 표에 이 코드가
  없어 헤더가 빠진다.
- 다른 예외로 감싼 carrier를 gRPC만 원인 사슬에서 찾고 web·GraphQL·
  STOMP는 500 INTERNAL_ERROR로 답하며 SQL 원인째 ERROR로 남긴다.
- gRPC 서비스가 IllegalArgumentException을 원인으로 든 raw status를
  던지면 INTERNAL_ERROR·ERROR(입력이 든 메시지 첨부)이고, onError로
  넘기면 BAD_PARAMETER·WARN이다.
- STOMP @MessageMapping 앞에서 Spring이 거부한 클라이언트 메시지(읽지
  못한 payload, 비었거나 검증에 걸린 payload, 변환되지 않는
  @DestinationVariable·@Header)를 ERROR와 예외 메시지(받은 JSON 조각·
  값)로 남긴다.

고른 방법:
- shared-contract ApiErrorCarrier.firstIn(Throwable): 원인 사슬의 첫
  carrier를 찾는다(자기 자신 포함, 사슬이 돌면 멈춤). web 처리기 둘,
  GraphQL 매퍼, gRPC 인터셉터, STOMP advice와 ERROR 프레임이 모두 이
  함수를 쓰고 gRPC carrierOf와 STOMP의 carrier 루프는 지웠다. 로그 줄은
  찾은 carrier로 정해 감싼 persistence 실패도 분류 한 줄만 남는다
  (소유자 결정 2026-11-06 (a)).
- LockAcquisitionTimeoutException이 ApiErrorCarrier를 구현한다. errorCode()
  반환 타입은 OperationalError로 둔다(공변 반환, 호출부 변경 없음).
  RetryAfterAdvisor에 LOCK_ACQUISITION_TIMEOUT=1(레지스트리 값)을 더한다.
  버린 안: web 전용 @ExceptionHandler — GraphQL·gRPC가 그대로 남는다.
- gRPC close는 status 예외를 벗긴 실패 하나(failureBehind)로 carrier·IAE
  판정과 로그를 모두 한다. 버린 안: closeWithError에서 status를 다시
  만드는 것 — 판정과 로그가 또 다른 값을 볼 수 있다.
- ServerFailureLog.refused(code, failure): refusedArgument와 같은 WARN
  한 줄(타입만, 메시지·예외 없음). STOMP advice가 받은 메시지가 실린
  MessageConversionException과 MethodArgumentNotValidException을
  VALIDATION_FAILED, @DestinationVariable·@Header 대상
  ConversionFailedException을 BAD_PARAMETER로 남긴다(web이 같은 실패에
  답하는 코드). 응답을 쓰다 난 변환 실패는 받은 메시지가 없어 ERROR로
  남는다.

위험·한계:
- 응답이 바뀐다: 락 timeout 500 → 409(+Retry-After: 1), 감싼 carrier
  500 → 그 carrier 코드, IAE가 감싼 carrier 400 → carrier 코드, gRPC가
  던진 IAE 원인 raw status INTERNAL → INVALID_ARGUMENT. 업그레이드 안내
  B-45·B-46과 5절에 적었다.
- STOMP 쓰기/읽기 변환 실패 구분은 Spring 7.0.9 변환기가 읽기 실패에만
  failedMessage를 싣는 데 기댄다(바이트코드로 확인). 바뀌면
  aReplyTheConverterCannotWriteIsLoggedAtErrorWithTheFailure가 실패한다.
- 고치지 않은 같은 모양(범위 밖, 보고에 적음): RetryAfterAdvisor 표에서
  빠진 레지스트리 값 7개, GraphQL @Argument BindException의
  INTERNAL_ERROR·ERROR, STOMP 필수 header 누락의 ERROR.

검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/):
- RED(기준 73d39212 + 테스트만): 7개 leaf에서 17건 실패, 모두 위 결함의
  값(500 INTERNAL_ERROR, INTERNAL, ERROR + 입력 메시지 등). red.log,
  red-websocket.log
- GREEN(이 트리 b540d48e): shared-contract 269, application-core 413(skip
  19, 이전부터), web 334, graphql 401, grpc 74, websocket 105,
  app-bootstrap 225(skip 4, 이전부터) 실패 0. green-test.log
- :ci :verifyDependencyLocks --warning-mode=fail rc=0
- :sample-portfolio:check :sample-portfolio:qualityCheck rc=0
- :verifyStrictLaneStages --dry-run, -p optional-platforms 같은 것 rc=0
- -p optional-platforms ci rc=0
- web·graphql·websocket systemTest, :conditionalTransportQualification
  rc=0(web 18, graphql 34+8, grpc 29, websocket 21+7)
- :app-bootstrap:documentContractTest rc=0(66)
- 바뀐 7개 leaf testQualityCheck rc=0
- scripts/verify-compose-profile-contracts.sh rc=0

BREAKING CHANGE: 분산 락 timeout은 409 LOCK_ACQUISITION_TIMEOUT
(retryable, Retry-After: 1), 다른 예외로 감싼 carrier는 web·GraphQL에서도
그 carrier 코드, gRPC가 던진 IllegalArgumentException 원인 raw status는
INVALID_ARGUMENT로 답한다. 클라이언트는 error.code로 가르면 바꿀 것이
없다. 업그레이드 안내 B-45·B-46.
Refs: docs/reviews/2026-11-03-rereview/round7/01-core-inbound.md RR7-01-03, RR7-01-04, RR7-01-05, RR7-01-06
2026-11-07 01:14:10 +09:00
DongHyeonka 6ec0c4f7fa fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다
문제 (재리뷰 round7 영속성 RR7-03-01~05)
- 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가
  "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의
  이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에
  다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다.
  docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서
  멈춘다.
- 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다.
  가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다
  커밋해 앞 문장이 남는다.
- 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX …
  CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE
  CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다.
- LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면
  SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은
  "늘 거부"라고 쓴다.
- ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고
  안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개
  (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도
  모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be
  executed within a pipeline"으로 실패한다.

고른 방법
- 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에
  "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드
  확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의
  실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고
  flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고
  postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어
  실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기
  Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다.
- 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와
  잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태).
- 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와
  상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은
  PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이
  맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라
  그대로 둔다.
- ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을
  두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스
  문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration
  Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어
  sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다
  (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을
  파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로
  바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다.

위험·한계
- 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다.
  걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이
  없다(업그레이드 안내 4.1에 적음).
- runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라
  성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이
  지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다.
- ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음).
- Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라
  UP-TO-DATE로 처리됐다.

검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/)
RED — 기준 73d39212 + 이 커밋의 테스트(+ 기준 문서 주장을 단언하는 임시
메서드, + 임시 ledger V004):
- persistence-jpa test --tests LockWaitMigrationInspectorTest: 80건 중
  2건 실패, 검사기가 빈 목록(통과)을 돌려줌 (red-unit.log)
- postgresqlMigrationLockWaitIntegrationTest: 47건 중 4건 실패 — 옛 주장
  대로면 거부여야 할 REINDEX SCHEMA|DATABASE CONCURRENTLY가 applied,
  conf=true VACUUM FULL·REINDEX SCHEMA를 PostgreSQL은 25001로 거부하는데
  검사기는 통과 (red2-lockwait.log)
- postgresqlConcurrentIndexMigrationIntegrationTest: 9건 중 3건 실패 —
  옛 절차(DROP INDEX) 뒤 재배포가 "Detected failed migration to version
  2", conf를 붙인 섞인 파일이 행 3001·무효 인덱스·실패 이력을 남김,
  runbook 블록이 없어 복구 테스트 준비 실패(RED로 세지 않음)
  (red2-concurrent.log)
- ledger integrationTest(V004 동시 인덱스): 6건 중 4건 실패 — 잠금 대기
  IT "name it as an exception here", 다른 IT 둘 "cannot be executed within
  a pipeline" (red-ledger.log)
GREEN — 이 커밋의 트리 b49369e7:
- :adapter:outbound:persistence-jpa:check rc=0 (test 666건 실패 0),
  :testQualityCheck rc=0
- postgresqlMigrationLockWaitIntegrationTest rc=0 (42건 실패 0)
- postgresqlConcurrentIndexMigrationIntegrationTest rc=0 (7건 실패 0)
- -p optional-platforms :grpc:grpc-operation-ledger-jpa:check
  integrationTest testQualityCheck rc=0 (IT 3+2+42건 실패 0)
- :app-bootstrap:documentContractTest rc=0 (66건 실패 0)
- 두 빌드의 verifyStrictLaneStages --dry-run rc=0
- ledger 탐침(임시 V004): 목록에 없으면 잠금 대기 케이스만 실패하고
  메시지가 RUN_OUTSIDE_A_TRANSACTION을 가리킴(48건 중 1건), 목록에 넣으면
  rc=0, 목록에 넣고 SET LOCAL을 섞으면 목록 검사가 "mixes a concurrent
  index statement"로 거부
- python3 scripts/check-work-docs.py --links docs: 깨진 링크 0

Refs: docs/reviews/2026-11-03-rereview/round7/03-persistence.md
2026-11-07 01:14:09 +09:00
DongHyeonka eab82df1f2 docs: README의 깨진 상대 링크 세 개를 고친다
src/adapter/outbound/fileserver/README.md와 objectstorage/README.md는
저장소 루트 docs를 ../../../(= src/docs)로 가리켜 없는 파일을 열었다.
../../../../로 고쳤다. src/README.md는 커밋되지 않는 .env를 가리켰다.
커밋된 템플릿 .env.example로 바꾸고 복사해 .env로 쓴다고 적었다.

검증: python3 scripts/check-work-docs.py --links를 src, docs,
README.md, .github에 돌려 깨진 링크 0(전에는 src에서 이 셋).
lychee는 노트북·desktop에 없어 돌리지 못했다.
2026-11-07 01:10:31 +09:00