e742e479213dfce41306babf2961ba6a4a01f08c
10
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d904d680af |
fix(scripts): 검사 스크립트와 smoke wrapper의 빈틈을 닫고 자기 시험을 더한다
문제: - README 「새 서비스로 시작하기」의 이름 바꾸기 명령(`git grep -l ... -- src scripts`)이 루트 build.gradle·build-logic의 group, config/spotbugs 목록, registry· API surface 스냅숏을 놓쳐, 따라 하면 qualityCheck와 surface 검사가 실패했다. - check-repo-layout.py의 HISTORY_PREFIXES가 없는 폴더 셋(superpowers, evidence, study)을 담고 docs/history·docs/design을 빠뜨렸다. 검사 스크립트 머리말에 누가 부르는지 없었고, check-repo-layout·check-review-index·verify-httpclient-docs에 자기 시험이 없었다. check-docs.py docstring은 「검사 여섯」(여덟), check-work-docs.py는 lychee를 PR workflow라 했다(main). - run-compose-runtime-smoke.sh가 lane마다 정적 계약 전체를 다시 돌려 nightly마다 compose config를 수백 번 렌더링했다. handoff lane의 --force-recreate가 1단계 재시작 수를 지웠고, ps가 빈 결과면 restarts.txt가 비어 재시작 검사가 통과했다. 고친 것: - 이름 바꾸기 명령을 그 범위로 넓히고 build-logic 자기 패키지는 그대로 둬도 된다고 적었다. - HISTORY_PREFIXES를 지금 기록 폴더 넷으로, 머리말에 부르는 곳, docstring 숫자· workflow를 고쳤다. 자기 시험 셋을 더했다(scripts/tests 통과, 옛 목록이면 HISTORY_PREFIXES 시험이 실패한다). - smoke는 정적 계약을 실행마다 한 번(두 모드 공통) 돌린다. 재시작 수는 record_restarts가 단계(phase1, final)를 붙여 쌓고, 살핀 컨테이너가 없거나 inspect·기록이 실패하면 실패한다(호출이 `|| return 1`이라 함수 안 set -e가 꺼진다). - verify-httpclient-docs 자기 시험은 실제 트리 대조(release workflow의 검사)를 하지 않고 누락 탐지만 본다. scripts/tests는 PR 단계에서 돈다. Refs: RR9-04-04, RR9-04-17, RR9-04-18, RR9-04-26, RR9-04-27 |
||
|
|
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
|
||
|
|
4d778c2293 |
Merge remote-tracking branch 'origin/main' into claude/t2a-backend-ci-451e3b
메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은 이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길 측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로 두고 CI 절을 3.10(B-60~B-66)으로 미룬다. |
||
|
|
d46bab9659 |
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로 나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations· TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸 모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는 한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절). 소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다. - .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와 `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities` (trivy), 필수 검사 하나 `done`. - main.yml: push마다 mainCheck·integrationCheck·build-logic 시험· configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서 PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos, jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck. - release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea 레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명 앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은 `needs: jpa-release-gate`가 대신한다. - 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 + 저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다. - verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의 계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로 바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에 선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른 run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는 needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른 working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job 하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다 (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를 TestKit 시험으로 둔다. - scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업 트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의 손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트 포워더·configuration cache 스크립트다. - workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을 .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다. - 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조, docs/upgrade B-57~B-61. 버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수 없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기 (결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다. 위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지 않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를 다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다. `.github/workflows/messaging-certification.yml`은 메시징 분리 작업이 지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이 없어 실제 태그로는 돌려 보지 않았다. BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법, 릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity- review.md B-57~B-61을 따른다. |
||
|
|
5af9415587 |
refactor(platforms)!: 메시징 플랫폼을 messaging-library 1.0.0으로 받고 지운다
템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).
- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
composition:outbox-relay와 app-bootstrap architectureTest. import와
auto-configuration 이름 문자열 dev.caskeleton.messaging →
dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
(../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
의존성 집합은 그대로, 설계 16절 H6).
버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).
위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).
검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.
BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).
Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
|
||
|
|
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단계 |
||
|
|
67ecae2cc2 |
feat(skills)!: 새 기능과 desktop 게이트 절차를 모델이 부르는 스킬로 둔다
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을 할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야 하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가 2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고 설명에 발동 조건을 문단으로 적기로 정했다(design-docs harness/01-harness-design.md 5.5절, 13절 Q9·Q18). - .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의 실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터 → 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트). - .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행 순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc → 테스트 수 → 잠금 대기 → 정리 → 보고 칸). - 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은 327자·268자로 목록 상한(1,536자) 안이다. - 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다. - test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본 가리키기, skills-lock.json 없음)을 더했다. 버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함), verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편 몫이라 여기서는 만들지 않는다). 위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른 스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다. 검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아 고쳤다), check-work-docs, check-repo-layout 모두 rc=0. BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/ 2026-11-harness.md 2절 6행. |
||
|
|
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행. |
||
|
|
6fa4f825f2 |
ci(links): 기록 안의 죽은 외부 링크 넷을 lychee 제외 목록에 둔다
문제: lychee가 기록 문서 안의 외부 링크 404 넷으로 실패한다(mongodb write-concern, aws credentials-chain `.html/`, aws SES SendEmail `.html/`, spring-graphql 1.3 request-execution). 넷 모두 `docs/design`·`docs/reviews` 안에 있고, 기록 본문은 고치지 않는다. 고른 방법: 저장소 루트에 `.lycheeignore`를 두고 그 네 URL만 `^…$`로 묶은 정규식으로 뺀다. lychee는 실행 위치의 `.lycheeignore`를 읽으므로 workflow를 고치지 않아도 된다. `scripts/check-repo-layout.py` 허용 목록에 이 파일을 더한다. 버린 대안: - `lychee.toml`의 `exclude_path`로 기록 폴더를 통째로 빼기. 기록 안 상대 링크까지 검사에서 빠진다. - workflow에 `--exclude` 인자 더하기. workflow는 CI 재편 작업이 고친다. 위험·한계: 같은 URL을 살아 있는 문서가 쓰면 거기서도 검사하지 않는다. 끝의 `/`가 없는 aws 두 URL은 살아 있어 빼지 않았다. 검증: `python3 scripts/check-repo-layout.py` rc=0. 정규식이 네 URL에만 맞고 `/` 없는 aws 두 URL에는 맞지 않는 것을 Python `re`로 확인했다. |
||
|
|
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(트리
|