cbfa776270a7b51ea5cc66a247998be0df1134cb
40
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
1185b36a6d |
test: 거짓 통과·흔들림·저장소 읽기 경로를 막도록 시험을 고친다
문제: - GraphQlDeploymentModeRegistryParityTest가 태그 없이 test에서 docs/registries/env-keys.yaml을 읽었다. 입력을 선언하지 않아 test 캐시가 registry 변경을 놓쳤고, modules.json을 거슬러 올라가 저장소 루트 가드를 우회했다(build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」). - 「값을 싣지 않는다」 단언 넷(WebSecurityContextBridgeTest, scalar 둘)이 예외 타입을 보지 않아, 메시지 null인 NPE로 바꿔도 통과했다. - FileserverAdminControllerRequestBodyValidationTest는 @RequestBody가 하나도 없는 controller에도 통과했다. - GraphQlRequestDeadlineTest가 sleep(500) 뒤에 하위 필드 부재를 단언했다. 부하에 따라 기다림이 짧으면 거짓 통과다. - 두 동작을 한 시험에서 보던 셋(표 입력 반복문, when 둘). 고친 것: - registry 대조 시험에 document-contract 태그를 달고 graphql leaf에 mainStage lane graphqlDocumentContractTest를 둔다(lane은 다음 커밋의 build.gradle에 있다. 그 파일의 다른 변경과 같이 간다). - 부재 단언에 예외 타입(CoercingParseValueException, UntrustedTenantInputException)을 먼저 둔다. - admin 시험은 @RequestBody 매개변수 목록을 고정한 뒤 @Valid를 본다. - deadline 시험은 slowNode 실행이 끝났다는 신호(Instrumentation beginExecution 완료, 세대 번호로 이전 시험의 늦은 완료를 거른다)를 기다린 뒤 부재를 본다. - 표 입력(scalar 넷의 부재 단언 포함)은 @ParameterizedTest로, 두 동작은 시험 둘로 나눴다. 고친 시험은 GWT와 catchThrowable로 when을 하나로 둔다. - decisions 2.1에 「시험 형식 일괄 전환 안 함」(리뷰 README 6절 ④) 행을 더했다. Refs: RR9-03-17, RR9-03-18, RR9-03-19, RR9-03-20, RR9-03-22 |
||
|
|
6a792b8144 |
refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
|
||
|
|
7dc5725fe7 |
docs!: 메시징 문서를 messaging-library로 보내고 관련 저장소 절을 채운다
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms 경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도 지운 docs/messaging/support-matrix.md를 가리킨다. - docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째 messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09, messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다. - 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만 고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱 쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md. - docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움), 라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때 composite build(Gradle 루트가 src/라 ../../messaging-library), registry 라이브러리 칸. 설계 14절이 근거다. - src/config/architecture/README.md: library_groups·allowed_libraries 설명. - docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는 법·패키지·auto-config 이름), B-59(registry 칸). - 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions, review-criteria, defect-patterns, gates, capability-status, manual 07, build-logic·persistence-jpa·inbound messaging·shared-contract 지침, env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo 라이브러리 문장으로 바꿨다. 위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개 repo라 익명으로 읽힌다). 검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크 깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s scripts/tests OK. BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는 messaging-library repo의 docs/messaging/에 있다. Refs: design-docs repo-structure/05-library-repos.md 4.3·14절 |
||
|
|
5e204e6a43 |
refactor(platforms)!: gRPC 플랫폼을 별도 repo grpc-library로 옮기고 지운다
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼 (src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드 (src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘, 카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다. 소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절, 05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다. gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13). 코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리 해시가 이 기준 커밋 22df3525와 같다). 지운 것: - src/platforms/grpc, grpc-advanced, optional-build(343파일) - registry의 "build": "optional-grpc" 9행 - ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs, integration-main.yml optional 성능 단계와 job grpc-optional-platform-integration, release.yml job grpc-stable-release-gate와 이미지 job의 needs 한 줄 - build-logic ca.grpc-platform-module·ca.optional-architecture-registry, MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의 optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다 - 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14: 채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄 - 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘, gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리 블록 「현재 정본」만 새 자리를 말하게 했다 - DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험, adopter API 표면 검사의 optional-build 제외 경로 남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원 (ModuleRegistry, 일반 기능). 살아 있는 문서: README, docs 지도, capability-status, work/delegate· gates·decisions(새 행 「라이브러리 repo」)·defect-patterns· review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로), manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석. 새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이 고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56. 위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다 (tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck, compose smoke, 빠른 시작). 문서 검사 셋 rc=0. BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:* 프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로 받는다(docs/upgrade/2026-11-maturity-review.md 3.8절). Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계 |
||
|
|
248df5180f | Merge remote-tracking branch 'origin/main' into claude/h3-backend-harness-34fc23 | ||
|
|
c8db79a78f |
docs(work): 쌓인 매뉴얼 빈틈과 조사 문서의 매뉴얼 규칙을 한 묶음으로 넣는다
cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이 「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에 없다. 세션마다 같은 판단을 스스로 다시 했다. 넣은 자리(항목별 표는 PR 본문): - delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드 연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌 없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로). - improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다, 그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로. - docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다, 이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml, 머리말 없는 runbook, MANIFEST는 납품 당시 해시). - operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1, 12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에. - reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패, lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음, 원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거 실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e), 새 7절 「workflow·검사 스크립트를 더할 때」. - reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함, Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사). - reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값. - reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻. - README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는 leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check· check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙. 버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음). 위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용, 병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로 상한에 가깝다. 검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0. |
||
|
|
3c73fc333c |
docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은 AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은 AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs harness/01-harness-design.md 13절 Q1·Q2·Q3). - AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증, 일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄. - 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새), 테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스), 계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새 src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 → src/composition/AGENTS.md(새), capability 규칙·완료 기준 → docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 → .claude/rules/settings-and-runtime.md, 문서 편집 규칙 → .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README 「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길· 작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다. - 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛 행에 취소선을 긋고 「지침 배치」 행을 더했다. - check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10), 진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지, .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다. - DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서 읽는다. 단언은 그대로다. 버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함), CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크. 위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로 읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다. 검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10), check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트 변경은 마지막 트리에서 desktop documentContractTest로 확인한다. BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로 옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행. |
||
|
|
6ad8f4b635 |
docs(persistence-jpa): README가 고친 버전 없는 Querydsl 좌표를 권하지 않게 한다
문제: persistence-jpa README 「라이브러리 API」가 Querydsl을 쓰는 서비스에
`com.querydsl:querydsl-jpa:5.1.0:jakarta`를 직접 추가하라고 한다. 그 좌표에는
HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있고 고친 버전이 없다.
8e3bef0f가 이 leaf를 querydsl-core로 옮겼는데, 살아 있는 문서는 아직 그
좌표를 권한다.
고친 방법: 총괄이 권한 안 A를 확인하고 이 문장도 고치라고 했다(2026-11-07).
문장을 넷으로 나눴다: 템플릿은 querydsl-core의 `Predicate`만 쓴다, JPA 질의가
필요한 서비스는 querydsl-jpa를 직접 더한다, 그 좌표 5.1.0에는 CVE-2024-49203이
있고 고친 버전이 없다, 쓰려면 OpenFeign 포크(`io.github.openfeign.querydsl`)를
검토한다. Envers 안내는 그대로다. 결정 색인 「Querydsl 취약 좌표」 행의 「누가」를
「총괄 확인 전」에서 위임(총괄 확인)으로 바꾸고 README를 출처에 더했다.
- 원래는 8e3bef0f와 같은 커밋이어야 했다. 그 커밋은 이미 push해서 고쳐 쓰지
않고 바로 뒤에 붙인다.
위험·한계: README 줄은 문서 번역 작업(D2b) 범위 안이다. 총괄이 D2b에 이 줄을
건드리지 말라고 알린다.
검증(desktop, 이 커밋과 다음 커밋을 얹은 트리
|
||
|
|
cb67b8792d |
docs: 의존성 취약점 수정의 업그레이드 안내와 결정 색인 행을 더한다
문제: 앞 커밋 아홉 개가 파생 서비스가 받는 버전을 바꿨다(Spring Boot 4.0.9, gRPC 1.75.0, httpclient5·httpcore5, 새 `pinned-*` 고정, Querydsl 컴파일 의존, lockfile 옛 줄). 업그레이드 안내에 행이 없으면 파생 서비스는 merge 때 lockfile 충돌과 httpcore5의 새 응답 헤더 상한을 미리 알 수 없다. 버전을 고르는 규칙과 Querydsl 처리도 결정 색인에 없어 다음 세션이 다시 묻는다. 고친 방법: - `docs/upgrade/2026-11-maturity-review.md`: 새 3.7절과 B-54 행(무엇이 바뀌었나, 증상, 할 일, 근거 커밋). 이 안내는 아직 main에 합쳐지지 않았으므로 결정 색인 「아직 합치지 않은 업그레이드 안내」대로 머리 「커밋:」 목록에 한 항목을 더했다. - `docs/work/reference/decisions.md` 2.7절: 「취약점이 있는 의존성 버전」(고르는 순서와 놓는 곳)과 「Querydsl 취약 좌표」 두 행. 둘 다 기본값이고, Querydsl은 총괄 확인 전이라고 적었다. - `docs/web/repository-adaptation.md:65`: baseline 숫자 4.0.8→4.0.9만 고쳤다. 같은 숫자가 있는 다른 살아 있는 문서 8곳은 `scripts/check-docs-exceptions.txt`의 number 예외로 얼어 있어 고치지 않았다(고치면 문서 검사가 실패하고, 예외 파일은 이 작업의 범위 밖이다). 위험·한계: 위 8곳은 Boot 4.0.8로 남는다. 번역 작업이 그 문서를 옮길 때 숫자를 정본(카탈로그)을 가리키는 말로 바꾸고 예외 줄을 지워야 한다. 검증: `python3 scripts/check-docs.py` rc=0(number 걸림 28, 예외 28, 실패 0), `python3 scripts/check-work-docs.py` rc=0. 고친 세 문서를 읽는 테스트는 없다 (`grep -rn --include='*.java'`로 파일 이름을 찾았다). |
||
|
|
ae54f312a0 |
docs(work): 저장소 정리 결정 중 색인에 없던 행을 더한다
문제: 소유자가 2026-11-07에 정한 저장소 정리 결정(design-docs `repo-structure/README.md` 3.1·3.2절) 중 문서 체계 결정이 결정 색인에 없다. 배치 결정 중 「업무 기능 하나가 끝까지 도는 별도 fixture를 두지 않는다」도 없다. 색인에 없으면 다음 세션이 이미 정한 것을 다시 묻는다. 고친 방법: 없는 결정만 「소유자」, 2026-11-07, 출처 3.1·3.2절로 더한다. - 2.1 작업 방식: 문서 체계, 한국어의 범위(상태 어휘 포함), 문서 검사, 학습 문서(지금 결정. 「학습 문서(지난 것)」 행은 그대로 둔다), 문서 규칙 정본, 레지스트리 yaml 설명 칸, 짝 프론트 적용 시점, README 필수 절. 비슷한 두 결정(목표 구조와 폴더 이름, 한국어 범위와 상태 어휘)은 한 행에 묶었다. - 2.2 구조·조립: 기능 끝까지 도는 fixture. 3.3절(CI·스크립트) 결정은 CI 재편 작업에 남긴다. 검증: check-work-docs.py rc=0(이력 ID 0), check-docs.py rc=0. |
||
|
|
8251616767 |
fix(docs): 지우고 옮긴 경로에 문서 검사 예외와 참조를 맞춘다
문제: 구조 정리와 문서 체계를 합친 트리에서 `python3 scripts/check-docs.py`가 23건으로 실패한다. 문서 검사는 구조 정리 전 트리를 기준선으로 만들어졌다. - 예외 목록이 지운 파일(infra 아래 README 6개, 샘플 CLAUDE.md의 언어·숫자 두 줄)을 가리킨다. - 옮긴 문서 넷(infra/keycloak, infra/redis-sdk, infra/redis-sdk/acl, src/optional-platforms의 README)은 옛 예외 줄이 낡고 새 경로가 영어 문서로 걸린다. - `docs/jpa/security.md`는 구조 정리가 한국어 절(운영 DB 조건)을 더해 더는 영어 문서로 판정되지 않는다. - 살아 있는 문서 넷이 지운 `infra/`, `src/sample-portfolio`, `src/Dockerfile.sample`을 인라인 코드로 가리킨다. 고친 방법: 문서 체계 인계 노트의 「구조 정리와 합칠 때」를 따른다. - 지운 파일과 더는 걸리지 않는 줄 아홉은 예외 목록에서 지운다. - 옮긴 문서 넷은 예외 줄의 경로를 새 경로로 바꾸고, FROZEN에서 옛 줄의 지문을 새 줄의 지문으로 바꾼다. FROZEN에 새로 더한 지문은 없다. - 결정 색인의 두 행은 지운 경로 대신 지운 목록이 있는 업그레이드 안내 B-49·B-50을 가리킨다(docs/README.md 「지운 경로는 upgrade/에 쓴다」). - JPA 적응 표의 「저장소 현실」 칸과 리뷰 기준 18행에서 지운 경로를 뺀다. - docs/README.md의 검사 설명은 지운 infra 폴더를 인라인 코드 밖에서 적는다. 검사는 지운 infra/ 아래 경로를 계속 본다(다시 나타나면 낡은 참조다). 버린 대안: 결정 색인을 참조 검사 제외 목록(HISTORY_HOLDERS)에 넣기. 색인은 지금 결정을 찾는 곳이라 낡은 경로를 걸러야 한다. 위험·한계: `docs/jpa/security.md`는 영어 본문이 그대로 남아 있지만 판정에서 빠졌다. 번역 단계의 대상 목록에서 빠지지 않게 인계 노트에 적는다. 검증(노트북, 이 트리): check-docs.py rc=0(언어 걸림 173·예외 173, 참조 걸림 7· 예외 7, 숫자 걸림 28·예외 28), `python3 -m unittest discover -s scripts/tests` 42개 통과, check-work-docs.py rc=0. |
||
|
|
268bfdd1d8 |
Merge remote-tracking branch 'origin/claude/d1-docs-system-fd4a0f' into claude/i1-layout-docs-merge-217f1e
# Conflicts: # docs/ci-cd/template-vs-consumer.md # src/platforms/grpc/CLAUDE.md |
||
|
|
e13a29024f |
ci(repo)!: 최상위 폴더 허용 목록 검사를 더한다
문제: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이
여덟으로 늘었고, 루트에는 compose 파일과 infra/가 쌓였다. 어느 커밋도
최상위 모양을 묻지 않았고 리뷰 기준에도 그 칸이 없었다.
고른 방법(소유자 결정 2026-11-07, 설계 10.3절): scripts/check-repo-layout.py
- 저장소 루트와 src/ 바로 아래의 추적 항목이 허용 목록 안에 있는가
- registry source_path가 허용된 src/ 폴더 아래인가
- (경고) compose·스크립트·compose 보조 파일을 아무 추적 파일도 가리키지
않는가
를 본다. ci-quality-gates.yml quality-gates job에 한 단계로 붙인다.
Gradle 밖 스크립트다(문서·배치를 파싱하는 Gradle 검사를 두지 않는 정책).
버린 대안: registry에서 허용 폴더를 파생하기. 새 vendored 폴더를 registry
에 등록하는 것만으로 통과해, 막으려는 drift를 막지 못한다.
위험·한계: 참조 0 경고는 경로를 변수로 조립하는 workflow를 따라가지
못해 경고로만 둔다. 리뷰 기준·playbook 문장은 매뉴얼 보강 작업이 넣는다.
검증:
- 노트북·desktop: python3 scripts/check-repo-layout.py rc=0, 경고 0
- 일부러 infra/, src/messaging/, 고아 compose/orphan.sh를 둔 임시 저장소:
rc=1, 실패 3건과 경고 1건
- desktop(트리
|
||
|
|
8d69e599a3 |
refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.
고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).
위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.
검증(desktop, 트리
|
||
|
|
50cd7154d0 |
refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
.local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.
고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).
위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
(YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
lane-services.yaml(smoke client 변수)은 뺀다.
검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친
|
||
|
|
a025f244c7 |
refactor(repo)!: 쓰지 않는 파일과 운영 인프라 파일을 지운다
문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.
고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.
위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.
검증(desktop, 트리
|
||
|
|
ab5982e955 |
refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리
|
||
|
|
630f9b860a |
docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.
고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
→ docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.
옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.
위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.
검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
|
||
|
|
07f7c3054d |
docs(work): 소유자가 확인한 기본값 행의 「누가」를 소유자로 바꾼다
문제: 결정 색인 2.1·2.3·2.4·2.7절의 기본값 행 아홉(커밋 단위, 넘어온
「범위 밖」 항목, desktop 도구 설치, 약속한 응답으로 맞추기, 검사를 더
엄하게 하는 수정, 아직 합치지 않은 업그레이드 안내, 라운드 끝 태그 단계
범위, 넘겨받기 전 핸들의 재전송 적용 조건, GraphQL 로그 줄)은 「누가」가
"기본값"이라 소유자 확인 대상으로 읽힌다. 소유자가 2026-11-07 round8
수정 묶음을 합치기로 하며 이 기본값들을 확인했다.
고른 방법: 「누가」 칸만 "소유자(2026-11-07, 기본값 확인)"로 바꾼다.
결정 내용과 출처는 그대로 둔다. 기본값에서 나왔다는 것을 칸에 남겨 출처를
따라갈 수 있게 한다.
위험·한계: brief가 이름으로 든 행은 여덟이다. 「GraphQL 판정 순서」의
"로그 줄은 기본값"(r9-g1 `e1fb049b`의 기본값)은 brief가 소유자가 확인했다고
적은 수정 세션 기본값 다섯 중 하나라 같이 바꿨다. 리뷰 README 19.7절이 그
기본값을 "소유자 확인"으로 적어, 바꾸지 않으면 두 문서가 다르다. 옛 칸에
있던 괄호 설명("옛 '묶음마다 커밋 하나'를 정본에 맞춤", "소유자 기계를
바꾸는 일")은 지웠다. 같은 이유가 출처(evidence.md 11절, operate.md
4.1절)에 있다.
검증: python3 scripts/check-work-docs.py rc=0. 이 파일을 읽는 테스트는
없다(grep -rln 'decisions.md' src --include='*.java' 결과 0건).
|
||
|
|
c79d4259a9 |
Merge remote-tracking branch 'origin/claude/r9-g4-idempotency-c669be' into claude/integration-r9-f1bc5c
충돌 하나를 정리했다. - docs/upgrade/2026-11-maturity-review.md 머리 「커밋:」 줄: 앞서 합친 G3·G1·G2 항목을 두고, G4의 「멱등 저장소의 markFailed 재전송 인자와 renew 뒤 start」를 끝에 더했다(G4가 둔 자리도 끝이다). decisions.md와 application-core README는 G1·G4가 서로 다른 행·문단을 고쳐 자동 병합됐다. 두 브랜치가 더한 줄이 모두 남은 것을 diff로 봤다. |
||
|
|
ee5b4e1b7e |
fix(inbound): 인자 변환 실패는 원인의 carrier와 상관없이 거부로 본다
문제(round8 리뷰 01 「Declined to judge」, 리뷰 README 19.4절 ④): - 결정 「감싼 carrier를 전송이 읽는 법」이 인자 변환 단계까지 덮는지 정해지지 않았다. STOMP advice는 @DestinationVariable·@Header의 ConversionFailedException과 받은 메시지가 실린 MessageConversionException의 원인에 carrier가 있으면 거부 WARN 한 줄 대신 그 carrier의 줄(5xx면 ERROR와 예외)을 남긴다. web은 같은 실패에 원인을 보지 않고 BAD_PARAMETER·VALIDATION_FAILED로 답한다. 고른 방법(소유자 결정 2026-11-07, ④ (a)): - 인자 변환 단계는 carrier를 보지 않는다. StompHandlerFailureLog가 거부 판정(clientRefusalOf)을 원인 사슬의 carrier 검색보다 먼저 한다. 응답 프레임은 그대로다(handler 경로는 프레임을 보내지 않는다). - web은 지금 동작이 결정과 같아 코드를 바꾸지 않았다. 경로 변수 변환기와 Jackson creator가 carrier를 던지는 지킴 테스트 둘을 더하고, handleTypeMismatch·handleHttpMessageNotReadable Javadoc에 이유를 적었다. - GraphQL @Argument binder는 변환기가 던진 실패를 binding result에 담고 BindException의 원인으로 싣지 않아, carrier를 던져도 BAD_PARAMETER다. 실제 binder 경로 지킴 테스트 하나와 매퍼 Javadoc·README 한 줄. - 버린 안: (b) 세 전송의 변환 단계가 원인의 carrier를 먼저 본다 — 요청 형식 오류의 코드가 변환기 구현에 따라 바뀐다. 위험·한계: - 바뀌는 것은 STOMP 로그 줄뿐이다. 템플릿에는 carrier를 던지는 변환기가 없다. 안내 B-46에 적었다. - GraphQL 지킴 테스트는 Spring for GraphQL 2.0.5 binder의 동작에 기댄다. binder가 원인을 싣게 바뀌면 그 테스트가 실패한다. 검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/): - RED(기준 |
||
|
|
e1fb049b64 |
fix(graphql): 등록한 실패는 원인의 carrier보다 등록한 코드로 답한다
문제(round8 확인 리뷰 RR8-01-01, 회귀): - GraphQL 매퍼가 원인 사슬의 첫 carrier를 앱이 등록한 매핑보다 먼저 본다. 앱이 GraphQlExceptionResolver에 등록한 실패가 하위 실패(예: PersistenceFailureException)를 원인으로 들면 등록한 코드 대신 carrier 코드로 답한다(ORDER_UNAVAILABLE 대신 DB_UNAVAILABLE). r8-f1 전에는 등록한 코드였다. 소유자 결정 「감싼 carrier를 전송이 읽는 법」은 "바뀌는 응답은 500 INTERNAL_ERROR이던 경우뿐"을 전제로 했다. 고른 방법(소유자 결정 2026-11-07, 리뷰 README 19.4절 ① (a)): - 판정 순서를 플랫폼 거부 → 실패 자신이 carrier → 등록된 application 매핑 → 원인 사슬의 첫 carrier → 거부된 인자 → 가림으로 바꾼다. sharedCodeOf는 실패 자신이 carrier가 아니고 등록 매핑이 있으면 원인 사슬을 보지 않는다. web에서 앱의 도메인 advice가 먼저 받는 것과 같다. - 로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier로 정한다(기본값). 등록 매핑이 답해도 그 안의 서버 쪽 carrier는 그 줄(persistence는 분류 한 줄)을 남긴다. 버린 안: 등록 매핑이 답하면 아무 줄도 남기지 않기 (r8-f1 전 동작) — DB 장애의 흔적이 사라진다. - 버린 안: (b) 지금 순서를 두고 문서에 적기 — 앱에 원인 버리기를 강요하고 web과 계속 다르다. (c) 등록 매핑을 실패 자신이 carrier인 경우보다도 먼저 — r8-f1 전에도 없던 변화라 범위가 넓다. - 같은 내용을 GraphQL README·CLAUDE.md, GraphQlExceptionResolver· ApiErrorCarrier.firstIn Javadoc, shared-contract README, 결정 색인, 업그레이드 안내 B-45·B-46에 적었다. 위험·한계: - 실패 자신이 carrier인 타입(예: LockAcquisitionTimeoutException)을 등록한 GraphQL 매핑은 계속 쓰이지 않는다. B-45와 resolver Javadoc에 적었다. - main 대비 GraphQL 응답은 바뀌지 않는다(r8-f1이 아직 main에 없다). 합치지 않은 안내 행 B-45·B-46만 최종 동작으로 고쳤다. 검증(desktop, flock /tmp/claude-gates/heavy.lock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/): - RED(기준 |
||
|
|
7535a4ca7a |
fix(idempotency)!: 적용한 핸들의 재전송을 전이 종류와 인자로 가린다
문제: 전이를 적용한 핸들이 그 전이를 다시 보낼 때 세 저장소가 서로, 그리고 포트 Javadoc과 다르게 답한다(재리뷰 round8 RR8-04-01·02, 같은 원인). - markFailed를 다른 disposition으로 다시 보내면 fake·Redis·PostgreSQL 모두 NOT_OWNER다. 기록을 남이 가져갔다는 틀린 신호이고 Javadoc은 OPERATION_CONFLICT라고 적는다. - retention만 다르면 fake·Redis는 ALREADY_MARKED_SAME_OPERATION, PostgreSQL은 fail digest에 retention이 들어 있어 OPERATION_CONFLICT다. - Redis는 start가 돌려준 핸들로 renew한 뒤 그 핸들로 start를 보내면 ALREADY_STARTED_SAME_OPERATION으로 답한다. renew도 기록을 EXECUTING· revision+1로 두어 TRANSITION이 상태와 revision만으로는 start와 구별하지 못한다. executor는 그 답에 action을 실행해 이미 도는 작업을 한 번 더 돌린다. fake·PostgreSQL은 NOT_OWNER다. 원인은 하나다. "적용한 핸들"을 revision 하나로만 가리고 전이 종류와 인자를 같이 보지 않는다. 방법: 소유자 결정(2026-11-07, 1103 README 19.4절 ② (a))대로 다른 disposition은 OPERATION_CONFLICT, 다른 retention은 "이미 처리됨"으로 맞춘다. retention은 complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐이라 비교하지 않는다. - Redis: 기록 hash에 lastKind(CLAIM·START·RENEW·COMPLETE·FAIL)를 남긴다. TRANSITION의 재전송 판정은 "rev == 핸들 rev + 1 그리고 lastKind == 이 전이"다. 그 안에서 상태가 목표면 ALREADY, 아니면(다른 disposition의 실패) OPERATION_CONFLICT. claim·takeover는 CLAIM을 써 넘겨받기 전 종류가 남지 않게 한다. 어댑터가 전이 종류를 9번째 인자로 보낸다. 명령 fake를 같이 고친다. - PostgreSQL: fail 재생 판정이 두 실패 종류(FAIL_RETRYABLE·FAIL_ABANDONED)를 모두 실패의 재생으로 읽는다. fail digest에서 retention을 뺀다. - fake: 적용한 핸들의 markFailed 재전송에 disposition이 다르면 OPERATION_CONFLICT. - 공유 계약 IdempotencyStoreContract에 케이스 셋(다른 retention, 다른 disposition과 기록 유지, renew 뒤 같은 핸들의 start)을 더했다. - PostgreSqlIdempotencyIntegrationTest의 "다른 retention은 conflict" 케이스가 옛 동작을 고정하고 있어 결정대로 "이미 처리됨, 처음 retention 유지"로 바꿨다(...IsConfirmedAndKeepsItsRetention). IdempotencyFailOutcome·IdempotencyStartOutcome·IdempotencyStorePort Javadoc, 결정 색인 2.4절(새 행과 「넘겨받기 전 핸들의 재전송」 적용 조건), application-core CLAUDE.md·README, cache-redis·persistence-jpa README, TESTING_STRATEGY, 업그레이드 안내 5절 행을 같이 고쳤다. 버린 대안: 다른 disposition을 NOT_OWNER로 두고 Javadoc만 고치기(19.4절 ② (b), 소유자가 고르지 않음, 적용한 핸들에 "넘겨받혔다"는 틀린 신호), 다른 retention도 OPERATION_CONFLICT(② (c), Redis 기록에 retention을 더하고 Lua를 바꿔야 하며 보관 기간을 인자로 본다), Redis start 분기만 "renewedFromRev가 있으면 ALREADY 아님"으로 막기(같은 상태에 머무는 전이가 늘면 다시 갈라진다). 위험·한계: 템플릿 호출자(IdempotencyExecutor)는 같은 인자로만 다시 보내고 renew를 부르지 않아 HTTP 동작은 같다. 포트를 직접 부르는 코드만 답이 바뀐다. 이 배포 전에 쓰인 Redis 기록에는 lastKind가 없어, 새 프로그램이 그 기록의 전이를 재전송으로 보지 않는다. 핸들은 프로세스 메모리에만 있고 같은 프로세스는 같은 프로그램을 돌리므로, 새 프로그램이 옛 프로그램이 적용한 전이의 핸들을 받는 경로는 템플릿에 없다고 본다(실행으로 확인하지 않음). PostgreSQL도 같은 이유로 옛 fail digest(retention 포함)와 새 digest를 같은 핸들로 비교하는 경로가 없다고 보고 digest VERSION을 올리지 않았다. 검증: desktop, 공유 잠금, --no-build-cache, 기준 |
||
|
|
3eb3b06755 |
docs(work): cold-read 시험 2회차 빈틈 52건을 매뉴얼에 반영한다
문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).
고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.
위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.
검증(트리
|
||
|
|
51230caf62 |
fix(scripts): 색인 절을 총괄이 쓰는 라운드의 색인 검사를 --extra-index로 한다
문제: 독립 리뷰어 둘이나 여러 리뷰 세션이 한 라운드를 나눠 보면, 정본 리뷰어는
영역 문서를 리뷰 폴더에 커밋하지만 README 색인 절은 총괄이 쓴다. 그래서 정본
리뷰어가 커밋한 트리의 색인 검사는 반드시 rc=1인데, improve.md는 리뷰어에게
rc=0을 요구했다(round8 발견 RR8-06-01). 두 규칙을 함께 지킬 수 없었다.
고른 방법: check-review-index.py에 --extra-index <파일>을 더했다. 리뷰어가
보고에 둔 색인 표 파일을 색인의 일부로 센다. improve.md 4.1절 7·8단계와 5절,
delegate.md 4.1절, 결정 색인 「리뷰 README 분담」에 쓰는 법을 적었다. 버린 안:
리뷰가 권한 "보고 표를 붙인 README 임시 사본" 절차 — 복사·붙이기 단계가 늘고
같은 대조를 손으로 한다. 정본 리뷰어가 README 색인 절을 먼저 쓰는 안 — 결정
「리뷰 README 분담」을 뒤집는다.
위험·한계: --extra-index는 넘긴 파일 전체를 색인으로 읽는다. 표만 담은 파일을
넘겨야 한다(노트 전체를 넘기면 본문에 나온 ID도 색인으로 센다). 매뉴얼에
"색인 표만 담은 파일"로 적었다.
검증(트리
|
||
|
|
6b253c6c75 |
docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리
|
||
|
|
c95869da9d |
Merge remote-tracking branch 'origin/claude/r8-f5-small-fixes-f40412' into claude/integration-r8-a4196a
# Conflicts: # docs/upgrade/2026-11-maturity-review.md |
||
|
|
91a708340f | Merge remote-tracking branch 'origin/claude/r8-f4-idempotency-3a6a0f' into claude/integration-r8-a4196a | ||
|
|
9a7c954303 | Merge remote-tracking branch 'origin/claude/r8-f1-transport-errors-b21ebf' into claude/integration-r8-a4196a | ||
|
|
ef8ef170e8 |
fix(inbound)!: Retry-After를 레지스트리대로 붙이고 GraphQL 인자 거부를 맞춘다
문제(r8-f1 보고의 범위 밖 1·2, 소유자 답 2026-11-07 "권하는 안대로"): - web RetryAfterAdvisor 표가 레지스트리 retry_after_seconds 칸의 미러인데 7개가 빠졌다(DB_UNAVAILABLE 5, DB_SERIALIZATION_FAILURE 1, DB_DEADLOCK 1, DB_IDLE_IN_TX_TIMEOUT 2, OUTBOX_PUBLISH_FAILED 30, JOB_EXECUTOR_REJECTED 5, JOB_TIMEOUT 10). 그래서 DB 일시 실패 응답에 Retry-After가 없다. 대조하는 테스트가 없었다: advisor 단위 테스트는 값을 코드마다 손으로 옮겼고, enum·레지스트리 대조 테스트는 category· status·retryable만 봤다. - GraphQL @Argument 값이 파라미터 타입으로 바뀌지 않으면 Spring 인자 binder가 BindException을 던지는데, 매퍼가 모르는 타입이라 INTERNAL_ERROR로 가리고 예외째 ERROR로 남긴다. 그 메시지에 rejected value [...]가 실린다. 고친 것: - RetryAfterAdvisor 표를 Map.ofEntries로 바꾸고 7개를 채웠다(Map.of는 10쌍이 상한). OperationalErrorRegistryContractTest(document-contract)에 OperationalError마다 RetryAfterAdvisor.retryAfterSeconds와 레지스트리 값이 같은지 보는 테스트를 더했다. 버린 안: advisor가 레지스트리를 런타임에 읽는 것 — web leaf가 저장소 파일을 읽게 되고 jar에 실리지 않는다. - GraphQlWireErrorMapper가 BindException을 IllegalArgumentException과 같은 "거부된 인자"로 본다: 등록된 매핑이 없으면 BAD_PARAMETER(REQUEST), 로그는 ServerFailureLog.refused의 WARN 한 줄(타입만). web이 바뀌지 않는 경로 변수에 답하는 것과 같다. - 결정 색인 2.3절에 두 결정과 STOMP 필수 header 누락을 ERROR로 두는 기본값(이유 포함)을 적었다. 업그레이드 안내 B-47·B-48. 위험·한계: - 응답이 바뀐다: DB 일시 실패 넷에 Retry-After가 생기고, GraphQL 인자 변환 실패가 INTERNAL_ERROR → BAD_PARAMETER. - 대조 테스트는 OperationalError 코드만 본다. 다른 leaf의 코드는 RetryAfterHint로 자기 값을 말한다(대조 대상 아님). - BindException은 binder가 인자 변환을 모아 던질 때만 온다. @Valid 검증(ConstraintViolationException)은 이 leaf에 Bean Validation이 없어 다루지 않았다. 검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/round2/): - RED( |
||
|
|
a490c20f3e |
fix(strict-lane)!: 태그 push·release로만 도는 workflow는 releaseCheck에만 센다
문제: verifyStrictLaneStages의 workflow 판독기는 `push: tags:`만 있거나
`release` trigger만 있는 workflow의 명령을 모든 단계의 실행으로 센다.
태그 push는 매 변경에 돌지 않는데, 그런 workflow에만 `:integrationCheck`
같은 단계를 두어도 검사가 통과한다(round7 05 「Declined to judge」 ①).
고른 방법: 소유자 결정(2026-11-07, "권하는 안대로", 리뷰 README 18.4절
(a))대로, 요청이나 경로 필터 없이 시작하는 trigger가 release 흐름뿐인
workflow — `release`, 또는 `branches`·`branches-ignore` 없이
`tags`·`tags-ignore`가 있는 `push` — 의 명령은 `:releaseCheck`에만
센다. 경로 필터 결정(2026-11-06)과 같은 원칙이다. 판독기는 trigger를
변경·release·경로 필터·요청 넷으로 나누고, workflow의 시작을 "매 변경 /
release 흐름만 / 돌지 않을 수 있음" 셋으로 낸다. release 흐름만인
workflow를 부르는 재사용 workflow도 같다. Invocation에 releaseFlowReason을
두고, whyNotExecuting(taskPath, buildDirectory)가 `:releaseCheck` 밖의
단계에 그 이유를 준다. 실패 메시지, AGENTS.md, src/README.md,
build-logic/README.md, 업그레이드 안내 B-36, 결정 색인 2.7절을 고쳤다.
버린 대안: 지금처럼 모든 단계에 세고 문서에 적는다 — 소유자가 위 안을
골랐다. release 단계 이름을 빌드 설정(`strictLaneStages`)으로 받는다 —
결정이 `releaseCheck`를 이름으로 정했고, 파생 서비스 설정 표면이 늘어
판독기 상수로 두었다.
위험·한계: 파생 서비스가 `releaseCheck`가 아닌 단계를 태그·release
workflow에서만 돌리면 이제 verifyStrictLaneStages --dry-run이 실패한다.
이 repo의 release.yml은 `-p optional-platforms integrationCheck`도
돌리지만 integration-main.yml(main push·nightly)이 같은 단계를 돌려
판정이 그대로다(두 빌드 확인). release의 `types`는 보지 않는다.
`branches`와 `tags`를 함께 둔 push는 지금처럼 모든 단계에 센다.
검증(desktop, 로그 ~/r8-f5b-logs/):
- RED: 기준 ac3c6a81에 테스트만 얹음. 68건 중 2건 실패 —
WorkflowGradleInvocationsTest(세 workflow의 :integrationCheck가
실행으로 셈), StrictLaneStagesFunctionalTest(UnexpectedBuildSuccess,
"every strict lane is in an executed stage")
(red-release-flow.log, TEST-*.xml)
- GREEN: 같은 두 클래스 46건·22건 실패 0 (green-release-flow.log)
- -p build-logic check javadoc rc=0(build-logic 테스트 173건 실패 0),
:verifyStrictLaneStages --dry-run, -p optional-platforms
:verifyStrictLaneStages --dry-run rc=0(둘 다 "every strict lane is in
an executed stage"), check-work-docs.py와 상대 링크 검사 rc=0
(summary.txt)
Refs: docs/reviews/2026-11-03-rereview/README.md 18.4절(
|
||
|
|
1443510638 |
fix(idempotency)!: 이미 적용된 전이는 그 전이를 적용한 핸들에게만 확인한다
문제: 이미 적용된 전이를 다시 보낸 호출에 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, 공유 잠금, 기준 |
||
|
|
b619c44298 |
docs(work): 세 경우의 확인 리뷰를 독립 리뷰어 둘로 하고 총괄이 합친다
문제: 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 검증은 다음 커밋의 트리로 했다(그 커밋 본문)
|
||
|
|
73d39212f5 |
docs(work): cold-read 시험 1회차의 빈틈과 모순을 매뉴얼에 반영한다
문제: 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: 바꾼 것을 패치로 기준 커밋
|
||
|
|
2c8a359d32 |
docs(work): 소유자 결정 네 건을 결정 색인에 적는다
round7 확인 리뷰와 멱등 저장소 수정(t5)이 소유자 결정 네 건을 남겼고, 소유자가 2026-11-06 모두 권하는 안으로 정했다. 다음 수정 묶음이 다시 묻지 않도록 결정 색인의 해당 절에 내용과 출처를 적는다. - 계약·오류: 네 전송이 원인 사슬의 첫 carrier를 본다 - 멱등성: 넘겨받기 전 핸들의 재전송은 적용한 핸들에게만 확인한다, 해제된 핸들의 start는 ABSENT와 NOT_OWNER를 둘 다 받는다 - 영속성: 실패한 동시 인덱스 마이그레이션은 그 버전의 실패 이력 행만 지우고 다시 배포한다 - 빌드·게이트: paths 필터 trigger만 있는 workflow는 단계 실행으로 세지 않는다 검증: scripts/check-work-docs.py rc=0. |
||
|
|
0fa01019d0 | Merge remote-tracking branch 'origin/claude/t5-idempotency-operation-id-9bd973' into claude/integration-r7 | ||
|
|
200019aa5c |
fix(idempotency)!: 두 멱등 저장소가 operation id·release·inspect에 같게 답한다
문제: 같은 호출에 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, 공유 잠금, 기준
|
||
|
|
e0beeca214 |
fix(error-codes)!: 레지스트리에서 log_level 칸을 지운다
문제: 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: 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다. |
||
|
|
06f520e667 |
docs(work): 성능 lane 단언 강제와 캐시 결과의 한계를 매뉴얼에 맞춘다
문제: 성능 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 |
||
|
|
63c63413d1 |
docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 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에서 돌린다 |