Commit Graph
191 Commits
Author SHA1 Message Date
DongHyeonka d8afffce9e docs(docs): docs/README를 모든 문서 폴더를 덮는 지도로 다시 쓴다
문제: `docs/README.md`의 폴더 표에 `ci-cd/`, `compatibility/`, `mongo/`,
`objectstorage/`, `observability/`, `roadmap/`, `testing/`, `upgrade/`, `web/`,
`websocket/`가 없다. 폴더 밖 문서 둘(`capability-status.md`,
`storage-capability-boundary.md`)도 없다. 처음 온 사람이 문서를 찾을 수 없다.

고른 방법: 「문서 지도」 절 하나에 목적별 표(매뉴얼, 계약과 스냅숏, 영역 운영 문서,
운영과 전달, 결정 기록, 설계와 기록, 폴더 밖 문서)를 두고, 표의 첫 칸에 `폴더/`를
적는다. 다음 커밋의 `map` 검사가 이 첫 칸을 읽는다. 「문서 검사」 절에 `map`·`readme`
검사, resources 폴더 제외, `.lycheeignore` 규칙을 적는다.

위험·한계: 알림 ADR은 지금 위치 `notification/adr/`로 적었다. 옮기는 변경이 지도도
고친다.

검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py --links
docs/README.md` 깨진 링크 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 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
donghyeon.kang 03a313ed65 Merge pull request 'refactor!: 확인 리뷰 수정과 저장소 구조·문서 체계 정리를 합친다' (#2) from refactor/maturity-review-2026-11 into main 2026-11-07 07:51:45 +00: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 ae54f312a0 docs(work): 저장소 정리 결정 중 색인에 없던 행을 더한다
문제: 소유자가 2026-11-07에 정한 저장소 정리 결정(design-docs
`repo-structure/README.md` 3.1·3.2절) 중 문서 체계 결정이 결정 색인에 없다.
배치 결정 중 「업무 기능 하나가 끝까지 도는 별도 fixture를 두지 않는다」도
없다. 색인에 없으면 다음 세션이 이미 정한 것을 다시 묻는다.

고친 방법: 없는 결정만 「소유자」, 2026-11-07, 출처 3.1·3.2절로 더한다.
- 2.1 작업 방식: 문서 체계, 한국어의 범위(상태 어휘 포함), 문서 검사,
  학습 문서(지금 결정. 「학습 문서(지난 것)」 행은 그대로 둔다), 문서 규칙
  정본, 레지스트리 yaml 설명 칸, 짝 프론트 적용 시점, README 필수 절.
  비슷한 두 결정(목표 구조와 폴더 이름, 한국어 범위와 상태 어휘)은 한 행에
  묶었다.
- 2.2 구조·조립: 기능 끝까지 도는 fixture.
3.3절(CI·스크립트) 결정은 CI 재편 작업에 남긴다.

검증: check-work-docs.py rc=0(이력 ID 0), check-docs.py rc=0.
2026-11-07 15:05:57 +09:00
DongHyeonka 0e54b5b564 docs(work): 문서 검사를 게이트 표와 단계 묶음에 넣는다
문제: 문서 체계 1단계가 PR·main push마다 도는 `python3 scripts/check-docs.py`
(workflow `docs-check`)를 더했지만 게이트 정본 gates.md에는 없다. 라운드
끝 게이트를 gates.md 3절대로 돌리는 세션은 이 검사를 빠뜨린다. 파일이나
Gradle 프로젝트를 지우는 코드 변경이 문서를 낡게 만든다는 것도 2절 표에
없다.

고친 방법: 구조 정리가 `check-repo-layout.py`를 넣은 모양을 따른다.
- 1절 게이트 목록에 한 행(무엇·단계·workflow, 앞에 도는 자기 시험).
- 3절 단계별 묶음의 pull request·main 줄과 (가) 명령 목록에 자기 시험과
  검사 두 줄. workflow가 main push에서도 돌리므로 main 줄에도 넣는다.
- 2절 「바꾼 것에 맞춰 고르기」의 문서 행에 더하고, 「파일·폴더·Gradle
  프로젝트를 지우거나 옮김」 행을 새로 둔다.

위험·한계: docs-writing.md·review-criteria.md에 새 검사와 규칙 줄을 더하는
일은 매뉴얼 보강 작업에 남긴다.

검증: check-work-docs.py rc=0, check-docs.py rc=0, gates.md 상대 링크 0 깨짐.
2026-11-07 15:05:57 +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 13cbbb578c Merge remote-tracking branch 'origin/claude/t1-backend-layout-46973e' into claude/i1-layout-docs-merge-217f1e 2026-11-07 14:59:07 +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 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 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 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 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 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +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 ac03192ddd docs(review): round8 수정을 합친 트리의 게이트와 멈춤 기준을 적는다
문제: round8 수정 다섯 브랜치를 합친 트리(8a0b1216)의 라운드 끝
게이트 결과와 병합 충돌 처리, 지금의 멈춤 기준 상태가 README 19절에
없다. 19.6절은 리뷰 직후 상태(결정 대기, 게이트 미실행)를 적고 있다.

고른 방법: 19.8절에 병합 순서·충돌 넷의 처리·게이트 표(gates.md 4절
모양)·실패한 게이트 둘의 원인과 기준 커밋 확인·못 돌린 것을 적는다.
19.6절을 지금 사실로 고친다: Declined 0은 참, 게이트는 아님, 남은
항목은 수정 세션의 「범위 밖」 넷 + 합칠 때 본 RunbookSql Javadoc 하나 +
게이트 실패 둘. 실패는 brief대로 고치지 않고 원인과 담당 커밋만 적는다.
버린 안: 실패한 smoke를 한 번 더 돌려 통과한 결과만 적기 — 같은
lane이 기준에서도 OOM으로 죽는 것을 커널 로그로 봤으므로 통과가
게이트를 믿을 근거가 되지 않는다.

위험·한계:
- compose smoke all-adapters 실패는 기준 3eb3b067에서도 app이 OOM으로
  죽는 것(4번 중 2번)을 봤지만, 합친 트리는 5번 모두 죽고 3번 실패했다.
  표본이 작아 합친 변경이 메모리를 조금 늘렸을 가능성은 배제하지 못했다.
- 게이트 대상은 8a0b1216이다. 이 커밋은 README만 바꿔 Gradle 게이트를
  다시 돌리지 않았고 문서 검사만 다시 돌렸다.

검증(desktop, flock /tmp/claude-gates/heavy.lock, --no-build-cache,
로그 ~/integration-r9-logs/):
- 대상 8a0b1216(트리 88743668, 노트북과 같은 해시)에서 PR 단계 25개
  명령과 문서 검사, main 단계 18개, 태그 단계 2개. rc=1은 둘:
  verifyMessagingCertificationEvidence(테스트 37건 통과, 증거 대조
  실패), compose runtime smoke(all-adapters, 17 lane 통과).
- 기준 3eb3b067: 같은 인증 명령 rc=1(같은 차이), smoke 전체 rc=0,
  all-adapters lane 3번 rc=0(그중 2번 app OOM, 커널 로그).
- 이 커밋: check-work-docs.py 기본·--history docs/manual·lychee 범위
  --links(578파일, 깨짐 0), check-review-index.py(182/182) rc=0.
2026-11-07 11:47:41 +09:00
DongHyeonka 8a0b12166e docs(review): round8 처리 표와 소유자 답을 리뷰 README 19절에 적는다
문제: round8 결함 10건과 결정 넷, 개선 제안 하나를 다섯 브랜치가 고쳤고
소유자가 2026-11-07 결정 넷에 답했다. README 19절에는 그 답과 어느 커밋이
무엇을 고쳤는지가 없다.

고른 방법: 19.4절 표에 「소유자 답」 칸을 더하고 결정 색인 위치를 적었다
(18.4절과 같은 모양). 개선 제안을 받아 넣은 커밋을 그 절 끝에 적었다.
19.7절에 처리 표를 새로 뒀다. 칸은 brief대로 결함 · 상태 · 고친 커밋 ·
검증 · 결정이다. 검증 칸은 각 커밋 본문에서 RED와 GREEN을 옮겼다.
「결정」 칸에는 수정 세션이 정한 기본값 다섯을 적고 소유자 확인으로
표시했다.

위험·한계: 검증 칸은 커밋 본문을 옮긴 것이고 이 커밋이 다시 돌린 것이
아니다. 합친 트리의 게이트와 멈춤 기준은 다음 커밋(19.6·19.8절)에 적는다.

검증: python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview
rc=0(182/182), check-work-docs.py 기본·--history docs/manual·lychee 범위
--links(578파일, 깨짐 0) rc=0.
2026-11-07 10:04:22 +09:00
DongHyeonka 07f7c3054d docs(work): 소유자가 확인한 기본값 행의 「누가」를 소유자로 바꾼다
문제: 결정 색인 2.1·2.3·2.4·2.7절의 기본값 행 아홉(커밋 단위, 넘어온
「범위 밖」 항목, desktop 도구 설치, 약속한 응답으로 맞추기, 검사를 더
엄하게 하는 수정, 아직 합치지 않은 업그레이드 안내, 라운드 끝 태그 단계
범위, 넘겨받기 전 핸들의 재전송 적용 조건, GraphQL 로그 줄)은 「누가」가
"기본값"이라 소유자 확인 대상으로 읽힌다. 소유자가 2026-11-07 round8
수정 묶음을 합치기로 하며 이 기본값들을 확인했다.

고른 방법: 「누가」 칸만 "소유자(2026-11-07, 기본값 확인)"로 바꾼다.
결정 내용과 출처는 그대로 둔다. 기본값에서 나왔다는 것을 칸에 남겨 출처를
따라갈 수 있게 한다.

위험·한계: brief가 이름으로 든 행은 여덟이다. 「GraphQL 판정 순서」의
"로그 줄은 기본값"(r9-g1 `e1fb049b`의 기본값)은 brief가 소유자가 확인했다고
적은 수정 세션 기본값 다섯 중 하나라 같이 바꿨다. 리뷰 README 19.7절이 그
기본값을 "소유자 확인"으로 적어, 바꾸지 않으면 두 문서가 다르다. 옛 칸에
있던 괄호 설명("옛 '묶음마다 커밋 하나'를 정본에 맞춤", "소유자 기계를
바꾸는 일")은 지웠다. 같은 이유가 출처(evidence.md 11절, operate.md
4.1절)에 있다.

검증: python3 scripts/check-work-docs.py rc=0. 이 파일을 읽는 테스트는
없다(grep -rln 'decisions.md' src --include='*.java' 결과 0건).
2026-11-07 10:04:22 +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 24db780a99 Merge remote-tracking branch 'origin/claude/r9-g3-migration-7ce36d' into claude/integration-r9-f1bc5c 2026-11-07 10:00:03 +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 3eb3b06755 docs(work): cold-read 시험 2회차 빈틈 52건을 매뉴얼에 반영한다
문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).

고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
  명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
  증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
  안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.

위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.

검증(트리 f43dbc29, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/C-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
  lychee 범위 --links rc=0, check-review-index.py 2026-11-03-rereview rc=0
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- MongoNamespaceContractTest --rerun rc=0(3건)
- 테스트 수 세는 명령은 desktop의 지난 결과 XML로 시험했다
2026-11-07 07:02:09 +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 83948d58f3 docs(review): round8 두 리뷰를 합쳐 색인 절을 쓰고 B에만 있던 결함 둘을 넣는다
문제
- round8 확인 리뷰는 독립 리뷰어 둘(A 정본, B)이 따로 봤다. 총괄이 짝을
  지은 뒤 남은 일: B에만 있던 결함 둘의 재확인, 심각도가 다른 짝 하나,
  리뷰 README의 이 라운드 색인 절(총괄 지시로 정본 리뷰어가 씀).

방법
- B-03-01(OutboxRunbookSql 이름)은 근거를 다시 읽어 RR8-03-03으로 넣었다.
  이름 문제라 탐침은 쓰지 않았다(E1).
- B-03-02(ledger 예외 목록 검사 테스트가 빈 목록 위에서 돎)는 변이 탐침
  으로 확인해 RR8-03-04로 넣었다. 원래 rc=0, 거부 조건 셋을 무력하게 한
  변이도 rc=0(변이 생존), 목록에 트리에 없는 파일을 넣은 대조는 rc=1.
  그래서 영역 03의 RR7-03-01 재확인을 닫힘에서 부분으로 바꿨다.
- RR8-01-02는 review-criteria.md 3절로 Minor로 정했다(A Important,
  B Minor). runbook이 status: stub이고 템플릿 코드는 락 포트를 부르지
  않는다. 이유와 반론은 영역 01에 적었다.
- README 19절: 색인 표 10건, B → 정본 대응표, 겹침 비율 5/10 = 50%,
  실행 요약, 결정 넷(GraphQL 판정 순서, markFailed 재전송 인자, 이력 ID
  범위, 인자 변환 단계의 감싼 carrier — 영역 01의 Declined를 올림),
  18.6절 남은 항목 판정, 멈춤 기준 상태.
- 짝지은 결함에는 B가 더 본 모양과 증거(B 탐침 P1·P4 등)와 분류 차이를
  영역 문서에 한 줄씩 더했다.

위험·한계
- RR8-06-01(정본 리뷰어의 색인 검사 모순)은 결함으로 두고 다음 수정
  묶음에서 고친다. 이번에는 총괄 지시로 색인 절을 써서 rc=0이다.
- B의 개선 제안(web 필터 예외의 컨테이너 로그 안내)은 실행으로 확인하지
  않아 19.4절 끝에 받을지 닫을지만 적었다.

검증
- desktop(flock /tmp/claude-gates/heavy.lock, --no-build-cache, 로그
  ~/r8-review-a-logs/pass2/): -p optional-platforms
  :grpc:grpc-operation-ledger-jpa:integrationTest --tests <예외 목록 테스트>
  원래·변이·대조 rc=0·0·1, FROM-CACHE 0. worktree는 지웠다.
- 노트북: check-review-index.py docs/reviews/2026-11-03-rereview rc=0
  (182/182), check-work-docs.py rc=0, README·round8 --links 깨짐 0.
  리뷰 문서를 읽는 테스트는 없다(src grep 0건).

Refs: docs/reviews/2026-11-03-rereview/README.md 19절
2026-11-07 03:38:52 +09:00
DongHyeonka 27260ad05c docs(review): round7 수정을 합친 트리의 확인 리뷰 round8 영역 문서를 남긴다
문제
- round7 결함 수정 다섯 브랜치와 매뉴얼 수정을 합친 2c8a359d..83a12f66이
  새로 만든 결함을 찾는 확인 리뷰다. 독립 리뷰어 둘 중 정본 리뷰어의
  기록이다. 범위는 docs/reviews 밖 116개 파일 +3,747줄이라 확인 리뷰
  상한(추가 1,500줄)을 넘는다.

방법
- docs/work/improve.md 4.4절대로 영역 여섯(전송 오류, 아키텍처 규칙,
  마이그레이션, 멱등 저장소, build-logic·httpclient, 매뉴얼·스크립트)과
  공통 문서로 나눠 한 세션이 차례로 봤다. 영역마다 문서 하나다.
- 의심 결함은 desktop 임시 worktree(83a12f66, 비교용 2c8a359d)의 탐침으로
  확인했다. 탐침 코드는 공유 노트 폴더 r8-review-a-probes/에 있다.
- README의 이 라운드 색인 절은 쓰지 않았다. 두 리뷰를 합친 뒤 총괄이
  쓴다(improve.md 4.1절 7단계, 결정 색인 「리뷰 README 분담」).

결과
- 결함 8건: Important 3(RR8-01-01 회귀, RR8-01-02, RR8-03-01),
  Minor 5(RR8-02-01, RR8-03-02, RR8-04-01, RR8-04-02, RR8-06-01).
  이번 수정 4, 섞임 3, 이전부터 1.
- README 18.6절이 넘긴 항목은 결함 셋(RR8-02-01, RR8-04-01·02),
  결함 아님 둘, 소유자 결정 필요 하나로 판정했다.

위험·한계
- 색인 절이 없어 check-review-index.py는 총괄이 색인 절을 쓸 때까지
  rc=1이다(RR8-06-01). 보고의 색인 표를 붙인 임시 사본에서는 rc=0이다.
- RR8-02-01은 spring-messaging이 architectureTest 컴파일 경로에 없어
  탐침 없이 코드로만 봤다(E1).

검증(desktop, flock /tmp/claude-gates/heavy.lock, --no-build-cache,
로그 ~/r8-review-a-logs/)
- 탐침 A1~A7 rc=0: GraphQL 등록 매핑(두 커밋 비교), 멱등 저장소 세 모양
  (fake, Redis 명령 fake, 실 Redis, 실 PostgreSQL), 실패한
  DROP INDEX CONCURRENTLY의 runbook 복구(실 PostgreSQL).
- A8 바뀐 leaf test·architectureTest --rerun rc=0(테스트 태스크 10개 실행,
  FROM-CACHE 0, 실패 0), A9 -p build-logic test --rerun rc=0(173건).
- 노트북: check-work-docs.py(전체, --history docs/manual, lychee 범위
  --links) rc=0, round8 문서 --links 깨짐 0.

Refs: docs/reviews/2026-11-03-rereview/README.md 18.6절, 18.7절
2026-11-07 03:28:13 +09:00