문제 (재리뷰 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)
문제(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
문제 (재리뷰 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
"brief가 허용하면 자기 브랜치에만 commit·push한다"는 commit을
허용하면 push도 된다고 읽힐 수 있다. docs/work/README.md 4절과 루트
CLAUDE.md는 둘을 따로 허용한다. 문장을 "brief가 허용한 것만(commit과
push는 따로) 그 작업의 자기 브랜치에 한다"로 바꿨다.
검증: AGENTS.md 본문을 읽는 테스트는 없다(git grep으로 확인, 걸리는 것은
주석과 루트 표시용 파일 존재 확인뿐).
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에 없어 돌리지 못했다.
문제: ClientRuntimeRegistry.close()는 "돌아오면 drain 스레드가 없다"를
약속하고, 기다리다 시간이 지나면 IllegalStateException을 던진다.
그런데 닫는 스레드가 이미 interrupt 상태면 첫 awaitTermination이 바로
InterruptedException을 내고, catch가 flag만 되살린 뒤 정상으로
돌아온다. drain 스레드가 살아 있어도 호출자는 모른다(리뷰 RR7-02-01).
고른 방법: interrupt를 받아도 같은 마감(5초)까지 다시 기다리고,
기다림이 끝나면 flag를 되살린다. 마감 안에 끝나지 않으면 다른 경로처럼
IllegalStateException을 던진다. 기다리는 부분을 awaitDrainThreadExit로
떼어 내 interrupt마다 남은 시간으로 다시 부른다.
버린 대안: interrupt 경로에서 바로 IllegalStateException을 던진다 —
더 단순하지만, 곧 끝날 스레드를 두고 정상 종료를 실패로 보고한다.
위험·한계: interrupt된 스레드의 close()가 이제 최대 5초까지 막힐 수
있다(전에는 바로 돌아왔다). interrupt된 채 마감을 넘기는 경로는
테스트하지 않았다(5초를 기다려야 한다). 같은 모양을 찾아본 다른
종료 코드(gRPC 서버, notification worker, S3 worker, outbox relay)는
"스레드가 없다"를 약속하지 않고 shutdownNow로 끝내는 최선 노력이라
고치지 않았다.
검증(desktop, 로그 ~/r8-f5-logs/):
- RED: 기준 73d39212에 테스트만 얹음.
closingFromAnInterruptedThreadStillWaitsForTheDrainThread 실패 —
"Expecting empty but was: [httpclient-runtime-drain]"
(red-rr7-02-01.log, .xml)
- GREEN: ClientRuntimeRegistryTest rc=0 (green-rr7-02-01.log)
- :adapter:outbound:httpclient:check, :testQualityCheck,
httpClientStableContractTest(apache, jdk), spring70CompatibilityTest,
:ci rc=0 (summary.txt)
Refs: docs/reviews/2026-11-03-rereview/round7/02-idempotency-outbound.md RR7-02-01
문제: verifyStrictLaneStages의 workflow 판독기는 trigger 이름과
types만 본다. paths·paths-ignore 필터가 붙은 pull_request·push로만
시작하는 workflow의 `./gradlew :ci`도 실행으로 센다. 그런 workflow는
필터 밖 변경에서 돌지 않는데, 실패 메시지와 업그레이드 안내 B-36은
"매 push·pull request·schedule에 도는 workflow에서 단계를 돌리라"고
약속한다(리뷰 RR7-05-01).
고른 방법: 소유자 결정(2026-11-06, docs/work/reference/decisions.md
"경로 필터 workflow와 단계 검사")대로, change trigger에 paths나
paths-ignore가 있으면 그 trigger로는 세지 않는다. 필터 없는 change
trigger가 하나라도 있으면 지금처럼 센다. 세지 않는 이유는 "돌지 않을
수 있음" 칸이고, 메시지가 어느 trigger의 어떤 필터인지 적는다
(예: "push (paths-ignore)"). trigger마다 types와 경로 필터를 함께
읽도록 Trigger 레코드를 두었다. 실패 메시지(NOT_COUNTED), AGENTS.md,
src/README.md, build-logic/README.md, 업그레이드 안내 B-36을 같은
규칙으로 고쳤다.
버린 대안: 동작은 두고 메시지·B-36의 약속만 고친다 — 소유자가 위
안을 골랐다. branches·tags 필터까지 판정한다 — 결정 범위 밖이라
읽지 않고, Javadoc과 문서에 읽지 않는다고 적었다.
위험·한계: 파생 서비스가 단계 명령을 paths 필터 workflow에만 두었으면
이제 verifyStrictLaneStages --dry-run이 실패한다. 이 repo는 단계 명령이
필터 없는 workflow에 있어 두 빌드 모두 판정이 그대로다. tags와 paths가
함께 있는 push(GitHub은 태그 push에 paths를 보지 않음)도 세지 않는다 —
거짓 실패 쪽이다. 실제 GitHub의 필터 해석은 실행해 보지 않았다.
검증(desktop, 로그 ~/r8-f5-logs/):
- RED: 기준 73d39212에 테스트만 얹음. WorkflowGradleInvocationsTest
44건 중 1건 실패 — 필터 workflow 셋 모두 uncountedReason=null
(red-rr7-05-01.log, .xml)
- GREEN: 같은 테스트 rc=0 (green-rr7-05-01.log)
- -p build-logic check javadoc, :verifyStrictLaneStages --dry-run,
-p optional-platforms :verifyStrictLaneStages --dry-run,
:ci :verifyDependencyLocks rc=0 (summary.txt)
Refs: docs/reviews/2026-11-03-rereview/round7/05-build-logic-workflow.md RR7-05-01
BREAKING CHANGE: change trigger가 모두 paths·paths-ignore 필터를 단 workflow에서만 단계(:ci 등)를 부르면 verifyStrictLaneStages --dry-run이 실패한다. 단계 명령을 필터 없는 push·pull_request·schedule workflow로 옮긴다(docs/upgrade/2026-11-maturity-review.md B-36).
문제
- 설정에 중첩된 클래스를 요청 처리기 목록(ARE_REQUEST_HANDLER_TYPES)으로만
본다. 이 목록에는 JAX-RS와 주석형 JSR-356 타입이 없어서, 설정 안에 둔
JAX-RS 자원이나 @ServerEndpoint가 @SystemCaller를 불러도 잡히지 않는다.
r9는 잡았다(RR7-01-01, 회귀).
- 메서드 참조로 route만 등록한 설정도 사용자 전송으로 센다. 그런데 Javadoc,
매뉴얼 07, 업그레이드 안내 B-16은 "요청 처리 코드가 있을 때만"이라고 적어,
안내대로 처리 코드를 옮겨도 빌드가 실패한다(RR7-01-02). 같은 원인으로
CORS 설정에 쓰는 RequestMethod도 설정을 사용자 전송으로 만든다.
고른 방법
- 설정 클래스 자신만 요청 처리기 목록으로 본다. 중첩 클래스는 r9처럼 사용자
전송 타입 전체로 본다. 설정용 타입(ARE_TRANSPORT_SETUP_TYPES: MVC·WebFlux·
WebSocket·STOMP broker 설정 패키지, CORS 설정, RequestMethod)에만 의존하는
중첩 클래스는 설정의 일부로 둔다. 설정 필드를 읽는 익명 WebMvcConfigurer
(RR6-01-02)가 이 경우다. 목록에 없는 타입은 잡히는 쪽(거짓 실패)으로 간다.
- RR7-01-02는 판정을 좁히지 않고 문서를 동작에 맞췄다. route·data fetcher·
interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 실패
메시지에도 이 안내를 넣었다. RequestMethod만 설정용 타입으로 뺐다.
- 두 목록이 다시 갈라지지 않게 UserTransportTypeListsTest를 더했다. 요청
처리기·설정용 항목은 모두 사용자 전송 타입이어야 하고, 설정용 항목은 요청
처리기 타입을 덮지 않아야 한다.
- 버린 대안:
- 중첩 클래스에서 바깥 설정으로 가는 의존을 따라가지 않기(리뷰 권장안).
중첩 endpoint가 설정의 메서드를 거쳐 작업을 부르는 길을 놓친다. r9는
잡던 길이다. 위반 fixture RunNowThroughTheConfigurationFixture로 고정했다.
- 요청 처리기 목록에 JAX-RS·JSR-356 타입을 더하기. 목록에 없는 다음
라이브러리에서 같은 구멍이 난다.
- 설정 판정을 "요청을 받는 메서드"(파라미터·annotation·상속)로 좁히기.
route builder 람다(b -> b.GET(...))도 builder를 받아 목록이 또 필요하고
규칙이 복잡해진다.
- @CrossOrigin·HttpServletRequest는 설정용 타입으로 빼지 않았다.
@CrossOrigin은 handler에만 붙고, HttpServletRequest를 받는 람다(matcher,
CORS source)는 요청마다 돈다.
위험·한계
- 판정이 넓어진 곳: 설정에 중첩된 클래스가 설정용이 아닌 웹 타입(예:
HandlerMethodArgumentResolver, RestClient)을 쓰고 설정 필드를 읽으며, 그
설정이 @SystemCaller bean을 만들면 이제 실패한다. r9와 같고 r10보다 엄격하다.
그 타입이 기동 때만 도는 설정용 타입이면 목록에 더한다.
- JAX-RS·JSR-356 런타임 기동은 보지 않았다. 규칙 판정만 봤다.
검증 (desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f2-arch-rules-logs/)
- RED: 73d39212에 테스트·fixture만 얹고 ArchitectureViolationFixtureTest
실행. 87건 중 5건 실패: 중첩 JAX-RS·설정 경유·@ServerEndpoint 셋은 위반
0건, CORS 두 모양은 거짓 위반. rc=1.
- GREEN: :app-bootstrap:architectureTest --rerun 237건 실패 0, rc=0.
- 변이: 설정용 목록에 servlet.function, 요청 처리기 목록에 io.vertx.ext.web을
넣으면 UserTransportTypeListsTest 2건과 fixture 테스트 3건이 실패했다.
- :app-bootstrap:check, architectureCheck, :app-bootstrap:testQualityCheck,
:ci :verifyDependencyLocks --warning-mode=fail, :verifyStrictLaneStages
--dry-run, :sample-portfolio:check :sample-portfolio:qualityCheck,
-p optional-platforms ci, -p optional-platforms :verifyStrictLaneStages
--dry-run, scripts/verify-compose-profile-contracts.sh 모두 rc=0.
- 매뉴얼 07과 업그레이드 안내를 읽는 테스트는 없다(src grep 0건).
check-work-docs.py --links docs: 깨진 링크 0.
BREAKING CHANGE: 설정(@Configuration)에 중첩된 클래스를 사용자 전송 타입 전체로
판정한다. 그 안의 JAX-RS 자원·@ServerEndpoint 같은 endpoint가 @SystemCaller에
닿으면(설정의 메서드를 거쳐도) architectureTest가 실패한다. route·data fetcher·
interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다
(docs/upgrade/2026-11-maturity-review.md B-16).
Refs: docs/reviews/2026-11-03-rereview/round7/01-core-inbound.md RR7-01-01, RR7-01-02
문제: 이미 적용된 전이를 다시 보낸 호출에 Redis·PostgreSQL 저장소와
in-memory fake가 다르게 답한다.
- 같은 attempt가 넘겨받기 전 핸들로, 넘겨받은 뒤 적용된 complete를 다시
보내면 Redis·PostgreSQL은 ALREADY_COMPLETED_SAME_RESULT, fake는 NOT_OWNER.
- 같은 경우의 markFailed는 Redis ALREADY_MARKED_SAME_OPERATION, PostgreSQL
OPERATION_CONFLICT, fake NOT_OWNER. markFailed를 적용한 핸들이 응답을
잃고 다시 보내면 fake만 NOT_OWNER.
- release한 핸들로 start하면 PostgreSQL은 NOT_OWNER, Redis·fake는 ABSENT.
- 같은 원인(재생 판정이 "어느 핸들이 적용했나"를 보지 않음)이 다른 전이에도
있다. PostgreSQL은 기록된 renew·release와 digest가 다른 핸들을 모두
OPERATION_CONFLICT로 답해, 주인이 renew가 돌려준 핸들로 다시 renew해도
거절하고 넘겨받기 전 핸들의 renew·release도 OPERATION_CONFLICT다. fake는
적용한 핸들이 start·renew를 다시 보내도 NOT_OWNER다.
방법: 소유자 결정(2026-11-06) 「넘겨받기 전 핸들의 재전송」「해제된 핸들로
start」대로 맞춘다. "적용한 핸들"은 owner identity가 같고 기록보다
revision이 하나 낮은 핸들이다. 라운드6에서 start에 쓴 기준을 모든 전이에
쓴다.
- Redis TRANSITION과 command fake: ALREADY 조건에서 "start가 아니면 아무
핸들" 분기를 지우고 rev == handle rev + 1만 남긴다. 다른 핸들은 revision
검사로 내려가 NOT_OWNER·WRONG_STATE.
- PostgreSQL: replayVerdict가 적용한 핸들일 때만 재생(같은 digest → 이미
처리됨, 다른 digest → OPERATION_CONFLICT)으로 읽는다. 다른 핸들은 owner
검사로 내려가 NOT_OWNER. complete 재생 판정도 owner token 대신 적용한
핸들을 본다.
- fake: 마지막으로 적용한 전이와 그 핸들·인자(renew lease, fail disposition)
를 기억해 start·renew·complete·markFailed 재전송에 저장소와 같게 답한다.
- release한 핸들의 start는 계약이 ABSENT·NOT_OWNER를 둘 다 받고 포트
Javadoc(IdempotencyStartOutcome)에 적는다. 코드 동작은 그대로.
버린 대안: PostgreSQL complete·fail 재생을 전이 digest 비교만으로
하기(complete digest에 replay TTL이 들어가 같은 결과·다른 TTL 재전송이
RESPONSE_CONFLICT가 된다), Redis를 원래 주석 의도대로 두고 fake·PostgreSQL을
"operation의 아무 핸들"로 넓히기(소유자 결정과 반대, 넘겨받기 전 핸들이 남의
결과를 자기 것으로 확인받는다), 재생 핸들을 attempt만으로 가리기(같은
attempt가 넘겨받으면 attempt가 올라가지만 renew 뒤의 낡은 핸들은 attempt가
같다).
공유 계약 IdempotencyStoreContract에 10케이스를 더했다. 포트 결과 enum
Javadoc 넷, application-core CLAUDE.md·README, persistence-jpa·cache-redis
README, TESTING_STRATEGY, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.
위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 넘겨받기 전 핸들로 다시
보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접
부르는 코드는 넘겨받기 전 핸들의 재전송에 NOT_OWNER를 받고, PostgreSQL에서
renew를 이어 부를 수 있게 된다. fake로 응답 유실을 흉내 내던 테스트는 이제
"이미 처리됨"을 받는다. 적용한 핸들이 markFailed를 다른 retention·disposition
으로 다시 보낼 때의 답은 저장소마다 다르고 IdempotencyFailOutcome Javadoc과도
다르다(범위 밖, 보고에 적음).
검증: desktop, 공유 잠금, 기준 73d39212.
- RED(기준 커밋 + 계약 테스트만, 로그 ~/r8-f4-red-logs/): in-memory fake
계약 59 중 4 실패(적용한 핸들의 start·renew·markFailed 재전송,
"expected: ALREADY_MARKED_SAME_OPERATION but was: NOT_OWNER" 등), Redis
command fake 2·실 Redis(redisContainerContractTest) 2 실패("expected:
NOT_OWNER but was: ALREADY_COMPLETED_SAME_RESULT"·"…ALREADY_MARKED_SAME_
OPERATION"), 실 PostgreSQL(jpaPlatformContractTest) 5 실패(complete는
ALREADY_COMPLETED_SAME_RESULT, markFailed·renew·release는
OPERATION_CONFLICT, 두 번째 renew는 "expected: RENEWED but was:
OPERATION_CONFLICT"). release한 핸들의 start 케이스는 동작 변경이 없어
처음부터 셋 다 통과한다. lane마다 실패 수는 위 계약 실패 수와 같다.
- GREEN(이 커밋과 같은 트리 377d1232, 로그 ~/r8-f4-green-logs/): 네 leaf
check(application-core 422·skip 19 fake 시간 케이스, persistence-jpa 664,
cache-redis 225, redis-runtime 65), 네 leaf testQualityCheck,
redisContainerContractTest 100, jpaPlatformContractTest 429,
postgresqlIdempotencyIntegrationTest 10, fake를 쓰는 leaf(composition:
idempotency check 32, redis-sdk test 310, web test 329, sample-portfolio
test 339), documentContractTest 66 — 모두 rc=0, 실패 0.
- scripts/check-work-docs.py, git diff --check 통과.
BREAKING CHANGE: IdempotencyStorePort 구현은 이미 적용된 전이의 재전송을 그
전이를 적용한 핸들(기록보다 revision이 하나 낮은 핸들)에게만 "이미 처리됨"
으로 확인하고 다른 핸들은 NOT_OWNER로 답해야 한다. 직접 구현한 store는
IdempotencyStoreContract의 새 케이스로 확인한다.
문제: 2026-11-07 합친 브랜치 전체 게이트를 매뉴얼만 보고 돌리게 했더니
(1회차 수정 전 매뉴얼) 여섯 곳에서 답이 없었다.
- gates.md 3절 묶음에 main job(configuration-cache, compose smoke,
http3, notification pr)과 경로 필터 PR lane이 없어 "workflow와 같은
명령"이 아니었다
- 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차가 없었다
- 집계 태스크 전체가 실제로 돌았음을 보이는 법이 없었다(--rerun은
앞 태스크 하나만)
- lychee 대체 명령(--links docs)이 lychee 범위보다 좁았고, buf와
dependency review는 대체 안내가 없었다
- compose bind mount가 tmp/heap-dumps를 root로 만들어 git worktree
remove가 실패했다
- 결과 기록 형식이 게이트 하나 = Gradle 명령 하나를 가정했다
고른 방법:
- gates.md 3절을 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것,
(다) 로컬 도구가 없는 것으로 나눈다. (가)에 workflow의 run 줄을
더하고, (나)는 git diff --name-only를 on.pull_request.paths(glob)와
pr-adapters.yml emit 줄(정규식)에 맞추는 절차로, (다)는 job마다
로컬 대체와 대체가 못 보는 것을 적은 표로 둔다
- 실제 실행 증명: 새 worktree와 --no-build-cache, 로그의 FROM-CACHE 0
- 링크 검사 대체는 lychee와 같은 glob을 git ls-files로 넘긴다
- operate.md 4.1에 compose down과 root 폴더 지우기 한 줄
- gates.md 4절은 한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제
실행」 칸
- 처리 표(evidence.md 9절)에 T6 여섯 행
버린 대안: workflow의 모든 job 명령을 gates.md에 옮겨 적기. workflow가
정본이라 옮긴 사본이 낡는다. 경로 필터 lane은 절차만 둔다.
위험·한계:
- (가)의 명령은 workflow의 사본이다. workflow를 바꾸면 이 블록도 고쳐야
한다
- 경로 필터 맞추기는 손으로 한다. glob을 기계로 맞추는 도구는 없다
- 같은 범위 링크 검사는 지금 rc=1이다. src/README.md와 fileserver·
objectstorage README의 상대 링크 3건이 기준 커밋부터 깨져 있다(이번
범위 밖)
검증:
- python3 scripts/check-work-docs.py rc=0. improve.md 141/150,
delegate.md 121/150, operate.md 131/150, 진입 경로 최대 290/350,
본문 이력 0줄
- 바꾼 문서를 읽는 테스트: grep 결과 0(delivery-evidence.md 이름만
걸림)
- desktop: 바꾼 것을 패치로 73d39212 위에 얹어 이 커밋과 같은 트리
7e28874c를 만들고, flock 아래 :app-bootstrap:documentContractTest
--rerun --no-build-cache rc=0, 66건 실패 0 건너뜀 0, FROM-CACHE 0,
직전 1분 부하 5.64. 같은 트리에서 check-work-docs.py rc=0,
--history docs/manual 16줄 rc=1(기대대로)
(desktop ~/manual-gap-fix-2-logs/final-*.log)
- 링크 검사(lychee와 같은 범위) rc=1, 깨진 3건은 위 위험·한계의 것
(desktop ~/manual-gap-fix-2-logs/links-lychee-scope.log)
문제: 2026-11-06 같은 커밋을 두 세션이 따로 확인 리뷰했더니 합친 결함
8건 중 1건만 겹쳤다. 라운드의 Important 2건도 한 리뷰어의 첫 리뷰 밖에서
나왔다. 반복은 마지막 확인 리뷰의 0건으로 멈추는데, 리뷰어 하나의 0은
남은 결함이 0이라는 증거로 약하다.
고른 방법: 2026-11-07 소유자 결정("(c)로 받기")대로 세 경우에만
서로 결과를 보지 않는 리뷰어 둘이 같은 범위를 보고 총괄이 합친다.
- 멈추는 확인 리뷰: 리뷰어 하나가 0을 내면 두 번째가 본다. 둘 다 0이어야
멈춘다(improve.md 4.5 1)
- 수정 diff가 상한에 가까운 리뷰: 추가 1,000줄 이상
- Critical·Important를 고친 수정의 리뷰
정본 리뷰어만 리뷰 폴더에 커밋하고 ID를 매긴다. 다른 쪽은 보고에 같은
양식을 두고 임시 번호 B-NN-MM을 쓴다. 합칠 때 총괄이 같은 결함끼리
짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어가 탐침으로 다시 확인해 다음
번호로 넣는다. 겹침 비율을 색인 절과 지표 기록(M11)에 적는다.
버린 대안: 언제나 둘(비용 약 2배), 지금처럼 하나(멈춤 판정이 약함).
소유자가 2~3라운드 겹침 비율을 보고 다시 정한다.
위험·한계:
- "상한에 가까움"을 추가 1,000줄 이상으로 정한 것은 기본값이다
(decisions.md 2.1에 적음)
- 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립성은 brief의
금지 문장과 노트 이름 분리에 기대고, 막는 장치는 없다
- 같은 범위를 두 번 보므로 그 리뷰의 비용이 약 두 배다
검증: 이 커밋의 트리에서 python3 scripts/check-work-docs.py rc=0. desktop 검증은 다음 커밋의 트리로 했다(그 커밋 본문)
문제: 앞 커밋에서 더한 한국어 라운드 번호 패턴이 "1라운드"(지난 라운드
하나의 이름)와 "2~3라운드 동안"(라운드 수)을 가르지 못한다. 확인 리뷰를
독립 리뷰어 둘로 하는 소유자 결정을 delegate.md에 옮기다가 "2~3라운드
기록이 쌓이면"이 이력 ID로 잡혀 기본 검사가 rc=1이 됐다.
고른 방법: 범위 기호(~, -) 바로 뒤의 숫자와, 뒤에 동안·마다·씩·간이
붙는 경우를 뺀다. 버린 대안: 문서에서 "라운드 두세 번"으로 돌려 쓰기.
다음에 쓰는 사람이 같은 오탐을 다시 만난다.
위험·한계: "3라운드 뒤"처럼 다른 낱말이 붙는 횟수는 아직 이력으로
잡는다. 그때는 문장을 고치거나 패턴에 낱말을 더한다.
검증:
- 패턴 시험 19건(보통 문장 11, 이력 8)이 모두 기대대로 나왔다
- python3 scripts/check-work-docs.py rc=0, 본문 이력 0줄
- --history docs/manual 결과는 16줄 그대로(rc=1)
문제: docs/manual 본문 19줄이 "리뷰 02-01 결정", "1라운드 06-01·06-03",
"리뷰 README 13.2, 09-02", "(05-01, 04-01, 06-01)", "sample P30 결정"처럼
지난 리뷰 번호만으로 이유를 댄다. 그 리뷰를 모르는 독자는 따라갈 수
없고, docs-writing.md 4절 6단계가 금지한다. 16줄은 --history 검사가
찾았고, 3줄은 걷어낸 뒤 grep으로 다시 읽어 찾았다.
고른 방법: 문장의 뜻은 두고 괄호만 바꾼다.
- 문장이 이미 내용을 말하는 곳(6줄)은 괄호를 지운다
- 지난 일이 근거인 곳은 날짜와 일어난 일로 바꾼다. 예: "2026-11-01
소유자 결정", "2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다"
- README 제목 "1라운드 수정으로 생긴 패턴 (리뷰 README 13절)"은
"리뷰 뒤 첫 수정으로 생긴 패턴"으로 바꾼다. 이 제목을 가리키는 링크는
repo에 없다
걷어낸 번호와 원래 괄호, 원래 리뷰 문서와 발견 내용은
docs/work/evidence.md 8절에 표로 더했다(2026-11-06 표와 같은 칸).
버린 대안: 리뷰 문서로 링크 걸기. 본문이 다시 이력을 가리킨다.
위험·한계: 날짜와 "전에는" 문장은 1101 README 13절·15절과 영역 문서의
색인 문장에서 옮겼다. 코드로 다시 확인하지는 않았다. evidence.md 9절
T4-1 행("16줄은 고치지 않음")은 그때의 기록이라 고치지 않았다.
검증(desktop worktree, 이 커밋과 같은 트리 8ff82a67):
- python3 scripts/check-work-docs.py --history docs/manual
lines with history IDs: 0, rc=0
- python3 scripts/check-work-docs.py rc=0(분량, 본문 이력 0, 링크)
- python3 scripts/check-work-docs.py --links docs/manual docs/work
링크 113개, 깨진 것 0
- ./gradlew :app-bootstrap:documentContractTest rc=0, 22개 클래스
66건 통과, 실패·skip 0. docs/manual과 docs/work를 읽는 테스트는 없다
(src의 Java·Gradle에서 파일 이름·폴더 경로 grep, 주석 2곳만 걸림)
- grep -e 리뷰 -e 라운드 -e 결정 docs/manual/*.md로 남은 줄을 읽었다.
모두 날짜와 내용이 있는 문장이다
문제: check-work-docs.py --history는 리뷰·라운드 낱말 바로 뒤의 NN-NN만
발견 번호로 본다. 그래서 앞말 없이 나열한 "(05-01, 04-01, 06-01)",
"리뷰 01 영역 5.2절", "sample P30 결정"을 놓친다. 2026-11-07 docs/manual
이력 걷어내기에서 검사가 찾은 16줄을 고친 뒤 docs-writing.md 9절대로
grep으로 다시 읽으니 이 꼴 3줄이 더 있었다.
고른 방법: 패턴 셋을 더한다.
- 쉼표+공백이나 가운뎃점으로 이은 NN-NN 둘 이상. 콜론 뒤 줄 범위
("Foo.java:10-12,20-24")와 공백 없는 쉼표 범위는 잡지 않는다
- "리뷰 NN 영역", "NN 영역 N.N절"
- 2026-09-25 리뷰 후속 묶음 번호 P10~P49와 "W3-P30" 꼴
버린 대안:
- 홀로 선 NN-NN 하나까지 잡기. 장 번호·범위 같은 보통 숫자가 걸린다
- P 뒤 두 자리를 모두 잡기. P95·P99 같은 백분위수가 걸린다
위험·한계: 검사는 여전히 아는 꼴만 잡는다. P1~P9 묶음 번호는 우선순위
P0~P3과 겹쳐 잡지 않는다. 문서가 자기 목록에 P10~P49 번호를 붙이면
이력이 아니어도 잡는다(docs/study/graphql-walkthrough.ko.md의 할 일
번호 P10·P11). 지금 검사 대상인 docs/work 본문과 docs/manual에는 그런
줄이 없다. 이 커밋만 있으면 --history docs/manual이 19줄, rc=1이다.
다음 커밋이 그 19줄을 걷어낸다. 기본 모드(docs/work 본문, 루트
CLAUDE.md)는 0줄 그대로다.
검증(desktop worktree, 다음 커밋까지 얹은 트리 8ff82a67과 같은 스크립트):
- 기준 커밋 73d39212의 docs/manual: 옛 스크립트 16줄, 새 스크립트 19줄.
더 잡은 3줄은 03-placement.md:40·:54, 05-idempotency.md:93이다
- 오탐 시험 14줄: 보통 문장 8줄(p95·P99, 콜론 뒤 줄 범위, 날짜 쌍,
홀로 선 번호, 장 번호)은 안 잡고 이력 6줄은 잡았다
- 노트북에서 docs/reviews 밖 *.md에 새 패턴을 돌려 걸린 65줄을 읽었다.
위 할 일 번호 4줄 말고는 모두 실제 이력 번호였다
- 기본 모드 rc=0, 본문 이력 0줄
문제: round7 1차 리뷰의 「Declined to judge」 12건이 판정 없이 남아
멈춤 기준 2(열린 Declined 0)가 거짓이었다. round6 판정 표의 두 줄은
"다른 브랜치 병합 시 닫힘"으로 열려 있었다.
방법: 리뷰 브랜치(2c8a359d, t3·t5 수정과 2026-11-06 결정 포함)로
fast-forward한 뒤 round6 30건과 같은 방식으로 판정했다. (a) 3건 —
RR7-02-02(in-memory fake의 같은 핸들 재시작 NOT_OWNER), RR7-03-06
(Flyway 규칙이 Flyway.configure()만 막음), WebFlux 타입은 RR7-01-01에
합침. (b) 8건, 그중 둘은 정해진 결정(같은 token·다른 operation의
claim, Flyway PostgreSQL 잠금)으로 닫음. (c) 1건 — 태그·릴리스
trigger만 있는 workflow를 단계 실행으로 셀지, 18.4절에 선택지와 권하는
안. round6 판정 표의 t3·t5 두 줄은 합친 트리에서 확인해 닫았다.
총괄 지시대로 README는 18.4절과 18.5절 판정 표만 고쳤다(18.1절 색인
표에는 새 발견 둘을 넣지 않았다).
위험·한계: 새 발견 둘은 코드 경로(E1)만 봤다. 실행 탐침은 돌리지
않았다.
검증: check-review-index.py docs/reviews/2026-11-03-rereview rc=0
(172건), check-work-docs.py --links(round7 문서) rc=0.
Refs: docs/reviews/2026-11-03-rereview/README.md 18.4·18.5절
문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다
고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
(operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
(고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.
위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다
검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
트리 3d0e5900을 만들고 flock 아래
:app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
건너뜀 0, 13초, 직전 1분 부하 3.13
(desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
문제: check-work-docs.py --history는 날짜 접두어(MMDD/), RR 접두어,
묶음 이름, round 폴더, 번호만 쓴 결정, 커밋 sha만 이력 ID로 본다.
그래서 "리뷰 02-01 결정", "1라운드 06-01·06-03", "리뷰 README 13절"처럼
날짜 접두어 없이 쓴 리뷰 번호를 놓친다. 2026-11-06 docs/manual 이력
걷어내기 시험에서 --history가 0을 냈는데, 손으로 찾으니 16줄이 남아
있었다.
고른 방법: 패턴 셋을 더한다.
- 리뷰·라운드·review 낱말 뒤 20자 안에 홀로 선 NN-NN. 2026-11-01 같은
날짜의 일부는 홀로 선 번호가 아니라 잡지 않는다
- 한국어 라운드 번호(1라운드, 라운드6)
- 리뷰 README 절 번호(리뷰 README 13절)
버린 대안: 앞말 없이 모든 NN-NN을 잡기. 장 번호·시각 범위 같은 보통
숫자까지 잡아 오탐이 많다.
위험·한계: 검사는 아는 꼴만 잡는다. 다른 꼴은 걷어낸 뒤 grep으로 한 번
더 읽는다(docs-writing.md 자주 하는 실수). 이 커밋 뒤 --history
docs/manual은 16줄을 내고 rc=1이 된다. 그 16줄은 이번에 고치지 않는다.
다음 cold-read 시험 과제다. 기본 모드(docs/work 본문, 루트 CLAUDE.md)는
0줄 그대로다.
검증:
- 고치기 전 python3 scripts/check-work-docs.py --history docs/manual
결과 0줄, rc=0
- 고친 뒤 같은 명령 결과 16줄, rc=1. 2026-11-06 시험 세션이 손으로 찾은
16줄과 같다
- 오탐 시험 12건(보통 문장 7, 이력 5)이 모두 기대대로 나왔다
- 기본 모드 rc=0, 본문 이력 0줄. desktop worktree에서도 같다
round7 확인 리뷰와 멱등 저장소 수정(t5)이 소유자 결정 네 건을 남겼고,
소유자가 2026-11-06 모두 권하는 안으로 정했다. 다음 수정 묶음이 다시
묻지 않도록 결정 색인의 해당 절에 내용과 출처를 적는다.
- 계약·오류: 네 전송이 원인 사슬의 첫 carrier를 본다
- 멱등성: 넘겨받기 전 핸들의 재전송은 적용한 핸들에게만 확인한다,
해제된 핸들의 start는 ABSENT와 NOT_OWNER를 둘 다 받는다
- 영속성: 실패한 동시 인덱스 마이그레이션은 그 버전의 실패 이력 행만
지우고 다시 배포한다
- 빌드·게이트: paths 필터 trigger만 있는 workflow는 단계 실행으로
세지 않는다
검증: scripts/check-work-docs.py rc=0.
문제: 같은 커밋 6e992970을 따로 본 리뷰(claude/t1-baseline-7d623a
3add4917)가 이 리뷰에 없는 결함 셋을 찾았고 ID가 겹쳤다. 다른 세션이
코드 읽기로만 찾은 결함 후보(LockAcquisitionTimeoutException)가 남아
있었다. round6 「Declined to judge」 30건은 처리 기록이 없어 멈춤 기준
2가 거짓이었다.
방법: 넘겨받은 셋은 그쪽 근거를 읽고 이 리뷰의 기준 커밋 06f520e6에서
탐침을 다시 돌려 새 ID로 넣었다(RR7-01-03, RR7-03-03, RR7-03-04, 겹친
RR7-01-01은 합침, README 18.2절 대응표). 동시 인덱스 복구는 실패 이력
행 삭제를 더한 경우도 돌려 권하는 절차를 확인했다. 락 후보는 web·
GraphQL 탐침으로 500 INTERNAL_ERROR를 확인해 RR7-01-04(Important)로
넣었다. round6 Declined 30건은 (a) 4 · (b) 24 · (c) 2로 판정해 (a)를
RR7-01-05·06, RR7-02-01, RR7-03-05로 올렸다. 소유자 결정 셋(RR7-05-01,
RR7-03-03 복구, RR7-01-05 방향)을 18.4절 한 표로 모았다. 버린 대안:
다른 리뷰의 review.md를 그대로 합치기(같은 ID가 다른 결함을 가리킴).
결과: 결함 13건(Important 2, Minor 11, 회귀 1).
위험·한계: RR7-01-05·06, RR7-02-01, RR7-03-01·05는 코드 경로만(E1)
봤다. 라운드 끝 게이트는 다시 돌리지 않았다. round7 1차 Declined 12건은
아직 판정하지 않았다. (b) 2건은 t3·t5 브랜치가 병합돼야 닫힌다.
검증: check-review-index.py docs/reviews/2026-11-03-rereview rc=0(170건),
check-work-docs.py --links(round7 6개 문서) rc=0. desktop 공유 잠금 아래
탐침 B1~B4(~/t1-r10-review-logs/summary.txt), 결과는 공유 노트
rr7-probes/results/pass2-06f520e6.txt.
Refs: docs/reviews/2026-11-03-rereview/README.md 18절
문제: 같은 호출에 Redis와 PostgreSQL 저장소(와 in-memory fake)가 다르게
답한다.
- owner token이 같아도 호출이 claim과 다른 operation id를 대면 Redis는
다섯 전이(start·renew·complete·fail·release)를 OPERATION_CONFLICT로
거절하고 PostgreSQL·fake는 적용한다. PostgreSQL은 CAS에 핸들의 claim
operation만 쓰고 호출의 id는 last_transition_operation_id에 적기만 한다.
- PostgreSQL complete 재생은 operation id만 보고 owner를 보지 않아, 같은
id를 쓴 다른 attempt의 늦은 complete를 이미 적용된 완료로 확인한다.
Redis는 NOT_OWNER.
- fake의 claim·inspect는 같은 token·다른 operation에 OwnerOperationConflict
·OPERATION_CONFLICT를 내지 않는다. PostgreSQL·fake의 inspect는 완료된
기록이면 그 응답을 재생하고 Redis는 OPERATION_CONFLICT.
- 기록이 없는 release에 Redis는 ALREADY_RELEASED_SAME_OPERATION, PostgreSQL
·fake는 ABSENT. Redis release는 revision을 보지 않아, 같은 attempt가 claim을
넘겨받기 전 핸들로 지금의 claim을 지운다.
방법: 소유자 결정 (a)로 PostgreSQL·fake를 Redis에 맞춘다. owner token이
같고 호출 id가 기록의 claim id와 다르면 다섯 전이 모두 OPERATION_CONFLICT,
기록은 그대로. 나머지 셋은 "거절이 안전한 쪽, 운영 호출자 경로가 안 바뀌는
쪽"으로 정했다.
- complete 재생은 같은 owner token에만 확인한다(Redis에 맞춤).
- fake claim은 진행 중 기록에 OwnerOperationConflict, inspect는 같은 token·
다른 operation이면 상태와 상관없이 OPERATION_CONFLICT. PostgreSQL inspect도
완료 재생보다 이 검사를 먼저 한다.
- 기록 없는 release는 셋 다 ABSENT. Redis adapter가 ABSENT를 그대로 넘기고
RELEASE 스크립트와 command fake가 핸들 revision을 본다. release한 기록을
지울지 남길지는 저장소 선택이라 release 재시도는 ABSENT(Redis·fake)와
ALREADY_RELEASED_SAME_OPERATION(PostgreSQL)으로 갈리는 것을 계약이 허용한다.
버린 대안: Redis를 PostgreSQL에 맞추기(Redis에는 전이 id를 둘 필드가 없어
인자가 죽는다), PostgreSQL release를 삭제로 바꾸기(release 뒤 기록 모양은
계약이 저장소 선택으로 정해 두었다), 기록 없는 release를 셋 다
ALREADY_RELEASED로(찾지 못한 것을 성공으로 확인한다 — JPA 설계 22.2와 반대).
공유 계약 IdempotencyStoreContract에 12케이스를 더했다. 포트·결과 enum
Javadoc, persistence-jpa·cache-redis README, TESTING_STRATEGY, application-core
CLAUDE.md, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.
위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 늘 claim의 id를 넘기고
release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르며 전이마다
다른 id를 넘기던 코드는 OPERATION_CONFLICT를 받는다. PostgreSQL 통합
테스트가 그렇게 쓰고 있어 claim의 id로 바꿨다. last_transition_operation_id
열은 이제 늘 claim_operation_id와 같다(마이그레이션은 건드리지 않음).
같은 token의 넘겨받기 전 핸들로 이미 끝난 complete·markFailed를 다시 보내는
경우는 저장소마다 답이 다르다(범위 밖, 보고에 적음).
검증: desktop, 공유 잠금, 기준 06f520e6.
- RED(기준 커밋 + 계약만): in-memory fake 계약 49 중 8 실패, Redis
command fake 2, 실 Redis(redisContainerContractTest) 2, 실 PostgreSQL
(jpaPlatformContractTest) 7 — 실패 메시지가 위 차이 그대로("expected:
OPERATION_CONFLICT but was: STARTED", "expected: ABSENT but was:
ALREADY_RELEASED_SAME_OPERATION" 등).
- GREEN(이 커밋과 같은 트리): 네 leaf check(application-core 412·skip 19
시간 케이스, persistence-jpa 664, cache-redis 215, redis-runtime 65),
네 leaf testQualityCheck, jpaPlatformContractTest 419,
postgresqlIdempotencyIntegrationTest 10, redisContainerContractTest 90,
app-bootstrap integrationTest 10, sample integrationTest 63,
documentContractTest 65, architectureTest 228, composition:idempotency
check 32 — 모두 rc=0, 실패·skip 0(fake 시간 케이스 19 제외).
- scripts/check-work-docs.py, --links docs, git diff --check 통과.
Refs: docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md Declined to judge
BREAKING CHANGE: 멱등 store 포트를 직접 부르는 코드는 전이마다 claim의
operation id(IdempotencyOwner.claimOperationId())를 넘겨야 한다. 다른 id는
OPERATION_CONFLICT다. Redis release는 기록이 없으면 ABSENT를 돌려준다.
직접 구현한 store는 IdempotencyStoreContract의 새 케이스를 통과해야 한다.
문제: docs/registries/error-codes.yaml의 log_level 칸은 읽는 코드가 없다.
로그 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다
(ServerFailureLog, AuthErrorResponseWriter). 그래서 그 코드를 내는 곳이 있는
47행 중 33행이 실제 레벨과 달랐고, 런북 2곳이 틀린 레벨을 증상으로 적었다.
고른 방법: 칸을 지우고, 머리말이 레벨을 정하는 코드를 가리킨다(설계 메모 안
A, 소유자 결정 2026-11-06). 칸이 다시 생기지 않게
OperationalErrorRegistryContractTest에 단언을 둔다. client_safe_message를
코드에 고정한 테스트가 있는 자리다. 모든 레지스트리의 공통 스키마를 보는
ContractRegistrySchemaGovernanceTest는 한 레지스트리의 칸 뜻을 다루지 않아
고르지 않았다. 런북은 실제 로그 줄을 증상으로 적는다. 결정 색인 2.3절과
설계 메모 10절에 결정을 남겼다.
버린 대안: 칸을 코드에 맞추고 테스트로 고정(B) — 규칙의 손 사본이 생기고,
템플릿이 내지 않는 13행은 고정할 값이 없다. 칸을 규범으로 만들어 코드가
읽기(C) — 4xx를 남기지 않는 설계를 뒤집고 로그 양이 는다.
위험·한계: 자기 error-codes.yaml 행에 log_level을 둔 파생 서비스는 merge
뒤 mainCheck(documentContractTest)가 실패한다. upgrade 안내 「반드시 할 일」
17과 B-44에 적었다. repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다(소유자
결정 4).
검증(desktop, 공유 잠금, 로그는 desktop ~/t3-loglevel-logs/):
- RED: 기준 yaml로 OperationalErrorRegistryContractTest 3건 중
noRegistryRowCarriesALogLevel 1건 실패(log_level이 있는 행 목록 출력).
rc=1, red-registry.log
- GREEN: :app-bootstrap:documentContractTest rc=0, 66건 실패 0
(RunbookCoverageContractTest 포함). green-doc-contract.log
- :app-bootstrap:testQualityCheck :app-bootstrap:spotlessCheck rc=0.
green-quality.log
- python3 scripts/check-work-docs.py rc=0, --links docs 깨진 링크 0
BREAKING CHANGE: error-codes.yaml 행에 log_level이 있으면
OperationalErrorRegistryContractTest가 실패한다. 파생 서비스는 자기 행에서
log_level: 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다.
문제: AuthErrorResponseWriter는 보안 필터가 답한 실패를 모두 WARN으로
남긴다. AUTH_JWKS_UNAVAILABLE(503, 키 서버 장애)과
INTERNAL_AUTH_MISCONFIGURATION(500, 인증 설정 오류)은 서버 쪽 고장인데도
WARN이다. 다른 모든 경로는 5xx를 ERROR로 남기므로(ServerFailureLog) 규칙이
갈라져 있고, ERROR로 거르는 운영자는 이 둘을 놓친다.
고른 방법: 응답 상태로 레벨을 고른다. 5xx는 ERROR, 4xx는 WARN이다. 줄의
모양(code·category·method·path, 예외 없음)은 그대로다. 401 서명·issuer·
audience 불일치는 WARN으로 둔다(소유자 결정 3, 2026-11-06). 테스트가 서명
실패 WARN도 고정한다.
버린 대안: 두 코드를 이름으로 나열하기 — 새 5xx 보안 코드가 생기면 조용히
WARN에 남는다. ServerFailureLog 줄로 바꾸기 — 예외를 붙이는 줄이라, 토큰이
섞일 수 있는 실패 메시지를 남기지 않는 이 writer의 계약과 맞지 않는다.
위험·한계: ERROR 수로 경보를 거는 곳에 JWKS 장애와 인증 설정 오류가 새로
잡힌다. upgrade 안내 5절에 적었다. 결정은
docs/superpowers/specs/2026-11-06-error-code-log-level-design.md 10절이다.
검증(desktop, 공유 잠금, 로그는 desktop ~/t3-loglevel-logs/):
- RED: 기준 writer로 EnvelopeAuthenticationEntryPointTest 8건 중 2건 실패
(aKeyServiceOutageIsLoggedAtError, aDecoderMisconfigurationIsLoggedAtError
— WARN이 나오고 ERROR를 기대). rc=1, red-web.log
- GREEN: :adapter:inbound:web:check rc=0, 테스트 329건 실패 0.
green-web-check.log
- :adapter:inbound:web:testQualityCheck rc=0, green-quality.log
문제: r10(6e992970)은 round6 결함 25건을 고친 커밋 하나로 +5,143줄이다.
확인 리뷰 상한(추가 1,500줄, docs/work/improve.md 4.4절)을 넘어, 수정이
새로 만든 결함을 영역마다 따로 봐야 했다.
방법: 영역 pathspec 다섯(01 core·inbound +1056, 02 멱등성 +407,
03 persistence +877, 04 build-logic 셸 판독 +659, 05 workflow 판독
+1288)으로 나눠 차례로 리뷰했다. build-logic은 한 묶음이 +1,916줄이라
둘로 갈랐다. 의심 결함은 desktop 임시 worktree의 탐침으로 확인했다.
r9(45d2a478)에 같은 탐침을 돌려 회귀인지 가렸다. 버린 대안: 커밋 전체를
한 문서로 보는 것(상한 위반), 리뷰 기록 round6(+829줄)까지 읽는 것.
결과: Critical 0, Important 0, 회귀 1. 결함 5건 모두 Minor.
RR7-01-01 설정에 중첩된 JAX-RS 자원·@ServerEndpoint를 놓침(회귀),
RR7-01-02 메서드 참조 route 설정의 거짓 실패, RR7-03-01 ledger IT의
없는 예외 장치 안내, RR7-03-02 REINDEX SCHEMA|DATABASE CONCURRENTLY
설명 오류, RR7-05-01 경로 필터 workflow를 "매 변경"으로 셈. RR6 항목은
RR6-03-05만 부분이고 나머지는 닫혔다.
위험·한계: 라운드 끝 게이트와 실 Redis·실 PG 계약 lane은 다시 돌리지
않았다(17.2절 2c692554 결과가 마지막). leaf test 10개는 FROM-CACHE다.
RR7-05-01은 경로 필터 정책을 소유자가 정해야 고칠 수 있다(18.3절).
round6 Declined 30건이 처리 기록 없이 남아 멈춤 기준 2가 거짓이다.
검증: python3 scripts/check-review-index.py docs/reviews/2026-11-03-rereview
rc=0(162건 모두 색인). check-work-docs.py --links(새 문서 6개) rc=0.
desktop 탐침 4종 rc=0(~/t1-r10-review-logs/summary.txt), 탐침 코드는
공유 노트 rr7-probes/. architectureTest --rerun 229건, build-logic test
--rerun 169건, persistence-jpa test 664건 실패 0.
Refs: docs/reviews/2026-11-03-rereview/README.md 18절
문제:
JDK transport는 attempt deadline을 Spring JdkClientHttpRequest의 read
timeout 하나로 끊는다. DeadlineAwareJdkRequestFactory는 그 값을
AttemptDeadline.bound(response-header)로 정하고, bound는 남은 시간을
나노초까지 그대로 돌려준다. Spring 7.0.9 TimeoutHandler는 이 값을
Duration.toMillis()로 잘라 timer를 건다. 그래서 timer가 deadline보다
최대 1ms 먼저 터진다.
BlockingAttemptExecutor.finish와 circuit breaker 제외 조건
(deadline.setByCaller() && scope.expired())은 엔진이 포기한 뒤에
scope.expired()로 deadline이 원인인지 묻는다. 그 순간 deadline은 아직
지나지 않았다. 그래서 호출자 deadline으로 끊긴 시도가
HttpResponseTimeoutException(헤더 대기 중)이나
HttpResponseTruncatedException(본문 중)으로 보고되고, breaker는 그것을
상대 장애로 센다. 건강한 상대 서버에 circuit이 열릴 수 있다.
CircuitBreakerStatusAccountingTest의 JDK 변형 2건이 이 경로로 실패했다.
고른 방법:
bound가 남은 시간으로 줄인 값을 다음 밀리초로 올린다. 엔진 timer는
bound를 계산한 뒤에 걸리므로, 올린 값을 밀리초로 잘라 건 timer도
deadline보다 먼저 끝나지 않는다. 단계 timeout이 더 짧으면 그 값을 그대로
둔다.
버린 대안:
- JDK 일반 요청도 scope abort로 끊기(Apache·Jetty 방식). Spring 요청의
응답 future에 닿을 수 없어 JdkClientHttpRequest를 본문 닫기까지 다시
구현해야 한다. 결함 크기에 비해 바뀌는 면이 크다.
- finish에서 1ms 여유를 두고 deadline으로 판정. deadline 근처에서 터진
진짜 단계 timeout도 deadline으로 바꿔 부르는 추측이다.
- factory에서만 올리기. bound를 쓰는 다음 엔진이 같은 함정에 빠진다.
위험·한계:
- deadline으로 줄인 JDK timer는 deadline보다 1ms 미만 늦게 끝난다.
JDK 일반 요청이 deadline을 넘기는 시간이 그만큼 늘어난다.
- 같은 원인을 찾아본 곳: JDK 스트리밍 setup(JDK 요청 timeout은 나노초를
지키고 deadline은 scope abort가 끊는다), Apache·Jetty(scope abort가
fired를 먼저 세운다), messaging DefaultMessagePublisher.withDeadline
(밀리초로 자르지만 원인을 TimeoutException 타입으로 판정한다),
gRPC·Redis(나노초 단위). 같은 원인은 없었다.
검증(desktop, 공유 잠금 아래, 로그 ~/t2-cb-logs/):
- RED: 기준 커밋 06f520e6에 새 테스트만 얹고
CircuitBreakerStatusAccountingTest·AttemptDeadlineTest를 --rerun으로
10회. 10/10 rc=1. 새 단위 테스트 10/10 실패, CircuitBreaker JDK
변형은 10회 중 9회 실패(JDK 케이스 20건 중 14건).
- GREEN: 수정 트리에서 같은 명령 10회 두 번. 20/20 rc=0, 실패 0.
- ./gradlew ci: rc=0(93초, 다른 leaf는 캐시 재사용, httpclient test
359건·계약 23건·보안 9건·Spring 6.2 스캔 7건 실제 실행).
- :adapter:outbound:httpclient:testQualityCheck spring70CompatibilityTest
(23건) rc=0, httpClientFailureInjectionTest(Toxiproxy, 4건) rc=0.
Fixes: 34565130e0 ("fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다")
문제: docs/registries/error-codes.yaml의 log_level 칸은 읽는 코드와 테스트가
없다. 코드의 로그 레벨은 오류 코드가 아니라 실패 종류와 경로가 정한다
(ServerFailureLog, AuthErrorResponseWriter). 그래서 내는 곳이 있는 47행 중
33행이 실제 레벨과 다르고, 런북 2곳이 틀린 레벨을 증상으로 적는다.
고른 방법: 설계 메모만 쓴다. 대안 셋(A 칸 삭제, B 코드 규칙에 맞추고
테스트로 고정, C 규범화해 코드가 읽음)을 비교하고 A를 권한다. B는 규칙의
손 사본을 테스트에 하나 더 만들고, C는 리뷰를 거친 4xx 무로그 설계를 뒤집고
로그 양을 늘린다. 소유자 결정 4건(칸, 재생성 방지 단언, 보안 필터 5xx 레벨,
401 서명 불일치 레벨)을 7절에 모았다.
위험·한계: 60행 대조는 코드 읽기 결과이고 실행 탐침은 돌리지 않았다. repo
밖 운영 도구가 이 칸을 읽는지는 모른다(결정 4). 코드와 yaml은 바꾸지
않았다. 조사 중 본 LockAcquisitionTimeoutException 미매핑은 9절에 범위 밖
결함 후보로만 적었다.
검증: python3 scripts/check-work-docs.py rc=0. 메모 2.3 표의 코드 목록을
레지스트리 60개 코드와 대조해 누락·중복 0을 확인했다.
docs/manual/ 본문 9줄에 리뷰 ID(RR-, RR3-, RR5-, RR6-), 설계 결정 번호(D4),
번호만 쓴 소유자 결정("소유자 결정 5")이 있었다. 지난 리뷰를 모르는
독자는 이 괄호를 따라갈 수 없고, docs-writing.md 4절 6단계가 금지한다.
괄호 안의 ID만 걷어내고 문장의 뜻은 바꾸지 않았다. 지난 일을 근거로 든
곳은 날짜와 내용으로 바꿨다(2026-11-05 확인 리뷰, 2026-09-25 소유자 결정).
D4는 규칙 이름 대신 "쓰기 유스케이스의 권한 선언 검사"로 풀었다. 걷어낸
ID와 원래 괄호, 원래 리뷰 문서는 docs/work/evidence.md 8절에 모았다.
리뷰 문서로 링크를 거는 안은 본문이 다시 이력을 가리키게 되어 버렸다.
검사 스크립트 패턴이 못 잡는 "리뷰 NN-NN", "1라운드 NN-NN" 꼴의 ID는
이 커밋 범위 밖이라 남겼다.
검증: python3 scripts/check-work-docs.py --history docs/manual
(lines with history IDs: 0, rc=0), check-work-docs.py 전체 rc=0,
--links docs 깨진 링크 0. document-contract lane은 desktop에서 돌린다.
문제: 성능 lane 단언을 빌드가 강제하게 된 뒤에도 docs/work/는 옛 동작을
안내했다. gates.md 5절은 "desktop에서 -Pperformance.assertions.enabled=true를
준다. 안 주면 httpclient의 시간 단언 없이 통과한다"고 했고, 3절 라운드 끝
명령과 improve.md·operate.md의 「자주 하는 실수」도 그 속성을 맞추라고 했다.
지금은 convention이 단언을 켜고 true 아닌 값이나 skip이 있으면 테스트 전에
실패하므로, 그 문장은 틀렸고 그 속성은 필요 없다. 또 2026-11-06 B3 desktop
ci rc=0은 캐시 결과(태스크 701개 중 403개)였는데, 그 사이 httpclient
CircuitBreakerStatusAccountingTest 2건은 기준 커밋에서도 10번 중 10번 실패하고
있었다. 캐시 결과를 현재 통과의 증거로 쓰면 이런 기존 결함을 놓친다.
고른 방법:
- gates.md 5절을 새 동작으로 다시 쓰고(정본 AGENTS.md 「Gradle 정책 권위」,
docs/testing/TESTING_STRATEGY.md), 1절 표와 6절 거짓 통과 표를 맞췄다.
3절 명령에서는 그 속성을 뺐다. workflow도 이제 주지 않는다.
- improve.md의 같은 실수 줄은 지웠다. 빌드가 막으므로 더는 실수가 아니다.
- operate.md 「자주 하는 실수」의 그 줄 자리에 캐시 교훈을 넣었다: 기준 상태와
시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. gates.md
6절에도 한 줄, 근거는 evidence.md 2절, 결정은 decisions.md 2.7, 장치는
defect-patterns.md A7에 더했다.
위험·한계: --rerun은 지정한 태스크 하나만 다시 돈다. 집계 태스크 전체를 캐시
없이 돌리려면 --rerun-tasks가 필요하고 시간이 훨씬 길다. 이 매뉴얼은 그 둘을
가르는 기준까지는 정하지 않았다.
검증
- python3 scripts/check-work-docs.py: rc=0, 본문 이력 ID 0줄, improve.md
131/150, operate.md 115/150
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
AGENTS.md: 깨진 링크 0
성능 lane 단언을 빌드가 강제하게 바꾼 e6b6e18e를 이 브랜치 위로 합친다.
충돌: CLAUDE.md 하나. 리뷰 브랜치는 옛 CLAUDE.md의 「Gradle policy
authorities」·「Testing」 절에 성능 lane 문장을 더했고, 이 브랜치는 그 절들을
지도로 바꾸며 지웠다. 지도를 남기고, 더해진 뜻("성능 lane에는 단언을 끄는
스위치가 없다. true 아닌 값이나 skip이 있으면 테스트 전에 실패한다. 손으로
돌리든 workflow든 같다")은 지도 5절 「헷갈리는 곳」에 한 줄로 살렸다. 정본은
AGENTS.md 「Gradle 정책 권위」이고, 그 문단은 충돌 없이 함께 합쳐졌다.
검증
- python3 scripts/check-work-docs.py: rc=0
문제: 성능 lane의 기계 의존 상한(httpclient 스트리밍 힙 증가, Mongo 시간
gate)이 performance.assertions.enabled 뒤에 있었고 기본값이 자리마다
달랐다(httpclient build false, Mongo build true, Mongo 테스트 코드 false).
workflow만 GRADLE_OPTS로 켰다. 그래서 desktop에서 손으로 돌린
./gradlew :performanceCheck가 httpclient 힙 상한을 재지 않고 통과했다
(2026-11-05 r10 게이트). JPA pool lane도 전에 같은 속성 뒤에서 아무 상한도
비교하지 않았다(PoolLaneClaimTest).
방법: 규칙을 build-logic strict-lane convention 한 곳에 둔다.
- PERFORMANCE lane 테스트 JVM에 performance.assertions.enabled=true를
넣는다. 빌드(-P, GRADLE_OPTS)나 lane(systemProperty, jvmArgs, task
설정)이 true 아닌 값을 주면 테스트 전에 실패하고, 지우거나 true로
바꾸라고 알려 준다. true는 받아 준다(파생 서비스 workflow가 넘긴다).
- PERFORMANCE lane은 skip된 테스트가 있으면 실패한다.
- httpclient·Mongo 테스트는 조건 없이 단언하고 잰 값을 한 줄 남긴다.
두 leaf의 속성 선언과 integration-main·release workflow의 GRADLE_OPTS
줄을 지웠다. 사람과 workflow가 같은 명령을 쓴다. verifyStrictLaneStages가
읽는 run: 줄은 그대로다.
버린 대안: 두 leaf 기본값만 true로(정의가 leaf마다 남아 다음 lane이 다시
복사한다), 속성 삭제만(옛 속성을 기본값 false로 읽는 파생 서비스 테스트가
조용히 건너뛴다), 측정 전용 태스크(쓸 곳이 없다: 숫자만 볼 때는 JMH, 실패한
단언과 매 실행 출력이 값을 남긴다).
같은 원인으로 함께 고친 문서: httpclient support-matrix·release-checklist의
없는 lane 이름 spring62CompatibilityTest와 빠진 main push 주기.
위험·한계: 손으로 돌린 performanceCheck가 이제 상한을 실제로 재므로 느린
기계에서는 실패할 수 있다. JVM 인자 공급자(jvmArgumentProviders)가 넣는
-D는 보지 않는다. Docker가 없을 때 skip되는 통합·시스템 lane은 지금
모두 실패한다(전부 skip이면 executed no test, 아니면 skip 안 되는 컨테이너
테스트가 실패) — 거짓 통과가 아니어서 고치지 않았다.
검증(desktop ~/b4-logs, flock 아래, 노트북과 같은 트리 — git diff sha256 일치):
- RED(고치기 전 트리 + 새 테스트): build-logic 새 테스트 4건이
UnexpectedBuildSuccess로 실패 — aPerformanceLaneFailsOnAnExceededBound
WhenTheBuildSetsNoAssertionsProperty, …FailsBeforeTestingWhenTheBuild
TurnsItsAssertionsOff, …FailsWhenItsOwnDeclarationTurnsTheAssertionsOff,
…FailsWhenOneOfItsTestsIsSkipped. jvmArgs 경로(…FailsWhenItsJvmArguments
TurnTheAssertionsOff)도 같은 실패. 실제 lane: 속성 없이
httpClientPerformanceTest rc=0인데 "skipped machine-dependent bound" 출력.
- GREEN: -p build-logic check javadoc rc=0. :performanceCheck rc=0(lane 5개
테스트 26, skip 0; httpclient 힙 증가 5,243,880 B / 상한 16,777,216 B,
Mongo p50·p95·p99 1ms, examined/returned 1.0, pool 대기 0).
-p optional-platforms performanceCheck rc=0(grpc 1). 두 명령에
-Pperformance.assertions.enabled=false → rc=1, 6개 lane 모두 테스트 전
실패. =true → rc=0. verifyStrictLaneStages --dry-run 두 빌드 rc=0,
architectureCheck rc=0, ci·mainCheck·integrationCheck·releaseCheck·
performanceCheck --dry-run --configuration-cache rc=0,
:mainCheck --continue --warning-mode=fail rc=0, -p optional-platforms ci
rc=0, persistence-mongo:check rc=0, verify-httpclient-docs.py rc=0.
- 이 변경 밖 실패: :ci :verifyDependencyLocks --continue와
httpclient:check가 CircuitBreakerStatusAccountingTest JDK 2건으로 rc=1.
기준 커밋 3d73b6f1에서도 10/10 실패(이 트리도 10/10). ci의 다른
task는 모두 통과했다.
Refs: docs/upgrade/2026-11-maturity-review.md B-43, docs/testing/TESTING_STRATEGY.md 6절
BREAKING CHANGE: PERFORMANCE lane은 performance.assertions.enabled가
true가 아니거나 skip된 테스트가 있으면 실패한다. 자기 성능 lane의 그 속성
선언(false)과 skip을 없앤다.
문제: improve.md 4.4절은 확인 리뷰 하나가 보는 수정 diff를 추가 1,500줄로
묶고, 넘으면 "묶음 커밋별로" 나누라고만 했다. 여러 영역 묶음을 한 커밋에
합친 수정(예: 영역 묶음 넷을 합친 +5,143줄 커밋)은 커밋으로 나눌 수 없어,
그 확인 리뷰를 맡은 세션이 어떻게 나눌지 답이 없었다.
고른 방법: 커밋이 따로 있으면 커밋별로, 한 커밋에 섞였으면 영역 pathspec별로
`git diff --shortstat <base>..<head> -- <pathspec>`를 재서 각각 상한 안이 되게
나눈다. 지난 확인 리뷰도 영역 4개를 pathspec으로 나눠 봤다.
위험·한계: pathspec 하나가 그 자체로 1,500줄을 넘으면 더 나눌 기준은 아직
없다. 그때는 그 영역을 맡은 리뷰를 둘로 나누거나 맡긴 쪽에 묻는다.
검증
- python3 scripts/check-work-docs.py: rc=0, improve.md 132/150
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).
고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
(new-feature, improve, research-design, docs-writing, operate, delegate, 모두
같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
+13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
(reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
CLAUDE.md 「Layer workflow」를 가리키던 줄).
위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.
검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
.guidanceNamesTheArchitectureSourceSetTask가 기대하는
"./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
이 커밋을 push한 뒤 desktop에서 돌린다
문제: 옛 개선 매뉴얼은 진입 경로가 717줄이었고 본문에 지난 리뷰 ID가 든
줄이 많아, 이력을 모르는 세션은 근거를 따라가지 못했다. 이것을 사람 눈으로만
지키면 다시 늘어난다. 리뷰 색인도 손으로 옮기다 발견 5건이 빠져 어떤 수정
묶음에도 배정되지 않은 적이 있다(원래 리뷰 124건이 색인에는 119건).
고른 방법: Gradle 밖 Python 스크립트 두 개를 둔다(2026-11-06 소유자 결정 D6:
이 repo는 문서를 파싱하는 Gradle 검사를 두지 않는다).
- check-work-docs.py: 지도(CLAUDE.md)와 docs/work/의 분량 상한(지도 120,
README 80, playbook 150, 진입 경로 350), playbook 9칸 뼈대, 「자주 하는
실수」 10줄, 본문 이력 ID 0(evidence.md와 reference/의 두 색인 문서는 제외),
상대 링크를 본다. --links, --history 모드로 다른 문서에도 쓴다.
- check-review-index.py: 리뷰 폴더의 영역 문서 제목에 있는 발견 ID가 README
색인에 모두 있는지 본다. 범위(A~B)와 이어 쓰기(A·07)를 읽고, NN- 자리표시자를
잡는다.
정규식은 re.ASCII로 쓴다. Python의 \w·\b가 한글을 단어 문자로 봐서
"RR6-01-07과" 같은 표기를 놓쳤다.
버린 대안: document-contract Gradle lane(이 repo 원칙과 충돌), 검사 없이
cold-read 시험에서만 확인(매번 사람이 세야 한다).
위험·한계: check-work-docs.py가 보는 docs/work/는 다음 커밋에 들어온다. 이
커밋만으로는 "missing"으로 실패한다. 이력 ID 패턴은 이 repo가 쓴 형식만 안다
(MMDD/, RR<n>-, 묶음 이름, round<n>, 번호만 쓴 결정, 커밋 sha). 색인 검사는
"이름이 있나"만 보고 고쳤는지는 보지 않는다.
검증
- check-review-index.py docs/reviews/2026-11-01-maturity-review
--index-heading "12. 발견 색인": 124/124, rc=0
- 같은 폴더를 사고 시점 34565130에서 꺼내 돌림: NN-10~NN-14 5건, rc=1
- check-review-index.py docs/reviews/2026-11-03-rereview: 157 중 135, rc=1
(README가 ID 대신 내용·건수로 적은 22건)
- check-work-docs.py를 일부러 망가뜨린 사본 18가지에 돌림: 이력 ID 7형식,
분량 3종, 뼈대, 실수 줄 수, 깨진 링크, 빠진 파일은 rc=1, ID가 허용된 파일과
"결정 3개" 같은 개수 표현은 rc=0
문제: 소유자 규칙은 "세션 안의 하위 에이전트(Agent 도구)를 쓰지 않고, 일을
나눌 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다"이다. 그런데 이
규칙은 문서와 메모리에만 있었고, AGENTS.md 「Superpowers Workflow」는 오히려
subagent-driven-development·dispatching-parallel-agents를 쓰라고 안내했다.
하위 세션 시작이 막혔을 때 Agent로 우회한 일도 있었다.
고른 방법: 이 repo의 .claude/settings.json에 permissions.deny "Agent"를 둔다
(2026-11-06 소유자 결정 D5: 사용자 설정이 아니라 두 템플릿 repo의 프로젝트
설정). Claude Code 권한 문서대로 맨 도구 이름 deny는 그 도구를 세션에서
없애고, 한 설정 단계의 deny는 다른 단계의 allow로 풀리지 않는다.
.gitignore는 .claude/ 전체 무시를 .claude/* + !.claude/settings.json으로
바꿔 이 파일 하나만 추적한다. settings.local.json, worktree, 노트는 계속
무시한다. AGENTS.md의 두 스킬 문장은 "이 저장소에서는 쓰지 않는다"로 바꿨다.
버린 대안: 사용자 설정(~/.claude/settings.json)에 두기는 다른 프로젝트에서
Agent를 쓸 여지를 없앤다. PreToolUse 훅은 deny 규칙 하나로 충분한 일에
스크립트를 더한다.
위험·한계: 추적 파일이라 이 템플릿을 받는 파생 서비스(tech-log-backend 등)에도
넘어간다. 파생 서비스가 Agent를 쓰려면 그 파일을 자기 repo에서 고쳐야 한다.
deny가 실제로 막는지는 Agent를 불러 보는 방식으로 시험하지 않았다(막히지
않으면 하위 에이전트가 떠서 규칙을 어긴다). 대신 공식 권한 문서의 문법과
우선순위를 확인했다.
검증
- jq -e '.permissions.deny | index("Agent")' .claude/settings.json: rc=0
- git check-ignore: .claude/settings.json 추적 가능, settings.local.json·
.claude/worktrees/·.claude/review-followup/ 무시
r10(2c692554)은 소유자가 노트북 Gradle을 금지한 뒤에 바뀐 부분(01의 A5
fixture 재작성, 03의 동시 인덱스 검사기)과 합친 트리 전체가 검증되지
않은 상태였다. 재리뷰 README 17.1절이 결과를 17.2절에 적기로 했다.
desktop에서 전체 게이트를 차례로 돌렸고 모두 첫 실행에서 rc=0이라
코드는 고치지 않았다. 17.2절에 게이트별 결과·시간·실행 직전 부하와,
로컬에서 확인하지 못했던 RED/GREEN(01 A5 최종 fixture RED, 02 경로 1
RED, 03 검사기 GREEN 등)을 적었다. 실패가 없어 17.3절은 두지 않는다.
한계: 각 묶음이 로컬에서 이미 확인한 RED는 desktop에서 다시 돌리지
않았다. r10-03 보고서가 적은 persistence-jpa documentContractTest는
없는 태스크라 돌릴 대상이 없었다.
검증: desktop에서 :ci :verifyDependencyLocks, sample check,
verifyStrictLaneStages(두 빌드), :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck,
:performanceCheck, :releaseCheck, compose 계약 스크립트,
-p build-logic check javadoc 모두 rc=0. 이 커밋 뒤
:app-bootstrap:documentContractTest를 다시 돌린다.
Refs: docs/reviews/2026-11-03-rereview/README.md 17절
문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).
방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.
위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).
검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).
Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
문제: 확인 리뷰들이 찾은 Minor와 "남음" 항목을 고치지 않고 기록만 했다.
그중 동작에 닿는 것이 여럿이었다. verifyStrictLaneStages가 `./gradlew ci
|| true`, `| tee`, `if ./gradlew …` 같은 실패를 막지 못하는 명령을 실행으로
세는 거짓 통과, Redis 멱등 저장소가 lease가 지난 CLAIMED의 시작을 받아
주던 것(PostgreSQL은 거절), gRPC가 INTERNAL_ERROR 실패를 아무 데도 남기지
않고 STOMP가 SQL 원인까지 로그에 쓰던 것, 잠금 대기 검사기가 Flyway가
트랜잭션 밖에서 돌리는 VACUUM FULL을 몰라 통과시키던 것, 템플릿 패키지
목록과 버전 판정 정규식이 두 곳에 갈라져 있던 것.
방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README
16절).
- workflow run 스크립트를 bash 문법으로 읽고, 실패를 막지 못하는 명령과
셸이 실행하지 않는 줄의 cd는 이유를 대며 세지 않는다.
- 두 멱등 저장소가 lease가 지난 시작을 LEASE_EXPIRED로 거절하고,
executor는 아무것도 실행하지 않았으므로 503으로 답한다.
- web·GraphQL·gRPC·STOMP가 shared-contract ServerFailureLog로 같은 실패
로그 줄을 쓴다(persistence 실패는 분류만).
- @SystemCaller 규칙이 인터페이스로 주입한 경로도 보고, 조립 설정은 사용자
전송으로 세지 않는다.
- 갈라진 복사본은 하나로: 템플릿 패키지 표가 정본이고 클래스를 대조하며,
버전 판정 코드는 grpc 빌드가 Sync로 가져와 컴파일한다.
- httpclient 장애 주입 lane이 main 단계에서 두 번 돌던 것을 한 번으로.
- 게이트에서 드러난 httpclient drain 스레드 경쟁: close()가 스레드를 join하고,
런타임이 닫기를 거부해도 drain 스레드를 먼저 멈춘다.
위험·한계: 목록에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수
없다(문서화). 서브셸·eval·source 안의 cd 뒤 명령과 `|| exit 1`은 세지 않는다
(거짓 실패 쪽). Gradle 옵션 판독은 Gradle 9.0 동작을 TestKit으로 고정했다.
검증: 첫 ci가 httpclient ClientRuntimeRegistryTest 1건으로 실패(기존 코드의
drain 스레드 경쟁, README 16.1절) — 고친 뒤 ci 재실행 통과. 두 빌드
verifyStrictLaneStages, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck, compose
18 lane 통과. httpclient check·testQualityCheck·failure injection·performance
lane을 수정 뒤 다시 돌려 통과.
Refs: docs/reviews/2026-11-03-rereview/README.md 16절
BREAKING CHANGE: 멱등 저장소 시작·renew 결과에 LEASE_EXPIRED가 생겼고,
lease가 지난 시작은 503 IDEMPOTENCY_UNAVAILABLE이다. verifyStrictLaneStages가
실패를 막지 못하는 workflow 명령을 세지 않는다.
문제: 70fb80bf 뒤 IDEMPOTENCY_RECOVERY_REQUIRED에 대한 클라이언트 안내가
문서마다 달랐다. http-contract 표는 새 키 금지, 매뉴얼 05 표는 옛 문구(재전송도
위험), runbook은 효과가 없으면 새 키라고 했다. 결정 ① 뒤에는 같은 키 재전송이
작업을 다시 돌리지 않으므로 안전하다.
방법: 세 문서를 "자동 재시도 안 함, 같은 키 재전송은 안전(서버가 판정하고
다시 돌리지 않음), 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키"로
맞췄다. 70fb80bf 확인 리뷰(Important 0, Minor 9) 결과를 재리뷰 README 15.2절과
round5/review.md에 남기고, 업그레이드 안내의 결정 행에 커밋 해시를 적었다.
위험·한계: 문서만 바뀐다. 나머지 Minor 8건은 기록만 했다.
검증: :app-bootstrap:documentContractTest, :app-bootstrap:repositoryContractTest
통과.
Refs: docs/reviews/2026-11-03-rereview/README.md 15.2절
문제: 기본값으로 정했던 세 가지를 소유자가 다시 정했다.
- lease(기본 30s)가 지난 실행을 다음 같은 키 요청이 포기로 표시해서,
첫 시도가 늦게 끝나면 결과가 버려지고 그 요청도 500을 받았다.
executor가 lease를 갱신하지 않아 30s를 넘는 정상 요청도 해당됐다.
- failure-retention이 replay-ttl보다 짧아도 기동이 막히지 않아, 효과
불명 실패의 중복 방지 기간이 주석 경고만 남긴 채 짧아졌다.
- verifyStrictLaneStages가 `cd src && ./gradlew`를 저장소 루트 빌드로
읽어 파생 서비스 workflow에서 거짓 실패가 났다.
방법:
- lease가 지난 실행 기록을 claim이 만나면 기록을 바꾸지 않고 회복
필요로만 답한다. 주인의 늦은 complete·markFailed는 기록되고 다음
claim은 그 결과를 재생한다. 다시 실행하지 않는다는 결정은 그대로다.
PostgreSQL·Redis·fake와 공유 계약을 함께 바꿨다. 이미 끝난 lease의
renew는 두 저장소 모두 거절한다(Redis만 받던 것을 맞춤).
- IdempotencySettings가 failure-retention < replay-ttl이면 기동을
실패시킨다. 기본값(둘 다 24h)은 그대로 뜬다.
- workflow 명령의 빌드를 working-directory → 같은 셸의 최상위
`cd <상대 경로>` → -p 순서로 정한다. 읽을 수 없는 이동($VAR, 절대
경로, 서브셸·조건문 안) 뒤의 명령은 이유를 대며 세지 않는다.
위험·한계: lease가 지난 실행의 EXECUTING 기록을 운영자가 지우면 늦은
완료가 사라지고 같은 키가 다시 실행된다(runbook에 적음). 회복 필요를 받은
뒤 같은 키로 다시 보내면 성공 응답이 올 수 있다(프론트 인계 문서 갱신).
CLAIMED에서 실행 시작으로 넘어갈 때 PostgreSQL은 lease를 보고 Redis는
보지 않는다. `./gradlew ci || true` 같은 명령을 여전히 실행으로 센다
(이전부터, 거짓 통과).
검증: ci, 두 빌드 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 결정 ①은 실
PostgreSQL·실 Redis 계약 lane에서 RED(늦은 complete 거절)를 먼저 확인했다.
Refs: docs/reviews/2026-11-03-rereview/README.md 15절
BREAKING CHANGE: lease가 지난 멱등 실행의 늦은 완료가 기록된다(전에는
포기). failure-retention < replay-ttl 설정은 기동 실패.
문제: qualityCheck는 spotbugsMain만 돈다. main 밖 source set(test,
testFixtures, integrationTest, systemTest 등)의 SpotBugs 태스크 111개는
어느 게이트에도 없었고, 돌려 보니 53개가 실패했다(발견 300건). 그중
동시성 테스트 7건은 CountDownLatch.await의 시간 초과를 무시하고 다음
단계로 가서 순서를 확인하지 않은 채 통과했다. 2개는 분석 classpath에
없는 클래스 때문에 분석이 불완전했다.
방법:
- leaf마다 testQualityCheck를 두고 main 빌드는 mainCheck, optional 빌드는
ci에 넣었다. PR 게이트에 넣지 않은 것은 테스트 코드가 배포되지 않고
전체 실행이 ci만큼 걸려서다.
- 테스트용 제외 목록 config/spotbugs/exclude-test.xml. 패턴 전체 제외는
이유가 모든 테스트 클래스에 성립하는 것만(보안 범주, 내부 상태 노출,
생성자 예외, 반환값 null 역참조, 아키텍처 위반 fixture). 나머지 30건은
클래스·메서드로 좁히고 이유를 달았다.
- 24건은 코드로 고쳤다: await 결과 단언, 공유 변수 원자성, 닫지 않은
Statement, SQLException을 삼키던 upsert 테스트, 만료 없는 키에서 NPE가
나던 Redis fake. 쓰는 곳이 없던 web-fileserver 테스트 helper 2개는
지웠다.
- 모든 SpotBugs 태스크가 그 source set의 runtime classpath로 분석하고
분석이 불완전하면 실패한다. SpotBugs 플러그인이 나중에 생긴 source
set의 태스크를 등록하면서 classpath를 덮어써서 설정을 평가 뒤에
등록한다. 그 자리에 의존성을 더하는 우회는 버렸다.
위험·한계: 파생 서비스는 자기 테스트 코드의 SpotBugs 발견이 mainCheck를
막는다(업그레이드 안내 B-40). mainCheck가 그만큼 길어진다(main 빌드 테스트
태스크 100개).
검증: ci, 두 빌드 verifyStrictLaneStages --dry-run, mainCheck(testQualityCheck
100개 포함, 3분 10초 → 8분 33초), :integrationCheck, -p optional-platforms
ci(testQualityCheck 포함) integrationCheck performanceCheck,
:performanceCheck, :releaseCheck(-PgitRevision), verify-compose-profile-
contracts(18 lane) 첫 실행 통과. 고친 컨테이너 테스트는 클래스별로 따로
실행해 통과.
Refs: docs/reviews/2026-11-03-rereview/README.md 14절
BREAKING CHANGE: mainCheck(optional 빌드는 ci)가 테스트 source set의
SpotBugs·FindSecBugs 발견에 실패한다. 고치거나 config/spotbugs/
exclude-test.xml에 이유를 단 좁은 Match를 더한다.
문제: 마지막 정리 커밋(f40c03c6)이 새 결함을 만들었는지 확인해야 리뷰·
수정 반복을 끝낼 수 있다.
방법: 리뷰어 1명이 그 커밋 전체를 영역별로 봤다. Important 0, 회귀 0,
Minor 7. 재리뷰 README 11.1절 결정대로 반복을 끝내고 Minor 7건과
소유자 일(Gitea Actions·runner, PR·병합, 기본값 결정 확인)을 13절에
남겼다.
위험·한계: Minor 7건은 고치지 않았다. 그중 새 ArchUnit 규칙이 인터페이스로
주입한 시스템 호출자를 못 보는 것과 문서의 반대 서술은 같은 leaf 안에서만
생긴다.
검증: 리뷰 문서만 바뀐다. 리뷰어 탐침은 round4/review.md 범위 절.
Refs: docs/reviews/2026-11-03-rereview/README.md 13절
문제: 3차 수정의 확인 리뷰가 새 Important 없이 Minor 19건을 남겼다.
동작에 닿는 것이 셋이다. JDK read-idle watchdog이 공용 ForkJoinPool에서
돌아 그 풀이 바쁘면 300ms timeout이 6초 가까이 늦었다. 붙여 쓴
-x<task>를 verifyStrictLaneStages가 읽지 않아 lane을 뺀 workflow가
통과했다. 사용자 전송이 중간 클래스를 거쳐 @SystemCaller bean을 부르면
ArchUnit 규칙을 지났다. 잠금 대기 검사기는 FK·trigger·REINDEX와
lock_timeout = 0을 못 봤고, 쿼터 보정 SQL은 코드와 다른 모양의 행을
넣었다.
방법: 영역별 4묶음이 맡은 Minor만 test-driven-development 절차로
고쳤다(재리뷰 README 12절).
- watchdog은 전용 데몬 스레드 하나에서 돌고 스트림을 닫으면 작업을
취소한다. read당 비용은 그대로다(21–24ns).
- 사용자 전송 → @SystemCaller는 직접·간접 의존 모두 거부한다. 리뷰가
권한 직접 의존 검사는 중간 클래스 하나로 다시 열려서 버렸다.
- 검사기를 보강하면서 새로 걸린 이미 배포된 마이그레이션 5개는 내용을
바꾸지 않고 동결 목록에 더했다(main과 blob이 같다).
- 비밀 목록 bean은 규칙보다 먼저 만들어 실제 클래스로 검사한다.
위험·한계: 회복 필요 예외 메시지 끝에 scope digest가 붙고 기동 실패
문구가 바뀌어, 문구 전체에 맞추던 로그 매처는 고쳐야 한다. 코드가 든
Redis 계정 참조의 fixture- 검사는 문서로만 막았다(코드로 막으려면 새
의존 edge가 필요하다). failure-retention ≥ replay-ttl 기동 검사는 넣지
않았다. -mx 같은 짧은 플래그 묶음과 graphql 전송 fixture는 남았다.
spotbugsTestFixtures(게이트 밖)의 정규식 경고가 15건으로 늘었다.
검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. watchdog은
공용 풀을 채운 상태에서 300ms 설정이 300ms에 끝나는 것을 쟀다.
Refs: docs/reviews/2026-11-03-rereview/README.md 11·12절, round3/
문제: 3차 수정 커밋(1885bf8d)이 또 새 결함을 만들었는지 알아야 리뷰
반복을 멈출 수 있다.
방법: 리뷰어 4명이 그 커밋만 영역별로 봤다. 새 Important 0, 회귀 0,
Minor 19건. 재리뷰 README 9.1절의 멈춤 기준을 채웠다. Minor는 마지막
정리 라운드로 고치고, 그 뒤에는 Important만 고친다(11.1절).
위험·한계: Minor 중 JDK read-idle timeout 지연(공용 풀 포화 시)과
붙여 쓴 -x 거짓 통과는 동작에 닿는다. 아직 고치지 않았다.
검증: 리뷰 문서만 바뀐다. 리뷰어가 실행한 탐침은 각 문서 범위 절.
Refs: docs/reviews/2026-11-03-rereview/README.md 11절