ci/dependency-cache-same-filesystem
31
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
309631e419 |
docs(config): 설정 파일의 사람이 읽는 설명 칸을 한국어로 옮긴다
문제: recipe 카탈로그(config/recipes/frontend-capability-recipes.json), runbook 등록(config/runbooks/runbooks.json), 규모 상한 (config/scale/feature-shape-ceilings.json), 짝 백엔드 pin의 `fact`, secret scan 허용 이유의 설명 칸이 영어다. 소유자 결정(2026-11-07): 레지스트리의 설명 칸은 번역하되 그 칸을 읽는 테스트를 먼저 찾는다. 고른 방법: 칸마다 읽는 코드를 찾아, 비었는지만 보거나 자유 문자열로 산출물에 복사하는 칸만 옮긴다. 키, 배열 길이, 순서, 식별자·상태·경로· 명령·숫자는 그대로다. - 옮기지 않은 칸: registry-baseline.json의 `trigger`·`compatibilityRole` (승인 파일이 그 사본의 digest를 고정한다), 승인·변경 증거 파일의 `reason`(쓴 때의 기록), benchmark-baseline.json의 승인 이유, feature-shape-ceilings의 `axes[].axis`(테스트가 영어 리터럴로 비교한다), 값이나 이름뿐인 칸. config/ci/는 정리 3단계·CI 세션 범위라 보지 않았다. 위험: scripts/drill-runbook.ts의 복구 확인 항목 이름은 아직 영어라 설정과 코드의 언어가 다르다. 비교하지는 않는다. 검증: 다섯 파일 모두 HEAD와 키 경로·순서·배열 길이가 같다. json-schema·runbook-contract·feature-shape-growth·backend-contract-pin 시험을 desktop에서 돌렸다. |
||
|
|
e3c8db48ae |
chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로 템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다. 참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록 7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트 참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은 비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을 하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다. 기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로 옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플 경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다. 레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약 기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능 539B, context 4B)을 다시 받았다. 위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은 수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에 공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는 플랫폼 코드에 남았다. 검증(desktop): check:types, lint, check:architecture, check:registries, check:ci, verify:documentation, test:unit, test:component, test:contract, test:integration, test:recipes, test:coverage(Risk coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual, test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76 checks), test:sample-removal SKIP, build, check:bundle. |
||
|
|
b8d53c9aae |
chore(review): 1105 성능·구조 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘. - 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가 `scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해 빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`, `tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다. 1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로 옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에 `scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면 `tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고, 임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로 실패한다. - `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정 브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01 |
||
|
|
45c9c4dc48 |
chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나. - 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`· `RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에 옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에 두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the answers from the backend table rows at the pin"이 "is both copied and listed in notCopied"로 실패한다. - pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*` 둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다. - `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게 푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts Refs: 1105/03-02, 1105/07-01 |
||
|
|
7af80859e5 | chore(review): 1105 브라우저 파일·캐시·저장소 조치 브랜치를 합친다 | ||
|
|
c6c37f395b |
fix(http): 백엔드 rate-limit 503 두 code를 쓰기 전 거절로 읽는다
문제 짝 백엔드 http-contract.md §4는 web 전용 code 넷을 적는다. 그중 503 RATE_LIMIT_UNAVAILABLE(저장소 응답 없음, retryable, Retry-After 있음)과 503 RATE_LIMIT_INCOMPATIBLE(제공자 불일치)이 답 표 사본에도 프론트 판정 표에도 없다. 그래서 이 503은 기능 분류기가 정하고, create:feature가 만든 쓰기의 분류기는 늘 MAYBE_APPLIED다. 아무 일도 일어나지 않은 저장이 결과 불명이 되고, NEVER 쓰기는 사실과 다른 "변경됨으로 확인"을 눌러야 폼이 풀린다(리뷰 실험 X4: 429는 NOT_APPLIED, 503 둘은 SERVER_FAILURE/MAYBE_APPLIED). pin은 §4를 대조했다고 적었지만 사본에는 REQUEST_TIMEOUT 한 행만 있었다. 고른 방법 백엔드 45d2a478을 읽기만 해서 code마다 판정했다. 두 code는 RateLimitInterceptor.preHandle이 false를 돌려주며 쓰고(Unavailable· Indeterminate → RATE_LIMIT_UNAVAILABLE, Incompatible → RATE_LIMIT_INCOMPATIBLE), main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다. preHandle이 false면 handler를 부르지 않으므로 둘 다 쓰기 전이다. 백엔드는 같은 키 재전송을 요구하지 않는다(멱등성 executor 전). 그래서 답 표 사본에 refusedBeforeWrite: true, sameKeyResend: false로 두 행을 더하고, 프론트 거절 표 REFUSED_BEFORE_WRITE에 status 503과 함께 더했다. pin 테스트의 "답 표대로 읽는다" 규칙이 그대로 NOT_APPLIED를 요구하고 양방향 대조가 두 표를 함께 지킨다. kind는 지금처럼 SERVER_FAILURE(action retry)이고, KEYED도 자동 재전송은 없다(같은 키를 요구하는 답은 503 IDEMPOTENCY_UNAVAILABLE 하나다). pin의 comparedOn을 §4를 다시 대조한 날짜로 올렸다. 계약 문서 4.1·6.1절과 매뉴얼 01·02의 5xx 행 수를 고쳤다. 버린 대안 생성기 분류기가 503을 code별로 보게 한다: 생성 기능에만 고쳐지고 손으로 쓴 Envelope operation은 그대로 남는다. 판정은 백엔드 답 표 한 곳이 정한다는 지금 규칙을 따랐다. 위험·한계 - 추론(실행 확인 안 함): Spring MVC는 비동기 처리(Callable·DeferredResult) 뒤 ASYNC 재디스패치에서도 interceptor의 preHandle을 다시 부르고, 이 interceptor는 dispatcher 종류를 보지 않는다. 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. 45d2a478에는 Envelope을 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). 계약 6.1절에 적었다. 백엔드에 넘길 요청: RateLimitInterceptor가 DispatcherType.REQUEST에서만 평가하게 한다. - fileserver-upload.ts는 같은 백엔드 답을 자기 표로 따로 판정한다(01 영역). 여기서는 바꾸지 않았다. - NOT_APPLIED가 되면서 IDEMPOTENT 쓰기는 이 503에 retryBudget 안에서 자동으로 다시 보낼 수 있게 됐다(503은 재시도 status다). 쓰기 전 거절이라 중복은 없다. RATE_LIMIT_INCOMPATIBLE은 백엔드가 retryable false로 보내지만 실행기는 status로 판단하므로 같은 답을 한 번 더 받을 수 있다. KEYED·NEVER는 자동 재전송이 없다. 검증 desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts tests/integration/http-execution-v3-envelope.test.ts Refs: 1105/03-02 |
||
|
|
dc7c95b005 |
fix(recipes): OIDC PKCE 레시피가 sessionStorage 키를 registry에서 가져온다
문제: OIDC PKCE session owner 레시피가 sign-in transaction의 sessionStorage 키를 글자 그대로 적는다 (`"ca-frontend:auth:v1:oidc-pkce-transaction"`). 주석은 `buildPhysicalKey(...)`라고 하지만 함수를 부르지 않는다. 템플릿의 다른 Web Storage 키는 모두 `src/contracts/storage-keys.ts` registry가 `APP_NAMESPACE`로 만들고, 어댑터가 직접 쓰는 키도 `backend: "external"` 행으로 둔다. 그래서 제품이 `APP_NAMESPACE`를 바꾸면(memento 설계가 예정한 일) 이 키만 `ca-frontend:`로 남고, registry는 앱이 쓰는 Web Storage 키 목록이 아니게 된다. registry로 로그아웃 때 지울 키를 정하는 제품은 버려진 sign-in의 verifier·state·nonce·돌아갈 경로를 지우지 못한다. 고른 방법: - registry에 `AUTH_REDIRECT_TRANSACTION` 행을 둔다. `scope: "auth"`, `name: "oidc-pkce-transaction"`, `backend: "external"`(pulse 키와 같은 모양, StoragePort는 거절), `ttl: "session"`. 물리 키는 지금 글자와 같다 (`ca-frontend:auth:v1:oidc-pkce-transaction`)라서 진행 중인 sign-in을 잃지 않는다. - 레시피의 `OIDC_PKCE_TRANSACTION_KEY`는 그 행의 `physicalKey`다. 매뉴얼의 복사 규칙(`../../src/` → `../`)이 새 import에도 그대로 맞는다. - 분류는 `opaque-cache`다. `sensitive-forbidden`은 "저장하지 않는다"는 뜻이고 backend가 disabled·forbidden이어야 해서 맞지 않는다. 이 값은 리다이렉트 한 번 동안 저장하는 것이 설계다. - FE-REG-STORAGE의 `orphanExemptRows`에 이 행을 더한다 (`config/contracts/registry-governance.json`). 이 행을 쓰는 곳은 레시피 하나뿐이고, 레시피는 제품이 지울 수 있다(test:optional-recipe-removal). 행은 registry로 지울 키를 정하는 제품을 위해 남는다. `AUTH_TOKEN`처럼 사용처 없이 선언만 하는 행이다. 빼지 않으면 `src`만 복사해 check:registries를 돌리는 `tests/unit/second-api-feature-registries.test.ts`가 "has no executable consumer"로 실패한다. 버린 대안: consumer 폴더에 `recipes`를 더하기. 레시피를 지운 사본(FE-GATE-020) 에서 다시 사용처가 사라진다. 버린 대안: registry에 새 분류(예: `session-transaction`)를 더하기. 계약 타입의 union과 registry 기준선의 허용 값이 함께 바뀌는데, 분류가 코드 동작을 바꾸는 곳은 `sensitive-forbidden` 검사뿐이라 얻는 것이 없다. 위험·한계: - `src/contracts/storage-keys.ts`에 행 하나가 더해진다(FE-REG-STORAGE additive). CHANGELOG [계약] 행이 필요하다. - 이미 레시피를 복사한 제품은 자기 복사본을 같은 diff로 고쳐야 키가 namespace를 따른다. - orphan 검사가 이 행을 보지 않는다. 레시피가 키를 registry에서 가져오는지는 `tests/recipes/oidc-pkce-session-owner.test.ts`가 본다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/storage-registry.test.ts tests/recipes/oidc-pkce-session-owner.test.ts - corepack pnpm check:registries (additive 행) - node scripts/run-vitest.ts run tests/unit/second-api-feature-registries.test.ts - corepack pnpm test:optional-recipe-removal Refs: 1105/05-01 |
||
|
|
f600e6b132 |
fix(contracts): 짝 백엔드 pin과 drift 검사가 생성기 템플릿 사실도 대조한다
문제: create:feature --with-create가 백엔드 생성기 템플릿의 사실 넷을 프론트 문자열로 옮겼다. 경로 복수형(scripts/new-feature.sh), 이름 상한 100 (__Feature__.java.tmpl NAME_MAX_LENGTH), 오류 code <FEATURE>_INVALID· _NOT_FOUND(__Feature__ErrorCode·ControllerTest 템플릿), 201과 검사 순서 (Controller·Create__Feature__UseCase 템플릿)다. 그러나 pin (config/contracts/backend-contract-pin.json)과 check:backend-contract-drift는 docs/web/http-contract.md(1105/07-01 뒤로는 그 문서의 표 사본과 답 표)만 본다. 백엔드가 템플릿을 바꾸면 생성 기능이 다른 경로·상한·code를 써도 아무 신호가 없다. 고른 방법: pin의 backend.scaffoldSources에 백엔드 템플릿 파일 여섯과 각 파일에서 옮긴 사실, 옮긴 프론트 위치(파일과 이름)를 적는다. drift 검사는 1105/07-01의 사본·답 표 대조와 종료 코드(0 일치, 1 어긋남, 2 비교 못 함)를 그대로 두고, pin 뒤 HEAD에서 이 파일들도 diff한다. 바뀐 파일마다 다시 볼 프론트 위치를 failures에 더해 exit 1한다. pin 단위 테스트는 각 항목의 프론트 이름이 실제로 그 파일에 있는지 본다. drift 단위 테스트는 07-01의 가짜 백엔드 fixture에 생성기 템플릿 파일 하나를 더하고, 그 파일이 바뀐 경우(exit 1, 프론트 위치 출력)와 pin이 이름 붙이지 않은 파일만 바뀐 경우(exit 0, "1 scaffold sources unchanged")를 더한다. 07-01의 경우들은 그대로다. 계약 문서 4.1절과 생성기 머리 주석에 같은 내용을 적었다. 버린 대안: 백엔드가 생성기 사실을 JSON으로 내고 프론트가 읽기 — 두 repo를 바꿔야 한다(백엔드는 이번에 읽기만 한다). 위험·한계: drift 검사는 여전히 게이트 밖이고 형제 checkout이 있을 때만 돈다. 파일 단위 diff라 템플릿의 무관한 줄이 바뀌어도 알린다(사람이 다시 본다). pin의 commit(45d2a478)은 그대로다. 네 사실이 그 커밋과 같다는 대조는 리뷰(1105/16 영역)가 했고 이번에는 이름 상한만 다시 읽었다. 07-01과 같은 파일을 고쳐서 fix/r1105-contracts-core-sq 위에 다시 쌓았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/backend-contract-drift.test.ts tests/unit/backend-contract-pin.test.ts corepack pnpm check:backend-contract-drift (desktop 형제 checkout 기준, 참고) Refs: 1105/16-02 |
||
|
|
daf3474252 |
fix(contracts): 짝 백엔드 답 표를 pin한 백엔드 표의 사본과 대조한다
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.
고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
`notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.
위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.
Refs: 1105/07-01
|
||
|
|
580be5839d |
docs(contracts): 짝 백엔드 계약 기준점을 45d2a478로 올린다
문제 check:backend-contract-drift가 백엔드 HEAD 45d2a478에서 http-contract.md §2 두 행의 설명 변경을 알린다. IDEMPOTENT_IN_FLIGHT(PostgreSQL 저장소는 409 대신 첫 요청이 끝날 때까지 기다림)와 IDEMPOTENCY_UNAVAILABLE(processing lease가 시작 전에 끝나 저장소가 시작을 거절함)이다. 같은 커밋이 6.1절이 인용하는 GlobalExceptionHandler와 IdempotencyExecutor도 고쳤다. 고른 방법 - 두 행의 code·status·retryable·재전송 규칙은 같다. 프론트 판정(처리 중 MAYBE_APPLIED·같은 키, UNAVAILABLE 실행 안 됨·같은 키 자동 재전송)은 바꾸지 않는다. - 6.1절이 인용하는 블록 13개를 두 판에서 대조했다. 내용은 모두 같고 GlobalExceptionHandler 4개, IdempotencyExecutor 1개의 줄 번호만 옮겼다. 인용한 다른 백엔드 파일 15개는 바뀌지 않았다. - pin, 답 표 JSON, 계약 문서 4.1·6·6.1절, CHANGELOG의 pin 행과 알려진 제한을 같이 고친다. 위험·한계 - PostgreSQL 저장소의 기다림이 프론트 totalDeadline보다 길면 응답 없는 끝(결과 불명, 키 유지)이 된다. 판정은 안전 쪽이다. - Fileserver 계약(docs/fileserver/http-contract.md)은 bbe944bd 이후 바뀌지 않았다. 검증 - check:backend-contract-drift --backend <백엔드 checkout>: pinned 45d2a478. - backend-contract-pin·changelog-review-ids 테스트 11건, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06 |
||
|
|
3b40f73638 |
fix(contracts)!: 스키마 메타의 boundary를 쓰임과 대조하고 실패 본문 행을 둔다
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(
|
||
|
|
5379c805ba |
docs(contracts): 짝 백엔드 계약 기준점을 c508b1ba로 올린다
문제 fix/r1103-http는 짝 백엔드 계약 pin을 bbe944bd에 두었다. 그 뒤 백엔드에 70fb80bf(늦게 끝난 멱등 실행 기록)와 c508b1ba(회복 필요 응답 안내)가 들어왔다. 새 `check:backend-contract-drift`가 §2의 500 IDEMPOTENCY_RECOVERY_REQUIRED 행 변경을 알린다. 전에는 "재전송도 재실행도 안전하지 않다"였고, 지금은 "자동 재시도하지 않는다. 같은 키 재전송은 안전하다"다. 고른 방법 - pin과 답 표 JSON의 기준을 c508b1ba 전체 SHA로 옮기고, IDEMPOTENCY_RECOVERY_REQUIRED의 sameKeyResend를 true로 바꾼다. - 프론트 판정은 바꾸지 않는다. 이 code는 이미 MAYBE_APPLIED이고 키를 붙들며 자동 재전송하지 않는다. 결과 불명 화면의 같은 키 재전송은 새 문장과 맞는다. - 6.1절이 인용하는 IdempotencyExecutor를 c508b1ba에서 다시 읽었다. 처리 중·불일치 판정은 그대로 action 전이고 줄 번호만 옮겼다 (127-130, 166-169, 267). 위험·한계 - c508b1ba에서는 §1·§2·§4와 IdempotencyExecutor만 다시 대조했다. 나머지 6.1절 파일은 bbe944bd 판독 그대로다(두 커밋 사이에 바뀌지 않았다). 검증 - check:backend-contract-drift --backend <백엔드 checkout>: pin과 HEAD가 같다. - tests/unit/backend-contract-pin.test.ts 10건, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06, README.md 10.6 |
||
|
|
6088f6e533 |
chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06 # Conflicts: # docs/manual/02-decision-tables.md |
||
|
|
ba2b4f4c6d |
feat(contracts): 짝 백엔드 계약 기준점을 기계가 읽는 pin과 답 표로 둔다
문제 짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 5786126c)뿐이고, 이 SHA를 읽는 코드·설정·테스트가 없다. 쓰기 전 거절 표 REFUSED_BEFORE_WRITE와 5xx 판정은 백엔드 http-contract.md §2를 손으로 옮긴 것이다. 리뷰 중 백엔드에 bbe944bd가 들어와 503 IDEMPOTENCY_COMPLETION_UNKNOWN이 새로 생겼는데 프론트의 어떤 검사도 알리지 않았다(README 10.6). 고른 방법 (결정 D6 (1)+(2)) - config/contracts/backend-contract-pin.json: repo, 전체 SHA(bbe944bd), 대조한 문서와 절(§1·§2·§4), 프론트 쪽 계약 절·판정 파일, 담당. - config/contracts/backend-idempotency-answers.json: 백엔드 §2 표 여섯 행과 §4 REQUEST_TIMEOUT을 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겼다. 백엔드가 문서에 적은 사실만 담는다. - tests/unit/backend-contract-pin.test.ts: 두 JSON의 모양과 같은 SHA를 확인하고, 답마다 프론트 판정이 그 두 열에서 나오는 값인지(쓰기 전 거절이면서 같은 키 재전송이 아니면 NOT_APPLIED, 아니면 MAYBE_APPLIED, 자동 재전송은 둘 다 참일 때만) 본다. 반대로 프론트 표의 행이 모두 이 답 표나 6.1절 읽기(VALIDATION_FAILED)로 뒷받침되는지 본다. 그래서 백엔드 표에 행이 늘거나 status가 바뀐 JSON을 넣으면 실패한다. - scripts/check-backend-contract-drift.ts(check:backend-contract-drift): 형제 디렉터리(또는 --backend)의 백엔드 checkout이 pin 뒤에 http-contract.md를 바꿨는지 알리고 바뀐 표 행을 보인다. CI에는 백엔드가 없어 게이트 밖이다. ungated-scripts.json에 이유를 적었다. - 계약 문서 4.1·6절의 기준 커밋을 bbe944bd와 pin 파일로 옮겼다. 6.1절 표는 5786126c..bbe944bd 사이 바뀐 백엔드 파일 다섯을 다시 읽었다. 판정은 같고 줄 번호만 옮겼다(IdempotencyExecutor, GlobalExceptionHandler → HttpStatusErrorCodes, FailureCategory, PersistenceExceptionTranslator). 버린 대안 - 백엔드 error-codes.yaml과 문서 다이제스트를 기록: 다이제스트는 바뀐 것만 알리고 무엇을 고칠지 말하지 않는다. - 백엔드가 계약 패키지를 발행: 백엔드 빌드에 JS 발행이 생긴다. 지금 규모에는 pin과 표가 작다. 위험·한계 - 답 표 JSON은 사람이 백엔드 문서에서 옮긴다. 옮기는 실수는 drift 스크립트와 리뷰가 잡는다. 백엔드 쪽이 같은 JSON을 자기 레지스트리와 대조하는 일은 백엔드 저장소 몫이다. - 백엔드 HEAD는 이미 pin 뒤로 갔다(지금 c508b1ba). http-contract.md §2의 500 IDEMPOTENCY_RECOVERY_REQUIRED 행이 "같은 키 재전송은 안전하다"로 바뀌었다. 프론트 판정(MAYBE_APPLIED, 자동 재전송 없음, 사용자 재전송은 같은 키)은 그 문장과도 맞는다. pin은 지시대로 bbe944bd에 두었다. 검증 - 새 테스트 10건 통과. 변이 4종 검출: 답 표에 503 새 code 행 추가, 프론트 표에서 COMPLETION_UNKNOWN 제거, 프론트 표에 근거 없는 400 BAD_PARAMETER 추가, 답 표의 RECOVERY_REQUIRED status 변경. - check:backend-contract-drift: worktree에서 skipped(exit 0), 실제 백엔드 checkout으로 exit 1과 바뀐 RECOVERY_REQUIRED 행 출력. - test:unit 178파일 2,645건, check:ci, check:types, eslint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06 Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6 |
||
|
|
a144b575e5 |
fix(contracts): FE-REG-ENV 런타임 행의 필수 여부·기본값을 스키마와 맞춘다
문제
FE-REG-ENV 런타임 행 13개 중 5개의 required·defaultValue가 실제 V2
runtime config 스키마(runtimeConfigV2ArtifactSchema)와 다르다.
- TELEMETRY_ENABLED: 행 기본값 false / 스키마 필수, 기본값 없음
- AUTH_MODE: 행 기본값 "external" / 스키마 기본값 없음
- RELEASE_MANIFEST_URL: 행 required true / 스키마 선택(기본값 있음)
- CAPABILITY_OVERRIDES: 행 기본값 null / 스키마 기본값 네 항목 DEFAULT
- FEATURE_OVERRIDES: 행 기본값 null / 스키마 기본값 {}
d0414c8의 테스트는 스키마 키마다 행이 있는지만 본다. 스키마에 없는 런타임
행도, 값이 다른 행도 통과한다. 이 레지스트리는 기준선 호환 검사 대상이라
틀린 값이 계약으로 굳는다. AUTH_MODE를 빼도 external이 된다고 읽으면
부팅이 스키마 오류로 멈춘다.
고른 방법
- env-registry-coverage에 두 방향을 더한다. 스키마가 읽지 않는 런타임 행은
실패한다. 각 행의 required·defaultValue는 스키마 필드에 undefined를 넣은
결과(실패 = 필수·기본값 없음, 성공 = 선택·그 값)와 같아야 한다. 차이는
키·행 값·스키마 값을 한 줄로 보인다. 제품 키(PRODUCT_*)도 같은 검사를
받는다.
- 5개 행을 스키마에 맞춘다. 두 override 기본값은 객체라 governance의
defaultValue 타입에 object를 더했다.
- ENV_REGISTRY 주석에 두 칸의 뜻(null = 스키마가 기본값을 주지 않음)을
적었다.
버린 대안
- 행의 required·defaultValue를 스키마에서 계산해 채우기: 손으로 맞출 일이
사라지지만 env.ts가 zod 스키마를 import해야 한다. env.ts는 부팅 경로
(getBuildConfig)에 있어 초기 청크에 zod 스키마가 끌려 들어간다.
위험·한계
- RELEASE_MANIFEST_URL required true→false는 breaking 칸 변경이고
governance fieldTypes도 바뀌어 기준선을 다시 승인했다.
- 스키마 superRefine의 조건부 필수(TELEMETRY_ENABLED면 TELEMETRY_ENDPOINT)는
행에 표현하지 않는다.
검증
- RED: 새 대조 테스트가 위 5개 행을 정확히 보고하며 실패했다.
- GREEN: env-registry-coverage 3건 통과. 변이: 스키마 REQUEST_TIMEOUT_MS
기본값만 20,000으로 바꾸면 실패, 스키마 필드 없는 제품 행을 더하면 실패.
- check:registries(재승인 뒤 compatibility=none), run-vitest related
(env.ts, governance) 18파일 154건, registry-governance·product-composition
23건, check:types, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-05
|
||
|
|
08ed0a088d |
fix(contracts)!: FE-REG-API 행에 status 목록·상한·재시도 예산·검증 생략을 담는다
문제 V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서 12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감, retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에 없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도 check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이 breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고 (X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도 behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에 204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다. 고른 방법 - projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다: acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기 칸 이름: input·output·problem), requestByteLimit, responseByteLimit, totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery. - commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지 (classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite 목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로 읽고, 없으면 행에도 없다. - governance: problemSchema와 unvalidated를 breakingFields에 넣는다. status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이 빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에 넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지 증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다. - 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지, descriptor 함수는 행에 없다는 것을 적었다. 버린 대안 - descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지 기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다. - V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다. - 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감 조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다. 위험·한계 - governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어 기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다. - FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사 대상이 아니다. breaking 칸으로만 잠근다. - classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다. 검증 - 기준선 재승인 뒤 실험 재실행(check:registries): X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락), X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건), X5 GET 출력 검증기 생략 실패(unvalidated:field-changed), X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다. - tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite 있음·없음, governance JSON으로 분류한 8가지 변경. - run-vitest related(api-operations.ts, governance) 21파일 156건, registry 테스트 4파일 63건, check:registries:compatibility-fixtures, check:types, eslint, verify:documentation 통과. BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의 check:registries가 FE-REG-API:$contract:* contract-field-changed로 실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을 주고 update:registry-baseline을 한 번 돌린다. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01 Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절 |
||
|
|
12f3bb7862 |
refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제 기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행 (defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고, contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게 http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가 없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을 위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석 (resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만 남기고, 레지스트리 기준선 재승인을 승인했다. 고른 방법 - src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다. 조립된 contribution의 descriptor마다 operationId, featureId, method, path, authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope, request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는 같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다. requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다. - FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다. installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고 FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다. - realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과 retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics· replayPolicy 대신). - rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립 때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다. - 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로 바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를 지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다. - create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를 만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다. - 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다 (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음). - 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다. 버린 대안 - V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다. - 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary· unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다. 위험·한계 - BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes 의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다. 옮기는 법은 CHANGELOG에 적는다. - V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF 모드)가 사라졌다. V3 descriptor에는 그 칸이 없다. - BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2 필드를 갖지만 자체 계약이라 바꾸지 않았다. 검증 - check:types, lint, check:architecture, check:registries(11 registries PASS, compatibility=none), check:ci, check:diagnostics, check:adapter-inventory, verify:documentation 통과. - test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함), test:integration 114, test:component 245, test:contract 23, test:runtime-schema 56, tests/features 99 통과. - tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두 번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다. - check:bundle 통과. 초기 JS 201,598 → 200,911 B. - test:feature-scaffold 16개, test:sample-removal 23개 검사 통과. BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다. defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS, createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile, loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은 operation을 contract contribution에만 적고, schemas 행을 feature-runtime에 넘긴다. |
||
|
|
048f490ada |
refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
|
||
|
|
70d0ac1ca2 |
chore(registry): 레지스트리 기준선을 재승인하고 옮긴 source 경로를 바로잡는다
문제
registry-baseline.json의 FE-REG-API·FE-REG-SCHEMA source가 15-01(
|
||
|
|
e8d7fb427f |
fix(registry): 기능 라우트를 추가해도 governance를 고치지 않게 한다 (0929/07-03)
문제
FE-REG-ROUTE governance가 paramsSchema·searchSchema·loadingSurface를 참조
기능 값까지 적은 닫힌 목록으로 둔다. 기능이 자기 search 스키마나 자기
로딩 화면 이름을 가진 라우트를 더하면 check:registries가 "has unknown
value"로 실패하고, 템플릿 소유 파일인 registry-governance.json을 고쳐야
한다. 목록은 contract 일부라 고치면 breaking 증거나 재승인도 필요하다.
두 다운스트림 모두 여기서 충돌했다. 스키마 id는 이미 references가
FE-REG-SCHEMA와 대조하므로 목록은 같은 사실의 세 번째 사본이고,
loadingSurface는 data-surface 속성 말고 읽는 코드가 없다. 문서는
"governance file do not change"라고 적지만 그 약속을 고정하는 테스트는
라우트 없는 기능만 넣었다.
고른 방법 (2026-11-03 결정, 리뷰 (B))
- paramsSchema·searchSchema를 FE-REG-ROUTE allowedValues에서 뺐다.
references 검사는 그대로라 등록되지 않은 스키마 id는 계속 실패한다.
- loadingSurface는 목록 대신 이름 형식만 본다. governance에 선언형 키
fieldPatterns(필드 → 고정된 정규식)를 더하고 check-registries가 문자열
값을 대조한다. FE-REG-ROUTE는 kebab-case
^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$를 쓴다. fieldPatterns는 선언한
레지스트리에서만 contract 스냅샷에 들어가므로 다른 레지스트리의
contract는 바뀌지 않고, 정규식을 바꾸면 contract 변경(breaking)으로
잡힌다.
- second-api-feature-registries 테스트의 두 번째 기능에 자기 search 스키마
(SecondItemListQuery)와 전용 loading surface(second-item-list)를 가진
라우트를 넣었다. 저장소 사본에 기능 디렉터리와 context만 더하고
check-registries가 PASS인지 본다. 지시의 two-feature-install-typecheck는
app 타입 검사만 돌려 governance를 보지 않으므로, check-registries를 돌리는
이 테스트를 확장했다.
- 라우트 fixture(check:routes:fixture)의 governance도 같은 모양으로 바꾸고,
형식에 맞지 않는 이름("Unknown loading")이 거절되는 단위 테스트를 더했다.
- starter-experience.md가 이 테스트를 가리키고, 라우트의 스키마·로딩 화면이
governance 수정 없이 들어가는 이유를 적는다.
- 두 contract 변경(allowedValues 축소, fieldPatterns 추가)은 breaking이다.
이 커밋에서는 증거 2건으로 게이트를 통과시키고, 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
이유: 기능 하나를 추가할 때 템플릿 파일을 고치게 만드는 지점이다. 두
다운스트림 모두에서 충돌했다.
버린 대안
- 문서만 "allowlist를 고치고 증거를 쓴다"로 정정: 기능마다 비용이
반복된다.
- 기능 계약이 자기 allowlist 값을 기여하는 확장 메커니즘: 등록 규약이
하나 더 생긴다.
위험·한계
- loadingSurface 오타는 이제 형식만 맞으면 통과한다. 이 값은 로딩
요소의 data-surface 속성일 뿐이라 동작이 바뀌지 않는다. loadingSurface가
로딩 컴포넌트 선택 같은 실행 의미를 갖게 되면 닫힌 목록을 다시 둔다.
- errorSurface·access는 라우터가 의미로 읽으므로 닫힌 목록을 유지한다.
기능이 새 errorSurface를 쓰려면 지금처럼 governance를 고친다.
- 다운스트림은 다음 동기화에서 자기가 이 목록에 더한 값을 지운다.
CHANGELOG [계약] 행이 필요하다.
검증
- RED(수정 전): 확장한 second-api-feature-registries 테스트가
"FE-REG-ROUTE.SECOND_ITEM_LIST.searchSchema has unknown value
SecondItemListQuery", "...loadingSurface has unknown value
second-item-list"로 실패. 새 형식 테스트는 수정 전 checker로
"expected [] to deeply equal [ Array(1) ]"로 실패.
- GREEN: 두 테스트 통과. 증거 없이 check-registries는 "breaking change
missing evidence" 2건(allowedValues contract-field-changed,
fieldPatterns contract-field-added)으로 실패, 증거를 넣은 뒤
"11 registries PASS".
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts·two-feature-install-typecheck 57/57.
compatibility fixtures 11 PASS. check:routes:fixture는 기대대로
"duplicates routeId=DUPLICATE"로 실패. verify-documentation-readiness
PASS_SCOPED. tsc node·test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
4ada84e1ec |
fix(registry): 맞는 변경이 없는 breaking 증거 행을 실패로 막는다 (0929/07-01)
문제
check:registries는 증거 행이 지금 diff의 어느 breaking 변경을 설명하는지
보지 않는다. 증거 파일 17건 중 14건이 지금 diff의 어떤 changeId와도 맞지
않았다(예: FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed,
그 필드는 07-04 이후 없다). update:registry-baseline은 기준선을 새로 찍어도
증거 행을 그대로 두므로 오래된 행이 계속 쌓인다. 5e6be9a가 리뷰 개선
(1)(증거를 값에 묶기)만 했고 (2)·(3)이 남았다.
고른 방법 (2026-11-03 결정)
- (2) validateBreakingEvidence가 지금 diff의 breaking 변경과 changeId가
맞지 않는 증거 행마다 "stale breaking evidence <changeId>: ..."로
실패한다. 메시지에 지울 행과 update:registry-baseline이 지운다는 사실을
적는다. breaking이 아닌 변경(behavior-change 등)과 맞는 행도 오래된
행으로 본다. 증거는 breaking 변경에만 쓰기 때문이다.
- (3) update:registry-baseline이 승인 파일을 쓴 뒤 증거 행을 모두 지우고,
지운 changeId를 출력한다. 새 기준선은 지금 스냅샷이라 증거가 설명하던
변경을 모두 흡수한다. 남은 행은 어떤 변경과도 맞지 않아 (2)에서
실패한다. 이력 파일로 옮기지 않는다. git 이력이 이력이다.
증거 파일은 쓰기 전에 읽어서, 파일이 없으면 아무것도 바꾸지 않고 멈춘다.
- 이번 검사에 걸리는 오래된 14건을 지웠다. 지금 diff와 맞는 3건
(REFERENCE_RESOURCE_DETAIL.path, CACHE_INVALIDATION_PULSE backend·
valueCodec)은 남겼다.
- docs/operations/ci-quality-gates.md 증거 안내에 두 동작을 적었다.
이유: 목록을 출력만 하면 아무도 보지 않는다. 정리가 자동이라 실패해도
고치는 비용이 작다.
버린 대안
- 오래된 행을 목록으로 출력만 하기: 위 이유.
- 지운 행을 이력 파일로 옮기기: 파일이 하나 늘고, git 이력과 같은 사실의
사본이 된다.
위험·한계
- 다운스트림이 이 검사를 동기화하면 자기 증거 파일의 오래된 행 때문에
게이트가 실패한다. 실패 메시지가 행을 나열하므로 지우거나
update:registry-baseline을 한 번 돌리면 된다. CHANGELOG [계약] 행이
필요하다.
- 같은 changeId가 증거 파일에 두 번 있으면 지금처럼 뒤의 행만 쓰고,
앞의 행은 오래된 행으로 걸리지 않는다. 이번 범위 밖이다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 "fails on evidence
rows that explain no breaking change of the current diff"가
"expected [] to deeply equal [ …(2) ]"로 실패. registry-governance.test.ts
새 사례 "deletes the evidence rows the new baseline explains"가
"expected { schemaVersion: 1, changes: [ …(1) ] } to deeply equal
{ schemaVersion: 1, changes: [] }"로 실패.
- GREEN: 두 파일 25/25 통과. 오래된 행을 지우기 전 check-registries가
"stale breaking evidence ..." 14줄로 실패(rc=1), 지운 뒤 "11 registries
PASS"(rc=0).
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts 55/55 통과. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc node·test rc=0, 바꾼
파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요). 제거 드릴은
update:registry-baseline 뒤 check:registries를 돌리므로 (3)이 있어야
통과한다.
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
65ea208b99 |
fix(registry): pulse 키 breaking 증거에 after 값을 적는다 (05-01, 0929/07-01)
두 수정이 따로 고쳐져 합쳐지면서 레지스트리 검사가 실패했다. 05-01은 CACHE_INVALIDATION_PULSE 행의 backend·valueCodec을 바꾸고 breaking 증거 2건을 넣었다. 0929/07-01은 증거가 설명하는 값(after)을 필수로 바꿨다. 그래서 05-01의 증거 2건에 after가 없어 check-registries와 second-api-feature-registries 테스트가 실패했다. 두 증거에 diff의 새 값(`external`, `none`)을 after로 적었다. 증거 내용과 05-01의 변경은 그대로다. 위험: 증거 파일만 바뀐다. 검증: check-registries "11 registries PASS", second-api-feature-registries 테스트 통과. |
||
|
|
5e6be9a92f |
fix(registry): breaking 증거를 그 증거가 설명하는 값에 묶는다 (0929/07-01)
문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.
고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
needs after", 다르면 "evidence explains after=..., the change is
after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
registry-governance tamper 사례)에 after를 넣었다.
버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
하지 않았다.
위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
적어야 한다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
("rejects evidence written for another value", "requires the explained
value": expected [] to deeply equal [...]). X3 변이로 check-registries
"11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
after=\"/examples/reference-resources/items/:resourceId\", the change is
after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
"11 registries PASS". registry-compatibility·registry-governance·
release-artifacts·second-api-feature-registries 53/53 통과.
compatibility fixtures 11 PASS. verify-documentation-readiness
PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
|
||
|
|
e98a980dff |
fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.
고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).
버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.
위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.
검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
"expected { ok: true, value: undefined } to match object { ok: false }"
로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
contract-registry-lookup, browser-security, runtime-adapters,
release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
eslint 통과, check-registries PASS, verify-documentation-readiness
PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
|
||
|
|
298201f3ee |
perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제 초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의 feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper 포함), HTTP 계약 contribution, application input 팩토리, route codec까지 모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서 예산을 넘었다. 고른 방법 - 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime 계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼 contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API 계약, adapter contribution, contract contribution)는 feature-runtime.ts로 옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의 route handle에 실어 route와 함께 적재한다. - 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route 모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에 화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route 모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은 적재하지 않는다. - 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다 (installed-contract-contributions.ts). 선언하지 않은 contract package를 적재하면 거절한다. - 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는 installed-feature-runtime-registries.ts의 async 함수로, Node·테스트· registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로 둔다. src에서 후자를 import하면 새 아키텍처 규칙 boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은 route 로더에서 async 함수를 불러 결과를 prop으로 받는다. - vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy 청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면 기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는 플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져 템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을, feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다. render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03: 애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다). 버린 대안 - 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는 lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라 버렸다. - 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를 공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다. - 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당 -60 B 수준이라 그룹 없이 목표에 못 미쳤다. - 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만 i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다. - boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두 초기로 세어 218,303 B가 됐다. 위험·한계 - FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로 실행부를 옮겨야 한다(BREAKING CHANGE). - 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라 그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트· 테스트)로 옮겨 간다. - 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼 구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가 재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다. - 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가 비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿 총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다. - config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직 installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인 때 고친다. check-registries는 통과한다. - 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의 98.8%다. 수치 (vite build, classifyViteJavascript + gzipSync 기본 수준) - 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B - 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741) - 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648) - 참조 복사본 +5: 205,629 B - lazy JS: 23,516 B -> 28,204 B 검증 - RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or equal to 1024 - GREEN: 같은 테스트 통과(+741 B) - node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과 - node scripts/run-vitest.ts run tests/component tests/features tests/integration tests/contract tests/runtime-schema tests/architecture tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출): 109파일 787 통과 - npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과 - npx eslint 바뀐 파일 통과 - check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이 boot.tsx의 import를 거절하는 것 확인 - check-adapter-inventory, check-registries, verify-documentation-readiness, check-ci-contract: PASS - e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트): 55 통과 - storybook build 성공 - 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026), pnpm 경로의 check:bundle, test:system BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages, loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약 (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로 만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle codecs로 옮긴다. contracts에는 contractPackages를 추가한다. Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01, 16-structure-patterns.md 9절 |
||
|
|
2b2cabb7f2 |
Merge lane/H: presentation (07-01, 08-02, 08-04, 08-05, 08-07~08-13, 11-02, F-10)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> # Conflicts: # config/contracts/registry-change-evidence.json |
||
|
|
d7b81c633d |
fix(reference): move the detail route under items/ (08-13)
The detail path /examples/reference-resources/:resourceId lost to the static new and status routes, so an item with one of those ids opened the wrong screen. The breaking route change carries registry evidence. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
063375ed04 |
fix(contracts): fail public builds without VITE_BUILD_ID and record the local default (F-6, 13-15)
ENV_REGISTRY called VITE_BUILD_ID required with no default while every reader fell back to local-build. Staging and production builds now fail without it; local builds keep the placeholder, and the registry records that default. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
aff5f43652 |
fix(contracts): drop unread error registry fields and pin the createFailure effect rule (07-04)
Nothing read severity, telemetryEvent or redaction, yet FE-REG-ERROR guarded them as policy. They are removed and the registry baseline is re-approved. A new test fails if createFailure stops clearing retryable for MAYBE_APPLIED (M1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
ad0e83c867 |
fix(features): make feature add and removal work from the feature directory (09-07, 14-03)
A feature directory without feature-module.ts vanished silently, registry consumers listed only the sample's directories, and the removal gate only knew the sample. The generator now fails unless a NOT_INSTALLED marker says so (D-10), consumer directories are globs over every feature, and the removal script takes --feature=<id>. starter-experience.md documents the current ownership declarations and the files a new feature touches. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
6f6c48ebb7 | refactor: 도메인이 100개 1000개씩 늘어나도 유지보수 쉬운 구조로 변경 |