round9 리뷰의 runbook 신호 발견 넷(RR9-02-04 Medium, RR9-02-24·RR9-04-34·RR9-04-37 Low)을 고친다. runbook이 코드가 내지 않는 신호로 장애를 찾게 했다.
actuator·cross-tenant runbook: 증상이 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH였고, 없는 경보·지표·로그 칸을 적었다(RR9-02-04, RR9-04-37).
auth runbook: 로그에서 token payload·Authorization 원문을 보라고 했고(남지도 않고 남겨서도 안 된다), 없는 JWKS 캐시 손잡이·경보·지표를 적었고, issuer 비교 대상을 decoder가 읽지 않는 Spring 키로 적었다(RR9-02-24).
rate-limit·dependency runbook: 없는 gateway 지표·헤더·CACHE_UNAVAILABLE·dependency_name 칸을 적었다(RR9-04-37).
docs/web/runbook.md: 멱등 TTL을 「연산마다」, 시험 도구 GracefulShutdownProbe를 운영 장치로, 없는 tag routeTemplate을 적었고, 기동이 거부하는 CORS 설정을 「기동은 된다」고 적었다(RR9-04-34).
고른 방법과 버린 대안
runbook을 지금 코드가 내는 신호로 다시 썼다: 응답 코드·헤더, 보안 로그 줄 security failure: code=… path=…, 요청 로그 줄, ServerFailureLog의 고정 문구(dependency failure classified as … dependency=<이름>, persistence failure classified as …), 실제 설정 키 APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이 없다는 것과, 내는 코드가 없는 코드·지표(JOB_DEAD_LETTER·JOB_TIMEOUT, job.*)는 서비스가 낼 때만 있다는 것을 적었다.
진단 순서를 코드에 맞췄다: actuator 노출은 관리 포트 9001로 가른다(메인 포트도 같은 401·404로 답한다). INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery부터 본다(후보 주소 모두 4xx·issuer 불일치·jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503). 종료 예산은 웹 drain 30s + async 19s + preStop 5s의 합이다. 키 교체에 재시작은 필요 없다(모르는 kid면 JWKS를 다시 받는다. jwks_uri가 옮겨졌을 때만 재시작).
같은 원인의 다른 자리도 고쳤다: 경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로 적은 칸, 지적 밖 auth·dependency·db·outbox·redis runbook, error-codes.yaml 주석, 같은 틀린 신호를 적은 shared-contract README·web README·DependencyFailureException Javadoc(없는 OutboundHttpErrorMapper, 로그의 JVM_OOM, 403 ACTUATOR_FORBIDDEN). 본문의 리뷰 ID는 지웠다.
버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator 노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로 답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정 자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적었다.
정한 기본값
runbook은 모두 status: 초안으로 둔다(RunbookCoverageContractTest의 초안 목록 그대로). 신호를 바로잡은 것이지 운영 본문을 완성한 것이 아니다.
고친 runbook의 last_updated는 2026-11-13이다.
runbook 본문의 설계 번호(D2·D8 등)와 bbe944bd는 그대로 둔다(runbook은 ID 0 규칙 범위 밖, docs/work/README.md 8절). 리뷰 ID만 지웠다.
위험과 영향
문서와 Javadoc 한 곳만 바뀐다. 응답·env·기동은 그대로다.
같은 묶음의 다른 두 PR과 함께 병합한다. dependency-unavailable.md가 적은 hikaricp.connections.pending·timeout 행과 job runbook이 기대는 job.* 행의 emitted_when은 관측 registry PR이 더하고, auth-jwks-unavailable.md의 「캐시가 지난 뒤 IdP에 닿지 않으면 503」은 인증 PR의 JWKS 재조회 분류 수정이 만든다.
노트북: python3 scripts/check-docs.py·check-work-docs.py OK.
새 눈 리뷰 3회(runbook 1·2차, 셋을 묶은 좁은 3차). 마지막 3차에서 이 PR은 발견 0.
리뷰어가 볼 곳
docs/runbooks/management-actuator-forbidden.md, auth-public-path-misconfiguration.md, authz-cross-tenant-violation.md, job-dead-letter.md·job-timeout.md, docs/web/runbook.md 종료 예산 절.
2026-11-12 전체 리뷰 docs/reviews/2026-11-12-round9-review/(색인 「묶음」 B7).
범위 밖으로 남긴 것: INTERNAL_AUTH_MISCONFIGURATION의 runbook 파일 이름 auth-public-path-misconfiguration(제목만 바꿈). 이름을 바꾸면 registry runbook_link와 RunbookCoverageContractTest가 함께 바뀌는 계약 변경이다.
## 무엇을, 왜
round9 리뷰의 runbook 신호 발견 넷(RR9-02-04 Medium, RR9-02-24·RR9-04-34·RR9-04-37 Low)을 고친다. runbook이 코드가 내지 않는 신호로 장애를 찾게 했다.
- actuator·cross-tenant runbook: 증상이 아무 코드도 내지 않는 `ACTUATOR_FORBIDDEN`·`AUTHZ_TENANT_MISMATCH`였고, 없는 경보·지표·로그 칸을 적었다(RR9-02-04, RR9-04-37).
- auth runbook: 로그에서 token payload·`Authorization` 원문을 보라고 했고(남지도 않고 남겨서도 안 된다), 없는 JWKS 캐시 손잡이·경보·지표를 적었고, issuer 비교 대상을 decoder가 읽지 않는 Spring 키로 적었다(RR9-02-24).
- rate-limit·dependency runbook: 없는 gateway 지표·헤더·`CACHE_UNAVAILABLE`·`dependency_name` 칸을 적었다(RR9-04-37).
- `docs/web/runbook.md`: 멱등 TTL을 「연산마다」, 시험 도구 `GracefulShutdownProbe`를 운영 장치로, 없는 tag `routeTemplate`을 적었고, 기동이 거부하는 CORS 설정을 「기동은 된다」고 적었다(RR9-04-34).
## 고른 방법과 버린 대안
- runbook을 지금 코드가 내는 신호로 다시 썼다: 응답 코드·헤더, 보안 로그 줄 `security failure: code=… path=…`, 요청 로그 줄, `ServerFailureLog`의 고정 문구(`dependency failure classified as … dependency=<이름>`, `persistence failure classified as …`), 실제 설정 키 `APP_SECURITY_JWT_ISSUER`, registry에 있는 지표. 이 템플릿에 경보 규칙이 없다는 것과, 내는 코드가 없는 코드·지표(`JOB_DEAD_LETTER`·`JOB_TIMEOUT`, `job.*`)는 서비스가 낼 때만 있다는 것을 적었다.
- 진단 순서를 코드에 맞췄다: actuator 노출은 관리 포트 9001로 가른다(메인 포트도 같은 401·404로 답한다). `INTERNAL_AUTH_MISCONFIGURATION`은 issuer discovery부터 본다(후보 주소 모두 4xx·issuer 불일치·`jwks_uri` 없음은 500, 연결 실패·5xx·JSON 아님은 503). 종료 예산은 웹 drain 30s + async 19s + preStop 5s의 합이다. 키 교체에 재시작은 필요 없다(모르는 kid면 JWKS를 다시 받는다. `jwks_uri`가 옮겨졌을 때만 재시작).
- 같은 원인의 다른 자리도 고쳤다: 경보 이름을 지어 적은 job·outbox·internal-error-spike, `traceId`로 적은 칸, 지적 밖 auth·dependency·db·outbox·redis runbook, `error-codes.yaml` 주석, 같은 틀린 신호를 적은 shared-contract README·web README·`DependencyFailureException` Javadoc(없는 `OutboundHttpErrorMapper`, 로그의 `JVM_OOM`, 403 `ACTUATOR_FORBIDDEN`). 본문의 리뷰 ID는 지웠다.
- 버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator 노출 밖 경로는 메인 chain이 401 `AUTH_TOKEN_MISSING`(익명)·404(인증됨)로 답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정 자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적었다.
## 정한 기본값
- runbook은 모두 `status: 초안`으로 둔다(`RunbookCoverageContractTest`의 초안 목록 그대로). 신호를 바로잡은 것이지 운영 본문을 완성한 것이 아니다.
- 고친 runbook의 `last_updated`는 2026-11-13이다.
- runbook 본문의 설계 번호(D2·D8 등)와 `bbe944bd`는 그대로 둔다(runbook은 ID 0 규칙 범위 밖, `docs/work/README.md` 8절). 리뷰 ID만 지웠다.
## 위험과 영향
- 문서와 Javadoc 한 곳만 바뀐다. 응답·env·기동은 그대로다.
- 같은 묶음의 다른 두 PR과 함께 병합한다. `dependency-unavailable.md`가 적은 `hikaricp.connections.pending`·`timeout` 행과 job runbook이 기대는 `job.*` 행의 `emitted_when`은 관측 registry PR이 더하고, `auth-jwks-unavailable.md`의 「캐시가 지난 뒤 IdP에 닿지 않으면 503」은 인증 PR의 JWKS 재조회 분류 수정이 만든다.
## 검증
- desktop(트리 `34dcf291` = 이 커밋): `./gradlew :app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest` rc=0, `scripts/verify.sh pr` rc=0(시험 6873건, 실패 0, 건너뜀 35).
- 노트북: `python3 scripts/check-docs.py`·`check-work-docs.py` OK.
- 새 눈 리뷰 3회(runbook 1·2차, 셋을 묶은 좁은 3차). 마지막 3차에서 이 PR은 발견 0.
## 리뷰어가 볼 곳
- `docs/runbooks/management-actuator-forbidden.md`, `auth-public-path-misconfiguration.md`, `authz-cross-tenant-violation.md`, `job-dead-letter.md`·`job-timeout.md`, `docs/web/runbook.md` 종료 예산 절.
## 발견 판정
| 발견 | 판정 | 커밋 |
|---|---|---|
| RR9-02-04 | 고침 | 0fded57c |
| RR9-02-24 | 고침 | 0fded57c |
| RR9-04-34 | 고침 | 0fded57c |
| RR9-04-37 | 고침 | 0fded57c |
## 관련
- 2026-11-12 전체 리뷰 `docs/reviews/2026-11-12-round9-review/`(색인 「묶음」 B7).
- 범위 밖으로 남긴 것: `INTERNAL_AUTH_MISCONFIGURATION`의 runbook 파일 이름 `auth-public-path-misconfiguration`(제목만 바꿈). 이름을 바꾸면 registry `runbook_link`와 `RunbookCoverageContractTest`가 함께 바뀌는 계약 변경이다.
runbook이 코드가 내지 않는 신호로 장애를 찾게 한다. actuator·cross-tenant
runbook은 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH를
증상으로 적고, 없는 경보·지표·로그 칸을 적는다. auth runbook은 로그에서
token payload·Authorization 원문을 보라고 하고(남지도 않고 남겨서도 안
된다), 없는 JWKS 캐시 손잡이와 decoder가 읽지 않는 Spring issuer 키를
적는다. rate-limit·dependency runbook은 없는 gateway 지표·헤더·
CACHE_UNAVAILABLE·dependency_name 칸을, web runbook은 연산마다의 TTL,
시험 도구 GracefulShutdownProbe, 없는 tag routeTemplate, 기동이 거부하는
CORS 설정을 「기동은 된다」고 적는다. job runbook은 내는 코드가 없는
JOB_DEAD_LETTER·JOB_TIMEOUT과 job.* 지표에 경보를 걸게 한다.
각 runbook을 지금 코드가 내는 신호로 다시 쓴다: 응답 코드·헤더, 보안
로그 줄 `security failure: code=… path=…`, 요청 로그 줄, ServerFailureLog
의 고정 문구(`dependency failure classified as … dependency=<이름>`,
`persistence failure classified as …`), 실제 설정 키
APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이
없다는 것, 내는 코드가 없는 코드·지표는 서비스가 낼 때만 있다는 것을
적는다. 진단 순서도 고친다: actuator 노출은 관리 포트 9001로 가르고,
INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery(4xx·issuer 불일치·
jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503)부터, 종료 예산은
웹 drain 30s + async 19s + preStop의 합으로 본다. 같은 원인의 다른
자리(경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로
적은 칸, 지적 밖 auth·dependency·db·outbox runbook, error-codes.yaml 주석,
같은 틀린 신호를 적은 shared-contract README·web README·
DependencyFailureException Javadoc)도 고치고, 본문의 리뷰 ID는 지운다.
버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator
노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로
답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정
자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적는다.
위험: 문서만 바뀐다. runbook은 모두 status 초안으로 둔다.
dependency-unavailable이 적은 hikaricp.connections.pending·timeout 행과
job.* 행의 emitted_when은 관측 registry 변경(같은 묶음의 다른 PR)이
더하고, auth-jwks-unavailable의 「캐시가 지난 뒤 503」은 인증 PR의 JWKS
재조회 분류 수정이 만든다. 세 PR을 함께 병합한다.
검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop
:app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest,
scripts/verify.sh pr rc=0.
Refs: RR9-02-04, RR9-02-24, RR9-04-34, RR9-04-37
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
round9 리뷰의 runbook 신호 발견 넷(RR9-02-04 Medium, RR9-02-24·RR9-04-34·RR9-04-37 Low)을 고친다. runbook이 코드가 내지 않는 신호로 장애를 찾게 했다.
ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH였고, 없는 경보·지표·로그 칸을 적었다(RR9-02-04, RR9-04-37).Authorization원문을 보라고 했고(남지도 않고 남겨서도 안 된다), 없는 JWKS 캐시 손잡이·경보·지표를 적었고, issuer 비교 대상을 decoder가 읽지 않는 Spring 키로 적었다(RR9-02-24).CACHE_UNAVAILABLE·dependency_name칸을 적었다(RR9-04-37).docs/web/runbook.md: 멱등 TTL을 「연산마다」, 시험 도구GracefulShutdownProbe를 운영 장치로, 없는 tagrouteTemplate을 적었고, 기동이 거부하는 CORS 설정을 「기동은 된다」고 적었다(RR9-04-34).고른 방법과 버린 대안
security failure: code=… path=…, 요청 로그 줄,ServerFailureLog의 고정 문구(dependency failure classified as … dependency=<이름>,persistence failure classified as …), 실제 설정 키APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이 없다는 것과, 내는 코드가 없는 코드·지표(JOB_DEAD_LETTER·JOB_TIMEOUT,job.*)는 서비스가 낼 때만 있다는 것을 적었다.INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery부터 본다(후보 주소 모두 4xx·issuer 불일치·jwks_uri없음은 500, 연결 실패·5xx·JSON 아님은 503). 종료 예산은 웹 drain 30s + async 19s + preStop 5s의 합이다. 키 교체에 재시작은 필요 없다(모르는 kid면 JWKS를 다시 받는다.jwks_uri가 옮겨졌을 때만 재시작).traceId로 적은 칸, 지적 밖 auth·dependency·db·outbox·redis runbook,error-codes.yaml주석, 같은 틀린 신호를 적은 shared-contract README·web README·DependencyFailureExceptionJavadoc(없는OutboundHttpErrorMapper, 로그의JVM_OOM, 403ACTUATOR_FORBIDDEN). 본문의 리뷰 ID는 지웠다.AUTH_TOKEN_MISSING(익명)·404(인증됨)로 답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정 자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적었다.정한 기본값
status: 초안으로 둔다(RunbookCoverageContractTest의 초안 목록 그대로). 신호를 바로잡은 것이지 운영 본문을 완성한 것이 아니다.last_updated는 2026-11-13이다.bbe944bd는 그대로 둔다(runbook은 ID 0 규칙 범위 밖,docs/work/README.md8절). 리뷰 ID만 지웠다.위험과 영향
dependency-unavailable.md가 적은hikaricp.connections.pending·timeout행과 job runbook이 기대는job.*행의emitted_when은 관측 registry PR이 더하고,auth-jwks-unavailable.md의 「캐시가 지난 뒤 IdP에 닿지 않으면 503」은 인증 PR의 JWKS 재조회 분류 수정이 만든다.검증
34dcf291= 이 커밋):./gradlew :app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTestrc=0,scripts/verify.sh prrc=0(시험 6873건, 실패 0, 건너뜀 35).python3 scripts/check-docs.py·check-work-docs.pyOK.리뷰어가 볼 곳
docs/runbooks/management-actuator-forbidden.md,auth-public-path-misconfiguration.md,authz-cross-tenant-violation.md,job-dead-letter.md·job-timeout.md,docs/web/runbook.md종료 예산 절.발견 판정
0fded57c0fded57c0fded57c0fded57c관련
docs/reviews/2026-11-12-round9-review/(색인 「묶음」 B7).INTERNAL_AUTH_MISCONFIGURATION의 runbook 파일 이름auth-public-path-misconfiguration(제목만 바꿈). 이름을 바꾸면 registryrunbook_link와RunbookCoverageContractTest가 함께 바뀌는 계약 변경이다.