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건)
This commit is contained in:
@@ -80,7 +80,7 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
|
||||
`performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면
|
||||
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
|
||||
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
|
||||
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다.
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
|
||||
@@ -199,7 +199,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
|
||||
쓴다(소유자 결정 5). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
|
||||
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
|
||||
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
|
||||
@@ -264,7 +264,7 @@ capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
|
||||
자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
|
||||
constructor에서 한다.
|
||||
예외(리뷰 05-18): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중
|
||||
하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
|
||||
|
||||
@@ -50,7 +50,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이
|
||||
|
||||
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
|
||||
- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다.
|
||||
- `docs/work/`나 이 파일을 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다.
|
||||
- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
|
||||
|
||||
## 5. 코드만 보고는 헷갈리는 곳
|
||||
|
||||
|
||||
+2
-2
@@ -72,5 +72,5 @@
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다.
|
||||
- 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 `AGENTS.md`와 `src/**/CLAUDE.md`도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다.
|
||||
- 이 폴더, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다.
|
||||
8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
|
||||
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다.
|
||||
10. `docs/work/`나 루트 `CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크를 본다.
|
||||
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
|
||||
11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다.
|
||||
12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`.
|
||||
13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
|
||||
@@ -50,7 +50,7 @@
|
||||
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
|
||||
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
|
||||
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
|
||||
- `docs/work/`·루트 `CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
|
||||
- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
|
||||
- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
|
||||
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
|
||||
|
||||
|
||||
@@ -4,6 +4,13 @@
|
||||
|
||||
표기: `1101/05-01`은 `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01이다. `1103/RR6-01-05`는 `docs/reviews/2026-11-03-rereview/`의 발견이다. 접두어와 문서: `RR-`는 1차 재리뷰(폴더 바로 아래 `01`~`07` 영역 문서)와 round2의 `01`~`03` 영역 문서(1차 번호를 이어 썼다), `RR2-`는 round2의 `04` 영역 문서, `RR3-`~`RR7-`는 round3~round7이다. `1101` README, `1103` README는 각 폴더의 `README.md`다. 「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번이다.
|
||||
|
||||
더 오래된 표기:
|
||||
|
||||
- 「1라운드」·「2라운드」·「3라운드」: `1101` README 13·14·15.1절의 수정 라운드(2026-11-01~03). `r2-05a`, `r3-I`처럼 `r<라운드>-<묶음>`은 그 라운드의 수정 묶음 이름이다. `r9-a`, `r10-02`는 `1103` README 16·17절의 묶음이다.
|
||||
- `P<N>`·`W<n>-P<N>`: 2026-09-25 리뷰 후속 작업(`docs/reviews/2026-09-25-review-followup-status.md`)의 묶음 이름(Wave n의 묶음 N). 같은 문서는 2026-09-24 리뷰들의 발견을 `S<n>-#<m>`, `S<n>-lead-<m>`, `X<n>-#<m>`, `X<n>-P<k>-<m>`, `G-3a`처럼 부른다. 그 행을 찾으면 내용과 처리 묶음이 있다.
|
||||
- `MSG-`·`BOOT-`·`JPA-`·`MNG-`·`GQL-`·`NTF-` + 세 자리: 2026-11 전의 모듈 리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md`, `2026-09-07-app-bootstrap-module-code-review.md` 등)의 발견이다.
|
||||
- `D<N>`: 문맥에 따라 둘이다. 이 매뉴얼의 설계 결정(design-docs `delegation-loop/02-design.md` 13절, D1~D14)이거나, leaf `CLAUDE.md`가 이름을 댄 설계 기록(`feature-*-contract` 등)의 결정 번호다. 그 설계 기록들은 이 repo에 없다(10절).
|
||||
|
||||
## 1. 이 매뉴얼이 나온 곳
|
||||
|
||||
- 조사와 설계: design-docs `delegation-loop/01-research.md`(1~5단계), `delegation-loop/02-design.md`(6단계, 4·5·6·7·10절). 2026-11-06 소유자가 결정 D1~D14를 모두 권하는 안대로 승인했다.
|
||||
@@ -247,3 +254,66 @@
|
||||
|
||||
- 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 이를 근거로 확인 리뷰를 독립 리뷰어 둘로 할지 소유자에게 물었고, 2026-11-07 소유자가 세 경우에만 둘로 하는 안을 골랐다(소유자 원문 "(c)로 받기"). 넣은 곳: `improve.md` 4.1절 「독립 리뷰어 둘」·4.5절 1, `delegate.md` 4.1·4.3절, `reference/review-criteria.md` 10절 「ID」, `reference/decisions.md` 2.1, design-docs `conventions/delegation-loop.md` 3절 5·9절 M11, `delegation-loop/metrics.md`.
|
||||
- 「자주 하는 실수」에 넣은 줄: `improve.md`(strict lane 탐침), `operate.md`(`--rerun` 범위를 기존 줄에 더함, push 뒤 검증), `docs-writing.md`(`--history` 0을 믿음), `delegate.md`(두 리뷰의 ID).
|
||||
|
||||
## 10. 진입 문서에서 걷어낸 이력 ID (2026-11-07)
|
||||
|
||||
2026-11-07 소유자가 이력 ID 0 규칙을 진입 문서로 넓혔다: `AGENTS.md`와 `src/**/CLAUDE.md`다(`1103` README 19.4절 ③의 (b)). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. 새 세션이 처음 읽는 규칙 문서에서만 ID가 이해를 막고, 나머지는 같은 repo의 리뷰 문서로 따라갈 수 있어서다. `scripts/check-work-docs.py` 기본 모드가 이제 이 문서들을 본다.
|
||||
|
||||
걷어낸 줄은 87줄이다. 넓힌 범위에서 옛 패턴이 74줄을 잡았고, 그중 2줄은 날짜로 쓴 소유자 결정을 잘못 잡은 것이었다. 새 패턴과 줄바꿈 검사가 15줄을 더 잡았다. 줄 번호는 기준 커밋 `83948d58`의 줄이다. `feature-*-contract` 같은 설계 기록은 이 repo에 없다(`git ls-files`로 0건). 그래서 그 번호의 근거 칸은 가리키는 규칙과 코드 위치를 적는다.
|
||||
|
||||
| 원래 위치 | 원래 괄호 | 지금 본문 | 근거 |
|
||||
| --- | --- | --- | --- |
|
||||
| `AGENTS.md:83`, `:202` | "소유자 결정 4", "소유자 결정 5" | "2026-09-25 소유자 결정" | 결정 4(`verifyEnvKeys`는 app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), 결정 5(`@DisplayName`은 한국어). 결정 색인 2.7·2.1 |
|
||||
| `AGENTS.md:267`, `src/adapter/outbound/cache-redis/CLAUDE.md:197`~`198` | "리뷰 05-18", "review finding 05-18" | "2026-11-03 정함", "decided 2026-11-03" | `1101/05-18`(설정 prefix·바인딩 방식이 capability 기준 4와 다르다, `05-outbound-capabilities.md`). 결정은 `1101` README 15절(2026-11-03, 위임), 결정 색인 2.6 「Redis prefix 예외」 |
|
||||
| `src/adapter/inbound/graphql/CLAUDE.md:76`, `:130` | "owner decision 25", "소유자 결정 25" | "owner decision 2026-09-25", "2026-09-25 소유자 결정" | 결정 25(GraphQL DataLoader 키 실패는 등록된 `ApiErrorCode`만 노출). 결정 색인 2.3 |
|
||||
| `src/adapter/inbound/graphql/CLAUDE.md:104` | "servlet 단일 스택(D4)" | 괄호를 지웠다 | D4는 servlet 단일 스택 결정의 번호다. 결정 9 행의 "D4를 outbound에도 적용"이 같은 번호다(`2026-09-25-review-followup-status.md` 「소유자 결정」). D4를 적은 원래 설계 기록은 이 repo에 없다 |
|
||||
| `src/adapter/inbound/web/CLAUDE.md:45`~`46`(줄바꿈으로 갈림), `src/adapter/outbound/support/CLAUDE.md:30` | "review 2026-11-01 07-10" | "since 2026-11-01" | `1101/07-10`(설정 오타·죽은 키가 기동에서도 게이트에서도 안 잡히는 곳이 있다, `07-bootstrap-composition-config.md`). 그 수정이 `app.security`를 `StrictSettingsBinder`로 묶었다 |
|
||||
| `src/adapter/inbound/web/CLAUDE.md:136`, `:143`, `:154`, `:161`, `:163`, `:164` | "D2", "D3", "D3 / SBMS-C3", "D5", "D6", "D7" | 괄호를 지웠다. S1~S5는 이 문서의 항목 이름이라 남겼다 | 설계 기록 `feature-schema-serialization-contract`(이 repo에 없음)의 결정 번호. 규칙은 각 항목 본문, `JacksonSerializationPolicyTest`, ArchUnit `no_bigdecimal_double_constructor`가 가진다 |
|
||||
| `src/adapter/inbound/web/CLAUDE.md:191` | "C3 / C7 / D9" | "C3 / C7" | 설계 기록 `feature-business-rule-validation-contract`(이 repo에 없음)의 결정 번호. 규칙은 `BusinessRuleValidationContractTest`와 누출 테스트 |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:222` | "persistence-multi-db-extensibility D3" | 괄호를 지웠다 | 설계 기록 `persistence-multi-db-extensibility`(이 repo에 없음)의 결정 번호. 규칙은 같은 문장의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`·`PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2` |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:239` | "review 09-05" | 괄호를 지웠다. 이유는 같은 문단 끝 문장(시작마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복)이 적는다 | `1101/09-05`(트랜잭션마다 `SHOW TRANSACTION ISOLATION LEVEL` 왕복 1회, `09-performance-measurement.md`) |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:246` | "review 04-10" | "since 2026-11-01" | `1101/04-10`(기본 쓰기·읽기 트랜잭션에 시간 제한이 없다, `04-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:251` | "review RR-03-03" | 지웠다 | `1103/RR-03-03`(JPA 경로에서 트랜잭션 마감 초과가 분류되지 않고 500이 된다, `03-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:265`, `:277`, `:367` | "D12 of …", "… D1", "D9 of …" | 설계 기록 이름만 남겼다 | `feature-application-port-usecase-contract`의 D12(`inNew` 풀 크기 제약), `feature-persistence-failure-baseline`의 D1(영속성 실패 번역 계약), `feature-architecture-enforcement-rules`의 D9(MapStruct 생성 mapper 예외). 셋 다 이 repo에 없다 |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:309` | "review 04-06" | "before 2026-11-01 a hand-kept second table had already drifted" | `1101/04-06`(SQLState 분류표가 두 벌이고 이미 갈라졌다, `04-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:318` | "review 04-05" | 지웠다 | `1101/04-05`(`@Version` 충돌이 변환되지 않고 500 INTERNAL_ERROR로 나간다, `04-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-jpa/CLAUDE.md:340`, `:341`, `:343`, `:348`, `:349`, `:357`, `:361` | "D3", "D2", "D6", "D1", "D4", "D5" | 지웠다 | 설계 기록 `feature-persistence-auditing-contract`(같은 문서 「Persistence auditing contract」 절 제목이 이름을 댄다, 이 repo에 없음)의 결정 번호. 규칙은 `AuditableEntity`와 ArchUnit `domain_is_pure`가 가진다 |
|
||||
| `src/application-core/CLAUDE.md:40`, `:42`, `:44`, `:242`, `:250`, `:332` | "D3", "ArchUnit D11", "per D12", "(D11)", "(D12)" | D11 하나는 ArchUnit 규칙 이름 `application_does_not_depend_on_application_context`로 바꿨다. 나머지는 지웠다 | 설계 기록 `feature-application-port-usecase-contract`(이 repo에 없음)의 결정 번호: D3 `TransactionPort`, D11 콜백 시그니처와 `ApplicationContext` 금지, D12 `inNew` 풀 크기(문자열 키 bean 조회의 정적 분석 사각지대 문장도 같은 번호를 썼다) |
|
||||
| `src/application-core/CLAUDE.md:174` | "review 2026-11-01 01-10 (b)" | "weighed in the 2026-11-01 maturity review" | `1101/01-10`(application-core 한 이름공간에 커널·플랫폼 기능·업무 기능이 섞인다, `01-core-and-feature-pattern.md`)의 대안 (b) |
|
||||
| `src/application-core/CLAUDE.md:288`, `:290` | "re-review RR5-01-02·03", "re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04" | 앞은 "owner decision 2026-11-04"만 남겼다. 뒤 줄은 지웠다 | `1103/RR5-01-02`(`renew`·`inspect` 결과 값의 뜻이 하나씩 늘었다)·`RR5-01-03`(포트 javadoc의 "주인의 마지막 보고를 기록이 갖는다"가 동작과 다르다), `round5/review.md`. `1103/RR-01-11`(lease가 지나면 Redis 저장소가 작업을 다시 돌린다, `round2/01-core-app-inbound.md`), `1103/RR-03-11`(replay TTL이 lease보다 짧으면 key가 lease 도중 사라진다, `round2/03-outbound.md`), `1103/RR3-03-04`(watchdog·계약으로 바뀐 뒤 옛 표현이 남은 문서, `round3/03-outbound.md`) |
|
||||
| `src/application-core/CLAUDE.md:293`, `:297` | "owner decision 2026-11-06" | 그대로 | 걷어낼 ID가 아니다. 옛 패턴 `owner decision \d+`가 날짜를 번호로 잡은 오탐이라 패턴을 고쳤다(아래) |
|
||||
| `src/application-core/CLAUDE.md:311`, `:317`, `:319`, `:322`, `:326`, `:336` | "D1", "D3", "D4", "D5", "D2", "query-bypass D1" | 항목 이름만 남겼다(Purity guardrail, Strict ceremony, Transaction, Capability) | 설계 기록 `feature-application-query-bypass-contract`(같은 문서 「Read / query path」 절 제목, 이 repo에 없음)의 결정 번호. D1은 ArchUnit `query_ports_do_not_leak_domain_jpa_or_web_types`가 지킨다 |
|
||||
| `src/adapter/outbound/cache-redis/CLAUDE.md:137`, `:138`, `src/adapter/outbound/httpclient/CLAUDE.md:93` | "review 2026-11-01 05-16", "review 2026-11-03 RR-04-05" | "since 2026-11-01", "until 2026-11-03", httpclient는 지웠다 | `1101/05-16`(capability 완료 기준 5가 영역 전체에서 지켜지지 않는다, `05-outbound-capabilities.md`), `1103/RR-04-05`(Redis 멱등성 계약의 실서버 실행이 어느 게이트에도 없다, `04-outbound-capabilities.md`) |
|
||||
| `src/adapter/outbound/cache-redis/CLAUDE.md:186`~`187`(줄바꿈으로 갈림) | "review 2026-11-03 README §4, RR-04-02" | "decided 2026-11-03" | `1103/RR-04-02`(캐시 조건부 쓰기가 멱등성·rate-limit·lease와 SCRIPT lane을 나눠 쓴다, `04-outbound-capabilities.md`). 결정은 `1103` README 4절(위임), 결정 색인 2.4 「Redis 연결 예산」 |
|
||||
| `src/adapter/outbound/cache-redis/CLAUDE.md:190` | "RR-04-10" | 지웠다 | `1103/RR-04-10`(`DEGRADED` 정렬 순서를 상태를 내지 않는 leaf가 싣는다, `04-outbound-capabilities.md`) |
|
||||
| `src/adapter/outbound/httpclient/CLAUDE.md:27` | "decision 9 (2026-09-25)" | "the 2026-09-25 owner decision" | 결정 9(httpclient reactive 스택 삭제). 결정 색인 2.7 |
|
||||
| `src/adapter/outbound/identifier/CLAUDE.md:22` | "review 2026-11-01 06-06" | 지웠다 | `1101/06-06`(application EventId 문법과 platform MessageId(UUID)가 다르다, `06-messaging.md`) |
|
||||
| `src/adapter/outbound/identifier/CLAUDE.md:24` | "README, review 05-21" | "README" | `1101/05-21`(identifier leaf: 이름·문서가 내용과 맞지 않는다, `05-outbound-capabilities.md`) |
|
||||
| `src/adapter/outbound/identifier/CLAUDE.md:32`, `src/adapter/outbound/persistence-mongo/CLAUDE.md:53`~`54`(줄바꿈), `src/messaging/CLAUDE.md:33`, `src/grpc/CLAUDE.md:44`, `src/grpc-advanced/CLAUDE.md:21`, `src/shared-contract/CLAUDE.md:34` | "review 2026-11-01 01-11"(shared-contract는 "…, decision in the review README §15") | 지웠다. shared-contract는 "decided 2026-11-03" | `1101/01-11`(공용 다이제스트 헬퍼가 있는데 복사본이 남아 있고, 일부 leaf는 registry 때문에 복사가 강제된다, `01-core-and-feature-pattern.md`). 결정은 `1101` README 15절(2026-11-03, 위임), 결정 색인 2.2 「edge 없는 복사본」 |
|
||||
| `src/adapter/outbound/messaging/CLAUDE.md:42` | "owner decision 29" | "owner decision 2026-09-25" | 결정 29(messaging 카드 검증기의 YAML 라이브러리는 테스트에서만). 결정 색인 2.6 |
|
||||
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:15`, `src/adapter/outbound/persistence-notification/CLAUDE.md:9` | "review 04-16" | 지웠다 | `1101/04-16`(notification·fileserver leaf에 가까운 안내 문서가 없고 패키지가 평평하다, `04-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:26` | "review 04-17" | 지웠다 | `1101/04-17`(미리 정한 UUID + primitive `long` version이라 `save()`가 merge로 동작한다, `04-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:58`~`59` | "added in review 2026-11-03 RR-01-04" | "added on 2026-11-03" | `1103/RR-01-04`(application-fileserver 저장 포트 9개 중 7개는 공유 계약이 없다, `01-core-application.md`) |
|
||||
| `src/adapter/outbound/persistence-fileserver/CLAUDE.md:64` | "review 04-04" | 지웠다 | `1101/04-04`(실 PostgreSQL lane 9개가 어떤 게이트·workflow에서도 돌지 않는다, `04-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-notification/CLAUDE.md:20` | "review RR-03-09" | 지웠다 | `1103/RR-03-09`(notification 엔티티의 변경 메서드가 public이 됐다, `03-persistence.md`) |
|
||||
| `src/adapter/outbound/persistence-notification/CLAUDE.md:40` | "owner decision 33" | "owner decision 2026-09-25" | 결정 33(caller 트랜잭션 guard: `persistence-jpa` edge, `CallerTransaction` 하나). 결정 색인 2.2 |
|
||||
| `src/adapter/outbound/support/CLAUDE.md:32` | "review 15절, r3-I" | "decided 2026-11-03" | `1101` README 15절(2026-11-03) 「선택 숫자 설정의 빈 env 값 (r3-I 발견)」 행. r3-I는 3라운드 수정 묶음이다. 결정 색인 2.6 「빈 env 값」 |
|
||||
| `src/app-bootstrap/CLAUDE.md:49` | "BOOT-006 / BOOT-007" | 리뷰 문서 경로만 남겼다 | `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`의 BOOT-006(패키지 분류가 두 축으로 섞이고 `Settings` 배치 규칙이 없다), BOOT-007(같은 분해 문제를 두 방식으로 푼다) |
|
||||
| `src/messaging/CLAUDE.md:29` | "S7-#5b" | "2026-09-25 리뷰 후속 작업에서 나눴다" | `2026-09-25-review-followup-status.md` S7-#5b 행(한 leaf가 relay 로직·PG repository·admin journal을 함께 가졌다, W3-P18에서 완료) |
|
||||
| `src/messaging/CLAUDE.md:38`, `src/grpc/CLAUDE.md:50`, `src/grpc-advanced/CLAUDE.md:25`, `src/shared-contract/CLAUDE.md:31`~`32` | "MSG-023 §6.2", "MSG-023" | "2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치" 등 | `docs/reviews/2026-08-14-messaging-module-code-review.md` MSG-023(module 이름·폴더 구조와 canonical 정책 문서가 실제 구조를 설명하지 못한다). vendored 플랫폼은 Clean Architecture 계층이 아니라는 결정은 `1101/06-messaging.md` 머리의 "소유자 결정 유지" 줄 |
|
||||
| `src/messaging/CLAUDE.md:43` | "review 2026-11-01 06-01" | 지웠다 | `1101/06-01`(다시 시도하면 될 거부를 relay가 즉시 DEAD로 보낸다, `06-messaging.md`) |
|
||||
| `src/messaging/CLAUDE.md:66` | "재리뷰 2026-11-03 RR-05-07" | "2026-11-03" | `1103/RR-05-07`(vendored 제품 안에 두 재시도 규칙이 생겼고 고른 이유가 제품 쪽에 없다, `05-messaging.md`) |
|
||||
| `src/messaging/CLAUDE.md:98`, `:113`, `src/grpc/CLAUDE.md:98` | "MSG-015", "MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7)", "MSG-015(bridge 부재)" | "cutover 완료", "application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정)", "bridge 부재(2026-08-14 messaging 모듈 리뷰)" | MSG-015(기존 application/runtime과 신규 platform 사이에 semantic bridge와 cutover 권한이 없다, 같은 messaging 리뷰). 결정 7(outbox append를 canonical `OutboxAppendPort`로 통일) |
|
||||
| `src/messaging/CLAUDE.md:140` | "MSG-022" | 지웠다 | MSG-022(experimental adapter가 class 이름 문자열로 오류를 추측한다, 같은 messaging 리뷰) |
|
||||
| `src/grpc/CLAUDE.md:167`, `:169` | "03-11 (b)", "The review", "re-review 2026-11-03, RR-02-07" | "option (b)", "The 2026-11-01 maturity review", "(b) was chosen on 2026-11-03" | `1101/03-11`(`app.grpc.platform.operation-ledger-enabled`가 검증만 통과시키고 key를 처리하는 코드가 없다, `03-inbound-realtime-graphql-grpc.md`)의 대안 (a)·(b), `1103/RR-02-07`(같은 문제를 다시 본 발견, `02-inbound-transports.md`). 고른 안은 ADR-GRPC-004 |
|
||||
| `src/grpc/CLAUDE.md:185` | "re-review RR-02-04" | ADR 이름만 남겼다 | `1103/RR-02-04`(ledger에 시도 구분이 없어 takeover 뒤 옛 owner의 기록이 새 시도를 덮는다, `02-inbound-transports.md`) |
|
||||
| `src/grpc-advanced/CLAUDE.md:64` | "리뷰 2026-09-24 S5-lead-4" | "2026-09-25 리뷰 후속 작업에서 삭제했다" | `2026-09-25-review-followup-status.md` S5-lead-4 행(release·promotion gate가 websocket·grpc에도 반복되는지, W3-P16에서 삭제). 같은 ID가 `docs/runbooks/grpc-advanced-capabilities.md`와 `docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md`에 남아 있다(검사 대상 밖) |
|
||||
| `src/shared-contract/CLAUDE.md:27` | "review X2-P1-5, X2-P1-4b, X1-#9" | "moved here in the 2026-09-25 review follow-up" | `2026-09-25-review-followup-status.md`의 X2-P1-5(SHA-256 보일러플레이트 → `Sha256`), X2-P1-4b(서명 헬퍼만 shared-contract로), X1-#9(Backoff 계산식 10개 → `Backoff`). 셋 다 W3-P19 |
|
||||
|
||||
`scripts/check-work-docs.py`에 더하고 고친 것(2026-11-07):
|
||||
|
||||
- 기본 검사 대상: `AGENTS.md`와 `src/**/CLAUDE.md`(build 출력 밖)를 더했다. `AGENTS.md`는 링크 검사에도 더했다(lychee 범위 밖이다).
|
||||
- 새 패턴 넷: 모듈 리뷰 발견(`MSG-023`, `BOOT-006` — 접두어는 `docs/reviews/`에서 세 자리 번호로 쓰인 여섯), 리뷰 후속 발견(`S6-#10a`, `X2-P1-5`, `S5-lead-4`), 고른 대안이 붙은 발견 번호(`03-11 (b)`), 영어 리뷰 README 절(`review README §15`). 「결정 N」 패턴에 영어 `decision 9`를 더했다.
|
||||
- 고친 오탐: 날짜로 쓴 결정(`owner decision 2026-11-06`, `소유자 결정 2026-11-07`)은 잡지 않는다.
|
||||
- 줄바꿈 검사: 한 줄에서 안 걸려도 다음 줄과 이었을 때 줄 경계를 넘는 ID(`(review` ↵ `2026-11-01 07-10)`)를 잡는다. 이번에 2줄(web·persistence-mongo)이 이 꼴이었다. persistence-fileserver·cache-redis의 갈린 괄호는 둘째 줄의 `RR-` 접두어가 따로 잡혔다.
|
||||
- 오탐 시험(`docs-writing.md` 4절 12단계): 잡아야 할 문장 10개는 모두 잡혔다. 잡지 말아야 할 문장 8개 중 하나가 걸렸다: 일부러 만든 "line 10-12 (b)"(콜론 없는 줄 범위 뒤 대안 표시)다. repo에는 그 꼴이 없어 그대로 뒀다. `docs/reviews/**` 밖 전체에 돌리면 새로 125줄이 걸린다. 모두 검사 대상 밖(모듈 README, ADR, `docs/httpclient/` 등)의 실제 ID이고, 검사 대상 안의 오탐은 0이다.
|
||||
|
||||
@@ -100,7 +100,7 @@
|
||||
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
|
||||
- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다.
|
||||
- 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다.
|
||||
- `docs/work/`나 루트 `CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
||||
- `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
|
||||
@@ -33,6 +33,7 @@
|
||||
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 |
|
||||
| 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 |
|
||||
| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 총괄이 쓴다 | 기본값 | 2026-11-06 | `docs/work/evidence.md` 9절 |
|
||||
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`. 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
|
||||
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 `~/.claude/CLAUDE.md` 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 | 기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「보고」 |
|
||||
| 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 |
|
||||
| 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | `1103` 16절 |
|
||||
|
||||
@@ -48,7 +48,7 @@
|
||||
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
|
||||
| 의존성 | `verifyDependencyLocks` |
|
||||
| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) |
|
||||
| `docs/work/`, 루트 `CLAUDE.md` | `python3 scripts/check-work-docs.py` |
|
||||
| `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md` | `python3 scripts/check-work-docs.py` |
|
||||
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` |
|
||||
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
|
||||
|
||||
+51
-11
@@ -8,6 +8,9 @@ to finish the job from those alone. Two things break that, and both are mechanic
|
||||
1. History IDs in the body. A sentence such as "fixed as in 1101/05-01" means nothing to a reader
|
||||
who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference
|
||||
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`).
|
||||
The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and
|
||||
every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and
|
||||
`docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository.
|
||||
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
|
||||
total limit, so a session reads the whole path instead of skimming it.
|
||||
|
||||
@@ -32,6 +35,7 @@ from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
MAP = REPO_ROOT / "CLAUDE.md"
|
||||
RULE_BOOK = REPO_ROOT / "AGENTS.md"
|
||||
WORK = REPO_ROOT / "docs/work"
|
||||
README = WORK / "README.md"
|
||||
|
||||
@@ -100,10 +104,21 @@ HISTORY_PATTERNS = [
|
||||
("round number in Korean (1라운드, 라운드6)",
|
||||
re.compile(r"(?<![\w.~-])\d{1,2} ?라운드(?! ?(?:동안|마다|씩|간))|라운드 ?\d{1,2}(?![\w.])", re.ASCII)),
|
||||
("review README section number (리뷰 README 13절)", re.compile(r"리뷰 README \d", re.ASCII)),
|
||||
# A decision named by its date ("owner decision 2026-11-06") is content plus a date, not a number.
|
||||
("decision named by number only",
|
||||
re.compile(r"결정 ?(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))|owner decision \d+", re.ASCII)),
|
||||
re.compile(r"결정 ?(?!\d{4}-)(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))"
|
||||
r"|(?<![A-Za-z])[Dd]ecision (?!\d{4}-)\d+", re.ASCII)),
|
||||
("old manual decision number (M-3)", re.compile(r"\bM-\d+\b", re.ASCII)),
|
||||
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", re.ASCII)),
|
||||
# Module code reviews before 2026-11 numbered findings per module: MSG-023, BOOT-006, GQL-012.
|
||||
("module review finding (MSG-023, BOOT-006)",
|
||||
re.compile(r"(?<![\w-])(?:BOOT|MSG|JPA|MNG|GQL|NTF)-\d{3}\b", re.ASCII)),
|
||||
# The 2026-09-24 reviews and their follow-up named findings S6-#10a, X2-P1-5, S5-lead-4.
|
||||
("review follow-up finding (S6-#10a, X2-P1-5)",
|
||||
re.compile(r"\b[SX]\d-(?:#\d+|P\d-\d+|lead-\d+)", re.ASCII)),
|
||||
("finding number with its chosen option (03-11 (b))",
|
||||
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
|
||||
("review README section (review README §15)", re.compile(r"review README §", re.ASCII)),
|
||||
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
|
||||
]
|
||||
|
||||
@@ -119,7 +134,7 @@ def line_count(path: Path) -> int:
|
||||
|
||||
|
||||
def check_exists(errors: list[str]) -> bool:
|
||||
expected = [MAP, README, WORK / EVIDENCE]
|
||||
expected = [MAP, RULE_BOOK, README, WORK / EVIDENCE]
|
||||
expected += [WORK / name for name in PLAYBOOKS + REFERENCES]
|
||||
missing = [rel(path) for path in expected if not path.is_file()]
|
||||
for name in missing:
|
||||
@@ -180,23 +195,48 @@ def check_skeleton(errors: list[str]) -> None:
|
||||
)
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output."""
|
||||
skipped = {"build", ".gradle", "node_modules"}
|
||||
return sorted(
|
||||
path
|
||||
for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
)
|
||||
|
||||
|
||||
def history_checked_files() -> list[Path]:
|
||||
files = [MAP]
|
||||
files = [MAP, RULE_BOOK]
|
||||
for path in sorted(WORK.rglob("*.md")):
|
||||
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
|
||||
files.append(path)
|
||||
return files
|
||||
return files + module_guides()
|
||||
|
||||
|
||||
def history_match(line: str, following: str) -> tuple[str, str] | None:
|
||||
"""The first history ID on this line, or one that a line break splits ("review\n2026-11-01 07-10")."""
|
||||
for label, pattern in HISTORY_PATTERNS:
|
||||
match = pattern.search(line)
|
||||
if match:
|
||||
return label, match.group(0)
|
||||
if not following.strip():
|
||||
return None
|
||||
joined = line.rstrip() + " " + following.strip()
|
||||
for label, pattern in HISTORY_PATTERNS:
|
||||
for match in pattern.finditer(joined):
|
||||
if match.start() < len(line.rstrip()) < match.end():
|
||||
return label, match.group(0)
|
||||
return None
|
||||
|
||||
|
||||
def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]:
|
||||
hits = []
|
||||
for path in files:
|
||||
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
||||
for label, pattern in HISTORY_PATTERNS:
|
||||
match = pattern.search(line)
|
||||
if match:
|
||||
hits.append((path, number, label, match.group(0)))
|
||||
break
|
||||
lines = path.read_text(encoding="utf-8").splitlines()
|
||||
for number, line in enumerate(lines, start=1):
|
||||
found = history_match(line, lines[number] if number < len(lines) else "")
|
||||
if found:
|
||||
hits.append((path, number, *found))
|
||||
return hits
|
||||
|
||||
|
||||
@@ -225,7 +265,7 @@ def check_history(errors: list[str], report: list[str]) -> None:
|
||||
|
||||
|
||||
def check_links(errors: list[str], report: list[str]) -> None:
|
||||
checked, broken = broken_links([MAP] + sorted(WORK.rglob("*.md")))
|
||||
checked, broken = broken_links([MAP, RULE_BOOK] + sorted(WORK.rglob("*.md")))
|
||||
for path, number, target in broken:
|
||||
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
|
||||
report.append(f"relative links checked: {checked}")
|
||||
|
||||
@@ -73,7 +73,7 @@ platform wire-code catalogue in `GraphQlErrorCode`.
|
||||
- application/domain `ApiErrorCode` values remain a separate namespace and pass through with
|
||||
`GraphQlErrorCode.of(...)`; GraphQL must not rename product errors. Only a registered
|
||||
`ApiErrorCode` reaches the wire this way — a DataLoader per-key failure carries one, never a free
|
||||
string (owner decision 25).
|
||||
string (owner decision 2026-09-25).
|
||||
- new GraphQL-owned platform codes use the `GRAPHQL_` prefix. The existing unprefixed platform
|
||||
values are frozen legacy wire contracts and are listed explicitly by
|
||||
`legacyUnprefixedPlatformCodes()`.
|
||||
@@ -101,7 +101,7 @@ application/platform namespace split.
|
||||
`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만
|
||||
`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를
|
||||
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
|
||||
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택(D4)이라 실행
|
||||
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
|
||||
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
|
||||
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
|
||||
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
|
||||
@@ -127,7 +127,7 @@ application 매핑(`GraphQlExceptionResolver`) → `IllegalArgumentException`·
|
||||
걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
|
||||
shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category →
|
||||
wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다.
|
||||
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 소유자 결정 25).
|
||||
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정).
|
||||
|
||||
## 향후 adopter 의 feature 기여 방법
|
||||
|
||||
|
||||
@@ -42,8 +42,8 @@ ArchUnit `WEB-ARCH-ADV`).
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- `:adapter:outbound:support` — `StrictSettingsBinder` only. `app.security` (`SecuritySettings`, the
|
||||
authentication mode included) is bound by the one strict binder every module uses (review
|
||||
2026-11-01 07-10); the ArchUnit inbound/outbound rules allow that class and nothing else from the
|
||||
authentication mode included) is bound by the one strict binder every module uses (since
|
||||
2026-11-01); the ArchUnit inbound/outbound rules allow that class and nothing else from the
|
||||
leaf.
|
||||
- Spring Web/Security/Validation dependencies.
|
||||
|
||||
@@ -133,14 +133,14 @@ live in `app-bootstrap` (`application.yml` `spring.jackson.serialization.*` /
|
||||
`spring.jackson.generator.*`); ArchUnit + effective-config tests live in
|
||||
`app-bootstrap` (`JacksonSerializationPolicyTest`, `no_bigdecimal_double_constructor`).
|
||||
|
||||
- **S1 — Date / time / timezone (D2).** `WRITE_DATES_AS_TIMESTAMPS=false` is
|
||||
- **S1 — Date / time / timezone.** `WRITE_DATES_AS_TIMESTAMPS=false` is
|
||||
pinned, so `java.time` values serialize as ISO-8601 strings via `JavaTimeModule`
|
||||
(`OffsetDateTime` → `"...Z"`, `LocalDate` → `"YYYY-MM-DD"`), never a numeric
|
||||
epoch or `[y,m,d,...]` array. Server timezone is **UTC**: emit instants as
|
||||
`OffsetDateTime`/`Instant` with a `Z` offset. Use `LocalDate` only for
|
||||
date-only calendar fields. Do **not** put timezone-less `LocalDateTime` on a
|
||||
response DTO — it serializes without an offset and breaks the contract.
|
||||
- **S2 — Money / BigDecimal (D3).** Default scale 2, rounding `HALF_UP` unless
|
||||
- **S2 — Money / BigDecimal.** Default scale 2, rounding `HALF_UP` unless
|
||||
the domain documents otherwise (KRW/JPY = scale 0 with a schema note).
|
||||
`WRITE_BIGDECIMAL_AS_PLAIN=true` is pinned so values never serialize in
|
||||
scientific notation. Pick **one** JSON representation per API and state it in
|
||||
@@ -151,17 +151,17 @@ live in `app-bootstrap` (`application.yml` `spring.jackson.serialization.*` /
|
||||
- **S3 — `new BigDecimal(double)` is banned.** The `double`/`float` constructors
|
||||
capture binary floating-point error (`new BigDecimal(0.1)` ≠ `0.1`). Build from
|
||||
a `String` (`new BigDecimal("0.1")`) or `BigDecimal.valueOf(double)`. Enforced
|
||||
by the `no_bigdecimal_double_constructor` ArchUnit rule (D3 / SBMS-C3).
|
||||
by the `no_bigdecimal_double_constructor` ArchUnit rule.
|
||||
- **S4 — Enum / null·empty·missing.** Request-side unknown enum →
|
||||
`VALIDATION_FAILED` (B1 `read-unknown-enum-values-as-null=false`); legacy values
|
||||
map through an explicit adapter, never a silent fallback. The
|
||||
absent / explicit-null / value distinction is owned by the inbound web mapper
|
||||
(Controller DTO → Command), expressed with `Patch<T>` (B2); `domain-core` and
|
||||
`application-core` receive the already-resolved 3-state, never a wire type.
|
||||
- **S5 — Out of this branch's scope.** OpenAPI drift enforcement (D5) is owned by
|
||||
- **S5 — Out of this branch's scope.** OpenAPI drift enforcement is owned by
|
||||
the verification suite / api-contract-baseline; removed-field-reuse ban tooling
|
||||
(D6, `x-removed-fields` vs markdown catalog) is `needs-confirmation`; Avro
|
||||
Schema Registry for outbox/event (D7) and response field rename/versioning
|
||||
(`x-removed-fields` vs markdown catalog) is `needs-confirmation`; Avro
|
||||
Schema Registry for outbox/event and response field rename/versioning
|
||||
(`feature-api-compatibility-deprecation-contract`) are separate branches.
|
||||
|
||||
## Business rule validation contract
|
||||
@@ -188,7 +188,7 @@ above and is enforced by ArchUnit + contract tests (not new runtime mechanism).
|
||||
the type immutable, so no application-service or persistence path can hand out an
|
||||
invariant-violating instance. A DB constraint is a backstop, never the only check
|
||||
(Forbidden: "DB constraint as only invariant").
|
||||
- **C3 / C7 / D9 — Persistence integrity maps to an operational error, leak-free.** A
|
||||
- **C3 / C7 — Persistence integrity maps to an operational error, leak-free.** A
|
||||
unique/FK/check/serialization failure maps to `DATA_INTEGRITY` / `CONFLICT` with a
|
||||
**client-safe message only**. The raw SQL, constraint/index name, SQLState code,
|
||||
exception class, and stack frame must never reach `error.message` or
|
||||
|
||||
@@ -134,8 +134,8 @@ not in this leaf's `mainCheck` too, which ran it twice per push to main) starts
|
||||
runs `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest` and
|
||||
`LiveRedisIdempotencyStoreContractTest` (the `application-core` port contracts the in-memory fakes
|
||||
also pass), `LiveRedisSemanticPortsTest` and `LiveRedisSemanticScriptAclProbeTest`; a skip fails it
|
||||
(review 2026-11-01 05-16). The idempotency contract was on the explicit-only topology lane alone
|
||||
until review 2026-11-03 RR-04-05, so the Lua state machine's stale-handle, renew-refusal and
|
||||
(since 2026-11-01). The idempotency contract was on the explicit-only topology lane alone
|
||||
until 2026-11-03, so the Lua state machine's stale-handle, renew-refusal and
|
||||
retry cases reached a real server in no gate. `RedisTestContainer`
|
||||
starts the server only when that lane names the ACL file.
|
||||
|
||||
@@ -183,19 +183,19 @@ that reads a cache entry cannot execute a script.
|
||||
The cache's conditional writes run on the same account but on a lane of their own,
|
||||
`CacheScriptLane.CACHE_SCRIPT` (`app.capabilities.cache.maximum-script-connections`, contributed by
|
||||
`RedisCacheConfig` as a `RedisLaneContribution`). Do not move them back to `SCRIPT`: that lane is the
|
||||
idempotency, rate-limit and lease budget, and a cache under load must not take it (review 2026-11-03
|
||||
README §4, RR-04-02). Each lane's wait, refusals and reconnects are meters of `redis-runtime`
|
||||
idempotency, rate-limit and lease budget, and a cache under load must not take it (decided
|
||||
2026-11-03). Each lane's wait, refusals and reconnects are meters of `redis-runtime`
|
||||
(`RedisLaneMetrics`, `redis.lane.*`, tag `lane`), so whether the cache stays off `SCRIPT` is a query,
|
||||
not an assumption. The `DEGRADED` health order ships with `redis-runtime`, which reports the
|
||||
status (`config/module-defaults/redis-runtime.yml`, RR-04-10).
|
||||
status (`config/module-defaults/redis-runtime.yml`).
|
||||
|
||||
A Cluster transaction runs on one node, so the SDK's `RedisTransactionRunner` derives a routing key
|
||||
from the watched keys (or an explicit `RedisSlotTag`) and borrows `RedisSdkLane.TRANSACTION`, which
|
||||
is pinned to its key's owner, on the node that owns that slot. Routed leases are never pooled: a pooled connection is pinned to the previous caller's
|
||||
node.
|
||||
|
||||
Settings binding is a recorded exception to capability criterion 4 (one prefix, `StrictSettingsBinder`,
|
||||
review finding 05-18): `app.redis.*` is bound by `redis-runtime` with setters and `validate()`,
|
||||
Settings binding is a recorded exception to capability criterion 4 (one prefix, `StrictSettingsBinder`;
|
||||
decided 2026-11-03): `app.redis.*` is bound by `redis-runtime` with setters and `validate()`,
|
||||
because that leaf has no project dependencies and cannot reach `StrictSettingsBinder` (support);
|
||||
`app.capabilities.*` (cache, lease, rate-limit provider) is bound strictly by this leaf under the
|
||||
shared capability-selector root; `app.rate-limit.*` is the HTTP boundary's switch that this leaf only
|
||||
|
||||
@@ -24,7 +24,7 @@ moving a type between packages.
|
||||
- Own the public call surfaces: H1 typed service clients (default), H2 generic exchange, H3 dynamic
|
||||
target. H4 native engine access stays internal to `apache`, `jdk`, and `http3`.
|
||||
- Blocking only: calls run on the caller's (virtual) thread through `RestClient`. The reactive stack
|
||||
(`WebClient`, Reactor Netty) was removed by decision 9 (2026-09-25); do not add it back.
|
||||
(`WebClient`, Reactor Netty) was removed by the 2026-09-25 owner decision; do not add it back.
|
||||
- Own Named Client Profiles, runtime generations, transport SPI, deadlines, evidence-based retry,
|
||||
resilience, authentication, TLS, SSRF defence, streaming lifecycle, and observability.
|
||||
- Adapt external HTTP calls behind application/domain ports.
|
||||
@@ -90,4 +90,4 @@ The transport port (`BlockingTransportProvider`) has one abstract contract in th
|
||||
(`StableTransportProviderContractTest`, the contract lane, once per selected transport) and the
|
||||
scripted fake the gateway tests stand on passes it in the default lane
|
||||
(`ScriptedTransportContractTest`). A new transport, or a change to `ScriptedTransport`, inherits the
|
||||
same class rather than a copy (AGENTS.md rule 6; review 2026-11-01 05-16).
|
||||
same class rather than a copy (AGENTS.md rule 6).
|
||||
|
||||
@@ -19,9 +19,9 @@ build choices) live in [README.md](README.md).
|
||||
(HMAC-SHA-256 of the UTF-8 principal, lowercase hex).
|
||||
- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` implementation (UUIDv7 via
|
||||
`uuid-creator`). The operation id is also the submission event's id, and the messaging platform's
|
||||
message id accepts only UUIDv7 (review 2026-11-01 06-06). Wired by `composition:durable-operation`.
|
||||
message id accepts only UUIDv7. Wired by `composition:durable-operation`.
|
||||
- The leaf name says "identifier"; general-purpose clock and random sources are not here.
|
||||
The name is kept because Gradle paths and consumers use it (README, review 05-21).
|
||||
The name is kept because Gradle paths and consumers use it (README).
|
||||
- Wiring is `composition/service-runtime` (`PseudonymizationConfig`), not this leaf.
|
||||
|
||||
## Allowed
|
||||
@@ -29,7 +29,7 @@ build choices) live in [README.md](README.md).
|
||||
Declared in [build.gradle](build.gradle); the registry entry is the SSOT.
|
||||
|
||||
- `:application-core` — the ports both classes implement.
|
||||
- `:shared-contract`, for `HmacSha256` only (review 2026-11-01 01-11). The pseudonym is the hex HMAC
|
||||
- `:shared-contract`, for `HmacSha256` only. The pseudonym is the hex HMAC
|
||||
of the principal; `HmacUserPrincipalPseudonymizerVectorTest` pins it to a vector computed outside
|
||||
the JVM, because logs written before and after a release are joined on it.
|
||||
- `:domain-core` — a feature's server-assigned id adapter implements its domain `*IdFactory` port
|
||||
|
||||
@@ -39,7 +39,7 @@ Package root: `dev.caskeleton.adapter.outbound.messaging`.
|
||||
removed on 2026-09-25 (see `docs/capability-status.md`).
|
||||
- No JSON Schema engine (NetworkNT) on the main classpath. The evidence manifest schema check and the
|
||||
capability card check (`config/messaging`) are this leaf's tests (`evidence/`); snakeyaml is
|
||||
test-only (owner decision 29).
|
||||
test-only (owner decision 2026-09-25).
|
||||
- Do not hide use-case sequencing or business routing policy in broker adapters.
|
||||
- `OutboxMessagePublishAdapter` is delegate-only and emits no dependency log. The confirmed
|
||||
FAILED/DEAD transition owns the one canonical ERROR.
|
||||
|
||||
@@ -12,7 +12,7 @@ store adapters that implement `application-fileserver` ports. Root `AGENTS.md` a
|
||||
classes that register them as beans.
|
||||
|
||||
`persistence-notification` follows the same rule (`platform.entity`, `platform.repository`, adapters
|
||||
in `platform`), so the two capability leaves read the same way (review 04-16).
|
||||
in `platform`), so the two capability leaves read the same way.
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -23,7 +23,7 @@ in `platform`), so the two capability leaves read the same way (review 04-16).
|
||||
extend `AssignedIdEntity` (`Persistable<UUID>`). Without it `save` merges — a SELECT before every
|
||||
insert, and a second insert under an existing id overwrites the row instead of failing on the
|
||||
primary key. A new `@Version` column may stay primitive `long`; newness comes from
|
||||
`Persistable`, not from the version (review 04-17).
|
||||
`Persistable`, not from the version.
|
||||
- **No policy here.** Retry budgets, lease lengths and other decisions belong to
|
||||
`application-fileserver` and arrive as port arguments. A claim token or other fence travels in
|
||||
the port type (`CleanupItem.claimToken`), never in a field of the adapter.
|
||||
@@ -55,13 +55,13 @@ in `platform`), so the two capability leaves read the same way (review 04-16).
|
||||
- Port contracts live in `application-fileserver` testFixtures (`*PortContract`, and
|
||||
`FileQuotaLedgerContract` for the three quota ports, which share one table). The in-memory fakes
|
||||
and the PostgreSQL tests both extend them; every port this leaf implements has one
|
||||
(`docs/testing/TESTING_STRATEGY.md` 9.3). The PostgreSQL side of the seven added in review
|
||||
2026-11-03 RR-01-04 is tagged `jpa-contract` and runs in persistence-jpa's
|
||||
(`docs/testing/TESTING_STRATEGY.md` 9.3). The PostgreSQL side of the seven added on
|
||||
2026-11-03 is tagged `jpa-contract` and runs in persistence-jpa's
|
||||
`jpaPlatformContractTest` lane on `FileserverPostgreSqlStack`, whose clock a case moves.
|
||||
- The real-PostgreSQL tests are still in `persistence-jpa`'s `postgresqlIntegrationTest` source
|
||||
set, which owns the container and Flyway wiring, and the JPA readiness card
|
||||
(`config/jpa/readiness-cards.yaml`, checked by `JpaReadinessRegistryTest`) names them as that
|
||||
leaf's tasks — moving them means moving the card's tasks and selectors with them (review 04-04):
|
||||
leaf's tasks — moving them means moving the card's tasks and selectors with them:
|
||||
`postgresqlFileserverMigrationIntegrationTest`, `postgresqlFileserverMetadataIntegrationTest`,
|
||||
`postgresqlFileserverReclamationIntegrationTest`
|
||||
(`./gradlew :adapter:outbound:persistence-jpa:<lane> --console=plain`).
|
||||
|
||||
@@ -218,8 +218,8 @@ should not exist.
|
||||
[application-core/CLAUDE.md](../../../application-core/CLAUDE.md)).
|
||||
- **DB drivers** (`org.postgresql..`, `org.h2..`) or **`org.flywaydb.database.postgresql..`** —
|
||||
those are vendor-specific and belong only in this module's matching vendor package (`.postgresql`,
|
||||
`.h2`); NoSQL-specific dependencies belong only in their own future modules
|
||||
(persistence-multi-db-extensibility D3). This is enforced by ArchUnit
|
||||
`.h2`); NoSQL-specific dependencies belong only in their own future modules.
|
||||
This is enforced by ArchUnit
|
||||
`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL` and `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2` in
|
||||
`CleanArchitectureTest`.
|
||||
- NoSQL adapter code. MongoDB/Redis/DynamoDB adapters are sibling modules, not children of this module.
|
||||
@@ -236,19 +236,19 @@ should not exist.
|
||||
| `inRead` | `REQUIRED` | `READ_COMMITTED` (pool) | `true` | `app.persistence-jpa.transaction.read-timeout` (30 s) |
|
||||
| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED` (pool) | `false` | 30 s, fixed |
|
||||
|
||||
Isolation is pinned on the pool, not on the templates (review 09-05): the templates use
|
||||
Isolation is pinned on the pool, not on the templates: the templates use
|
||||
`ISOLATION_DEFAULT`, the module defaults set `spring.datasource.hikari.transaction-isolation:
|
||||
TRANSACTION_READ_COMMITTED` (applied once per physical connection), and
|
||||
`HikariPoolConstraintValidator` refuses to boot with any other level. Naming the level per template
|
||||
made Spring call `getTransactionIsolation()` at every begin, which pgjdbc answers with a
|
||||
`SHOW TRANSACTION ISOLATION LEVEL` round trip.
|
||||
|
||||
Every mode is time-bounded (review 04-10). Spring hands the remaining time to each statement, so a
|
||||
Every mode is time-bounded (since 2026-11-01). Spring hands the remaining time to each statement, so a
|
||||
slow query or lock wait is cancelled by the server (`57014` → `DB_QUERY_CANCELED`), and a deadline
|
||||
that passed before the next statement gets the same code: Spring's `TransactionTimedOutException`
|
||||
on the JDBC path, and on the JPA path (`JpaTransactionManager`, production) Hibernate's own
|
||||
`TransactionException`, which has no SQLState and is classified because `SpringTransaction` knows
|
||||
its deadline passed (`translateAfterDeadline`, review RR-03-03). A business exception thrown after
|
||||
its deadline passed (`translateAfterDeadline`). A business exception thrown after
|
||||
the deadline is passed on unchanged.
|
||||
|
||||
Pre-built templates are immutable after construction so concurrent callers cannot
|
||||
@@ -262,7 +262,7 @@ When an actual ambient transaction exists it MUST throw
|
||||
committed. A commit failure propagates the transaction exception and no success value
|
||||
is returned to the caller.
|
||||
|
||||
### `inNew` pool-sizing constraint (D12 of feature-application-port-usecase-contract)
|
||||
### `inNew` pool-sizing constraint (feature-application-port-usecase-contract)
|
||||
|
||||
`REQUIRES_NEW` acquires a NEW physical JDBC connection while pinning the outer
|
||||
transaction's connection. Provision the pool to satisfy:
|
||||
@@ -274,7 +274,7 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
Loop-per-record `inNew` calls are forbidden (pool exhaustion + deadlock risk).
|
||||
Batch records inside ONE `inNew`, or move the loop outside the transaction.
|
||||
|
||||
## Persistence failure translation contract (feature-persistence-failure-baseline D1)
|
||||
## Persistence failure translation contract (feature-persistence-failure-baseline)
|
||||
|
||||
A raw Spring `DataAccessException` (and the JPA exception / SQLState / constraint name
|
||||
inside it) must never reach the presentation layer. The
|
||||
@@ -306,7 +306,7 @@ framework-neutral `shared.error.PersistenceFailureException` carrying one of the
|
||||
| `23513` | `DB_CHECK_VIOLATION` | H2 (`.h2` package) — H2 reports CHECK as 23513, not the standard 23514 the core table maps |
|
||||
| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2 collapses statement and lock timeout into one state |
|
||||
|
||||
The PostgreSQL rows are not a second table (review 04-06). `PostgreSqlSqlStateErrorMapping` derives
|
||||
The PostgreSQL rows are not a second table: before 2026-11-01 a hand-kept second table had already drifted. `PostgreSqlSqlStateErrorMapping` derives
|
||||
them from `PostgreSqlFailureClassifier` (SQLState → `FailureCategory`) and
|
||||
`FailureCategory.operationalError()` (category → code) — the same classification the library
|
||||
`PostgreSqlExceptionTranslator` uses — leaving out the standard rows above, categories with no
|
||||
@@ -315,7 +315,7 @@ state, add it to `PostgreSqlState` and the classifier; `SqlStateClassificationPa
|
||||
the two paths disagree on any state.
|
||||
|
||||
**No SQLState, classified by type:** a lost `@Version` race (`OptimisticLockingFailureException`,
|
||||
JPA `OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT` (409, review 04-05); an expired Spring
|
||||
JPA `OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT` (409); an expired Spring
|
||||
transaction deadline (`TransactionTimedOutException`) → `DB_QUERY_CANCELED`; any other persistence
|
||||
failure (JPA, Spring data-access or Spring transaction exception) of a transaction
|
||||
`SpringTransaction` began, once its deadline has passed → `DB_QUERY_CANCELED`.
|
||||
@@ -337,16 +337,16 @@ PostgreSQL `57P01`, `57P02`) or a transport break with no SQLState becomes
|
||||
|
||||
## Persistence auditing contract (feature-persistence-auditing-contract)
|
||||
|
||||
Audit metadata (`created_at` / `updated_at` / `created_by` / `updated_by`, D3) is an
|
||||
infrastructure concern that must never reach `domain-core` (D2). It lives only on the
|
||||
Audit metadata (`created_at` / `updated_at` / `created_by` / `updated_by`) is an
|
||||
infrastructure concern that must never reach `domain-core`. It lives only on the
|
||||
`audit/AuditableEntity` `@MappedSuperclass`; a domain aggregate persistence entity opts in
|
||||
by extending it (D6 — e.g. the sample `WorkLogEntity`). The domain aggregate itself carries
|
||||
by extending it (e.g. the sample `WorkLogEntity`). The domain aggregate itself carries
|
||||
zero audit fields, enforced by ArchUnit `domain_is_pure` (no `jakarta.persistence..`) plus
|
||||
`domain_entities_do_not_carry_audit_fields` (no `createdAt`/`updatedAt`/`createdBy`/`updatedBy`
|
||||
fields under `..domain..`).
|
||||
|
||||
- **Capture = Manual explicit-set (D1 current default).** The repository adapter
|
||||
constructor-injects `Clock` (D4) and `AuditContextPort` (D5) and stamps audit on `save`:
|
||||
- **Capture = Manual explicit-set (current default).** The repository adapter
|
||||
constructor-injects `Clock` and `AuditContextPort` and stamps audit on `save`:
|
||||
INSERT (null version) → `initializeAudit(now, actor)`; UPDATE (non-null version) →
|
||||
carry the persisted `created_*` forward + `applyModification(now, actor)`.
|
||||
`created_*` is `updatable = false`.
|
||||
@@ -354,17 +354,17 @@ fields under `..domain..`).
|
||||
seam and falls back to `"system"` when no principal is bound (scheduler / Flyway / anonymous).
|
||||
The actor's value semantics are owned by feature-authentication-authorization-contract
|
||||
(UNSUPPORTED here); the type is fixed to `String`.
|
||||
- **Excluded (D6).** Infra/immutable entities such as `IdempotencyRecordEntity` (own
|
||||
- **Excluded.** Infra/immutable entities such as `IdempotencyRecordEntity` (own
|
||||
`created_at`, no `updated_at`) do NOT extend `AuditableEntity`. `version`/optimistic-lock
|
||||
is owned by feature-persistence-failure-baseline / feature-transaction-concurrency-contract,
|
||||
not by this audit base.
|
||||
- **Growth path (D1, deferred).** There is no second auditing implementation in the tree. If
|
||||
- **Growth path (deferred).** There is no second auditing implementation in the tree. If
|
||||
manual stamping becomes too error-prone, migrate the canonical `AuditableEntity` contract
|
||||
atomically to Spring Data listeners while preserving its `created_*`/`updated_*` schema, actor
|
||||
bound, `Clock`, and `AuditContextPort` semantics. Bulk/native `@Query` UPDATEs bypass listeners
|
||||
too, so they must continue to stamp audit columns explicitly.
|
||||
|
||||
## MapStruct generated mapper exemption (D9 of feature-architecture-enforcement-rules)
|
||||
## MapStruct generated mapper exemption (feature-architecture-enforcement-rules)
|
||||
|
||||
If MapStruct is introduced for persistence mappers, the generated mapper class will
|
||||
be annotated with `javax.annotation.processing.Generated`. Architecture rules that
|
||||
|
||||
@@ -50,8 +50,8 @@ design package's assumed module layout onto this leaf lives in
|
||||
## Allowed
|
||||
|
||||
- Two project dependencies. `shared-contract` for the `Sha256` and `HmacSha256` helpers (tenant
|
||||
observable key, admin command digest, credential fingerprint, keyset cursor tag — review
|
||||
2026-11-01 01-11; `MongoDigestOutputTest` pins the outputs). `application-core`, for
|
||||
observable key, admin command digest, credential fingerprint, keyset cursor tag;
|
||||
`MongoDigestOutputTest` pins the outputs). `application-core`, for
|
||||
`SecretSourcePort` only. The registry entry's `allowed_dependencies` is
|
||||
`["application-core", "shared-contract"]`, matching what the build actually uses; the
|
||||
bridge in `MongoProfileClientSettingsAutoConfiguration` resolves a typed profile's `uri-secret`
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
`src/config/architecture/modules.json`.
|
||||
- Focused test: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`.
|
||||
- Package root: `dev.caskeleton.adapter.outbound.persistence.notification`. The package rule is
|
||||
the one `persistence-fileserver` uses, so both capability leaves read the same way (review 04-16):
|
||||
the one `persistence-fileserver` uses, so both capability leaves read the same way:
|
||||
- `platform.entity` — JPA rows only.
|
||||
- `platform.repository` — Spring Data interfaces and the SQL text they run (`RecipientClaimSql`).
|
||||
- `platform` — the store adapters (`Jpa*`, `Jdbc*`, the inbox's `JpaNotificationInbox` and its
|
||||
@@ -17,7 +17,7 @@
|
||||
package; an entity never leaves the leaf (the ports carry records). Visibility no longer says so,
|
||||
so a rule does: `JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`, run over the production
|
||||
graph by `JpaProductionArchitectureTest` (app-bootstrap `architectureTest`) for this leaf and
|
||||
`persistence-fileserver` (review RR-03-09).
|
||||
`persistence-fileserver`.
|
||||
|
||||
## Where the tests are
|
||||
|
||||
@@ -37,7 +37,7 @@ without a contract (the serving-state read model, consent, inbox), and why, are
|
||||
## Rules
|
||||
|
||||
- **Every write joins the caller's transaction.** A store write starts with
|
||||
`CallerTransaction.require("<what>")`; the use case owns the transaction (owner decision 33).
|
||||
`CallerTransaction.require("<what>")`; the use case owns the transaction (owner decision 2026-09-25).
|
||||
- **Migrations** live in `src/main/resources/db/migration/jpa/notification-platform` and run as
|
||||
their own Flyway stream (`NotificationSchemaStream`, history table
|
||||
`flyway_jpa_notification_history`). An applied file is never edited: add the next `V<n>__`, pin
|
||||
|
||||
@@ -27,9 +27,9 @@ Package roots: `dev.caskeleton.adapter.outbound` and
|
||||
Fileserver's `LocalStorageFailures`); nothing here knows an error code.
|
||||
- Own `StrictSettingsBinder`, the one strict settings binding. It is also the only support class an
|
||||
inbound leaf may use: `adapter:inbound:web` binds `app.security` with it (registry edge and a
|
||||
class-named ArchUnit exemption, review 2026-11-01 07-10). An empty value for a setting the type
|
||||
class-named ArchUnit exemption, since 2026-11-01). An empty value for a setting the type
|
||||
has (`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`) binds as unset; an empty value under a name
|
||||
the type does not have is still refused (review 15절, r3-I).
|
||||
the type does not have is still refused (decided 2026-11-03).
|
||||
- Keep feature-specific clients and routing policies in their owning leaf.
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -46,7 +46,7 @@ Package root: `dev.caskeleton.bootstrap`.
|
||||
## Package layout
|
||||
|
||||
The rules below exist because their absence is what produced the drift this module was reviewed for
|
||||
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`, BOOT-006 / BOOT-007). Half the
|
||||
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). Half the
|
||||
capabilities lived under `autoconfigure/` and half at the package root; `Settings` classes were split
|
||||
between a `settings/` package and their feature packages with no stated rule; and the same
|
||||
decomposition problem was solved two different ways in the same leaf — Notification as nine focused
|
||||
|
||||
@@ -37,11 +37,11 @@ Package root: `dev.caskeleton.application`.
|
||||
- Controller request/response DTOs.
|
||||
- JPA entities and Spring Data repositories.
|
||||
- HTTP status, transport types (`org.springframework.web..`).
|
||||
- `org.springframework.transaction.annotation.Transactional` (use `TransactionPort` instead — D3).
|
||||
- `org.springframework.transaction.annotation.Transactional` (use `TransactionPort` instead).
|
||||
- `org.springframework.context.ApplicationContext` — direct dependency forbidden
|
||||
(`getBean(Class)` reflection-style bypass blocked by ArchUnit D11). String-key
|
||||
(`getBean(Class)` reflection-style bypass blocked by the ArchUnit rule `application_does_not_depend_on_application_context`). String-key
|
||||
bean lookup / `Class.forName(String)` / `BeanFactory#getBeansOfType` remain
|
||||
ArchUnit's static-analysis blind spot per D12 — guard via code review checklist.
|
||||
ArchUnit's static-analysis blind spot — guard via code review checklist.
|
||||
- Lombok (`lombok..`) — also forbidden in `domain-core`. Within `application-core`,
|
||||
Lombok is currently not in scope for the contract; if you intend to use it,
|
||||
weigh the bytecode opacity cost first.
|
||||
@@ -171,7 +171,7 @@ Enforcement:
|
||||
is part of adding it.
|
||||
- Rejected alternatives: allowing only the listed top-level packages (every derived feature would
|
||||
have to edit the template's list — a merge conflict per feature), and a separate
|
||||
`application-platform` leaf for the platform packages (review 2026-11-01 01-10 (b): clearer
|
||||
`application-platform` leaf for the platform packages (weighed in the 2026-11-01 maturity review: clearer
|
||||
boundary, but more registry edges than a naming rule needs).
|
||||
|
||||
## Canonical use case shape
|
||||
@@ -239,7 +239,7 @@ beans but no enforcing advisor fails startup too (`composition:service-runtime`
|
||||
Both `inWrite` and `inRootWrite` satisfy the direct boundary fitness rule for a
|
||||
`WRITE_REPOSITORY + WRITE` use case. READ and REQUIRES_NEW mappings remain exclusive.
|
||||
|
||||
### Callback signature contract (D11)
|
||||
### Callback signature contract
|
||||
|
||||
`TransactionPort` callbacks are `Supplier<T>` / `Runnable` and cannot throw checked
|
||||
exceptions. This matches Spring's `TransactionCallback<T>` constraint. Wrap domain
|
||||
@@ -247,7 +247,7 @@ checked exceptions into `RuntimeException` subclasses
|
||||
(`DomainException extends RuntimeException`); `IOException` → `UncheckedIOException`;
|
||||
`SQLException` is auto-translated by Spring's `DataAccessException` hierarchy.
|
||||
|
||||
### `inNew` pool-sizing constraint (D12)
|
||||
### `inNew` pool-sizing constraint
|
||||
|
||||
`inNew` acquires a new physical JDBC connection. Pool size MUST satisfy:
|
||||
|
||||
@@ -285,9 +285,8 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
|
||||
leaves the record to its holder: the holder's first late `complete`/`markFailed` is recorded, a
|
||||
lease that ran out is not renewed and a claim whose lease ran out is not started — both answer
|
||||
`LEASE_EXPIRED`, not `NOT_OWNER`, and the executor turns a refused start into "not applied"
|
||||
(owner decision 2026-11-04, re-review RR5-01-02·03). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
|
||||
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases
|
||||
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
|
||||
(owner decision 2026-11-04). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
|
||||
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases.
|
||||
- Every transition names the operation its record was claimed under (`IdempotencyOwner.claimOperationId()`).
|
||||
Another one is `OPERATION_CONFLICT` in every store and changes nothing; so is an inspection that
|
||||
brings the owner token under another operation (owner decision 2026-11-06).
|
||||
@@ -308,32 +307,32 @@ The read side has two equally-valid shapes; pick per read, do not force one:
|
||||
| **Through-aggregate** (default for simple reads) | domain aggregate via a `*Repository` port | read shape == write aggregate **and** the aggregate is the minimal invariant boundary (no lazy collections needed) | `QueryUseCase` → repository port → `WorkLog` |
|
||||
| **Projection (CQRS-lite)** | application-layer projection DTO via a `*QueryPort` | read shape ≠ write, or to skip aggregate hydration / lazy-collection joins | `QueryUseCase` → `*QueryPort` → `WorkLogSummary` (record); query via JPQL `SELECT new` / JdbcTemplate |
|
||||
|
||||
- **D1 — purity guardrail (core, machine-enforced):** a read port whose simple name ends
|
||||
- **Purity guardrail (core, machine-enforced):** a read port whose simple name ends
|
||||
with `QueryPort` MUST return application-layer projection DTOs only — never a domain
|
||||
aggregate, JPA entity, or web type, **including through generic type arguments**
|
||||
(`List<DomainType>`). Enforced by ArchUnit `query_ports_do_not_leak_domain_jpa_or_web_types`.
|
||||
Projection usage itself is **opt-in**, not a forced default; the demo lives in
|
||||
`sample-portfolio` (`WorkLogSummaryQueryPort` / `WorkLogSummary`).
|
||||
- **D3 — Strict ceremony:** every read goes through a `QueryUseCase` bean. There is no thin
|
||||
- **Strict ceremony:** every read goes through a `QueryUseCase` bean. There is no thin
|
||||
web→read-port path — that would bypass the mandatory `@UseCaseCapability` fitness function.
|
||||
- **D4 — transaction:** reads default to `TransactionPort.inRead`. A no-tx (autocommit) read
|
||||
- **Transaction:** reads default to `TransactionPort.inRead`. A no-tx (autocommit) read
|
||||
is an opt-in only when `spring.jpa.open-in-view=false` is confirmed **and** the read is
|
||||
projection-only (no lazy access) **and** a single statement; otherwise keep `inRead`.
|
||||
- **D5 — capability:** a repository-backed projection read is still
|
||||
- **Capability:** a repository-backed projection read is still
|
||||
`repositoryAccess = READ_REPOSITORY`. "Projection vs aggregate" is the return *shape* axis,
|
||||
orthogonal to the repository-access *level* axis — no new enum. Outbound-HTTP reads (no
|
||||
repository) stay `RepositoryAccess.NONE`.
|
||||
- Full CQRS with a separate physical read store (**D2**) is out of scope — escalation only.
|
||||
- Full CQRS with a separate physical read store is out of scope — escalation only.
|
||||
|
||||
## ArchUnit guardrails (enforced)
|
||||
|
||||
- `application_does_not_depend_on_adapters_or_transport`
|
||||
- `application_does_not_use_spring_transactional_annotation`
|
||||
- `application_does_not_depend_on_application_context` (D11)
|
||||
- `application_does_not_depend_on_application_context`
|
||||
- `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK`
|
||||
- `inbound_port_implementations_end_with_use_case`
|
||||
- `inbound_port_implementations_declare_capability`
|
||||
- `query_ports_do_not_leak_domain_jpa_or_web_types` (query-bypass D1 — `*QueryPort` return purity)
|
||||
- `query_ports_do_not_leak_domain_jpa_or_web_types` (`*QueryPort` return purity)
|
||||
|
||||
## Test
|
||||
|
||||
|
||||
@@ -18,11 +18,11 @@ grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
||||
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
|
||||
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의
|
||||
같은 절과 이유가 같다(vendored 플랫폼, MSG-023 §6.2와 같은 배치).
|
||||
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
|
||||
|
||||
## Capability grade와 feature flag
|
||||
|
||||
@@ -61,7 +61,7 @@ property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off
|
||||
|
||||
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
||||
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
||||
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
리뷰 규칙이다.
|
||||
|
||||
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
||||
|
||||
+7
-7
@@ -41,13 +41,13 @@ server profile·named channel profile·method size profile·method policy 기본
|
||||
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
|
||||
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
|
||||
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
|
||||
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
|
||||
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
|
||||
family가 같은 이유로 고른 배치(MSG-023 §6.2)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
||||
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
||||
같은 규칙인지 함께 본다.
|
||||
|
||||
## 증거 등급 — testkit이 하나의 leaf인 이유
|
||||
@@ -95,7 +95,7 @@ soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위
|
||||
|
||||
## application이 이 family에 도달하는 경로
|
||||
|
||||
`messaging:*`의 MSG-015(bridge 부재)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
|
||||
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
|
||||
|
||||
```text
|
||||
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
|
||||
@@ -164,9 +164,9 @@ These keys are not in `docs/registries/env-keys.yaml`: no `app.grpc.platform.*`
|
||||
optional build is not part of the shipped runtime. They join the registry when a composition root
|
||||
adopts the platform.
|
||||
|
||||
**Why the starter assembles the interceptor (03-11 (b)), and not (a).** The review proposed (a):
|
||||
delete the flag and judge by whether a ledger bean exists. (b) was chosen and is recorded in
|
||||
ADR-GRPC-004 (re-review 2026-11-03, RR-02-07): the flag stays and means what it says — when true, the
|
||||
**Why the starter assembles the interceptor (option (b)), and not (a).** The 2026-11-01 maturity review proposed (a):
|
||||
delete the flag and judge by whether a ledger bean exists. (b) was chosen on 2026-11-03 and is recorded in
|
||||
ADR-GRPC-004: the flag stays and means what it says — when true, the
|
||||
decision function is assembled and its TTL comes from configuration. (a) would have removed the false promise but left every adopter to rebuild the same
|
||||
assembly and TTL validation by hand; (b) keeps that in one place. The interceptor bean has no
|
||||
`@ConditionalOnMissingBean` on purpose: a replacement would silently ignore `operation-ledger-claim-ttl`.
|
||||
@@ -182,7 +182,7 @@ its typed service adapter: `decide(...)` before the mutation, `recordCommit(...)
|
||||
transaction, `recordFailure(...)` on a terminal failure. Both record calls take the `GrpcClaimToken`
|
||||
the `PROCEED` decision carried: a commit by an attempt whose claim was taken over is refused (its
|
||||
transaction rolls back) and its failure is ignored, so a slow owner cannot write over the attempt that
|
||||
took its claim (re-review RR-02-04, ADR-GRPC-004).
|
||||
took its claim (ADR-GRPC-004).
|
||||
|
||||
**Purge scheduling is the adopter's.** `GrpcOperationLedgerRetention.purgeExpired(now)` deletes
|
||||
expired finished rows in bounded batches (500 per statement) until a batch comes back short. The
|
||||
|
||||
@@ -26,21 +26,21 @@ leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이
|
||||
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
|
||||
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
|
||||
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
|
||||
가졌고 inbox도 같은 모양이었다(S7-#5b). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
|
||||
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
|
||||
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
|
||||
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
|
||||
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(MSG-023 §6.2), `messaging:*` leaf는
|
||||
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
|
||||
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
|
||||
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
|
||||
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
|
||||
|
||||
### Publish retryability of authentication and authorization (review 2026-11-01 06-01)
|
||||
### Publish retryability of authentication and authorization
|
||||
|
||||
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
|
||||
|
||||
@@ -63,7 +63,7 @@ registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길
|
||||
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
|
||||
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
|
||||
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(재리뷰 2026-11-03 RR-05-07).
|
||||
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
|
||||
|
||||
## Public surface 정책
|
||||
|
||||
@@ -95,7 +95,7 @@ RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium
|
||||
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
|
||||
qualification/support 상태를 함께 변경한다.
|
||||
|
||||
## application이 이 family에 도달하는 경로 (MSG-015, cutover 완료)
|
||||
## application이 이 family에 도달하는 경로 (cutover 완료)
|
||||
|
||||
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
|
||||
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
|
||||
@@ -110,7 +110,7 @@ lease/transport/outcome normalization/observation은 platform 중앙 publish pat
|
||||
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
|
||||
직접 보지 않는다.
|
||||
|
||||
**MSG-015 cutover는 끝났다(2026-09-28, 소유자 결정 7).** application의 outbox append는 canonical
|
||||
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
|
||||
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
|
||||
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
|
||||
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
|
||||
@@ -137,7 +137,7 @@ adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/
|
||||
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
|
||||
증거가 아니다.
|
||||
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
|
||||
Experimental에서도 금지다(MSG-022).
|
||||
Experimental에서도 금지다.
|
||||
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
|
||||
있을 때만.
|
||||
|
||||
|
||||
@@ -24,14 +24,14 @@ envelope shape, metric cardinality bounds, tracing seam, domain-context propagat
|
||||
- Tracing contract types (`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C
|
||||
`traceparent` value type and the span-error-recording seam (feature-distributed-tracing-contract; the OTel
|
||||
tracer runtime is a fork-activated seam, so these stay Java-stdlib-only).
|
||||
- Stdlib helpers every leaf used to copy (review X2-P1-5, X2-P1-4b, X1-#9): `digest/Sha256` (the
|
||||
- Stdlib helpers every leaf used to copy (moved here in the 2026-09-25 review follow-up): `digest/Sha256` (the
|
||||
SHA-256 digest value and the one `MessageDigest.getInstance("SHA-256")`), `digest/HmacSha256`
|
||||
(sign and constant-time verify), `retry/Backoff` (capped exponential ceiling; "full jitter" means
|
||||
`U[0, ceiling]` and nothing else). Vendored `messaging:*` and the optional gRPC build do not depend
|
||||
on this module and keep their own copies; each family's CLAUDE.md says why (a different product,
|
||||
MSG-023). Every template leaf that needs one of these has the `shared-contract` edge and uses them
|
||||
decided after the 2026-08-14 messaging module review). Every template leaf that needs one of these has the `shared-contract` edge and uses them
|
||||
instead of copying: identifier, persistence-mongo, application-objectstorage and redis-sdk took the
|
||||
edge for exactly this (review 2026-11-01 01-11, decision in the review README §15), each with a test
|
||||
edge for exactly this (decided 2026-11-03), each with a test
|
||||
that pins its output to a vector computed outside the JVM.
|
||||
- `observability/MdcKeys`: the snake_case MDC key names (registry `docs/registries/mdc-keys.yaml`)
|
||||
every transport puts a request's correlation under — web, GraphQL, STOMP and gRPC alike.
|
||||
|
||||
Reference in New Issue
Block a user